Payout Create

Request URL

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

Request Parameters

HTTP Method

POST

HTTP Header

Field	Data Type	Length Limit	Required	Description
Content-Type	String	N/A	YES	This field value only supports application/json.
Accept	String	N/A	YES	This field value only supports application/json.
Authorization	String		YES	Authorization: {type} {credentials}, refer to the Signature specifications section for details.

HTTP Body

Field	Data Type	Length Limit	Required	Description
merchantTradeNo	String	50	YES	The order number generated by the merchant. It is recommended that the merchant ensures its uniqueness.
amount	String	18	YES	Amount size: integer with 1-15 digits, with 2 decimal places, e.g., '100.05'.
currency	String	3	YES	International standardized currency abbreviation, indicating the currency of the amount, refer to the country currency table.
description	String	80	YES	The order title, which may be displayed in some scenarios if the consumer sees the order information.
payoutMethod	JSON Object		YES	Pay method information
merchantAttach	String	255	NO	If this field is used, synchronous/asynchronous notifications and the order query api will return the field value as is.
notifyUrl	String	255	YES	When the order is successfully paid, the payment platform will call this URL through the background to notify the merchant.

• The description of payoutMethod field:
  • payoutMethod is a dynamic parameter that contains a fixed field type, as well as different fields depending on the type
  • type is capitalized, and the value range is [BANK_ACCOUNT,UPI,PIX,WALLET]

Field	Data Type	Length Limit	Required	Description
type	String		YES	The value is UPI
vpa	String	128	YES
payeeName	String	80	YES	Payee's Name

Response Data

HTTP Header

Field	Data Type	Required	Description
Content-Type	String	YES	This field value only supports application/json.
Authorization	String	YES	Authorization: {type} {credentials}, refer to the Signature specifications section for details.

HTTP Body

Field	Data Type	Required	Description
code	String	YES
errorMessage	String	NO
data	JSON Object	NO

The description of data field

Field	Data Type	Required	Description
payoutNo	String	YES	The transaction serial number of the payment platform
merchantTradeNo	String	YES	The order number generated by the merchant
amount	String	YES	The amount of the order
currency	String	YES	The currency of the order

Examples

Request

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": {}
}'

Response

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"
    }
}

Merchant Handling Suggestions

TIP

• For a payment order in your business, do not use different merchant order numbers to call the platform interface to create an order, so as to avoid creating different payment orders at the same time.
• When the code value returned by the platform is Payout.Duplicate_TradeNo, it means that the payment order has been created with the same merchant order number, please do not repeat the request.

Scenario	Description	Handling Suggestions
The API call succeeded	When the API response code field is OK and the data field is not empty, it contains the order number created by the platform	Receive platform notifications for further order processing, or actively obtain the order status by calling the payout query API.
The API call failed	When the errorMessage field in the API response is not empty and the code field value is not OK	Payout order creation failed. Please adjust the parameters based on the code and errorMessage information, then resubmit the request When the code value is Payout.Duplicate_TradeNo, do not resubmit the request.
HTTP 4xx status code occurred during the API call	API permission or signature verification issue	Payout order creation failed. Please check whether the usage of signature verification parameters and logic aligns with the documentation specifications.
HTTP 5xx status code occurred during the API call	The server is busy	Call the payout query API to confirm whether the payout order has been created and to retrieve the order status.
API call timed out without receiving a response	In this case, it may be caused by poor network connectivity or server traffic	Call the payout query API to confirm whether the payout order has been created and to retrieve the order status.