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

      Accept payments for AlipayCN

      If you are integrating for the AlipayCN wallet, use this document for integration steps. This document displays a typical cashier payment product flow via API integration in the sandbox environment.


      To make integration with Alipay, you can use the Alipay-provided open SDK or you can call the API on your own.


      #Use Open SDK

      Alipay Global Open SDK encapsulates the process of performing the integration, including the adding and validating of signatures for calling Alipay APIs. For more details, refer to the SDK readme.


      #API integration

      To call Alipay APIs to accept payments, you can follow the steps provided in this section.


      #Payment process

      The following paragraphs describe 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.


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


      Main steps of the process are detailed in the following section.


      #Before you begin

      Go through the details under Development to be clear about how to invoke an interface, and how to retrieve the information that is 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. The following domain names are supported, and you can select the one nearby. If you need clarification on which domain to use, contact Technical support (overseas_support@service.alibaba.com).

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


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


      #Step 1: Create a payment

      Call the Payment interface (/v1/payments/pay) to create a payment. In this use case, make sure that the product code is CASHIER_PAYMENT.


      Request URL:


      Header:

      Replace the client-id SANDBOX_5Y055A2Y2F6K05235 with the client id that is assigned to the merchant's developer account.

      copy
      Content-Type:application/json; charset=UTF-8
      original_host:open-na.alipay.com
      Request-Time:2020-05-18T12:08:56+05:30
      client-id:SANDBOX_5Y055A2Y2F6K05235
      Signature:algorithm=RSA256,keyVersion=2,signature=TgpjpAzwmA7aWDloDEitOpYvPXT84kBXI3urHd6n0MvSQwvJM3bxeSM8UDogquQzfpnn%2f5VPmoZxHvxWdRfZcXMM3vVtVuLJcNdnaD3EPCFvsHoyzFnxBst5MEOO9dqoUhl13hGnx1BdCxsHSFTd5Wv%2b%2fmSNXhoVkYytTJ25k7VYl4YfpLMj2hSWsVvfd%2bLQ5vVq84rVRSHQQxecK%2bJqtZx92WzpD2CogRTbnHtnqMCBAhwCpfe9ZHRBC5DGvaam%2fsEtvy0C5n4tY0qOehoehWk0MIofRLHqBmLYnw6zXwVYTsdRqqVwxnoanKX9ywb6GJ%2fYPHqlAbuo2SclECe3Mg%3d%3d


      Request body:

      copy
      {
        "order": {
          "env": {
            "terminalType": "WEB"
          },
          "extendInfo": "{\"chinaExtraTransInfo\":{\"totalQuantity\":\"2\",\"businessType\":\"4\",\"goodsInfo\":\"Macbook 12 inch M3 8G 256G SSD^1|Apple iPad Pro 11 inch^1\"}}",
          "orderAmount": {
            "currency": "USD",
            "value": "100"
          },
          "orderDescription": "Macbook 12 inch M3 8G 256G SSD^1|Apple iPad Pro 11 inch^1",
          "referenceOrderId": "alipayCNOrder12345"
        },
        "paymentAmount": {
          "currency": "USD",
          "value": "100"
        },
        "paymentMethod": {
          "paymentMethodType": "ALIPAY_CN"
        },
        "paymentNotifyUrl": "http://af927046.ngrok.io",
        "paymentRedirectUrl": "https://www.taobao.com?param1=sl",
        "paymentRequestId": "ams_alipaycn_cashier_pay_sandbox_request_0001",
        "productCode": "CASHIER_PAYMENT",
        "settlementStrategy": {
          "settlementCurrency": "USD"
        }
      }


      Response:

      copy
      {
        "paymentAmount": {
          "currency": "USD",
          "value": "100"
        },
        "paymentCreateTime": "2020-06-01T17:25:10+08:00",
        "paymentId": "109251015910035106387585550135231999cwdeaACbLn202005310001917517",
        "paymentRequestId": "ams_alipaycn_cashier_pay_sandbox_request_0001",
        "redirectActionForm": {
          "method": "GET",
          "parameters": "{\"paymentExpireTime\":1591046710000,\"amountValue\":\"100\",\"paymentId\":\"109251015910035106387585550135231999cwdeaACbLn202005310001917517\",\"county\":\"US\",\"callback\":\"https://www.taobao.com?param1=sl\",\"paymentMethodType\":\"ALIPAY_CN\",\"amountCurrency\":\"USD\"}",
          "redirectUrl": "https://iopensandbox.alipay.com/alipaycn/pc/cashier"
        },
        "result": {
          "resultCode": "PAYMENT_IN_PROCESS",
          "resultMessage": "payment in process",
          "resultStatus": "U"
        }
      }


      The response shows that the payment is in process and waiting for the user to confirm the payment from the Wallet Checkout flow.


      Notes:

      1. order.extendInfo.chinaExtraTransInfo field:

      The order.extendInfo.chinaExtraTransInfo field is for extra information about the order for special use. For orders paid by AlipayCN, additional information is required as listed in the chinaExtraTransInfo object. This field is required for merchants that are directly integrated with AlipayCN, and is optional for acquirers. For example, the request body of an AlipayCN order is as below:

      copy
      "order": {
          //...
          "extendInfo": {
            "chinaExtraTransInfo": {
              "businessType": "4",
              "goodsInfo": "pencil^2|eraser^5|iPhone XS 256G^1",
              "totalQuantity": "8"
            }
          }
          //...
      }


      1. settlementStratgy.settlementCurrency field:

      This field is required for AlipayCN wallet integration. Ensure to use the settlement currency that is allowed in the contract for this field.

      1. paymentAmount.currency field:

      If you use CNY as the payment currency, you need to set the desired settlement currency. The settlement currency must not be CNY. If you use currencies other than CNY as the payment currency, ensure that the currency is specified in the contract for settlement.

      Here are examples for specifying the payment currency and settlement currency:


      Use CNY as the payment currency, and USD as the settlement currency:

      copy
      "paymentAmount": {
              "currency": "CNY",
              "value": "700"
      },
      "settlementStrategy": {
          "settlementCurrency": "USD"
      },


      Use USD as the payment currency, and USD as the settlement currency:

      copy
      "paymentAmount": {
              "currency": "USD",
              "value": "100"
      },
      "settlementStrategy": {
          "settlementCurrency": "USD"
      },


      #Step 2: Launch the user's wallet app

      You can launch the user's wallet app by using a page to display the QR code for scanning, or a WAP page redirection.


      In the sandbox environment, the QR code scan demo page and WAP demo page are provided.

      You can complete the payment by entering a random account number and password.


      Use the terminal type of WEB (QR code)
      1. Get the redirectActionForm field from the payment response.
      copy
        "redirectActionForm": {
          "method": "GET",
          "parameters": "{\"amountValue\":\"100\",\"paymentId\":\"811564915898030092746385048724835982WOSPeVnUwU202005180001827069\",\"county\":\"US\",\"callback\":\"https://www.taobao.com?param1=sl\",\"paymentMethodType\":\"ALIPAY_CN\",\"amountCurrency\":\"USD\"}",
          "redirectUrl": "https://iopensandbox.alipay.com/alipaycn/pc/cashier"
        },


      1. Make a GET operation with redirectUrl as the action value. Submit all parameters with an HTML form.


      1. Submit the form, and the QR code page is displayed.


      Note

      The QR code on the page is just a demo. In the sandbox environment, you can use the button on the right side of the page to log in with test accounts to complete the payment. Any account number or password will be accepted here. In the production environment, you need to use the AlipayCN app to scan and pay.


      The following graphic shows an example of the QR code page:

      图片1.png


      1. Enter the payment password and complete the payment.

      image.png


      1. If the payment succeeds, the following page is displayed.

      image.png


      1. The page is then automatically redirected to the specified merchant page.

      image.png


      Use the terminal type of WAP
      1. Firstly, get the redirectActionForm field from the payment response.
      copy
      "redirectActionForm": {
          "method": "GET",
          "parameters": "{\"amountValue\":\"100\",\"paymentId\":\"811564915898030092746385048724835982WOSPeVnUwU202005180001827069\",\"county\":\"US\",\"callback\":\"https://www.taobao.com?param1=sl\",\"paymentMethodType\":\"ALIPAY_CN\",\"amountCurrency\":\"USD\"}",
          "redirectUrl": "https://iopensandbox.alipay.com/alipaycn/h5/cashier"
        },


      1. Make a GET operation with redirectUrl as the action value. Submit all parameters with an HTML form.


      1. After submitting the form, the WAP page is displayed. Log in with test accounts and complete the payment. Any account number or password can be used.

      image.png


      1. The payment confirmation page is displayed after you log in successfully.

      image.png


      1. Enter the payment password. Any password can be used.

      image.png


      1. After entering the password, the page is then automatically redirected to the specified merchant page.

      image.png

      image.png


      #Step 3: Subscribe to notification messages

      You need to provide a server for receiving notification messages by specifying the value of paymentNotifyUrl in the payment request. When the payment succeeds, you will get a notification message by an HTTP POST method. 


      The following example shows the response of a successfully completed payment. And the grossSettlementAmount field indicates the actual settlement amount for the transaction.

      The notification message in the POST method:

      copy
      URL: "/"
      METHOD: "POST"
      HEADER: {"signature":"algorithm=RSA256,keyVersion=1,signature=WU1Q9em2B%2Bbe%2Fa7t8oJqzSny3%2BMugUpCj3RT4oVaabxsWa4ard22%2FFcfi%2Fgc%2FGiD%2F1LXnIwN%2BIaTQiyJJh5tI80x6kMax4cADgrIz0lC%2FZO2GMv%2FFAO7XxSSuC47wmIg8k8a4j9sfWs8VMGzFAEuSTUrX7Q8H3SPVncOA9Fwxv3pM%2FZc3mJIImXYcxMHdcvnqt1LoWukKYt%2Fzli08hBw0PvWSxI%2BbUsVG1%2Fuyin1z%2BwoWX%2FggxkISEd31MVhzWn%2F5nV7zwqtUhVV%2Bl1eIT8gBu5jg1EQ%2Fmxj9gxL1EO%2FxFxEb1V3NMIw6Jc7mJAGwozYOJ9hPZIGdx0qMqRSdRV0%2Fg%3D%3D","request-time":"2020-05-18T12:21:00Z","client-id":"SANDBOX_5Y055A2Y2F6K05235","content-type":"application/json","markuid":"0A","content-length":"491","host":"af927046.ngrok.io","user-agent":"Apache-HttpClient/4.5.6 (Java/1.8.0_172)","accept-encoding":"gzip,deflate","x-forwarded-for":"205.204.109.143"}
      BODY: "{\"grossSettlementAmount\":{\"currency\":\"USD\",\"value\":\"100\"},\"notifyType\":\"PAYMENT_RESULT\",\"notifyUrl\":\"http://af927046.ngrok.io\",\"paymentAmount\":{\"currency\":\"USD\",\"value\":\"100\"},\"paymentCreateTime\":\"2020-05-18T20:20:27+08:00\",\"paymentId\":\"812202715898044274806386466931604175JNxpyudMsn202005180001827071\",\"paymentRequestId\":\"ams_alipaycn_cashier_pay_sandbox_request_003\",\"paymentTime\":\"2020-05-18T20:20:27+08:00\",\"result\":{\"resultCode\":\"SUCCESS\",\"resultMessage\":\"success.\",\"resultStatus\":\"S\"}}"


      Details of the notification header:

      copy
      // the notify HEADER is like this
      {
        "signature": "algorithm=RSA256,keyVersion=1,signature=WU1Q9em2B%2Bbe%2Fa7t8oJqzSny3%2BMugUpCj3RT4oVaabxsWa4ard22%2FFcfi%2Fgc%2FGiD%2F1LXnIwN%2BIaTQiyJJh5tI80x6kMax4cADgrIz0lC%2FZO2GMv%2FFAO7XxSSuC47wmIg8k8a4j9sfWs8VMGzFAEuSTUrX7Q8H3SPVncOA9Fwxv3pM%2FZc3mJIImXYcxMHdcvnqt1LoWukKYt%2Fzli08hBw0PvWSxI%2BbUsVG1%2Fuyin1z%2BwoWX%2FggxkISEd31MVhzWn%2F5nV7zwqtUhVV%2Bl1eIT8gBu5jg1EQ%2Fmxj9gxL1EO%2FxFxEb1V3NMIw6Jc7mJAGwozYOJ9hPZIGdx0qMqRSdRV0%2Fg%3D%3D",
        "request-time": "2020-05-18T12:21:00Z",
        "client-id": "SANDBOX_5Y055A2Y2F6K05235",
        "content-type": "application/json",
        "markuid": "0A",
        "content-length": "491",
        "host": "af927046.ngrok.io",
        "user-agent": "Apache-HttpClient/4.5.6 (Java/1.8.0_172)",
        "accept-encoding": "gzip,deflate",
        "x-forwarded-for": "205.204.109.143"
      }
      // the notify BODY is like this
      {
        "grossSettlementAmount": {
          "currency": "USD",
          "value": "100"
        },
        "notifyType": "PAYMENT_RESULT",
        "notifyUrl": "http://af927046.ngrok.io",
        "paymentAmount": {
          "currency": "USD",
          "value": "100"
        },
        "paymentCreateTime": "2020-05-18T20:20:27+08:00",
        "paymentId": "812202715898044274806386466931604175JNxpyudMsn202005180001827071",
        "paymentRequestId": "ams_alipaycn_cashier_pay_sandbox_request_003",
        "paymentTime": "2020-05-18T20:20:27+08:00",
        "result": {
          "resultCode": "SUCCESS",
          "resultMessage": "success.",
          "resultStatus": "S"
        }
      }


      Note:

      When the payment is completed in CNY, the following notification message is received. In this case, the payment currency is CNY, and the gross settlement currency is USD.

      copy
      URL: "/"
      METHOD: "POST"
      HEADER: {"signature":"algorithm=RSA256,keyVersion=1,signature=DbhH2i6HFUmM0clhHgzvJp1ZjniTCV8f1ygj0mje4z7Q3sFLqYnYtO74vWHUTpzfQGe2VYFse7yAs7LKO5p1IPTjBGSg%2F3UfHYGR2p8O5VxlehcLz3tlzwVCzL8JrxALzqVQL23LmDjchgZL6RxpsX2PToIpmYhSEQ8xn0N7Nqh1%2FEjDc77XleaN4U0yn55TNs7nlV4XzNdHj7AP04aZs1bZkyQHeabyV1qd3NIrtbFsl92h7sDNVcM50iyCfLvMkv1x%2FmD%2Byf3aTIHH3V4EqFTLHtZ0H1B5RTbP7GNIs4tGMr3m2dX7kFhB%2BcG3yM0ZohhHoULlhl3psSvRhi3WDQ%3D%3D","request-time":"2020-05-18T12:24:00Z","client-id":"SANDBOX_5Y055A2Y2F6K05235","content-type":"application/json","markuid":"0A","content-length":"490","host":"af927046.ngrok.io","user-agent":"Apache-HttpClient/4.5.6 (Java/1.8.0_172)","accept-encoding":"gzip,deflate","x-forwarded-for":"205.204.109.83"}
      BODY: "{\"grossSettlementAmount\":{\"currency\":\"USD\",\"value\":\"14\"},\"notifyType\":\"PAYMENT_RESULT\",\"notifyUrl\":\"http://af927046.ngrok.io\",\"paymentAmount\":{\"currency\":\"CNY\",\"value\":\"100\"},\"paymentCreateTime\":\"2020-05-18T20:23:12+08:00\",\"paymentId\":\"812231215898045923636386631814585204hTuhEdqMKx202005180001827072\",\"paymentRequestId\":\"ams_alipaycn_cashier_pay_sandbox_request_004\",\"paymentTime\":\"2020-05-18T20:23:12+08:00\",\"result\":{\"resultCode\":\"SUCCESS\",\"resultMessage\":\"success.\",\"resultStatus\":\"S\"}}"
      copy
      // the notify HEADER is like this
      {
        "signature": "algorithm=RSA256,keyVersion=1,signature=DbhH2i6HFUmM0clhHgzvJp1ZjniTCV8f1ygj0mje4z7Q3sFLqYnYtO74vWHUTpzfQGe2VYFse7yAs7LKO5p1IPTjBGSg%2F3UfHYGR2p8O5VxlehcLz3tlzwVCzL8JrxALzqVQL23LmDjchgZL6RxpsX2PToIpmYhSEQ8xn0N7Nqh1%2FEjDc77XleaN4U0yn55TNs7nlV4XzNdHj7AP04aZs1bZkyQHeabyV1qd3NIrtbFsl92h7sDNVcM50iyCfLvMkv1x%2FmD%2Byf3aTIHH3V4EqFTLHtZ0H1B5RTbP7GNIs4tGMr3m2dX7kFhB%2BcG3yM0ZohhHoULlhl3psSvRhi3WDQ%3D%3D",
        "request-time": "2020-05-18T12:24:00Z",
        "client-id": "SANDBOX_5Y055A2Y2F6K05235",
        "content-type": "application/json",
        "markuid": "0A",
        "content-length": "490",
        "host": "af927046.ngrok.io",
        "user-agent": "Apache-HttpClient/4.5.6 (Java/1.8.0_172)",
        "accept-encoding": "gzip,deflate",
        "x-forwarded-for": "205.204.109.83"
      }
      // the notify BODY is like this
      {
        "grossSettlementAmount": {
          "currency": "USD",
          "value": "14"
        },
        "notifyType": "PAYMENT_RESULT",
        "notifyUrl": "http://af927046.ngrok.io",
        "paymentAmount": {
          "currency": "CNY",
          "value": "100"
        },
        "paymentCreateTime": "2020-05-18T20:23:12+08:00",
        "paymentId": "812231215898045923636386631814585204hTuhEdqMKx202005180001827072",
        "paymentRequestId": "ams_alipaycn_cashier_pay_sandbox_request_004",
        "paymentTime": "2020-05-18T20:23:12+08:00",
        "result": {
          "resultCode": "SUCCESS",
          "resultMessage": "success.",
          "resultStatus": "S"
        }
      }


      #More information

      The following currencies can be supported as payment currencies for Alipay CN wallet:

      USD, EUR, JPY, GBP, CAD, AUD, SGD, CHF, SEK, DKK, NOK, NZD, THB, HKD, and CNY.


      The following currencies can be supported as settlement currencies for Alipay CN wallet:

      USD, EUR, JPY, GBP, CAD, AUD, SGD, CHF, SEK, DKK, NOK, NZD, THB, and HKD.


      Notes:

      • The settlement currency cannot be CNY.
      • Rules for the payment and settlement currency:
        • If the payment is in a non-CNY currency, the settlement currency must be the same as the payment currency. For example, if the payment is in USD, the settlement currency must be USD.
        • If the payment is in CNY, the settlement currency must be a non-CNY currency.