Créer un Lien de paiement

Requête de base

curl -X POST https://buy.api.yabetoopay.com/v1/payment-links \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "amount",
    "name": "Paiement facture",
    "amount": 25000,
    "currency": "XOF"
  }'

Paramètres requis

Paramètre	Type	Description
`type`	string	Type de lien : `product`, `amount`, ou `subscription`
`name`	string	Nom du lien (affiché au client)
`currency`	string	Code devise (`XOF`, `EUR`, `USD`)

Paramètres optionnels

Paramètre	Type	Description
`description`	string	Description du lien
`slug`	string	Slug personnalisé pour l’URL
`amount`	number	Montant fixe (pour type `amount`)
`minAmount`	number	Montant minimum (pour montant variable)
`maxAmount`	number	Montant maximum (pour montant variable)
`items`	array	Articles à vendre (pour type `product`)
`expiresAt`	string	Date d’expiration (ISO 8601)
`maxRedemptions`	number	Nombre maximum d’utilisations
`collectBillingAddress`	boolean	Collecter l’adresse de facturation
`collectShippingAddress`	boolean	Collecter l’adresse de livraison
`allowPromotionCodes`	boolean	Autoriser les codes promo
`submitType`	string	Texte du bouton de paiement : `auto` (défaut), `pay`, `book` ou `donate`
`submitMessage`	string	Message affiché sous le bouton, texte brut de 1 à 500 caractères
`successUrl`	string	URL de redirection après paiement
`cancelUrl`	string	URL de redirection si annulation
`brandingId`	string	ID du branding personnalisé
`metadata`	object	Données personnalisées

Types de liens

Montant fixe
Montant variable
Produits
Abonnement

Type `amount` - Montant fixe

Pour collecter un montant spécifique :

{
  "type": "amount",
  "name": "Facture #1234",
  "description": "Paiement de votre facture du mois de janvier",
  "amount": 50000,
  "currency": "XOF"
}

Type `amount` - Montant variable

Permettez au client de choisir le montant (idéal pour les dons) :

{
  "type": "amount",
  "name": "Faire un don",
  "description": "Soutenez notre association",
  "minAmount": 1000,
  "maxAmount": 1000000,
  "currency": "XOF"
}

Si amount est omis mais minAmount et/ou maxAmount sont définis, le client pourra saisir le montant de son choix dans les limites spécifiées.

Type `product` - Vente de produits

Vendez des produits de votre catalogue :

{
  "type": "product",
  "name": "Boutique T-shirts",
  "description": "Collection été 2024",
  "currency": "XOF",
  "items": [
    {
      "productId": "prod_abc123",
      "priceId": "price_xyz789",
      "quantity": 1,
      "adjustableQuantity": true,
      "minQuantity": 1,
      "maxQuantity": 10
    },
    {
      "name": "Frais de livraison",
      "description": "Livraison express",
      "quantity": 1,
      "isOptional": false
    }
  ]
}

Type `subscription` - Abonnement récurrent

Créez un lien qui démarre un abonnement :

{
  "type": "subscription",
  "name": "Abonnement Pro",
  "description": "Accès illimité à toutes les fonctionnalités",
  "currency": "XOF",
  "items": [
    {
      "priceId": "price_recurring_monthly"
    }
  ]
}

Pour les abonnements, utilisez un priceId associé à un prix récurrent.

Structure des articles (items)

Pour les types product et subscription, vous pouvez définir des articles :

Champ	Type	Description
`productId`	string	ID du produit (`prod_xxx`)
`priceId`	string	ID du prix (`price_xxx`)
`name`	string	Nom personnalisé (si pas de produit)
`description`	string	Description personnalisée
`imageUrl`	string	URL de l’image
`quantity`	number	Quantité par défaut (défaut: 1)
`adjustableQuantity`	boolean	Permettre au client de modifier la quantité
`minQuantity`	number	Quantité minimum
`maxQuantity`	number	Quantité maximum
`isOptional`	boolean	Article optionnel (le client peut le retirer)
`sortOrder`	number	Ordre d’affichage

Options avancées

Limiter les utilisations

{
  "type": "amount",
  "name": "Offre limitée",
  "amount": 15000,
  "currency": "XOF",
  "maxRedemptions": 100,
  "expiresAt": "2024-12-31T23:59:59Z"
}

Collecter les adresses

{
  "collectBillingAddress": true,
  "collectShippingAddress": true
}

{
  "allowPromotionCodes": true
}

Personnaliser le bouton de paiement

{
  "submitType": "book",
  "submitMessage": "Annulation gratuite jusqu'à 48 h avant la date."
}

`submitType`	Bouton affiché
`auto` (ou absent)	Payer
`pay`	Payer
`book`	Réserver
`donate`	Faire un don

