Collecte - Liens de paiement

Les liens de paiement permettent de creer des URL de checkout heberge que les clients peuvent ouvrir depuis des factures, messages, reseaux sociaux ou campagnes e-mail. Un lien peut collecter un montant fixe ou laisser le client saisir un montant dans des limites configurees.

Quand un client termine un paiement via un lien de paiement, Payfonte envoie un webhook de paiement vers votre endpoint webhook configure. Utilisez l’evenement webhook comme source de verite avant d’executer une commande ou de marquer une facture comme payee.

Voir Webhooks et callbacks pour le payload payment.completed, la verification de signature, la gestion des retries et la priorite des URL webhook.

Endpoints

Methode	Endpoint	Objet
`POST`	`/payments/v1/payment-links`	Creer un lien de paiement
`GET`	`/payments/v1/payment-links`	Recuperer les liens de paiement pagines
`GET`	`/payments/v1/payment-links/{id}`	Recuperer un lien de paiement et ses analytics

Etapes d’integration

Creer le lien de paiement

Appelez POST /payments/v1/payment-links avec title, description, la devise, le pays et les parametres de montant. Envoyez votre identifiant client dans l’en-tete client-id.

Partager l'URL

Utilisez le shortURL ou le longURL renvoye dans vos factures, e-mails, conversations, publications sociales ou relances de paiement.

Recevoir le webhook de paiement

Apres le paiement du client, Payfonte envoie un webhook de paiement a l’endpoint configure. Verifiez la signature du webhook et traitez l’evenement de maniere idempotente.

Analyser les performances du lien

Utilisez GET /payments/v1/payment-links/{id} pour recuperer le lien, les totaux collectes, la repartition par canal et les providers disponibles.

Creer un lien de paiement

curl --request POST \
  --url https://sandbox-api.payfonte.com/payments/v1/payment-links \
  --header 'client-id: <client-id>' \
  --header 'client-secret: <client-secret>' \
  --header 'content-type: application/json' \
  --data '{
    "isAmountFixed": false,
    "title": "decimal test",
    "description": "demo",
    "redirectURL": "",
    "logo": "https://6thbridge-file-upload.s3.amazonaws.com/choosen-02.png",
    "customFields": [],
    "maximumAmount": 100000000,
    "minimumAmount": 0,
    "amountLimit": 100000000,
    "currency": "XOF",
    "country": "CI"
  }'

Exemple de reponse :

{
  "statusCode": 201,
  "data": {
    "clientId": "6thbridge",
    "locale": "en",
    "logo": "https://6thbridge-file-upload.s3.amazonaws.com/choosen-02.png",
    "currency": "XOF",
    "country": "CI",
    "title": "decimal test",
    "description": "demo",
    "isAmountFixed": false,
    "longURL": "https://checkout-staging.6thbridge.com/link/6a7a2093b9e24880f73a80b0",
    "shortURL": "https://s.6bd.co/payment-link/1PIDcH",
    "minimumAmount": 0,
    "maximumAmount": 100000000,
    "amountLimit": 100000000,
    "customFields": [],
    "redirectURL": "",
    "expiresAt": null,
    "isActive": true,
    "status": "active",
    "parentClientId": "6thbridge",
    "createdAt": "2026-08-10T19:03:47.222Z",
    "updatedAt": "2026-08-10T19:03:47.222Z",
    "id": "6a7a2093b9e24880f73a80b0"
  }
}

Champs de requete

Champ	Type	Requis	Description
`title`	string	Oui	Titre lisible du lien de paiement
`description`	string	Oui	Description lisible du lien de paiement
`currency`	string	Oui	Code devise ISO a 3 lettres obligatoire
`country`	string	Oui	Code pays ISO a 2 lettres obligatoire utilise pour rechercher les integrations actives
`isAmountFixed`	boolean	Non	Definissez `true` lorsque le payeur ne peut pas modifier le montant
`amount`	number	Requis quand `isAmountFixed` vaut `true`	Montant fixe de collecte en sous-unites
`minimumAmount`	number	Utilise quand `isAmountFixed` vaut `false`	Montant minimum saisi par le payeur en sous-unites
`maximumAmount`	number	Utilise quand `isAmountFixed` vaut `false`	Montant maximum saisi par le payeur en sous-unites
`amountLimit`	number	Non	Montant total collectable sur les paiements reussis de ce lien, en sous-unites
`customFields`	array	Non	Champs supplementaires a collecter avant la creation du checkout
`redirectURL`	string	Non	URL vers laquelle rediriger le payeur apres le flux de paiement
`logo`	string	Non	URL du logo ou chaine vide. Par defaut, le logo du client ou de l’entreprise est utilise
`locale`	string	Non	Locale du checkout visible par le payeur. Par defaut, la locale du client ou de l’entreprise est utilisee
`isAnonymousPaymentEnabled`	boolean	Non	Indique si les paiements anonymes sont autorises
`expiresAt`	date	Non	Date d’expiration du lien

