API 参考

代付接口

按接口定义说明代付接口。代付目前不可用。

代付目前不可用。 目前无法处理任何代付方式：所有合法的 /payouts/create 请求，以及带金额的 /payouts/precheck，均返回 code=5007（例如 payment_method CASH_APP is not available for payouts|unsupportedPayoutMethod）。不会创建任何订单，也不会冻结余额。下文按接口定义描述各接口。

创建代付

POST/api/v1/payouts/create

请求字段

字段	类型	必填	说明
`payment_method`	string	是	`CASH_APP` / `PAYPAL` / `PIX`（目前均不可用）
`merchant_payout_no`	string	是	商户代付单号，幂等键
`trans_amount.currency`	string	是	币种；`PIX` 固定 `BRL`
`trans_amount.value`	string	是	金额
`payee.account_id`	string	通常必填	收款账号；`PIX` 为 PIX Key 的值
`payee.account_type`	string	通常必填	`EMAIL` / `MOBILE` / `CASHTAG` / `USERID` 等；`PIX` 为 `CPF` / `CNPJ` / `PHONE` / `EMAIL`
`payee.full_name`	string	部分通道必填	收款人姓名；`PIX` 必填
`payee.document`	string	部分通道必填	收款人证件号；`PIX` 必填（巴西 CPF）
`payee.email`	string	否	收款人邮箱
`payee.mobile`	string	否	收款人手机号
`payee.country`	string	否	国家码
`payee.payee_id`	string	否	钱包侧用户ID
`memo`	string	否	付款备注
`notify_url`	string	是	商户接收代付结果的异步通知地址；HansaPay 系统会在收到上游结果后再通知该地址
`metadata`	string	否	商户透传参数
`client_ip`	string	否	客户端 IP

巴西 PIX 代付说明：

trans_amount.currency 必须是 BRL，其他币种会在冻结余额之前以 code=5008 拒绝；该金额即收款人实际到账金额
商户余额以结算币种（USD）记账，因此代付会按实时汇率（含加点）换算后以 USD 扣减。响应中的 trans_amount 回显 BRL（收款人到账），而 fee 与 total_debit 是结算币种（真正从余额扣走的金额）
payee.account_type 与 payee.account_id 描述 PIX Key。account_type 取值 CPF / CNPJ / PHONE / EMAIL，不填按 CPF 处理。CPF 类型下 account_id 可不填（使用收款人 payee.document 作为 PIX Key），填写时必须是合法 CPF；CNPJ / PHONE / EMAIL 类型必须填写 account_id
本通道不支持撤单：上游未提供撤单接口
若提交结果不确定（例如网络超时），代付单保持 PROCESSING、金额保持冻结，直到回调或平台定时查单确认结果。若上游确认从未收到该笔代付，会置为 FAILED 并解冻

说明：

若返回 code=5008，表示代付金额不满足当前可用通道限额

成功 `data`

字段	类型	说明
`payment_method`	string	支付方式
`payout_no`	string	HansaPay 系统代付单号
`merchant_payout_no`	string	商户代付单号
`status`	string	`PENDING` / `PROCESSING` / `SUCCESS` / `FAILED`
`trans_amount`	object	代付金额
`fee`	object	手续费
`total_debit`	object	实际扣减总额
`next_action`	string	`WAIT_NOTIFY` / `SUCCESS` / `FAILED`
`created_at`	string	创建时间

完整成功响应示例

JSON

{
  "code": 0,
  "msg": "success",
  "data": {
    "payment_method": "CASH_APP",
    "payout_no": "P202406240001",
    "merchant_payout_no": "MP202406240001",
    "status": "PENDING",
    "trans_amount": {
      "currency": "USD",
      "value": "88.50"
    },
    "fee": {
      "currency": "USD",
      "value": "1.50"
    },
    "total_debit": {
      "currency": "USD",
      "value": "90.00"
    },
    "next_action": "WAIT_NOTIFY",
    "created_at": "2026-06-24T12:00:00+08:00"
  }
}

查询代付

POST/api/v1/payouts/query

请求字段

字段	类型	必填	说明
`payout_no`	string	二选一	HansaPay 系统代付单号
`merchant_payout_no`	string	二选一	商户代付单号

成功 `data`

