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