Developer guide

SPEI

Mexico México spei 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

Display paymentData.clabe, the returned bank/beneficiary and reference or transfer concept, amountLocal and currencyLocal. Keep account and reference values as strings with their leading zeros. Provide a copy action for each value. Do not replace the transfer reference with merchantOrderId.

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 →