API 参考
English代付接口
从可用余额向 Cash App $cashtag 代付、查询结果,并在发起前查看手续费。
代付目前仅支持 CASH_APP。 在您的账户开通代付后,代付以 USD 付至 Cash App $cashtag。未开通时,以及 PAYPAL、PIX,/payouts/create 与带金额的 /payouts/precheck 均返回 code=5007。也可以在商户后台的「代付 → 发起代付」中发起代付。
代付只使用可用余额:未结算资金须结算后才能代付。创建代付时,代付金额与手续费从可用余额中扣出并冻结,直到结果确定;代付成功时扣除,失败时退回。若可用余额不足以覆盖金额与手续费,代付以 code=5004 拒绝,不冻结任何资金。
手续费 = 代付费率 × 金额 + 每笔固定手续费,四舍五入到分。调用带金额的 /payouts/precheck 可在发起前得到手续费与扣款总额(见 代付余额预检查)。
创建代付
POST/api/v1/payouts/create请求字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
payment_method | string | 是 | CASH_APP / PAYPAL / PIX(目前仅 CASH_APP 可用) |
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 |
Cash App 代付说明:
trans_amount.currency必须是USDpayee.account_id为收款人的 Cash App$cashtag,开头的$可省略;payee.account_type填CASHTAG或不填。其他收款人字段均为选填。 不是$cashtag的account_id会以code=5006拒绝- 金额须在您的代付通道限额之内,目前为每笔 10.00 至 1,000.00 USD,可在商户后台查看。
超出限额的金额以
code=5008拒绝,不冻结任何资金 - 若代付在提交时被拒绝,响应仍为
code=0,status与next_action均为FAILED。 金额与手续费立即退回可用余额,并发送payout.updated通知;查询该代付时可在status_reason中看到原因(见 查询代付) - 若 Cash App 不接受该收款人,代付以
FAILED结束,status_reason为Recipient not valid,金额退回可用余额 - 已受理的代付状态为
PROCESSING,金额与手续费保持冻结,直到结果到达。 若未收到响应(例如超时),请先用merchant_payout_no查询(见 查询代付),再决定是否重新发起: 使用新的单号会再发出一笔代付 - Cash App 代付不支持取消。结果通常在几分钟内到达,通过
notify_url通知, 也可主动查询该代付(见 查询代付)
说明:
- 若返回
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 | 创建时间 |
完整成功响应示例
{
"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、Recipient not valid 或 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 | 更新时间 |
完整成功响应示例
{
"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说明:
- 大部分渠道不支持取消代付
- Cash App 代付不支持取消
- 商户接入时通常可以忽略此接口
- 仅当 HansaPay 系统与具体代付通道明确支持取消时,再接入使用
请求字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
payout_no | string | 二选一 | HansaPay 系统代付单号 |
merchant_payout_no | string | 二选一 | 商户代付单号 |
reason | string | 否 | 取消原因 |
成功 data
| 字段 | 类型 | 说明 |
|---|---|---|
payout_no | string | HansaPay 系统代付单号 |
merchant_payout_no | string | 商户代付单号 |
status | string | 期望为 CANCELED |
完整成功响应示例
{
"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 时:available_balance 是否足以支付预估总扣减 |
完整成功响应示例
{
"code": 0,
"msg": "success",
"data": {
"payment_method": "CASH_APP",
"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
}
}