> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bullring.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Beneficiaries, Payouts & Offramp

> Manage recipients, send fiat payouts, and off-ramp to stablecoins.

## Overview

You can withdraw funds from a subaccount in two ways:

1. **Fiat Payouts:** Convert currency balances to local currency (e.g., NGN, BRL, USD) 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.

<Note>
  Always validate account numbers and bank codes before attempting to create a recipient.
</Note>

### Example: Validate NGN Account

```bash theme={null}
curl -X POST "https://api.bullring.finance/v1/banking/ngn/validate" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "0062881117",
    "bankCode": "270"
  }'
```

[View API Reference](/api-reference/recipients/validate-ngn-recipient)

## 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.

For USD named withdrawal use cases, create a business recipient. Business recipients are identified by `business_name`. The fields `beneficiary_date_of_formation`, `beneficiary_country_of_formation`, and `beneficiary_national_identification_number` are optional for recipient creation, but required if the recipient will be used for named withdrawal flows.

### Example: Create USD Business Recipient for named withdrawal

```bash theme={null}
curl -X POST "https://api.bullring.finance/v1/ramp/<SUBACCOUNT_ID>/banking/recipients" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "bank_name": "JPMorgan Chase Bank",
    "account_number": "123456789012",
    "routing_number": "021000021",
    "account_type": "CHECKING",
    "business_name": "Recipient Company LLC",
    "email": "finance@recipient-company.com",
    "address": {
      "street_line_1": "123 Market St",
      "street_line_2": "Suite 400",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    },
    "beneficiary_date_of_formation": "2020-01-31",
    "beneficiary_country_of_formation": "US",
    "beneficiary_national_identification_number": "12-3456789"
  }'
```

### Example: Create NGN Recipient

```bash theme={null}
curl -X POST "https://api.bullring.finance/v1/ramp/<SUBACCOUNT_ID>/banking/recipients" \
  -H "x-api-key: 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"
  }'
```

[View API Reference](/api-reference/recipients/add-fiat-recipient)

## 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.

USD withdrawals can include `payment_rail` with `RTP`, `WIRE`, `SWIFT`, `SAME_DAY_ACH`, or `ACH`. Set `named_withdrawal` to `true` only for a USD named withdrawal. named withdrawal currently supports USD only, requires a business recipient identified by `business_name`, and requires the recipient to include `beneficiary_date_of_formation`, `beneficiary_country_of_formation`, and `beneficiary_national_identification_number`. named withdrawal supports only `WIRE` and `SWIFT`; `RTP`, `SAME_DAY_ACH`, and `ACH` remain supported only for non-named USD flows where applicable.

### Example: Normal USD ACH Withdrawal

```bash theme={null}
curl -X POST "https://api.bullring.finance/v1/ramp/<SUBACCOUNT_ID>/banking/withdrawals" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_id": "f556899a-eea7-4a18-b9e8-6346823a9b06",
    "amount": "100.00",
    "currency": "USD",
    "payment_rail": "ACH",
    "client_reference": "123e4567-e89b-12d3-a456-426614174000"
  }'
```

### Example: Normal USD RTP Withdrawal

```bash theme={null}
curl -X POST "https://api.bullring.finance/v1/ramp/<SUBACCOUNT_ID>/banking/withdrawals" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_id": "f556899a-eea7-4a18-b9e8-6346823a9b06",
    "amount": "100.00",
    "currency": "USD",
    "payment_rail": "RTP",
    "client_reference": "123e4567-e89b-12d3-a456-426614174001"
  }'
```

### Example: USD named withdrawal by WIRE

```bash theme={null}
curl -X POST "https://api.bullring.finance/v1/ramp/<SUBACCOUNT_ID>/banking/withdrawals" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_id": "RECIPIENT_ACCOUNT_UUID",
    "amount": "100.50",
    "currency": "USD",
    "payment_rail": "WIRE",
    "named_withdrawal": true,
    "origin_id": "unique-client-reference-001",
    "client_reference": "invoice-1001",
    "wire_message": "Payment for services"
  }'
```

### Example: USD named withdrawal by SWIFT

```bash theme={null}
curl -X POST "https://api.bullring.finance/v1/ramp/<SUBACCOUNT_ID>/banking/withdrawals" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_id": "RECIPIENT_ACCOUNT_UUID",
    "amount": "100.50",
    "currency": "USD",
    "payment_rail": "SWIFT",
    "named_withdrawal": true,
    "origin_id": "unique-client-reference-002",
    "client_reference": "invoice-1002",
    "wire_message": "Payment for services"
  }'
```

### Example: Withdraw to NGN Recipient

```bash theme={null}
curl -X POST "https://api.bullring.finance/v1/ramp/<SUBACCOUNT_ID>/banking/withdrawals" \
  -H "x-api-key: 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.

[View API Reference](/api-reference/withdrawals/withdraw-fiat)

## 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

```bash theme={null}
curl -X POST "https://api.bullring.finance/v1/ramp/<SUBACCOUNT_ID>/banking/withdrawals/stablecoin" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100",
    "stablecoin": "usdt",
    "chain": "ethereum",
    "address": "0x22ccb74a200d7b8094b72482edd46e23cbf3af37"
  }'
```

[View API Reference](/api-reference/withdrawals/withdraw-stablecoin)

## 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.
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](/en/withdrawal-events) for payload details.