Recover failed payments - Zahlo Merchant Developer Docs

A failed payment is a state in the payment or invoice lifecycle, not a reason to create a replacement charge immediately. Preserve the original ID, explain the next action to the customer, and reconcile later events against the same record.

async function recoverPayment(paymentId) {
  const response = await fetch(`${API_URL}/api/v1/payments/${paymentId}`, {
    headers: { "x-api-key": process.env.ZAHLO_API_KEY },
  });
  if (!response.ok) throw new Error(`payment lookup failed: ${response.status}`);
  return response.json();
}

Payment recovery flow

Receive a verified failed or action-required event.
Mark the order or entitlement as needing payment action, without fulfilling it.
Show a safe recovery path, such as returning to checkout or opening the customer portal.
When a later confirmed event arrives, transition the same order idempotently.
Alert or contact the customer according to your dunning policy.

Subscription and invoice recovery

An invoice can move from open to paid after a retry, or from open to uncollectible or void according to your policy. Keep access decisions tied to the latest verified invoice and subscription state. Do not delete the customer or subscription because one attempt failed.

Retry rules

Network failures and temporary server responses can be retried with bounded backoff. Reuse the original idempotency key for the same create operation. Validation and authentication failures require a corrected request. If the response is ambiguous, retrieve the payment or invoice by ID before attempting another action.