Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

      Best practice

      Using the Cashier Payment product to collect payment is composed of two capabilities: cashier payment and refund. This section provides standard procedures that all involved parties can follow to integrate Cashier Payment successfully.


      #Fields and definitions

      • terminalType: the merchant terminal type that the customer uses rather than the wallet terminal type. Possible values include:
      • WEB: indicates the terminal is a PC
      • WAP: indicates the terminal is a WAP page
      • APP: indicates the terminal is a mobile app
      • osType: The merchant mobile operating system, including iOS or Android.
      • Universal Link: Allow users to intelligently follow links to content in your app or to your website in the iOS system. For more information, see iOS Universal Links.
      • App Link: A deep link that when tapped, takes the user directly to a page within a specific app. For more information, see Android App Links.
      • Alipay+ MPP: Alipay+ Mobile Payment Partner. In Cashier Payment, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash.


      #Payment process

      Payment processes involve the following four APIs:


      图片4.png

      Figure 1. Payment process


      • The user selects a wallet to initiate the payment. The merchant client obtains the user device information, order amount, and selected wallet, and calls the interface in the merchant server to place an order. (Step 1)
      • The merchant server calls the Alipay pay interface. (Step 2)
      • Alipay returns the result with the wallet URL according to the selected wallet and user device information. (Step 3)
      • The merchant client gets the wallet URL and redirects to the corresponding address. (Step 4)
      • The user confirms the transaction on the wallet side. (Step 5)
      • After the payment is successful, the wallet will be redirected back to the merchant client. (Step 6)
      • The merchant server obtains the payment result by receiving the notification from notifyPayment and actively calling the inquiryPayment interface. (Step 7)
      • If the merchant wants to abandon the transaction before obtaining the final payment result (SUCCESS or FAIL), the merchant needs to call the cancel interface. If the merchant wants to abandon the transaction when it has been paid successfully, the merchant still needs to call the cancel interface. By calling the cancel interface, the payment status of the merchant and the user will be kept consistent. (Step 9)

      Note: The payment succeeds if a result of SUCCESS being delivered from the notification or being returned by the inquiryPayment interface.

      • The merchant updates the internal transaction status. (Step 11)


      Payment result inquiry

      To obtain the payment result, the merchant needs to monitor the asynchronous notification or actively calling the inquiryPayment interface to get the payment result. Although a retransmission mechanism exists for the asynchronous notification, the asynchronous notification might not be received due to network issues when the user successfully completes the payment. Therefore, it is necessary to actively inquire the payment result with the inquiryPayment interface.


      Payment expiration time

      For cashier products, Alipay's payment expiration time is 14 minutes. The merchant can call the inquiryPayment interface in the form of polling to get the final payment result. The polling time needs to be longer than 14 minutes.


      Final payment results

      In the response of the inquiryPayment interface, the following statuses indicate the final payment result:

      • SUCCESS: The payment succeeded.
      • FAIL: The payment failed.
      • CANCELLED: The payment was canceled.

      Besides the above-mentioned final payment results, the response might also be an intermediate status:

      • PROCESSING: The payment is in progress. If this result is returned, the merchant needs to continue calling the inquiryPayment interface until a final payment result (SUCCESS, FAIL, or CANCELLED) is obtained.


      Transaction cancellation

      For payment scenarios with a specific transaction closing time of the merchant, for example, a flash sale, hotel reservation, or flight ticket purchase, conform to the following rule to ensure payment result consistency between the merchant and the user:

      When the following conditions are all met:

      • The merchant does not receive the notification.
      • No final payment result is returned for the inquiryPayment interface.
      • The merchant needs to close the transaction in advance before Alipay's payment expiration time (14 minutes).

      The cancel interface needs to be called to cancel the transaction to avoid payment result inconsistency between the merchant and user. As long as the merchant initiates the cancellation request, Alipay will guarantee that the transaction will be cancelled or refunded. By calling the cancel interface, the transaction will be cancelled if the user has not completed the payment, or refunded if the user has completed the payment.


      #Call the pay interface

      Call the pay interface to initiate a cashier payment with the following request URLs:

      • Sandbox endpoint: /ams/sandbox/api/v1/payments/pay
      • Production endpoint: /ams/api/v1/payments/pay


      #About the request

      The following fields need to be configured accordingly in the request:

      • productCode: The value needs to be CASHIER_PAYMENT.
      • paymentRequestId: This field is assigned by the merchant to uniquely identify each unique request.
      • order.orderAmount: This is the order amount of the merchant, with subfields of currency and value. The value of the value field needs to be a positive integer in the smallest currency unit, without any decimal places.
      • order.referenceOrderId: This is assigned by the merchant to identify the order. For acquirers, this field is used to identify the order of the secondary merchant.
      • order.orderDescription: This is the merchandise description.
      • order.env: This is the environment where the order is placed, such as the device information.
      • order.env.terminalType and order.env.osType: These indicate the terminal type and operating systems on which the order was placed by the user. Possible values include:

      terminalType

      osType

      WEB

      Null

      WAP

      IOS or ANDROID

      APP

      IOS or ANDROID

      Table 1. Values of terminalType and osType


      • paymentAmount: This field indicates the amount that the user needs to pay, with subfields of currency and value. The value of the value field needs to be a positive integer in the smallest currency unit, without any decimal places.
      • paymentMethod.paymentMethodType: This indicates the wallet used for payment.
      • settlementStrategy: This field is used to specify the settlement currency, especially when multiple currencies are available for settlement. When paymentMethod is AlipayCN, this field must be specified.
      • paymentRedirectUrl: This field specifies the merchant page that the user is redirected to after completing the payment. The following table shows the addresses used for different terminal types:

      terminalType of merchant

      Merchants integrated with Alipay directly

      Acquirers

      WEB

      HTTPS address for a PC website of the merchant

      HTTPS address for a PC website

      WAP

      HTTPS address for a mobile web page of the merchant

      HTTPS address for a mobile web page

      APP

      A URL scheme that can be used for redirection to the merchant app

      WAP address to a URL scheme that can be used for redirection to the merchant site  

      Table 2. Addresses for different terminal types


      • paymentNotifyUrl: This field specifies the URL used by the merchant to receive the payment result notification. The value must be an HTTPS address for security reasons.


      If no response is returned after the pay interface calling times out, call the pay interface again to get the redirectUrl. After receiving the response, take further actions according to the following graphic:

      图7.png

      Figure 2. Details about calling the pay interface


      #About the response

      The following fields in the pay interface's response must be understood correctly:

      • paymentRequestId: This field is assigned by the merchant to identify each unique request. This field will not be returned if result.resultStatus is F.
      • paymentId: This field is assigned by Alipay to identify each unique request. This field will not be returned if result.resultStatus is F.
      • paymentAmount: This field represents the amount that the user paid. The merchant can use the value of this field for comparing amounts.
      • paymentCreateTime: This field indicates the time when the payment was created
      • paymentTime: This field indicates the time when the payment was completed. If the payment failed, this field will not be returned.
      • redirectActionForm.redirectUrl: This field is suggested to be used for redirection to the wallet page. For some wallet, the orderCodeForm field might not be returned, however, redirectActionForm.redirectUrl is returned by all wallets. Therefore, use the redirectActionForm.redirectUrl for wallet page redirection is an applicable method for all wallets.


      #Redirect to wallet page

      To enter the wallet's cashier page, redirect the user to the redirectUrl. The redirectUrl is obtained in the pay interface's response.


      One redirectUrl can be used for a payment multiple times. Therefore, the payment result notification is not sent immediately, even if the payment fails more than once. The final payment result notification will only be sent after Alipay's 14-minute payment expiration time.


      The way to redirect to and open a redirectUrl address differs for three merchant terminal types:

      • WEB: Website
      • WAP: Mobile web page
      • APP: Mobile app

      Merchant terminal type

      How to open redirectUrl

      WEB

      Open in browser

      WAP

      Open in browser

      APP-IOS

      openURL

      APP-ANDROID

      startActivity

      Table 3. The way to open redirectUrl for different terminal types


      The openURL and startActivity methods can support all types of redirectUrl, therefore, it is suggested to use these methods in your system to improve the integration compatibility for all wallets. The following section provides details about the redirection process for each terminal type.


      #Merchant terminal: WEB

      For the WEB terminal, wallets provide the cashier page in different forms:

      • A redirectUrl that leads to a page where the account and password need to be entered to complete the payment.
      • A QR code that can be scanned by the user to complete the payment.


      The merchant can guide the user either directly to the cashier page that requires an account and password for payment, or the merchant page which has an embedded QR code for the user to scan.


      For Cashier Payment, different wallets provide the cashier page in different forms:

      Digital Wallet

      Forms

      Gcash

      redirectUrl

      Dana

      redirectUrl

      Touch 'n Go

      • redirectUrl (This redirectUrl page is a page with a QR code to be scanned for payment.)
      • QR code

      AlipayHK

      • redirectUrl (This redirectUrl page is a page with a QR code to be scanned for payment.)
      • QR code

      KakaoPay

      • redirectUrl (This redirectUrl page is a page with a QR code to be scanned for payment.)
      • QR code

      Table 4. Wallet-provided cashier page in different forms


      #Merchant terminal: WAP

      For the WAP terminal, wallets provide the cashier page in the form of redirectUrl. The redirectUrl might be of different types and leads to different pages:

      Digital Wallet

      Type of redirectUrl

      Page to go

      Users with wallet app installed

      Users without wallet app installed

      Gcash

      WAP page address

      A page opened by the mobile browser where the account and password are needed for payment.

      A page opened by the mobile browser where the account and password are needed for payment.

      Dana

      WAP page address

      A page opened by the mobile browser where the account and password are needed for payment.

      A page opened by the mobile browser where the account and password are needed for payment.

      Touch 'n Go

      An Apple Universal Link or Android App Link

      A WAP page that requires login account and password.

      A page opened by the mobile browser where the account and password are needed for payment.

      AlipayHK

      WAP-Scheme

      (The WAP page to evoke the app through URL scheme)

      Wallet app

      A page opened by the mobile browser where the account and password are needed for payment.

      KakaoPay

      An Apple Universal Link or Android App Link

      A WAP page with a button to open the wallet app

      A page opened by the mobile browser that displays the digital wallet app's download link. The link will redirect users to a page to download the app.

      Table 5. The redirectUrl of different types


      #Merchant terminal: APP

      For the APP terminal, wallets provide the cashier page in the form of redirectUrl. The redirectUrl might be of different types and leads to different pages. Note that redirectUrl needs to be opened by a system method, such as startActivity. Do not open the redirectUrl in app embedded WebView, container, or middle page.

      Digital Wallet

      Type of redirectUrl

      Page to go

      Users with wallet app installed

      Users without wallet app installed

      Gcash

      WAP page address

      A page opened by the mobile browser where the account and password are needed for payment.

      A page opened by the mobile browser where the account and password are needed for payment.

      Dana

      WAP page address

      A page opened by the mobile browser where the account and password are needed for payment.

      A page opened by the mobile browser where the account and password are needed for payment.

      Touch 'n Go

      An Apple Universal Link or Android App Link

      Wallet app

      A page opened by the mobile browser where the account and password are needed for payment.

      AlipayHK

      WAP-Scheme

      (The WAP page to evoke the app through URL scheme)

      Wallet app

      The digital wallet download page, opened by the mobile browser.

      KakaoPay

      An Apple Universal Link or Android App Link

      Wallet app

      The digital wallet download page, opened by the mobile browser.

      Table 6. The redirectUrl of different types


      #Tip for the redirection process

      To help the user see the payment status even when the page redirection from the wallet page to the merchant page fails, it is suggested to accept the following tip.

      In some scenarios after the payment is completed, the redirection from the wallet to the merchant page might fail. For example:

      • If the user opens the merchant page through a non-default mobile browser and then triggers the wallet app, the user completes the payment and is redirected to the default browser to open the merchant's page. However, the user's login information is not recorded in the default browser, and redirection fails.
      • Redirection failures occur due to network or compatibility reasons.


      To help the user see the payment result even if page redirection fails, it is suggested to add a pop-up notification on the payment page when redirecting to the wallet page. The pop-up window should contain two buttons: Payment Completed and Payment Not Completed. For example:

      image

      Figure 3. Pop-up notification example


      If the page fails to be redirected back after the user completes the payment, the user will return to the payment page and see the pop-up notification. The pop-up notification will guide the user to the payment result page.


      The above suggestion applies to the website, app, and WAP terminals. In addition, for a website experience, it is also suggested to open a new tab for the user when redirecting to the wallet page from the payment page. In this way, the user will easily switch between tabs if the wallet page does not open. Otherwise, the user might use the back button of the page to return to the payment page, which usually fails.


      #Process payment result

      To obtain accurate payment results, the merchant must integrate both the asynchronous notification and payment result inquiry services. Because some wallets might not return any notification when the payment fails, therefore, integrating both the asynchronous notification and payment result inquiry services will ensure the payment result being obtained from any wallet.


      When the payment is complete, the Alipay server sends an asynchronous notification to inform the merchant of the corresponding payment result. However, for some wallets, asynchronous notifications will not be sent when the payment fails. The asynchronous notification also does not have a 100% delivery guarantee.


      Therefore, it might occur that the user completes the payment but the merchant does not receive the payment result. To avoid this situation, merchants must integrate the payment result inquiry service to inquire the payment result constantly in a form of polling.


      It is suggested to use the asynchronous notification and payment result inquiry services in the following way:

      图8.png

      Figure 4. Use both the asynchronous notification and payment result inquiry services to get the payment result


      • The merchant needs to maintain an order table in the database to contain at least two fields: the order number and order status.
      • Asynchronous notification: The merchant needs to listen to Alipay's asynchronous notifications and make a response upon receiving an asynchronous notification. Then check the order status in the database:
      • If the order status is INIT, update the order status according to the asynchronous notification.
      • If the order status is not INIT, it indicates that the final payment result has been obtained through inquiry and the order status has been updated accordingly. No further actions need to be taken.
      • Inquiry: The merchant needs to initiate an active inquiry to the payment result in the form of polling. Before each inquiry, the merchant needs to check the order status in the database:
      • If the order status is INIT, initiate an inquiry. Update the order status in the database if a final payment result is obtained, otherwise, continue the polling process.
      • If the order status is not INIT, it indicates that the inquiry process has been conducted and a final payment result has been obtained and used for updating the order status. No further actions need to be taken.


      #Asynchronous notification

      After the merchant integrates the notifyPayment interface, Alipay sends the user's payment result to the merchant according to the following rules:

      • If the payment succeeds, the asynchronous notification is sent to the merchant immediately.

      • If the payment fails, the asynchronous notification is sent to the merchant after the 14-minute Alipay payment expiration time.

      • If the user does not pay, the asynchronous notification is sent to the merchant after the 14-minute Alipay payment expiration time.


      If no notification is received within 15 minutes (longer than 14 minutes) after receiving the response of the payment request, the merchant must call the inquiryPayment interface to actively inquire the payment status. Otherwise, it might occur that the user completes the payment but no payment result is received by the merchant.


      After receiving the asynchronous notification, the merchant needs to return SUCCESS to Alipay immediately. No digital signature is required. This message represents a successful receipt of the payment notification. The code sample is as follows:

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


      If the merchant doesn't send such a response to Alipay for the asynchronous notification, or the merchant response is not delivered to Alipay successfully due to network reasons, Alipay will automatically resend the asynchronous notification within 24 hours for up to 8 times or until the correct response is received. The sending intervals are as follows:

      0 minute, 2 minutes, 10 minutes, 10 minutes, 1 hour, 2 hours, 6 hours, 15 hours


      Fields in the notifyPayment request need to be understood correctly:

      • notifyType: The value is PAYMENT_RESULT for this case.
      • result.resultStatus: This field indicates the payment result of the order. Possible values include:
      • S: This indicates the payment succeeds.
      • F: This indicates the payment fails. The failure reason is indicated in resultCode.

      Note: The value of U , which represents an unknown status, is not used in this interface.

      • paymentRequestId: This field is assigned by the merchant to identify each unique request.
      • paymentId: The unique ID that is assigned by Alipay to identify a payment.
      • paymentAmount: This field represents the amount that the user paid. The merchant can use the value of this field for comparing amounts.
      • paymentCreateTime: This field indicates the time that the payment was created
      • paymentTime: This field indicates the time that the payment was completed. If the payment was failed to be paid, this field is not returned.


      #Inquiry

      Merchants can initiate the inquiryPayment interface to inquire the payment result after completing the pay interface calling, or when the payment result notification is not received within 15 minutes after receiving the response of the payment request. The following fields in the inquiryPayment interface need to be understood correctly:


      Fields in request:

      • paymentRequestId: This field is assigned by the merchant to identify each unique request. It is suggested to use this field for the inquiry process.


      Fields in response

      • result: This field only indicates the calling status of this inquiry request. It does not indicate the payment status.
      • paymentStatus: This field indicates the payment status of the order. This field is returned only when the value of result.resultStatus is S. The value of this field can be:
      • SUCCESS: This value indicates the payment succeeds. As this is a final payment status, the merchant can stop the inquiry process.
      • FAIL: This value indicates the payment failed. As this is a final payment status, the merchant can stop the inquiry process.
      • CANCELLED: This value indicates the payment is canceled. As this is a final payment status, the merchant can stop the inquiry process.
      • PROCESSING: This value indicates that the payment is still processing. This is an intermediate payment status. When this value is returned, the merchant needs to continue the inquiry process in the form of polling until a final payment status is obtained or until the asynchronous notification is received. The polling time needs to last for at least 14 minutes (Alipay's payment expiration time).


      #Cancel the transaction (if required)

      If the merchant deals with payment scenarios that have a specific transaction closing time, the cancel interface must be integrated. The merchant can initiate a payment cancellation in one of the following cases:

      • After the payment is successful and within the cancellable period. There is no fee charged for cancellation, but the cancellable period is usually only one day.
      • During the payment process, when the polling process cannot get a final payment result. The merchant can choose to terminate the transaction by calling the cancel interface to keep the transaction status consistent between the user and merchant sides.


      The following fields in the cancel interface need to be understood correctly:

      Fields in request:

      • paymentRequestId: This field is assigned by the merchant to identify each unique request. It is suggested to use this field for the cancellation process.


      Fields in response

      • result.resultStatus: This field indicates the cancellation result:
      • S: This value indicates that the cancellation succeeded.
      • F: This value indicates that the cancellation is failed. Take further actions according to resultCode.
      • U: This value indicates that the cancellation result is unknown. Use the same request parameters to retry the cancellation request. If the merchant calls the cancel request calling three times and still gets U, contact Alipay Technical Support.
      • paymentId: This field is assigned by Alipay to identify each unique request.
      • paymentRequestId: This field is assigned by the merchant to identify each unique request.
      • cancelTime: The time when the payment cancellation succeeds.


      #Refund process

      For transactions that are paid successfully, the merchant can initiate a refund via the refund interface or through the merchant portal. The refundable period is 12 months. The following fields in the refund interface need to be understood correctly:


      Fields in request:

      • refundRequestId: The unique ID assigned by the merchant to identify a refund request. This field needs to be unique for each refund request.
      • paymentId: The unique ID that is assigned by Alipay to identify a payment. Multiple partial refunds are supported for the payment.
      • refundAmount: The refund amount, where the currency needs to be consistent with that of the paymentAmount in the payment request and the value needs to be smaller than the payment amount. For multiple refunds, ensure that the total refund amount is less than or equal to the original payment amount.


      Fields in response

      • result.resultStatus: This fields indicates the refund status:
      • S: This value indicates that the refund succeeded.
      • U: This value indicates the refund result is unknown. Use the same request parameters to retry the refund request.
      • F: This value indicates that the refund is failed. Take further actions according to resultCode. For example, if a result code of MERCHANT_BALANCE_NOT_ENOUGH is returned, it indicates that the balance of the merchant to be settled is insufficient. That is, the balance of the merchant to be settled is less than the refund amount. Therefore, the merchant needs to wait until successful payments are generated and the balance of the merchant to be settled is greater than the refund amount of the transaction, then initiate the refund process again. When reinitiating the refund process, the value of request.refundRequestId must be updated.
      • refundRequestId: The unique ID assigned by the merchant to identify a refund request.
      • refundId: The unique ID assigned by Alipay to identify a refund request.
      • paymentId: The unique ID that is assigned by Alipay to identify a payment.
      • refundAmount: This field represents the refund amount. The merchant can use the value of this field for comparing amounts.
      • refundTime: The time when the refund succeeds.


      #About the payment amount and currency

      Currency related data fields exist for both APIs and reconciliation reports. One of them is the payment amount that is presented by the amount field. The amount field has subfields of currency and value. And all currency fields of Alipay APIs or reports follow the same definition.


      Amount

      Field

      Description

      currency

      MANDATORY String (3)
      The 3-letter currency code that follows
      ISO 4217 standard.

      value

      MANDATORY String (16)

      The amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY 100, a zero-decimal currency).

      Table 2. Subfields of the amount field


      Notes:

      • The wallet is specified by the value of paymentMethodType, and the corresponding currency for the wallet is specified by currency.
      • The actual value in the value field of the amount field is represented in the smallest unit of the currency. Alipay follows the ISO 4217 standard for the definition of the smallest unit of a currency.


      #Smallest unit for currencies

      Currency Code

      Smallest Unit

      (Number of the Digits after Decimal)

      Value in the Amount

      USD

      cent (2)

      1.00 USD needs to be set as "value:100"

      For example: {"currency":"USD","value":"100"}

      PHP

      cent (2)

      1.00 PHP needs to be set as "value:100"

      For example: {"currency":"PHP","value":"100"}

      IDR

      cent (2)

      1.00 IDR needs to be set as "value:100"

      For example: {"currency":"IDR","value":"100"}

      Note: For the currency of IDR, the amount value needs to be an integral multiple of 100. Otherwise, an error of PARAM_ILLEGAL is to be returned for the payment request.

      KRW

      yuan (0)

      1 KRW needs to be set as "value:1"

      For example: {"currency":"KRW","value":"1"}

      THB

      cent (2)

      1.00 THB needs to be set as "value: 100"

      For example: {"currency":"THB","value":"100"}

      HKD

      cent (2)

      1.00 HKD needs to be set as "value: 100"

      For example: {"currency":"HKD","value":"100"}

      MYR

      cent (2)

      1.00 MYR needs to be set as "value: 100"

      For example: {"currency":"MYR","value":"100"}

      CNY

      cent (2)

      1.00 CNY needs to be set as "value: 100"

      For example: {"currency":"CNY","value":"100"}

      BDT

      cent (2)

      1.00 BDT needs to be set as "value: 100"

      For example: {"currency":"BDT","value":"100"}

      PKR

      cent (2)

      1.00 PKR needs to be set as "value: 100"

      For example: {"currency":"PKR","value":"100"}

      Table 3. Details about the currency


      #Minimum payment or refund amount

      The minimum payment or refund amount differs for each wallet. The following table shows the details of the minimum payment or refund amount of each wallet.


      Wallet

      Minimum payment amount

      Minimum refund amount

      TrueMoney wallet

      1 THB


      1 THB

      Touch'n Go wallet

      0.1 MYR

      0.1 MYR

      Gcash wallet

      1 PHP

      1 PHP

      Dana wallet

      300 IDR

      300 IDR

      bKash wallet

      0.01 BDT

      0.01 BDT

      EasyPaisa wallet

      100 PKR

      100 PKR

      KakaoPay wallet

      50 KRW

      50 KRW

      Alipay HK wallet

      For Cashier Payment, the minimum payment amount is 0.1 HKD.

      Note:

      For Auto Debit, the minimum payment amount is 0.01 HKD.

      For Cashier Payment, the minimum refund amount is 0.1 HKD.

      Note:

      For Auto Debit, the minimum refund amount is 0.01 HKD.

      Table 4. The minimum payment or refund amount for different wallet.