Digital signature

2024-09-05 02:17

You can refer this document to sign Global API requests. However, if you are integrated with new version APIs, see Digital Signature (new) for details.

When you send your request to Alipay, your request must be signed to identify who send the request and ensure that the request is not tampered in data transmission.

Preparing keys

To generate a digital signature, normally a key is required to sign the data. The following table shows the supported sign types:

Product

Sign type

Online Payment

Web/Wap Payment: RSA, RSA2, and MD5.

In-App Payment: Only RSA.

Customs Declaration: RSA and MD5.

In-store Payment

RSA, RSA2, and MD5

MD5 sign type

The MD5 key is required for generating and verifying MD5 signatures. An MD5 key is a 32-byte string which is composed of English letters and numbers.

Complete the following steps to view your MD5 key:

Log in to Alipay Global Site. Go to Business Center -> Online Payment / Instore Payment Product -> See Key, and then click See my key.

Enter your payment password and then click Confirm. If you don't know your payment password, please contact Global Merchant Business Support (global.service@alipay.com).

Check your MD5 Key. The following figure is an example of an MD5 Key:

RSA/RSA2 sign type

An RSA/RSA2 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. For security reasons, RSA2 keys are strongly recommended.

RSA2

Alipay provides tools to help you generate and validate RSA2 keys. Also, you can exchange RSA2 public keys with Alipay by using Alipay Global Site.

Key pair generation

Complete the following steps to generate a RSA2 key pair by using Alipay API Tool:

Download Alipay API Tool.
Extract AlipayApiTool.zip.
Depending on your operating system, execute Run_Windows.bat or Run_Mac.
Click New to generate a key pair.

You can also generate RSA2 key pairs by using OpenSSL. See RSA section for details. To generate RSA2 keys, change OpenSSL> genrsa -out rsa_private_key.pem 1024 to OpenSSL> genrsa -out rsa_private_key.pem 2048.

The following examples are RSA2 key pairs:

RSA2 private key

copy
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCMJzNJinprwqy72FuBtrBQwapilYbQ2R0W3q8vfxhdgUudQwaLcsTpGLAsv1LIiVsKBGwozb1PfyjV5HfAktCjkqdvjn+1+TzRnlTc23uvHK/Hsan0CuMDEb6fYepUN56wCoX5pbHDcwD0Y9IQX+v3AD7e/mf8E5/IYDfr0MZWxTBafCBKAK/IRQPRZ/KFTO61hr9/rfiW3Len6aYlvcp+DfdIR8R1orkn/CO4/l6yYrlPmj2YxB4oeve5OjYPq3FHnKOYRwl7gy84loqZi7O5BVtOv1ZDsHojtMRTtWf1redeeFWEwuqN2Ng4lRbT1cj/q+oADiFbWau5H1xD1X59AgMBAAECggEAbAjTmf6qu2JG8E2oy+ZdJwMCKhgE4fxaVgS1mbEowPsnpEPESb3gV6X2N6gLUhW/HYunLBTbtunYOnhwbvs85LnpYy6+9zD2Vsbrt4tgXe2I+i/TSBEUSItnG0jI7r4pDp4uA/BbhMOjmr9Pb9vg8nc3/4Cv+znNUxIISTiXis4p5BSYWg0EnhbiV1pjft1JX3jhcmT3snIYIYbJxdnHAVimG1V2ANAOpFc6wF5wIIP98zXfQ2/Cx9QbSLwBEjyqV0COnPsbs3EFDLgmE7GFKg4+DZu1wam3DtO8Fo5dL0vFAEfi8hAgG3b14OmgwL1Q5YjDh7wzMhpfn23LdQrO6QKBgQD7QpFR/183Bw0gphtLN/8/pu0qX5jrOpFgbKz2IYkopRLQPmWSYrhVtX0ThRtufefQ8rfqVJdOMySD0qrJQC7+jXNiOYwcItCYNBCSiO7LSWxfj3OSwtOkmkLsdyw5NEL/pdwHRX/oP5f+Q9jLbKsP6MwIjVnK+SHkMPgw4Cuh9wKBgQCOzA3kGUlf+BTjl/aVMcsIRYfFSl+dbCLoyDXUaHFq6QGZ43bHMFO5a6K2cvsgxviHVZkRK1lnvgGYzEN21TGG/MtTKMhxmv9E0vo0C20EBoqKW4xobvTud1weiAcm4eKjeMac8hajGXwvXUKivARK/Q/52cItWHMumxaQWZaGKwKBgQDNUpmUSz5Qpmd43aSCNDFWn59BODurRgIUrNoujDscRsD4AXVZSWjfSV77e5NuGF8+ZYobaKL4WVymiJnduaBtjcPTablwKJcTOcCtLk8NOmPgN0a3kJQI97JmsAAogueZJ72FB6s9a/JV6rWXjqa/anqJJpFRB4NFiSrYLegaAwKBgDnDFQNlryag5WJDAD3NjIFmDsuhkBfPvDdJdWzcarSCWGF1f4CHbfadMY536FmT4shruaUWUe4DEAZM6iVRi908uMqEvsAloIiohwkybgCo3LWm3p8H8w/bPGolQC9cRB84Ja8qxjlnf7JxGRlW0K28vA+nJELPepgpp/DwLFFNAoGAWwgluqqsBHzQBzQ5A+GqTaTSX4uWOSKj60Jfj/mglB3D3iNzE+y/2xJx8HNF0PYqGV5qhC5GTDSMA3nTN+NMLT6oGnF8wDAA1M5soWfQCMmRUWLDEyZTIGUHaqknhVCLeCPh+oKwcR0Uhof//8zYh6kWLjX8jaovYY0/N9XnPaw=