Modes de montant

Montant fixe

Utilisez isAmountFixed: true lorsque le client doit payer un montant exact. Envoyez amount avec une valeur superieure a zero.

{
  "isAmountFixed": true,
  "amount": 50000,
  "currency": "NGN",
  "country": "NG",
  "title": "Invoice 1001",
  "description": "Payment for invoice 1001"
}

Montant variable

Utilisez isAmountFixed: false lorsque le client peut saisir le montant du paiement. Envoyez minimumAmount et maximumAmount pour definir la plage autorisee.

{
  "isAmountFixed": false,
  "minimumAmount": 10000,
  "maximumAmount": 200000,
  "amountLimit": 1000000,
  "currency": "NGN",
  "country": "NG",
  "title": "Donation",
  "description": "Choose how much to pay"
}

Champs personnalises

Utilisez customFields lorsque vous devez collecter des informations supplementaires du payeur avant la creation du checkout. Les champs de choix requierent options. Valeurs customFields.type prises en charge :

Type	Cas d’usage
`text`	Saisie texte courte
`paragraph-text`	Saisie texte longue
`dropdown`	Choix unique parmi des options definies
`number`	Saisie numerique
`date`	Saisie de date
`file-upload`	Piece jointe
`checkbox`	Confirmation booleenne

{
  "customFields": [
    {
      "label": "Invoice number",
      "name": "invoiceNumber",
      "type": "text",
      "required": true
    },
    {
      "label": "Package",
      "name": "package",
      "type": "dropdown",
      "required": true,
      "options": ["Basic", "Premium"]
    }
  ]
}

Recuperer les liens de paiement

curl --request GET \
  --url 'https://sandbox-api.payfonte.com/payments/v1/payment-links?page=1&limit=2' \
  --header 'client-id: <client-id>' \
  --header 'client-secret: <client-secret>'

Recuperer un lien de paiement par ID

curl --request GET \
  --url https://sandbox-api.payfonte.com/payments/v1/payment-links/6a7204a536c2106e38fe8e01 \
  --header 'client-id: <client-id>' \
  --header 'client-secret: <client-secret>'

La reponse inclut les champs du lien de paiement et un objet analytics avec le montant collecte, le nombre de transactions, la repartition par canal, l’historique de revenu, les providers disponibles et les canaux disponibles.

Finalisation par webhook

Les liens de paiement utilisent le meme flux de webhook de collecte que celui documente dans Webhooks et callbacks. Quand un client termine avec succes un checkout de lien de paiement, Payfonte envoie un webhook de paiement tel que payment.completed.

Verifier la signature

Validez x-webhook-signature avec votre client-secret avant de traiter l’evenement.

Utiliser l'idempotence

Suivez les valeurs reference et status deja traitees afin que les retries ne declenchent pas de double execution.

Executer apres le statut final

Marquez les factures, commandes ou soldes comme payes uniquement apres reception et validation d’un statut webhook final tel que success.

Regles importantes

Les valeurs de montant sont envoyees en sous-unites. Voir Specification des montants.

Ne vous fiez pas uniquement au comportement de redirection client pour confirmer le paiement. Traitez toujours le webhook de paiement avant d’executer une valeur.

Documentation associee

Reference API

Consultez les definitions d’endpoints de liens de paiement et les schemas de requete.

Webhooks

Recevez et verifiez les evenements de finalisation de paiement.

Specification des montants

Comprenez comment envoyer les montants en sous-unites.

Premiers pas

Concepts clés

Prestataires et couverture

Développement

Encaisser des paiements

Décaissements

Collecte - Liens de paiement

Endpoints

Etapes d’integration

Creer un lien de paiement

Champs de requete

Modes de montant

Champs personnalises

Recuperer les liens de paiement

Recuperer un lien de paiement par ID

Finalisation par webhook

Regles importantes

Documentation associee

Reference API

Webhooks

Specification des montants

​Endpoints

​Etapes d’integration

​Creer un lien de paiement

​Champs de requete

​Modes de montant

​Champs personnalises

​Recuperer les liens de paiement

​Recuperer un lien de paiement par ID

​Finalisation par webhook

​Regles importantes

​Documentation associee

Reference API

Webhooks

Specification des montants

Endpoints

Etapes d’integration

Creer un lien de paiement

Champs de requete

Modes de montant

Champs personnalises

Recuperer les liens de paiement

Recuperer un lien de paiement par ID

Finalisation par webhook

Regles importantes

Documentation associee