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

      Accept payments for AlipayCN

      If you are integrating for an 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 Alipay-provided open SDK or you can call the API by your self.


      #Use Open SDK

      Alipay Global Open SDK encapsulates the process to perform the integration, including the processing of adding and validating 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 to a checkout page or his wallet app is launched where the user can complete the authentication and make the payment before being redirected to the merchant site or merchant app. 


      cp1 Accepting payments&for AlipayCN.png

      Figure 1. Payment process of Cashier payment 


      The payment process consists of the following steps:

      1. 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 Payment (/v1/payments/pay) request (step 1.1) from the server side. From the result returned from Alipay, merchant can obtain the wallet cashier URL returned by Alipay (step 1.2).
      3. 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 Payment Result Notification interface (/v1/payments/notifyPayment). Merchant receives the notification and updates the internal payment status of the order (steps 4 and 4.1).
      6. Merchant server sends an acknowledge 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/<endpoint>
      • Production environment: https://<domain_name>/ams/<endpoint> 

      where, 

      <domain_name> can be obtained from Alipay. See Integration preparation -> Viewing development information for more details. The following domain names are supported, and you can select the one nearby. Plus, if you are not sure which domain to use, contact Alipay technical support (overseas_support@service.alibaba.com) for help.

      • 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, ensure 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. About the 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. About the 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. About the 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 exactly the one you 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 the QR code page for being scanned or an H5 page redirection.


      In the sandbox environment, the QR code scan demo page and H5 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.

      image.png


      1. Enter the payment password and complete the payment.

      image.png


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

      image.png


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

      image.png


      Use the terminal type of WAP (H5)
      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 H5 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 the notification message

      You need to provide a server for receiving the notification message 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 payment that is already completed successfully. 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 to be 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 the USD currency, the settlement currency must be USD.
        • If the payment is in the CNY currency, the settlement currency must be a non-CNY currency.