Handling Transaction States

​

The 4 states

​

Recommended implementation

async function handleTransaction(event, payload) {
  const txId = payload.id;
  const state = payload.state; // from X-Event suffix or payload.state

  switch (event) {
    case 'card.transaction.authorized':
      // Create if not exists (upsert by id)
      await db.transactions.upsert(txId, { ...payload, status: 'pending' });
      break;

    case 'card.transaction.cleared':
    case 'card.transaction.invoiced':
      // Update existing OR create if you skipped authorized
      await db.transactions.upsert(txId, { ...payload, status: 'confirmed' });
      break;

    case 'card.transaction.deleted':
      // Only relevant if you stored authorized
      await db.transactions.delete(txId);
      break;
  }
}

​

The golden rules

1. Always handle cleared — non-negotiable for accounting
2. authorized + deleted + cleared = best UX (users see purchases instantly, deletions handled)
3. authorized alone = you’ll miss transactions that clear without prior auth (rare but possible)
4. Use id as primary key — same id across all states for one transaction
5. card_issuer_reference differs per state — don’t use it as your primary key; when merging with another feed, compare cleared-to-cleared only → Current card issuer integration

​

Current card issuer integration

• Start the OpenCard feed per card holder on card_holder.identified (includes a retroactive batch).
• Upsert on transaction id for OpenCard events.
• On card.transaction.cleared, deduplicate against your other store with card_issuer_reference — cleared matches cleared only; auth and cleared references may differ per issuer.

​

Upsert logic detail

​

receiptable flag

{ "receiptable": true }

​

Card types

​

Card funding

​

VAT caveat