How to verify callback signature

All callback requests sent by our system are cryptographically signed using RSA-SHA256. This allows you to verify that each callback was sent by us and has not been tampered with in transit.

Algorithm

Property	Value
Algorithm	RSA-SHA256
Signature Encoding	Base64

Headers

Every callback request includes the following signature headers:

Header	Description	Example
`X-Signature-Timestamp`	Unix timestamp (10 digits, seconds since epoch)	`1713982800`
`X-Signature`	Base64-encoded RSA signature of the signed payload	`dGhpcyBpcyBhbiBleGFtcGxlIHNpZ25hdHVyZSE...`
`X-Signed-By`	Public key identifier (used to fetch the correct certificate from `/certificates`)	`5ac5ae43-01d2-4c70-8a5b-b69a34d11c62`

Signed Payload Construction

To verify the signature, you must reconstruct the exact signed payload that was used during signing:

signed_payload = timestamp + "." + raw_body_bytes

Where:

timestamp is the value from X-Signature-Timestamp header (as a string)

. is a literal period character (ASCII 46)

raw_body_bytes is the raw, unmodified HTTP request body (as bytes, not parsed JSON)

Example

Given:

X-Signature-Timestamp: 1785430667

Body:

{ "approved_on": "2026-07-30T14:53:34.964208905Z", "country": "SV", "created_on": "2026-07-30T14:53:27.210213Z", "currency": "USD", "fee": 0, "merchant_transaction_reference": "34ac9a13-b435-41f4-9d71-0db142b712c6", "payment_method": "cuscatlan", "status": "approved", "tax": 0, "transaction_amount": 1000, "transaction_id": "20260730-1453-4015-a22f-b18176861ca3", "transaction_type": "pay_in" }

The signed payload is:

1785430667.{ "approved_on": "2026-07-30T14:53:34.964208905Z", "country": "SV", "created_on": "2026-07-30T14:53:27.210213Z", "currency": "USD", "fee": 0, "merchant_transaction_reference": "34ac9a13-b435-41f4-9d71-0db142b712c6", "payment_method": "cuscatlan", "status": "approved", "tax": 0, "transaction_amount": 1000, "transaction_id": "20260730-1453-4015-a22f-b18176861ca3", "transaction_type": "pay_in" }

Important: Do not parse, format, or modify the JSON body before verification. Use the raw bytes exactly as received.

Verification Steps

Extract X-Signature-Timestamp, X-Signature, and X-Signed-By from the request headers

Verify the timestamp is within your tolerance window (recommended: 300 seconds / 5 minutes)

Fetch the public keys from Signing public keys and choose the correct one based on X-Signed-By header value (please refer Public Key Caching section).

Reconstruct the signed payload: timestamp + "." + raw_body

Compute SHA-256 hash of the signed payload

Base64-decode the X-Signature header

Verify the RSA signature using the public key

Public Key Caching

We recommend caching the certificates response locally to avoid fetching it on every callback notification, we rotate the certificates every month, but we preserve the previous one to ensure all signatures can be verified.

You could use the expires_at field of the latest certificate as TTL.

Implementation Note

Since only 2 certificates exist at any time, storing the full response is the recommended approach.

Code Examples

Go

JavaScript (Node.js)

C#

Java

Python

PHP

Important Notes

Always verify before parsing. Do not parse the JSON body until the signature has been verified.

Use raw bytes. Do not convert the body to string, format, or re-serialize the JSON before verification.

Timestamp tolerance. We recommend rejecting callbacks with timestamps older than 5 minutes (300 seconds) to prevent replay attacks.

Key rotation. When we rotate signing keys (every month), a new X-Signed-By identifier will be used.

How to verify callback signature

Algorithm#

Headers#

Signed Payload Construction#

Example#

Verification Steps#

Public Key Caching#

Implementation Note#

Code Examples#

Go#

JavaScript (Node.js)#

C##

Java#

Python#

PHP#

Important Notes#