Checksum Authentication Guide

To guarantee data integrity and authenticity for all communications, Exirom implements a checksum verification mechanism using the HMAC-SHA256 algorithm with your merchantSecret.

This checksum ensures:

• The request/callback data has not been altered in transit.
• The sender is genuinely authenticated using the shared secret.

When to Use the Checksum

How to Generate the Checksum

From Merchant to Exirom (Request)

Use the following fields in this exact order as strings:

accountId | amount | currency | requestId

From Exirom to Merchant (Callback)

Use the following fields in this exact order as strings:

accountId | amount | currency | transactionId

Apply HMAC-SHA256

• Use the pipe character (|) as a delimiter.
• Sign the concatenated string using HMAC-SHA256 with your merchantSecret.
• Base64-encode the resulting hash before sending.

Example: Request

Data:

accountId: merchant_001
amount:    1000
currency:  USD
requestId: req-789123

Checksum string:

merchant_001|1000|USD|req-789123

Send in body:

{
  "accountId": "merchant_001",
  "amount": "1000",
  "currency": "USD",
  "requestId": "req-789123",
  "checksum": "<Base64EncodedChecksum>"
}

Example: Callback

Data:

accountId: merchant_001
amount:    1000
currency:  USD
transactionId: tx-456789

Checksum string:

merchant_001|1000|USD|tx-456789

Sent as header:

X-Checksum: <Base64EncodedChecksum>

How to Format the amount Field

Use the smallest currency unit, without decimals or currency symbols.

✅ Correct Format

❌ Incorrect vs ✅ Correct

💡 Multiply your float amount by 100 (or currency factor) and convert it to a string before computing the checksum.

Validation Rules in Checksum

When working with checksum authentication in Exirom, it’s important to apply strict validation rules and handle amount formatting correctly.

What are they?

Validation rules ensure that every request and callback is trusted, secure, and tamper-free.

Why are they needed?

Without proper validation, unauthorized or malformed requests could slip into your system, causing errors or even fraud.

What’s the purpose?

These rules make sure requests are only processed if they include a valid checksum, and callbacks are verified using the exact data provided. This prevents mismatches and ensures consistent integrity checks.

❗ Validation Rules

Requests without a valid checksum → ❌ Rejected with 400 BadRequest

Callbacks with invalid X-Checksum → ❌ Should be ignored by your system

⚠ Important Note on Amount Formatting

In requests, the amount field is sent as a string (e.g., "200.00").
In callbacks, the amount field is returned as a numeric double (e.g., 200.0).

Because Exirom uses native numeric types internally, trailing zeros after the decimal point may not always be preserved.

Best Practice for Checksum Validation

When validating checksums for callbacks, always use the exact amountvalue as provided in the callback payload , not the original request value.

This ensures checksum validation stays consistent and avoids mismatches caused by formatting differences.

Security Best Practices

• Never expose your merchantSecret in client-side code or logs.
• Always verify both request and callback checksums.
• Use secure timestamp validation if possible to prevent replay attacks.
• Rotate merchantSecret periodically for better security.