Merchant payouts

A Payout transfers an available merchant balance to an external address on one exact chain and currency. Creation validates the enabled token, minimum payout, destination format, available balance and fee, then reserves the full debit while Chain Service submits the transfer.

Payout execution is asynchronous. A creation response does not prove blockchain settlement.

API Endpoints

Create Payout: Creates a new payout request to a specified destination address.
Get Payout: Retrieves details of a specific payout by its ID.
List Payouts: Returns a paginated list of payouts.

API Endpoint Reference

Method	Endpoint	Description
POST	`/api/v1/payouts`	Creates a new payout to a destination address.
GET	`/api/v1/payouts/:id`	Retrieves details of a specific payout.
GET	`/api/v1/payouts?offset=0&limit=10`	Lists payouts with pagination.

Attributes

Attribute	Type	Description
`id`	string	Unique identifier for the payout (e.g., `pout_t24cg6MLdv1PgUiO`).
`account_id`	string	ID of the account associated with the payout.
`chain`	string	Blockchain chain used (e.g., `base`).
`amount`	string	Total amount to be paid out (e.g., `5.0`).
`currency`	string	Currency of the transaction (e.g., `USDC`).
`destination_address`	string	Destination address for the payout (e.g., `0xB3906750209897ee480AcfA6cE64538ED0dB5A42`).
`metadata`	object or null	Additional metadata, if provided.
`status`	string	Current status of the payout (e.g., `pending`).
`tx_hash`	string or null	Transaction hash, if available.
`error_message`	string or null	Error message, if the payout failed.
`created_at`	timestamp	Time when the payout was created.
`updated_at`	timestamp	Time when the payout was last updated.

Retrieving one Payout also returns its public token, the related balance_transaction when one has been posted, and an activities array for creation, settlement or failure diagnostics. List and create responses return the compact Payout shape.

Statuses

pending: funds are reserved and processing is in progress;
succeeded: Chain Service finalized the payout; and
failed: submission or settlement failed and the terminal state is recorded.

Use signed payout.* webhooks or authenticated retrieval for final state. Never treat the presence of a transaction hash alone as your business fulfillment signal.