Error Codes

To verify whether all API requests and responses are correctly handled, and whether user experiences are as expected, you can test Alipay payment features integrated with your applications in sandbox environment before going live in the production environment.

Sandbox environment is an environment where you can mimic the characteristics of the production environment and create simulated responses from all APIs the application relies on before going live. You can make API tests based on your own requirements including making a transaction, cancel, or refund a transaction, and so on. Before you access the Alipay Sandbox Portal to start the test, you need to make some preparations. See Prerequisites for details.

Before you test Alipay payment features in sandbox, you need to get the following preparations:

• Download the demo code. If you haven’t done this, see demo code.
• Get an Alipay merchant account. If you don’t have one, watch the video below to get yourself an Alipay merchant account and a quick overview of Alipay sandbox portal.

Creating an Alipay merchant account:

1. Go to the Alipay for Business website: https://global.alipay.com
2. In the top-right corner of the homepage, click Sign Up.
3. Enter your email, enter the code displayed, and then click Continue.
4. Follow the instructions to complete the account creation.

Use your merchant account to log in to the Alipay Sandbox Portal, if you don’t have the account, see Prerequisites.

Alipay sandbox gateway

Use the Alipay sandbox gateway for testing. The URL of the sandbox gateway is:
https://mapi.alipaydev.com/gateway.do?

Alipay sandbox test accounts

There are two types of test account: merchant test account and buyer test account.

Merchant test accounts:

Find the merchant test account information in the Alipay sandbox portal under Sandbox Accounts > Merchant. More than one test accounts are provided, and the accounts are sorted by payment feature. Find the correct one to use according to the payment feature you want to test. For example, to test the Alipay Auto Debit feature, use the account information provided under Alipay Auto Debit.

Buyer test account:

Use the buyer test account to login to the Alipay sandbox app.
The buyer test account information can be found in the Alipay sandbox portal under Sandbox Accounts > Buyer.

Download the Alipay sandbox app

The Alipay sandbox app supports only Android at this time.

1) In the Alipay sandbox portal, click Alipay Sandbox App from the menu on the left.
2) Take one of the following steps:

• Scan the QR code displayed on the page with a QR code reader on your Android device. This will download and install the sandbox app to your device.
• Click the download link to download the sandbox app to your computer.

To log in to the Alipay sandbox app, use the buyer test account and login password that are provided in the portal under Sandbox Accounts > Buyer.

To generate a digital signature, normally a key is required to sign the data. You must prepare the MD5 private key or the RSA/DSA private and public key pair to generate and verify a digital signature.

MD5 sign type

MD5 private key is required for generating and verifying MD5 signatures. The MD5 secret key is the 32-byte string which is composed of English letters and numbers. You can log in to the Global Portal to view the private key:

1. Log in with your user ID.
2. Click My Technical Service and enter your payment password. If you don't know your payment password, please contact Global Merchant Business Support

3. Check your MD5 Key. For example, the following graphic is an example of an MD5 Key:

RSA/DSA sign type

An RSA/DSA key pair contains the private key and the public key. The private key is required for generating the signature, while the public key is used for verifying the signature. The following steps assume that you are using RSA sign type, similar steps applied for generating and uploading DSA key pair.

Many tools can be used to generate the RSA key pair. The following example illustrates the steps to generate the RSA key pair by using OpenSSL.

1. Install OpenSSL
   
   • For linux system, use the following command:

     sudo apt-get install openssl

   • For windows system, download and then install OpenSSL from OpenSSL site.
2. Generate RSA key pair.
   For linux system, use the following command:

   $ openssl
   OpenSSL> genrsa -out rsa_private_key.pem 1024 ##generating  private key
   OpenSSL> pkcs8 -topk8 -inform PEM -in rsa_private_key.pem  -outform PEM -nocrypt ##transform private key into PKCS8 format
   OpenSSL> rsa -in rsa_private_key.pem -pubout -out  rsa_public_key.pem ##Generate public key
   OpenSSL> exit          
   

   
   For windows system, use the following command:

   C:\Users\Hammer>cd C:\OpenSSL-Win32\bin ##enter OpenSSL directory
   C:\OpenSSL-Win32\bin>openssl.exe ##enter OpenSSL
   OpenSSL> genrsa -out rsa_private_key.pem 1024  ##generating private key
   OpenSSL> pkcs8 -topk8 -inform PEM -in rsa_private_key.pem  -outform PEM -nocrypt ##transform private key into PKCS8 format
   OpenSSL> rsa -in rsa_private_key.pem -pubout -out  rsa_public_key.pem ##Generate public key
   OpenSSL> exit 

After that, you can see two files under current folder, rsaprivatekey.pem and rsapublickey.pem. The former is the private key and the latter is the public key.

• For Java developers, remove the header, footer, carriage return, and space from the pkcs8 private key output in the console.
• After creating a private key with openssl, if you use JAVA, you need to transform the private key into PKCS8 format; if you use .NET or PHP, no need to transform the private key into PKCS8 format.

The following are the examples of the key pair:

• Standard private key file（PHP,.NET）

  -----BEGIN RSA  PRIVATE KEY-----MIICXQIBAAKBgQC+L0rfjLl3neHleNMOsYTW8r0QXZ5RVb2p/vvY3fJNNugvJ7lo4+fdBz+LN4mDxTz4MTOhi5e2yeAqx+v3nKpNmPzC5LmDjhHZURhwbqFtIpZD51mOfno2c3MDwlrsVi6mTypbNu4uaQzw/TOpwufSLWF7k6p2pLoVmmqJzQiD0QIDAQABAoGAakB1risquv9D4zX7hCv9MTFwGyKSfpJOYhkIjwKAik7wrNeeqFEbisqv35FpjGq3Q1oJpGkem4pxaLVEyZOHONefZ9MGVChT/MNH5b0FJYWl392RZy8KCdq376Vt4gKVlABvaV1DkapL+nLh7LMo/bENudARsxD55IGObMU19lkCQQDwHmzWPMHfc3kdY6AqiLrOss+MVIAhQqZOHhDe0aW2gZtwiWeYK1wB/fRxJ5esk1sScOWgzvCN/oGJLhU3kipHAkEAysNoSdG2oWADxlIt4W9kUiiiqNgimHGMHPwp4JMxupHMTm7D9XtGUIiDijZxunHv3kvktNfWj3Yji0661zHVJwJBAM8TDf077F4NsVc9AXVs8N0sq3xzqwQD/HPFzfq6hdR8tVY5yRMb4X7+SX4EDPORKKsgnYcur5lk8MUi7r072iUCQQC8xQvUne+fcdpRyrR4StJlQvucogwjTKMbYRBDygXkIlTJOIorgudFlrKP/HwJDoY4uQNl8gQJb/1LdrKwIe7FAkBl0TNtfodGrDXBHwBgtN/t3pyi+sz7OpJdUklKE7zMSBuLd1E3O4JMzvWP9wEE7JDb+brjgK4/cxxUHUTkk592-----END RSA  PRIVATE KEY-----

• Standard private key file in PKCS8 format(Java)

  -----BEGIN PRIVATE  KEY-----MIICeAIBADANBgkqhkiG9w0BAQEFAASCAmIwggJeAgEAAoGBAN0yqPkLXlnhM+2H/57aHsYHaHXazr9pFQun907TMvmbR04wHChVsKVgGUF1hC0FN9hfeYT5v2SXg1WJSg2tSgk7F29SpsF0I36oSLCIszxdu7ClO7c22mxEVuCjmYpJdqb6XweAZzv4Is661jXP4PdrCTHRdVTU5zR9xUByiLSVAgMBAAECgYEAhznORRonHylm9oKaygEsqQGkYdBXbnsOS6busLi6xA+iovEUdbAVIrTCG9t854z2HAgaISoRUKyztJoOtJfI1wJaQU+XL+U3JIh4jmNx/k5UzJijfvfpT7Cv3ueMtqyAGBJrkLvXjiS7O5ylaCGuB0Qz711bWGkRrVoosPM3N6ECQQD8hVQUgnHEVHZYtvFqfcoq2g/onPbSqyjdrRu35a7PvgDAZx69Mr/XggGNTgT3jJn7+2XmiGkHM1fd1Ob/3uAdAkEA4D7aE3ZgXG/PQqlm3VbE/+4MvNl8xhjqOkByBOY2ZFfWKhlRziLEPSSAh16xEJ79WgY9iti+guLRAMravGrs2QJBAOmKWYeaWKNNxiIoF7/4VDgrcpkcSf3uRB44UjFSn8kLnWBUPo6WV+x1FQBdjqRviZ4NFGIP+KqrJnFHzNgJhVUCQFzCAukMDV4PLfeQJSmna8PFz2UKva8fvTutTryyEYu+PauaX5laDjyQbc4RIEMU0Q29CRX3BA8WDYg7YPGRdTkCQQCG+pjU2FB17ZLuKRlKEdtXNV6zQFTmFc1TKhlsDTtCkWs/xwkoCfZKstuV3Uc5J4BNJDkQOGm38pDRPcUDUh2/-----END PRIVATE  KEY-----

• Public key file

  -----BEGIN PUBLIC  KEY-----MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDQWiDVZ7XYxa4CQsZoB3n7bfxLDkeGKjyQPt2FUtm4TWX9OYrd523iw6UUqnQ+Evfw88JgRnhyXadp+vnPKP7unormYQAfsM/CxzrfMoVdtwSiGtIJB4pfyRXjA+KL8nIa2hdQy5nLfgPVGZN4WidfUY/QpkddCVXnZ4bAUaQjXQIDAQAB-----END PUBLIC  KEY-----

Exchange the public key

For a transaction that has been successfully paid, the customer can request the merchant for refunding as long as the refunding period is still valid, and the merchant can make use of the refunding interface to complete the refunding, as illustrated.

For the integration of the refunding service, we would like to highlight:

