Alipay+ DocsAlipay+ Docs

Sign a request and validate the signature

To ensure message transmission security, the Acquiring Service Provider (ACQP) must properly perform message signing and signature validation：

  • When calling an Alipay+ API, the ACQP must sign the API request and validate the response signature accordingly. For more information, see Direction: ACQP > Alipay+.
  • When receiving an API call from Alipay+, the ACQP must validate the request signature and sign the API response accordingly. For more information, see Direction: Alipay+>ACQP.

Direction: Acquiring Service Provider > Alipay+

This section introduces the ACQP to Alipay+ API workflow.

Sign a request

The following steps demonstrate how to sign a request message:

1. Obtain your private key to sign the request

Get your private key ready, which is used to generate the signature later. In this topic, privateKey is used to represent the private key.

2. Construct the content to be signed

Take a request as an example, which includes the following properties:

  • Request-URI: aps/api/v1/payments/pay
  • Client-Id: TEST_5X00000000000000
  • Request-Time: 2019-05-28T12:12:12+08:00
  • Request-Body: The following code sample describes the body format. For example:
copy
{
 "order":{
    "orderId":"OrderID_0101010101",
    "orderDescription":"sample_order",
    "orderAmount":{
       "value":"100",
       "currency":"JPY"
    }，
 },
 "paymentAmount":{
    "value":"100",
    "currency":"JPY"
 },
 "paymentFactor": {
     "isInStorePayment": "true"
 } 
}

By complying with the Syntax of Content_To_Be_Signed, the content to be signed (Content_To_Be_Signed) is created as follows:

copy
POST /aps/api/v1/payments/pay
TEST_5X00000000000000.2019-05-28T12:12:12+08:00.{
"order":{
    "orderId":"OrderID_0101010101",
    "orderDescription":"sample_order",
    "orderAmount":{
       "value":"100",
       "currency":"JPY"
    }，
 },
 "paymentAmount":{
    "value":"100",
    "currency":"JPY"
 },
 "paymentFactor": {
     "isInStorePayment": "true"
 } 
}

Syntax of Content_To_Be_Signed

copy
<HTTP-METHOD> <Request-URI>
<Client-Id>.<Request-Time>.<Request-Body>
  • HTTP-METHOD: POST
  • Request-URI: The {endpoint} part of the whole URL https://{host}{endpoint}. For example:
  • If the HTTP URL is https://www.example.com/aps/api/v1/payments/pay, this property is /aps/api/v1/payments/pay.
  • Client-Id: A unique ID that is assigned by Alipay+ to identify a Partner. You can get this field from the request header. For example, TEST_5X00000000000000.
  • Request-Time: Specifies the time when a request is sent, as defined by ISO 8601.

Note: This field must be accurate to seconds. For example, 2019-05-28T12:12:12+08:00 and 2021-04-21T01:47:04Z. You can get this field from the request header.

  • Request-Body: The body of the request.

3. Calculate and generate the signature

Use the base64UrlEncode and sha256withrsa methods that involve the proper algorithm and private key to calculate and generate the signature.

copy
generatedSignature=base64UrlEncode(sha256withrsa(<Content_To_Be_Signed>, <privateKey>))

Methods that are used:

  • sha256withrsa: The method to generate a digital signature for the content provided.
  • base64UrlEncode: The method to encode the generated digital signature.

Input parameters:

  • Content_To_Be_Signed: The content to be signed that is obtained in Step 2.
  • privateKey: The private key value that is obtained in Step 1.

The following code sample describes the generated signature (represented by generatedSignature):

copy
KrwDE9tAPJYBb4cUZU6ALJxGIZgwDXn5UkFPMip09n%2FkYKPhEIII%2Fki2rYY2lPtuKVgMNz%2BtuCU%2FjzRpohDbrOd8zYriiukpGAxBQDIVbatGI7WYOcc9YVQwdCR6ROuRQvr%2FD1AfdhHd6waAASu5Xugow9w1OW7Ti93LTd0tcyEWQYd2S7c3A73sHOJNYl8DC1PjasiBozZ%2FADgb7ONsqHo%2B8fKHsLygX9cuMkQYTGIRBQsvfgICnJhh%2BzXV8AQoecJBTrv6p%xxxx

4. Configure the signature in the request header

