Key2Pay - Payment Gateway Processor

Direct integration · bank link

The same payment API supports card routes enabled for your shop in each country. For the existing direct contract (Key2Pay-Version: 2026-05-01, also the default), send hostedCheckout: false and the card paymentMethodId. HTTP 200 returns transactionId and paymentFormUrl: the actual bank/processor URL when generation succeeds. Open that returned URL for card entry and 3DS. Do not send card details to our API. Keep the method's country, accepted currency and buyer requirements from GET /payment-methods.

Compare all three checkout experiences →

Supported card flow

Your backend creates and retrieves the payment through Key2Pay. For Club Pago, the buyer enters card details and completes 3DS on the processor's hosted page. This is server-to-server payment creation with hosted card capture; the public API does not accept PAN, expiry or CVV for a direct card charge.

Use secret keys only on your backend. Never include card details in user fields, metadata, tags, URLs or logs. A generated payment link is not a confirmed charge.

Discover available cards

bash

curl 'https://sandbox.key2pay.ai/api/v1/payment-methods?country=MX&channel=CREDIT_CARD' \
  -H "Authorization: Bearer $KEY2PAY_SECRET"

Choose methods[].paymentMethodId from the response for your shop, country and environment. Check currencies, currencyLimits and buyer requirements before creating the payment. An empty list means no card route is available for that shop; do not substitute a method id from another shop. Availability in this catalogue does not guarantee acceptance of every brand or issuing country.

Create a card payment

The following backend example requests a USD 10 payment for a USD-balance shop and explicitly selects the consent contract. Local Currency shops in Mexico must instead send the intended MXN amount with currency: MXN; USD input is rejected with unsupported_currency. Replace CARD_METHOD_ID with the paymentMethodId discovered above. Use a unique merchantOrderId and a stable Idempotency-Key for the same payment attempt.

javascript

const response = await fetch("https://sandbox.key2pay.ai/api/v1/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KEY2PAY_SECRET}`,
    "Content-Type": "application/json",
    "Key2Pay-Version": "2026-10-12",
    "Idempotency-Key": "card-order-1001-attempt-1",
  },
  body: JSON.stringify({
    amount: 10,
    currency: "USD",
    country: "MX",
    paymentMethodId: "CARD_METHOD_ID",
    merchantOrderId: "card-order-1001",
    userName: "Ana Torres",
    userEmail: "buyer@example.com",
    userPhone: "+525512345678",
  }),
});
const result = await response.json();
if (!response.ok) {
  // Handle the documented error; do not create a new payment automatically.
  throw new Error("Payment creation requires review");
}
// Send result.checkoutUrl to the buyer. Keep the secret key on this server.

With Key2Pay-Version: 2026-10-12, creation returns HTTP 201, status awaiting_consent, a sessionId, transactionId: null and checkoutUrl. Redirect the buyer to checkoutUrl to review the local amount and accept. Only after acceptance is the provider payment created. The Club Pago card route presents MXN; USD 10 is converted using the quoted FX, not charged as MXN 10.

Consent, version compatibility and post-acceptance retrieval

Buyer details and prefill

Send userName, userEmail and userPhone as top-level fields. Key2Pay uses these buyer details in its checkout. The Club Pago adapter forwards userName as CustomerName and userEmail as CustomerEmail when supplied. Its documented generator contract has no phone field, so userPhone is not currently forwarded to Club Pago. The processor may still ask for contact details or the cardholder name; sending customer details does not guarantee that its card form is prefilled.

Confirmation and declines

After acceptance, retrieve the transaction using GET /payments/{id} and reconcile it with your merchantOrderId. Process signed Key2Pay webhooks idempotently using the webhook contract. A browser redirect, successful link generation or HTTP 200 from a provider lookup is not evidence that funds were received. A decline displayed by the processor may remain pending in Key2Pay until authoritative reconciliation; do not mark it paid or automatically create a replacement charge.

Webhook signature and event contract

The Aurora Mexico Club Pago affiliation accepts only cards issued in Mexico. International cards are not supported. Club Pago notifies successful payments only and does not supply issuer decline codes or 3DS results. Its courtesy reference-status lookup is not a supported decline-diagnostics API. Keep transactionId, merchantOrderId, reference/Folio, amount, time and the displayed message for support; never send card numbers, CVV or 3DS codes. No notification does not prove a decline or the absence of a hold.

Iframe and direct card capture

The Aurora Mexico route can use the dedicated Getnet checkout template when enabled by the operator. It loads the provider's original form in an isolated iframe after buyer acceptance, with a link to open the same payment in another tab if bank verification requires it. Key2Pay does not read or change the bank form. An iframe load or browser message never confirms payment. Direct API clients still receive the original paymentFormUrl; the request and response contract is unchanged. Mobile layout and initial framing have been checked; a real Mexican-card payment and 3DS acceptance remain required before claiming end-to-end validation.