Skip to main content
POST
Create Payout Destination

Authorizations

Authorization
string
header
required

Bearer token authentication. Pass your API key as Authorization: Bearer sk_.... See Authentication for keys, scopes, and sandbox vs production.

Body

application/json

Register where money should land. Accepts both the field names this surface has always used and newer aliases, so a caller never has to know which generation of the API it is talking to. Where a legacy name and its alias overlap, the newer name wins.

currency
string
required

Currency code this destination accepts (e.g., 'NGN', 'USD', 'USDT_TRC20').

Maximum string length: 10
Example:

"NGN"

name
string | null

User-friendly name for this destination.

Maximum string length: 255
Example:

"My GTBank Savings"

label
string | null

Alias for name. name wins if both are sent.

Maximum string length: 255
Example:

null

type
string | null

Type of payout destination: bank_account, mobile_money, or crypto_wallet. Inferred from currency when omitted.

Example:

"bank_account"

destination_type
string | null

Alias for type. type wins if both are sent.

Example:

null

account_number
string | null

Bank account number. Required for bank_account destinations.

Maximum string length: 50
Example:

"0123456789"

bank_code
string | null

Bank code or routing number. Required for bank_account destinations.

Maximum string length: 20
Example:

"058"

account_name
string | null

Accepted for compatibility and ignored, because the account holder name is always resolved from the bank.

Maximum string length: 255
Example:

null

bank_name
string | null

Accepted for compatibility and ignored, because the bank name is always resolved from the bank.

Maximum string length: 255
Example:

null

phone_number
string | null

Phone number for the mobile money account. Required for mobile_money destinations.

Maximum string length: 20
Example:

null

mobile_provider
string | null

Mobile money provider (e.g., 'MTN', 'Vodafone'). Required for mobile_money destinations.

Maximum string length: 50
Example:

null

wallet_address
string | null

Cryptocurrency wallet address. Required for crypto_wallet destinations.

Maximum string length: 255
Example:

null

network
string | null

Blockchain network. Optional when the currency already names its network (e.g. USDT_TRC20).

Maximum string length: 50
Example:

null

metadata
object | null

Additional custom metadata to associate with this destination.

Example:

null

Response

Success

Response containing payout destination details (bank account, mobile money, or crypto wallet).

id
string
required

Unique identifier for this payout destination. Use this ID when creating payouts.

Example:

"pd_7Kq2mNv4XbR9dLc0"

name
string
required

User-friendly name for this destination. Helps you identify destinations in your system.

Example:

"My GTBank Savings"

type
enum<string>
required

Type of payout destination: bank_account, mobile_money, or crypto_wallet. Determines which fields are populated.

Available options:
bank_account,
mobile_money,
crypto_wallet
Example:

"bank_account"

currency
string
required

Currency code this destination accepts (e.g., 'NGN', 'USD', 'USDT_TRC20'). Payouts to this destination must use this currency.

Example:

"NGN"

status
enum<string>
required

Review status. pending_review: awaiting review, not usable yet. approved: cleared for payouts. rejected: permanently unusable, register a new destination instead.

Available options:
pending_review,
approved,
rejected
Example:

"approved"

status_reason
string | null

Free-text reason set by review, populated when the destination is rejected. Null while pending or approved.

Example:

null

is_usable
boolean

Whether this destination can be used for a payout right now. True only when status is approved and the destination has not been deactivated.

Example:

true

is_default
boolean

Whether a payout schedule pays out to this destination for its currency. Set it with PATCH /v1/payouts/destinations/{destination_id}.

Example:

false

account_number
string | null

Bank account number. Only populated for bank_account destinations.

Example:

"0123456789"

account_name
string | null

Account holder name as resolved from the bank. Only populated for bank_account destinations.

Example:

"JOHN DOE"

bank_code
string | null

Bank code or routing number. Only populated for bank_account destinations.

Example:

"058"

bank_name
string | null

Full name of the bank. Only populated for bank_account destinations.

Example:

"Guaranty Trust Bank"

phone_number
string | null

Phone number associated with the mobile money account. Only populated for mobile_money destinations.

Example:

null

mobile_provider
string | null

Mobile money provider (e.g., 'MTN', 'Vodafone'). Only populated for mobile_money destinations.

Example:

null

wallet_address
string | null

Cryptocurrency wallet address. Only populated for crypto_wallet destinations.

Example:

null

network
string | null

Blockchain network (e.g., 'TRC20', 'ERC20'). Only populated for crypto_wallet destinations. May be included in currency code (e.g., 'USDT_TRC20').

Example:

null

reviewed_at
string<date-time> | null

ISO 8601 timestamp when this destination was last reviewed by an admin. Null until reviewed.

Example:

null

created_at
string<date-time> | null

ISO 8601 timestamp when this destination was created.

Example:

"2026-01-24T14:30:00.000Z"

updated_at
string<date-time> | null

ISO 8601 timestamp when this destination was last updated.

Example:

"2026-01-24T14:30:00.000Z"