1. The refunding service name is: alipay.acquire.overseas.spot.refund(REFUND);
2. To refund a transaction, the interface REVERSE is only applicable at the same day of the payment (GMT +8, Beijing time); on the other hand, the interface REFUND is applicable as long as the refunding period has not expired yet;
3. the refunding of a transaction can be full or partial, i.e. the refunding amount can respectively be the same as or less than the original transaction amount that has been paid; furthermore, for a transaction, multiple refunding request is allowed provided the sum of the amount of the multiple refunding request is less than or equal with the original transaction amount. 

Except for "sign" and "sign_type", all other parameters used need to be signed.

Generating the pre-sign string for request

For the following parameter array:

string[]  parameters={"partner=\"208861122157****\"",
"seller_id=\"208861122157****\"",
"out_trade_no=\"0811172929-1013\"",
"subject=\"test\"",
"body=\"test\"",
"currency=\"HKD\"",
"total_fee=\"0.1\"",
"notify_url=\"http://0ee96cd2.ngrok.io/notify.htm\"",
"service=\"mobile.securitypay.pay\"",
"payment_type=\"1\"",
"_input_charset=\"utf-8\"",
"appenv=\"system=java^version=1.8\"",
"forex_biz=\"FP\""
  };

_input_charset="utf-8"&appenv="system=java^version=1.8"&body="test"¤cy="HKD"&forex_biz="FP"¬ify_url="http://0ee96cd2.ngrok.io/notify.htm"&out_trade_no="0811172929-1013"&partner="208861122157****”&payment_type="1"&seller_id="208861122157****”&service="mobile.securitypay.pay"&sign="$$$"&sign_type="RSA"&subject="test"&total_fee="0.1"

Generating the pre-sign string for synchronous notification

resultStatus={9000};memo={};result={partner="2088101568358171"&seller_id="xxx@alipay.com"&out_trade_no="0819145412-6177"&subject="test"&body="testtest"&total_fee="0.01"&notify_url="http://notify.msp.hk/notify.htm"&service="mobile.securitypay.pay"&payment_type="1"&_input_charset="utf-8"&it_b_pay="30m"&show_url="m.alipay.com"&success="true"&sign_type="RSA"&sign="hkFZr+zE9499nuqDNLZEF7W75RFFPsly876QuRSeN8WMaUgcdR00IKy5ZyBJ4eldhoJ/2zghqrD4E2G2mNjs3aE+HCLiBXrPDNdLKCZgSOIqmv46TfPTEqopYfhs+o5fZzXxt34fwdrzN4mX6S13cr3UwmEV4L3Ffir/02RBVtU="}

partner="2088101568358171"&seller_id="xxx@alipay.com"&out_trade_no="0819145412-6177"&subject="test"&body="testtest"&total_fee="0.01"&notify_url="http://notify.msp.hk/notify.htm"&service="mobile.securitypay.pay"&payment_type="1"&_input_charset="utf-8"&it_b_pay="30m"&show_url="m.alipay.com"&success="true"

Generating the pre-sign string for asynchronous notification

http://0ee96cd2.ngrok.io/notify.htm? buyer_id=208812287878****¤cy=HKD&forex_rate=0.85420000¬ify_id=e5f5c6a77034fcd111e373e7e61dcbegdy¬ify_type=trade_status_sync¬ify_time=2017-08-11 17:31:39&out_trade_no=0811172929-1013&rmb_fee=0.09&seller_id=208861122157****&trade_no=2017081121001003050274536539&total_fee=0.10&trade_status=TRADE_FINISHED&sign_type=RSA&sign=$$$

buyer_id=208812287878****¤cy=HKD&forex_rate=0.85420000¬ify_id=e5f5c6a77034fcd111e373e7e61dcbegdy¬ify_type=trade_status_sync¬ify_time=2017-08-11 17:31:39&out_trade_no=0811172929-1013&rmb_fee=0.09&seller_id=208861122157****&trade_no=2017081121001003050274536539&total_fee=0.10&trade_status=TRADE_FINISHED

After the pre-sign string is generated:

1. Append the MD5 secret key to the pre-sign string to generate a new string.
2. Calculate the new string with the MD5 signature algorithm (by using the MD5 signature function).

After the pre-sign string is generated, perform the following steps to generate the signature:

1. Use the RSA/DSA algorithm and the merchant private key to generate the signature.
2. Encode the signature to a string.

After receiving the character string of the response or notification from Alipay system, similar to the steps taken in Signing the data, append the MD5 secret key to the character string to generate a new string. Then, calculate this new string with the MD5 signature algorithm. After the 32-byte signature result string is generated, verify whether the value is equal to the value passed in the sign parameter. If Yes, the verification is passed.

After receiving a response or notification, perform the following steps to verify the signature:

1. Generate the pre-sign string as described in Generating Pre-sign String.
2. Use the RSA/DSA algorithm to calculate a message digest.
3. Use the RSA/DSA public key to de-sign the signature (the value of the sign field) to a message digest.
4. Compare the two message digests obtained in step 2 and step 3. If the digests are the same, then it indicates that the signed data has not been changed.

The gateway URL:

If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.