Liens de paiement

Les liens de paiement sont des URLs réutilisables qui permettent aux clients de payer une commande. Contrairement aux commandes standard qui expirent après un seul échec, les liens de paiement supportent plusieurs tentatives, ce qui les rend idéaux pour les factures, les paiements par e-mail et les scénarios où le client ne paie pas immédiatement.

Caractéristiques principales

Réutilisables : Les clients peuvent réessayer le paiement jusqu'à 25 fois si les tentatives précédentes échouent.
Longue durée de vie : L'expiration par défaut est de 30 jours (configurable via expiration_period).
Partageables : Envoyez le lien par e-mail, SMS, messagerie ou intégrez-le sur votre site web.

Créer un lien de paiement

Envoyez une requête POST à /v1/paymentlinks/ :

POST /v1/paymentlinks/

curl -X POST https://api.costplus.online/v1/paymentlinks/ \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_order_id": "invoice-1234",
    "amount": 995,
    "currency": "EUR",
    "description": "Invoice #1234"
  }'

La réponse inclut le payment_url à partager avec le client et un id unique pour le suivi :

Réponse (201 Created)

{
  "id": "e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1",
  "merchant_order_id": "invoice-1234",
  "amount": 995,
  "currency": "EUR",
  "description": "Invoice #1234",
  "expiration_period": "P30D",
  "payment_url": "https://pay.costplus.online/paymentlinks/e6eecc6a.../",
  "status": "new",
  "reason": "Payment Link was created, not yet visited",
  "orders": {},
  "created": "2026-01-15T12:00:00.000000Z"
}

Sauvegardez l'id — vous l'utiliserez pour vérifier le statut du lien de paiement ultérieurement.

Champs obligatoires

Champ	Description
`merchant_order_id`	Votre propre identifiant de référence pour le lien de paiement
`amount`	Montant en centimes (ex. 9,95 EUR = `995`)
`currency`	Code devise ISO 4217 (ex. `EUR`, `GBP`)

Champs optionnels

Champ	Description
`description`	Description affichée au client
`expiration_period`	Durée ISO 8601. Par défaut `P30D` (30 jours)
`return_url`	URL de redirection du client après un paiement réussi
`failure_url`	URL de redirection du client en cas d'annulation, d'expiration ou d'erreur
`webhook_url`	URL pour recevoir les notifications de changement de statut
`customer`	Objet contenant les informations du client (nom, e-mail, etc.)

Si vous fournissez à la fois return_url et failure_url, les clients sont redirigés vers failure_url lorsque le statut de la commande est cancelled, expired ou error. Sinon, toutes les redirections vont vers return_url.

Récupérer un lien de paiement

Envoyez une requête GET à /v1/paymentlinks/{id}/ en utilisant l'id du lien de paiement de la réponse de création :

GET /v1/paymentlinks/{id}/

curl -u YOUR_API_KEY: \
  https://api.costplus.online/v1/paymentlinks/e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1/

La réponse inclut le statut actuel et les références à toutes les commandes créées à partir du lien, regroupées par statut :

Réponse (exemple completed)

{
  "id": "e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1",
  "merchant_order_id": "invoice-1234",
  "amount": 995,
  "currency": "EUR",
  "description": "Invoice #1234",
  "expiration_period": "P30D",
  "payment_url": "https://pay.costplus.online/paymentlinks/e6eecc6a.../",
  "status": "completed",
  "reason": "Completed",
  "completed": "2026-01-15T12:05:30.123456+00:00",
  "completed_order_id": "3bb663cc-2a20-400d-8bf6-18d9695d0c66",
  "orders": {
    "error": ["0d79014c-0aaa-4fd6-87c5-c8cfa5f5ac69"],
    "completed": ["3bb663cc-2a20-400d-8bf6-18d9695d0c66"]
  }
}

Dans cet exemple, le client a effectué une tentative échouée (commande 0d79014c... en statut error) avant de réussir (commande 3bb663cc... en statut completed). Vous pouvez récupérer les détails complets de toute commande via GET /v1/orders/{order_id}/.

Statuts des liens de paiement

Statut	Description
`new`	Le lien a été créé mais aucune tentative de paiement n'a été effectuée.
`processing`	Une tentative de paiement est actuellement en cours.
`all_unsuccessful`	Toutes les tentatives de paiement ont échoué jusqu'à présent. Le client peut encore réessayer (jusqu'à 25 tentatives).
`completed`	Le paiement a réussi. Le lien n'est plus actif.
`expired`	Le lien a expiré avant qu'un paiement réussi ne soit effectué.

Le statut all_unsuccessful n'est pas un statut final. Le client peut encore tenter de payer jusqu'à ce que le paiement réussisse, que le nombre maximum de tentatives (25) soit atteint, ou que le lien expire.

Une fois qu'un lien de paiement atteint le statut completed ou expired, il ne peut plus être utilisé. Créez un nouveau lien de paiement si le client doit payer à nouveau.

Exemple de flux de travail

Créez un lien de paiement via POST /v1/paymentlinks/.
Partagez le payment_url retourné avec votre client (ex. par e-mail, SMS ou facture).
Le client ouvre le lien et finalise le paiement.
Cost+ envoie un webhook à votre webhook_url lorsque le statut change.
Vérifiez le statut du lien de paiement via GET /v1/paymentlinks/{id}/.
Traitez la commande une fois le statut completed.

Points d'accès associés

Créer un lien de paiement — créer un lien de paiement réutilisable
Obtenir un lien de paiement — récupérer le statut actuel d'un lien de paiement

On this page