Docs/Intégration Widget

Intégration Widget

Le moyen le plus rapide d'accepter des paiements. Aucun backend requis.

Démarrage rapide

Ajoutez deux lignes à votre HTML. Le widget gère automatiquement la connexion wallet, la sélection de chaîne, la signature de transaction et le transfert inter-chaînes.

Minimal Setup
<script async src="https://checkout.fivo.finance/v1/fivo.js"></script>

<fivo-button
  merchant-id="YOUR_MERCHANT_ID"
  amount="29.99"
  currency="USDC">
</fivo-button>
i

Merchant ID

Votre Merchant ID est affiché sur la page de votre tableau de bord.Intégration Format: fivo_live_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Modes de paiement

Montant fixe

Pour les produits, factures, abonnements. Définissez l'attribut et le client ne peut payer que ce prix exact.amount

Montant variable

Pour les dons, pourboires, prix libre. Omettez l'attribut et le client saisit le montant qu'il souhaite payer.amount

Montant fixe

Définissez le prix et le système vérifie le montant exact sur la blockchain. Les montants doivent être compris entre 0,01 et 1 000 000.

Product Checkout
<script async src="https://checkout.fivo.finance/v1/fivo.js"></script>

<!-- Product: $49.99 USDC -->
<fivo-button
  merchant-id="YOUR_MERCHANT_ID"
  amount="49.99"
  currency="USDC">
</fivo-button>

Cas d'utilisation

  • Paiement de produits e-commerce
  • Paiements d'abonnements SaaS
  • Factures de services
  • Billets d'événements

Montant variable

Omettez l'attribut . Le widget affiche un champ de saisie où le client indique le montant à payer.amount

Donation / Tip
<script async src="https://checkout.fivo.finance/v1/fivo.js"></script>

<!-- Donation: customer chooses amount -->
<fivo-button
  merchant-id="YOUR_MERCHANT_ID"
  currency="USDC">
</fivo-button>
!

Limites de montant

Les montants variables sont validés entre 0,01 et 1 000 000. Les montants en dehors de cette plage afficheront un message d'erreur.

Cas d'utilisation

  • Dons et collectes de fonds
  • Pourboires pour créateurs de contenu
  • Prix libre (pay-what-you-want)
  • Contributions de financement participatif

Attributs

L'élément accepte les attributs suivants :<fivo-button>

fivo-button Attributes

merchant-idstringRequired

Votre Merchant ID (format : fivo_live_UUID)

amountstringOptional

Montant de paiement fixe (0,01 - 1 000 000). Omettez pour le mode variable.

currencystringOptional

"USDC" ou "EURC". Par défaut "USDC".

wallet-idstringOptional

UUID de wallet spécifique pour les commerçants multi-wallet. Omettez pour utiliser votre wallet par défaut.

data-amount-fromstringOptional

Sélecteur CSS de l'élément contenant le total du panier. Le montant est lu au moment du clic.

data-referencestringOptional

Votre référence interne (numéro de commande, numéro de facture, etc.). Max 255 caractères.

data-descriptionstringOptional

Description du paiement affichée dans le tableau de bord. Max 500 caractères.

data-metadatastringOptional

Chaîne JSON avec des paires clé-valeur personnalisées. Max 10 Ko.

i

Attributs dynamiques

Les attributs sont réactifs. Vous pouvez les mettre à jour avec JavaScript (ex. ) et le libellé du bouton se met à jour automatiquement.el.setAttribute('amount', '59.99')

Événements

Le bouton émet des événements DOM personnalisés que vous pouvez écouter. Toutes les données de l'événement sont disponibles dans .e.detail

fivo:payment-success

Data: txHash, amount, token, chainId

Paiement confirmé sur la blockchain

fivo:payment-error

Data: error

Paiement échoué ou rejeté

fivo:payment-tracking

Data: paymentId, status, step

Mise à jour de la progression du transfert inter-chaînes

