API 付款交易

请求

付款交易 API 使商户能够向各种收款人（包括员工、客户、供应商和商业伙伴）发起安全高效的转账。此 API 支持多个秘鲁银行机构和支付方式，提供全面的付款解决方案。

请求路径：

沙盒环境：https://sandbox-gateway.smilepayz.com/v2.0/disbursement/pay-out
生产环境：https://gateway.smilepayz.com/v2.0/disbursement/pay-out

请求头参数

字段	必填	类型	描述
Content-Type	是	String	HTTP 内容类型规范固定值：application/json 用于正确解析请求
X-TIMESTAMP	是	String	ISO 8601 日期时间格式，带时区偏移格式：yyyy-MM-ddTHH:mm:ss±HH:mm 示例：2020-12-17T10:55:00-05:00 注意：必须是当前服务器时间，误差在 ±5 分钟内
X-SIGNATURE	是	String	请求认证的数字签名参见签名生成
X-PARTNER-ID	是	String	平台分配的唯一商户标识符格式：字母数字字符串用于商户认证和交易路由请输入 merchantID

请求体参数

字段	必填	类型	描述
orderNo	是	String(32)	唯一交易标识符格式：字母数字字符串（仅数字和字母）长度：6-32 个字符必须在商户的所有交易中保持唯一
purpose	是	String(64)	交易目的或描述格式：UTF-8 编码字符串最大长度：64 个字符用于交易识别和报告
merchant	是	Object	商户信息容器包含商户识别和业务详情参见商户模型
merchantId	是	String	平台分配的主要商户标识符格式：字母数字字符串用于商户认证和交易路由
merchantName	否	String	商户业务名称，用于显示格式：UTF-8 编码字符串用于交易识别和客户显示
subMerchantId	否	String	多级商户结构的子商户标识符格式：字母数字字符串用于复杂的商户层级结构
subMerchantName	否	String	子商户业务名称，用于显示格式：UTF-8 编码字符串用于多级结构中的交易识别
money	是	Object	交易金额和货币规范包含支付金额和货币详情参见货币模型
currency	是	String	ISO 4217 货币代码规范固定值：PEN（秘鲁索尔）确定支付处理规则和结算货币
amount	是	Number	最小货币单位的交易金额格式：整数值示例：20000 表示 PEN 200.00 范围：100-999999999
paymentMethod	是	String(6)	交易处理的支付方式格式：预定义支付方式代码示例：BCP, INTERBANK, SCOTIABANK_PE 参见支付方式列表
cashAccount	是	String(32)	收款人的银行账户号格式：字母数字字符串最大长度：32 个字符必须是有效的秘鲁银行账户号
cashAccountType	是	String(32)	银行账户类型规范格式：预定义账户类型代码值：CORRIENTE（活期账户），AHORROS（储蓄账户）确定交易处理的账户类型
cci	条件	String(20)	银行间账户代码（CCI），用于更快处理格式：20 位字母数字字符串建议用于更快的支付处理和减少交易延迟
receiver	是	Object	收款人信息容器包含收款人识别和联系详情参见收款人模型
name	是	String	收款人全名，用于交易识别格式：UTF-8 编码字符串用于交易记录和收款人验证
email	是	String	收款人邮箱地址，用于通知格式：有效的邮箱地址用于交易通知和沟通
phone	是	String	收款人电话号码，用于联系格式：国际电话号码格式用于交易验证和支持
idType	是	String	身份文档类型规范格式：预定义身份类型代码值：DNI（国民身份证），CE（外国人身份证），PAS（护照），RUC（税号）确定身份验证要求
identity	是	String	身份文档号码格式：字母数字字符串必须匹配指定的 idType 格式用于收款人验证和合规
callbackUrl	否	String(256)	交易状态更新的 Webhook 通知 URL 格式：有效的 HTTP/HTTPS URL 最大长度：256 个字符用于异步交易通知

重要说明

