Instant payment

Generated page, from the OpenAPI specification the gateway serves (GET /v1/openapi.json). Do not edit it by hand: it is rewritten on every build.

Method	Path	Description
POST	/v1/alias-claims	Claim an alias
PUT	/v1/alias-claims/{claimId}/response	Answer a claim
POST	/v1/alias-lookups	Resolve an alias
POST	/v1/payouts/{id}/recall	Recall an instant payout
GET	/v1/pi-aliases	Your enrolled aliases
POST	/v1/pi-aliases	Enrol an alias
DELETE	/v1/pi-aliases/{cle}	Remove an alias
PUT	/v1/pi-aliases/{cle}/claim-response	Answer an alias claim
POST	/v1/qr	Issue an EMVCo QR
POST	/v1/rtp	Request a payment (RTP)
PUT	/v1/rtp/received/{end2endId}/response	Answer a received request
GET	/v1/rtp/{id}	Retrieve a payment request

POST /v1/alias-claims

Claim an alias

Requests the transfer to you of an alias held elsewhere.

ⓘ Family restricted to accounts with the “instant payment” product enabled; everyone else gets 403. Instant payment is the BCEAO's scheme, on which Mikaty SN SA is a participant.

Parameters

Name	In	Required	Description
Idempotency-Key	header	no	An idempotency key specific to THIS operation. Replaying the same key with the same payload returns the original; replaying it with a different payload is refused (409).

Request body

Field	Type	Required	Description
alias	string	yes	The alias being claimed.

Responses

• 201 — Claim lodged (PiClaim)
• 401 — API key missing or rejected (Error)
• 403 — The key does not carry the required scope, or the account is not active (Error)
• 409 — Idempotency key replayed with a different payload (Error)
• 422 — Well-formed but refused: missing field, closed corridor, insufficient balance (Error)
• 429 — The key's request budget is exhausted (300/min) — honour Retry-After (Error)

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

Answer a claim

The response to a claim, by its identifier.

ⓘ Family restricted to accounts with the “instant payment” product enabled; everyone else gets 403. Instant payment is the BCEAO's scheme, on which Mikaty SN SA is a participant.

Parameters

Name	In	Required	Description
claimId	path	yes	The claim's identifier.

Request body

Field	Type	Required	Description
accept	boolean	yes

Responses

• 200 — OK (PiClaim)
• 401 — API key missing or rejected (Error)
• 403 — The key does not carry the required scope, or the account is not active (Error)
• 429 — The key's request budget is exhausted (300/min) — honour Retry-After (Error)

POST /v1/alias-lookups

Resolve an alias

Queries the directory: who owns this alias?

⚠️ The name returned is the one the directory holds. It is compared against what you assert when you send: a mismatch makes the scheme refuse the operation.

ⓘ Family restricted to accounts with the “instant payment” product enabled; everyone else gets 403. Instant payment is the BCEAO's scheme, on which Mikaty SN SA is a participant.

Request body

Field	Type	Required	Description
alias	string	yes

Responses

• 200 — OK (PiLookup)
• 401 — API key missing or rejected (Error)
• 403 — The key does not carry the required scope, or the account is not active (Error)
• 429 — The key's request budget is exhausted (300/min) — honour Retry-After (Error)

POST /v1/payouts/{id}/recall

Recall an instant payout

Requests the recall of a payout already sent. The scheme passes the request on to the beneficiary; a recall is never a right to take the money back.

ⓘ Family restricted to accounts with the “instant payment” product enabled; everyone else gets 403. Instant payment is the BCEAO's scheme, on which Mikaty SN SA is a participant.

Parameters

Name	In	Required	Description
id	path	yes	Internal identifier, the operation's reference, or your own client_ref.

Request body

Field	Type	Required	Description
reason	string	yes

Responses

• 200 — OK (Operation)
• 401 — API key missing or rejected (Error)
• 403 — The key does not carry the required scope, or the account is not active (Error)
• 429 — The key's request budget is exhausted (300/min) — honour Retry-After (Error)

GET /v1/pi-aliases

Your enrolled aliases

The payment aliases enrolled for your accounts with the scheme's directory.

ⓘ Family restricted to accounts with the “instant payment” product enabled; everyone else gets 403. Instant payment is the BCEAO's scheme, on which Mikaty SN SA is a participant.

Responses

• 200 — OK (PiAliasList)
• 401 — API key missing or rejected (Error)
• 403 — The key does not carry the required scope, or the account is not active (Error)
• 429 — The key's request budget is exhausted (300/min) — honour Retry-After (Error)

POST /v1/pi-aliases

Enrol an alias

Enrols an alias with the directory.

