Payouts Overview

Payouts move funds from your BoomFi virtual account balance to an external account you’ve registered — a crypto wallet or a bank account. See Whitelist External Account to register a destination first.

Prerequisites

Funded Virtual Accounts
A registered, enabled external account to pay out to
Authentication (X-API-KEY, X-API-Nonce, X-API-Signature)

Because whitelisting the destination is the step-up-protected step, creating the payout itself needs no per-request OTP — it can be called by an API key alone.

Create a payout (API)

Address the destination by the id or reference you registered it with. The currency decides the rail: a fiat symbol settles to the destination’s bank account, a digital one to its wallet (and requires chain_id).

curl -X POST "https://mapi.boomfi.xyz/v1/accounts/virtual/payout" \
  -H "X-API-KEY: sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "X-API-Nonce: nonce-unique-1" \
  -H "X-API-Signature: <hmac-hex>" \
  -d '{
    "destination_account_reference": "treasury-base",
    "currency": "USDC",
    "chain_id": 8453,
    "amount": "10.00"
  }'

Field	Type	Required	Description
`destination_account_id` / `destination_account_reference`		exactly one	The registered external account to pay
`account_id` / `account_reference`		no	Which virtual (sub-)account to pay out from; defaults to the org’s primary virtual account
`amount`	string	yes	Amount in major units
`currency`	string	yes	Fiat symbol takes the bank rail, digital takes the chain rail
`chain_id`	number	required for digital	Must be omitted for fiat
`token_address`	string	no	Only needed when the symbol maps to several tokens on the chain
`reference`	string	no	Your own reference for this payout; must be unique
`metadata`	object	no	Caller metadata returned on the payment record (max 2 KiB)

Use the request schema from the API reference (CreateVirtualPayoutRequest) for exact fields.

Direct wallet payout (no whitelisting)

For a one-off crypto send where you don’t want to register a destination first, POST /accounts/virtual/payout/address still pays out directly to a wallet address:

curl -X POST "https://mapi.boomfi.xyz/v1/accounts/virtual/payout/address" \
  -H "X-API-KEY: sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "X-API-Nonce: nonce-unique-1" \
  -H "X-API-Signature: <hmac-hex>" \
  -d '{
    "wallet_address": "0xRecipientWallet…",
    "chain_id": 8453,
    "ccy": "USDC",
    "amount": "10.00"
  }'

This path is digital-only and has no equivalent for fiat: use the whitelisted flow above for a bank payout, or for any destination you’ll pay repeatedly.

Dashboard

Use the Account experience (https://app.boomfi.xyz/dashboard/account) for payout controls in the merchant UI.

Events and monitoring

Track resulting payments/transactions in the dashboard and via webhooks. Failed webhook delivery does not reverse an on-chain payout: reconcile carefully.

Get Started

Dashboard

Settlement

Payments

Deposit Accounts

External Account

Webhooks

Payouts

Integrations

Pricing and Policies

Payouts Overview

Prerequisites

Create a payout (API)

Direct wallet payout (no whitelisting)

Dashboard

Events and monitoring

​Prerequisites

​Create a payout (API)

​Direct wallet payout (no whitelisting)

​Dashboard

​Events and monitoring

Prerequisites

Create a payout (API)

Direct wallet payout (no whitelisting)

Dashboard

Events and monitoring