Skip to content
BitMomo Developers
Test money only. BitMomo currently runs on test networks. Payments use testnet coins and no real money moves. Live keys are not available yet.

Create a payment

POST
/gateway/payments

Required scope: payments:write.

Merchant and money environment are bound to the key, never caller-selected. Only test money is currently enabled. Subscription routing is evaluated at event time.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
object
amount
required

Positive GHS amount, at most 8 fractional digits. Existing HTTP aliases amount_ghs/amount_fiat remain accepted.

string
/^-?[0-9]+(\.[0-9]+)?$/
callback_url

Optional registered active HTTPS destination. Omit to use all subscribed merchant endpoints. No subscription for a lifecycle event means no delivery of that event.

string format: uri
crypto_type
required

Asset selector for REQUEST payloads. Parsing is lenient: case-insensitive, _/- ignored, bare USDT means USDT_TRC20. Responses serialize the serde UPPERCASE form (no separators), see PaymentResponse.crypto_type.

string
Allowed values: BTC ETH USDT_TRC20 USDT_ERC20 USDC SOL SOL_USDC BNB MATIC BTC-LN BASE_ETH BASE_USDC ARB_ETH ARB_USDC ARB_USDT OP_ETH OP_USDC OP_USDT LINEA_ETH LINEA_USDC AVAX AVAX_USDC
customer_id
string format: uuid
description
string
<= 500 characters
fiat_currency
string
default: GHS
Allowed values: GHS
guest_session_id
string
idempotency_key

Persist one key per business intent and reuse it after uncertain responses. Changed intent under the same key returns 409.

string
>= 1 characters <= 255 characters /^[!-~]+$/
metadata

At most 4096 bytes and depth 3. Underscore, bitmomo_, cryptopos_, server_ prefixes and collect_rail are reserved.

object
<= 20 properties
order_id
string
<= 128 characters
redirect_url

Retained merchant terms; Bitmomo does not automatically navigate to this URL.

string format: uri
<= 2048 characters

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Success

object
amount_ghs
required

Decimal string (BigDecimal serializes as a string)

string
Example
100.00
chain_type
required

Lowercase chain label (see PayIntentResponse.network for the canonical {chain}:{testnet|mainnet} form).

string
Allowed values: bitcoin ethereum tron polygon solana bsc base lightning arbitrum optimism linea avalanche
created_at
required
string format: date-time
crypto_amount
required
string
Example
6.66666667
crypto_type
required

Serde UPPERCASE wire form (no separators).

string
Allowed values: BTC ETH USDTTRC20 USDTERC20 USDC SOL BNB MATIC BTCLN ARBETH ARBUSDC ARBUSDT OPETH OPUSDC OPUSDT BASEETH BASEUSDC SOLUSDC LINEAETH LINEAUSDC AVAX AVAXUSDC
deposit_address
required
string
environment
required
string
Example
test
expires_at
required
string format: date-time
expires_in_seconds
required
integer
id
required
string format: uuid
locked_rate
required
string
Example
15.00
merchant_id
required
string format: uuid
network
required

testnet or mainnet (from CRYPTO_NETWORK)

string
Example
testnet
qr_code_data
required
string
quote_id
required
string format: uuid
rate_expires_at
required
string format: date-time
rate_locked_at
required
string format: date-time
session_code
required
string
Example
PAY-A1B2C3D4
status
required

Snake_case lifecycle status. cancelled (explicit user/merchant cancel) is distinct from expired (time expiry).

string
Allowed values: created locked pending detected confirming confirmed settling completed expired failed flagged needs_review orphaned cancelled
token_contract

Null for native assets

string
token_decimals
required
integer
Example
6

400

Section titled “400 ”

Validation error

R15 canonical error envelope. Every 4xx/5xx JSON body carries these five keys, plus x-request-id header; 4xx machine fields (e.g. available_balance) merge in alongside and never shadow them.

object
error
required

Machine code (SCREAMING_SNAKE)

string
Example
VALIDATION_ERROR
message
required

Human-readable detail

string
Example
amount_ghs must be greater than zero
request_id
required

Mirrors the x-request-id response header

string format: uuid
retriable
required

True for 429/502/503/504 only; 400/401/403/404/409 are final

boolean
timestamp
required
string format: date-time

401

