Liens de paiement

Le lien et ses sessions

Un lien de paiement vit jusqu'à son échéance, ou jusqu'à ce que vous le désactiviez. Chaque fois qu'un client l'ouvre, Mobupay ouvre une session de paiement de durée normale, une quinzaine de minutes. Si le client abandonne, si sa carte est refusée ou si la session expire, le lien reste ouvert : il pourra le rouvrir et réessayer, avec une session neuve.

Lien à usage unique

C'est le lien par défaut (type: "single") : une commande, un paiement. Au premier paiement abouti, le lien est validé et ne s'ouvre plus ; le client qui le rouvre voit son reçu. Son échéance est de 24 heures par défaut, et peut être aussi longue que vous le souhaitez.

curl -X POST https://api.mobupay.nc/api/v1/payments/links \
  -H "Authorization: Bearer sk_test_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "order": { "amount": 5000, "currency": "XPF", "reference": "CMD-2026-0142" },
    "expiresIn": 604800,
    "redirectUrl": "https://example.com/retour",
    "notificationUrl": "https://example.com/webhook"
  }'

Lien permanent

Un lien permanent (type: "fixed") se partage une fois, sur votre site, un réseau social ou une affiche, et sert autant de clients que vous le souhaitez. Chaque client paie le sien, avec le même montant et la même commande. Il n'a pas d'échéance, sauf si vous en donnez une, et reste payable jusqu'à ce que vous le désactiviez.

curl -X POST https://api.mobupay.nc/api/v1/payments/links \
  -H "Authorization: Bearer sk_test_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "fixed",
    "order": { "amount": 5000, "currency": "XPF", "reference": "COTISATION-2026" },
    "externalId": "cotisation-2026",
    "redirectUrl": "https://example.com/retour",
    "notificationUrl": "https://example.com/webhook"
  }'

• La réponse porte paymentId: null : aucun paiement n'existe avant qu'un client ouvre le lien. Chaque paiement naît à l'ouverture et porte linkId dans ses webhooks.
• Un lien permanent ne désigne aucun client : customerId est refusé (400 FIXED_LINK_NOT_ALLOWED).
• Il n'est jamais validé : chaque paiement émet ses propres payment.*, et le lien reste ouvert.
• Il n'est pas disponible sur un compte de simulation.

Suivre un lien

GET /payments/links/{linkId} rend l'état du lien (active, completed, disabled, expired) et la liste de ses paiements. Les événements link.completed, link.expired, link.disabled et link.enabled vous préviennent de chaque changement, sans avoir à interroger l'API : voir le guide Webhooks.

Désactiver, réactiver

POST /payments/links/{linkId}/disable ferme un lien : vos clients voient une page « lien expiré ». Les paiements déjà reçus ne sont pas touchés. POST /payments/links/{linkId}/enable le rouvre. Un lien à usage unique déjà payé, ou un lien dont l'échéance est passée, ne se réactive pas (409).

Depuis votre espace marchand

Sans intégration, « Créer un paiement » propose le choix entre un lien à usage unique et un lien permanent, ainsi qu'une option « Sans échéance ». La page « Liens de paiement » les range en deux onglets ; pour un lien permanent, elle affiche le nombre de paiements reçus et le montant encaissé, et permet de le désactiver ou de le réactiver.