Developer guide

Credit card

Mexico México card paymentData paymentFormUrl

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.

Create with the selected method

Select paymentMethodId from your shop's catalogue. Submit the real buyer details required by that route. Use your shop's permitted input currency and display the returned local amount and currency without recalculating them.

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.

What to display in your checkout

Use the non-empty paymentFormUrl returned by POST /payments for the existing direct contract to open the bank/processor page. The buyer completes card entry and any 3DS there. Never construct the URL from an ID. A missing URL or pending recovery requires checking the same payment, not creating another one. If you opted into the consent version, open checkoutUrl first.

Use channel CREDIT_CARD to discover card methods. Do not send PAN, expiry or CVV to our API. Do not embed the processor page unless that particular integration supports it.

Buyer prefill, card flow and decline handling →

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 →