SNAP Signature

Signature Generation and Validation

The below explains about signature generation & validation.

Asymmetric Signature

Asymmetric signature is used verify your access token request. The signature needs to be provided using a private key. Paydia's system supports the use of PKCS#8 for the private key, thus merchant should generate the signature with pkcs8_rsa_private_key.pem. The generated signature will be verified using a public key with rsa_public_key.pem. The algorithm used by Paydia is SHA256withRSA and the format type is Base64.

Asymmetric Key Generation

The following steps of asymmetric key generation.

1. Create Private Key

   openssl genrsa -out rsa_private_key.pem 2048

2. Export Public Key

   openssl rsa -in rsa_private_key.pem -out rsa_public_key.pem -pubout

3. Private Key to PKCS#8 Encode

   openssl pkcs8 -topk8 -in rsa_private_key.pem -out pkcs8_rsa_private_key.pem -nocrypt

After the merchant obtains the public key, they need to share it with Paydia to continue the signature process.

Signature Generation

The following steps are used to explain how to generate the digital signature used by the sender of APIs.

The following steps are used for Asymmetric Signature:

1. Prepare the data to do signature, the data are:

   No	Data	Remarks	Example
   1	X-CLIENT-KEY	Unique identifier for partner was generated by Paydia, or known as clientId	4abbcb6ce30229994c76169006e0dc9c
   2	X-TIMESTAMP	Transaction date time, in format YYYY-MM-DDTHH:mm:ss+07:00. Time must be in GMT+7 (Jakarta time)	2024-07-25T07:01:08+07:00

2. Compose the string to sign

   <X-CLIENT-KEY> + "|" + <X-TIMESTAMP>

   The following is the example:

   4abbcb6ce30229994c76169006e0dc9c|2024-07-25T07:01:08+07:00

3. The signature string is generated from string to sign above with applying SHA-256 with RSA-2048 encryption using PKCS#8 or PKCS#1 private key, and then encode the result to base64. Refer to the tools section number 3 for the example process.

   caqCS4JSfv1A2R8oTXT0tzQrZkAgkezPrs7yG17yKp1V0UmmXjW/Ju4eAHgVBqNTloRFwjKx63HNATEzL8QId4TJa3OudeRwGDZq2LWoEg+5YGVkjReFkQJiWYOBxaCsMZj8wSoE7ip/NlJc+5ufNM4m9A2UMjhwesnkPB9dd9wSuZJ8exMJMr7RgPq+9//5yzBZALXhdwpRvseccnlWizCWt0WGE83+pBV4wDv3hXYgChICjzMlmw8+nHoGtnPGlKKajWC9u8Ex8Mw9iTCWgycRNQVT+CaeLBZmkylKtJbHArENkWsnQsxrDKXEwSWgrLSR1OdxwUT4HN1t52+AHg==

4. Put the signature string into HTTP header "X-SIGNATURE". The following is the example value:

   X-SIGNATURE: caqCS4JSfv1A2R8oTXT0tzQrZkAgkezPrs7yG17yKp1V0UmmXjW/Ju4eAHgVBqNTloRFwjKx63HNATEzL8QId4TJa3OudeRwGDZq2LWoEg+5YGVkjReFkQJiWYOBxaCsMZj8wSoE7ip/NlJc+5ufNM4m9A2UMjhwesnkPB9dd9wSuZJ8exMJMr7RgPq+9//5yzBZALXhdwpRvseccnlWizCWt0WGE83+pBV4wDv3hXYgChICjzMlmw8+nHoGtnPGlKKajWC9u8Ex8Mw9iTCWgycRNQVT+CaeLBZmkylKtJbHArENkWsnQsxrDKXEwSWgrLSR1OdxwUT4HN1t52+AHg==

Symmetric Signature

Symmetric signature is used to verify your SNAP service request. The signature needs to be provided using a client secret. The algorithm used by Paydia is SHA-512 HMAC and the format type is Base64.

Signature Generation

The following steps are used for Symmetric Signature:

1. Prepare the data to do signature, the data are:

   No	Data	Remarks	Example
   1	HTTP METHOD	Method on each API, for instance GET, POST, PUT, PATCH, and DELETE	POST
   2	RELATIVE PATH URL	URL on each API	/snap/v1.0/qr/qr-mpm-generate
   3	ACCESS TOKEN B2B	Access token b2b from Authorization Token Request	eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJQYXlkaWEiLCJpYXQiOjE3MjE4OTU5OTksImV4cCI6MTcyMTk4MjM5OX0.eewVuMxRfBhWjEUqaxHn09a5Uw7KGqKuan5vRnV5xzw
   4	HTTP BODY	Minify request body and hash the request body with SHA-256, refer to step no 2 and 3 for the detail	0932935ef0fff8e78818c8f2d8da5bc85e1d3e4692500fec48ef9b084f70d127
   5	X-TIMESTAMP	Transaction date time, in format YYYY-MM-DDTHH:mm:ss+07:00. Time must be in GMT+7 (Jakarta time)	2024-07-25T15:33:58+07:00

