Cookbook: Deposit, convert, and withdraw fiat

Onboard merchants and use the APIs for account management, deposits, swaps, and fiat withdrawals.

End-to-end flow

1. Merchant onboarding

Create a merchant organisation:

POST https://mapi.zbx.boomfi.xyz/v1/partners/orgs

Example response:

{
  "data": {
    "org_id": "3IDieTi1aMaCafUfmlotbHyDeSP",
    "name": "Demo-1",
    "partner_id": "2pWs0DuVESI5B1fnQWj1eXe5YIC",
    "owner": {
      "user_id": "3IDieT0UeHHhX48vEk10UFzIdvy",
      "email": "ops-1@acme.example",
      "name": "Acme Ops",
      "phone": "+4915112345678"
    },
    "kyc_status": "pending",
    "verification_url": "https://in.sumsub.com/websdk/p/...",
    "created_at": "2026-08-21T09:47:14Z"
  }
}

The merchant must open verification_url and complete KYC. Check the onboarding status using:

GET https://mapi.zbx.boomfi.xyz/v1/partners/orgs/{orgId}

Once ZBX receives the KYC approval update, the merchant’s fiat and crypto accounts are provisioned automatically. You do not need to call another provisioning endpoint.

2. Authentication

Signed merchant requests use these headers:

X-API-KEY: <API_KEY>
X-Api-Nonce: <NONCE>
X-Api-Signature: <HMAC_SIGNATURE>

Calculate the signature using SIGNING_SECRET. Use the partner credentials for /partners/orgs. After onboarding, use the new merchant organisation’s credentials for account, deposit, swap, and withdrawal requests. ZBX will provide test credentials separately. Credentials must not be committed to source control or shared through an unsecured channel. Retrieve the signing secret when credentials are first configured or after the secret is rotated:

GET https://mapi.zbx.boomfi.xyz/v1/orgs/signing-secret

This request is authenticated with the organisation API key. Do not sign it: the signing secret is not available yet.

Test environment

A test organisation can be prepared with the required fiat and crypto accounts and API credentials. Use the provided API_KEY and SIGNING_SECRET to test the account, balance, deposit-address, swap, and withdrawal APIs. The organisation onboarding and KYC steps are included separately to demonstrate how you onboard new merchants.

API overview

Request	Endpoint	Purpose
Get Signing Secret	`GET /orgs/signing-secret`	Retrieve the secret used to sign merchant API requests.
Create Org	`POST /partners/orgs`	Create a merchant organisation and start onboarding.
Get Org	`GET /partners/orgs/{orgId}`	Read the organisation and KYC status.
Get Account	`GET /accounts/virtual`	Return the virtual account and its fiat and crypto subaccounts. Use the subaccount IDs in swap requests.
Get Balances	`GET /accounts/virtual/balances`	Return current balances for the organisation’s accounts.
List Account Movements	`GET /accounts/{accountId}/movement`	Return incoming and outgoing movements for an account and its subaccounts.
Get Payment Detail	`GET /payments/{paymentId}`	Read the latest payment status and next action.
Get Deposit Address	`POST /accounts/virtual/payin/address`	Create or return a permanent crypto deposit address for a customer reference and chain.
Request Quote	`GET /trade/quote`	Request an RFQ for a crypto-to-fiat or fiat-to-crypto swap.
Accept Quote	`POST /trade/quote/{quoteId}/accept`	Accept and execute an unexpired RFQ quote.
Whitelist External Bank Account	`POST /accounts/external-account`	Register an external EUR bank beneficiary.
Withdraw Fiat	`POST /accounts/virtual/payout`	Withdraw EUR from the fiat account to a registered beneficiary.
Cancel Withdraw Fiat	`POST /accounts/virtual/payout/{paymentId}/cancel`	Request cancellation of an eligible withdrawal.

Paths are relative to https://mapi.zbx.boomfi.xyz/v1.

3. Accounts and balances

Use these requests to inspect the merchant’s account structure:

