法币出金对接指南

本文档面向商户开发者，说明如何通过 quickpayout 发起法币出金、处理验证 Webhook，并通过查询接口确认最终结果。

法币出金主流程分为三步：

发起打款：商户调用 POST /payment/quickpayout 创建并提交出金指令。
验证并执行：Beyounger 异步校验打款信息，必要时通过 Webhook 请求商户确认，验证通过后执行打款。
确认结果：商户通过 Webhook 接收结果通知，也可以调用查询接口做补偿确认和对账。

一页摘要

最小 API 集合：

POST /payment/quickpayout
GET /payment/payouts/{payout_id}

最小 Webhook 集合：

payout.verify.request：商户侧验证出金信息，按账号配置启用
payout.execution.completed：打款成功
payout.execution.failed：打款失败

可能还会收到：

payout.review.approved
payout.review.returned
payout.review.rejected
payout.execution.processing

接入前准备

正式发起打款前，先确认这些信息：

项目	为什么需要
API Key 权限	创建出金需要 `payment.payout.create`。如果传 `submit=true`，还需要 `payment.payout.submit`。查询出金需要 `payment.payout.read`。
出金路线	Beyounger 需要先为商户账号开通对应币种、方式和服务商路线。
`method_id`	使用 Beyounger 为该商户账号配置的实际值。本文 PayPal 示例使用 `1`。
Webhook 地址	商户需要准备可访问的 HTTPS `notify_url`，并配置 payout webhook 签名和订阅。
商户侧存储	至少保存 `reference`、`client_request_id`、`payout_id`、`beneficiary_id`、`beneficiary_account_id`。

确认可用方式和字段

首次接入或新增出金路线时，商户需要先知道可用的 payout method，以及该方式下收款账户要传哪些字段。

建议顺序：

调用 GET /payment/payout-methods?currency=USD，确认当前账号可用的出金方式，拿到 method_id。
调用 GET /payment/payout-networks?method_id=1&currency=USD&include_schema=true，确认该方式支持的收款网络和字段规则。
如果只需要查看某个网络的字段，调用 GET /payment/payout-networks/{code}/schema，例如 GET /payment/payout-networks/PAYPAL/schema。
根据 schema 里的 field_key、required、validation_rule 组装 beneficiary_account.fields。

字段来源对应关系：

你需要的值	从哪里获取	用在请求哪里
出金方式 ID	`GET /payment/payout-methods` 返回的 `method_id`	`method_id`
收款网络	`GET /payment/payout-networks` 返回的 `code`	`beneficiary_account.network_code`
收款账户字段	`fields[].field_key`	`beneficiary_account.fields`
是否必填	`fields[].required`	判断字段是否必须传
校验规则	`fields[].validation_rule`	前端或后端提交前校验

例如 PayPal 收款邮箱字段来自 PAYPAL 网络 schema，打款请求中应放在：

{
  "beneficiary_account": {
    "network_code": "PAYPAL",
    "fields": {
      "paypal_email": "recipient@example.com"
    }
  }
}

这些查询接口用于接入前确认配置和字段要求，不需要商户在每笔出金前都调用。

核心流程图

第一步：发起打款

接口

POST /payment/quickpayout

商户通过该接口创建一笔法币出金指令。正式打款场景建议传 submit=true，让出金创建后进入 Beyounger 的异步验证和执行流程。

请求头

Authorization: Bearer <api_key_jwt>
Content-Type: application/json
Accept: application/json

核心请求参数

字段	是否必填	说明
`client_request_id`	建议必填	商户侧幂等或追踪 ID，建议每笔唯一
`currency`	必填	出金币种，例如 `USD`
`amount`	必填	出金金额，例如 `"0.5"`
`method_id`	通常必填	商户账号配置的出金方式 ID
`reference`	必填	商户业务单号，建议唯一
`notify_url`	必填	商户接收出金验证和结果通知的回调地址
`beneficiary`	必填	收款人身份信息
`beneficiary_account`	必填	收款账户信息，字段按对应 network schema 传入
`beneficiary_account_id`	可选	已提前创建收款账户时可用于复用
`fee_bearer`	否	手续费承担方，不传默认 `merchant`
`submit`	建议 `true`	是否创建后立即提交进入验证和执行

推荐在 quickpayout 请求中同时传 beneficiary 和 beneficiary_account。Beyounger 会根据收款人和收款账户信息创建或匹配已有记录。

如果商户已经提前创建并保存了收款账户，也可以传 beneficiary_account_id 复用该账户。

