Référence de l'API
Base : https://qkmvexkljdcfarulydao.supabase.co/functions/v1
Cette page est dérivée de la spécification OpenAPI, qui décrit exactement ce qui répond aujourd'hui. Le fichier brut est téléchargeable pour vos outils.
Encaissement mobile money en Côte d'Ivoire, par une intégration unique.
Conventions
- Montants : entier en unité mineure. Le franc CFA n'a pas de subdivision :
10000vaut 10 000 F. Un montant en chaîne ou à décimales est refusé — deviner l'intention d'un montant est le début des ennuis. - Idempotence :
Idempotency-Keyest obligatoire sur tout POST qui déplace de l'argent. Rejouer la même clé avec le même corps rend la réponse d'origine, sans second mouvement. - Traçabilité : toute réponse porte
Valsoria-Request-Id. C'est l'identifiant à citer au support, et celui qui apparaît dans le journal des requêtes de votre console. - Test et live : la clé détermine l'environnement. Aucun paramètre de mode, et aucune donnée ne traverse la frontière.
Ce qui n'existe pas encore : payouts, lots, bénéficiaires, règlements, pagination. Ne pas coder contre ces routes : elles ne répondent pas.
POST /v1-payments
Créer un encaissement
Crée une intention d'encaissement. La réponse ne dit pas que l'argent est arrivé : le paiement naît created, passe pending pendant que le connecteur travaille, et n'est succeeded qu'une fois la preuve reçue de l'opérateur. Écoutez le webhook, ou interrogez GET.
Corps de la requête
| Champ | Type | Requis | Description |
|---|---|---|---|
amount | integer | oui | Unité mineure, entier strict. 10000 = 10 000 F. |
currency | string | non | |
operator | string | non | Opérateur visé, p. ex. orange_ci, mtn_ci. |
counterparty | object | non | Le payeur. |
merchant_reference | string | non | Votre référence. Unique par marchand : une seconde transaction portant la même valeur est refusée en 409. C'est une protection contre le double encaissement, pas une gêne. |
description | string | non | |
metadata | object | non | |
simulate | string | non | Sandbox uniquement : force l'issue sans passer par le connecteur. Ignoré en live. |
Réponses
| Statut | Description |
|---|---|
201 | Paiement créé. Un rejeu d'idempotence rend AUSSI 201. Même clé, même corps : la réponse d'origine est restituée telle quelle, statut compris, et aucun second mouvement n'a lieu. N'en déduisez donc pas qu'un paiement vient d'être créé — 201 signifie « voici le paiement qui correspond à cette clé », pas « un de plus ». Fiez-vous à l'id. |
400 | idempotency_key_required — l'en-tête est obligatoire. invalid_body — corps JSON illisible. |
401 | authentication_required — aucune clé fournie. invalid_api_key — clé inconnue, révoquée ou malformée. Les trois cas rendent le même code : les distinguer aiderait à deviner des clés valides. |
403 | merchant_inactive — le compte ne peut pas encaisser. |
409 | idempotency_in_progress — une requête identique est en cours. duplicate_reference — ce merchant_reference désigne déjà une autre transaction. |
422 | invalid_amount, invalid_currency, ou idempotency_key_reused (même clé, corps différent). |
GET /v1-payments
Lire un paiement
L'identifiant se place en fin de chemin : …/v1-payments/txn_XXXXXXXX.
Un paiement appartenant à un autre marchand rend 404, jamais 403 : répondre 403 confirmerait son existence.
Réponses
| Statut | Description |
|---|---|
200 | Le paiement. |
404 | resource_not_found — inconnu, ou appartenant à un autre marchand. |
422 | invalid_id — l'identifiant ne ressemble pas à un txn_…. |
POST /v1-refunds
Rembourser un encaissement
Rembourse tout ou partie d'un paiement réussi. Sans amount, le reste remboursable est rendu en totalité.
Tous les connecteurs ne savent pas rembourser. Un paiement encaissé par un canal sans opération inverse est refusé en 422 refund_unsupported, avant toute écriture — mieux vaut un refus immédiat qu'une promesse qu'on ne tient pas.
Corps de la requête
| Champ | Type | Requis | Description |
|---|---|---|---|
payment_id | string | oui | |
amount | integer | non | Absent ⇒ remboursement total du reste. |
Réponses
| Statut | Description |
|---|---|
201 | Remboursement créé. |
409 | already_refunded, ou paiement non remboursable dans son état actuel. |
422 | invalid_payment_id, invalid_amount, amount_too_large (au-delà du reste remboursable), ou refund_unsupported. |
L'objet paiement
| Champ | Type |
|---|---|
id | string |
object | string |
amount | integer |
currency | string |
status | string |
operator | string ou null |
merchant_reference | string ou null |
failure_code | string ou null |
failure_message | string ou null |
livemode | boolean |
created_at | string |
succeeded_at | string ou null |
failed_at | string ou null |
Version d'API 2026-08-25 ·
changements ·
spécification OpenAPI