Developer guide

Overview and response contract

Create the payment on your backend and display its result in your own checkout. Browse the country and method below for required buyer fields and the payment artifact to display.

These guides use the existing API. Direct integration keeps Key2Pay-Version: 2026-05-01 (also the default when omitted): HTTP 200, transactionId and payment instructions or paymentFormUrl. Opting into 2026-10-12 returns HTTP 201 awaiting_consent and checkoutUrl first. Hosted checkouts always collect buyer acceptance. Keep your current version and handle its response; a retry keeps the original contract.

javascript

// Backend only. Example amounts: use your shop's permitted input currency.
const response = await fetch("https://sandbox.key2pay.ai/api/v1/payments", {
  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",
  "hostedCheckout": false,
  "userName": "Buyer Fullname",
  "userEmail": "buyer@example.com",
  "userPhone": "+525512345678",
  "documentId": "BUYER_DOCUMENT"
})
});
const result = await response.json();
if (!response.ok) throw new Error("Review the API error before retrying");
// Keep transactionId; render returned paymentData or open paymentFormUrl.

🇲🇽SPEI 🇲🇽OXXO 🇲🇽Credit card 🇺🇾RedPagos 🇺🇾Bank transfer

Discover enabled methods using GET /payment-methods for your shop and country. Choose its paymentMethodId, requiredFields, currencies and currencyLimits. Availability depends on the account configuration; a documentation entry does not activate a route.

Cards across supported countries

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 →