admin_api/US_Payment_Payout_API_Doc.md

美国支付与代付接口文档

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