受益人和收款账户逻辑

beneficiary 和 beneficiary_account 作为一组收款对象提交：

对象	含义	关键字段
`beneficiary`	收款人身份档案，表示实际收款的人或主体	`name`、`fields.payee_id`、`fields.email`、`fields.first_name`、`fields.last_name`、`fields.country`、`fields.phone`
`beneficiary_account`	该受益人在当前 `network_code` 下的目标收款账户。PayPal 场景下表示 PayPal 收款账户	`network_code`、`display_name`、`fields.paypal_email`

对 /payment/quickpayout 来说，商户应传 beneficiary.fields.payee_id。它是商户系统里的收款方唯一标识，例如用户 ID、卖家 ID、客户 ID。对于同一个收款方，这个值应该保持稳定。

Beyounger 在接口对接层面按“同一个 network_code 下，一个受益人只有一个收款账户”处理。一次 quickpayout 请求中，只传一个 beneficiary，并传与之对应的一个 beneficiary_account。

Beyounger 会用 method_id + payee_id 查找已有的 active 受益人。如果该受益人在同一个 network_code 下已经有账户，并且账户字段一致，则复用该账户。如果同一个受益人在该 network_code 下已经有不同账户，请求会被拒绝，商户应复用已有账户，或为不同收款人传不同的 payee_id。

如果没有匹配到已有受益人，则根据 beneficiary 创建受益人，并根据 beneficiary_account 创建该受益人的收款账户。

不要只把 PayPal 收款邮箱放在 beneficiary.fields.email。PayPal 出金的实际收款邮箱必须放在 beneficiary_account.fields.paypal_email。

Inline 创建 PayPal 收款方

{
  "client_request_id": "po_202606190001",
  "currency": "USD",
  "amount": "0.5",
  "method_id": 1,
  "reference": "po_202606190001",
  "notify_url": "https://merchant.example.com/webhooks/payout",
  "beneficiary": {
    "name": "PayPal Recipient",
    "fields": {
      "payee_id": "729921697",
      "language": "en",
      "country": "US",
      "phone": "+1-4155550100",
      "birthdate": "1990-01-01",
      "email": "recipient@example.com",
      "first_name": "PayPal",
      "last_name": "Recipient",
      "zip": "94105",
      "city": "San Francisco",
      "state": "CA",
      "address": "1 Market St"
    }
  },
  "beneficiary_account": {
    "network_code": "PAYPAL",
    "display_name": "PayPal Account",
    "fields": {
      "paypal_email": "recipient@example.com"
    }
  },
  "submit": true
}

成功响应

{
  "code": 0,
  "message": "OK",
  "data": {
    "payout": {
      "payout_id": "payout_7b35b81fa57121c6",
      "client_request_id": "po_202606190001",
      "reference": "po_202606190001",
      "currency": "USD",
      "amount": "0.5",
      "status": "pending_review",
      "review_status": "pending_review",
      "execution_status": "init",
      "risk_status": "pending",
      "beneficiary_id": "beneficiary_xxx",
      "beneficiary_account_id": "bacc_xxx"
    }
  }
}

创建成功不代表已经打款成功，只代表 Beyounger 接收了出金指令。

必须保存：

reference
client_request_id
payout_id
beneficiary_id
beneficiary_account_id
status
review_status
execution_status

第二步：验证并执行打款

quickpayout 提交后，Beyounger 会异步验证打款信息。如果商户账号启用了商户侧验证，Beyounger 会在执行前发送 payout.verify.request。

验证请求

示例 payload：

{
  "payout_id": "payout_7b35b81fa57121c6",
  "type": "payout.verify",
  "account_id": "acct_xxx",
  "reference": "po_202606190001",
  "currency": "USD",
  "amount": "0.5",
  "status": "pending_review",
  "review_status": "pending_review",
  "execution_status": "init",
  "beneficiary_id": "beneficiary_xxx",
  "beneficiary_account_id": "bacc_xxx",
  "beneficiary_name": "PayPal Recipient",
  "network_code": "PAYPAL",
  "account_type": "fiat",
  "beneficiary_account": {
    "network_code": "PAYPAL",
    "display_name": "PayPal Account",
    "fields_masked": {
      "paypal_email": "r***@example.com"
    }
  },
  "submitted_at": 1781789497,
  "created_at": 1781789497
}

商户收到后应：

