Developer guide

Checkout for one method

Send the selected paymentMethodId to open our checkout for that method. The buyer sees the local amount, supplies only missing details and accepts before payment instructions are generated.

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",
  "paymentMethodId": "PAYMENT_METHOD_ID_FROM_YOUR_CATALOGUE",
  "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 →