/v2/payments/pay

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 the wallet through this interface.

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

Currently, this API supports the 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 the user 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

Example

appId

String 

Yes

The mini program ID.

ps:小程序的id是否使用mini-program

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 a fee, limitation information, and so on.

Max. length: 32 characters.

"202011271xxx"

paymentRequestId

String 

Yes

The unique ID of payment is 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 Issuing Participant

ps:这个改动是什么?

 must return the unique result.

"2019112719074101000700000077771xxxx"

paymentAmount

Amount

Yes

The order amount, displaying users' consumption records and payment results page.

copy
{
  "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 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.

copy
{
  "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 funds by wallets.

copy
{
  "paymentMethodType": "ID_000001xxxx",
  "paymentMethodId": "1"
}

paymentFactor

PaymentFactor

No

In the mini program scenario, it is a fixed value, map format.

copy
{
  "needSurcharge": true,
  "isPaymentEvaluation": false
}

paymentExpiryTime

String/Datetime

No

The payment order close time defined by the merchant,

which follows the

ISO 8601 standard.

"2020-06-08T12:12:12+08:00"

paymentRedirectUrl

String 

No

The redirect URL is defined by merchants.

Max. length: 1024 characters.

"https://www.merchant.com/redirectxxx"

paymentNotifyUrl

String 

No

The payment success notification URL is 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 extension information that wallets and merchants want to describe.

Max. length: 4096 characters.

copy
{
    "memo": "memo"
}

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.

copy
{
  "resultCode": "SUCCESS",
  "resultStatus": "S",
  "resultMessage": "success"
}

paymentId

String 

No

The unIque 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.

copy
{
  "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 extension 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 as follows.

resultStatus

Description 

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 transactions 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 the authorization payment scenario, 'S' just means that the authorization is successful, and needs to wait for the capture operation to finish the transaction (finish the final fund flow).

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 an unknown exception occurs on the wallet side. The merchant/partner can inquiry about 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 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).

F

That means this transaction is failed. The corresponding result.resultCode  and result.resultMessage are various 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's OpenAPIs.  
  • API-specific error codes are listed in the following table.

resultStatus

resultCode

resultMessage

Further Action

U

PAYMENT_IN_PROCESS

The payment is still under process.

A

ACCEPT

Need next actions according to the

RedirectActionForm field.

F

REPEAT_REQ_INCONSISTENT

The submitted request is not consistent with the last one.

F

PAYMENT_AMOUNT_EXCEED_LIMIT

The payment amount exceeds the limit.

F

USER_NOT_EXIST

The user does not exist.

F

USER_STATUS_ABNORMAL

The user status is abnormal.

F

USER_BALANCE_NOT_ENOUGH

The user's balance is not enough for the payment.

F

PARTNER_NOT_EXIST

The partner does not exist.

F

PARTNER_STATUS_ABNORMAL

Partner status abnormal.

F

RISK_REJECT

The payment is rejected due to risk control.

F

CURRENCY_NOT_SUPPORT

The currency is not supported.

F

ORDER_STATUS_INVALID

The order status is invalid, such as close status.

F

INVALID_ACCESS_TOKEN

The access token is invalid.

F

USER_AMOUNT_EXCEED_LIMIT

The payment amount exceeds the user's amount limit.

F

AUTH_CODE_ALREADY_USED

Auth code already used.

F

INVALID_CODE

Auth code is invalid.

F

EXPIRED_AGENT_TOKEN

The agent token of the mini program is expired.

F

INVALID_AGENT_TOKEN

The agent token of the 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 the user to wallet cashier page with the my.tradePay  API.

/v2/payments/pay
  1. The mini program creates an order.
  2. The merchant server calls this pay interface with paymentNotifyUrl to initiate payment flow.
  3. The wallet server returns payment detail information with paymentId to the merchant server.
  4. The merchant server passes the payment detail information to the mini program.
  5. The mini program calls the my.tradePay interface to conduct the payment.
  6. 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).
  7. 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 successful 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 on the wallet cashier page, the wallet will direct back to the merchant based on this URL.
  • paymentNotifyUrl is the URL defined by the merchant/partner.  In the cashier payment scenario, after the user finished payment on 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 the 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 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.

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 accepted successfully. After a user finished payment on the 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 accepted result, which will be redirected to this URL.