Refunds

Create refunds from trusted server code using the payment ID. For a partial refund, send an amount in minor units; otherwise refund the remaining amount. Use a unique key per intended refund and reuse it when the response is lost.

Create a refund

const response = await fetch("https://merchant-demo.zahlo.eu/api/v1/refunds", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.ZAHLO_API_KEY,
    "Idempotency-Key": `refund-${order.id}-1`,
  },
  body: JSON.stringify({
    paymentId: order.paymentId,
    amountMinor: 4990,
    reason: "requested_by_customer",
  }),
});
if (!response.ok) throw new Error(`refund request failed: ${response.status}`);

Record the refund ID in your order system and process refund events idempotently. A refund request being accepted is not the same as a completed refund, so update customer-facing state from the final refund event. For a partial refund, keep the remaining captured amount and fulfillment record explicit. Before refunding, verify the merchant payment, amount, currency, and order ownership. Do not accept a payment ID or amount from an untrusted browser without resolving it against your own order.

Start here

Core concepts

Accept payments

Sell online

Subscriptions

Integrations

Operations

Create a refund

​Create a refund

Create a refund