# 支付接口

> 直连下单、收银台下单与查询支付订单，以及钱包和部分卡通道使用的金额档位。

## 创建支付订单（统一入口）

`POST /api/v1/payments/create`

说明：

- `/api/v1/payments/create` 是统一支付下单入口
- HansaPay 系统会根据 `payment_method` 分发请求
- 支持的 `payment_method`：
  - `CARD`
  - `CASH_APP`
  - `PAYPAL`（目前不可用）
  - `APPLE_PAY`
  - `GOOGLE_PAY`
  - `PIX`（目前不可用）

通用字段：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `payment_method` | string | 是 | 支付方式 |
| `merchant_order_no` | string | 是 | 商户订单号，最长 64 个字符，在你的订单与退款之间唯一 |
| `trans_amount.currency` | string | 是 | 三位大写币种，如 `USD`，须为支持的币种之一（见 [重要说明](https://www.hansapay.io/docs/zh/what-to-expect)） |
| `trans_amount.value` | string | 是 | 金额字符串，如 `99.99`：最多 2 位小数，`JPY` 不带小数，`OMR` 最多 3 位 |
| `notify_url` | string | 是 | 支付结果异步通知地址 |
| `return_url` | string | 否 | 前端支付完成后跳转地址 |
| `trade_info.goods_name` | string | 是 | 商品名称 |
| `trade_info.description` | string | 否 | 商品描述 |
| `metadata` | string | 否 | 商户透传参数，通知原样回传 |
| `client_ip` | string | 否 | 商户端记录的客户端 IP |

### 卡支付直连

适用：

- `payment_method=CARD`

附加字段：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `payer.email` | string | 否 | 付款人邮箱 |
| `payer.mobile` | string | 否 | 付款人手机号 |
| `payer.user_name` | string | 否 | 用户名 |
| `payer.user_agent` | string | 否 | 浏览器 UA |
| `payer.ext_type` | string | 否 | 渠道扩展字段 |
| `payer.payer_id` | string | 否 | 钱包侧付款人标识 |
| `card.card_number` | string | 是 | 卡号 |
| `card.cardholder_name` | string | 是 | 持卡人姓名 |
| `card.exp_month` | int | 是 | 过期月，1-12 |
| `card.exp_year` | int | 是 | 过期年，四位 |
| `card.cvc` | string | 是 | CVV/CVC |
| `billing_address.country` | string | 是 | 两位国家码，如 `US` |
| `billing_address.first_name` | string | 否 | 名 |
| `billing_address.last_name` | string | 否 | 姓 |
| `billing_address.email` | string | 否 | 邮箱 |
| `billing_address.phone` | string | 否 | 电话 |
| `billing_address.state` | string | 否 | 州/省 |
| `billing_address.city` | string | 否 | 城市 |
| `billing_address.address` | string | 否 | 地址 |
| `billing_address.street_number` | string | 否 | 门牌号 |
| `billing_address.postal_code` | string | 否 | 邮编 |
| `billing_address.document` | string | 否 | 某些国家要求的证件号 |
| `shipping_address.*` | object | 否 | 如传入则按完整配送地址校验 |
| `device_ip` | string | 是 | 用户设备公网 IP |
| `browser.accept` | string | 否 | 浏览器 Accept |
| `browser.user_agent` | string | 否 | 浏览器 UA |
| `browser.accept_language` | string | 否 | 语言 |
| `browser.java_enabled` | bool | 否 | 是否启用 Java |
| `browser.color_depth` | string | 否 | 色深 |
| `browser.screen_height` | string | 否 | 屏幕高 |
| `browser.screen_width` | string | 否 | 屏幕宽 |
| `browser.time_zone_offset` | string | 否 | 时区偏移 |
| `browser.referer` | string | 否 | Referer |

为获得最高的支付成功率，请尽量传入所有已有字段，包括可选字段。卡组织和发卡行会使用完整的账单地址、邮箱、电话、收货地址、付款人真实的 `device_ip` 以及 `browser` 字段进行风控，部分收单机构还会强制要求这些字段；信息缺失可能导致更多交易被拒绝。美国和加拿大地址的 `state` 请传两位代码（如 `CA`、`ON`），`postal_code` 请传 `12345` 或 `12345-6789`（美国）或 `A1B 2C3`（加拿大）。

卡支付请求示例：

```json
{
  "payment_method": "CARD",
  "merchant_order_no": "M202406240001",
  "trans_amount": {
    "currency": "USD",
    "value": "99.99"
  },
  "notify_url": "https://merchant.example.com/callback/payment",
  "return_url": "https://merchant.example.com/pay/success",
  "trade_info": {
    "goods_name": "VIP Membership",
    "description": "Monthly subscription"
  },
  "metadata": "biz=member&uid=10001",
  "card": {
    "card_number": "4111111111111111",
    "cardholder_name": "JOHN DOE",
    "exp_month": 12,
    "exp_year": 2028,
    "cvc": "123"
  },
  "billing_address": {
    "country": "US",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "15551234567",
    "state": "CA",
    "city": "San Francisco",
    "address": "Market Street",
    "street_number": "1355",
    "postal_code": "94103"
  },
  "device_ip": "203.0.113.10",
  "client_ip": "203.0.113.10"
}
```

#### 成功 `data`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `payment_method` | string | `CARD` |
| `order_no` | string | HansaPay 系统订单号 |
| `merchant_order_no` | string | 商户订单号 |
| `status` | string | 订单状态 |
| `trans_amount` | object | 实收金额 |
| `next_action` | string | `SUCCESS` / `3DS_VERIFICATION_REQUIRED` / `PROCESSING` / `FAILED` |
| `masked_card_number` | string | 脱敏卡号 |
| `three_ds_url` | string | `next_action=3DS_VERIFICATION_REQUIRED` 时返回；请将付款人跳转到该地址 |
| `created_at` | string | 创建时间 |

说明：

- 即使金额已取整到价位，本响应也不含 `requested_amount`；请使用查单或通知获取
- 若卡被拒，响应为 `code=422`、`Payment request failed|paymentFailed`，不含 `order_no`；随后会发送 `status=FAILED` 的 `payment.updated` 通知
- 卡号、CVC 或有效期无效时返回 `System busy, please try again later|systemBusy`

### 钱包支付直连

适用：

- `payment_method=CASH_APP`
- `payment_method=APPLE_PAY`
- `payment_method=GOOGLE_PAY`
- `payment_method=PAYPAL` 与 `payment_method=PIX` 目前不可用（`code=3003`）

`APPLE_PAY` / `GOOGLE_PAY` 为托管钱包页：将付款人跳转到 `pay_url`，钱包面板在该页面呈现并完成支付。这两种方式下 HansaPay 不采集卡信息。付款人字段一般可选，除非路由到的通道有额外要求（错误信息会指明缺失字段）。支付完成后，付款人会返回 HansaPay 的结果页，该页显示支付结果后再将付款人跳转到您的 `return_url`。

`CASH_APP`：将付款人跳转到 `pay_url`。根据订单路由到的通道，它可能是 HansaPay 的支付页面，也可能是支付处理方的 Cash App Pay 页面：
- HansaPay 页面在手机上显示"打开 Cash App"按钮，在电脑上显示供扫描的二维码，并持续跟踪支付状态，支付完成后将付款人跳转到您的 `return_url`。其支付请求仅在有限时间内可支付（目前为 15 分钟），过期后付款人需从您的网站重新发起支付。
- 在支付处理方的 Cash App Pay 页面上，付款人在 Cash App 中确认付款，随后返回 HansaPay 的结果页，再跳转到您的 `return_url`。这类通道上的 Cash App 使用下方的钱包金额档位。

**钱包金额档位。** 钱包上游只按固定价位收款（USD 4.99、5.99、6.99、7.99、8.99、9.90、9.99、10.99、11.99、12.99、13.99、14.99、15.99、17.99、19.80、19.99、24.99、29.99、30.99、39.99、49.50、49.99、59.99、89.99、99.99、124.99、129.99、149.99、159.99、199.99、249.99、299.99、399.99、499.99）。创建 `APPLE_PAY` / `GOOGLE_PAY` 订单（使用支付处理方 Cash App Pay 页面的通道上的 `CASH_APP` 订单亦同，或在收银台通过快捷按钮把卡订单切换为钱包）时，HansaPay 会把金额**向下**取整到最接近的档位：请求 USD 11.00 时实收、入账与回传均为 USD 10.99。所有响应、查单与通知中的 `trans_amount` 为实收金额，原请求金额另以 `requested_amount` 返回（结构同 `trans_amount`，未取整时省略）。手续费按实收金额计算。低于 USD 4.99、高于 USD 499.99、或比最近的较低档位高出 5% 以上的金额不支持钱包支付：`POST /api/v1/payments/create` 返回 `code=422`（`notSupported`），收银台则不展示钱包按钮，付款人改用卡支付。钱包订单请按 `order_no` / `merchant_order_no` 对账，不要按金额精确匹配。

**部分通道的卡金额档位。** 部分卡通道只接受固定价位（USD 9.99、10.99、11.99、12.99、13.99、14.99、17.99、19.99、24.99、29.99、30.99、39.99、49.99、59.99、99.99、124.99、129.99、149.99、199.99、249.99、299.99、399.99、499.99）。`CARD` 订单（直连或托管收银台）路由到此类通道时，HansaPay 会在创建订单时把金额**向下**取整到最接近的档位，同样以 5% 为限：请求 USD 12.50 时实收、入账与回传均为 USD 11.99，`requested_amount` 为 USD 12.50。没有档位可匹配的金额（低于 USD 9.99、高于 USD 499.99、或比最近的较低档位高出 5% 以上）会路由到其他卡通道；只有当没有任何通道能接收时，`POST /api/v1/payments/create` 才返回金额错误（`code=2006`）。每个卡档位同时也是钱包档位，因此通过快捷按钮切换为钱包的收银台订单不会被二次取整。与钱包相同，请按 `order_no` / `merchant_order_no` 对账，不要按金额精确匹配。

附加字段：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `payer.email` | string | 否 | 付款人邮箱 |
| `payer.mobile` | string | 否 | 付款人手机号 |
| `payer.user_name` | string | 否 | 用户名 |
| `payer.user_agent` | string | 否 | 浏览器 UA |
| `payer.ext_type` | string | 否 | 渠道扩展字段 |
| `payer.payer_id` | string | 否 | 钱包侧付款人标识 |
| `payer.document` | string | 否 | 付款人证件号 |

部分通道要求额外的付款人字段；缺失或格式非法会在订单
创建前被拒绝，错误信息中会指出具体字段，如 `payer.document`。

钱包支付请求示例：

```json
{
  "payment_method": "CASH_APP",
  "merchant_order_no": "M202406240003",
  "trans_amount": {
    "currency": "USD",
    "value": "49.99"
  },
  "notify_url": "https://merchant.example.com/callback/payment",
  "return_url": "https://merchant.example.com/pay/success",
  "trade_info": {
    "goods_name": "Gift Card",
    "description": "Cash App checkout"
  },
  "metadata": "channel=cashapp",
  "payer": {
    "email": "buyer@example.com",
    "payer_id": "PAYER123456"
  },
  "client_ip": "1.1.1.1"
}
```

说明：

- 钱包支付创建成功后，商户前端应直接使用 `pay_url` 跳转用户
- 当 `next_action=REDIRECT` 时，表示应立即跳转到 `pay_url`
- 钱包支付不需要再走收银台流程
- 若返回 `code=2006`，表示本次代收金额不满足当前可用通道限额

#### 成功 `data`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `payment_method` | string | 支付方式 |
| `order_no` | string | HansaPay 系统订单号 |
| `merchant_order_no` | string | 商户订单号 |
| `status` | string | 订单状态 |
| `trans_amount` | object | 金额与币种 |
| `requested_amount` | object | 你传入的金额，仅在已取整到价位时返回 |
| `next_action` | string | `REDIRECT` / `QRCODE` / `SUCCESS` / `FAILED` |
| `pay_url` | string | 钱包跳转支付地址。`next_action=REDIRECT` 时返回 |
| `qr_code` | string | 二维码支付凭证原文。`next_action=QRCODE` 时返回；目前没有可用的支付方式使用它 |
| `created_at` | string | RFC3339 创建时间 |

#### 完整成功响应示例

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "payment_method": "CASH_APP",
    "order_no": "O202406240003",
    "merchant_order_no": "M202406240003",
    "status": "PENDING",
    "trans_amount": {
      "currency": "USD",
      "value": "49.99"
    },
    "next_action": "REDIRECT",
    "pay_url": "https://wallet.example.com/redirect/pay_abc123",
    "created_at": "2026-06-24T10:03:00+08:00"
  }
}
```

## 收银台下单

`POST /api/v1/payments/checkout`

说明：

- 收银台模式创建 `payment_method=CARD` 订单并返回托管收银台页面
- 收银台模式同样接受钱包方式（`APPLE_PAY`、`GOOGLE_PAY`、`CASH_APP`），此时 `checkout_url` 即钱包支付页面
- 收到 `checkout_url` 后请立即保存。它 30 分钟后失效，查单不返回该链接，且以相同 `merchant_order_no` 重复请求会被视为重复而拒绝。链接过期仍未支付的订单保持 `CHECKOUT_REQUIRED`
- 若商户同时开通了 Apple Pay / Google Pay 通道，收银台页面会在卡表单上方展示快捷钱包按钮。付款人选择钱包后，同一笔订单（`order_no`、`merchant_order_no` 不变）会切换为 `payment_method=APPLE_PAY` / `GOOGLE_PAY` 并跳转到钱包页面，后续查单与通知均返回钱包方式及其费率快照。若金额不在钱包档位上，切换时会向下取整（见上文*钱包金额档位*）；美元订单的页面会在付款人点击前提示钱包实收金额，切换后 `requested_amount` 保留原金额。
- **由付款人选择钱包**（应您的申请由 HansaPay 为您的账户开启）：`APPLE_PAY`、`GOOGLE_PAY` 或 `CASH_APP` 的收银台请求会打开一个页面，列出您的账户在该金额下可用的所有钱包，由付款人选择其一。付款人选择之前不会扣款。订单的 `order_no` 与 `merchant_order_no` 不变；查单与通知中的 `payment_method` 为付款人所选的钱包，可能与您请求的不同。只有一种钱包可用时，收银台与未开启该设置时相同。
- 不经托管页面的服务端钱包下单请使用 `POST /api/v1/payments/create`
- 若返回 `code=2006`，表示代收金额不满足当前可用通道限额

### 与直连下单的差异

- 不传 `card`
- 不传 `billing_address`
- 不传 `device_ip`
- 由用户在收银台页面自行完成支付信息输入

### 请求核心字段

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `payment_method` | 是 | `CARD` 或钱包方式 |
| `merchant_order_no` | 是 | 商户订单号 |
| `trans_amount` | 是 | 金额与币种 |
| `notify_url` | 是 | 异步通知地址 |
| `return_url` | 否 | 支付完成跳转地址 |
| `trade_info` | 是 | 商品信息 |
| `metadata` | 否 | 商户透传参数 |
| `payer` | 否 | 付款人信息 |
| `client_ip` | 否 | 客户端 IP |
| `billing_address` | 否 | 仅 `CARD`。付款人账单地址，字段与直连卡支付相同（见 [卡支付直连](https://www.hansapay.io/docs/zh/payments#direct-card-payment)）；传入时 `country` 必填 |
| `shipping_address` | 否 | 仅 `CARD`。收货地址，字段与直连卡支付相同；传入时除 `street_number` 与 `document` 外均必填 |

- 部分卡通道由付款人在卡处理方自己的页面上输入卡信息。处理方掌握的付款人信息越多，通过率越高，因此只要您有，请传入 `payer`、`client_ip`（付款人自己的 IP，而非您服务器的 IP）、`billing_address` 与 `shipping_address`。我们自己的收银台页面会自行向付款人收集账单地址。

### 成功 `data`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `payment_method` | string | 支付方式 |
| `order_no` | string | HansaPay 系统订单号 |
| `merchant_order_no` | string | 商户订单号 |
| `status` | string | 订单状态 |
| `trans_amount` | object | 金额与币种 |
| `requested_amount` | object | 你传入的金额，仅在已取整到价位时返回 |
| `next_action` | string | 下一步动作 |
| `token` | string | 收银台 token |
| `checkout_url` | string | 收银台链接 |
| `created_at` | string | 创建时间 |

说明：

- `CARD` 时 `status` 与 `next_action` 均为 `CHECKOUT_REQUIRED`。钱包方式时 `status` 为 `PENDING`，`next_action` 为 `REDIRECT`；由付款人选择钱包时，在付款人选择之前 `status` 为 `CHECKOUT_REQUIRED`（`next_action` 仍为 `REDIRECT`）
- 部分卡通道由付款人在卡处理方自己的安全页面上输入卡信息：此时 `checkout_url` 会直接将付款人带到该页面，`status` 为 `PENDING`（`next_action` 仍为 `CHECKOUT_REQUIRED`）。无论哪种情况都请跳转到 `checkout_url`；付款人会先返回收银台结果页，再跳转到您的 `return_url`
- 若付款人在收银台页面使用了快捷钱包按钮，后续查单与通知中的 `payment_method` 将为 `APPLE_PAY` / `GOOGLE_PAY`。此时 `trans_amount` 可能低于原请求金额（钱包档位），原请求金额以 `requested_amount` 返回。卡订单路由到有卡金额档位的通道时同理（见*部分通道的卡金额档位*）。

### 完整成功响应示例

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "payment_method": "CARD",
    "order_no": "O202406240002",
    "merchant_order_no": "M202406240002",
    "status": "CHECKOUT_REQUIRED",
    "trans_amount": {
      "currency": "USD",
      "value": "49.99"
    },
    "next_action": "CHECKOUT_REQUIRED",
    "token": "5c4f0f53-c0e9-4d11-8a2b-0f3e6a1d9b27",
    "checkout_url": "https://cashier.example.com/pay/5c4f0f53-c0e9-4d11-8a2b-0f3e6a1d9b27",
    "created_at": "2026-06-24T10:05:00+08:00"
  }
}
```