Listening for Events
<fivo-button
  id="pay-btn"
  merchant-id="YOUR_MERCHANT_ID"
  amount="25.00"
  currency="USDC">
</fivo-button>

<script>
  const btn = document.getElementById('pay-btn');

  btn.addEventListener('fivo:payment-success', (e) => {
    console.log('TX hash:', e.detail.txHash);
    console.log('Amount:', e.detail.amount, e.detail.token);
    console.log('Chain ID:', e.detail.chainId);
    window.location.href = '/thank-you?tx=' + e.detail.txHash;
  });

  btn.addEventListener('fivo:payment-error', (e) => {
    console.error('Payment failed:', e.detail.error);
  });

  btn.addEventListener('fivo:payment-tracking', (e) => {
    // Only fires for cross-chain (CCTP) payments
    console.log('Step:', e.detail.step, 'Status:', e.detail.status);
  });
</script>

Panier dynamique

Collez ce bouton dans votre panier. Il lit automatiquement le total de votre page lorsque le client clique. S'il ne détecte pas le total, changez pour correspondre à l'ID de l'élément total de votre panier.#cartTotal

Cart Integration (Recommended)
<script async src="https://checkout.fivo.finance/v1/fivo.js"></script>

<!-- Replace #cartTotal with YOUR cart total element's ID -->
<fivo-button
  merchant-id="YOUR_MERCHANT_ID"
  data-amount-from="#cartTotal"
  currency="USDC">
</fivo-button>
i

Le total n'est pas détecté ?

Faites un clic droit sur le total de votre panier, cliquez sur Inspecter. Le code surligné affichera . Utilisez dans . Les signes dollar et les virgules sont supprimés automatiquement.id="something"#somethingdata-amount-from

Avancé : contrôle manuel

Si vous avez besoin d'un contrôle programmatique complet (ex. le total n'est pas visible sur la page), vous pouvez mettre à jour l'attribut amount directement avec JavaScript :

Manual setAttribute
<fivo-button
  id="checkout-btn"
  merchant-id="YOUR_MERCHANT_ID"
  currency="USDC">
</fivo-button>

<script>
  // Update when cart changes
  function updateCheckout(total) {
    document.getElementById('checkout-btn')
      .setAttribute('amount', total.toFixed(2));
  }

  // Redirect after payment
  document.getElementById('checkout-btn')
    .addEventListener('fivo:payment-success', (e) => {
      window.location.href = '/thank-you?tx=' + e.detail.txHash;
    });
</script>
!

E-commerce avec gestion de commandes ?

Pour les boutiques nécessitant un suivi de commandes côté serveur, consultez les ci-dessous.Sessions de paiement

Produits multiples

Chargez le script une fois, puis ajoutez autant de boutons que nécessaire. Chacun fonctionne indépendamment.

Multiple Buttons
<script async src="https://checkout.fivo.finance/v1/fivo.js"></script>

<!-- Product A -->
<fivo-button merchant-id="YOUR_MERCHANT_ID" amount="19.99" currency="USDC"></fivo-button>

<!-- Product B -->
<fivo-button merchant-id="YOUR_MERCHANT_ID" amount="49.99" currency="USDC"></fivo-button>

<!-- Donation (variable) -->
<fivo-button merchant-id="YOUR_MERCHANT_ID" currency="EURC"></fivo-button>

Lien de paiement direct

Vous pouvez également créer un lien direct vers la page de paiement sans intégrer le widget. Utile pour les factures par e-mail, les liens sur les réseaux sociaux ou les codes QR.

Checkout URL Format
https://checkout.fivo.finance?merchant=YOUR_MERCHANT_ID&amount=49.99&currency=USDC

Paramètres d'URL

merchantstringRequired

Votre Merchant ID

amountstringOptional

Montant fixe. Omettez pour le mode variable.

currencystringOptional

"USDC" ou "EURC". Par défaut "USDC".

