​

Introduction

This section details how to integrate the optional payload signature mechanism to ensure the integrity and authenticity of API requests.

​

Prerequisites

Before utilizing the payload signature feature, the following steps must be completed:

1. Generate Cryptographic Keys: A unique public and private key pair must be generated using a secure cryptographic algorithm (e.g., RSA, ECDSA). The private key will be used to sign the request payload, and the corresponding public key will be used by the system to verify the signature.
2. Upload Public Key: The generated public key must be securely uploaded to the merchant preferences within the dashboard. This allows the system to associate the public key with the account for signature verification. Assistance with this step can be requested from the support team if necessary.

​

Sandbox Environment Integration

During development and testing in the sandbox environment, implementation of the payload signature can begin:

1. Construct the X-Signature Header: For each API request made with the mode=sandbox parameter, an X-Signature header can be included in the request.
2. Generate the Signature: The value of the X-Signature header should be the cryptographic signature of the JSON request body, generated using the private key. The specific signing process will depend on the chosen cryptographic algorithm.
3. Signature Verification (Sandbox): When a request with the mode=sandbox parameter includes the X-Signature header, the system will attempt to verify the signature using the public key associated with the account.

• If the signature is valid, the request will be processed normally.
• If the signature is invalid or malformed, the API will return an error indicating a signature verification failure.
• Note: If the X-Signature header is not present in sandbox mode requests, it will be ignored, and the request will proceed without signature verification.

​

Live Environment Enforcement

To enforce payload signature verification for live transactions (mode=live), an additional step is required:

• Enable “Force Signature” on Dashboard: Within the merchant dashboard, the option to “force traffic to use signature” can be enabled by ticking the corresponding checkbox.
• Signature Verification (Live): Once this option is enabled:
  • All subsequent API requests with mode=live must include a valid X-Signature header.
  • If a request in mode=live is missing the X-Signature header or contains an invalid signature, the API will return an error indicating a signature verification failure.
  • Note: Before enabling this option in the live environment, ensure that signature generation and handling are correctly implemented and thoroughly tested in the sandbox environment.

By following these steps, the payload signature feature can be effectively integrated and utilized to enhance the security of transactions. Secure management of the private key and keeping the public key updated in the dashboard are essential.