# 代付接口

> 从可用余额向 Cash App $cashtag 代付、查询结果，并在发起前查看手续费。

**代付目前仅支持 `CASH_APP`。** 在您的账户开通代付后，代付以 `USD` 付至 Cash App `$cashtag`。未开通时，以及 `PAYPAL`、`PIX`，`/payouts/create` 与带金额的 `/payouts/precheck` 均返回 `code=5007`。也可以在商户后台的「代付 → 发起代付」中发起代付。

代付只使用可用余额：未结算资金须结算后才能代付。创建代付时，代付金额与手续费从可用余额中扣出并冻结，直到结果确定；代付成功时扣除，失败时退回。若可用余额不足以覆盖金额与手续费，代付以 `code=5004` 拒绝，不冻结任何资金。

手续费 = 代付费率 × 金额 + 每笔固定手续费，四舍五入到分。调用带金额的 `/payouts/precheck` 可在发起前得到手续费与扣款总额（见 [代付余额预检查](https://www.hansapay.io/docs/zh/payouts#payout-balance-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` 必须是 `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` 中看到原因（见 [查询代付](https://www.hansapay.io/docs/zh/payouts#query-payout)）
- 若 Cash App 不接受该收款人，代付以 `FAILED` 结束，`status_reason` 为
  `Recipient not valid`，金额退回可用余额
- 已受理的代付状态为 `PROCESSING`，金额与手续费保持冻结，直到结果到达。
  若未收到响应（例如超时），请先用 `merchant_payout_no` 查询（见 [查询代付](https://www.hansapay.io/docs/zh/payouts#query-payout)），再决定是否重新发起：
  使用新的单号会再发出一笔代付
- Cash App 代付不支持取消。结果通常在几分钟内到达，通过 `notify_url` 通知，
  也可主动查询该代付（见 [查询代付](https://www.hansapay.io/docs/zh/payouts#query-payout)）

说明：

- 若返回 `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`、`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 | 更新时间 |

### 完整成功响应示例

```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_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` 时：`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
  }
}
```
