POST /v1/payments/pay

The pay API is used to initiate a payment at wallet.

Note: A payment which takes place at wallet.

1）merchant/partner initiates payment request to wallet through Payment Interface.

2）Wallet will handle different payment scenarios base on the parameters in request.

Currently, payment API support following acquiring scenarios:

• Cashier Payment：Usually used in online payment scenario. In this scenario, merchant/partner will call this payment API to create order, and wallet will return cashier page url to merchant/partner, and then redirect to this cashier page. So user can finished payment in cashier page.

Message structure

Request

Response

Result process logic

For different request results, different actions are to be performed. See the following list for details:

• result.resultStatus = S

• That means this transaction is success, merchant/partner can update transaction to success. What need to notice is :

• In payment evaluation scenario, 'S' just means evaluate success, no real fund transfer.  
• In authorization payment scenario, 'S' just means authorization success, need wait for capture operation to finish the  transaction(finish final fund flow).

• result.resultStatus = A

• That means transaction already accept by wallet. Merchant/partner need continue the next step operation according to actionForm response.  Such as display order code to user or redirect to wallet cashier page.

• result.resultStatus = F

• That means this transaction is failed, the failed reason can refer to result code param.  Usually F transactions can not be success again if use the same payment request to call wallet.

• result.resultStatus = U

• That means unknown exception occur on wallet side. Merchant/partner can inquiry payment result or waiting for payment status notification to get the real payment result. What need to notice is :

• Payment evaluation scenario can not inquiry.
• U status can not set to fail or success on merchant/partner system.
• U status can not refund to user by offline(Maybe will make fund loss).

Result

Sample

Cashier Payment

For example, a user purchases a 100 USD merchandise at the merchant/partner(online merchant usually) , merchant/partner call this payment api to create payment order first, wallet will return payment order id and wallet cashier page url to merchant/partner, then merchant/partner can redirect user to wallet cashier page with my.tradePay api.

1. Firstly the Mini Program create order (Step 1).
2. The merchant server calls /v1/payments/pay interface with paymentNotifyUrl to initiate payment flow (Step 2).
3. E-wallet server returns payment detail information with paymentId to the merchant server (Step 3).
4. The merchant server has to pass through the payment detail information to the Mini Program (step 4).
5. And the Mini Program should call my.tradePay interface to do payment (Step 5).
6. When the payment reaches the final status, e-wallet server notifies the payment result to the merchant server with paymentNotifyUrl provided in Step 2 (Step 8).
7. Also E-wallet App returns payment result to the Mini Program (Step 9).

Request

{
    "partnerId": "P000000000000001xxxx",
    "paymentRequestId": "2019112719074101000700000077771xxxx",
    "paymentOrderTitle": "SHOES",
    "productCode": "PC_5800000001",
    "mcc": "4399",
    "paymentAmount": {
        "currency": "USD",
        "value": "10000"
    },
    "paymentFactor": {
        "isCashierPayment": true
    },
    "paymentReturnUrl":"https://www.merchant.com/redirectxxx",
    "paymentNotifyUrl":"https://www.merchant.com/paymentNotifyxxx",
    "extraParams": {
        "ORDER": "{\"referenceOrderId\":\"ID_000001\",\"orderAmount\":\"{\\\"currency\\\":\\\"USD\\\",\\\"value\\\":\\\"10000\\\"}\"}"
    },
    "extendInfo": "{\"customerBelongsTo\":\"siteNameExample\"}", 
    "envInfo": {
        "osType": "IOS",
        "terminalType": "APP"
    }
}

• partnerId is the identifier of a merchant/partner, allocated by Wallet.
• paymentRequestId is generated by merchant/partner, uniquely identifies the payment. Wallet must make use of paymentRequestId and partnerId for idempotent control. For example, if a payment with paymentRequestId== 2019112719074101000700000077771xxxx and partnerId==P000000000000001xxxx  has been processed successfully by Wallet, when merchant/partner uses the same paymentRequestId  and partnerId for payment, Wallet will respond with successful payment.
• productCode defined by wallet, wallet will use productCode to get the contract config which include fee,limit info.
• paymentFactor In the Mini Program scenario, the PaymentFactor only have the fixed value: isCashierPayment = true
• paymentReturnUrl is the url defined by merchant/partner.  In cashier payment scenario, after user finished payment in wallet cashier page, wallet will direct back to merchant base on this URL.
• paymentNotifyUrl is the url defined by merchant/partner.  In cashier payment scenario, after user finished payment in wallet cashier page, wallet will notify merchant the payment result base on this URL.
• paymentAmount describes the amount of 100 USD to be collected by Wallet from user account for this payment.
• extraParams, only includes 1 key - ORDER now.  ORDER describes the order details of the purchase of the 100 USD 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.
• extendInfo, includes key - customerBelongsTo the e-wallet that the customer uses. Corresponding to the field 'siteName' that obtained from the API 'my.getSiteInfo', in the Mini Program scenario this is mandatory.

Response

{
 "result": {
    "resultCode":"ACCEPT",
    "resultStatus":"A",
    "resultMessage":"accept"
 },
 "paymentId": "string",
 "actionForm":{
    "actionFormType":"REDIRECTION",
    "redirectionUrl":"http://www.merchant.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.
• actionForm will return cashier  page url to merchant/partner,  after merchant/partner received accept result, will redirect to this URL.