Appearance
创建接口 - Payout create
请求地址
HTTP
https://{{gateway_domain}}/pg/v2/payout/create
请求参数
HTTP Method
POST
HTTP Header
字段 | 数据类型 | 长度限制 | 是否必填项 | 说明 |
---|---|---|---|---|
Content-Type | String | N/A | 是 | 字段值只支持 application/json |
Accept | String | N/A | 是 | 字段值只支持 application/json |
Authorization | String | 是 | Authorization: {type} {credentials},详情参考签名机制部分 |
HTTP Body
字段 | 数据类型 | 长度限制 | 是否必填项 | 说明 |
---|---|---|---|---|
merchantTradeNo | String | 50 | 是 | 商户自行生成的订单号,建议商户保证唯一性 |
amount | String | 18 | 是 | 金额大小,整数 1-15 位,保留2位小数,比如:"100.05" |
currency | Enum String | 3 | 是 | 国际统一币种简称,表示amount金额的币种,参照国家币种表 |
description | String | 80 | 是 | 订单的标题,有些场景如果消费者看到订单信息,可能会展示此字段内容 |
payoutMethod | JSON Object | 是 | 支付方式信息 | |
merchantAttach | String | 255 | 否 | 如使用此字段,同步/异步通知、订单查询接口将原样返回该字段值 |
notifyUrl | String | 255 | 是 | 订单在支付成功时,支付平台会通过后台调用此url通知商户 |
payoutMethod 参数说明:
payoutMethod 为动态参数,包含了固定字段 type,以及根据 type 的不同包含不同的字段
type 约定大写,取值范围:[BANK_ACCOUNT,UPI,PIX]
字段 | 数据类型 | 长度限制 | 是否必填项 | 说明 |
---|---|---|---|---|
type | Enum String | 是 | 值为 UPI | |
vpa | String | 128 | 是 | |
payeeName | String | 80 | 是 | 收款人姓名 |
响应结果
HTTP Header
字段 | 数据类型 | 是否必填项 | 说明 |
---|---|---|---|
Content-Type | String | 是 | 字段值只支持 application/json |
Authorization | String | 是 | Authorization: {type} {credentials},详情参考签名规范部分 |
HTTP Body
字段 | 数据类型 | 是否必填项 | 说明 |
---|---|---|---|
code | Enum String | 是 | |
errorMessage | String | 否 | |
data | JSON Object | 否 |
data 字段说明
字段 | 数据类型 | 是否必填项 | 说明 |
---|---|---|---|
payoutNo | String | 是 | 支付平台交易流水号 |
merchantTradeNo | String | 是 | 商户生成的订单号 |
amount | String | 是 | 订单金额 |
currency | Enum String | 是 | 订单的币种 |
示例
请求
SHELL
curl https://{{gateway_domain}}/pg/v2/payout/create \
-X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H 'Authorization: V2_SHA256 appId=1111b620f93b48c5904210ff47bb1111,sign=9e494e8a91bcdd08f18ad5b2cfdbfd5654f5c00c89f8216eebd7c1637b6ce01b,timestamp=1714128828114,nonce=C7CA27DC6D55DA935DFC8450C721CC99' \
-d '{
"merchantTradeNo": "MTOU-0211",
"amount": "1.00",
"currency": "INR",
"description": "upi payout test",
"payoutMethod": {
"type": "UPI",
"vpa": "[email protected]",
"payeeName": "test payeeName"
},
"merchantAttach": "merchant attach",
"notifyUrl": "https://example.com/subscribe/payout/notify",
"extendInfo": {}
}'
响应
SHELL
HTTP/1.1 200 OK
Content-Type: application/json
Server: nginx/1.18.0
Date: Mon, 06 Mar 2024 12:00:00 GMT
Authorization: V2_SHA256 appId=1111b620f93b48c5904210ff47bb1111,sign=ac6ae72f8c46f5c2092c3dab9bb0e08b6cdb6d5e7ff8ad190499a8955d57f297,timestamp=1714128245401,nonce=28FA11BF8FD1309767551B4FD8A57BD5
{
"code": "OK",
"errorMessage": null,
"data": {
"payoutNo": "20240426192048100800062197000010",
"merchantTradeNo": "MTOU-0211",
"amount": "1.00",
"currency": "INR"
}
}
商户处理建议
TIP
- 对于业务上的一笔代付订单,请勿使用不同的商户订单号调用平台接口创建订单,避免同时创建了不同的代付订单。
- 当平台返回的 code 值为
Payout.Duplicate_TradeNo
时表示已经用相同的商户订单号创建过代付订单了,请勿重复请求。
场景 | 说明 | 处理建议 |
---|---|---|
调用接口成功 | 接口返回的 code 值为 OK,data 字段不为空,包含平台创建的订单号信息 | 接收平台通知进行后续订单处理,或者调用代付查询接口主动获取订单状态 |
调用接口失败 | 接口返回的 errorMessage 字段不为空,code 字段值不等于 OK | 代付订单创建失败,请根据 code 和 errorMessage 信息调整参数,重新提交请求 code 值为 Payout.Duplicate_TradeNo 时,请勿重复提交请求 |
调用接口时出现 HTTP 4xx 状态码 | 接口权限或者签名校验问题 | 代付订单创建失败,请检查签名校验相关参数使用和逻辑是否和文档规范一致 |
调用接口时出现 HTTP 5xx 状态码 | 服务器繁忙 | 调用代付查询接口,确认代付单是否已创建并获取订单状态 |
调用接口超时未得到响应 | 出现这种情况,有可能是网络连通性差或者服务器繁忙造成 | 调用代付查询接口,确认代付单是否已创建并获取订单状态 |