submitMessage est affiché sous le bouton en texte brut (aucun HTML, retours à la ligne conservés). Les espaces en bord sont retirés ; une chaîne vide équivaut à null, une chaîne faite uniquement d’espaces est refusée en 422. Une session de paiement ouverte depuis le lien hérite de son submitType.

URL de redirection personnalisées

{
  "successUrl": "https://votre-site.com/merci?link_id={PAYMENT_LINK_ID}",
  "cancelUrl": "https://votre-site.com/annule"
}

Slug personnalisé

Créez une URL mémorable :

{
  "slug": "don-2024"
}

L’URL sera : https://pay.yabetoo.com/p/don-2024

Exemple complet

curl -X POST https://buy.api.yabetoopay.com/v1/payment-links \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "product",
    "name": "Boutique Formation",
    "description": "Formations en ligne",
    "slug": "formations",
    "currency": "XOF",
    "collectBillingAddress": true,
    "allowPromotionCodes": true,
    "successUrl": "https://votre-site.com/success",
    "cancelUrl": "https://votre-site.com/cancel",
    "maxRedemptions": 500,
    "expiresAt": "2024-12-31T23:59:59Z",
    "items": [
      {
        "productId": "prod_formation_js",
        "priceId": "price_formation_js",
        "quantity": 1,
        "adjustableQuantity": false
      },
      {
        "productId": "prod_formation_react",
        "priceId": "price_formation_react",
        "quantity": 1,
        "isOptional": true
      }
    ],
    "metadata": {
      "campaign": "summer_2024",
      "source": "newsletter"
    }
  }'

const response = await fetch("https://buy.api.yabetoopay.com/v1/payment-links", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer sk_live_...",
  },
  body: JSON.stringify({
    type: "product",
    name: "Boutique Formation",
    description: "Formations en ligne",
    slug: "formations",
    currency: "XOF",
    collectBillingAddress: true,
    allowPromotionCodes: true,
    successUrl: "https://votre-site.com/success",
    items: [
      {
        productId: "prod_formation_js",
        priceId: "price_formation_js",
        quantity: 1,
      },
    ],
    metadata: {
      campaign: "summer_2024",
    },
  }),
});

const paymentLink = await response.json();
console.log(paymentLink.url); // URL à partager

import requests

response = requests.post(
    "https://buy.api.yabetoopay.com/v1/payment-links",
    headers={
        "Authorization": "Bearer sk_live_...",
        "Content-Type": "application/json"
    },
    json={
        "type": "amount",
        "name": "Faire un don",
        "description": "Soutenez notre cause",
        "minAmount": 1000,
        "maxAmount": 500000,
        "currency": "XOF",
        "allowPromotionCodes": False,
        "metadata": {
            "campaign": "charity_2024"
        }
    }
)

payment_link = response.json()
print(payment_link["url"])

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://buy.api.yabetoopay.com/v1/payment-links",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_live_...",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "type" => "amount",
        "name" => "Paiement facture",
        "amount" => 75000,
        "currency" => "XOF",
        "expiresAt" => "2024-06-30T23:59:59Z",
        "metadata" => [
            "invoice_id" => "INV-2024-001"
        ]
    ])
]);

$response = curl_exec($curl);
$paymentLink = json_decode($response, true);
echo $paymentLink["url"];

Réponse

