|
|
@@ -0,0 +1,237 @@
|
|
|
+# 美国支付与代付接口文档
|
|
|
+
|
|
|
+> 本文档根据提供的接口截图整理，**按接口调用顺序**组织，从【说明】→【支付（代收）】→【支付结果异步通知】→【代付】→【代付结果异步通知】，仅聚焦**美国（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. 平台异步回调 **代付结果**
|
Tree