walletIdstringOptional

UUID de wallet spécifique pour les commerçants multi-wallet.

referencestringOptional

Votre référence interne (numéro de commande, etc.).

descriptionstringOptional

Description du paiement.

metadatastringOptional

Chaîne JSON encodée en URL avec des données personnalisées.

Example: Invoice Link
<a href="https://checkout.fivo.finance?merchant=YOUR_MERCHANT_ID&amount=150.00&currency=USDC">
  Pay Invoice #1234, $150.00 USDC
</a>

Sessions de paiement (mode redirection)

Pour les intégrations côté serveur, vous pouvez créer une session de paiement via l'API et rediriger votre client vers une page de paiement hébergée par Fivo. Après le paiement, le client est redirigé vers votre site. Cela fonctionne de manière similaire à Stripe Checkout.

i

Intégration côté serveur

Les Sessions de paiement nécessitent une API key. Créez-en une dans votre . N'exposez jamais votre API key dans le code côté client.tableau de bord

Comment ça fonctionne

1

Votre serveur crée une session

Appelez POST /checkout/sessions avec le montant, la devise et une URL de retour.

2

Redirigez le client

Utilisez l'URL renvoyée pour rediriger votre client vers la page de paiement Fivo.

3

Le client paie

Le client connecte son wallet et effectue le paiement sur la page hébergée.

4

Le client revient sur votre site

Après le paiement, le client est redirigé vers votre return_url avec l'identifiant de session.

5

Vérifiez le paiement sur votre serveur

Appelez GET /checkout/sessions/:id pour confirmer le statut du paiement avant de traiter la commande.

1. Créer une session (côté serveur)

Create Checkout Session
const response = await fetch(`https://api.fivo.finance/checkout/sessions`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.FIVO_API_KEY,
  },
  body: JSON.stringify({
    amount: '49.99',
    currency: 'USDC',
    return_url: 'https://yoursite.com/success',
    cancel_url: 'https://yoursite.com/cancel',
    metadata: { order_id: 'order_123' },
    expires_in: 1800,   // 30 minutes (default)
  }),
});

const { data } = await response.json();
// data.id  → "cs_live_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
// data.url → "https://checkout.fivo.finance?session=cs_live_..."
// data.expires_at → "2026-02-18T11:00:00.000Z"
// After payment, the customer is redirected to:
// https://yoursite.com/success?session_id=cs_live_...

2. Rediriger le client

Redirect
// Express.js example
app.post('/create-checkout', async (req, res) => {
  const session = await createCheckoutSession(req.body);
  res.redirect(303, session.url);
});

3. Vérifier le paiement au retour

Verify Session
// When the customer lands on your return_url
app.get('/success', async (req, res) => {
  const sessionId = req.query.session_id;

  const response = await fetch(
    `https://api.fivo.finance/checkout/sessions/${sessionId}`,
    { headers: { 'X-API-Key': process.env.FIVO_API_KEY } }
  );
  const { data } = await response.json();

  if (data.status === 'complete' && data.payment) {
    // Payment confirmed: fulfill the order
    console.log('Payment ID:', data.payment.id);
    console.log('TX Hash:', data.payment.tx_hash);
    console.log('Amount:', data.payment.amount, data.currency);
  } else {
    // Payment not yet confirmed: show a waiting state
    console.log('Session status:', data.status);
  }
});

POST /checkout/sessions : Paramètres

amountstring | numberOptional

Montant du paiement (0,01 - 1 000 000). Omettez pour un montant variable.

currencystringOptional

"USDC" ou "EURC". Par défaut "USDC".

return_urlstringRequired

URL de redirection du client après le paiement. Doit être HTTPS en production.

cancel_urlstringOptional

URL de redirection si le client annule. Doit être HTTPS en production.

metadataobjectOptional

Jusqu'à 5 paires clé-valeur pour votre référence interne (ex. numéro de commande).

expires_innumberOptional

