/v2/payments/pay

2022-11-17 04:34

POST /v2/payments/pay

The pay API is used to initiate a payment request to wallets.

Note: A payment which takes place at wallets.

1）The merchant/partner initiates a payment request to wallet through this interface.

2）The wallet will handle different payment scenarios based on the parameters in the request.

Currently, this API support following scenarios:

Cashier payment：Usually used in the online payment scenario. In this scenario, the merchant/partner will call this API to create an order, and the wallet will return the cashier page URL to the merchant/partner, and then redirect to this cashier page. So user can finish the payment in the cashier page.

Message structure

Request

Property	Data type	Required	Description	Example
appId	String	Yes	The Mini Program app ID. Max. length: 32 characters.	"3333010071465913xxx"
productCode	String	No	The product code, `AGREEMENT_PAYMENT, IN_STORE_PAYMENT, CASHIER_PAYMENT` Max. length: 32 characters.	"CASHIER_PAYMENT"
salesCode	String	No	Defined by wallets. The wallet uses the `salesCode` to get the contract configuration which includes fee, limitation information, and so on. Max. length: 32 characters.	"202011271xxx"
paymentRequestId	String	Yes	The unqiue ID of a payment generated by merchants. Max. length: 64 characters. This field is used for idempotence control. For the payment requests which are initiated with the same `paymentRequestId` and reach a final status (S or F), the wallet must return the unique result.	"2019112719074101000700000077771xxxx"
paymentAmount	Amount	Yes	The order amount, displaying users' consumption records, payment results page.	{ "currency": "USD", "value": "10000" }
order	Order	No	The purchase order details, such as Merchant, Buyer, Goods, etc. The information in the Order is only used to display user's payment result page and transactions history, regulation reporting, etc. It will not make use of the amount in the order for fund operation.	{ "referenceOrderId":"OrderID_0101010101xxxx", "orderDescription":"SHOES", "orderAmount":{ "currency": "USD", "value": "10000" }, "orderCreateTime": "2020-01-01T12:01:01+08:30", "merchant":{ "referenceMerchantId":"M00000000001xxxx", "merchantMCC":"1405", "merchantName":"UGG Technology Limited", "merchantDisplayName":"UGG", "merchantAddress":{ "region":"MY", "city":"KL" } }, "env": { "osType": "IOS", "terminalType": "APP" } }
paymentMethod	PaymentMethod	No	It is used to collect fund by wallets.	{ "paymentMethodType":"ID_000001xxxx", "paymentMethodId":"1" }
paymentFactor	PaymentFactor	No	In the Mini Program scenario, it is fixed value, map format.	{ "needSurcharge": true, "isPaymentEvaluation": false }
paymentExpiryTime	String/Datetime	No	The payment order close time defined by merchant, which follows the ISO 8601 standard.	"2020-06-08T12:12:12+08:00"
paymentRedirectUrl	String	No	The redirect URL defined by merchants. Max. length: 1024 characters.	"https://www.merchant.com/redirectxxx"
paymentNotifyUrl	String	No	The payment success notification URL defined by merchants. Max. length: 1024 characters.	"https://www.merchant.com/paymentNotifyxxx"
voidNotifyUrl	String(2048)	No	the url that void notification will be sent to.
extendInfo	String	No	The extensive information. The wallet and merchant can put extensive information in this property. Max. length: 4096 characters.	"This is additional information"

Response