{
  "id": "plink_abc123def456ghi789jkl012",
  "object": "payment_link",
  "type": "product",
  "name": "Boutique Formation",
  "description": "Formations en ligne",
  "slug": "formations",
  "url": "https://pay.yabetoo.com/p/formations",
  "currency": "XOF",
  "amount": null,
  "minAmount": null,
  "maxAmount": null,
  "isActive": true,
  "expiresAt": "2024-12-31T23:59:59.000Z",
  "maxRedemptions": 500,
  "redemptionCount": 0,
  "collectBillingAddress": true,
  "collectShippingAddress": false,
  "allowPromotionCodes": true,
  "submitType": "pay",
  "submitMessage": null,
  "successUrl": "https://votre-site.com/success",
  "cancelUrl": "https://votre-site.com/cancel",
  "items": [
    {
      "id": "plitem_abc123",
      "productId": "prod_formation_js",
      "priceId": "price_formation_js",
      "name": "Formation JavaScript",
      "description": "Maîtrisez JavaScript",
      "quantity": 1,
      "adjustableQuantity": false,
      "isOptional": false,
      "sortOrder": 0
    },
    {
      "id": "plitem_def456",
      "productId": "prod_formation_react",
      "priceId": "price_formation_react",
      "name": "Formation React",
      "description": "Créez des apps React",
      "quantity": 1,
      "adjustableQuantity": false,
      "isOptional": true,
      "sortOrder": 1
    }
  ],
  "metadata": {
    "campaign": "summer_2024",
    "source": "newsletter"
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Champs de la réponse

Champ	Description
`id`	Identifiant unique du lien
`url`	URL publique à partager
`slug`	Slug utilisé dans l’URL
`isActive`	Indique si le lien est actif
`redemptionCount`	Nombre de fois que le lien a été utilisé
`items`	Liste des articles (pour type `product`)

Opérations courantes

Récupérer un lien

curl https://buy.api.yabetoopay.com/v1/payment-links/plink_abc123 \
  -H "Authorization: Bearer sk_live_..."

Mettre à jour un lien

curl -X PUT https://buy.api.yabetoopay.com/v1/payment-links/plink_abc123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nouveau nom",
    "description": null
  }'

Seules les clés envoyées sont modifiées :

une clé absente laisse le champ inchangé ;
null efface le champ : description, amount, minAmount, maxAmount, suggestedAmounts, expiresAt, maxRedemptions, successUrl, cancelUrl, brandingId, metadata, submitType, submitMessage. name et slug ne s’effacent pas (422).

Le slug est modifiable, sous les mêmes règles qu’à la création. L’ancienne URL https://pay.yabetoo.com/p/<ancien-slug> cesse alors de fonctionner : tout lien déjà partagé ou encodé dans un QR code est cassé. Un slug reste pris même après la suppression de son lien.

Un minAmount supérieur à maxAmount est refusé en 422, à la création comme à la mise à jour. Articles (liens product et subscription) : quand items est envoyé, c’est la nouvelle liste complète. Un article portant son id est modifié, un article sans id est créé, un article existant absent de la liste est supprimé. Un id inconnu, répété ou envoyé avec un autre productId est refusé en 422.

curl -X PUT https://buy.api.yabetoopay.com/v1/payment-links/plink_abc123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "id": "plitem_keep", "quantity": 2 },
      { "productId": "prod_new", "priceId": "price_new" }
    ]
  }'

Désactiver un lien

curl -X PUT https://buy.api.yabetoopay.com/v1/payment-links/plink_abc123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": false
  }'

Supprimer un lien

curl -X DELETE https://buy.api.yabetoopay.com/v1/payment-links/plink_abc123 \
  -H "Authorization: Bearer sk_live_..."

Lister les liens

curl "https://buy.api.yabetoopay.com/v1/payment-links?type=product&isActive=true" \
  -H "Authorization: Bearer sk_live_..."

Webhooks

Recevez des notifications lorsqu’un paiement est effectué via un lien :

{
  "id": "evt_abc123",
  "type": "payment_link.checkout.completed",
  "data": {
    "paymentLinkId": "plink_abc123",
    "checkoutSessionId": "cs_xyz789",
    "orderId": "ord_def456",
    "amount": 25000,
    "currency": "xaf",
    "customerEmail": "client@example.com",
    "completedAt": "2026-09-26T10:15:00.000Z"
  },
  "created_at": "2026-09-26T10:15:00.000Z"
}

Les champs sont directement sous data (il n’y a pas de data.object). amount est en unité majeure de la devise (25000 = 25 000 XAF).

Événements disponibles

Événement	Description
`payment_link.created`	Lien créé
`payment_link.checkout.completed`	Paiement réussi via un lien `product` ou `amount`
`payment_link.checkout.failed`	Paiement échoué via un lien `product` ou `amount` (`data.error` porte le motif, pas d’`amount`)

Un paiement par lien émet payment_link.checkout.completed, pas checkout.session.completed : abonnez-vous à la famille payment_link.*.
La mise à jour d’un lien n’émet aucun événement.
Les liens subscription passent par le flux d’abonnement et n’émettent aucun événement payment_link.* : écoutez les événements d’abonnement.

Voir la documentation Webhooks pour la signature et la livraison.

Bonnes pratiques

Sécurité

Créez toujours les liens côté serveur
Ne stockez jamais les clés API côté client
Utilisez des webhooks pour vérifier les paiements

Expérience utilisateur

Utilisez des slugs mémorables pour les liens importants
Ajoutez une description claire
Définissez une date d’expiration raisonnable

Gestion

Utilisez les métadonnées pour le suivi (campagne, source, etc.)
Surveillez le redemptionCount pour les offres limitées
Désactivez les liens plutôt que de les supprimer

Prochaines étapes

Partager un lien

Découvrez comment partager vos liens efficacement

Webhooks

Configurez les notifications en temps réel

Pour commencer

Créer une page de paiement

Intégration avancée des paiements

Décaissements

Transferts

Liens de paiement

Créer un Lien de paiement