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
string
required

The payment amount in local currency.

Example:

"1000"

​
sourceCurrency
enum<string>
required

Fiat currency sent onchain for payment settlement.

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

Stablecoin received by the recipient.

Available options:
USDC,
USDT
​
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:
MOMO,
BANK
​
reference
string
required

Wallet issuer's unique reference.

Example:

"csh-txn-20260506-001"

​
accountNumber
string

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

Example:

"+254712345678"

​
accountName
string

Recipient full name associated with the payment method. Required when paymentMethod is MOMO; optional otherwise.

Example:

"Jane Doe"

​
paymentCode
string

Required when paymentMethod is MOMO, OPAY. Available MOMO options: MPESA, MTN, AIRTEL, TIGO, ZAMTEL, HALOTEL, VODAFONE, VODACOM, ORANGE, MOOV, FREE. Available BANK options: OPAY.

​
email
string<email>

Customer's email address. Required when paymentMethod is BANK; optional otherwise.

Example:

"jane@example.com"

​
paymentIdentifier
string

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

​
customerId
string

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

Example:

"cus_01KXG3R0X8DXTKB849FFFEPT7Y"

Response

Payment accepted. The provider will collect fiat from the customer asynchronously. Listen for the payment.succeeded webhook for finality.

​
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.

​
depositInstruction
object | null

For bank payins that require the customer to transfer fiat into a provided account.