Signature & Code samples

RSA-SHA512 API request signing

I. Purpose

To protect API integrity and authenticate the caller, the platform uses RSA signatures with an SHA-512 digest (algorithm name SHA512withRSA). The signature proves the request came from the merchant and that the path, body, and timestamp were not changed.

II. When signing is required

Signing applies to all API requests between the merchant and Setu. Setu-to-merchant callbacks and responses are signed as well. Their string to sign is defined in section IV and does not include the request path.

III. Structure and rules

Every request must include a Signature header computed as described below, together with MerchantID and Timestamp.

Signing algorithms

Digest: SHA-512 (512-bit Secure Hash Algorithm)

Signature: RSA, PKCS#1 v1.5, signed with the merchant private key

Algorithm name: SHA512withRSA

Signing procedure

Step 1: Hash the request body (Body Hash)

Hash the exact JSON body bytes that will be sent (UTF-8) with SHA-512, and encode the digest as lowercase hex (128 characters).

For GET, DELETE, and any request with an empty body, skip this step. Do not place the SHA-512 of an empty string into the string to sign.

Example body (no trailing newline):

{"merchantRef":"0954f567-ea8f-49b4-920f-c49174aa2c1f","amount":100,"currency":"INR","method":"NATIVE","name":"LuciaLesch","phone":"82445415208","email":"quinten31@yahoo.com","redirectUrl":"https://www.redirect.com/"}

Lowercase hex SHA-512 of that body:

bfcd0c58c547c1d5960c73a6cf130cf5ae3f96d115392bdc678a36dab1ea08bdaf271b73db17650536a0a78d04d771557f9c5d71596e36547fb2089deb780784

Step 2: Build the string to sign

With a body:

stringToSign = requestPathUri + sha512Hex + timestamp

With no body:

stringToSign = requestPathUri + timestamp

requestPathUri is the path only. It starts with / and does not include the scheme, host, or query string.

Example with a body and timestamp 1699447297:

/v1/api/payment/initiatebfcd0c58c547c1d5960c73a6cf130cf5ae3f96d115392bdc678a36dab1ea08bdaf271b73db17650536a0a78d04d771557f9c5d71596e36547fb2089deb7807841699447297

Sign with private key

Sign the UTF-8 bytes of stringToSign with the merchant RSA private key using SHA512withRSA.

Base64-encode the signature bytes with the standard alphabet to produce the Signature header.

Headers:

Header	Value
`MerchantID`	Merchant id
`Timestamp`	The same Unix timestamp, in seconds, that was concatenated above
`Signature`	The Base64 value from this step
`Content-Type`	`application/json` when the request has a body

IV. Security notes

The merchant signs requests with its private key. Setu verifies them with the merchant public key.
For Setu-to-merchant callbacks and responses, Setu signs with its private key and the merchant verifies with Setu’s public key. The string to sign is sha512Hex + timestamp, with no requestPathUri.
The path, body hash, and timestamp are all covered by the signature. None of them can be changed after signing.

V. Important notes

The string to sign is case-sensitive and must match byte for byte. The body hash must be lowercase hex.
Hash the raw body bytes that are sent. Field order, whitespace, and number-versus-string differences all change the hash.
Timestamp is the current Unix time in seconds, and it must be the same value concatenated into the string to sign.
Signature is standard Base64 (alphabet includes +, /, and =), on a single line, and is case-sensitive. Do not use URL-safe Base64.
The private key is PKCS#8 (-----BEGIN PRIVATE KEY-----).

VI. Code samples

Java

Python

PHP

C#(.NET Core)

Signature & Code samples

RSA-SHA512 API request signing#

I. Purpose#

II. When signing is required#

III. Structure and rules#

IV. Security notes#

V. Important notes#