Créer un Lien de paiement

Requête de base

curl -X POST https://api.yabetoo.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
`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
}

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://checkout.yabetoo.com/p/don-2024

Exemple complet

curl -X POST https://api.yabetoo.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"
    }
  }'

Réponse

{
  "id": "plink_abc123def456ghi789jkl012",
  "object": "payment_link",
  "type": "product",
  "name": "Boutique Formation",
  "description": "Formations en ligne",
  "slug": "formations",
  "url": "https://checkout.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,
  "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://api.yabetoo.com/v1/payment-links/plink_abc123 \
  -H "Authorization: Bearer sk_live_..."

Mettre à jour un lien

curl -X PATCH https://api.yabetoo.com/v1/payment-links/plink_abc123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nouveau nom",
    "isActive": false
  }'

Désactiver un lien

curl -X PATCH https://api.yabetoo.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://api.yabetoo.com/v1/payment-links/plink_abc123 \
  -H "Authorization: Bearer sk_live_..."

Lister les liens

curl "https://api.yabetoo.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 :

{
  "type": "payment_link.payment.completed",
  "data": {
    "object": {
      "paymentLinkId": "plink_abc123",
      "sessionId": "plsession_xyz789",
      "amount": 25000,
      "currency": "XOF",
      "customerEmail": "client@example.com",
      "status": "completed"
    }
  }
}

Événements disponibles

Événement	Description
`payment_link.created`	Lien créé
`payment_link.updated`	Lien mis à jour
`payment_link.payment.completed`	Paiement réussi via le lien
`payment_link.payment.failed`	Paiement échoué

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