Section titled “401 ”

Invalid key

R15 canonical error envelope. Every 4xx/5xx JSON body carries these five keys, plus x-request-id header; 4xx machine fields (e.g. available_balance) merge in alongside and never shadow them.

object
error
required

Machine code (SCREAMING_SNAKE)

string
Example
VALIDATION_ERROR
message
required

Human-readable detail

string
Example
amount_ghs must be greater than zero
request_id
required

Mirrors the x-request-id response header

string format: uuid
retriable
required

True for 429/502/503/504 only; 400/401/403/404/409 are final

boolean
timestamp
required
string format: date-time

403

Section titled “403 ”

Scope, merchant or environment denied

R15 canonical error envelope. Every 4xx/5xx JSON body carries these five keys, plus x-request-id header; 4xx machine fields (e.g. available_balance) merge in alongside and never shadow them.

object
error
required

Machine code (SCREAMING_SNAKE)

string
Example
VALIDATION_ERROR
message
required

Human-readable detail

string
Example
amount_ghs must be greater than zero
request_id
required

Mirrors the x-request-id response header

string format: uuid
retriable
required

True for 429/502/503/504 only; 400/401/403/404/409 are final

boolean
timestamp
required
string format: date-time

404

Section titled “404 ”

Not found

R15 canonical error envelope. Every 4xx/5xx JSON body carries these five keys, plus x-request-id header; 4xx machine fields (e.g. available_balance) merge in alongside and never shadow them.

object
error
required

Machine code (SCREAMING_SNAKE)

string
Example
VALIDATION_ERROR
message
required

Human-readable detail

string
Example
amount_ghs must be greater than zero
request_id
required

Mirrors the x-request-id response header

string format: uuid
retriable
required

True for 429/502/503/504 only; 400/401/403/404/409 are final

boolean
timestamp
required
string format: date-time

409

Section titled “409 ”

Intent conflict

R15 canonical error envelope. Every 4xx/5xx JSON body carries these five keys, plus x-request-id header; 4xx machine fields (e.g. available_balance) merge in alongside and never shadow them.

object
error
required

Machine code (SCREAMING_SNAKE)

string
Example
VALIDATION_ERROR
message
required

Human-readable detail

string
Example
amount_ghs must be greater than zero
request_id
required

Mirrors the x-request-id response header

string format: uuid
retriable
required

True for 429/502/503/504 only; 400/401/403/404/409 are final

boolean
timestamp
required
string format: date-time

429

Section titled “429 ”

Rate limited

R15 canonical error envelope. Every 4xx/5xx JSON body carries these five keys, plus x-request-id header; 4xx machine fields (e.g. available_balance) merge in alongside and never shadow them.

object
error
required

Machine code (SCREAMING_SNAKE)

string
Example
VALIDATION_ERROR
message
required

Human-readable detail

string
Example
amount_ghs must be greater than zero
request_id
required

Mirrors the x-request-id response header

string format: uuid
retriable
required

True for 429/502/503/504 only; 400/401/403/404/409 are final

boolean
timestamp
required
string format: date-time

500

Section titled “500 ”

Internal error

R15 canonical error envelope. Every 4xx/5xx JSON body carries these five keys, plus x-request-id header; 4xx machine fields (e.g. available_balance) merge in alongside and never shadow them.

object
error
required

Machine code (SCREAMING_SNAKE)

string
Example
VALIDATION_ERROR
message
required

Human-readable detail

string
Example
amount_ghs must be greater than zero
request_id
required

Mirrors the x-request-id response header

string format: uuid
retriable
required

True for 429/502/503/504 only; 400/401/403/404/409 are final

boolean
timestamp
required
string format: date-time

503

Section titled “503 ”

Service unavailable

R15 canonical error envelope. Every 4xx/5xx JSON body carries these five keys, plus x-request-id header; 4xx machine fields (e.g. available_balance) merge in alongside and never shadow them.

object
error
required

Machine code (SCREAMING_SNAKE)

string
Example
VALIDATION_ERROR
message
required

Human-readable detail

string
Example
amount_ghs must be greater than zero
request_id
required

Mirrors the x-request-id response header

string format: uuid
retriable
required

True for 429/502/503/504 only; 400/401/403/404/409 are final

boolean
timestamp
required
string format: date-time