Liens de paiement

Les Liens de paiement sont des URLs de paiement permanentes et partageables, sans date d’expiration par défaut. Contrairement aux Sessions de paiement qui sont à usage unique et expirent, un Lien de paiement peut être utilisé plusieurs fois, par plusieurs clients différents.

Cas d’usage typiques : lien de paiement dans un email marketing, bouton d’achat sur un site, QR code en point de vente, lien partagé sur WhatsApp.

Lien de paiement vs. Session de paiement

Lien de paiement → lien permanent, réutilisable, partageable à grande échelle. Idéal pour les produits standards. Session de paiement → session unique, liée à un Customer précis, expire après un délai. Idéale pour les paniers e-commerce personnalisés.

Types de liens

Type	Usage	Champs requis
`product`	Vente d'un ou plusieurs Products définis.	`products` (IDs)
`custom`	Montant libre défini par le marchand.	`amount`
`donation`	Don libre — le client saisit le montant.	Aucun montant requis

Endpoints

Méthode	Endpoint	Description
POST	`/payment-links/`	Créer un lien de paiement
GET	`/payment-links/`	Lister les liens
GET	`/payment-links/{id}/`	Récupérer un lien
PATCH	`/payment-links/{id}/`	Modifier un lien
DELETE	`/payment-links/{id}/`	Supprimer définitivement
POST	`/payment-links/{id}/archive/`	Archiver (désactiver sans supprimer)
POST	`/payment-links/{id}/restore/`	Restaurer un lien archivé

Cette introduction est-elle claire ?

Schéma de l’objet

ResponseObjet PaymentLink

json

{
  "id": "link_xxxxxxxxxxxx",
  "object": "payment_link",
  "name": "Formation Excel Avancé",
  "url": "https://pay.sangho.ga/l/lnk_xxx",
  "payment_link_type": "product",
  "currency": "XAF",
  "amount": 25000,
  "products": ["prod_xxx"],
  "status": "active",
  "validity_type": "limited",
  "max_usage": 100,
  "usage_count": 12,
  "expires_at": "2026-12-31T23:59:59Z",
  "redirect_url": {
    "success": "https://boutique.com/merci",
    "cancel": "https://boutique.com/panier"
  },
  "payment_method_types": ["mobile_money", "bank_card"],
  "collect_customer_info": true,
  "allow_quantity": false,
  "livemode": true,
  "metadata": { "sku": "FORM-XLS-001" },
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Créer un Lien de paiement

POSTCorps de la requête

currencyRequis

stringISO 4217ex :XAF

Code devise ISO 4217 du lien de paiement.

payment_link_typeOptionnel

stringdéfaut :product

Type du lien : product, custom, ou donation. Détermine les champs requis et le comportement de la page de paiement.

productsOptionnel

array[string]

Liste d’IDs de Products à vendre via ce lien. Requis si payment_link_type: product.

Vous pouvez associer jusqu’à 20 produits par lien. Si un seul produit est associé, la page de paiement affiche directement ses détails. Avec plusieurs produits, l’acheteur voit une liste de sélection.

amountOptionnel

integercentimes

Montant fixe en centimes. Requis si payment_link_type: custom. Ignoré pour les types product et donation.

nameOptionnel

string

Nom affiché en titre sur la page de paiement. Si non fourni et type: product, le nom du premier produit est utilisé.

validity_typeOptionnel

stringdéfaut :unlimited

Politique de validité du lien.

Valeurs : unlimited (jamais expiré, jamais limité), limited (limité par max_usage et/ou expires_at), one_time (utilisable une seule fois — équivalent à max_usage: 1).

max_usageOptionnel

integer

Nombre maximum d’utilisations du lien. Une fois atteint, la page de paiement affiche un message d’indisponibilité.

Actif uniquement si validity_type: limited. Compte une utilisation dès qu’un paiement est initié (statut processing), même si le paiement échoue ensuite. Utile pour les ventes en quantité limitée.

expires_atOptionnel

stringISO 8601ex :2026-12-31T23:59:59Z

Date et heure d’expiration du lien. Après cette date, la page de paiement est désactivée.

Actif uniquement si validity_type: limited. Le lien peut expirer avant max_usage si les deux sont définis.

redirect_urlOptionnel

object

URLs de redirection après paiement. Objet avec les clés success (URL après paiement réussi) et cancel (URL si l’acheteur abandonne).

Si non fourni, Sangho affiche une page de confirmation générique. Ajoutez ?session_id={CHECKOUT_SESSION_ID} à votre URL de succès pour récupérer les détails côté serveur.

payment_method_typesOptionnel

array[string]

Méthodes de paiement autorisées sur ce lien. Si omis, toutes les méthodes actives de l’App sont proposées.

collect_customer_infoOptionnel

booleandéfaut :true

Si true, la page de paiement collecte les informations de l’acheteur (nom, email) et crée automatiquement un Customer.

Désactiver cette option (false) produit des paiements anonymes — moins de données mais une expérience plus rapide. Non recommandé si vous souhaitez envoyer des reçus automatiques.

allow_quantityOptionnel

booleandéfaut :false

Si true, affiche un sélecteur de quantité sur la page de paiement. L’acheteur peut choisir combien d’exemplaires acheter.

metadataOptionnel

object

Données libres. Retournées dans les webhooks payment_intent.succeeded liés à ce lien.

Les paramètres du Lien de paiement sont-ils clairs ?

Créer un lien produit

bash

curl -X POST https://api.sangho.ga/v1/payment-links/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "XAF",
    "payment_link_type": "product",
    "products": ["prod_xxx"],
    "name": "Formation Excel Avancé",
    "validity_type": "limited",
    "max_usage": 50,
    "expires_at": "2026-12-31T23:59:59Z",
    "redirect_url": {
      "success": "https://boutique.com/merci",
      "cancel": "https://boutique.com/catalogue"
    },
    "metadata": { "campaign": "newsletter-mars-2026" }
  }'

Response201 Created

Le lien est actif immédiatement. Partagez link.url à vos clients.

json

{
  "id": "link_xxxxxxxxxxxx",
  "object": "payment_link",
  "name": "Formation Excel Avancé",
  "url": "https://pay.sangho.ga/l/lnk_xxx",
  "payment_link_type": "product",
  "currency": "XAF",
  "amount": 25000,
  "status": "active",
  "validity_type": "limited",
  "max_usage": 50,
  "usage_count": 0,
  "expires_at": "2026-12-31T23:59:59Z",
  "livemode": true,
  "created_at": "2026-03-01T10:00:00Z"
}

ResponseLien archivé

POST /payment-links/{id}/archive/ désactive le lien sans le supprimer. La page de paiement devient inaccessible mais le lien reste récupérable via GET.

L'archivage est réversible via /restore/. La suppression (DELETE) est définitive.

json

{
  "id": "link_xxxxxxxxxxxx",
  "status": "archived",
  "updated_at": "2026-06-01T12:00:00Z"
}