# 美国支付与代付接口文档

> 本文档根据提供的接口截图整理，**按接口调用顺序**组织，从【说明】→【支付（代收）】→【支付结果异步通知】→【代付】→【代付结果异步通知】，仅聚焦**美国（US）相关支付与代付**。

---

## 一、接口说明

### 1. 接口概述

本接口用于商户系统与支付平台进行对接，涵盖：
- 接口地址
- 请求/响应格式
- 签名机制
- 支付（代收）与代付流程

### 2. 接口地址

- **生产环境（正式商户对接）**
  - 生产地址：由平台运营人员提供

---

## 二、公共规则

### 1. 请求方式

- HTTP Method：`POST`
- 提交方式：`form` 表单
- Content-Type：`application/x-www-form-urlencoded; charset=UTF-8`

### 2. 字符集

- `UTF-8`

### 3. 签名机制（必选）

#### 3.1 签名规则

- 请求参数与回调参数 **都需要参与验签**
- **不参与签名的字段**：`sign`
- 参数规则：
  1. 所有参数按 **ASCII 字典序升序排列**
  2. 剔除 `value` 为空或 `null` 的字段
  3. 拼接为：`key1=value1&key2=value2...`
  4. 最后拼接商户密钥：`&key=商户密钥`

> ⚠️ 参数值 **使用原始值，不进行 URL Encode**

#### 3.2 签名算法

- MD5（32 位）
- 不区分大小写（建议统一转大写）

---

## 三、国家与币种（美国）

| 国家 | 国家编码 | 货币编码 | 推荐语言 |
|----|----|----|----|
| 美国 | US | USD | en |

---

## 四、支付（代收）接口（美国）

### 1. 接口说明

- 用于用户向商户付款
- 支持美国本地支付方式（如 CASH / APP 等）
- 下单成功后返回平台订单号

### 2. 请求方式

- `POST`（form 表单）

### 3. 请求参数（核心字段）

| 参数名 | 必填 | 类型 | 说明 |
|---|---|---|---|
| version | 是 | string | 接口版本号，如 `2.1` |
| orgNo | 是 | string | 平台分配的机构编号 |
| custId | 是 | string | 平台分配的商户编号 |
| custOrderNo | 是 | string | 商户订单号（唯一） |
| payType | 是 | string | 支付类型（如 CASH_APP、APPLE_PAY） |
| payAmt | 是 | int | 支付金额（单位：分，100=1 美元） |
| currency | 是 | string | USD |
| backUrl | 是 | string | 支付结果异步通知地址 |
| sign | 是 | string | 签名值 |

### 4. 返回参数（示例字段）

| 参数名 | 类型 | 说明 |
|---|---|---|
| code | string | 返回码，`000000` 表示成功 |
| msg | string | 返回描述 |
| prdOrdNo | string | 平台订单号 |
| sign | string | 签名 |

---

## 五、支付结果异步通知

### 1. 通知说明

- 平台根据 `backUrl` 向商户后台回调支付结果
- 商户需：
  - 验签
  - 做幂等处理（同一订单只处理一次）
- 若商户返回内容 **包含 `SC000000`**，视为回调成功

### 2. 请求方式

- `POST`（form 表单）

### 3. 通知参数

| 参数名 | 必填 | 类型 | 说明 |
|---|---|---|---|
| version | 是 | string | 版本号 |
| orgNo | 是 | string | 机构编号 |
| custId | 是 | string | 商户编号 |
| custOrderNo | 是 | string | 商户订单号 |
| prdOrdNo | 是 | string | 平台订单号 |
| payAmt | 是 | int | 支付金额 |
| ordStatus | 是 | string | 订单状态 |
| sign | 是 | string | 签名 |

#### 订单状态说明

- `00` 未交易
- `01` 成功
- `02` 失败
- `03` 被拒绝
- `04` 处理中
- `05` 已取消
- `06` 未支付
- `07` 已退款
- `08` 退款中

> 除成功和失败外，其余状态均可视为处理中

### 4. 回调成功示例

```
SC000000
```

---

## 六、代付接口（美国）

### 1. 接口说明

- 用于商户向用户付款（提现 / 打款）
- 美国代付方式：`CASH` / `CASH_APP` / `APPLE_PAY`

### 2. 请求方式

- `POST`（form 表单）

### 3. 请求参数（核心字段）

| 参数名 | 必填 | 类型 | 说明 |
|---|---|---|---|
| version | 是 | string | 版本号 |
| orgNo | 是 | string | 机构编号 |
| custId | 是 | string | 商户编号 |
| custOrderNo | 是 | string | 商户代付订单号 |
| country | 是 | string | US |
| currency | 是 | string | USD |
| payAmt | 是 | int | 代付金额（分） |
| payOutType | 是 | string | 代付方式 |
| accountName | 是 | string | 收款人姓名 |
| sign | 是 | string | 签名 |

### 4. 返回参数

| 参数名 | 类型 | 说明 |
|---|---|---|
| code | string | 返回码 |
| msg | string | 描述 |
| prdOrdNo | string | 平台代付订单号 |
| sign | string | 签名 |

---

## 七、代付结果异步通知

### 1. 通知说明

- 平台根据 `callBackUrl` 回调代付结果
- 商户需校验签名并做幂等处理
- 返回内容包含 `SC000000` 即视为成功

### 2. 请求方式

- `POST`（form 表单）

### 3. 通知参数

| 参数名 | 必填 | 类型 | 说明 |
|---|---|---|---|
| custOrderNo | 是 | string | 商户代付订单号 |
| prdOrdNo | 是 | string | 平台代付订单号 |
| payAmt | 是 | int | 代付金额 |
| ordStatus | 是 | string | 代付状态 |
| casDesc | 是 | string | 代付说明 |
| utr | 否 | string | UTR（印度专用，美国可忽略） |
| sign | 是 | string | 签名 |

#### 代付状态说明

- `00` 未处理
- `01` 待结算
- `06` 清算中
- `07` 清算完成（成功）
- `08` 清算失败
- `09` 清算撤销

> 实际状态以该字段为准，除成功 / 失败，其余均视为处理中

### 4. 回调成功示例

```
SC000000
```

---

## 八、流程总览（美国）

1. 商户发起 **支付（代收）请求**
2. 平台返回下单结果
3. 平台异步回调 **支付结果**
4. 商户发起 **代付请求**
5. 平台异步回调 **代付结果**