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

# Beneficiários, Pagamentos e Offramp

> Gerencie destinatários, envie pagamentos fiat e faça off-ramp para stablecoins.

## Visão Geral

Você pode sacar fundos de uma subconta de duas formas:

1. **Pagamentos Fiat:** Converta saldos de moedas para moeda local (ex.: NGN, BRL, EUR) e envie para uma conta bancária.
2. **Off-ramp para Stablecoin:** Saque USD como stablecoins (USDC/USDT) para uma carteira cripto externa.

Este guia cobre a validação de destinatários, criação de beneficiários e iniciação de saques.

## 1. Validar Detalhes do Destinatário (Fiat)

**Endpoint:** `POST /v1/banking/{currency}/validate`

Antes de adicionar um destinatário para saques fiat, é **crucial** validar os detalhes da conta. Isso garante que a conta existe e previne transações falhas ou fundos perdidos.

<Note>
  Sempre valide os números de conta e códigos bancários antes de tentar criar um destinatário.
</Note>

### Exemplo: Validar Conta NGN

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

**Resposta:**

```json theme={null}
{
  "accountNumber": "0062881117",
  "bankCode": "270"
}
```

[Ver Referência da API](/api-reference/recipients/validate-ngn-recipient)

## 2. Criar Destinatário

**Endpoint:** `POST /v1/ramp/{subaccountId}/banking/recipients`

Uma vez validado, salve os detalhes como um destinatário. Este `id` de destinatário será usado para iniciar saques.

### Exemplo: Criar Destinatário NGN

```bash theme={null}
curl -X POST "https://api.bullring.finance/v1/ramp/<ID_DA_SUBCONTA>/banking/recipients" \
  -H "Authorization: Bearer <SUA_CHAVE_DE_API>" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "NGN",
    "account_number": "0062881117",
    "account_owner_name": "João Silva",
    "bank_code": "270",
    "bank_name": "Access Bank",
    "country": "NG"
  }'
```

**Resposta:**

```json theme={null}
{
  "id": "f4725e12-466f-49fd-89bd-899635f3f7f6",
  "bank_name": "Access Bank",
  "account_owner_name": "João Silva",
  "last_4": "1117",
  "active": true,
  "account_id": "0062881117",
  "currency": "NGN"
}
```

[Ver Referência da API](/api-reference/recipients/add-fiat-recipient)

## 3. Iniciar Pagamento Fiat

**Endpoint:** `POST /v1/ramp/{subaccountId}/banking/withdrawals`

Envie fundos da subconta para o destinatário criado. O sistema deduzirá o saldo apropriado de moeda da subconta.

### Exemplo: Sacar para Destinatário NGN

```bash theme={null}
curl -X POST "https://api.bullring.finance/v1/ramp/<ID_DA_SUBCONTA>/banking/withdrawals" \
  -H "Authorization: Bearer <SUA_CHAVE_DE_API>" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "0062881117",
    "amount": "50",
    "currency": "NGN"
  }'
```

> **Nota:** O campo `amount` especifica o valor na **moeda de destino** (ex.: NGN). O saldo equivalente será deduzido das participações em moeda da subconta.

**Resposta:**

```json theme={null}
{
  "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
}
```

[Ver Referência da API](/api-reference/withdrawals/withdraw-fiat)

## 4. Off-ramp para Stablecoin (Saque Cripto)

**Endpoint:** `POST /v1/ramp/{subaccountId}/banking/withdrawals/stablecoin`

Você também pode sacar saldos diretamente como stablecoins (USDC ou USDT) para um endereço de carteira externo.

### Exemplo: Sacar USDT na Ethereum

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

**Resposta:**

```json theme={null}
{
  "id": "acbad679-7fcf-44a5-be65-dfa27a824113",
  "amount": "100.00",
  "currency": "USD",
  "status": "pending",
  "chain": "ethereum",
  "local_currency": "usdt",
  "destinationAddress": "0x22ccb74a200d7b8094b72482edd46e23cbf3af37",
  "tx_hash": null
}
```

[Ver Referência da API](/api-reference/withdrawals/withdraw-stablecoin)

## Erros Comuns

1. **Pular Validação:** Não validar os detalhes da conta bancária frequentemente leva a saques falhos e atrasos desnecessários.
2. **Rede Incorreta:** Ao sacar stablecoins, certifique-se de que a `chain` corresponde à carteira de destino (ex.: enviar USDT ERC-20 para um endereço TRC-20 resultará em perda de fundos).
3. **Saldo Insuficiente:** Certifique-se de que a subconta tem saldo suficiente na moeda relevante para cobrir o valor do saque **mais as taxas**.
4. **Subcontas não verificadas:** Saques são permitidos apenas para subcontas com verificação aprovada.

## Eventos de Webhook

Escute os eventos de webhook para acompanhar o status dos seus saques em tempo real.

* `withdrawal.status.completed`: Os fundos chegaram com sucesso ao destino.
* `withdrawal.status.failed`: O saque não pôde ser processado.

Veja [Eventos de Saque](/pt/withdrawal-events) para detalhes do payload.