Durée de vie de la session en secondes (60 - 86400). Par défaut 1800 (30 min).

Devises et chaînes supportées

DeviseCodeChaînes
USD CoinUSDCLes 9 chaînes
Euro CoinEURCEthereum, Avalanche, Base
BlockchainTokens
EthereumUSDC, EURC
PolygonUSDC
AvalancheUSDC, EURC
ArbitrumUSDC
BaseUSDC, EURC
OptimismUSDC
LineaUSDC
UnichainUSDC
SonicUSDC

Les clients peuvent payer depuis n'importe quelle chaîne. Si leur chaîne diffère de celle de votre wallet, les paiements USDC sont automatiquement transférés via Circle CCTP (généralement 1-2 minutes). EURC fonctionne uniquement sur la même chaîne et ne supporte pas les transferts inter-chaînes.

Comment ça fonctionne

1

Le client clique sur le bouton

Une fenêtre de paiement s'ouvre par-dessus votre page. Votre site reste chargé en dessous.

2

Le client connecte son wallet

Compatible MetaMask, Coinbase Wallet, WalletConnect et d'autres wallets populaires.

3

Le client sélectionne la chaîne et paie

Le widget scanne les chaînes supportées pour les soldes USDC (9 chaînes) ou EURC (3 chaînes) et affiche les options disponibles.

4

Vous recevez les fonds

Les paiements sur la même chaîne sont instantanés. Les paiements USDC inter-chaînes arrivent en 1-2 minutes via CCTP. EURC fonctionne uniquement sur la même chaîne.

E-mail client et reçus

Chaque paiement nécessite que le client saisisse son adresse e-mail avant de payer. Le widget gère cela automatiquement. Un champ e-mail obligatoire est affiché avant l'étape de connexion wallet.

Pour les clients

Après le paiement, le client reçoit un reçu par e-mail avec son identifiant de paiement, le montant, le nom du commerçant et le lien de la transaction blockchain.

Pour les commerçants

Vous pouvez voir les e-mails des clients sur votre page Transactions et rechercher des remboursements par e-mail au lieu de l'identifiant de paiement.

Suivi de commande

Utilisez les attributs optionnels pour relier les paiements à vos systèmes internes. Ils sont transmis aux webhooks et visibles dans votre tableau de bord.

E-commerce Integration
<fivo-button
  merchant-id="YOUR_MERCHANT_ID"
  amount="49.99"
  currency="USDC"
  data-reference="ORD-2024-001"
  data-description="Pro Plan - Monthly"
  data-metadata='{"product_id": "plan_pro", "customer_name": "John"}'>
</fivo-button>

Order Tracking Attributes

data-referencestringOptional

Votre identifiant de commande/facture. Visible dans le tableau de bord et les webhooks. Max 255 caractères.

data-descriptionstringOptional

Description du paiement. Visible dans le tableau de bord. Max 500 caractères.

data-metadatastringOptional

Chaîne JSON avec des données personnalisées. Incluse dans les webhooks. Max 10 Ko.

i

Ces attributs sont optionnels

L'e-mail du client est toujours requis (géré automatiquement par le widget). La référence, la description et les métadonnées sont optionnelles. Utilisez-les lorsque vous devez relier les paiements à votre système de commandes.

Bon à savoir

Léger

Script de ~7 Ko, chargé en asynchrone. Ne ralentira pas votre site.

Styles isolés

Utilise le Shadow DOM. Votre CSS ne le perturbera pas.

Protection anti-fraude

Les montants fixes sont vérifiés sur la blockchain.

9 blockchains

USDC sur les 9 chaînes avec transfert automatique via CCTP. EURC sur 3 chaînes (même chaîne uniquement).

Besoin de plus de contrôle ?

Utilisez les pour les flux de redirection côté serveur, ou consultez le guide d'intégration API pour les webhooks et les requêtes de paiement programmatiques.Sessions de paiement