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

Response Objet PaymentLink

json

{
  "id": "lnk_xxxxxxxxxxxx",
  "object": "payment_link",
  "name": "Formation Excel Avancé",
  "url": "https://pay.sangho.com/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

POST Corps de la requête

currency Requis

string ISO 4217 ex : XAF

Code devise ISO 4217 du lien de paiement.

payment_link_type Optionnel

string défaut : product

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

products Optionnel

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.

amount Optionnel

integer centimes

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

name Optionnel

string

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

validity_type Optionnel

string dé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_usage Optionnel

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_at Optionnel

string ISO 8601 ex : 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_url Optionnel

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_types Optionnel

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_info Optionnel

boolean dé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_quantity Optionnel

boolean défaut : false

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

metadata Optionnel

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.com/v1/payment-links/ \
  -H "Authorization: Bearer sk_live_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" }
  }'

Response 201 Created

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

json

{
  "id": "lnk_xxxxxxxxxxxx",
  "object": "payment_link",
  "name": "Formation Excel Avancé",
  "url": "https://pay.sangho.com/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"
}

Response Lien 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": "lnk_xxxxxxxxxxxx",
  "status": "archived",
  "updated_at": "2026-06-01T12:00:00Z"
}