Bank payments - Zahlo Merchant Developer Docs

Bank payments can require a customer redirect, bank approval, and delayed confirmation. Use the same checkout session and webhook model as other methods, but design the customer journey around a visible pending state.

Offer a bank method

Discover eligible methods for the amount, currency, country, and mode. Create a hosted or in-page session using the returned method type.

const methods = await fetch(
  "https://merchant-demo.zahlo.eu/api/v1/payment-methods?currency=EUR&amountMinor=4990&country=DE&mode=hosted",
  { headers: { "x-api-key": process.env.ZAHLO_API_KEY } },
).then((response) => response.json());
const bank = methods.methods.find((method) => method.type === "bank" && method.enabled);
if (!bank) throw new Error("No eligible bank method");

Redirect and return

Preserve the order and session ID while the customer authorizes the payment. On return, show pending until your server receives or retrieves confirmation. A customer closing the bank window, returning early, or losing connectivity is not proof of failure.

Reconciliation

Verify events and correlate payment ID, order ID, amount, and currency. Retry event processing safely and reconcile delayed events by listing webhook events or retrieving the payment. Never create a replacement payment solely because bank confirmation is delayed.