RSA2 public key

copy
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAjCczSYp6a8Ksu9hbgbawUMGqYpWG0NkdFt6vL38YXYFLnUMGi3LE6RiwLL9SyIlbCgRsKM29T38o1eR3wJLQo5Knb45/tfk80Z5U3Nt7rxyvx7Gp9ArjAxG+n2HqVDeesAqF+aWxw3MA9GPSEF/r9wA+3v5n/BOfyGA369DGVsUwWnwgSgCvyEUD0WfyhUzutYa/f634lty3p+mmJb3Kfg33SEfEdaK5J/wjuP5esmK5T5o9mMQeKHr3uTo2D6txR5yjmEcJe4MvOJaKmYuzuQVbTr9WQ7B6I7TEU7Vn9a3nXnhVhMLqjdjYOJUW09XI/6vqAA4hW1mruR9cQ9V+fQIDAQAB

Key pair validation

You can validate your key pair by using Alipay API Tool by completing the following steps:

Depending on your operating system, execute Run_Windows.bat or Run_Mac.
Enter your private key and public key in the fields.
Click Validate to see whether the private key and public key matches.

Public key exchange

To exchange your RSA2 public key with Alipay, complete the following steps:

At My Order tab, click See Key.

Find RSA2 Key Information and click Edit my public key.

Enter your RSA2 key in the text box and then click SAVE.

Click See my public key.

Enter your payment password and then click Confirm.

You can then view your public key and Alipay public key. For example:

${6B8F887E-43F6-4227-937B-A4999552AB43}_20200102151516.jpg$

Note:

Alipay public key is only provided after you have uploaded your public key.

RSA

RSA keys are nor recommended and you must generate RSA keys on your own. In addition,to exchange RSA public keys with Alipay, you must contact Alipay Technical Support.

Key pair generation

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.

Install OpenSSL

For linux system, use the following command:

copy
sudo apt-get install openssl

For windows system, download and then install OpenSSL from OpenSSL site.

Generate RSA key pair.

For linux system, use the following command:

copy
$ 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:

copy
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.

Notes:

For Java developers, remove the header, footer, carriage returns, and spaces 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 examples of RSA key pair:

Standard private key file (PHP,.NET)

copy
-----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)

copy
-----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

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

Public key exchange