GET https://mapi.zbx.boomfi.xyz/v1/accounts/virtual
GET https://mapi.zbx.boomfi.xyz/v1/accounts/virtual/balances
GET https://mapi.zbx.boomfi.xyz/v1/accounts/{accountId}/movement

Get Account returns the virtual account and its fiat and crypto accounts.
Get Balances returns their current balances.
List Account Movements returns incoming and outgoing movements for the selected account and its subaccounts, including deposits, swaps, and withdrawals.

Do not reuse example account IDs for another organisation. Obtain the correct IDs from GET /accounts/virtual.

4. Crypto deposits

Create or retrieve a permanent crypto deposit address:

POST https://mapi.zbx.boomfi.xyz/v1/accounts/virtual/payin/address

The address is permanent for the same customer reference and parent account. Repeating the request returns the existing address instead of creating a new one. The customer sends funds to the address returned by the API. After confirmation, ZBX sweeps the received asset to the corresponding parent crypto account. The deposit network and asset must be supported by the returned address and its parent account.

The complete on-chain deposit flow depends on sandbox network and test-token support. Confirm the supported network and token before testing.

5. Asset swaps

Both directions are included:

Crypto to fiat
Fiat to crypto

The RFQ must be accepted within 10 seconds. If it expires before acceptance, no order is created and you must request a new RFQ. After acceptance, ZBX fetches a fresh executable quote and validates it against the committed amount. If the price is outside the allowed tolerance, ZBX automatically requests another executable quote. The order is marked as Rejected only when the swap cannot be completed after all retry attempts. Use account IDs returned by the account API:

deposit_account_id: account holding the asset being sold.
settlement_account_id: account receiving the purchased asset.

6. Fiat withdrawal

First, whitelist the beneficiary’s external bank account:

POST https://mapi.zbx.boomfi.xyz/v1/accounts/external-account

Then create the EUR withdrawal:

POST https://mapi.zbx.boomfi.xyz/v1/accounts/virtual/payout

If Travel Rule information is required, the withdrawal is placed on hold. Retrieve the withdrawal details using the returned paymentId:

GET https://mapi.zbx.boomfi.xyz/v1/payments/{paymentId}

The payment detail returns the Travel Rule action in this format:

{
  "next_action": "travel_rule:https://example.zbx/travel-rule/..."
}

Use the URL after the travel_rule: prefix to open the form and provide the requested information. After the information is submitted and accepted, processing can continue. Call the payment-detail endpoint again to obtain the latest status. To cancel an eligible withdrawal:

POST https://mapi.zbx.boomfi.xyz/v1/accounts/virtual/payout/{paymentId}/cancel

Use the payment ID returned by the withdrawal API. A withdrawal can only be cancelled while it remains in a cancellable state.

Request values

Configure these values before you run the flow:

Variable	Purpose
Merchant API URL	`https://mapi.zbx.boomfi.xyz/v1`
`API_KEY`	API key for the current organisation
`SIGNING_SECRET`	Secret used to sign requests
`orgId`	Organisation created during onboarding
`accountId`	Account returned by the account API
`quoteId`	RFQ quote returned by the quote API
`paymentId`	Payment ID returned by a payment or withdrawal API

IDs that appear in examples are test values. Replace them with values returned by earlier requests.

Get Started

Dashboard

Settlement

Payments

Deposit Accounts

Trading

Webhooks

Integrations

Pricing and Policies

Cookbook: Deposit, convert, and withdraw fiat

End-to-end flow

1. Merchant onboarding

2. Authentication

Test environment

API overview

3. Accounts and balances

4. Crypto deposits

5. Asset swaps

6. Fiat withdrawal

Request values

​End-to-end flow

​1. Merchant onboarding

​2. Authentication

​Test environment

​API overview

​3. Accounts and balances

​4. Crypto deposits

​5. Asset swaps

​6. Fiat withdrawal

​Request values

End-to-end flow

1. Merchant onboarding

2. Authentication

Test environment

API overview

3. Accounts and balances

4. Crypto deposits

5. Asset swaps

6. Fiat withdrawal

Request values