FivoDocs
Docs/Intégration API

Intégration API

Créez des flux de paiement personnalisés et des intégrations backend.

Aperçu

Bien que le widget soit le moyen le plus simple d'accepter des paiements, l'API Fivo vous donne un contrôle total pour les intégrations personnalisées. Utilisez l'API pour :

  • Créer des expériences de paiement personnalisées
  • Interroger l'historique des paiements de manière programmatique
  • Intégrer avec vos systèmes backend existants
  • Créer des paiements depuis du code côté serveur

Sessions de paiement

Les Sessions de paiement sont le moyen recommandé pour accepter des paiements depuis une intégration côté serveur. Votre serveur crée une session, redirige le client vers une page de paiement hébergée par Fivo, et vérifie le paiement lorsque le client revient.

Quand utiliser quoi

Widget intégré

Produits fixes, dons, sites statiques

Backend: Non

Widget + data-amount-from

Paniers d'achat, totaux dynamiques

Backend: Non

Lien direct

E-mails, réseaux sociaux, codes QR

Backend: Non

Sessions de paiement

E-commerce, SaaS, traitement de commandes

Backend: Oui (API key)

Exemple complet (Node.js / Express)

server.js
const express = require('express');
const app = express();

const FIVO_API = 'https://api.fivo.finance';
const FIVO_API_KEY = process.env.FIVO_API_KEY;

// 1. Customer clicks "Pay": create a session and redirect
app.post('/checkout', async (req, res) => {
  const response = await fetch(FIVO_API + '/checkout/sessions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': FIVO_API_KEY,
    },
    body: JSON.stringify({
      amount: req.body.amount,
      currency: 'USDC',
      // Fivo appends ?session_id=cs_live_... automatically
      return_url: 'https://yoursite.com/success',
      cancel_url: 'https://yoursite.com/cancel',
      metadata: { order_id: req.body.orderId },
    }),
  });

  const { data } = await response.json();
  res.redirect(303, data.url);
});

// 2. Customer returns after payment: verify and fulfill
app.get('/success', async (req, res) => {
  const response = await fetch(
    FIVO_API + '/checkout/sessions/' + req.query.session_id,
    { headers: { 'X-API-Key': FIVO_API_KEY } }
  );
  const { data } = await response.json();

  if (data.status === 'complete' && data.payment) {
    // Fulfill the order
    res.send('Payment confirmed! TX: ' + data.payment.tx_hash);
  } else {
    res.send('Payment pending. Status: ' + data.status);
  }
});

app.listen(3000);

Exemple cURL

Create a Checkout Session
curl -X POST https://api.fivo.finance/checkout/sessions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: fivo_live_abc123..." \
  -d '{
    "amount": "49.99",
    "currency": "USDC",
    "return_url": "https://yoursite.com/success",
    "metadata": { "order_id": "order_123" }
  }'
i

Référence complète

Consultez la pour tous les paramètres, schémas de réponse et valeurs de statut de session.Référence API

URL de base

https://api.fivo.finance
i

API de production

Ceci est le point d'accès API de production. Toutes les requêtes sont traitées sur le mainnet. Nous informerons tous les commerçants avant tout changement majeur.

Authentification

L'API Fivo utilise deux méthodes d'authentification :

Tokens JWT

Pour le tableau de bord et les sessions utilisateur. Obtenus après connexion. Expirent après 15 minutes.

Authorization: Bearer <token>

API Keys

Pour les intégrations serveur à serveur. Créées dans le tableau de bord. N'expirent pas mais peuvent être révoquées.

X-API-Key: <api_key>

Créer une API Key

  1. Connectez-vous à votre Tableau de bord Fivo
  2. Accédez à API Keys
  3. Cliquez sur Créer une nouvelle clé
  4. Donnez un nom descriptif à votre clé (ex. « Serveur de production »)
  5. Copiez la clé immédiatement. Elle ne sera plus affichée !
!

Gardez vos clés secrètes

N'exposez jamais les API keys dans le code côté client. Les API keys ne doivent être utilisées que dans les applications côté serveur où elles peuvent rester secrètes.

Exemple : vérifier le statut d'un paiement

Après qu'un client a payé via le widget, vous pouvez vérifier le statut du paiement :

Check Payment Status
// Using fetch (Node.js/Browser): public endpoint, no auth required
const response = await fetch(
  `https://api.fivo.finance/payments/abc123-payment-id/status`
);

const data = await response.json();
console.log(data);

// Response (minimal data for security):
{
  "success": true,
  "data": {
    "id": "abc123-payment-id",
    "status": "completed",
    "is_cross_chain": false,
    "cctp_attestation_status": null,
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Exemple : lister vos paiements

Interrogez votre historique de paiements avec des filtres. Nécessite une authentification.

List Payments with Filters
// Using fetch with JWT authentication (from dashboard login)
const response = await fetch(
  `https://api.fivo.finance/payments?status=completed&limit=10`,
  {
    headers: {
      'Authorization': 'Bearer YOUR_JWT_TOKEN'
    }
  }
);

const data = await response.json();
console.log(data);

// Response:
{
  "success": true,
  "data": {
    "payments": [
      {
        "id": "payment-1",
        "amount": "49.99",
        "currency": "USDC",
        "status": "completed",
        "txHash": "0x123...",
        "sourceChain": "MATIC",
        "customerEmail": "customer@example.com",
        "reference": "ORD-2024-001",
        "createdAt": "2025-01-15T10:30:00Z"
      },
      // ... more payments
    ],
    "total": 150,
    "limit": 10,
    "offset": 0
  }
}

Exemples cURL

Pour des tests rapides, vous pouvez utiliser cURL depuis la ligne de commande :

Get Payment Status (cURL)
# Get payment status (public endpoint)
curl https://api.fivo.finance/payments/PAYMENT_ID/status

# List your payments (requires JWT from login)
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  "https://api.fivo.finance/payments?status=completed&limit=10"

# Get merchant wallet info (public endpoint)
# MERCHANT_ID format: fivo_live_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
curl https://api.fivo.finance/merchants/MERCHANT_ID/wallet

SDKs et bibliothèques

Les SDKs officiels arrivent bientôt. En attendant, vous pouvez utiliser les bibliothèques HTTP standard de n'importe quel langage pour interagir avec l'API.

SDK Node.js

Bientôt disponible

SDK Python

Bientôt disponible

SDK PHP

Bientôt disponible

Limites de débit

L'API dispose de limites de débit pour garantir un usage équitable et la stabilité du système :

Points d'accès API Key

200 requêtes par minute

Per: API Key

API générale

100 requêtes par minute

Per: IP

Création de paiement (widget)

20 requêtes par minute

Per: IP

Connexion

5 requêtes par 5 minutes

Per: IP + e-mail

Inscription

3 requêtes par 15 minutes

Per: IP

Réinitialisation du mot de passe

3 requêtes par 15 minutes

Per: IP + e-mail

Vérification 2FA

5 requêtes par 5 minutes

Per: IP

Retraits

10 requêtes par 10 minutes

Per: IP

Formulaire de contact

3 requêtes par 15 minutes

Per: IP

Lorsque vous dépassez une limite de débit, vous recevrez une réponse avec un en-tête indiquant quand vous pouvez réessayer.429 Too Many RequestsRetry-After

Référence API complète

Consultez la liste complète des points d'accès, paramètres et formats de réponse.

Voir la référence API