Use payment intents

A Payment Intent is the server-side record for one payment attempt. Use it when you need to separate creating a payment from confirming customer action, capture an authorization later, or recover an uncertain result without creating a duplicate payment.

Create the intent on your server

Resolve the final order amount and currency before creating the intent. The API key and internal order data stay on the server.

const response = await fetch(
  "https://merchant.zahlo.eu/api/v1/payment-intents",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.ZAHLO_API_KEY,
      "Idempotency-Key": `payment-intent-${order.id}`,
    },
    body: JSON.stringify({
      amountMinor: order.totalMinor,
      currency: order.currency,
      customerId: order.customerId,
      confirmationMethod: "automatic",
      captureMethod: "automatic",
      metadata: { orderId: order.id },
    }),
  },
);
const intent = await response.json();

Return the intent ID and its short-lived client token through an authenticated server response. Never return x-api-key or the webhook secret to browser code.

Confirm the payment

Use the secure SDK or the confirm endpoint to collect payment details and complete customer action. The confirmation response describes the next state; it does not guarantee settlement.

const confirmation = await fetch(
  `${API_URL}/api/v1/payment-intents/${intent.id}/confirm`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.ZAHLO_API_KEY,
      "Idempotency-Key": `confirm-${intent.id}`,
    },
    body: JSON.stringify({ clientToken }),
  },
);
const confirmedIntent = await confirmation.json();

Handle these states explicitly:

requires_payment_method: ask for another method or show a validation error
requires_action: keep the customer in the secure flow
processing: show pending and wait for the verified event
succeeded: compare amount, currency, and order ID before fulfillment
cancelled: close the unpaid order and release reserved inventory

Capture an authorization

Set captureMethod: "manual" when you need to authorize now and capture later, such as after inventory or fraud review. Capture the full amount or a lower amount before the authorization expires.

curl -X POST \
  "https://merchant.zahlo.eu/api/v1/payment-intents/pi_demo_1001/capture" \
  -H "x-api-key: ${ZAHLO_API_KEY}" \
  -H "Idempotency-Key: capture-pi_demo_1001" \
  -H "Content-Type: application/json" \
  -d '{"amountMinor":4990}'

Capture once. If the request times out, retrieve the intent before retrying with the same idempotency key. A partial capture must agree with the order and inventory policy you stored before authorization.

Cancel or recover

Cancel an intent only when the order is abandoned, expired, or rejected before capture. If a create, confirm, or capture request returns a timeout, retrieve the intent by ID and reconcile its status. Never create a replacement intent because a response was lost. Fulfill only from a verified payment.confirmed event or an authoritative terminal retrieval. For delayed bank methods, keep the order pending and use the reconciliation guide when the browser and event timelines differ.

Start here

Core concepts

Accept payments

Sell online

Subscriptions

Integrations

Operations

Create the intent on your server

Confirm the payment

Capture an authorization

Cancel or recover

​Create the intent on your server

​Confirm the payment

​Capture an authorization

​Cancel or recover

Create the intent on your server

Confirm the payment

Capture an authorization

Cancel or recover