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

      Digital signature (new)

      You can refer this document to sign New API requests. However,If you are integrated with Global APIs, see Digital Sigature for details.


      Digital signatures can ensure the reliability and anti-repudiation of the API data transmitted. Each qualified API caller, also called client, is assigned a clientId by Alipay. The API access is authenticated against the clientId by the RSA signature.


      Client and Alipay must exchange RSA keys before making API calls, and the length of RSA key must be 2048 bits. When making API call to Alipay, client uses the RSA private key to sign the API request. After receiving the API request, Alipay will use the client’s RSA public key to verify whether the signature is matched to the content of API request. Similarly, when client receives the API response, it is highly recommended that client verifies the signature of API response by using Alipay’s RSA public key. The following figure illustrates the interaction flow:


      Digital signature (new)


      #Signing the request


      The following figure illustrates a sample API request. The content enclosed by the two curly braces (inclusive) is what needs to be signed to create the RSA signature. And the generated signature is put in the signature parameter.


      Digital signature (new)


      Perform the following steps to sign the message:

      1、Extract the content to be signed. For example:

      copy
      {
           "head":{
               "version":"2.0.0",
               "function":"alipay.intl.acquiring.agreement.payCancel",
               "clientId":"211xxxxxxxxxxxxxxx044",
               "reqTime":"2001-07-04T12:08:56+05:30",
               "reqMsgId":"1234567asdfasdf1123fda",
               "reserve":"{}"
           },
           "body":{
               "merchantId":"218xxxxxxxxxxxxxxx023",
               "acquirementId":"2015xxxxxxxxxxxxxxxxxxxxx747"
           }
       }


      2、Hash the JSON content by using the SHA256withRSA algorithm. Then use the client's RSA private key to sign the value to obtain the signature. To achieve a better security level, the length of the RSA key/pairs must be 2048 bits. The following sample illustrates a raw signature:

      copy
      sXSGdA4tR4B0wnF6Nr8ShpfNMtHISWuzLpdKoNWskIgCcspMVFFzgkez4BrmtYXkMqZh1tyz/8sNNU3F2VTu0fOx+ZP4CnmVjNu8bciu4hTtnytA3Y1GZ/yXAUD+mVYGXeyDO3fHrqDdI7k3xV/Q8FCOd0culTsN6RRMxMZq+oqR2x+EjOXVofp7BZJwhQE8Us4Al573FQz5EHDvCLx35lq2hoMhXLCVLVDBHcpCgotuY4mg91MXh/qqcFGY/hQKhGdWAbZ9tcp2Q5s2ESh37rqxnOwZrrepK8NC6vMBPUiSPxQefpev2nG0JzAHOjRPbBXYw1XBS6RBYKAmufZZiQ==


      3、Base64-encode the signature. A sample result is listed below:

      copy
      c1hTR2RBNHRSNEIwd25GNk5yOFNocGZOTXRISVNXdXpMcGRLb05Xc2tJZ0Njc3BNVkZGemdrZXo0QnJtdFlYa01xWmgxdHl6LzhzTk5VM0YyVlR1MGZPeCtaUDRDbm1Wak51OGJjaXU0aFR0bnl0QTNZMUdaL3lYQVVEK21WWUdYZXlETzNmSHJxRGRJN2szeFYvUThGQ09kMGN1bFRzTjZSUk14TVpxK29xUjJ4K0VqT1hWb2ZwN0JaSndoUUU4VXM0QWw1NzNGUXo1RUhEdkNMeDM1bHEyaG9NaFhMQ1ZMVkRCSGNwQ2dvdHVZNG1nOTFNWGgvcXFjRkdZL2hRS2hHZFdBYlo5dGNwMlE1czJFU2gzN3JxeG5Pd1pycmVwSzhOQzZ2TUJQVWlTUHhRZWZwZXYybkcwSnpBSE9qUlBiQlhZdzFYQlM2UkJZS0FtdWZaWmlRPT0=


      4、Use the obtained string as the value of the Signature parameter. The following sample shows a whole API request:

      copy
      {
       "request":{
           "head":{
               "version":"2.0.0",
               "function":"alipay.intl.acquiring.agreement.payCancel",
               "clientId":"211xxxxxxxxxxxxxxx044",
               "reqTime":"2001-07-04T12:08:56+05:30",
               "reqMsgId":"1234567asdfasdf1123fda",
               "reserve":"{}"
           },
           "body":{
               "merchantId":"218xxxxxxxxxxxxxxx023",
               "acquirementId":"2015xxxxxxxxxxxxxxxxxxxxx747"
           }
       },
       "signature":"c1hTR2RBNHRSNEIwd25GNk5yOFNocGZOTXRISVNXdXpMcGRLb05Xc2tJZ0Njc3BNVkZGemdrZXo0QnJtdFlYa01xWmgxdHl6LzhzTk5VM0YyVlR1MGZPeCtaUDRDbm1Wak51OGJjaXU0aFR0bnl0QTNZMUdaL3lYQVVEK21WWUdYZXlETzNmSHJxRGRJN2szeFYvUThGQ09kMGN1bFRzTjZSUk14TVpxK29xUjJ4K0VqT1hWb2ZwN0JaSndoUUU4VXM0QWw1NzNGUXo1RUhEdkNMeDM1bHEyaG9NaFhMQ1ZMVkRCSGNwQ2dvdHVZNG1nOTFNWGgvcXFjRkdZL2hRS2hHZFdBYlo5dGNwMlE1czJFU2gzN3JxeG5Pd1pycmVwSzhOQzZ2TUJQVWlTUHhRZWZwZXYybkcwSnpBSE9qUlBiQlhZdzFYQlM2UkJZS0FtdWZaWmlRPT0="
      }


      #Verifying the signature


      A sample response is shown as below:


      Digital signature (new)


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


      1. Split the full response contents to 2 parts, the response JSON string and the signature string, by using the regular expression instead of JSON object.

      1. Hash the response JSON string by using the SHA256 algorithm to obtain a message digest.

      1. Use the public key to decrypt the signature to a message digest.

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


      #Sample codes

      The following exampls assume that you use the Java language.


      #Signature generation

      copy
      private String doSign(String content, String privateKey, String charset)
                                                                                  throws SignatureException {
              try {
                  PrivateKey priKey = KeyReader.getPrivateKeyFromPKCS8("RSA", new ByteArrayInputStream(
                      privateKey.getBytes()));
      
                  java.security.Signature signature = java.security.Signature
                      .getInstance("SHA256withRSA");
      
                  signature.initSign(priKey);
                  signature.update(getContentBytes(content, charset));
      
                  byte[] signed = signature.sign();
      
                  return new String(Base64.encodeBase64(signed));
              } catch (Exception e) {
                  throw new SignatureException("Failed to create RSA signature! [content = " + content + "; charset = " + charset
                                               + "]", e);
              }
          }


      #Signature Verification


      copy
      private boolean doCheck(String content, String sign, String publicKey, String charset)
                                                                                                throws SignatureException {
              try {
                  PublicKey pubKey = KeyReader.getPublicKeyFromX509("RSA", new ByteArrayInputStream(
                      publicKey.getBytes()));
      
                  java.security.Signature signature = java.security.Signature
                      .getInstance("SHA256withRSA");
      
                  signature.initVerify(pubKey);
                  signature.update(getContentBytes(content, charset));
      
                  return signature.verify(Base64.decodeBase64(sign.getBytes()));
              } catch (Exception e) {
                  throw new SignatureException("Failed to verify RSA signature! [content = " + content + "; charset = " + charset
                                               + "; signature = " + sign + "]", e);
              }
          }


      #RSA key pair

      An RSA 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.


      #Generating an RSA key pair


      Many tools can be used to generate the RSA key pair. The following steps assume that you use OpenSSL to generate the RSA key pair.


      1、Install OpenSSL.

        • For linux system, use the following command:

          copy
          sudo apt-get install openssl

      2、 Generate RSA key pair.

        • For linux system, use the following command:

          copy
          $ openssl
            OpenSSL> genrsa -out rsa_private_key.pem 2048 ##generate 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 2048  ##Generate 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.


      #Uploading RSA public key


      After the RSA2 key pair is generated, you must exchange the public key with the Alipay server for signature verification by completing the following steps:

      • Upload your public key to Alipay

      • Obatin Alipay public key