⚠️ ONE alias per account: a further enrolment is refused, and an orphaned alias blocks the account.

ⓘ Family restricted to accounts with the “instant payment” product enabled; everyone else gets 403. Instant payment is the BCEAO's scheme, on which Mikaty SN SA is a participant.

Parameters

Name	In	Required	Description
Idempotency-Key	header	no	An idempotency key specific to THIS operation. Replaying the same key with the same payload returns the original; replaying it with a different payload is refused (409).

Request body

Field	Type	Required	Description
account_ref	string	no	The account to enrol. Empty = the main account.
type	string	yes	The kind of alias: mobile number, merchant code, short id.
value	string	yes	The alias key, for the types that carry one.

Responses

• 201 — Alias enrolled (PiAlias)
• 401 — API key missing or rejected (Error)
• 403 — The key does not carry the required scope, or the account is not active (Error)
• 409 — Idempotency key replayed with a different payload (Error)
• 422 — Well-formed but refused: missing field, closed corridor, insufficient balance (Error)
• 429 — The key's request budget is exhausted (300/min) — honour Retry-After (Error)

DELETE /v1/pi-aliases/{cle}

Remove an alias

Removes the alias from the directory. The account remains; it is the addressing that disappears.

ⓘ Family restricted to accounts with the “instant payment” product enabled; everyone else gets 403. Instant payment is the BCEAO's scheme, on which Mikaty SN SA is a participant.

Parameters

Name	In	Required	Description
cle	path	yes	The alias key.

Responses

• 204 — Removed
• 401 — API key missing or rejected (Error)
• 403 — The key does not carry the required scope, or the account is not active (Error)
• 429 — The key's request budget is exhausted (300/min) — honour Retry-After (Error)

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

Answer an alias claim

Somebody is claiming an alias you hold: this response accepts or refuses the transfer.

ⓘ Family restricted to accounts with the “instant payment” product enabled; everyone else gets 403. Instant payment is the BCEAO's scheme, on which Mikaty SN SA is a participant.

Parameters

Name	In	Required	Description
cle	path	yes	The claimed alias's key.

Request body

Field	Type	Required	Description
accept	boolean	yes	Accept the transfer, or refuse it.

Responses

• 200 — OK (PiAlias)
• 401 — API key missing or rejected (Error)
• 403 — The key does not carry the required scope, or the account is not active (Error)
• 429 — The key's request budget is exhausted (300/min) — honour Retry-After (Error)

POST /v1/qr

Issue an EMVCo QR

A static or dynamic QR in EMVCo format: the payer scans it with their app and pays.

ⓘ Family restricted to accounts with the “instant payment” product enabled; everyone else gets 403. Instant payment is the BCEAO's scheme, on which Mikaty SN SA is a participant.

Parameters

Name	In	Required	Description
Idempotency-Key	header	no	An idempotency key specific to THIS operation. Replaying the same key with the same payload returns the original; replaying it with a different payload is refused (409).

Request body

Field	Type	Required	Description
asset_id	integer	yes
amount_minor	string	no	Amount in MINOR UNITS, as a string. Never a floating-point number: both lose centimes. The asset's decimal count comes from GET /v1/assets.
client_ref	string	no
description	string	no

Responses

• 201 — QR issued (PiQr)
• 401 — API key missing or rejected (Error)
• 403 — The key does not carry the required scope, or the account is not active (Error)
• 409 — Idempotency key replayed with a different payload (Error)
• 422 — Well-formed but refused: missing field, closed corridor, insufficient balance (Error)
• 429 — The key's request budget is exhausted (300/min) — honour Retry-After (Error)

POST /v1/rtp

Request a payment (RTP)

A payment request addressed to a payer: they see it and confirm it at their end. Nothing is debited without their agreement.

ⓘ Family restricted to accounts with the “instant payment” product enabled; everyone else gets 403. Instant payment is the BCEAO's scheme, on which Mikaty SN SA is a participant.

Parameters

Name	In	Required	Description
Idempotency-Key	header	no	An idempotency key specific to THIS operation. Replaying the same key with the same payload returns the original; replaying it with a different payload is refused (409).

Request body

Field	Type	Required	Description
asset_id	integer	yes
amount_minor	string	yes	Amount in MINOR UNITS, as a string. Never a floating-point number: both lose centimes. The asset's decimal count comes from GET /v1/assets.
alias	string	yes	The payer's alias.
client_ref	string	no
description	string	no

Responses