字段	类型	说明
`payment_method`	string	支付方式
`payout_no`	string	HansaPay 系统代付单号
`merchant_payout_no`	string	商户代付单号
`status`	string	代付状态
`status_reason`	string	`FAILED`：`Payout request failed` 或 `Payout failed`；`CANCELED`：`Payout canceled`；其他情况不返回。不会返回上游的原始信息
`trans_amount`	object	金额
`fee`	object	手续费
`total_debit`	object	总扣款
`payee`	object	收款人信息快照
`metadata`	string	商户透传参数
`paid_at`	string	完成时间
`created_at`	string	创建时间
`updated_at`	string	更新时间

完整成功响应示例

JSON

{
  "code": 0,
  "msg": "success",
  "data": {
    "payment_method": "CASH_APP",
    "payout_no": "P202406240001",
    "merchant_payout_no": "MP202406240001",
    "status": "SUCCESS",
    "trans_amount": {
      "currency": "USD",
      "value": "88.50"
    },
    "fee": {
      "currency": "USD",
      "value": "1.50"
    },
    "total_debit": {
      "currency": "USD",
      "value": "90.00"
    },
    "payee": {
      "account_id": "$cashdemo",
      "account_type": "CASHTAG",
      "full_name": "John Doe",
      "country": "US"
    },
    "metadata": "batch=20260624",
    "paid_at": "2026-06-24T12:00:08+08:00",
    "created_at": "2026-06-24T12:00:00+08:00",
    "updated_at": "2026-06-24T12:00:08+08:00"
  }
}

取消代付

POST/api/v1/payouts/cancel

说明：

大部分渠道不支持取消代付
商户接入时通常可以忽略此接口
仅当 HansaPay 系统与具体代付通道明确支持取消时，再接入使用

请求字段

字段	类型	必填	说明
`payout_no`	string	二选一	HansaPay 系统代付单号
`merchant_payout_no`	string	二选一	商户代付单号
`reason`	string	否	取消原因

成功 `data`

字段	类型	说明
`payout_no`	string	HansaPay 系统代付单号
`merchant_payout_no`	string	商户代付单号
`status`	string	期望为 `CANCELED`

完整成功响应示例

JSON

{
  "code": 0,
  "msg": "success",
  "data": {
    "payout_no": "P202406240001",
    "merchant_payout_no": "MP202406240001",
    "status": "CANCELED"
  }
}

代付余额预检查

POST/api/v1/payouts/precheck

请求字段

字段	类型	必填	说明
`payment_method`	string	是	`CASH_APP` / `PAYPAL` / `PIX`
`trans_amount`	object	否	若传入，则返回预估手续费与预估总扣款

说明：

若传入 trans_amount 且返回 code=5008，表示该代付金额不满足当前可用通道限额

成功 `data`

字段	类型	说明
`payment_method`	string	支付方式
`currency`	string	币种
`available_balance`	object	可用余额
`unsettled_balance`	object	未清算余额
`frozen_balance`	object	冻结余额
`spendable_balance`	object	可代付余额，等于 `available_balance`
`estimated_fee`	object	预估手续费，只有传入金额时返回
`estimated_debit`	object	预估总扣减，只有传入金额时返回
`can_payout`	bool	不传 `trans_amount` 时：`available_balance` 是否大于零。不代表有可用的代付方式。目前传入 `trans_amount` 的请求会返回 `code=5007`

完整成功响应示例

JSON

{
  "code": 0,
  "msg": "success",
  "data": {
    "payment_method": "PAYPAL",
    "currency": "USD",
    "available_balance": {
      "currency": "USD",
      "value": "1000.00"
    },
    "unsettled_balance": {
      "currency": "USD",
      "value": "200.00"
    },
    "frozen_balance": {
      "currency": "USD",
      "value": "50.00"
    },
    "spendable_balance": {
      "currency": "USD",
      "value": "1000.00"
    },
    "estimated_fee": {
      "currency": "USD",
      "value": "1.50"
    },
    "estimated_debit": {
      "currency": "USD",
      "value": "90.00"
    },
    "can_payout": true
  }
}

创建代付#

请求字段#

成功 data#

完整成功响应示例#

查询代付#

请求字段#

成功 data#

完整成功响应示例#

取消代付#

请求字段#

成功 data#

完整成功响应示例#

代付余额预检查#

请求字段#

成功 data#

完整成功响应示例#

创建代付

请求字段

成功 `data`

完整成功响应示例

查询代付

请求字段

成功 `data`

完整成功响应示例

取消代付

请求字段

成功 `data`

完整成功响应示例

代付余额预检查

请求字段

成功 `data`

完整成功响应示例