/v2/payments/pay

2023-05-31 12:13

POST /v2/payments/pay

With this API call, a merchant can get the cashier page address and then redirect the user to the cashier page to make a payment.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Request header

Field	Data type	Required	Description	Example
Agent-Token	String	No	An agent token that is issued by the merchant to authorize its ISV for API calls. Specify this parameter if an ISV calls the API in behalf of a merchant.

Request parameters

Field	Data type	Required	Description	Example
appId	String	Yes	Indicates the unique ID assigned by Mini Program Platform to identify a mini program. Maximum length: 32 characters Characters not allowed: special characters such as @ # ?	"3333010071465913xxx"
customerBelongsTo	String	Yes	Indicates the super app that the user uses. Valid values are: `ALIPAY_CN`: Alipay CN `ALIPAY_HK`: Alipay HK `ALIPAY_MO`: Alipay MO `TNG`: Touch 'n Go `GCASH`: Gcash `DANA`: Dana `KAKAOPAY`: KakaoPay `BKASH`: bKash `CHOPE`: Chope `TRUEMONEY`: TrueMoney	"TNG"
paymentRequestId	String	Yes	Indicates the unique ID assigned by the merchant to identify a payment request. Maximum length: 64 characters Characters not allowed: special characters such as @ # ? Note: This field is an API idempotency field. For the payment requests which are initiated with the same paymentRequestId, the super app must return the same payment result. For details about API idempotency, see the Idempotency chapter.	"2019112719074101000700000077771xxxx"
paymentAmount	Amount	Yes	Indicates the payment amount that the merchant requests to receive.	{ "currency": "USD", "value": "10000" }
paymentOrder	PaymentOrder	No	Indicates the merchant's order details, such as order amount, goods, buyer, and so on.	{ "referenceOrderId": "OrderID_0101010101xxxx", "orderDescription": "SHOES", "orderAmount": { "currency": "USD", "value": "10000" } }
paymentExpiryTime	Datetime	No	Indicates the actual date and time when the payment is expired. The merchant then must terminate the order processing. Note: This field is defined by the merchant. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".	"2020-06-08T12:12:12+08:00"
paymentRedirectUrl	URL	No	Indicates the URL generated by the merchant to redirect the user to a specific page after the payment is completed. Maximum length: 2048 characters	"https://www.merchant.com/redirectxxx"
paymentNotifyUrl	URL	No	Indicates the URL generated by the merchant to receive the payment result notification from the super app. Maximum length: 2048 characters	"https://www.merchant.com/paymentNotifyxxx"
extendInfo	String	No	Indicates the extended information about this API. Maximum length: 4096 characters Characters not allowed: special characters such as @ # ? Can be `Null`.	{ "memo": "memo" }

Response parameters

