使用虚拟账户收取本地付款

​

工作原理

​

一个账户还是每个付款人一个账户

​

开始之前

• API 访问权限。 一个 API 密钥、已加入白名单的服务器 IP，以及放在 X-BH-TOKEN 请求头中的业务令牌。参见认证。
• 一个已验证的商户。 参见创建商户。
• 一个已激活的币种账户，对应您要收款的币种和渠道（在获取商户账户列表中状态为 2）。参见激活商户账户。
• 一个 FUNDING_WEBHOOK 端点，已注册并能返回所要求的确认响应。参见 Webhook 和 Webhook 设置。

​

支持虚拟账户的渠道

​

分步操作

curl -X POST https://api.velafi.com/v2/merchant/virtual/accounts \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": 100001,
    "fiat": "MXN",
    "paymentId": 105,
    "alias": "CUST0001"
  }'

{ "code": 200, "msg": "SUCCESS", "data": { "fiat": "MXN", "status": 1 } }

curl -G https://api.velafi.com/v2/merchant/virtual/addfunds \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  --data-urlencode "merchantId=100001" \
  --data-urlencode "fiat=MXN" \
  --data-urlencode "paymentId=105" \
  --data-urlencode "depositAlias=CUST0001"

curl -G https://api.velafi.com/v2/merchant/accounts \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  --data-urlencode "merchantId=100001" \
  --data-urlencode "fiat=MXN"

​

需要处理的 Webhook

{
  "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
  "eventType": "FUNDING_WEBHOOK",
  "txId": "1123123123",
  "merchantId": "100001",
  "fiat": "MXN",
  "totalAmount": "1000",
  "amount": "1000",
  "fee": "0",
  "paymentId": "105",
  "type": "DEPOSIT",
  "status": "2",
  "depositAlias": "CUST0001",
  "payerName": "Example Payer",
  "payerAccount": "000000000000000002",
  "bankWebhookInfo": "{...}",
  "completedTime": "1737452344000",
  "createTime": "1737452292000",
  "updateTime": "1737452344000",
  "timestamp": "1737452344512"
}

​

处理失败

• 重复或乱序的事件。 同一事件可能到达不止一次，而在推送前状态已发生变化的事件会被丢弃。请基于 eventType + txId + status 实现幂等处理，并在需要最新状态时通过获取资金记录读取该记录。
• 错过的 Webhook。 如果您的端点宕机或响应不正确，事件不会重发。请定期运行下文的对账流程，确保不遗漏任何充值。
• 没有 depositAlias 的充值。 付款到商户主账户信息的充值，或不回传别名的支付通道，都没有可匹配的虚拟账户。请利用付款人字段和 bankWebhookInfo 将其转入人工审核。
• 虚拟账户创建失败。 status 3 表示渠道拒绝了该账户。-5079 表示该账户未针对该币种和渠道开通，-5071 表示商户在该渠道上的币种账户未激活。重试前请检查商户账户。
• COP 别名被拒绝。 对于 68 和 69，别名必须为 6 到 21 位大写字母或数字。

​

对账

• 使用 GET /v2/merchant/funding/records，传入 type=DEPOSIT、一个 fiat 以及 startTime/endTime 时间窗口（该窗口按完成时间计算）。将每条状态为 2 的记录与您保存的 Webhook 进行比对，并处理遗漏的记录。对于充值，webhookInfo 包含与 bankWebhookInfo 相同的服务商信息，其中包括 depositAlias。
• 使用 GET /v2/merchant/fiat/flows 获取逐笔余额历史：每一行包含变动额（changed）、变动后余额（total）以及相关的 txId。用它来证明获取商户账户列表中的余额等于您所有变动之和。

​

在沙盒环境中测试

• Webhook 不会在沙盒环境中触发。 请自行向处理程序发送示例负载进行测试，并通过获取资金记录检查每笔模拟充值的结果。
• 模拟器只能生成成功的充值，无法生成失败或被退回的充值。

​

上线检查清单

• FUNDING_WEBHOOK 端点会验证签名，并快速返回 HTTP 200 和 {"callbackStatus":"SUCCESS"}，远在 60 秒超时之内。
• 处理程序基于 eventType + txId + status 实现幂等，并忽略已处理过的事件。
• 每个付款人都有自己的虚拟账户，且别名对应您系统中的唯一一位客户。
• 您的账本维护每个付款人的余额；您不期望 VelaFi 为每个虚拟账户单独维护余额。
• 没有 depositAlias 的充值会进入审核队列。
• 有定时任务将资金记录（type=DEPOSIT）与保存的 Webhook 进行比对，并处理缺失的部分。
• 二维码和付款链接在展示前会重新获取。