Skip to main content
POST

Authorizations

​
Authorization
string
header
required

Stablepay API key. Include as Authorization: Bearer <key>.

Headers

​
Idempotency-Key
string
required

Client-generated UUID. Required to prevent duplicate payments.

Body

application/json
​
fiatAmount
number
required

The payment amount in local currency.

Example:

1350

​
sourceCurrency
enum<string>
required

Stablecoin sent onchain for payment settlement.

Available options:
USDC,
USDT
​
destinationCurrency
enum<string>
required

Fiat currency received by the recipient.

Available options:
CDF,
GHS,
KES,
NGN,
TZS,
UGX,
XAF,
XOF,
ZAR,
ZMW
​
country
enum<string>
required

Recipient country code.

Available options:
BF,
BJ,
CD,
CI,
CM,
GH,
KE,
NG,
SN,
TZ,
UG,
ZA,
ZM
​
blockchain
enum<string>
required

Supported blockchains for onchain settlement.

Available options:
BSC,
SOLANA
​
paymentMethod
enum<string>
required

The supported payment method used to deliver funds to the recipient.

Available options:
BANK,
MOMO,
PAYBILL,
TILL
​
accountName
string
required

Recipient full name associated with the payment method.

Example:

"Jane Doe"

​
accountNumber
string
required

The account number of the payment method. Must be in E.164 format with the + prefix when paymentMethod is MOMO.

Example:

"+254712345678"

​
paymentCode
string
required

Available MNO options: MPESA, MTN, AIRTEL, TIGO, ZAMTEL, HALOTEL, VODAFONE, VODACOM, ORANGE, MOOV, FREE, TIPS. Available BANK options: OPAY, BANKCODE.

​
reference
string
required

Wallet issuer's unique reference.

Example:

"csh-txn-20260506-001"

​
paymentIdentifier
string

A method-specific identifier required for processing the payment. Examples include BVN (BANK) Paybill business number (PAYBILL), or other market specific references.

Example:

"123456"

​
customerId
string

The customer this payment is for. Required when KYC is enabled for your account.

Example:

"cus_01KXG3R0X8DXTKB849FFFEPT7Y"

Response

Payment accepted. Processing is async. Poll or await webhook.

​
paymentId
string
required

Use this ID to track the payment status.

Example:

"pay_01HV8KZMRJPQR9S7T3XABCDEF"

​
status
string
required
Example:

"provider_accepted"

​
createdAt
string<date-time>
required
​
providerRef
string | null

Provider's internal transaction ID.