• 201 — Request issued (Operation)
• 401 — API key missing or rejected (Error)
• 403 — The key does not carry the required scope, or the account is not active (Error)
• 409 — Idempotency key replayed with a different payload (Error)
• 422 — Well-formed but refused: missing field, closed corridor, insufficient balance (Error)
• 429 — The key's request budget is exhausted (300/min) — honour Retry-After (Error)

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

Answer a received request

Accept or refuse a payment request addressed to you.

ⓘ Family restricted to accounts with the “instant payment” product enabled; everyone else gets 403. Instant payment is the BCEAO's scheme, on which Mikaty SN SA is a participant.

Parameters

Name	In	Required	Description
end2endId	path	yes	The request's end-to-end identifier.

Request body

Field	Type	Required	Description
accept	boolean	yes

Responses

• 200 — OK (Operation)
• 401 — API key missing or rejected (Error)
• 403 — The key does not carry the required scope, or the account is not active (Error)
• 429 — The key's request budget is exhausted (300/min) — honour Retry-After (Error)

GET /v1/rtp/{id}

Retrieve a payment request

The state of the request and, once accepted, the operation that settles it.

ⓘ Family restricted to accounts with the “instant payment” product enabled; everyone else gets 403. Instant payment is the BCEAO's scheme, on which Mikaty SN SA is a participant.

Parameters

Name	In	Required	Description
id	path	yes	Internal identifier, the operation's reference, or your own client_ref.

Responses

• 200 — OK (Operation)
• 401 — API key missing or rejected (Error)
• 403 — The key does not carry the required scope, or the account is not active (Error)
• 429 — The key's request budget is exhausted (300/min) — honour Retry-After (Error)

Schemas

The shapes the operations above return.

PiClaim

Field	Type	Description
claim_id	string
alias	string
status	string

Error

Field	Type	Description
error	object
error.code	string
error.message	string

PiLookup

Field	Type	Description
alias	string
nom	string
participant	string

Operation

One money operation — collection, payout, refund, transfer or rebalance. The same object across all five families.

Field	Type	Description
id	string	The operation's public id. It is the one in the /v1/payments/{id} paths.
ref	string	Our internal, readable reference. Distinct from the id: quote this one to support.
client_ref	string	The reference you supplied at creation, returned unchanged.
kind	string	payin | payout | withdrawal | refund | chargeback | adjustment | transfer | rebalance. The same object serves all five families; this field says which.
status	string	The rail's detailed state. ⚠️ To decide whether the money arrived, read outcome: status carries journey detail and its vocabulary depends on the rail.
outcome	string	pending | succeeded | failed | cancelled | expired | reversed. The only field to base a business decision on.
asset_id	integer	The operation's asset, by its id (GET /v1/assets).
amount_minor	string	The GROSS amount in minor units, as a string.
fee_minor	string	The fee taken, in minor units.
net_minor	string	The net in minor units: amount_minor less fee_minor.
platform_id	integer	The platform that carried the operation. Absent while a hosted collection is still waiting for the payer to choose.
is_test	boolean	True for an operation created with a test key. No real money moves.
payment_url	string	The hosted payment page, when the rail provides one. Absent until submission has succeeded.
deeplink	string	The deep link into the rail's app, when it provides one.
qrcode_url	string	The QR to show the payer, when the rail provides one.
risk	Risk	The state of the risk check (FRAML). Absent when the operation was not assessed — which is not the same thing as “clear”. The outbound webhook and this read return the same block.
risk.status	string	held: the funds have not moved. review: the payment ran its course, something is being looked at. clear: nothing to report.
risk.case_ref	string	The operational case reference, to quote to support. Null when the hold is a compliance review.
risk.case_kind	string	Accompanies case_ref, or nothing at all.
risk.reason	string	The only free text this block carries, and it is identical for every hold.
risk.signals	object[]	Product signals, advisory. Absent when there are none.
risk.signals[].code	string
risk.signals[].detail_fr	string
amount_refunded_minor	string	Collections only: the sum of SUCCEEDED refunds, in minor units.
amount_refund_pending_minor	string	Collections only: the sum of refunds IN PROGRESS, in minor units.
amount_refundable_minor	string	Collections only: what can be refunded NOW, in minor units — the original amount less succeeded and in-progress refunds, or "0" when the refund rule allows none (collection not successful, Wave period passed after a partial refund…).
refund_count	integer	Collections only: the number of refunds that did not fail.
partial_refund_deadline	string	Wave collections only: until when a partial refund is possible (RFC 3339). Absent for other rails, or when Wave partial refunds are disabled.

PiAliasList

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

PiAlias

Field	Type	Description
cle	string
type	string
account_ref	string
status	string

PiQr

Field	Type	Description
payload	string	The EMVCo string to encode.
qrcode_url	string