Skip to content

创建接口 - Payout create

请求地址

HTTP
https://{{gateway_domain}}/pg/v2/payout/create

请求参数

HTTP Method

POST

HTTP Header

字段数据类型长度限制是否必填项说明
Content-TypeStringN/A字段值只支持 application/json
AcceptStringN/A字段值只支持 application/json
AuthorizationStringAuthorization: {type} {credentials},详情参考签名机制部分

HTTP Body

字段数据类型长度限制是否必填项说明
merchantTradeNoString50商户自行生成的订单号,建议商户保证唯一性
amountString18金额大小,整数 1-15 位,保留2位小数,比如:"100.05"
currencyEnum String3国际统一币种简称,表示amount金额的币种,参照国家币种表
descriptionString80订单的标题,有些场景如果消费者看到订单信息,可能会展示此字段内容
payoutMethodJSON Object支付方式信息
merchantAttachString255如使用此字段,同步/异步通知、订单查询接口将原样返回该字段值
notifyUrlString255订单在支付成功时,支付平台会通过后台调用此url通知商户
  • payoutMethod 参数说明:

    • payoutMethod 为动态参数,包含了固定字段 type,以及根据 type 的不同包含不同的字段

    • type 约定大写,取值范围:[BANK_ACCOUNT,UPI,PIX]

字段数据类型长度限制是否必填项说明
typeEnum String值为 UPI
vpaString128
payeeNameString80收款人姓名

响应结果

HTTP Header

字段数据类型是否必填项说明
Content-TypeString字段值只支持 application/json
AuthorizationStringAuthorization: {type} {credentials},详情参考签名规范部分

HTTP Body

字段数据类型是否必填项说明
codeEnum String
errorMessageString
dataJSON Object

data 字段说明

字段数据类型是否必填项说明
payoutNoString支付平台交易流水号
merchantTradeNoString商户生成的订单号
amountString订单金额
currencyEnum 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 状态码服务器繁忙调用代付查询接口,确认代付单是否已创建并获取订单状态
调用接口超时未得到响应出现这种情况,有可能是网络连通性差或者服务器繁忙造成调用代付查询接口,确认代付单是否已创建并获取订单状态