Request a payout

POST

/gateway/payouts

• Shared development environment (test money only)

Required scope: payouts:write.

Test-money only. Reuse the same key after an uncertain response. No automatic write retry.

Authorizations

• apiKeyAuth

Parameters

Header Parameters

Idempotency-Key

required

string

>= 1 characters <= 128 characters

Request Body ^required

object

amount

required

string

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

settlement_method

Requested method; defaults from the saved merchant preference. Destinations come from the saved merchant profile.

string

Responses

200

Success

object

amount

string

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

created_at

string

currency

string

fill_id

string format: uuid

id

string format: uuid

message

required

string

replayed

boolean

settlement_method

required

string

settlements

Array<object>

object

status

required

string

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

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

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

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

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

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

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

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