Transactions and reconciliation - Zahlo Merchant Developer Docs

Payments describe the customer-facing charge lifecycle. Transactions describe the resulting money movement. Keep both IDs and reconcile them to your order, currency, and amount.

Retrieve a transaction

const response = await fetch(
  "https://merchant.zahlo.eu/api/v1/transactions?limit=50&offset=0",
  { headers: { "x-api-key": process.env.ZAHLO_API_KEY } },
);
const page = await response.json();
for (const transaction of page.data) {
  await reconcileTransaction(transaction);
}

Run reconciliation from a durable job, not from a browser return page. Store the last successful offset or checkpoint, but make the job safe to replay because new events can arrive while a page is being processed.

Reconciliation checks

Compare payment ID, transaction ID, order ID, amount, currency, and final status. Record unmatched, duplicated, or out-of-order records for manual review. Never “repair” a mismatch by creating a second charge.

Refunds and balances

A refund may remain pending after the request is accepted. Reconcile the final refund event and update the order once. Use the balance endpoint for operational reporting; do not use a displayed balance as proof that an individual customer payment was fulfilled.