2. Minify the request body

   The following are the example value before and after minify the request body:

   HTTP BODY BEFORE MINIFY:

   {
       "merchantId": "240212001000000",
       "storeId": "12345",
       "terminalId": "Device 1",
       "partnerReferenceNo": "9cd55c25-7257-416d-8d70-1c16303ed4ba",
       "amount": {
           "value": "10000.00",
           "currency": "IDR"
       },
       "feeAmount": {
           "value": "0.00",
           "currency": "IDR"
       },
       "validityPeriod": "2024-12-31T23:59:59+07:00",
       "additionalInfo": {
           "callback": "https://webhook.site/36da5887-f4eb-46d5-a29c-91b765efb0aa"
       }
   }
   HTTP BODY AFTER MINIFY:

   {"merchantId":"240212001000000","storeId":"12345","terminalId":"Device 1","partnerReferenceNo":"9cd55c25-7257-416d-8d70-1c16303ed4ba","amount":{"value":"10000.00","currency":"IDR"},"feeAmount":{"value":"0.00","currency":"IDR"},"validityPeriod":"2024-12-31T23:59:59+07:00","additionalInfo":{"callback":"https:\/\/webhook.site\/36da5887-f4eb-46d5-a29c-91b765efb0aa"}}

3. Lowercase(HexEncode(SHA-256(RequestBody)))

   The following is the example value:

   0932935ef0fff8e78818c8f2d8da5bc85e1d3e4692500fec48ef9b084f70d127

4. Compose the string to sign

   <HTTP METHOD> + ":" + <RELATIVE PATH URL> + ":" + <ACCESS TOKEN B2B> + ":" + LowerCase(HexEncode(SHA-256(Minify(<HTTP BODY>)))) + ":" + <X-TIMESTAMP>

   The following is the example:

   POST:/snap/v1.0/qr/qr-mpm-generate:eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJQYXlkaWEiLCJpYXQiOjE3MjE4OTU5OTksImV4cCI6MTcyMTk4MjM5OX0.eewVuMxRfBhWjEUqaxHn09a5Uw7KGqKuan5vRnV5xzw:0932935ef0fff8e78818c8f2d8da5bc85e1d3e4692500fec48ef9b084f70d127:2024-07-25T15:33:58+07:00

5. The signature string is generated from string to sign above with applying SHA-512 HMAC encryption using Client Secret and then encode the result to base64. Refer to the tools section number 3 for the example process.

   The following is the example value:

   gA/Wjtpav1+8iod60CahNocr5Jpa20+4o/Gm91DN7KcMJKSygTfgxDYudOnElEU//Bhvm8y9GOw8svakl+vL3Q==

6. Put the signature string into HTTP header "X-SIGNATURE".

   The following is the example value:

   X-SIGNATURE: gA/Wjtpav1+8iod60CahNocr5Jpa20+4o/Gm91DN7KcMJKSygTfgxDYudOnElEU//Bhvm8y9GOw8svakl+vL3Q==

Signature Validation

The following steps are used to explain how to validate the digital signature used by the receiver of APIs:

1. Take the signature from HTTP header "X-SIGNATURE" from the sender of APIs.

   The following is the example:

   X-SIGNATURE: zy2qZG+iEvRakVi0rR2fj9O8N5luMYUKa07tdiPtVP6V6tYJgkCPrZ1NyJIZLnaDko21KIBwpXbOU+XuOuG\/GMUUP3v6R9Jx3ld4yyYs4QQzahvyyixxOsHphhTg\/ZHjfWBa5Pvg76i3WBfim1ZFsY4Y\/qgcVosbh1YGGrvu\/Wr8w2qbRv5\/05K9XQiln9r6cboiiIc7RjOCEaAHWf61s3ybPuxpiSM05zlvfZXYXDgtEnV7OIULdtAUK6sHNYE8HghwzZEJ0tM+Zy7PEuVh9gfsNqPmKJ0A\/JUT9IN1R9sGIwA6RnCcJVjmeqy7+q9A0s9LEcmhQOQZEX4Uwj\/uIA==

2. Compose the string to verify

   <HTTP METHOD> + ":" + <RELATIVE PATH URL> + ":" + LowerCase(HexEncode(SHA-256(Minify(<HTTP BODY>)))) + ":" + <X-TIMESTAMP>

   The following is the example:

   POST:/v1.0/qr/qr-mpm-notify:d3a7ddb7196ce272c7e9868113b953db233e5a61f27383b5a561c32501cd9a94:2024-07-25T15:52:56+07:00

3. Verify the correctness of the signature based on SHA-256 with RSA-2048 encryption signing against the string to sign with provided public key of sender of APIs. In this case is Paydia public key.

4. If the verification is correct, then consume the request.