Paiement instantané

Page générée depuis la spécification OpenAPI que la passerelle sert (GET /v1/openapi.json). Ne la modifiez pas à la main : elle est réécrite à chaque build.

Méthode	Chemin	Description
`POST`	`/v1/alias-claims`	Revendiquer un alias
`PUT`	`/v1/alias-claims/{claimId}/response`	Répondre à une revendication
`POST`	`/v1/alias-lookups`	Résoudre un alias
`POST`	`/v1/payouts/{id}/recall`	Rappeler un versement instantané
`GET`	`/v1/pi-aliases`	Vos alias enrôlés
`POST`	`/v1/pi-aliases`	Enrôler un alias
`DELETE`	`/v1/pi-aliases/{cle}`	Retirer un alias
`PUT`	`/v1/pi-aliases/{cle}/claim-response`	Répondre à une revendication d'alias
`POST`	`/v1/qr`	Émettre un QR EMVCo
`POST`	`/v1/rtp`	Demander un paiement (RTP)
`PUT`	`/v1/rtp/received/{end2endId}/response`	Répondre à une demande reçue
`GET`	`/v1/rtp/{id}`	Consulter une demande de paiement

`POST /v1/alias-claims`

Revendiquer un alias

Demande le transfert vers vous d'un alias détenu ailleurs.

ⓘ Famille réservée aux comptes dont le produit « paiement instantané » est activé ; les autres reçoivent 403. Le paiement instantané est le système de la BCEAO, sur lequel Mikaty SN SA est participant.

Paramètres

Nom	Emplacement	Requis	Description
`Idempotency-Key`	header	non	Clé d'idempotence propre à CETTE opération. Rejouer la même clé avec la même charge utile retourne l'originale ; la rejouer avec une charge utile différente est refusé (409).

Corps de la requête

Champ	Type	Requis	Description
`alias`	string	oui	L'alias revendiqué.

Réponses

201 — Revendication déposée (PiClaim)
401 — Clé API manquante ou rejetée (Error)
403 — La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)
409 — Clé d'idempotence rejouée avec une charge utile différente (Error)
422 — Requête recevable mais refusée : champ manquant, corridor fermé, solde insuffisant (Error)
429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

`PUT /v1/alias-claims/{claimId}/response`

Répondre à une revendication

La réponse à une revendication, par son identifiant.

Paramètres

Nom	Emplacement	Requis	Description
`claimId`	path	oui	L'identifiant de la revendication.

Corps de la requête

Champ	Type	Requis	Description
`accept`	boolean	oui

Réponses

200 — OK (PiClaim)
401 — Clé API manquante ou rejetée (Error)
403 — La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)
429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

`POST /v1/alias-lookups`

Résoudre un alias

Interroge l'annuaire : à qui appartient cet alias ?

⚠️ Le nom retourné est celui que l'annuaire détient. Il est comparé à ce que vous affirmez lors d'un envoi : un écart fait refuser l'opération par le schéma.

Corps de la requête

Champ	Type	Requis	Description
`alias`	string	oui

Réponses

200 — OK (PiLookup)
401 — Clé API manquante ou rejetée (Error)
403 — La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)
429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

`POST /v1/payouts/{id}/recall`

Rappeler un versement instantané

Demande le rappel d'un versement déjà parti. Le schéma transmet la demande au bénéficiaire ; un rappel n'est jamais un droit de reprise.

Paramètres

Nom	Emplacement	Requis	Description
`id`	path	oui	Identifiant interne, référence de l'opération, ou votre propre `client_ref`.

Corps de la requête

Champ	Type	Requis	Description
`reason`	string	oui

Réponses

200 — OK (Operation)
401 — Clé API manquante ou rejetée (Error)
403 — La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)
429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

`GET /v1/pi-aliases`

Vos alias enrôlés

Les alias de paiement enrôlés pour vos comptes auprès de l'annuaire du schéma.

Réponses

200 — OK (PiAliasList)
401 — Clé API manquante ou rejetée (Error)
403 — La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)
429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

`POST /v1/pi-aliases`

Enrôler un alias

Enrôle un alias auprès de l'annuaire.

⚠️ UN alias par compte : un enrôlement supplémentaire est refusé, et un alias orphelin bloque le compte.

Paramètres

Nom	Emplacement	Requis	Description
`Idempotency-Key`	header	non	Clé d'idempotence propre à CETTE opération. Rejouer la même clé avec la même charge utile retourne l'originale ; la rejouer avec une charge utile différente est refusé (409).

Corps de la requête

