Endpoints

POST /api/v1/checkout/sessions

Hosted-checkout flow — devolvemos NUESTRO checkout URL y manejamos toda la UI por método.

Endpoint dedicado para el flujo hosted checkout: la respuesta es una checkout session con checkoutUrl (https://sandbox.key2pays.com/c/<sessionId>). Redirigís al cliente ahí y nosotros renderizamos la UI por método (QR para PIX, CLABE para SPEI, redirect a tarjetas, referencia de voucher para cash, etc.). Cuando termina, el cliente vuelve a returnUrl y el estado del pago llega por webhook. Nunca ves la URL del provider upstream — eso queda escondido, así si rotamos providers, tu integración no se entera.

¿Cuándo usar este endpoint? Cuando NO querés construir tu propio UI de checkout. Redirigís y listo — 1 línea de integración. Si en cambio querés construir tu propio UI y embeber el iframe del provider o redirigir directo al upstream, usá POST /api/v1/payments que devuelve el paymentFormUrl del provider.

Body (idéntico a POST /payments)

El body acepta los mismos campos que POST /api/v1/payments — amount, paymentMethodId,country, userEmail,merchantOrderId, returnUrl. No hace falta mandar hostedCheckout: true: este endpoint lo asume.

bash

curl https://sandbox.key2pays.com/api/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_51N8mP...exampleK3Y" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50,
    "paymentMethodId": "1001",
    "country": "MEX",
    "userEmail": "carlos@example.com",
    "merchantOrderId": "ORD-12345",
    "returnUrl": "https://your-store.com/orders/1234"
  }'

Respuesta

json

{
  "sessionId": "TXN-MP25SDIS-ZQ68",
  "checkoutUrl": "https://sandbox.key2pays.com/c/TXN-MP25SDIS-ZQ68?returnUrl=https%3A%2F%2Fyour-store.com%2Forders%2F1234",
  "paymentMethodId": "1001",
  "status": "pending",
  "amount": 50,
  "amountLocal": 882.17,
  "currencyLocal": "MXN",
  "fxRate": 17.64,
  "expiresAt": "2026-05-12T16:00:00.000Z"
}

Note: the session id is the same value as the underlying transaction id — surfaced under a name that fits the session abstraction. Sessions are single-use; once the link is consumed (or expires) the integrator should create a new one. The path legacy POST /api/v1/payments con hostedCheckout: true sigue funcionando exactamente igual — usá el endpoint que prefieras.

Previous · Endpoints

GET /me

Next · Endpoints

POST /api/v1/payments