校验 Webhook 签名
按 event_id 或 payout_id 做幂等
校验商户订单、金额、币种、收款人和收款账户
只返回明确的 verified 决策

通过响应：

{
  "verified": true
}

拒绝响应：

{
  "verified": false
}

如果响应无法解析，或没有明确结果，Beyounger 会视为可重试，不会直接执行打款。

执行结果 Webhook

事件	说明	商户处理
`payout.review.approved`	验证或审核通过	标记为审核通过，等待执行
`payout.review.returned`	出金被退回	标记为退回，等待处理
`payout.review.rejected`	出金被拒绝	标记为拒绝或失败
`payout.execution.processing`	已开始执行打款	标记为处理中
`payout.execution.completed`	打款成功	标记为成功并对账
`payout.execution.failed`	打款失败	标记为失败并读取失败原因

结果通知使用事件包裹结构，核心字段如下：

{
  "event_id": "payout_payout_7b35b81fa57121c6_ab12cd34ef56",
  "event_type": "payout.execution.completed",
  "business_type": "payout",
  "business_id": "payout_7b35b81fa57121c6",
  "occurred_at": 1781789497,
  "version": "v1",
  "data": {
    "payout_id": "payout_7b35b81fa57121c6",
    "reference": "po_202606190001",
    "currency": "USD",
    "amount": "0.5",
    "status": "completed",
    "review_status": "approved",
    "execution_status": "completed"
  }
}

字段	说明
`event_id`	Webhook 事件 ID
`event_type`	事件类型
`business_type`	固定为 `payout`
`business_id`	等于 `payout_id`
`data.payout_id`	出金 ID
`data.reference`	商户业务单号
`data.amount` / `data.currency`	金额和币种
`data.status`	出金总状态
`data.review_status`	验证或审核状态
`data.execution_status`	执行状态
`data.execution_fail_reason`	失败原因

第三步：查询接口

接口

GET /payment/payouts/{payout_id}

调用场景：

创建后查看初始状态
收到 Webhook 后确认最新状态
Webhook 超时或丢失时补偿查询
财务或运营对账

状态判断

`review_status`	`execution_status`	含义
`pending_review`	`init`	等待验证或审核
`approved`	`init`	已通过，等待执行
`approved`	`processing`	正在执行
`approved`	`completed`	打款成功
`approved`	`failed`	打款失败
`rejected`	`init`	验证或审核拒绝
`returned`	`init`	已退回，需要处理

最终结果建议以 execution_status 为主：

completed：最终成功
failed：最终失败
processing：处理中
init：尚未执行，需要结合 review_status

Webhook 用于实时通知，查询接口用于确认和补偿。

PayPal 注意事项

字段	放置位置	说明
`paypal_email`	`beneficiary_account.fields`	PayPal 收款邮箱
`payee_id`	`beneficiary.fields`	商户侧收款方唯一标识，同一个收款方应保持稳定
`email`	`beneficiary.fields`	收款人身份邮箱
`first_name` / `last_name`	`beneficiary.fields`	收款人姓名
`country`	`beneficiary.fields`	国家或地区
`phone`	`beneficiary.fields`	手机号

注意：

PayPal 收款邮箱通常放在 beneficiary_account.fields.paypal_email
beneficiary.fields.email 是收款人身份字段，不等于收款账户字段
beneficiary.fields.payee_id 应该传商户内部的收款方 ID，不要传 PayPal 邮箱
phone 推荐格式：+1-4155550100
不确定时不要传 beneficiary_account.account_type
method_id 以 Beyounger 为该商户账号配置的实际值为准

常见问题

quickpayout 成功是否代表已打款？

不是。它只代表出金指令已被接收。最终结果看 Webhook 或查询接口。

必须实现 payout.verify.request 吗？

取决于账号配置。如果启用了商户侧验证，必须实现并返回 {"verified": true} 或 {"verified": false}。

Webhook 和查询接口哪个为准？

Webhook 用于实时通知，查询接口用于确认和补偿。建议两者都接入。

一页摘要​

接入前准备​

确认可用方式和字段​

核心流程图​

第一步：发起打款​

请求头​

核心请求参数​

受益人和收款账户逻辑​

Inline 创建 PayPal 收款方​

成功响应​

第二步：验证并执行打款​

验证请求​

执行结果 Webhook​

第三步：查询接口​

状态判断​

PayPal 注意事项​

常见问题​

quickpayout 成功是否代表已打款？​

必须实现 payout.verify.request 吗？​

Webhook 和查询接口哪个为准？​

开发资源​