Skip to main content
POST
/
v1
/
payments
/
moneyout
curl --request POST \
  --url https://stablepay-money-api-production.up.railway.app/v1/payments/moneyout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "fiatAmount": 1350,
  "sourceCurrency": "USDC",
  "destinationCurrency": "KES",
  "country": "KE",
  "blockchain": "BSC",
  "paymentMethod": "MOMO",
  "accountName": "Jane Doe",
  "accountNumber": "254712345678",
  "paymentCode": "MPESA",
  "reference": "csh-txn-20260506-001",
  "refundAddress": "0xAbCd1234AbCd1234AbCd1234AbCd1234AbCd1234",
  "optionalIssuerFee": "NO"
}
'
{
  "id": "pay_01HV8KZMRJPQR9S7T3XABCDEF",
  "status": "<string>",
  "amountStablecoin": "10.500000",
  "fiatAmount": "1350.000000",
  "providerRef": "CC4SOjQu8UUarKaOGZy9",
  "reference": "csh-txn-20260506-001",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

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:
GHS,
KES,
NGN,
TZS,
UGX,
XAF,
XOF,
ZAR,
ZMW
​
country
enum<string>
required

Recipient country code.

Available options:
BF,
BJ,
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

Recipient phone number or account number.

Example:

"254712345678"

​
paymentCode
string
required

Mobile network operator or bank code. Available MNO options: MPESA, MTN, AIRTEL, TIGO, TELEBIRR, CBE, ZAMTEL. Available bank options: OPAY, PALMPAY, MONIEPOINT.

​
reference
string
required

Wallet issuer's unique reference.

Example:

"csh-txn-20260506-001"

​
refundAddress
string
required

Onchain address to return funds to if the payout fails.

Example:

"7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"

​
optionalIssuerFee
enum<string>
required
Available options:
YES,
NO
Example:

"NO"

​
businessNumber
string

Only required for PAYBILL: M-Pesa Paybill business number (6 digits).

Example:

"123456"

Response

Payment accepted. Processing is async — poll or await webhook.

​
id
string
required

Prefixed ULID for this payment.

Example:

"pay_01HV8KZMRJPQR9S7T3XABCDEF"

​
status
string
required

Current state of the payment in the state machine. initiated → provider_accepted → succeeded | failed | refunded

​
paymentMethod
enum<string>
required

How the recipient receives funds.

Available options:
BANK,
MOMO,
PAYBILL,
TILL
​
sourceCurrency
enum<string>
required

Stablecoin sent onchain for payment settlement.

Available options:
USDC,
USDT
​
amountStablecoin
string
required

Total stablecoin amount charged.

Example:

"10.500000"

​
fiatAmount
string
required

Fiat amount the recipient receives.

Example:

"1350.000000"

​
destinationCurrency
enum<string>
required

Fiat currency received by the recipient.

Available options:
GHS,
KES,
NGN,
TZS,
UGX,
XAF,
XOF,
ZAR,
ZMW
​
providerRef
string | null
required

Provider's transaction ID. Null until the provider accepts.

Example:

"CC4SOjQu8UUarKaOGZy9"

​
reference
string | null
required

Caller's own reference code (e.g. "csh-txn-20260506-001"). Stored as supplied in the payment request.

Example:

"csh-txn-20260506-001"

​
createdAt
string<date-time>
required
​
updatedAt
string<date-time>
required