Beneficiários, Pagamentos e Offramp

Visão Geral

Você pode sacar fundos de uma subconta como pagamentos fiat para contas bancárias ou como stablecoins para carteiras externas. Este guia cobre validação, criação de destinatários e saques.

1. Validar Detalhes do Destinatário

Endpoint: POST /v1/banking/{currency}/validate Valide dados bancários antes de criar um destinatário para reduzir falhas de saque.

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"
  }'

2. Criar Destinatário

Endpoint: POST /v1/ramp/{subaccountId}/banking/recipients Após a validação, salve os dados como destinatário. O id do destinatário será usado para iniciar saques. Para casos de USD named withdrawal, crie um destinatário empresarial. Destinatários empresariais são identificados por business_name. Os campos beneficiary_date_of_formation, beneficiary_country_of_formation e beneficiary_national_identification_number são opcionais na criação, mas obrigatórios se o destinatário for usado em fluxos de named withdrawal.

Exemplo: Criar Destinatário Empresarial USD para named withdrawal

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": "[email protected]",
    "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"
  }'

3. Iniciar Pagamento Fiat

Endpoint: POST /v1/ramp/{subaccountId}/banking/withdrawals Saques USD podem incluir payment_rail com RTP, WIRE, SWIFT, SAME_DAY_ACH ou ACH. Defina named_withdrawal como true apenas para USD named withdrawal. named withdrawal atualmente suporta apenas USD, exige destinatário empresarial identificado por business_name e exige que o destinatário inclua beneficiary_date_of_formation, beneficiary_country_of_formation e beneficiary_national_identification_number. named withdrawal suporta apenas WIRE e SWIFT; RTP, SAME_DAY_ACH e ACH continuam suportados apenas para fluxos USD non-named quando aplicável.

Exemplo: Saque USD ACH Normal

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"
  }'

Exemplo: Saque USD RTP Normal

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"
  }'

Exemplo: USD named withdrawal por WIRE

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"
  }'

Exemplo: USD named withdrawal por SWIFT

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"
  }'

4. Off-ramp para Stablecoin

Você também pode sacar saldos diretamente como stablecoins para uma carteira externa. Veja Saque de Stablecoin.

Padrões Comuns

Casos de Uso

Visão Geral

1. Validar Detalhes do Destinatário

2. Criar Destinatário

Exemplo: Criar Destinatário Empresarial USD para named withdrawal

3. Iniciar Pagamento Fiat

Exemplo: Saque USD ACH Normal

Exemplo: Saque USD RTP Normal

Exemplo: USD named withdrawal por WIRE

Exemplo: USD named withdrawal por SWIFT

4. Off-ramp para Stablecoin

​Visão Geral

​1. Validar Detalhes do Destinatário

​2. Criar Destinatário

​Exemplo: Criar Destinatário Empresarial USD para named withdrawal

​3. Iniciar Pagamento Fiat

​Exemplo: Saque USD ACH Normal

​Exemplo: Saque USD RTP Normal

​Exemplo: USD named withdrawal por WIRE

​Exemplo: USD named withdrawal por SWIFT

​4. Off-ramp para Stablecoin

Visão Geral

1. Validar Detalhes do Destinatário

2. Criar Destinatário

Exemplo: Criar Destinatário Empresarial USD para named withdrawal

3. Iniciar Pagamento Fiat

Exemplo: Saque USD ACH Normal

Exemplo: Saque USD RTP Normal

Exemplo: USD named withdrawal por WIRE

Exemplo: USD named withdrawal por SWIFT

4. Off-ramp para Stablecoin