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

      Sandbox integration

      This page guides you through the sandbox integration as a merchant. The following graphic illustrates the steps to achieve complete merchant system development.

      sandbox integration.jpg

      Figure 1. System development process


      #Before you begin

      The following sample message contains no sensitive information, therefore, encryption is not required and only request signing and signature validation are illustrated. Before you integrate in the sandbox environment, ensure that the following information is ready. 


      Client ID and public key

      For more information about how to retrieve Client ID and public key information that you can use in the sandbox environment, see Integration preparation.


      Client Id sample:

      copy
      clientId:SANDBOX_5Y036S2Y1W4D03493

       

      Public key sample:

      copy
      MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAouaj1V+bzKl4Gb1Lqd0cEUcJ1s9X7NnqNtPcqODfxuusS3Q9GpakNyc3Oay+xng7faTSezsmFMOF72AKv/PLkyvxZawV1hcwknjfTSweWWwxmm8TDJ2gqSItKmbKQudAascMHacJLOfa/g19yuEAUULjc5ZsibD77PJ2FmP8A9xPmkRNJnu7ha/VBOOLCdZzXrysH9GBTneCDvdOx4ktn634timgqv0dpSvIt41IiDD5Ma2eMr2MAz1vViNhvYCsWuC7W71ow4g/Ub9EdOcLJd6N/BaARnY2EJSfRquq9enzgbogDfe5Nmp1NGLn6FnkCgOYjn+Cg62zj93xA3glcwIDAQAB


      Domain name

      Go to Alipay Developer Center, in Testing Resources, find the Gateway Endpoint (Domain name) under Integration Information.


      SFTP account

      Contact Technical Support (overseas_support@service.alibaba.com) to:

      1. Obtain the SFTP account that is used for accessing reports in the sandbox environment.
      2. Submit your public IP address (through which you visit the SFTP server) to whitelist the IP address.


      #Call an API

      Take the pay interface as an example and assume that the Client-Id is SANDBOX_5Y036S2Y1W4D03493 and the gateway is https://open-na.alipay.com/ams/sandbox/api/v1/payments/pay.


      #Sample request 

      Sample request message body:

      copy
      {
       "productCode": "CASHIER_PAYMENT",
       "paymentRequestId": "pay_1089760038715669_11277574501112",
       "order":{
            "referenceOrderId": "102775745075669",
            "orderDescription": "test orderDescription",
            "orderAmount":{
               "value":"100",
               "currency":"PHP"
            },
            "env":{
               "terminalType":"app"
            },
          "merchant": {
            "referenceMerchantId": "seller231117459@login.com",
            "merchantName": "cup Hu",
            "merchantMCC": "1234",
            "store": {
              "referenceStoreId": "S0000000001",
              "storeName": "UGG-2",
              "storeMcc": "1405"
            }
          }
        },
       "paymentAmount":{
          "value":"100",
          "currency":"PHP"
       },
       "paymentMethod":{
            "paymentMethodType": "GCASH"
        },
       "paymentNotifyUrl": "https://www.merchant.com/notifyUrl.htm",
       "paymentRedirectUrl": "https://www.merchant.com/redirectUrl.htm"
      }


      #Sign the request 

      1. Obtain your private key to sign the request. For more information about obtaining keys, see Integration preparation.


      1. Create the string to sign. The content to be signed is:
      copy
      <HTTP-method> <HTTP-URI-with-query-string>
      <Client-Id>.<Request-Time>.<http body>

         

      The following example illustrates how to generate the unsignedContent: 

      copy
      String unsignedContent = httpMethod + " " + path + "\n" + clientId + "." + requestTimeStr
                      + "." + reqBody;


      where,

      • httpMethod = "POST"; // Retrieve the value from http request line
      • path = "/ams/sandbox/api/v1/payments/pay"; //Retrieve the value from the http request line
      • clientId = "SANDBOX_5Y036S2Y1W4D03493"; // The unique ID assigned by Alipay to identify a merchant
      • requestTimeStr = "2020-03-23T14:00:00+08:00"; //Take the value of Request-Time from header
      • reqBody = "{

      "productCode": "CASHIER_PAYMENT",

      "paymentRequestId": "pay_1089760038715669_11277574501112",

      "order":{

           "referenceOrderId": "102775745075669",

           "orderDescription": "test orderDescription",

           "orderAmount":{

              "value":"100",

              "currency":"PHP"

           },

           "env":{

              "terminalType":"app"

           },

         "merchant": {

           "referenceMerchantId": "seller231117459@login.com",

           "merchantName": "cup Hu",

           "merchantMCC": "1234",

           "store": {

             "referenceStoreId": "S0000000001",

             "storeName": "UGG-2",

             "storeMcc": "1405"

           }

         }

       },

      "paymentAmount":{

         "value":"100",

         "currency":"PHP"

      },

      "paymentMethod":{

           "paymentMethodType": "GCASH"

       },

      "paymentNotifyUrl": "https://www.merchant.com/notifyUrl.htm",

      "paymentRedirectUrl": "https://www.merchant.com/redirectUrl.htm"

      }"; // The request body


      In this sample, the value of Request-Time is 2020-03-23T14:00:00+08:00. The generated content to be signed unsignedContent is:

      copy
      POST /ams/sandbox/api/v1/payments/pay
      SANDBOX_5Y036S2Y1W4D03493.2020-03-23T14:00:00+08:00.{
       "productCode": "CASHIER_PAYMENT",
       "paymentRequestId": "pay_1089760038715669_11277574501112",
       "order":{
            "referenceOrderId": "102775745075669",
            "orderDescription": "test orderDescription",
            "orderAmount":{
               "value":"100",
               "currency":"PHP"
            },
            "env":{
               "terminalType":"app"
            },
          "merchant": {
            "referenceMerchantId": "seller231117459@login.com",
            "merchantName": "cup Hu",
            "merchantMCC": "1234",
            "store": {
              "referenceStoreId": "S0000000001",
              "storeName": "UGG-2",
              "storeMcc": "1405"
            }
          }
        },
       "paymentAmount":{
          "value":"100",
          "currency":"PHP"
       },
       "paymentMethod":{
            "paymentMethodType": "GCASH"
        },
       "paymentNotifyUrl": "https://www.merchant.com/notifyUrl.htm",
       "paymentRedirectUrl": "https://www.merchant.com/redirectUrl.htm"
      }


      1. Generate the signature. Use the algorithm and private key obtained in step 1 to generate the signature. The following example assumes that RSA256 algorithm is used to generate the signature. Use the following code to perform the base64 URL encoding and generate the signature:
      copy
      base64UrlEncode(sha256withrsa(<unsignedContent>), <privateKey>))


      The generated signature:

      copy
      Oi50a6hX%2f7XgyX6NbAjlyU523gB2AhVKhJGxW%2f3ezjwUhzMnEmbMdznvVtXwtO%2fg2iLic3B%2ftpnxl7FYtGhQfal5ivvr3IMEjC%2bbT2%2b6%2bNuMwdeDSWq2dXyaY44wyhQFqzzfwdOg%2bX2TTGSzRpSN3KHFoGNUHMRxZElfw%2bz13neDJ9fnpr%2f4r6qrDnSB2eoGe293ez1bUFwtoM2sYGUP2vvXrLnaB%2bAEojLjiA1MY14%2bXD55RMBBwTOofteCEwgXwWFb6T6XFjlKK7Up7v2ps7IaOjo8QYHhgPMcxddpIh7JK9jwOej%2fWsL%2f3kckS6wy1OTyruUFq%2f7Ox1mTuzIxsg%3d%3d


      1. Add the signature to the header. Assemble the signature algorithm, the key version used for the signature, and the signature into the Signature header. The following example shows a finished Signature header: 
      copy
      key: Signature ;
      value:algorithm=<algorithm>,keyVersion=<key-version>,signature=<signature>


      Sample:

      copy
      "Signature": "algorithm=RSA256,keyVersion=1,signature=Oi50a6hX%2f7XgyX6NbAjlyU523gB2AhVKhJGxW%2f3ezjwUhzMnEmbMdznvVtXwtO%2fg2iLic3B%2ftpnxl7FYtGhQfal5ivvr3IMEjC%2bbT2%2b6%2bNuMwdeDSWq2dXyaY44wyhQFqzzfwdOg%2bX2TTGSzRpSN3KHFoGNUHMRxZElfw%2bz13neDJ9fnpr%2f4r6qrDnSB2eoGe293ez1bUFwtoM2sYGUP2vvXrLnaB%2bAEojLjiA1MY14%2bXD55RMBBwTOofteCEwgXwWFb6T6XFjlKK7Up7v2ps7IaOjo8QYHhgPMcxddpIh7JK9jwOej%2fWsL%2f3kckS6wy1OTyruUFq%2f7Ox1mTuzIxsg%3d%3d"


      #Construct the request 

      In this example, the request is sent by using cURL. Add Client-Id, Request-Time, and Signature to the request header:

      copy
      curl -X POST \
        https://open-na.alipay.com/ams/sandbox/api/v1/payments/pay \
        -H 'Content-Type: application/json; charset=UTF-8' \
        -H 'Client-Id: SANDBOX_5Y036S2Y1W4D03493' \
        -H 'Request-Time: 2020-03-23T14:00:00+08:00' \
        -H 'Signature: algorithm=RSA256, keyVersion=1, signature=Oi50a6hX%2f7XgyX6NbAjlyU523gB2AhVKhJGxW%2f3ezjwUhzMnEmbMdznvVtXwtO%2fg2iLic3B%2ftpnxl7FYtGhQfal5ivvr3IMEjC%2bbT2%2b6%2bNuMwdeDSWq2dXyaY44wyhQFqzzfwdOg%2bX2TTGSzRpSN3KHFoGNUHMRxZElfw%2bz13neDJ9fnpr%2f4r6qrDnSB2eoGe293ez1bUFwtoM2sYGUP2vvXrLnaB%2bAEojLjiA1MY14%2bXD55RMBBwTOofteCEwgXwWFb6T6XFjlKK7Up7v2ps7IaOjo8QYHhgPMcxddpIh7JK9jwOej%2fWsL%2f3kckS6wy1OTyruUFq%2f7Ox1mTuzIxsg%3d%3d' \
        -d \
      '{
       "productCode": "CASHIER_PAYMENT",
       "paymentRequestId": "pay_1089760038715669_11277574501112",
       "order":{
            "referenceOrderId": "102775745075669",
            "orderDescription": "test orderDescription",
            "orderAmount":{
               "value":"100",
               "currency":"PHP"
            },
            "env":{
               "terminalType":"app"
            },
          "merchant": {
            "referenceMerchantId": "seller231117459@login.com",
            "merchantName": "cup Hu",
            "merchantMCC": "1234",
            "store": {
              "referenceStoreId": "S0000000001",
              "storeName": "UGG-2",
              "storeMcc": "1405"
            }
          }
        },
       "paymentAmount":{
          "value":"100",
          "currency":"PHP"
       },
       "paymentMethod":{
            "paymentMethodType": "GCASH"
        },
       "paymentNotifyUrl": "https://www.merchant.com/notifyUrl.htm",
       "paymentRedirectUrl": "https://www.merchant.com/redirectUrl.htm"
      }'


      For more information about message structure, message fields, and message transmission, see API fundamentals.


      #Handle the response

      After you receive a response, you need to validate the signature of the response.


      #Receive the response

      The response consists of the response header and the response body. 


      Sample response header:

      copy
      Client-Id: SANDBOX_5Y036S2Y1W4D03493
      Response-Time: 2020-03-23T06:08:53Z
      Signature: algorithm=RSA256, keyVersion=1,
      signature=Pz5cU8WFyOPteA9gyvbXbXIes9JHNafmv6hXWuwU0rC%2bSmnZpzGf3lGPkmGVWK6YptKRluHt9yGsfZhtPH%2bbZBG50fXHv%2bKVhJw4uLVOKcAK4wwP2PPnW4ICHjSqqqbuBIADVIeEoRXcxsUKtNH%2btoWmdtFnYtYFK%2fRXYgxvF1%2f6TK5SafrsEZCHXwVvzAqd1HG2Qs2UK6QEkZ5u3U6LSoXzGwSnB4usWkSRw2GP69fHUYWfi5r7AfjhDs%2bcZrUnlKCXpUAmeEGNJs8NTeV0GlYt3DCFVNwMc%2f%2bnJ%2bkwd%2fzi29cpAYCPzEdK6Qt8m8OEG6Hn0WtRew7EYrXwY0jpEg%3d%3d
      Trace-Id: 0bfdda6f15815956184685437e0764.0.1.1

      Sample response body:

      copy
      {
          "paymentAmount": {
              "currency": "PHP",
              "value": "100"
          },
          "paymentCreateTime": "2020-03-23T11:54:08+08:00",
          "paymentId": "303540815849356482956531350278548000unSJuoDrlP202003220001430724",
          "paymentRequestId": "pay_1089760038715669_11277574501112",
          "redirectActionForm": {
              "method": "GET",
              "redirectUrl": "https://render.alipay.com/p/c/jzmcoal2/igg-checkout-counter.html?paymentId=303540815849356482956531350278548000unSJuoDrlP202003220001430724&callback=https%3A%2F%2Fwww.merchant.com%2FredirectUrl.htm&amountValue=100&amountCurrency=PHP&merchantName=cup%20Hu"
          },
          "result": {
              "resultCode": "PAYMENT_IN_PROCESS",
              "resultMessage": "payment in process",
              "resultStatus": "U"
          }
      }


      #Validate the signature 

      Use the following information to validate the signature: 

      • Alipay public key: <alipayPublicKey> 
      • Algorithm: sha256withrsa_verify(base64UrlDecode(<signature>), <content_to_be_verified>, <alipayPublicKey>) 


      The signature verification process consists of the following steps: 

      1. Obtain the public key, see Preparing keys for details. Obtain Client-Id and algorithm from the header.

      2. Create the string to be validated. The string to be validated unsignedContent is: 

      copy
      String unsignedContent = httpMethod + " " + path + "\n" + clientId + "." + responseTimeStr + "." + rspBody;


      where,

      • httpMethod = "POST";     //Take the value of request method out of the http request line
      • path = "/ams/sandbox/api/v1/payments/pay"; // Take the value from the http request line
      • clientId = "SANDBOX_5Y036S2Y1W4D03493"; // The unique ID assigned by Alipay to identify a merchant
      • responseTimeStr = "2020-03-23T06:08:53Z"; // Take the value of Response-Time from header
      • rspBody = "{

         "paymentAmount": {

             "currency": "PHP",

             "value": "100"

         },

         "paymentCreateTime": "2020-03-23T11:54:08+08:00",

         "paymentId": "303540815849356482956531350278548000unSJuoDrlP202003220001430724",

         "paymentRequestId": "pay_1089760038715669_11277574501112",

         "redirectActionForm": {

             "method": "GET",

             "redirectUrl": "https://render.alipay.com/p/c/jzmcoal2/igg-checkout-counter.html?paymentId=303540815849356482956531350278548000unSJuoDrlP202003220001430724&callback=https%3A%2F%2Fwww.merchant.com%2FredirectUrl.htm&amountValue=100&amountCurrency=PHP&merchantName=cup%20Hu"

         },

         "result": {

             "resultCode": "PAYMENT_IN_PROCESS",

             "resultMessage": "payment in process",

             "resultStatus": "U"

         }

      }"; // Response body


      The calculated unsignedContent is:

      copy
      POST /ams/sandbox/api/v1/payments/pay
      SANDBOX_5Y036S2Y1W4D03493.2020-03-23T06:08:53Z.{
          "paymentAmount": {
              "currency": "PHP",
              "value": "100"
          },
          "paymentCreateTime": "2020-03-23T11:54:08+08:00",
          "paymentId": "303540815849356482956531350278548000unSJuoDrlP202003220001430724",
          "paymentRequestId": "pay_1089760038715669_11277574501112",
          "redirectActionForm": {
              "method": "GET",
              "redirectUrl": "https://render.alipay.com/p/c/jzmcoal2/igg-checkout-counter.html?paymentId=303540815849356482956531350278548000unSJuoDrlP202003220001430724&callback=https%3A%2F%2Fwww.merchant.com%2FredirectUrl.htm&amountValue=100&amountCurrency=PHP&merchantName=cup%20Hu"
          },
          "result": {
              "resultCode": "PAYMENT_IN_PROCESS",
              "resultMessage": "payment in process",
              "resultStatus": "U"
          }
      }



      3. Use the following algorithm to verify the signature. sha256withrsa_verify(base64UrlDecode(<signature>), <unsignedContent>, <alipayPublicKey>) 


      #Test in the sandbox environment

      After you complete the integration in the sandbox environment, execute test cases to see whether the services can work as expected. To execute test cases, go to Alipay Developer Center, and then locate Test Suites under Acceptance Test.


      #More information

      Go live

      Reports and reconciliation