Signature Algorithm

To ensure the data authenticity and integrity during the data transmission, all requests need to be signed when calling the API and signatures of all responses need to be verified. For more details, please refer to data transmission flowchart.

Prerequisite

To sign a request, you need to first generate a pair of RSA asymmetric keys. Asymmetric key pairs include a private key and a public key, from which the private key is used for generating the signature and the public key is used when AlphaPay verifies the signature of the request.

ou can edit your public key by navigating to the ECommerce page in the merchant dashboard, clicking on the Edit Public Key button and clicking the Click to Generate button to open the RSA key generator.

Please choose 2048 for Key Length and click on the Generate key pair button. Copy the generated Public key and paste it into the popup window where opened by clicking the Edit Public Key button.

Sign a request

Generate the signature using the SHA256withRSA algorithm, then encode it with Base64, and finally encoded it with URLEncoder.

Signature request process:

1. Construct the content to be signed

Syntax of Content_To_Be_Signed:

<HTTP-Method> <HTTP-URI>
<Merchant-Code>.<Request-Time>.<Nonce>.<Request-Body>

For instance: String.format("%s %s\n%s.%s.%s.%s", method, requestURI, merchantCode, requestTime, nonce, body);

HTTP-Method: POST
HTTP-URI: For example, if the HTTP URL is https://openapi.alphapay.ca/api/v2.0/payments/pay, then the URI is /api/v2.0/payments/pay
Merchant-Code: Merchant code provided by AlphaPay, e.g. CXVJIU
Request-Time: Specifies the time when a request is sent, as defined by ISO 8601. This field must be accurate to milliseconds, e.g.2019-05-28T12:12:12+08:00
Nonce: Random-generated String with length of 32, e.g. b111bcf0dfb54d4e8bae68c293d85e2e
Request-Body: The data body of the request, e.g.:

Request Body

{
    "scenarioCode": "ONLINE_QRCODE",
    "paymentRequestId": "50",
    "order": {
        "orderAmount": {
            "value": "45366",
            "currency": "CNY"
        },
        "description": "This is a test order",
        "notifyUrl": "https://alphapay.com/success",
        "redirectUrl": "https://alphapay.com/successPage"
    },
    "paymentMethod": {
        "paymentMethodType": "Alipay"
    }
}

By complying with the Syntax of Content_To_Be_Signed, the request body above is constructed as follows:

Content for Signature

POST /api/v2.0/payments/pay
CXVJIU.2019-05-28T12:12:12+08:00.b111bcf0dfb54d4e8bae68c293d85e2e.{
    "scenarioCode": "ONLINE_QRCODE",
    "paymentRequestId": "50",
    "order": {
        "orderAmount": {
            "value": "45366",
            "currency": "CNY"
        },
        "description": "This is a test order",
        "notifyUrl": "https://alphapay.com/success",
        "redirectUrl": "https://alphapay.com/successPage"
    },
    "paymentMethod": {
        "paymentMethodType": "Alipay"
    }
}

2. Generate the signature

The syntax of generating the signature is as follows:

generatedSignature=urlEncode(base64Encode(sha256withrsa(<Content_To_Be_Signed>), <privateKey>)))

inside of which:

sha256withrsa: The method to generate a digital signature for the provided content
base64Encode: The method to encode the generated digital signature in base64
urlEncode: The method to encode the url for Http request
Content_To_Be_Signed: The content obtained from Step 1
privateKey: The private key value obtained from Prerequisite

An example of a generated signature is as follows:

generated Signature

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

3. Add the generated signature to the request header

Assemble a signature string based on the following syntax:
'Signature: algorithm=<algorithm>, keyVersion=<keyVersion>, signature=<generatedSignature>'

algorithm, keyVersion: See the Request Header - Signature chapter
generatedSignature: The signature generated in Step 2

For example:

Completed Signature

'Signature: algorithm=RS256, keyVersion=1, signature=d%2FqFC126U57guKgRRXnd4colw5Ed5tpq3NDh2M5JOtfDivAze4X%2BYEaUCWHNW7h02sSed7hsnsDtM2rjtYe8kqAJTV9fMLzraeUZvWBh4j8Sf2D%2Bcz4bJ23S4F7VtoWaxMWjySwWuS0nMQweg%2BM7MY1HQFz2EXZjAa4CVflxU1I61NuEURfiYJGW%2BLEf%2FPVPEgzBLO8LopYMovmgO7Fl97E9UVFZnFW37bSaEdkNCffJlBU00AYWKaXbsARLarETkY9NA8nTJ5yDwjKm4rH3O%2FUhwGYnwLAvozKKjfWLU4m15LoAUF30Tap6d7IGFfewnLxdY34sVYG3Nx6m0Mit%2Bg%3D%3D'

Send a request

Construct a request by adding the Merchant-Code, Request-Time, Nonce and Signature properties 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 being used:

Send a request

