Skip to main content

​
Overview

You can withdraw funds from a subaccount in two ways:
  1. Fiat Payouts: Convert currency balances to local currency (e.g., NGN, BRL, EUR) and send it to a bank account.
  2. Stablecoin Off-ramp: Withdraw USD as stablecoins (USDC/USDT) to an external crypto wallet.
This guide covers validating recipients, creating beneficiaries, and initiating withdrawals.

​
1. Validate Recipient Details (Fiat)

Endpoint: POST /v1/banking/{currency}/validate Before adding a recipient for fiat withdrawals, it is crucial to validate the account details. This ensures the account exists and prevents failed transactions or lost funds.
Always validate account numbers and bank codes before attempting to create a recipient.

​
Example: Validate NGN Account

curl -X POST "https://api.bullring.finance/v1/banking/ngn/validate" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "0062881117",
    "bankCode": "270"
  }'
Response: 
{
  "accountNumber": "0062881117",
  "bankCode": "270"
}
View API Reference

​
2. Create Recipient

Endpoint: POST /v1/ramp/{subaccountId}/banking/recipients Once validated, save the details as a recipient. This recipient id will be used to initiate withdrawals.

​
Example: Create NGN Recipient

curl -X POST "https://api.bullring.finance/v1/ramp/<SUBACCOUNT_ID>/banking/recipients" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "NGN",
    "account_number": "0062881117",
    "account_owner_name": "John Doe",
    "bank_code": "270",
    "bank_name": "Access Bank",
    "country": "NG"
  }'
Response: 
{
  "id": "f4725e12-466f-49fd-89bd-899635f3f7f6",
  "bank_name": "Access Bank",
  "account_owner_name": "John Doe",
  "last_4": "1117",
  "active": true,
  "account_id": "0062881117",
  "currency": "NGN"
}
View API Reference

​
3. Initiate Fiat Payout

Endpoint: POST /v1/ramp/{subaccountId}/banking/withdrawals Send funds from the subaccount to the created recipient. The system will deduct the appropriate currency balance from the subaccount.

​
Example: Withdraw to NGN Recipient

curl -X POST "https://api.bullring.finance/v1/ramp/<SUBACCOUNT_ID>/banking/withdrawals" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "0062881117",
    "amount": "50",
    "currency": "NGN"
  }'
Note: The amount field specifies the amount in the destination currency (e.g., NGN). The equivalent balance will be deducted from the subaccount’s currency holdings.
Response: 
{
  "id": "856b896f-3f16-4f70-952d-ce1f65b28aaa",
  "amount": "50",
  "currency": "NGN",
  "status": "pending",
  "created_at": "2025-11-21T15:59:09.341Z",
  "protocol": "wire",
  "fee_amount": "0.50",
  "fee_currency": "USD",
  "rate": 1500.00
}
View API Reference

​
4. Stablecoin Off-ramp (Crypto Withdrawal)

Endpoint: POST /v1/ramp/{subaccountId}/banking/withdrawals/stablecoin You can also withdraw balances directly as stablecoins (USDC or USDT) to an external wallet address.

​
Example: Withdraw USDT on Ethereum

curl -X POST "https://api.bullring.finance/v1/ramp/<SUBACCOUNT_ID>/banking/withdrawals/stablecoin" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100",
    "stablecoin": "usdt",
    "chain": "ethereum",
    "address": "0x22ccb74a200d7b8094b72482edd46e23cbf3af37"
  }'
Response: 
{
  "id": "acbad679-7fcf-44a5-be65-dfa27a824113",
  "amount": "100.00",
  "currency": "USD",
  "status": "pending",
  "chain": "ethereum",
  "local_currency": "usdt",
  "destinationAddress": "0x22ccb74a200d7b8094b72482edd46e23cbf3af37",
  "tx_hash": null
}
View API Reference

​
Common Mistakes

  1. Skipping Validation: Failing to validate bank account details often leads to failed withdrawals and unnecessary delays.
  2. Incorrect Network: When withdrawing stablecoins, ensure the chain matches the destination wallet (e.g., sending ERC-20 USDT to a TRC-20 address will result in loss of funds).
  3. Insufficient Balance: Ensure the subaccount has enough balance in the relevant currency to cover the withdrawal amount plus fees.
  4. Unverified subaccounts: Withdrawals are only permitted for subaccounts with approved verification.

​
Webhook Events

Listen to webhook events to track the status of your withdrawals in real-time.
  • withdrawal.status.completed: The funds have successfully reached the destination.
  • withdrawal.status.failed: The withdrawal could not be processed.
See Withdrawal Events for payload details.