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

      Accept payments

      The following paragraph describes the payment flow of the Cashier Payment product. In this flow, a wallet user is redirected from the merchant's platform to a checkout page on the wallet app. The user can authenticate and complete the payment on the checkout page before being redirected back to the merchant's platform.


      #Payment process


      cp1 Accepting payments&for AlipayCN.png

      Figure 1. Payment process of cashier payment 


      The payment process consists of the following steps:

      1. The user places an order on the merchant platform and then selects a wallet of Alipay to pay.
      2. After receiving the client request, merchant initiates a pay (/v1/payments/payrequest (step 1.1) from the server side. The merchant can obtain the wallet cashier URL based on the result returned by Alipay (step 1.2).
      3. The merchant passes the URL to the client side and redirects the user to the wallet cashier (step 1.3).
      4. After the wallet cashier guides the user to complete the payment, the user is redirected to the payment result page of the Merchant (step 3).
      5. Alipay notifies the merchant of the payment result by using the notifyPayment interface (/v1/payments/notifyPayment)The merchant receives the notification and updates the internal payment status of the order (steps 4 and 4.1).
      6. The merchant server sends an acknowledgement receipt to confirm that the payment result is received (step 4.2).


      #Before you begin

      Go through the details under Development to be clear about how to invoke an interface, and how to retrieve information required to implement the integration


      Request URL syntax is as follows:

      • Sandbox environment: https://<domain_name>/ams/sandbox/api/<endpoint>
      • Production environment: https://<domain_name>/ams/api/<endpoint>   

      where, 

      <domain_name> can be obtained from Alipay. See the View development information chapter under the Integration preparation document. Currently, the following domain names are supported, and you can select one nearby. If you need clarification on which domain to use, contact Technical support (overseas_support@service.alibaba.com).

      • open-na.alipay.com: data center located in North America.
      • open-sea.alipay.com: data center located in Asia.


      In this document, assume that the domain name used in all code samples is open-na.alipay.com


      #Optional: Use Open SDK

      You can use Alipay Global Open SDK, which encapsulates the process of adding and validating signatures to call Alipay API. For details, refer to the SDK readme.


      #1. Construct a payment request (step 1.1)

      Request URL:

      • Sandbox: https://open-na.alipay.com/ams/sandbox/api/v1/payments/pay
      • Production: https://open-na.alipay.com/ams/api/v1/payments/pay


      Parameter description:

      In the Cashier Payment scenario, specify the product code value as CASHIER_PAYMENT

      paymentRequestId is used for idempotent control.


      Request sample:

      copy
      {
          "productCode": "CASHIER_PAYMENT",
          "paymentRequestId": "pay_1089760038715669_102775745075669",
          "order": {
              "referenceOrderId": "102775745075669",
              "orderDescription": "XXX Hotel,10 Days",
              "orderAmount": {
                  "value": "50000",
                  "currency": "PHP"
              },
              "env": {
                  "terminalType": "APP",
                  "osType": "IOS"
              }
          },
          "paymentAmount": {
              "currency": "PHP",
              "value": "50000"
          },
          "paymentMethod": {
                "paymentMethodType": "GCASH"
          },
          "paymentRedirectUrl": "https://www.merchant.com/paymentResult.htm?orderId=pay_1089760038715669_102775745075669",
          "paymentNotifyUrl":"https://www.merchant.com/payNotify"
      }


      Response sample: 

      You can find the wallet cashier URL in: RedirectActionForm

      The following sample assumes that the payment is in process and waiting for the user to confirm payment in the Wallet Checkout flow.

      copy
      {
          "result": {
              "resultStatus": "U",
              "resultCode": "PAYMENT_IN_PROCESS",
              "resultMessage": "Payment is processing."
          },
          "paymentId": "212302615674274268857659685498868097avhIBxVMMX201909020000024285",
          "paymentRequestId": "pay_1029760066716669_102775765079666",
          "paymentAmount": {
              "currency": "PHP",
              "value": "800"
          },
          "RediretActionForm": {
              "redirectUrl": "https://payments.gcash.com/gcashapp/gcash-cashier-web/1.2.1/index.html#/confirm?bizNo=111111111111111",
              "method": "GET"
          }
      }


      #2. Launch user's wallet app or redirect to a WAP page (step 1.3)

      The merchant passes the wallet cashier URL retrieved from the /v1/payments/pay response to client side and launches the user's wallet app or redirects the user to a WAP page (step 1.3).


      Note:

      In this sandbox environment, only the WAP page experience is provided.

      1. Open the checkout URL (https://render.alipay.com/p/c/jzmcoal2/igg-checkout-counter.html?paymentId=212302615674274268857659685498868097avhIBxVMMX201909020000024285&callback=https%3A%2F%2Fwww.alipay.com) provided in the response of the pay request.
      2. Log in with test accounts and complete the payment. After the payment succeeds, the user will be redirected back to the merchant platform. 


      #3. Handle payment result notification (step3)

      After the user's payment succeeds, Alipay sends a payment result notification to the merchant.


      The address that is used to receive the notification is specified by paymentNotifyUrl when the merchant sends the payment request (v1/payments/pay).


      Upon receiving Alipay's notification, the merchant needs to return an acknowledgment receipt message to Alipay.


      #3.1 Monitor payment result notification on the server side

      The notification Alipay sends to the merchant is also signed, so it is recommended that the merchant verifies the signature to confirm whether the notification is sent from Alipay. For a sample code on how to verify signatures, refer to SignatureTool.verify in the Open SDK.


      Sample notification header:

      copy
      "Content-Type": "application/json",
      "Request-Time": "2019-07-12T12:08:56+05:30",
      "client-id": "T_111222333",
      "Signature": "algorithm=RSA256,keyVersion=1,signature=jTOHqknjk%2fnDjEn8lfg%2beNODdoh2eHGJV%2blvrKaDwP782WxJ7ro49giqUu23MUM8sFVVNvhg32qHS3sd4O6uf5kAVLqztqNOPJFZcjw141EVi1vrs%2bIB4vU0%2fK%2f8z2GyWUByh2lHOWFsp%2b5QKCclXp%2bjacYqWYUur5IVbuebR1LoD5IiJ7u7J9qYriFxodkxmIAJYJyJs7mks2FWHh2YePLj3K%2f4B65idy7RBKqY1NN1XcvqnbQmlfCH8CIv75bg%2fr9sGmPE5a%2bYgL8N9Q41buGwMSq1IcNsbceMbyPhw5Z5HnJ7tPz12fvdSi0cEicPikDthQ2EQFmtpntXcAc%2fHA%3d%3d"


      Sample notification body (payment succeeds):

      copy
      {
          "notifyType": "PAYMENT_RESULT",
          "result": {
              "resultCode": "SUCCESS",
              "resultStatus": "S",
              "resultMessage": "success"
          },
          "paymentRequestId": "pay_test_1106_0002", //The ID assigned by Merchant to identify the payment transaction
          "paymentId": "20200101234567890132", //The ID assigned by Alipay to identify the payment transaction
          "paymentAmount": { //The amount of the payment order, 80 EUR
              "value": "8000",
              "currency": "EUR"
          },
          "paymentCreateTime": "2020-01-01T12:01:00+08:30", //Time when the payment transaction is created
          "paymentTime": "2020-01-01T12:01:01+08:30" //Time when the payment is completed
      }


      Sample notification body (payment fails):

      copy
      {
       "notifyType":"PAYMENT_RESULT",
       "result": {
          "resultCode":"USER_BALANCE_NOT_ENOUGH",
          "resultStatus":"F",
          "resultMessage":"user balance not enough"
       },
       "paymentRequestId":"pay_test_1106_0002", 
       "paymentId":"20200101234567890132"
      }


      Content example

      Based on the notification header and body:

      copy
      POST {your_notification_endpoint/merchant/notify}
      T_111222333.2019-07-12T12:08:56+05:30.{"notifyType":"PAYMENT_RESULT","result":{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"success"},"paymentRequestId":"pay_test_1106_0002","paymentId":"20200101234567890132","paymentAmount":{"value":"8000","currency":"EUR"},"actualPaymentAmount":{"value":"8000","currency":"EUR"},"paymentCreateTime":"2020-01-01T12:01:00+08:30","paymentTime":"2020-01-01T12:01:01+08:30"}


      Verify the signature by using SDK

      Use the preceding content example, the signature enclosed in the header (the part after "signature=") "jTOHqknjk%2fnDjEn8lf....", and the Alipay public key as parameters of SignatureTool.verify.


      copy
      boolean isSuccess = SignatureTool.verify(httpMethod, path, clientId, rspTimeStr, rspBody, signature, alipayPublicKey);



      #3.2 Handle the notification

      After processing payment notifications, the merchant needs to return a receipt acknowledgment message to Alipay. Without the merchant's acknowledgment receipt, Alipay will continue sending the notification.


      Note:

      The response (a receipt acknowledgment message) sent to Alipay does not need to be signed. 


      The following samples illustrate the response header and body that the merchant sends to Alipay:


      Response header:

      copy
      "Content-Type": "application/json",
      "response-time": "2019-07-12T12:08:56+05:30",
      "client-id": "T_111222333",


      Response body:

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


      After receiving the server-side success payment  result notification from Alipay, the merchant can fulfill the purchase (for example, to deliver the goods).


      Merchants must not rely on the payment results page as the sole indicator of a successful order. The user may have closed the page before completing the payment, or an attacker may be using this payment page for malicious reasons.


      If the merchant receives repeated payment notifications from Alipay for one payment request, the merchant needs to record the processed notifications and handle the idempotence properly.


      #4. Optional: Obtain the payment result (step 4)

      Method 1: Call /v1/payments/pay to obtain the payment result. 

      Call this interface with the same paymentRequestId used in the original pay API (/v1/payments/pay) and Alipay will return the final payment status.


      Sample /v1/payments/pay request with the same paymentRequestId: 


      copy
      {
          "productCode": "CASHIER_PAYMENT",
          "paymentRequestId": "pay_1029760066716669_102775765079666",
          "order": {
          "referenceOrderId": "102775765075669",
          "orderDescription": "Mi Band 3 Wrist Strap Metal Screwless Stainless Steel For Xiaomi Mi Band 3",
          "orderAmount": {
          "value": "800",
          "currency": "PHP"
          },
        "env":{
          "terminalType":"APP",
          "osType":"IOS"
        },
        "merchant":{
          "referenceMerchantId": "seller12345678@login.com",
          "merchantName": "merchantName1234",
          "merchantMCC": "1234",
          "store": {
            "referenceStoreId": "S0000000001",
            "storeName": "storeName",
            "storeMcc": "1405"
          }
        }
          },
          "paymentAmount": {
          "value": "800",
          "currency": "PHP"
          },
          "paymentMethod": {
          "paymentMethodType": "GCASH",
          },
          "paymentRedirectUrl": "https://www.alipay.com",
          "paymentNotifyUrl": "https://www.merchant.com/notify.html"
      }


      Response: 

      copy
      {
          "result": {
              "resultStatus": "S",
              "resultCode": "SUCCESS",
              "resultMessage": "success."
          },
          "paymentId": "212302615674274268857659685498868097avhIBxVMMX201909020000024285",
          "paymentRequestId": "pay_1029760066716669_102775765079666",
          "paymentAmount": {
              "currency": "PHP",
              "value": "800"
          },
          "RediretActionForm": {
              "redirectUrl": "https://payments.gcash.com/gcashapp/gcash-cashier-web/1.2.1/index.html#/confirm?bizNo=111111111111111",
              "method": "GET"
          }
      }


      The response shows that the payment is already completed successfully.


      Method 2: Call /v1/payments/inquiryPayment if paymentId is known

      With paymentId or paymentRequestId, you can query the result of a payment by using inquiryPayment API /v1/payments/inquiryPayment.


      Request URL:

      • Sandbox environment: https://open-na.alipay.com/ams/sandbox/api/v1/payments/inquiryPayment
      • Production environment: https://open-na.alipay.com/ams/api/v1/payments/inquiryPayment
      copy
      {
          "paymentId": "212302615674274268857659685498868097avhIBxVMMX201909020000024285"
      }


      Response: 

      copy
      {
          "result": {
              "resultStatus": "S",
              "resultCode": "SUCCESS",
              "resultMessage": "success."
          },
          "paymentResultCode": "SUCCESS",
          "paymentResultMessage": "success",
          "paymentStatus": "SUCCESS",
          "paymentId": "212302615674274268857659685498868097avhIBxVMMX201909020000024285",
          "paymentRequestId": "pay_1029760066716669_102775765079666",
          "paymentAmount": {
              "currency": "PHP",
              "value": "800"
          },
          "RediretActionForm": {
              "redirectUrl": "https://payments.gcash.com/gcashapp/gcash-cashier-web/1.2.1/index.html#/confirm?bizNo=111111111111111",
              "method": "GET"
          },
          "transactions":[]
      }


      #Exceptional cases

      Payment response timeout

      Initiate a retry. The payment result is returned if the retry succeeds. Alipay supports payment idempotence, therefore, a repeated payment does not cause payment result confusion.


      Payment failed

      Take actions according to the error code returned by the pay interface (/v1/payments/pay).


      #More information

      Post-payment services

      Reports and reconciliation