Assemble a signature string by using the following syntax:

copy
'Signature: algorithm=<algorithm>, keyVersion=<key-version>, signature=<generatedSignature>'
  • algorithm , keyVersion: See the header of the Message structure chapter.
  • generatedSignature: The signature that is generated in Step 3.

The following sample describes an assembled signature string:

copy
'Signature: algorithm=RSA256, keyVersion=0, signature=KrwDE9tAPJYBb4cUZU6ALJxGIZgwDXn5UkFPMip09n%2FkYKPhEIII%2Fki2rYY2lPtuKVgMNz%2BtuCU%2FjzRpohDbrOd8zYriiukpGAxBQDIVbatGI7WYOcc9YVQwdCR6ROuRQvr%2FD1AfdhHd6waAASu5Xugow9w1OW7Ti93LTd0tcyEWQYd2S7c3A73sHOJNYl8DC1PjasiBozZ%2FADgb7ONsqHo%2B8fKHsLygX9cuMkQYTGIRBQsvfgICnJhh%2BzXV8AQoecJBTrv6p%xxxx'

Then, add the signature string to the request header.

Send a request

Construct a request by adding the Client-Id, Request-Time, and Signature fields to the request header. After a request is constructed, you can use common tools, such as cURL or Postman, to send the request. In the following example, cURL is used:

copy
curl -X POST \
  https://example.com/aps/api/v1/payments/pay \
  -H 'Content-Type: application/json' \
  -H 'Client-Id: TEST_5X00000000000000' \
  -H 'Request-Time: 2019-05-28T12:12:12+08:00' \
  -H 'Signature: algorithm=RSA256, keyVersion=0, signature=KrwDE9tAPJYBb4cUZU6ALJxGIZgwDXn5UkFPMip09n%2FkYKPhEIII%2Fki2rYY2lPtuKVgMNz%2BtuCU%2FjzRpohDbrOd8zYriiukpGAxBQDIVbatGI7WYOcc9YVQwdCR6ROuRQvr%2FD1AfdhHd6waAASu5Xugow9w1OW7Ti93LTd0tcyEWQYd2S7c3A73sHOJNYl8DC1PjasiBozZ%2FADgb7ONsqHo%2B8fKHsLygX9cuMkQYTGIRBQsvfgICnJhh%2BzXV8AQoecJBTrv6p%xxxx' \
  -d '{
      "order":{
          "orderId":"OrderID_0101010101",
          "orderDescription":"sample_order",
          "orderAmount":{
             "value":"100",
             "currency":"JPY"
          }
       },
       "paymentAmount":{
          "value":"100",
          "currency":"JPY"
       },
       "paymentFactor": {
           "isInStorePayment": "true"
       } 
}'

Handle a response

After you receive a response, you need to validate the signature of the response. A response consists of a response header and a response body. The following examples show the header and body of a response:

  • The response header sample
copy
Client-Id: 5X00000000000000
Response-Time: 2019-05-28T12:12:14+08:00
Signature: algorithm=RSA256, keyVersion=0, signature=p9T2hXxIjek0UOLw3fwlthNsV6ATaioIvu8X1uFx8a9tE87d2XEhqylnf0KjifJ3WhCoMoklGwwlDS3tsSenwnL0Ha6BsXbJvUHRC5qcVlNy5Oq%2FpNqx2%2BKdwbw4eY7tZBDQhMKoaMVSbqbCb3eRBxxxx
  • The response body sample
copy
{
"result": {
 "resultCode":"SUCCESS",
 "resultStatus":"S",
 "resultMessage":"success"
},
"paymentTime": "2019-05-28T12:12:13+08:00",
"paymentId":"1234567"
}

The following steps demonstrate how to validate a signature of a response by using the example above.

1. Obtain an Alipay+ public key

To get the Alipay+ public key, you must take the following steps:

  1. Create an application on Developer Center. For more information, see Create application in the Alipay+ Developer Center User Guide.
  2. Go to Integration Settings, generate your public key with the provided tool, and submit your public key.

The Alipay+ public key is then generated automatically and can be obtained from the Alipay+ public key field.