Contact Global Merchant Technical Support (AlipayGlobalTechService@service.alipay.com) and provide your PID and public key information. Alipay will then make configurations accordingly, and provide you Alipay public key.

After uploading your publick key to Alipay, you can view your public key and Alipay public key on Alipay Global Site in the same way you view your RSA2 public key.

Generating pre-sign string

This section describes how to generate the pre-sign string.

Only parameters used need to be signed, except for sign and sign_type.
Parameters without value don't need to be transmitted, nor to be included in the data to be signed.
At signing, the character set used to change the character into byte stream must be consistent with that specified in _input_charset.
If the parameter _input_charset is transmitted, it must also be included in the data to be signed.

For the following parameter array:

copy
key-----------------------value
total_fee-----------------0.01
trade_information---------{"business_type":"4","goods_info":"Macbook 12 inch M3 8G 256G SSD^1|Apple iPad Pro 11 inch^1","total_quantity":"2"}
_input_charset------------UTF-8
currency------------------USD
out_trade_no--------------out_trade_no_20200109_175140
partner-------------------2088021017666931
product_code--------------NEW_OVERSEAS_SELLER
service-------------------create_forex_trade
subject-------------------Mika's coffee shop
timeout_rule--------------12h

Combine all array values in the format of "key=value" (without quotation marks) and then link them up with the ampersand symbol (&) in an alphabetical order. For example:

_input_charset=UTF-8&currency=USD&out_trade_no=out_trade_no_20200109_175140&partner=2088021017666931&product_code=NEW_OVERSEAS_SELLER&service=create_forex_trade&subject=Mika's coffee shop&timeout_rule=12h&total_fee=0.01&trade_information={"business_type":"4","goods_info":"Macbook 12 inch M3 8G 256G SSD^1|Apple iPad Pro 11 inch^1","total_quantity":"2"}

Note:

For In-App Payment, combine all array values in the format of key="value" (with quotation marks) and then link them up with the ampersand symbol (&) in an alphabetical order. For example:

For the following parameter array:

copy
key-----------------------value
total_fee-----------------0.01
trade_information---------{"business_type":"4","goods_info":"Macbook 12 inch M3 8G 256G SSD^1|Apple iPad Pro 11 inch^1","total_quantity":"2"}
_input_charset------------UTF-8
appenv--------------------system=android^version=3.0.1.2
body----------------------test
currency------------------USD
forex_biz-----------------FP
out_trade_no--------------out_trade_no_20200109_175417
partner-------------------2088021017666931
payment_type--------------1
product_code--------------NEW_WAP_OVERSEAS_SELLER
seller_id-----------------2088021017666931
service-------------------mobile.securitypay.pay
subject-------------------Mika's coffee shop

The pre-sign string after processing:

_input_charset="UTF-8"&appenv="system=android^version=3.0.1.2"&body="test"&currency="USD"&forex_biz="FP"&out_trade_no="out_trade_no_20200109_175417"&partner="2088021017666931"&payment_type="1"&product_code="NEW_WAP_OVERSEAS_SELLER"&seller_id="2088021017666931"&service="mobile.securitypay.pay"&subject="Mika's coffee shop"&total_fee="0.01"&trade_information="{"business_type":"4","goods_info":"Macbook 12 inch M3 8G 256G SSD^1|Apple iPad Pro 11 inch^1","total_quantity":"2"}"

Signing the request

MD5 sign type

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

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

The result 32-byte string is the signature, which is used as the value of the sign parameter.

RSA2/RSA sign type

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

Use the RSA/RSA2 algorithm and your private key to generate the signature.
Encode the signature to a string.

Then, use the string as the value of the sign parameter.

Verifying the signature

This section describes how to verify the signature.

MD5 sign type

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.

RSA2/RSA sign type

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

Generate the pre-sign string as described in Generating Pre-sign String.
Use the RSA/RSA2 algorithm to calculate a message digest.
Use the RSA/RSA2 public key to de-sign the signature (the value of the sign field) to a message digest.
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.