Accept a payment - Zahlo Merchant Developer Docs

Start with Checkout Sessions unless you need to own the payment state machine. Use a Payment Intent when your application needs to collect payment details in a separate step, confirm a payment explicitly, or reuse the same intent while the customer completes additional action.

Create a payment intent

Create it on your server after resolving the cart and customer. The API key never crosses this boundary.

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

Return only the intent ID and the short-lived client token required by the browser. Use the SDK or the intent confirmation endpoint to complete customer action.

Confirm and handle action

An intent can require a payment method, customer action, processing time, or no further action. Render the appropriate state, then retrieve the intent or wait for the verified event. Never treat a redirect return as confirmation.

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 }),
  }
);

Use Fulfill orders safely for the confirmed-event boundary. Cancel an intent only when the order is genuinely abandoned or expired. The verified payment.confirmed webhook remains the fulfillment authority when the browser flow ends before the server receives confirmation.