Notes:

  • Your public key in the sandbox environment must be different from the one in the production environment. Therefore, you must get the Alipay+ public keys for the sandbox environment and the production environment separately.
  • For more information about getting the Alipay+ public keys for the sandbox environment, see Set public key in the Alipay+ Developer Center User Guide.
  • For more information about getting the Alipay+ public key for the production environment, see Set production public key in the Alipay+ Developer Center User Guide.

2. Construct the content to be validated

Given the response body sample above, construct the content to be validated (Content_To_Be_Validated) by complying with the Syntax of Content_To_Be_Validated as follows:

copy
POST /aps/api/v1/payments/pay
TEST_5X00000000000000.2019-05-28T12:12:14+08:00.{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
 },
 "paymentTime": "2019-05-28T12:12:13+08:00",
 "paymentId":"1234567"
}

Syntax of Content_To_Be_Validated

copy
<HTTP-METHOD> <Response-URI>
<Client-Id>.<Response-Time>.<Response-Body>
  • HTTP-METHOD: POST
  • Response-URI: The URI of an HTTP link. For example, if the URL is https://example.com/aps/api/v1/payments/pay, this field is /aps/api/v1/payments/pay.
  • Client-Id: A unique ID that is assigned by Alipay+ to identify a Partner. You can get this field from the response header. For example TEST_5X00000000000000.
  • Response-Time: Indicates the time when a response is returned, as defined by ISO 8601. Note: This field must be accurate to seconds. You can get this field from the response header.
  • Response-Body: Indicates the body of the response.

3. Get the signature from the response header

The target signature string ( target_signature ) is extracted from the Signature header of the response. For details about the response header, see the chapter Message structure.

copy
Signature: algorithm=RSA256, keyVersion=0, signature=<target_signature>

4. Validate the signature

Use the sha256withrsa_verify method to validate the signature of the response.

The syntax of the sha256withrsa_verify method is as follows:

copy
IS_SIGNATURE_VALID=sha256withrsa_verify(base64UrlDecode(<target_signature>), <Content_To_Be_Validated>, <serverPublicKey>)

Methods:

  • base64UrlDecode: The method to decode the signature.
  • sha256withrsa_verify: The method to verify the signature.

Input parameters:

  • target_signature: The target signature that is obtained in Step 3.
  • Content_To_Be_Validated: The content to be validated, which is created in Step 2.
  • serverPublicKey: The platform public key that is obtained in Step 1.

Output parameter:

  • IS_SIGNATURE_VALID: A Boolean value that specifies whether the signature is valid.
    • true: The signature is valid.
    • false: The signature is not valid. The causes can be that the private key and the public key do not match, or Content_To_Be_Validated is not correctly constructed.

Direction: Alipay+ > Acquiring Service Provider

This section introduces the Alipay+ to ACQP API workflow.

Handle a request

After you receive a request from Alipay+, you need to validate the signature of the request. The process is similar to the process introduced in Handle a response. To validate the signature complete the following steps:

  1. Obtain the Alipay+ public key, which is used to validate the request signature.
  2. Construct the Content_To_Be_Validated, which is:
copy
<HTTP-METHOD> <Request-URI>
<Client-Id>.<Request-Time>.<Request-Body>

Note: The Request-URI is the endpoint of your API path. For example, when Alipay+ sends a notifyPayment request to the API path https://www.sampleACQP.com/aaa/bbb/ccc, the Request-URI is /aaa/bbb/ccc.

  1. Get the signature from the request header.
  2. Validate the signature.

Sign a response

You must sign your response before sending it to Alipay+. The process is much like that as introduced in , which means you just need to:The process is similar to the process introduced in Sign a request. To sign a request, complete the following steps:

  1. Use your private key to sign the response.
  2. Construct the content to be signed, which is:
copy
<HTTP-METHOD> <Response-URI>
<Client-Id>.<Response-Time>.<Response-Body>

Note: The Response-URI is the endpoint of your API path. For example, when you respond to Alipay+'s notifyPayment request, whose API path is https://www.sampleACQP.com/aaa/bbb/ccc, the Response-URI is /aaa/bbb/ccc.

  1. Calculate and generate the signature.
  2. Configure the signature in the response header.

Send a response

Construct a response by adding the Client-Id, Response-Time, and Signature fields to the response header. After a response is constructed, you can use common tools, such as cURL or Postman to send the response. The process is similar to the process introduced in Send a request.

Learn more about

Home
Get Support
Need more help?