Liens de paiement
Créer un lien de paiement réutilisable, le partager, le désactiver, et retrouver les paiements qu’il a produits.
Un lien de paiement est une page hébergée par 221 Pay, à montant fixe. Le client y choisit un moyen de paiement parmi ceux actifs sur le compte, saisit son numéro mobile et paie. Le lien est réutilisable : chaque validation du formulaire crée un paiement ordinaire du projet.
Usage type : vente par messagerie ou réseau social, facture envoyée par SMS, sans page de paiement à intégrer.
Créer un lien
curl -X POST "$API_URL/v1/payment-links" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": "15000",
"description": "Panier légumes de la semaine",
"return_url": "https://boutique.example/merci",
"expiry": "2026-12-31T23:59:59Z"
}'| Champ | Requis | Description |
|---|---|---|
amount | oui | Montant en XOF, chaîne de chiffres strictement positive. |
description | oui | 1 à 80 caractères, affichés au client. |
return_url | non | URL https:// où revient le client après le paiement. |
expiry | non | Date RFC 3339 future. Sans expiry, le lien n’expire pas. |
{
"id": "4b0e2d7a-91c3-4f1e-8a6d-0c5b7e2f9d13",
"amount": "15000",
"currency": "XOF",
"description": "Panier légumes de la semaine",
"status": "active",
"created_at": "2026-10-07T10:00:00Z",
"expiry": "2026-12-31T23:59:59Z",
"link_to_pay": "https://…/p/4b0e2d7a-91c3-4f1e-8a6d-0c5b7e2f9d13"
}Partager link_to_pay : par message, QR code imprimé ou bouton sur un site.
Statuts
| Statut | Signification |
|---|---|
active | Le lien accepte des paiements. |
inactive | Désactivé par le marchand ; la page indique au client que le lien est indisponible. |
expired | Date expiry dépassée. Un lien expiré ne se réactive pas : en créer un nouveau. |
Désactiver ou réactiver
curl -X POST "$API_URL/v1/payment-links/$LINK_ID/status" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "inactive"}'status vaut active ou inactive. Réactiver un lien expiré renvoie
400 INVALID_REQUEST.
Relire et lister
curl "$API_URL/v1/payment-links/$LINK_ID" -H "Authorization: Bearer $API_KEY"
curl "$API_URL/v1/payment-links?status=active&limit=20" -H "Authorization: Bearer $API_KEY"Filtres : status, from, to (RFC 3339), limit (1 à 100), offset. La
réponse contient data et total_count.
Paiements issus d’un lien
Chaque paiement lancé depuis un lien porte une merchant_reference de la
forme link:{id du lien}:{identifiant de tentative}. Les retrouver :
curl "$API_URL/v1/payments?q=link:$LINK_ID" -H "Authorization: Bearer $API_KEY"Chacun renvoie aussi payment_link_description, la description du lien, plus
lisible que la merchant_reference. Ces paiements suivent le cycle normal et déclenchent les mêmes webhooks
(payment.succeeded, payment.failed, payment.expired). Voir
Paiements.