curl --location --request POST 'https://openapi.alphapay.ca/api/v2.0/payments/pay' \
--header 'Accept: application/json' \
--header 'Merchant-Code: CXVJIU' \
--header 'Request-Time: 2023-03-15T22:37:47Z' \
--header 'Nonce: b111bcf0dfb54d4e8bae68c293d85e2e' \
--header 'Signature: algorithm=RS256, keyVersion=1, signature=d%2FqFC126U57guKgRRXnd4colw5Ed5tpq3NDh2M5JOtfDivAze4X%2BYEaUCWHNW7h02sSed7hsnsDtM2rjtYe8kqAJTV9fMLzraeUZvWBh4j8Sf2D%2Bcz4bJ23S4F7VtoWaxMWjySwWuS0nMQweg%2BM7MY1HQFz2EXZjAa4CVflxU1I61NuEURfiYJGW%2BLEf%2FPVPEgzBLO8LopYMovmgO7Fl97E9UVFZnFW37bSaEdkNCffJlBU00AYWKaXbsARLarETkY9NA8nTJ5yDwjKm4rH3O%2FUhwGYnwLAvozKKjfWLU4m15LoAUF30Tap6d7IGFfewnLxdY34sVYG3Nx6m0Mit%2Bg%3D%3D' \
--header 'Content-Type: application/json' \
--data-raw '{
    "scenarioCode": "ONLINE_QRCODE",
    "paymentRequestId": "50",
    "order": {
        "orderAmount": {
            "value": "45366",
            "currency": "CNY"
        },
        "description": "This is a test order",
        "notifyUrl": "https://alphapay.com/success",
        "redirectUrl": "https://alphapay.com/successPage"
    },
    "paymentMethod": {
        "paymentMethodType": "Alipay"
    }
}'

Handle a response

After receiving a response from AlphaPay, verify the signature of the response. To verify a signature, the content to be validated needs to be assembled first. Then, use URLDecode to decode the signature, followed by Base64 decoding. Finally, use SHA256withRSA algorithm to validate the signature.

The following figure shows how to verify a signature:

1. Obtain AlphaPay public key

Obtain the AlphaPay public key by navigating to the ECommerce page from AlphaPay merchant dashboard. The following figure shows where to obtain the AlphaPay public key:

2. Construct the content to be verified

The syntax of Content_To_Be_Validate is as follows:

<HTTP-Method> <HTTP-URI>
<Merchant-Code>.<Response-Time>.<Nonce>.<Response-Body>

HTTP-Method: POST
HTTP-URI: For example, if the HTTP URL is https://openapi.alphapay.ca/api/v2.0/payments/pay, then the URI is /api/v2.0/payments/pay
Merchant-Code: Merchant code provided by AlphaPay, e.g. CXVJIU
Response-Time: Specifies the time when a response is returned, as defined by ISO 8601. This field must be accurate to milliseconds, e.g. 2019-05-28T12:12:12+08:00
Nonce: Random-generated String with length of 32, e.g. b111bcf0dfb54d4e8bae68c293d85e2e
Response-Body: The data body of the response, formatted in JSON

By complying with the syntax of Content_To_Be_Validate, construct the response given above as follows:

Content to verify

POST /api/v2.0/payments/pay
CXVJIU.2019-05-28T12:12:12+08:00.b111bcf0dfb54d4e8bae68c293d85e2e.{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
   }
}

3. Get the signature from the response header

The target signature string (target_signature) can be extracted from the Signature field in the Response Header. For details about the response header, see Response Header.

Syntax of Signature:

Signature: algorithm=RSA256, keyVersion=1, signature=<target_signature>

An example of a completed Signature:

Signature: algorithm=RS256, keyVersion=1, signature=d%2FqFC126U57guKgRRXnd4colw5Ed5tpq3NDh2M5JOtfDivAze4X%2BYEaUCWHNW7h02sSed7hsnsDtM2rjtYe8kqAJTV9fMLzraeUZvWBh4j8Sf2D%2Bcz4bJ23S4F7VtoWaxMWjySwWuS0nMQweg%2BM7MY1HQFz2EXZjAa4CVflxU1I61NuEURfiYJGW%2BLEf%2FPVPEgzBLO8LopYMovmgO7Fl97E9UVFZnFW37bSaEdkNCffJlBU00AYWKaXbsARLarETkY9NA8nTJ5yDwjKm4rH3O%2FUhwGYnwLAvozKKjfWLU4m15LoAUF30Tap6d7IGFfewnLxdY34sVYG3Nx6m0Mit%2Bg%3D%3D

Then target_signature is the value of signature

d%2FqFC126U57guKgRRXnd4colw5Ed5tpq3NDh2M5JOtfDivAze4X%2BYEaUCWHNW7h02sSed7hsnsDtM2rjtYe8kqAJTV9fMLzraeUZvWBh4j8Sf2D%2Bcz4bJ23S4F7VtoWaxMWjySwWuS0nMQweg%2BM7MY1HQFz2EXZjAa4CVflxU1I61NuEURfiYJGW%2BLEf%2FPVPEgzBLO8LopYMovmgO7Fl97E9UVFZnFW37bSaEdkNCffJlBU00AYWKaXbsARLarETkY9NA8nTJ5yDwjKm4rH3O%2FUhwGYnwLAvozKKjfWLU4m15LoAUF30Tap6d7IGFfewnLxdY34sVYG3Nx6m0Mit%2Bg%3D%3D

4. Verify the signature

The syntax of validating the signature is as follows:

IS_SIGNATURE_VALID=sha256withrsa_verify(base64Decode(urlDecode(<target_signature>)), <Content_To_Be_Validated>, <serverPublicKey>)

sha256withrsa_verify: The method to verify the signature
urlDecode: The method to URL decode the signature
base64Decode: The method to base64 decode the signature
target_signature: 从The target signature obtained from Step 3
Content_To_Be_Validated: The content to be verified, created from Step 2
serverPublicKey: The AlphaPay public key obtained from Step 1
IS_SIGNATURE_VALID: A Boolean value that specifies whether the signature is valid
- true: The signature is valid
- false: he signature is invalid