Skip to main content

Offline Mode

This guide shows how to keep the POS running during temporary network outages (loss of connectivity between the POS and the SIGN FR API) and how to safely buffer records offline for later replay.

In online mode, retain two values from every successful createRecord response: the last online record ID and the last online journaling signature. These anchor offline data to the server journal and provide the initial cryptographic seed.

When connectivity drops, switch to offline mode. Write each new record to a durable local buffer in original order. You can operate offline for up to 24 hours from the first unsent record. After that, stop processing new transactions, decommission the POS, and reset it.

On reconnection, replay the buffer. Wrap each record in a “Replay Intention” that includes the original timestamp, an anchoring record ID, and a seed. For transactions, add an offset that links the transaction to its corresponding intention in the buffer.

Ensure integrity by hashing the canonicalised content (excluding metadata) with SHA-256. Seed the first offline entry with the last online journaling signature, then chain each next entry to the previous record’s hash.

The diagram illustrates the workflow and highlights the essential steps necessary to successfully handle the Offline mode and Replay process.

Offline and Replay Implementation diagram​

Offline and Replay Implementation diagram

STEP 1: Online Mode​

During normal connectivity, two specific fields from every successful createRecord response must be tracked in the POS: the last online record ID (content.id) and the last online record journaling signature (content.journal.signature). These values are essential for anchoring the offline records and providing the initial cryptographic seed for hashing.

STEP 2: Outage – Local Buffering (Storage)​

When connectivity is lost, switch to offline mode and write every new record to a durable local buffer, keeping the original order. A POS may run offline for at most 24 hours from the first unsent record; if the outage exceeds this limit, stop taking new transactions, decommission the POS, and reset it. When the connection is restored (step 4), wrap each buffered record in a “Replay Intention” envelope that includes the original timestamp, the anchoring record ID, and a seed. For transaction records, also include an offset that links the transaction to the correct intention index in the buffer. Replay the records in order.

STEP 3: Security – Hashing and Seeds​

To ensure data integrity, compute a SHA-256 hash for the canonicalised content of each record, excluding any original metadata. The first offline record uses the last online journaling signature as its seed, while all subsequent records use the hash of the previous record as their seed. This creates a secure chain that the server can verify during the replay process.

STEP 4: Restoration – Replaying Records​

Once connectivity is restored, replay all buffered records in their original sequence using the createRecord endpoint of type INTENTION and operation.type REPLAY. Every request must include two mandatory header parameters: X-Replay-Hash (the base64 hash created offline) and X-Replay-Remaining (the count of records still in the buffer). Records should only be deleted from the local storage after the server successfully acknowledges them.

STEP 5: Finalising – Returning to Online Mode​

If the last record in the buffer is an intention, the merchant must capture the resolved ID from the server's response to use as the anchor for their first new online transaction. If connectivity drops again during the replay, simply transition back to the offline phase and continue using the original anchoring data until the entire buffer is cleared and a new online response is received.

Minimal replay examples:​

Header Parameters​

X-Replay-Hash: <offline computed SHA-256 hash, base64-encoded>
X-Replay-Remaining: <remaining after this one>

Intention → Transaction (wrapped for replay)​

{
  "content": {
    "type": "INTENTION",
    "system": { "id": "0199147a-8627-7101-aecc-d2149aa99ea7" },
    "operation": {
      "type": "REPLAY",
      "recorded_at": "2025-11-14T10:30:00+01:00",
      "record": { "id": "01695553-c90c-745a-b76f-770d7b3dcb6d" },
      "seed": "<base64 seed>",
      "content": {
        "type": "TRANSACTION",
        "record": { "id": "019a7e09-1590-738f-aa21-8ca7b58d9ccc", "offset": "0" },
        "operation": { "type": "RECEIPT" }
      }
    }
  }
}