Champ	Type	Requis	Description
`account_ref`	string	non	Le compte à enrôler. Vide = le compte principal.
`type`	string	oui	La sorte d'alias : numéro mobile, code marchand, identifiant court.
`value`	string	oui	La clé de l'alias, pour les types qui en portent une.

Réponses

201 — Alias enrôlé (PiAlias)
401 — Clé API manquante ou rejetée (Error)
403 — La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)
409 — Clé d'idempotence rejouée avec une charge utile différente (Error)
422 — Requête recevable mais refusée : champ manquant, corridor fermé, solde insuffisant (Error)
429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

`DELETE /v1/pi-aliases/{cle}`

Retirer un alias

Retire l'alias de l'annuaire. Le compte reste ; c'est l'adressage qui disparaît.

Paramètres

Nom	Emplacement	Requis	Description
`cle`	path	oui	La clé de l'alias.

Réponses

204 — Retiré
401 — Clé API manquante ou rejetée (Error)
403 — La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)
429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

`PUT /v1/pi-aliases/{cle}/claim-response`

Répondre à une revendication d'alias

Quelqu'un revendique un alias que vous détenez : cette réponse accepte ou refuse le transfert.

Paramètres

Nom	Emplacement	Requis	Description
`cle`	path	oui	La clé de l'alias revendiqué.

Corps de la requête

Champ	Type	Requis	Description
`accept`	boolean	oui	Accepter le transfert, ou le refuser.

Réponses

200 — OK (PiAlias)
401 — Clé API manquante ou rejetée (Error)
403 — La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)
429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

`POST /v1/qr`

Émettre un QR EMVCo

Un QR statique ou dynamique au format EMVCo : le payeur le scanne avec son application et paie.

Paramètres

Nom	Emplacement	Requis	Description
`Idempotency-Key`	header	non	Clé d'idempotence propre à CETTE opération. Rejouer la même clé avec la même charge utile retourne l'originale ; la rejouer avec une charge utile différente est refusé (409).

Corps de la requête

Champ	Type	Requis	Description
`asset_id`	integer	oui
`amount_minor`	string	non	Montant en UNITÉS MINEURES, en chaîne de caractères. Jamais un nombre à virgule flottante : les deux perdent des centimes. Le nombre de décimales de l'actif est donné par GET /v1/assets.
`client_ref`	string	non
`description`	string	non

Réponses

201 — QR émis (PiQr)
401 — Clé API manquante ou rejetée (Error)
403 — La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)
409 — Clé d'idempotence rejouée avec une charge utile différente (Error)
422 — Requête recevable mais refusée : champ manquant, corridor fermé, solde insuffisant (Error)
429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

`POST /v1/rtp`

Demander un paiement (RTP)

Une demande de paiement adressée à un payeur : il la voit et la confirme chez lui. Rien n'est débité sans son accord.

Paramètres

Nom	Emplacement	Requis	Description
`Idempotency-Key`	header	non	Clé d'idempotence propre à CETTE opération. Rejouer la même clé avec la même charge utile retourne l'originale ; la rejouer avec une charge utile différente est refusé (409).

Corps de la requête

Champ	Type	Requis	Description
`asset_id`	integer	oui
`amount_minor`	string	oui	Montant en UNITÉS MINEURES, en chaîne de caractères. Jamais un nombre à virgule flottante : les deux perdent des centimes. Le nombre de décimales de l'actif est donné par GET /v1/assets.
`alias`	string	oui	L'alias du payeur.
`client_ref`	string	non
`description`	string	non

Réponses

201 — Demande émise (Operation)
401 — Clé API manquante ou rejetée (Error)
403 — La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)
409 — Clé d'idempotence rejouée avec une charge utile différente (Error)
422 — Requête recevable mais refusée : champ manquant, corridor fermé, solde insuffisant (Error)
429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

`PUT /v1/rtp/received/{end2endId}/response`

Répondre à une demande reçue

Accepter ou refuser une demande de paiement qui vous est adressée.

Paramètres

Nom	Emplacement	Requis	Description
`end2endId`	path	oui	L'identifiant de bout en bout de la demande.

Corps de la requête

Champ	Type	Requis	Description
`accept`	boolean	oui

Réponses

200 — OK (Operation)
401 — Clé API manquante ou rejetée (Error)
403 — La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)
429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

`GET /v1/rtp/{id}`

Consulter une demande de paiement

L'état de la demande et, une fois acceptée, l'opération qui la règle.

Paramètres

Nom	Emplacement	Requis	Description
`id`	path	oui	Identifiant interne, référence de l'opération, ou votre propre `client_ref`.

Réponses

