🔐 Checksum Authentication Guide

To ensure data integrity and authenticity, Facilero uses a checksum mechanism based on HMAC-SHA256 with your merchantSecret.

✅ When to Use the Checksum

How to Generate the Checksum

➤ In Requests (from Merchant to Facilero)

Use the following fields in this exact order as strings:

accountId | amount | currency | requestId

➤ In Callbacks (from Facilero to Merchant)

Use the following fields in this exact order as strings:

accountId | amount | currency | transactionId

In both cases:

• Use | (pipe) as a delimiter
• Sign with HMAC-SHA256 using your merchantSecret
• Base64-encode the result

Example: Request

Data:

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

Checksum string:

merchant_001|10.55|USD|req-789123

Send in body:

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

Example: Callback

Data:

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

Checksum string:

merchant_001|10.0|USD|tx-456789

Sent as header:

X-Checksum: <Base64EncodedChecksum>

❗ 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 provided as a string (e.g., "200.00").
In callbacks, the amount field is returned as a double (e.g., 200.0).

Because Facilero uses native numeric types internally, trailing zeros after the decimal point may not be preserved. This means:

• Request → "200.00"
• Callback → 200.0

When generating or validating the checksum for callbacks, always use the exactamount value as provided in the callback payload, not the original request value.

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