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_methodstring是CASH_APP / PAYPAL / PIX(目前仅 CASH_APP 可用)
merchant_payout_nostring是商户代付单号,幂等键
trans_amount.currencystring是币种;PIX 固定 BRL
trans_amount.valuestring是金额
payee.account_idstring通常必填收款账号;PIX 为 PIX Key 的值
payee.account_typestring通常必填EMAIL / MOBILE / CASHTAG / USERID 等;PIX 为 CPF / CNPJ / PHONE / EMAIL
payee.full_namestring部分通道必填收款人姓名;PIX 必填
payee.documentstring部分通道必填收款人证件号;PIX 必填(巴西 CPF)
payee.emailstring否收款人邮箱
payee.mobilestring否收款人手机号
payee.countrystring否国家码
payee.payee_idstring否钱包侧用户ID
memostring否付款备注
notify_urlstring是商户接收代付结果的异步通知地址;HansaPay 系统会在收到上游结果后再通知该地址
metadatastring否商户透传参数
client_ipstring否客户端 IP

Cash App 代付说明:

  • trans_amount.currency 必须是 USD
  • payee.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_methodstring支付方式
payout_nostringHansaPay 系统代付单号
merchant_payout_nostring商户代付单号
statusstringPENDING / PROCESSING / SUCCESS / FAILED
trans_amountobject代付金额
feeobject手续费
total_debitobject实际扣减总额
next_actionstringWAIT_NOTIFY / SUCCESS / FAILED
created_atstring创建时间

完整成功响应示例

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_nostring二选一HansaPay 系统代付单号
merchant_payout_nostring二选一商户代付单号

成功 data

字段类型说明
payment_methodstring支付方式
payout_nostringHansaPay 系统代付单号
merchant_payout_nostring商户代付单号
statusstring代付状态
status_reasonstringFAILED:Payout request failed、Recipient not valid 或 Payout failed;CANCELED:Payout canceled;其他情况不返回。不会返回上游的原始信息
trans_amountobject金额
feeobject手续费
total_debitobject总扣款
payeeobject收款人信息快照
metadatastring商户透传参数
paid_atstring完成时间
created_atstring创建时间
updated_atstring更新时间

完整成功响应示例

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

说明:

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

请求字段

字段类型必填说明
payout_nostring二选一HansaPay 系统代付单号
merchant_payout_nostring二选一商户代付单号
reasonstring否取消原因

成功 data

字段类型说明
payout_nostringHansaPay 系统代付单号
merchant_payout_nostring商户代付单号
statusstring期望为 CANCELED

完整成功响应示例

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

代付余额预检查

POST/api/v1/payouts/precheck

请求字段

字段类型必填说明
payment_methodstring是CASH_APP / PAYPAL / PIX
trans_amountobject否若传入,则返回预估手续费与预估总扣款

说明:

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

成功 data

字段类型说明
payment_methodstring支付方式
currencystring币种
available_balanceobject可用余额
unsettled_balanceobject未清算余额
frozen_balanceobject冻结余额
spendable_balanceobject可代付余额,等于 available_balance
estimated_feeobject预估手续费,只有传入金额时返回
estimated_debitobject预估总扣减,只有传入金额时返回
can_payoutbool不传 trans_amount 时:available_balance 是否大于零。不代表有可用的代付方式。传入 trans_amount 时:available_balance 是否足以支付预估总扣减

完整成功响应示例

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