1. 交易唯一性： orderNo 必须在您的商户账户的所有交易中保持唯一
2. 金额格式： 所有金额都以最小货币单位指定（例如，20000 = PEN 200.00）
3. 时区： 所有时间戳使用 UTC-5（秘鲁时区）
4. 银行账户： 必须是有效的秘鲁银行账户号
5. CCI 代码： 建议用于更快处理和减少延迟
6. 身份类型： DNI（国民身份证），CE（外国人身份证），PAS（护照），RUC（税号）

请求体示例 – 付款请求：

Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00-05:00
X-SIGNATURE: 7MHd9v5/m9JeqmDZVwWBZUZ5J5...7120QnFEny7Qm7uQR1G0TWCh10fsU6nVxiRoeoQ==
X-PARTNER-ID: 20001

{
    "cashAccount": "12532481501",
    "cashAccountType": "CORRIENTE",
    "cci": "12345678901234567890",
    "receiver": {
        "idType": "DNI",
        "identity": "12345678909",
        "name": "Maria Rodriguez Lopez",
        "phone": "51987654321",
        "email": "[email protected]"
    },
    "merchant": {
        "merchantId": "20001"
    },
    "money": {
        "amount": 20000,
        "currency": "PEN"
    },
    "orderNo": "2000102900000000000001",
    "paymentMethod": "BCP",
    "purpose": "2024年3月工资支付"
}

响应

HTTP 响应

字段	必填	类型	描述
Content-Type	是	String	HTTP 响应内容类型规范固定值：application/json 表示 JSON 响应格式
X-TIMESTAMP	是	String	ISO 8601 日期时间格式，带时区偏移格式：yyyy-MM-ddTHH:mm:ss±HH:mm 示例：2020-12-17T10:55:00-05:00

响应体参数

字段	必填	类型	描述
code	是	String	API 响应状态码，表示操作结果格式：两位数字字符串成功："00"，错误：其他代码用于程序化响应处理
message	是	String	人类可读的响应状态描述格式：UTF-8 编码字符串提供操作结果的详细信息根据请求语言进行本地化
orderNo	是	String	商户交易标识符格式：字母数字字符串与请求中提供的 orderNo 相同用于交易跟踪和对账
tradeNo	否	String	内部交易参考号格式：系统生成的字母数字字符串用于内部交易管理和支持
status	否	String	当前交易处理状态格式：预定义状态代码示例：PROCESSING, SUCCESS, FAILED 表示交易的当前状态参见状态模型
disbursementTime	是	String	交易处理时间戳格式：yyyy-MM-ddTHH:mm:ss±HH:mm 示例：2020-12-17T10:55:00-05:00 时区：UTC-5（秘鲁时区）
merchant	是	Object	商户信息容器包含商户识别和账户详情参见商户模型
merchantId	是	String	平台分配的主要商户标识符格式：字母数字字符串用于商户认证和交易路由
merchantName	否	String	商户业务名称，用于显示格式：UTF-8 编码字符串用于交易识别和客户显示
subMerchantId	否	String	多级商户结构的子商户标识符格式：字母数字字符串用于复杂的商户层级结构
subMerchantName	否	String	子商户业务名称，用于显示格式：UTF-8 编码字符串用于多级结构中的交易识别
accountNo	否	String	交易处理的商户账户号格式：字母数字字符串用于账户识别和余额管理
money	是	Object	交易金额和货币规范包含确认的交易金额和货币参见货币模型
currency	是	String	ISO 4217 货币代码规范固定值：PEN（秘鲁索尔）确定支付处理规则和结算货币
amount	是	Number	最小货币单位的交易金额格式：整数值示例：20000 表示 PEN 20000 范围：100-999999999
channel	是	Object	支付渠道信息容器包含支付方式和处理详情参见渠道模型
paymentMethod	是	String	用于交易处理的支付方式格式：预定义支付方式代码示例：BCP 表示实际使用的支付渠道
cashAccount	是	String	收款人的银行账户号格式：字母数字字符串用于交易验证和处理
accountName	是	String	收款人的账户持有人姓名格式：UTF-8 编码字符串用于交易验证和收款人识别

