Skip to main content
POST
/
v1
/
payout
/
accounts
/
setup
/
virtual-account
Set up a payout account — Step 2
curl --request POST \
  --url https://api.example.com/v1/payout/accounts/setup/virtual-account \
  --header 'Content-Type: application/json' \
  --data '
{
  "beneficiaryId": "<string>",
  "beneficiaryAccountId": "<string>"
}
'
{
  "id": "<string>",
  "clabe": "<string>",
  "currency": "<string>",
  "beneficiaryId": "<string>"
}
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

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

​
Response

​
id
string
Internal virtual account ID. You don’t need to store it — call setup again to retrieve.
​
clabe
string
The 18-digit SPEI CLABE for Mexican fiat deposits. Share this with your client.
​
currency
string
Fiat currency. Today: MXN (CLABE/SPEI). Other rails (ACH USD, SEPA EUR) will surface here as those go live.
​
beneficiaryId
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_funds → funds_received → payment_submitted → completed
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

StatusCauseFix
400No withdrawal address exists for the (beneficiaryId, beneficiaryAccountId) pairRun step 1 (/setup/liquidation-address) first
403Workspace lacks payout module or write scopeActivate Payout Kit in dashboard; check API key scope
404beneficiaryId or beneficiaryAccountId not foundCross-tenant lookups return 404 (no existence leak)
422Recipient’s bank account is not yet usable (pending rails partner approval)Wait for the registration to confirm; retry

​
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