Skip to main content
POST
Set up a payout account — Step 2
This endpoint closes the 2-step payout account setup. After you created a withdrawal address in step 1, this creates a permanent fiat virtual account (e.g. a CLABE in Mexico) that lets your client deposit fiat to trigger an off-ramp settlement.
1

Step 1 — POST /v1/payout/accounts/setup/liquidation-address

Created the crypto withdrawal address for (beneficiaryId, beneficiaryAccountId, chain, currency).
2

Step 2 — POST /v1/payout/accounts/setup/virtual-account (this endpoint)

Returns the fiat virtual account (CLABE for SPEI, account number + routing for ACH, IBAN for SEPA) backed by the withdrawal address.
3

Operate — quote then execute

POST /v1/payout/accounts/quote to get the rate, then POST /v1/payout/accounts/execute to trigger settlement. Track via GET /v1/orders/{orderId}.

Prerequisites

  • The recipient exists (POST /v1/payout/recipients)
  • The recipient’s bank account is registered (POST /v1/payout/recipients/{id}/accounts)
  • Step 1 (withdrawal address) succeeded for this (beneficiaryId, beneficiaryAccountId) pair
If step 1 hasn’t run for this pair, this endpoint returns 400.

Request body

string
required
The recipient (from POST /v1/payout/recipients).
string
required
The recipient’s bank account ID. Must be the same pair you used in step 1.

Response

string
Internal virtual account ID. You don’t need to store it — call setup again to retrieve.
string
The 18-digit SPEI CLABE for Mexican fiat deposits. Share this with your client.
string
Fiat currency. Today: MXN (CLABE/SPEI). Other rails (ACH USD, SEPA EUR) will surface here as those go live.
string
Echo of the recipient.
This call is idempotent — calling it twice with the same (beneficiaryId, beneficiaryAccountId) returns the same CLABE. Don’t cache; just call setup before each payment if you want to be sure the account is current.

What happens after a deposit

When your client wires MXN to the returned CLABE:
  1. The fiat rails partner detects the deposit and credits the workspace’s float
  2. An on-chain transfer of equivalent stablecoin is initiated from the withdrawal address
  3. The stablecoin lands at the on-chain off-ramp partner, triggering the bank wire to the recipient
  4. An order is created in /v1/orders with status transitioning: awaiting_fundsfunds_receivedpayment_submittedcompleted
End-to-end settlement: typically 1–2 business days via SPEI.

Authentication

Authorization: ApiKey rk_client_key_v1_... — workspace key with payout module enabled and write scope.

Common errors

Next steps

After step 2 you’re operational. Recommended next reads:
  • POST /v1/payout/accounts/quote — get the exchange rate and fees for a payment
  • POST /v1/payout/accounts/execute — trigger settlement
  • GET /v1/orders/{orderId} — track the full timeline
  • Payout Kit Flow Guide — narrative end-to-end