响应体示例 – 交易响应：

Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00-05:00

{
  "code": "00",
  "message": "成功",
  "orderNo": "2000102900000000000001",
  "tradeNo": "1522000109e998347483949",
  "status": "处理中",
  "disbursementTime": "2020-12-17T10:55:00-05:00",
  "merchant": {
    "merchantId": "20001",
    "merchantName": "test",
    "accountNo": "2000124234782342"
  },
  "money": {
    "currency": "PEN",
    "amount": 20000
  },
  "channel": {
    "paymentMethod": "BCP",
    "cashAccount": "12532481501",
    "accountName": "Maria Rodriguez Lopez"
  }
}

通知

HTTP 请求

字段	必填	类型	描述
Content-Type	是	String	HTTP 内容类型规范固定值：application/json 用于正确解析请求
X-TIMESTAMP	是	String	ISO 8601 日期时间格式，带时区偏移格式：yyyy-MM-ddTHH:mm:ss±HH:mm 示例：2020-12-17T10:55:00-05:00 注意：必须是当前服务器时间，误差在 ±5 分钟内
X-SIGNATURE	是	String	请求认证的数字签名参见回调签名验证

请求体参数

字段	必填	类型	描述
orderNo	是	String	商户交易标识符格式：字母数字字符串与原始请求中提供的 orderNo 相同用于交易跟踪和对账
tradeNo	是	String	内部交易参考号格式：系统生成的字母数字字符串用于内部交易管理和支持
merchantId	是	String	平台分配的主要商户标识符格式：字母数字字符串用于商户认证和交易路由
merchantName	是	String	商户业务名称，用于显示格式：UTF-8 编码字符串用于交易识别和客户显示
subMerchantId	否	String	多级商户结构的子商户标识符格式：字母数字字符串用于复杂的商户层级结构
subMerchantName	否	String	子商户业务名称，用于显示格式：UTF-8 编码字符串用于多级结构中的交易识别
paymentMethod	是	String	用于交易处理的支付方式格式：预定义支付方式代码示例：BCP 表示实际使用的支付渠道参见支付方式列表
transactionTime	是	String	交易处理时间戳格式：yyyy-MM-ddTHH:mm:ss±HH:mm 示例：2020-12-17T10:55:00-05:00 时区：UTC-5（秘鲁时区）
status	是	String	当前交易处理状态格式：预定义状态代码示例：PROCESSING, SUCCESS, FAILED, CANCELLED 表示交易的当前状态参见状态模型
money	是	Object	交易金额和货币规范包含确认的交易金额和货币参见货币模型
currency	是	String	ISO 4217 货币代码规范固定值：PEN（秘鲁索尔）确定支付处理规则和结算货币
amount	是	Number	最小货币单位的交易金额格式：整数值示例：20000 表示 PEN 20000 范围：100-999999999

重要响应要求

通知响应： 请仅返回字符串 SUCCESS 以确认收到通知

{
  "merchantId": "20001",
  "merchantName": "test",
  "money": {
    "amount": 20000,
    "currency": "PEN"
  },
  "orderNo": "2000102900000000000001",
  "status": "SUCCESS",
  "tradeNo": "1522000109e998347483949",
  "transactionTime": "2020-12-17T10:55:00-05:00"
}

SUCCESS

API 付款交易

# 请求

# 请求路径：

# 请求头参数

# 请求体参数

# 请求体示例 – 付款请求：

# 响应

# HTTP 响应

# 响应体参数

# 响应体示例 – 交易响应：

# 通知

# HTTP 请求

# 请求体参数

# 返回

请求

请求路径：

请求头参数

请求体参数

请求体示例 – 付款请求：

响应

HTTP 响应

响应体参数

响应体示例 – 交易响应：

通知

HTTP 请求

请求体参数

返回