🔐 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 – Amount Type and Checksum Validation

The amount field uses different numeric representations depending on the message direction:

• Requests: amount is sent as a string (e.g. "200.00")
• Callbacks: amount is returned as a numeric value (e.g. 200.0)

Facilero processes amounts using native numeric types. As a result, decimal formatting (such as trailing zeros) is not preserved in callbacks.

Example:

• Request: "200.00"
• Callback: 200.0

When validating or generating a callback checksum, always use the exact amount value received in the callback payload.

Do not reuse or reformat the original request amount, as this may cause checksum mismatches.