收款人、支付与出金

概述

您可以通过两种方式从子账户提取资金：

法币支付： 将货币余额转换为当地货币（如 NGN、BRL、EUR）并发送到银行账户。
稳定币出金： 将 USD 作为稳定币（USDC/USDT）提取到外部加密钱包。

本指南涵盖验证收款人、创建受益人和发起提款。

1. 验证收款人信息（法币）

端点： POST /v1/banking/{currency}/validate 在为法币提款添加收款人之前，务必验证账户详情。这可确保账户存在，防止交易失败或资金丢失。

在尝试创建收款人之前，请始终验证账号和银行代码。

示例：验证 NGN 账户

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

响应：

{
  "accountNumber": "0062881117",
  "bankCode": "270"
}

查看 API 参考

2. 创建收款人

端点： POST /v1/ramp/{subaccountId}/banking/recipients 验证通过后，将详细信息保存为收款人。该收款人 id 将用于发起提款。

示例：创建 NGN 收款人

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

响应：

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

查看 API 参考

3. 发起法币支付

端点： POST /v1/ramp/{subaccountId}/banking/withdrawals 从子账户向已创建的收款人发送资金。系统将从子账户中扣除相应的货币余额。

示例：向 NGN 收款人提款

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

注意： amount 字段指定的是目标货币的金额（如 NGN）。等值余额将从子账户的货币持有中扣除。

响应：

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

查看 API 参考

4. 稳定币出金（加密提款）

端点： POST /v1/ramp/{subaccountId}/banking/withdrawals/stablecoin 您也可以将余额直接作为稳定币（USDC 或 USDT）提取到外部钱包地址。

示例：在以太坊上提取 USDT

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

响应：

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

查看 API 参考

常见错误

跳过验证： 未验证银行账户详情通常会导致提款失败和不必要的延迟。
网络错误： 提取稳定币时，请确保 chain 与目标钱包匹配（例如，将 ERC-20 USDT 发送到 TRC-20 地址将导致资金丢失）。
余额不足： 确保子账户有足够的相关货币余额来支付提款金额加上费用。
未验证的子账户： 仅允许已通过验证的子账户进行提款。

Webhook 事件

监听 webhook 事件以实时跟踪提款状态。

withdrawal.status.completed：资金已成功到达目的地。
withdrawal.status.failed：提款无法处理。

请参阅提款事件了解载荷详情。

常见模式

使用场景

概述

1. 验证收款人信息（法币）

示例：验证 NGN 账户

2. 创建收款人

示例：创建 NGN 收款人

3. 发起法币支付

示例：向 NGN 收款人提款

4. 稳定币出金（加密提款）

示例：在以太坊上提取 USDT

常见错误

Webhook 事件

​概述

​1. 验证收款人信息（法币）

​示例：验证 NGN 账户

​2. 创建收款人

​示例：创建 NGN 收款人

​3. 发起法币支付

​示例：向 NGN 收款人提款

​4. 稳定币出金（加密提款）

​示例：在以太坊上提取 USDT

​常见错误

​Webhook 事件

概述

1. 验证收款人信息（法币）

示例：验证 NGN 账户

2. 创建收款人

示例：创建 NGN 收款人

3. 发起法币支付

示例：向 NGN 收款人提款

4. 稳定币出金（加密提款）

示例：在以太坊上提取 USDT

常见错误

Webhook 事件