Chargement de vos clés API…

Créer un lien de paiement

POSThttps://api.mobupay.nc/api/v1/payments/links

Ce que fait cet appel

Crée un lien de paiement réutilisable à transmettre au client par email, SMS ou QR. Le client ouvre l'URL et paye sur la page hébergée Mobupay (Payment Widget) à son rythme avant l'expiration. À la fin (succès ou échec), un webhook payment.* est envoyé et le client est redirigé vers redirectUrl.

Si vous exploitez plusieurs boutiques sur un même compte, storeId rattache l'encaissement à l'une d'elles : guide « Plusieurs boutiques » (/docs/guides/boutiques).

En-tête d'authentification

Authorization: Bearer sk_test_XXXX

Le pool est déduit du préfixe de la clé

Il n'y a pas d'interrupteur test et production sur cette page. sk_test_* ne traite aucun paiement réel, sk_live_* encaisse.

Corps de la requête

application/json

storeIdstringOptionnel

Boutique à laquelle rattacher cet encaissement. Accepte l'identifiant (`sto_*`) **ou le code** de la boutique, celui que vos propres systèmes connaissent déjà. **Champ de premier niveau** : à côté de `externalId`, jamais à l'intérieur de `order`. Une clé inconnue placée dans `order` est écartée en silence, et le paiement partirait alors sur le contrat par défaut sans qu'aucune erreur ne vous prévienne. Facultatif. Si votre clé API est déjà rattachée à une boutique, elle fait autorité et vous n'avez rien à transmettre : le corps peut la répéter, jamais la contredire (`STORE_KEY_MISMATCH`). Une boutique inconnue (`UNKNOWN_STORE`), désactivée (`STORE_INACTIVE`) ou déclarée point de vente physique (`STORE_KIND_MISMATCH`) fait échouer l'appel : elle n'est jamais ignorée. Vos boutiques se créent depuis votre espace marchand, Paramètres puis « Mes offres ». Voir le guide « Plusieurs boutiques » (/docs/guides/boutiques). La boutique suit le lien jusqu'au paiement qu'il produit : elle est restituée dans la réponse, portée par les webhooks de ce paiement, et lisible à tout moment sur `GET /payments/{id}`.

merchantConfigIdstringOptionnel

**Usage avancé.** Contrat d'encaissement à employer (`mcf_*`), désigné directement. Ce champ reste accepté, mais la voie normale est la boutique : `storeId`, ou une clé API rattachée à une boutique, désigne le contrat sans que vous ayez à le nommer. Facultatif : absent, le contrat actif par défaut s'applique. Si l'appel et la boutique désignent deux contrats différents, l'appel est refusé (`STORE_CONTRACT_CONFLICT`) : Mobupay n'arbitre jamais en silence entre deux contrats, puisque le choix décide du libellé porté au relevé du client et de la ventilation des fonds.

objectRequis

Détail de la commande à payer. Voir sous-objets `items`, `taxDetail`, `platformConfig`, `delivery`.

captureModestringOptionnel

AUTO (défaut) ou MANUAL. Voir `POST /payments/sessions`.

customerIdstringOptionnel

Identifiant du client à associer au lien (`cus_*`). Optionnel.

externalIdstringOptionnel

Identifie le customer par son identifiant externe (unique par marchand). Max 255 caractères.

isInclTaxAmountbooleanOptionnel

Le montant `order.amount` inclut les taxes (TTC). Défaut `true`.

languageCodestringOptionnel

Code langue de la page de paiement (`fr`, `en`...). 2 a 5 caractères. Défaut `fr`.

redirectUrlstringRequis

URL de redirection après paiement (succès ou échec). Le `paymentId` est ajoute en query string.

failureRedirectUrlstringOptionnel

URL de retour dédiée en cas de refus (défaut : `redirectUrl`). Voir `POST /payments/sessions`.

failurePageModestringOptionnel

`show` (défaut) : page d'échec Mobupay. `redirect` : redirection immédiate vers `failureRedirectUrl`. Voir `POST /payments/sessions`.

successPageModestringOptionnel

Comportement de la page de succès (`auto` par défaut). Voir `POST /payments/sessions`.

notificationUrlstringRequis

URL HTTPS de votre webhook : Mobupay y envoie (POST signé) les events du paiement (`payment.authorized`, `payment.captured`, `payment.failed`...). Livrée en complément des endpoints webhook enregistrés.

privateDataobjectOptionnel

Données privees libres (JSON) conservées côté Mobupay et retournées dans les webhooks.

expiresInintegerOptionnel

Duree de validite du lien en secondes (entier strictement positif). Défaut 86400 (24h).

Codes de retour

201

Lien de paiement créé. store restitue la boutique retenue (null si le lien n'en porte aucune). Sur un rejeu d'idempotence (réponse 200), le champ est absent plutôt que null : ce chemin ne relit pas le paiement déjà créé, et null affirmerait à tort qu'il n'a pas de boutique. Lisez-la alors sur GET /payments/{id}.

400

Paramètres invalides. Sur la boutique : UNKNOWN_STORE (aucune boutique ne porte cet identifiant ni ce code), STORE_INACTIVE (boutique désactivée), STORE_KIND_MISMATCH (point de vente physique, il n'encaisse pas à distance), STORE_CONTRACT_INACTIVE (le contrat rattaché à la boutique n'est plus actif), STORE_CONTRACT_CONFLICT (l'appel et la boutique désignent deux contrats différents), STORE_KEY_MISMATCH (la clé API est rattachée à une autre boutique que celle demandée).

401

Clé API manquante ou invalide.

Langage

Requête cURLpostExemple

1curl --request POST \

2 --url https://api.mobupay.nc/api/v1/payments/links \

3 --header 'authorization: Bearer sk_test_XXXX' \

4 --header 'content-type: application/json' \

5 --data '{ "order": { "reference": "CMD-2026-0142", "amount": 5000, "currency": "XPF", "items": [ { "product": "Pizza Margherita", "unitPrice": 1500, "quantity": 2 }, { "product": "Coca-Cola 33cl", "unitPrice": 500, "quantity": 4 } ] }, "expiresIn": 3600, "customerId": "cus_2KmBz9aQp4nT8R", "storeId": "PAITA", "redirectUrl": "https://example.com/return", "notificationUrl": "https://example.com/webhook" }'

Réponse

Cliquez sur Essayer pour lancer la requête et voir la réponse ici. Ou choisissez un exemple :

application/json