## 查询支付订单

`POST /api/v1/payments/query`

### 请求字段

二选一：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `order_no` | string | 二选一 | HansaPay 系统订单号 |
| `merchant_order_no` | string | 二选一 | 商户订单号 |

### 成功 `data`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `payment_method` | string | 支付方式 |
| `order_no` | string | HansaPay 系统订单号 |
| `merchant_order_no` | string | 商户订单号 |
| `status` | string | 订单状态 |
| `trans_amount` | object | 金额 |
| `requested_amount` | object | 商户原始请求金额；仅当金额被向下取整到上游支持的价位时返回（钱包，以及部分通道的卡），此时 `trans_amount` 为实际收取金额 |
| `paid_at` | string | 支付完成时间 |
| `created_at` | string | 创建时间 |
| `masked_card_number` | string | 脱敏卡号，钱包订单通常为空 |
| `trade_info` | object | 商品信息 |
| `metadata` | string | 商户透传参数 |

订单状态取值：`PENDING`、`CHECKOUT_REQUIRED`、`3DS_VERIFICATION_REQUIRED`、`PROCESSING`、`SUCCESS`、`FAILED`、`PARTIAL_REFUNDED`、`REFUNDED`。

说明：

- 查询仍在处理中的订单时，会同时向上游获取最新状态
- 极少数情况下，已报 `FAILED` 的卡支付之后被确认已付款并变为 `SUCCESS`，并会发送新的通知

### 完整成功响应示例

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "payment_method": "CARD",
    "order_no": "O202406240001",
    "merchant_order_no": "M202406240001",
    "status": "SUCCESS",
    "trans_amount": {
      "currency": "USD",
      "value": "99.99"
    },
    "paid_at": "2026-06-24T10:01:23+08:00",
    "created_at": "2026-06-24T10:00:00+08:00",
    "masked_card_number": "411111******1111",
    "trade_info": {
      "goods_name": "VIP Membership",
      "description": "Monthly subscription"
    },
    "metadata": "biz=member&uid=10001"
  }
}
```
