Developer guide

Checkout with method selector

Omit paymentMethodId. Our checkout lists the methods enabled for your shop and country, grouped by their payment channel, including Credit card.

javascript

// Backend only. Example amounts: use your shop's permitted input currency.
const response = await fetch("https://sandbox.key2pay.ai/api/v1/checkout/sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAYMENT_SECRET}`,
    "Content-Type": "application/json",
    "Key2Pay-Version": "2026-05-01",
    "Idempotency-Key": "your-order-attempt-1"
  },
  body: JSON.stringify({
  "amount": 500,
  "currency": "MXN",
  "country": "MX",
  "merchantOrderId": "your-unique-order-id",
  "customer": {
    "firstName": "Buyer",
    "lastName": "Fullname",
    "email": "buyer@example.com"
  }
})
});
const result = await response.json();
if (!response.ok) throw new Error("Review the API error before retrying");
// Send result.checkoutUrl to the buyer. Do not construct the URL yourself.

Redirect to the checkoutUrl returned by the API. Keep sessionId until a transaction is created; use completedTxId from the session to retrieve that payment. The buyer enters card details only on the supported processor page.

Full checkout endpoint reference →

Confirm the payment

Keep transactionId as the platform identifier and merchantOrderId as your order identifier. Query GET /payments/{transactionId} or handle signed POST webhooks idempotently. Creating instructions, opening a bank link or returning to your site does not confirm a payment. Keep the same Idempotency-Key and request body if an attempt needs recovery.

Webhook contract and signatures →