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.
<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>Merchant ID
fivo_live_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxModes 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.
<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
<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
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-idstringRequiredVotre Merchant ID (format : fivo_live_UUID)
amountstringOptionalMontant de paiement fixe (0,01 - 1 000 000). Omettez pour le mode variable.
currencystringOptional"USDC" ou "EURC". Par défaut "USDC".
wallet-idstringOptionalUUID de wallet spécifique pour les commerçants multi-wallet. Omettez pour utiliser votre wallet par défaut.
data-amount-fromstringOptionalSélecteur CSS de l'élément contenant le total du panier. Le montant est lu au moment du clic.
data-referencestringOptionalVotre référence interne (numéro de commande, numéro de facture, etc.). Max 255 caractères.
data-descriptionstringOptionalDescription du paiement affichée dans le tableau de bord. Max 500 caractères.
data-metadatastringOptionalChaîne JSON avec des paires clé-valeur personnalisées. Max 10 Ko.
| Name | Type | Required | Description |
|---|---|---|---|
merchant-id | string | Required | Votre Merchant ID (format : fivo_live_UUID) |
amount | string | Optional | Montant de paiement fixe (0,01 - 1 000 000). Omettez pour le mode variable. |
currency | string | Optional | "USDC" ou "EURC". Par défaut "USDC". |
wallet-id | string | Optional | UUID de wallet spécifique pour les commerçants multi-wallet. Omettez pour utiliser votre wallet par défaut. |
data-amount-from | string | Optional | Sélecteur CSS de l'élément contenant le total du panier. Le montant est lu au moment du clic. |
data-reference | string | Optional | Votre référence interne (numéro de commande, numéro de facture, etc.). Max 255 caractères. |
data-description | string | Optional | Description du paiement affichée dans le tableau de bord. Max 500 caractères. |
data-metadata | string | Optional | Chaîne JSON avec des paires clé-valeur personnalisées. Max 10 Ko. |
Attributs dynamiques
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-successData: txHash, amount, token, chainId
Paiement confirmé sur la blockchain
fivo:payment-errorData: error
Paiement échoué ou rejeté
fivo:payment-trackingData: paymentId, status, step
Mise à jour de la progression du transfert inter-chaînes
| Événement | Données | Quand |
|---|---|---|
fivo:payment-success | txHash, amount, token, chainId | Paiement confirmé sur la blockchain |
fivo:payment-error | error | Paiement échoué ou rejeté |
fivo:payment-tracking | paymentId, status, step | Mise à jour de la progression du transfert inter-chaînes |
<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
<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>Le total n'est pas détecté ?
id="something"#somethingdata-amount-fromAvancé : 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 :
<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 ?
Produits multiples
Chargez le script une fois, puis ajoutez autant de boutons que nécessaire. Chacun fonctionne indépendamment.
<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.
https://checkout.fivo.finance?merchant=YOUR_MERCHANT_ID&amount=49.99¤cy=USDCParamètres d'URL
merchantstringRequiredVotre Merchant ID
amountstringOptionalMontant fixe. Omettez pour le mode variable.
currencystringOptional"USDC" ou "EURC". Par défaut "USDC".
walletIdstringOptionalUUID de wallet spécifique pour les commerçants multi-wallet.
referencestringOptionalVotre référence interne (numéro de commande, etc.).
descriptionstringOptionalDescription du paiement.
metadatastringOptionalChaîne JSON encodée en URL avec des données personnalisées.
| Name | Type | Required | Description |
|---|---|---|---|
merchant | string | Required | Votre Merchant ID |
amount | string | Optional | Montant fixe. Omettez pour le mode variable. |
currency | string | Optional | "USDC" ou "EURC". Par défaut "USDC". |
walletId | string | Optional | UUID de wallet spécifique pour les commerçants multi-wallet. |
reference | string | Optional | Votre référence interne (numéro de commande, etc.). |
description | string | Optional | Description du paiement. |
metadata | string | Optional | Chaîne JSON encodée en URL avec des données personnalisées. |
<a href="https://checkout.fivo.finance?merchant=YOUR_MERCHANT_ID&amount=150.00¤cy=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.
Intégration côté serveur
Comment ça fonctionne
Votre serveur crée une session
Appelez POST /checkout/sessions avec le montant, la devise et une URL de retour.
Redirigez le client
Utilisez l'URL renvoyée pour rediriger votre client vers la page de paiement Fivo.
Le client paie
Le client connecte son wallet et effectue le paiement sur la page hébergée.
Le client revient sur votre site
Après le paiement, le client est redirigé vers votre return_url avec l'identifiant de session.
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)
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
// 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
// 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 | numberOptionalMontant du paiement (0,01 - 1 000 000). Omettez pour un montant variable.
currencystringOptional"USDC" ou "EURC". Par défaut "USDC".
return_urlstringRequiredURL de redirection du client après le paiement. Doit être HTTPS en production.
cancel_urlstringOptionalURL de redirection si le client annule. Doit être HTTPS en production.
metadataobjectOptionalJusqu'à 5 paires clé-valeur pour votre référence interne (ex. numéro de commande).
expires_innumberOptionalDurée de vie de la session en secondes (60 - 86400). Par défaut 1800 (30 min).
| Name | Type | Required | Description |
|---|---|---|---|
amount | string | number | Optional | Montant du paiement (0,01 - 1 000 000). Omettez pour un montant variable. |
currency | string | Optional | "USDC" ou "EURC". Par défaut "USDC". |
return_url | string | Required | URL de redirection du client après le paiement. Doit être HTTPS en production. |
cancel_url | string | Optional | URL de redirection si le client annule. Doit être HTTPS en production. |
metadata | object | Optional | Jusqu'à 5 paires clé-valeur pour votre référence interne (ex. numéro de commande). |
expires_in | number | Optional | Durée de vie de la session en secondes (60 - 86400). Par défaut 1800 (30 min). |
Devises et chaînes supportées
| Devise | Code | Chaînes |
|---|---|---|
| USD Coin | USDC | Les 9 chaînes |
| Euro Coin | EURC | Ethereum, Avalanche, Base |
| Blockchain | Tokens |
|---|---|
| Ethereum | USDC, EURC |
| Polygon | USDC |
| Avalanche | USDC, EURC |
| Arbitrum | USDC |
| Base | USDC, EURC |
| Optimism | USDC |
| Linea | USDC |
| Unichain | USDC |
| Sonic | USDC |
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
Le client clique sur le bouton
Une fenêtre de paiement s'ouvre par-dessus votre page. Votre site reste chargé en dessous.
Le client connecte son wallet
Compatible MetaMask, Coinbase Wallet, WalletConnect et d'autres wallets populaires.
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.
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.
<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-referencestringOptionalVotre identifiant de commande/facture. Visible dans le tableau de bord et les webhooks. Max 255 caractères.
data-descriptionstringOptionalDescription du paiement. Visible dans le tableau de bord. Max 500 caractères.
data-metadatastringOptionalChaîne JSON avec des données personnalisées. Incluse dans les webhooks. Max 10 Ko.
| Name | Type | Required | Description |
|---|---|---|---|
data-reference | string | Optional | Votre identifiant de commande/facture. Visible dans le tableau de bord et les webhooks. Max 255 caractères. |
data-description | string | Optional | Description du paiement. Visible dans le tableau de bord. Max 500 caractères. |
data-metadata | string | Optional | Chaîne JSON avec des données personnalisées. Incluse dans les webhooks. Max 10 Ko. |
Ces attributs sont optionnels
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