Digital receipt lookup pull guide

​

1. Enabling the feature

1. Set Digital receipt lookup URL to your host and path without the https:// prefix (for example api.example.com/v1/chargeblast/digital_receipt_lookup). Chargeblast calls https://{that value}.
2. Turn the toggle on.
3. Note two secrets (both can be rotated independently):
   • Lookup key — sent as plaintext in X-Digital-Receipt-Lookup-Key.
   • Lookup signature key — used only on your side to verify X-Digital-Receipt-Signature (HMAC; see HMAC-SHA256 signature).

​

Testing in the app

​

2. Request method, URL, and headers

​

Where the digest is (no separate timestamp)

• The digest is the header value X-Digital-Receipt-Signature. It is not in the JSON body. The string is exactly 64 characters (0–9, a–f): the hex encoding of the 32-byte HMAC-SHA256 output. There is no separate Digest field, body field, or second signature—if you do not see a digest, check request headers, not the body. (The dashboard Send test webhook cURL includes the same header.)
• There is no timestamp header (for example no X-Digital-Receipt-Timestamp) and nothing is prepended or appended to the body before HMAC. The MAC uses only the lookup signature key (UTF-8, as the HMAC key) and the raw POST body bytes (as the message). You do not need a timestamp to compute or verify the signature: re-read the exact body bytes from the request, run the same HMAC with your stored secret, and compare to the header (prefer constant-time comparison).
• Replay: The signature does not by itself prevent replay of a captured valid request. Mitigate with HTTPS, rotating keys, idempotent handlers, and your own rate limiting as needed.

​

3. Request body (wire format)

​

3.1 Primary keys for matching (always present)

​

3.2 source

​

3.3 JSON serialization (critical for HMAC)

• JSONSerialization with .sortedKeys — keys are in sorted order at every object level.
• UTF-8 encoding.

​

3.4 Other fields (optional)

​

4. HMAC-SHA256 signature algorithm

​

4.1 Steps (normative for interoperability)

1. Let secret be the lookup signature key string from Chargeblast settings (UTF-8 bytes).
2. Let body be the raw HTTP request body as received (the same bytes as in Content-Length). Treat it as a UTF-8 string only if you know it is valid UTF-8 JSON; the HMAC is over those bytes.
3. Compute HMAC_SHA256(secret_utf8, body_bytes) using the standard library for your language (see examples below).
4. Encode the 32-byte MAC as lowercase hex (64 characters): each byte as two hex digits 00–ff, no separators, no 0x.
5. Compare that string to X-Digital-Receipt-Signature using constant-time equality when possible. Do not expect a timestamp header or a t= / v1= style signed prefix—those are not used here.

​

4.2 Reference implementation (Chargeblast server)

• Key material: SymmetricKey(data: Data(secret.utf8))
• Message: Data(body.utf8) where body is the exact JSON string used as the POST body
• Output: hex string via %02hhx per byte (lowercase), set as the X-Digital-Receipt-Signature header value

​

4.3 Examples (Node.js, Python, Go)

const crypto = require("crypto");

function digitalReceiptSignature(secret, bodyBuffer) {
  return crypto.createHmac("sha256", secret).update(bodyBuffer).digest("hex");
}

​

4.4 Verification checklist (signature mismatches)

• Using the signature secret, not the lookup key.
• HMAC is over raw body bytes, not pretty-printed JSON.
• Same sorted-key canonical form as the sender (or read body as sent and do not reserialize before verifying).
• Compare hex case-insensitively if your stack emits uppercase (Chargeblast sends lowercase).
• Expecting a timestamp or signed-prefix scheme—none is sent; only the header + body HMAC applies.

​

5. Using only the lookup key (weaker authentication)

• Possession of the lookup key alone is not enough to forge payloads without knowing the signature secret (and without breaking HMAC).
• The body cannot be tampered with in transit without invalidating the MAC (assuming the secret stays private).

​

6. Response: HTTP status

​

7. Minimal successful JSON (top-level keys)

​

7.1 Required for a valid minimal receipt (decode succeeds)

​

7.2 Optional on the minimal path (but useful)

​

7.3 Compelling evidence (CE) vs “valid receipt”

• order.transactionDetails.deviceIpAddress is important for CE but not part of the minimal required-field list above.
• Other CE-related gaps are derived from the mapped receipt shape (merchant descriptors, product description, customer identifiers, delivery address, etc.).

​

8. Example minimal body (illustrative)

{
  "order": {
    "merchantOrderId": "ord_123",
    "orderDateTime": "2026-01-15T10:07:20Z",
    "total": "15.00",
    "subtotal": "15.00",
    "currencyCode": "USD",
    "orderPhone": "+13612221788",
    "orderItems": [
      {
        "id": "line_1",
        "quantity": "1",
        "productName": "Subscription",
        "productPrice": "15.00"
      }
    ],
    "transactionDetails": {
      "deviceIpAddress": "203.0.113.10"
    }
  },
  "merchantProfile": {
    "name": "Example Co",
    "merchantReceiptContact": {
      "emailForReceipt": "support@example.com",
      "phoneForReceipt": "+18005550100",
      "websiteForReceipt": "https://example.com"
    }
  },
  "accountProfile": {
    "name": { "givenName": "Jane", "familyName": "Doe" },
    "email": "jane@example.com",
    "accountBillingAddress": {
      "city": "Austin",
      "country": "US",
      "postalCode": "78701"
    }
  }
}

​

9. Idempotency and side effects

​

10. SLA and deflection eligibility

​

Related

• Digital Receipts & Deflections — Pull vs push, qualifying fields, monitoring
• Deflection Logs — Poll blocked chargebacks
• Implementation Overview — Compare integration paths