/v1/payments/pay

2021-07-21 11:23

POST /v1/payments/pay

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

Note: A payment which takes place at the wallet.

Merchant/partner initiates payment request to the wallet through Payment Interface.
The wallet will handle different payment scenarios base on the parameters in the request.

Currently, pay API supports the following acquiring scenarios:

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

Message structure

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

Request

Property	Data Type	Required	Description	Examples
partnerId	String	Yes	The partner ID, which is allocated by the wallet. Max. length: 32 characters.
appId	String	No	The mini program ID. Max. length: 32 characters.
productCode	String	No	Defined by the wallet, the wallet will use productCode to get the contract config which includes fee and limit info. Max. length: 32 characters.
paymentOrderTitle	String	Yes	The order title of this payment. Max. length: 256 characters.
paymentRequestId	String	Yes	The unique ID of a payment, which is generated by the merchant. Max. length: 64 characters. This field is used for the idempotence control. For the payment requests which are initiated with the same `paymentRequestId` and reach a final status (S or F), the Mobile Payment Partner must return the unique result.
paymentAmount	Amount	Yes	Order amount for the display of user consumption records on the payment results page.
paymentMethods	PaymentMethod	No	The paymentMethod used to collect funds by the wallet.
paymentAuthCode	String	No	If payFactor.isAgreementPay is `true`, then it's the accessToken of wallet users. If payFactor.isPaymentCode is `true`, then it's the authcode of wallet users. Max. length: 128 characters.
paymentFactor	PaymentFactor	No	In the mini program scenario, it is a fixed value, map format, {"isCashierPayment" : true}.
paymentExpiryTime	String/Datetime	No	The payment order close time, which is defined by the merchant. It follows the ISO 8601 standard.
paymentReturnUrl	String	No	The redirect URL, which is defined by the merchant. Max. length: 1024 characters.
paymentNotifyUrl	String	No	The payment success notification URL, which is defined by the merchant. Max. length: 1024 characters.
mcc	String	No	The merchant category code. Max. length: 32 characters.
extraParams	Map	No	Map format, specific payment ability which provided by the wallet. Now we only support 1 key: ORDER.
extendInfo	String	No	The extended information that wallets and merchants want to describe. Max. length: 4096 characters.	copy `{ "memo": "memo" }`
envInfo	EnvInfo	No	Environment information of mobile phone.

Response

Property	Data Type	Required	Description	Examples
result	Result	Yes	The request result, which contains information related to the request result, such as status and error codes.
paymentId	String	No	The unique ID of a payment, which is generated by the wallet. Max. length: 64 characters.
paymentTime	String/Datetime	No	Payment success time, which follows the ISO 8601 standard.
actionForm	ActionForm	No
authExpiryTime	String/Datetime	No	Authorization expiry time, which has the value only when paymentFactor.isAuthorizationPayment is `true`.
extendInfo	String	No	The extended information that wallets and merchants want to describe. Max. length: 4096 characters.	copy `{ "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
S	The transaction is successful. The merchant/partner can update the transaction to a success. What need to notice is : In the payment evaluation scenario, 'S' just means that evaluation is successful, with no real fund transfer. In the authorization payment scenario, 'S' just means that authorization is successful and needs to wait for the capture operation to finish the transaction(finish final fund flow).
A	The transaction is accepted by the wallet. Merchant/partner need continue the next step operation according to `actionForm` response. Such as display order codes to the user or redirect the user to the wallet cashier page.
F	The transaction is failed. The corresponding `result.resultCode` and `result.resultMessage` may vary based on different situations. For details, see the following Error codes section. Usually, F transactions can not be successful again when using the same payment request to call the wallet.
U	The status of the transaction 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. Merchant/partner can inquiry payment result or waiting for payment status notification to get the real payment result. What need to notice is : The payment evaluation scenario can not be inquired. U status can not be set to fail or success on the merchant/partner system. U status can not refund to users offline (Maybe will make fund loss).

Error codes

Error Code	Result Status	Error Message	Further Action
SUCCESS	S	Success
PAYMENT_IN_PROCESS	U	The payment is still under process.
ACCEPT	A	Need to perform next action according to `actionForm` response.
REPEAT_REQ_INCONSISTENT	F	Repeated submit, and requests are inconsistent.
PAYMENT_AMOUNT_EXCEED _LIMIT	F	The payment amount exceeds the limit.
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 balance is not enough for this payment.
PARTNER_NOT_EXIST	F	Partner does not exist.
PARTNER_STATUS_ABNORMAL	F	Partner status abnormal.
RISK_REJECT	F	Risk reject.
CURRENCY_NOT_SUPPORT	F	The currency is not supported.
ORDER_STATUS_INVALID	F	Order is in invalid status such closed.
INVALID_ACCESS_TOKEN	F	Invalid accesstoken.
USER_AMOUNT_EXCEED_LIMIT	F	The payment amount exceeds the user's amount limit.
EXPIRED_ACCESS_TOKEN	F	The access token is expired.
AUTH_CODE_ALREADY_USED	F	Auth code already used.
INVALID_CODE	F	Auth code illegal.
EXPIRED_AGENT_TOKEN	F	The access token of mini program is expired.
INVALID_AGENT_TOKEN	F	The access token of mini program is invalid.

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, the wallet will return payment order ID and wallet cashier page URL to merchant/partner, then merchant/partner can redirect users to wallet cashier page with my.tradePay API.

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

Request

copy

{
    "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 the wallet.
paymentRequestId is generated by merchant/partner, uniquely identifies the payment. the 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 the wallet, when merchant/partner uses the same paymentRequestIand partnerId for payment, the wallet will respond with successful payment.
productCode is defined by the wallet. The wallet will use productCode to get the contract config which includes fee and limit info.
paymentFactor: In the mini program scenario, the PaymentFactor only has a fixed value: isCashierPayment = true.
paymentReturnUrl is the URL defined by merchant/partner. In the cashier payment scenario, after a user finished payment on the wallet cashier page, the wallet will direct back to the merchant base on this URL.
paymentNotifyUrl is the URL defined by merchant/partner. In the cashier payment scenario, after a user finished payment on the wallet cashier page, the wallet will notify the merchant of the payment result base on this URL.
paymentAmount describes the amount of 100 USD to be collected by the wallet from the 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 the 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 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

copy

{
 "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 accepted success. After a user finishes payment on the cashier page, payment will change to success.
paymentId is generated by the wallet, uniquely identifies the payment.
actionForm will return the cashier page URL to merchant/partner after merchant/partner accepts the result and then will redirect to this URL.