Field	Data type	Required	Description	Example
result	Result	Yes	Indicates the request result such as status and error codes.	{ "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "success" }
paymentId	String	Yes	Indicates the unique ID assigned by the super app to identify the payment. Maximum length: 64 characters Characters not allowed: special characters such as @ # ?	"4374784884773748478499xxxx"
paymentCreateTime	Datetime	No	Indicates the actual date and time when the payment succeeded. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".	"2020-01-08T12:12:12+08:00"
redirectActionForm	RedirectActionForm	No	Indicates the URL generated by the super app to redirect users to the cashier page to make a payment.	{ "method": "POST", "redirectionUrl": "https://www.wallet.com/cashier?orderId=xxxxxxx" }
extendInfo	String	No	Indicates the extended information about this API. Maximum length: 4096 characters Characters not allowed: special characters such as @ # ? Can be `Null`.	{ "memo": "memo" }

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request. The following table describes each result status:

Result status	Description
A	The payment is already accepted by the super app. The corresponding result.resultCode is `ACCEPT` and the result.resultMessage varies based on different situations.
S	The payment is successful. The corresponding result.resultCode is `SUCCESS` and the result.resultMessage is `Success`.
U	The status of the payment is unknown. The corresponding result.resultCode is `UNKNOWN_EXCEPTION` and result.resultMessage is "An API calling is failed, which is caused by unknown reasons.". For details, see the Common error codes section.
F	The payment is failed. Usually, transactions with `F` status can not be successful again when the merchant calls this API with the same paymentRequestId. The corresponding result.resultCode and result.resultMessage vary based on different situations. For details, see the following Error codes section.

Error codes

Error codes are usually classified into the following categories:

Common error codes are common for Open APIs in V2.
API-specific error codes are listed in the following table:

Error code	Result status	Error message	Further action
ACCEPT	A	The transaction is already accepted by the super app.	Perform the next action according to the redirectActionForm field and then query the final payment result via the /v2/payments/inquiryPayment API.
PAYMENT_IN_PROCESS	U	The payment is still under process.	Query the final payment result via the /v2/payments/inquiryPayment API.
REPEAT_REQ_INCONSISTENT	F	The payment request is duplicated with the previous one.	For a new request, use another paymentRequestId.
PAYMENT_AMOUNT_EXCEED_LIMIT	F	The payment amount exceeds the limit.	Contact technical support to increase the payment amount limit. Or enter a lower payment amount and try again.
USER_AMOUNT_EXCEED_LIMIT	F	The payment amount exceeds the user's amount limit.	Enter a lower payment amount and try again.
USER_NOT_EXIST	F	The user does not exist.	-
USER_STATUS_ABNORMAL	F	The user status is abnormal.	-
USER_BALANCE_NOT_ENOUGH	F	The user's balance is not enough for the payment.	Try again later.
RISK_REJECT	F	The payment is rejected due to risk control.	Contact technical support for more details about payment risk control.
CURRENCY_NOT_SUPPORT	F	The currency of a user's payment is not supported by the super app.	Change to a supported currency and try again.
ORDER_STATUS_INVALID	F	The order status is invalid, which means the order is already paid or closed.	Check the order status via the /v2/payments/inquiryPayment API.

Samples

For example, a user places an order in a mini program and initiates a payment. Then the merchant calls this API to initiate a payment request to the super app. The data flow to complete a payment is illustrated as below:

A user places an order in the mini program.
The mini program initiates a payment request to the merchant server.
The merchant server calls the /v2/payments/pay API to initiate a payment request to the super app server.
The super app server returns the cashier page URL to the merchant server.
The merchant server returns the URL to the mini program.
The mini program redirects the user to the cashier page via the URL and calls the my.tradePay JSAPI to make the payment.
The super app service requests the super app server to process the payment.
The super app server returns the payment result to the super app service.
The super app service returns the payment result to the mini program.
The mini program returns the payment result to the user.
The super app server also calls the /v2/payments/notifyPayment API to notify the merchant server of the payment result.
The merchant server returns the result of whether it received the payment result.

Request

copy
{
    "customerBelongsTo":"TNG",
    "appId": "3333010071465913xxx", 
    "paymentRequestId": "2019112719074101000700000077771xxxx",
    "productCode": "CASHIER_PAYMENT",
    "paymentAmount": {
        "currency": "USD",
        "value": "10000"
    },
    "paymentOrder":{
        "referenceOrderId": "OrderID_0101010101xxxx",
        "orderDescription": "SHOES",
        "orderAmount": {
          "currency": "USD",
          "value": "10000"
        }
    },
    "paymentRedirectUrl":"https://www.merchant.com/redirectxxx",
    "paymentNotifyUrl":"https://www.merchant.com/paymentNotifyxxx"    
}

The user places an order at orderCreateTime (2020-01-01T12:01:01+08:30) in the miniprogram (3333010071465913xxx).
Both the total order amount and the payment amount are 100 USD.
After the user completed the payment, the user is redirected by paymentRedirectUrl (https://www.merchant.com/redirectxxx).

Response

copy
{
 "result": {
    "resultCode":"ACCEPT",
    "resultStatus":"A",
    "resultMessage":"accept"
 },
 "paymentId": "4374784884773748478499xxxx",
 "paymentCreateTime":"2020-01-01T12:02:01+08:30",
 "redirectActionForm":{
    "method":"POST",
    "redirectionUrl":"https://www.wallet.com/cashier?orderId=xxxxxxx"
 }
}

result.resultStatus is A, which shows that the payment is already accepted by the super app. After a user successfully finished payment on the cashier page, the result status will be changed to S.