200 — OK (Operation)
401 — Clé API manquante ou rejetée (Error)
403 — La clé ne porte pas le scope requis, ou le compte n'est pas actif (Error)
429 — Budget de requêtes de la clé épuisé (300/min) — honorer Retry-After (Error)

Schémas

Les formes renvoyées par les opérations ci-dessus.

`PiClaim`

Champ	Type	Description
`claim_id`	string
`alias`	string
`status`	string

`Error`

Champ	Type	Description
`error`	object
`error.code`	string
`error.message`	string

`PiLookup`

Champ	Type	Description
`alias`	string
`nom`	string
`participant`	string

`Operation`

Une opération monétaire — encaissement, versement, remboursement, virement ou rééquilibrage. Le même objet dans les cinq familles.

Champ	Type	Description
`id`	string	L'identifiant public de l'opération. C'est celui des chemins /v1/payments/{id}.
`ref`	string	Notre référence interne, lisible. Distincte de l'identifiant : citez-la au support.
`client_ref`	string	La référence que vous avez fournie à la création, rendue telle quelle.
`kind`	string	payin \| payout \| withdrawal \| refund \| chargeback \| adjustment \| transfer \| rebalance. Le même objet sert les cinq familles ; ce champ dit laquelle.
`status`	string	L'état détaillé du rail. ⚠️ Pour décider si l'argent est arrivé, lisez `outcome` : `status` porte le détail du parcours et son vocabulaire dépend du rail.
`outcome`	string	pending \| succeeded \| failed \| cancelled \| expired \| reversed. Le seul champ sur lequel fonder une décision métier.
`asset_id`	integer	L'actif de l'opération, par son identifiant (GET /v1/assets).
`amount_minor`	string	Le montant BRUT en unités mineures, en chaîne de caractères.
`fee_minor`	string	Les frais prélevés, en unités mineures.
`net_minor`	string	Le net en unités mineures : `amount_minor` moins `fee_minor`.
`platform_id`	integer	La plateforme qui a porté l'opération. Absent tant qu'un encaissement hébergé attend que le payeur choisisse.
`is_test`	boolean	Vrai pour une opération créée avec une clé de test. Aucun argent réel ne bouge.
`payment_url`	string	La page de paiement hébergée, quand le rail en fournit une. Absent tant que la soumission n'a pas abouti.
`deeplink`	string	Le lien profond vers l'application du rail, quand il en fournit un.
`qrcode_url`	string	Le QR à présenter au payeur, quand le rail en fournit un.
`risk`	Risk	État du contrôle des risques (FRAML). Absent si l’opération n’a pas été évaluée — ce qui n’est pas la même chose que « clear ». Le webhook sortant et cette lecture rendent le même bloc.
`risk.status`	string	held : les fonds ne sont pas partis. review : le paiement a suivi son cours, quelque chose est examiné. clear : rien à signaler.
`risk.case_ref`	string	Référence du dossier opérationnel, à citer auprès du support. Null lorsque la retenue relève d’un examen de conformité.
`risk.case_kind`	string	Accompagne case_ref ou rien du tout.
`risk.reason`	string	Le seul texte que ce bloc porte, et il est identique pour toute retenue.
`risk.signals`	object[]	Signaux produit, consultatifs. Absent s’il n’y en a aucun.
`risk.signals[].code`	string
`risk.signals[].detail_fr`	string
`amount_refunded_minor`	string	Encaissements seulement : la somme des remboursements ABOUTIS, en unités mineures.
`amount_refund_pending_minor`	string	Encaissements seulement : la somme des remboursements EN COURS, en unités mineures.
`amount_refundable_minor`	string	Encaissements seulement : ce qui peut être remboursé MAINTENANT, en unités mineures — le montant d'origine moins les remboursements aboutis et en cours, ou "0" quand la règle de remboursement n'en permet plus aucun (encaissement non abouti, délai Wave dépassé après un remboursement partiel…).
`refund_count`	integer	Encaissements seulement : le nombre de remboursements non échoués.
`partial_refund_deadline`	string	Encaissements Wave seulement : jusqu'à quand un remboursement partiel est possible (RFC 3339). Absent pour les autres rails, ou quand les remboursements partiels Wave sont désactivés.

`PiAliasList`

Champ	Type	Description
`data`	PiAlias[]
`data[].cle`	string
`data[].type`	string
`data[].account_ref`	string
`data[].status`	string
`page`	integer
`per_page`	integer

`PiAlias`

Champ	Type	Description
`cle`	string
`type`	string
`account_ref`	string
`status`	string

`PiQr`

Champ	Type	Description
`payload`	string	La chaîne EMVCo à encoder.
`qrcode_url`	string