Sandbox integration

    This page is about how to perform the sandbox integration. The following graphic illustrates steps of a complete system development process.

    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 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 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 for example, 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 header. Assemble the signature algorithm, the key version used for the signature, and the signature into 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 response header and 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 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 sandbox environment

    After you complete the integration in sandbox environment, execute test cases to see whether the services can work as expected. For a full list of sandbox test cases, see Test cases.


    #More information

    Go live

    Reports and reconciliation