Property	Data type	Required	Description	Example
result	Result	Yes	The request result, which contains information related to the request result, such as status and error codes.	{ "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "success" }
paymentId	String	No	The unqiue ID of a payment generated by Wallet. Max. length: 64 characters.	"4374784884773748478499xxxx"
paymentTime	String/Datetime	No	Payment success time, which follows the ISO 8601 standard.	"2020-01-08T12:12:12+08:00"
redirectActionForm	RedirectActionForm	No	Indicates a redirect URL.	{ "method":"POST", "redirectionUrl":"https://www.wallet.com/cashier?orderId=xxxxxxx" }
authExpiryTime	String/Datetime	No	The authorization expiry time, has value only when `paymentFactor.isAuthorizationPayment` is `true` .	"2020-07-08T12:12:12+08:00"
extendInfo	String	No	The extensive information. The wallet and merchant can put extensive information in this property. Max. length: 4096 characters.	"This is additional information"

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request as follows.

resultStatus	Decription
S	The corresponding `result.resultCode` is "SUCCESS" and the `result.resultMessage` is "Success". That means that this transaction is successful. The merchant/partner can update transaction to success. What needs to note is : In the payment evaluation scenario, 'S' just means that the evaluation is successful and there is no real fund transfer. In authorization payment scenario, 'S' just means that the authorization is successful, and need to wait for the capture operation to finish the transaction (finish the final fund flow).
A	The corresponding `result.resultCode` is "ACCEPT"; and the `result.resultMessage` varies based on different situations. That means that the transaction is already accepted by wallets. The merchant/partner needs to continue the next operation according to the `redirectActionForm` response, such as display the order code to users or redirect to the wallet cashier page.
U	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. That means that unknown exception occurs on the wallet side. The merchant/partner can inquiry the payment result or wait for the payment status notification to get the real payment result. What needs to note is : Payment evaluation scenario can not be inquiried. `U` status can not set to fail or success on the merchant/partner system. `U` status can not refund to users by offline (Maybe will make fund loss).
F	That means this transaction is failed. The corresponding `result.resultCode` and `result.resultMessage` vary based on different situations. For details, see the following Error codes section. Usually the `F` transactions can not be successful again if use the same payment request to call wallets.

Error codes

Error codes are usually classified into the following categories:

Common error codes: are common for all Mini Program OpenAPIs.
API-specific error codes: are listed in the following table.

resultStatus	resultCode	resultMessage
U	PAYMENT_IN_PROCESS	The payment is still under process.
A	ACCEPT	Need next actions according to the `RedirectActionForm` field.
F	REPEAT_REQ_INCONSISTENT	Repeated submission, and requests are inconsistent.
F	PAYMENT_AMOUNT_EXCEED_LIMIT	Payment amount exceeds limit.
F	USER_NOT_EXIST	User not exist.
F	USER_STATUS_ABNORMAL	The user status is abnormal.
F	USER_BALANCE_NOT_ENOUGH	User balance is not enough for this payment.
F	PARTNER_NOT_EXIST	Partner not exist.
F	PARTNER_STATUS_ABNORMAL	Partner status abnormal.
F	RISK_REJECT	Risk reject.
F	CURRENCY_NOT_SUPPORT	The currency is not supported.
F	ORDER_STATUS_INVALID	Order is in invaid status such closed.
F	INVALID_ACCESS_TOKEN	Invalid accesstoken.
F	USER_AMOUNT_EXCEED_LIMIT	Payment amount exceeds user's amount limit.
F	AUTH_CODE_ALREADY_USED	Auth code already used.
F	INVALID_CODE	Auth code illegal.
F	EXPIRED_AGENT_TOKEN	The agent token of mini program is expired.
F	INVALID_AGENT_TOKEN	The agent token of mini program is invalid.

Sample

Cashier Payment

For example, a user purchases a 100 USD good at the merchant/partner(online merchant usually) , the merchant/partner calls this API to create the payment order first, the wallet will return the payment order ID and wallet cashier page URL to the merchant/partner, then merchant/partner can redirect user to wallet cashier page with the my.tradePay API.

The Mini Program creates an order.
The merchant server calls this pay interface with paymentNotifyUrl to initialte payment flow.
E-wallet server returns payment detail information with paymentId to the merchant server.
The merchant server passes the payment detail information to the Mini Program.
The Mini Program calls the my.tradePay interface to conduct the payment.
When the payment reaches the final status, the e-wallet server notifies the merchant server of the payment result with paymentNotifyUrl provided in Step 2 (Step 8).
Also the E-wallet App returns the payment result to the Mini Program (Step 9).

Request

copy
{

    "appId": "3333010071465913xxx", 
    "paymentRequestId": "2019112719074101000700000077771xxxx",
    "productCode": "CASHIER_PAYMENT",
    "paymentAmount": {
        "currency": "USD",
        "value": "10000"
    },
    "order":{
      "referenceOrderId":"OrderID_0101010101xxxx",
      "orderDescription":"SHOES",
      "orderAmount":{
        "currency": "USD",
        "value": "10000"
      },
      "orderCreateTime": "2020-01-01T12:01:01+08:30",
      "merchant":{
          "referenceMerchantId":"M00000000001xxxx",
          "merchantMCC":"1405",
          "merchantName":"UGG Technology Limited",
          "merchantDisplayName":"UGG",
          "merchantAddress":{
             "region":"MY",
             "city":"KL"
          }
       },
      "env": {
          "osType": "IOS",
          "terminalType": "APP"
         } 
     },
    "paymentRedirectUrl":"https://www.merchant.com/redirectxxx",
    "paymentNotifyUrl":"https://www.merchant.com/paymentNotifyxxx"    
}

paymentRequestId is generated by the merchant/partner, which uniquely identifies the payment. Wallet must make use of paymentRequestId for idempotent control. For example, if a payment with paymentRequestId== 2019112719074101000700000077771 has been processed successfully by Wallet, when the merchant/partner uses the same paymentRequestId for payment, Wallet will respond with sucessful payment.
productCode is the product code, including the IN_STORE_PAYMENT , CASHIER_PAYMENT, and AGREEMENT_PAYMENT information
paymentRedirectUrl is the redirect URL defined by the merchant/partner. In the cashier payment scenario, after the user finished payment in the wallet cashier page, the wallet will direct back to merchant based on this URL.
paymentNotifyUrl is the URL defined by the merchant/partner. In the cashier payment scenario, after the user finished payment in the wallet cashier page, the wallet will notify the merchant of the payment result based on this URL.
paymentAmount describes the amount of 100 USD to be collected by Wallet from user's account for this payment.
order describes the order details of the purchase of the 100CNY merchandise by the user at the merchant. Such as Merchant, Buyer, Goods, etc are included in order . The information in the Order is only used to display user's payment result page and transactions history, regulation reporting, etc. It will not make use of the amount in the order for fund operation.

Response

copy
{
 "result": {
    "resultCode":"ACCEPT",
    "resultStatus":"A",
    "resultMessage":"accept"
 },
 "paymentId": "4374784884773748478499xxxx",
 "redirectActionForm":{
    "method":"POST",
    "redirectionUrl":"https://www.wallet.com/cashier?orderId=xxxxxxx"
 }
}

result.resultStatus ==A shows that the payment is accept success. After user finish payment in cashier page, payment will change to success.
paymentId is generated by Wallet, uniquely identifies the payment.
redirectActionForm returns the cashier page URL to the merchant/partner. After the merchant/partner receives the accept result, which will be redirected to this URL.