Alipay International Mini Program Development PlatformAlipay International Mini Program Development PlatformDOCS

/v2/payments/pay

POST /v2/payments/pay

With this API call, a merchant can initiate a payment request to the super app. Currently, this API only supports cashier payment, which is usually used in the online payment scenario.

Structure

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

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"

productCode

String 

Yes

Indicates the code to identify a payment product. The valid value is CASHIER_PAYMENT, which means that users can pay with the super app.

"CASHIER_PAYMENT"

salesCode

String 

No

Indicates the code defined by the super app to negotiate the contract configurations such as fees, limitations, and so on.

  • Maximum length: 32 characters
  • Characters not allowed: special characters such as @ # ?
  • Can be Null.

"202011271xxx"

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 amount that users actually pay.

copy
{
  "currency": "USD",
  "value": "10000"
}

order

Order

No

Indicates the merchant's order details such as order amount, goods, and so on.

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

Yes

Indicates the methods by which the super app collects the payment.

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

paymentFactor

PaymentFactor

No

Indicates cashier payment, which allows users to pay with the super app.

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

paymentExpiryTime

Datetime

No

Indicates the actual date and time that 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 users to a specific page after users complete a payment.

  • Maximum length: 2048 characters

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

paymentNotifyUrl

URL 

No

Indicates the URL generated by the merchant to receive the payment result from the super app.

  • Maximum length: 2048 characters

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

voidNotifyUrl

URL

No

Indicates the URL generated by the merchant to receive the void result from the super app.

  • Maximum length: 2048 characters

extendInfo

String

No

Indicates the extended information about this API.

  • Maximum length: 4096 characters
  • Characters not allowed: special characters such as @ # ?
  • Can be Null.
copy
{
    "memo": "memo"
}

Response parameters

Field

Data type

Required

Description

Example

result

Result

Yes

Indicates the request result such as status and error codes.

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

paymentId

String 

Yes

Indicates the unique ID assigned by the super app to identify a payment.

  • Maximum length: 64 characters
  • Characters not allowed: special characters such as @ # ?

"4374784884773748478499xxxx"

paymentTime

Datetime

No

Indicates the actual date and time when a payment is successful. 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.

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

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 are various 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 next actions 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:

image

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

Request

{

    "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":"Merchant Name",

          "merchantDisplayName":"Merchant Name",

          "merchantAddress":{

             "region":"MY",

             "city":"KL"

          }

       },

      "env": {

          "osType": "IOS",

          "terminalType": "APP"

         } 

     },

    "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).
  • The total order amount and payment amount is 100 USD.
  • After the user completes the payment, the user is redirected by paymentRedirectUrl (https://www.merchant.com/redirectxxx).

Response

{

 "result": {

    "resultCode":"ACCEPT",

    "resultStatus":"A",

    "resultMessage":"accept"

 },

 "paymentId": "4374784884773748478499xxxx",

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