Saltar al contenido principal
El Checkout de Z2Pay es una página de pago hospedada (Z2Pay-hosted, al estilo Stripe Checkout / Mercado Pago Checkout Pro). Creas la configuración vía API — ítems, métodos aceptados, branding, splits — y recibes una URL lista para entregar al comprador. Él finaliza el pago en una página servida por Z2Pay (mobile-first, con tu identidad visual), y tú recibes webhooks a lo largo de todo el ciclo de vida.
Todos los ejemplos de esta sección usan las URLs de sandbox (https://checkout-api.sandbox.z2pay.com para la API y https://pay.sandbox.z2pay.com para la página). En producción, cambia a https://checkout-api.z2pay.com y https://pay.z2pay.com.

​
Lo que NO necesitas implementar

Página de pago (UI)

La interfaz de checkout es nuestra, responsiva y con tu marca.

Tokenización de tarjeta (PCI)

Los datos sensibles de la tarjeta nunca tocan tu servidor.

PIX, boleto y cuotas

Toda la lógica de método de pago es nuestra.

Enrutamiento entre adquirentes

Basta con registrar el gateway una vez en el panel.

​
Casos de uso típicos

  • Tienda online — crea una CheckoutSession por pedido y redirige al cliente.
  • Enlace de pago compartible (bio de Instagram, post, WhatsApp) — crea un CheckoutLink (template persistente) y comparte la URL. Cada clic genera una nueva CheckoutSession.
  • Cobro individual — llama a /checkout/charges (venta rápida ad-hoc) y envía la URL directamente por WhatsApp o correo electrónico.
  • Marketplace — usa splits para dividir el monto entre múltiples destinatarios automáticamente.

​
Conceptos centrales

Un intento concreto de compra. Tiene un monto congelado (snapshot del Link en el momento de la creación), un comprador (parcial o completo) y un estado que progresa: created → opened → paying → paid. Los IDs comienzan con cs_ (48 chars hex = 192 bits de entropía, seguro para exponer en URL).
Al crear una Session a partir de un Link, todos los datos (items, precio, splits, branding, métodos) se copian. Editar el Link después no afecta las Sessions ya creadas. Esto garantiza que lo que el comprador vio en el momento del pago es exactamente lo que paga.
No estás obligado a crear un Link antes — puedes crear una Session “ad-hoc” (sin linkId), con toda la configuración inline. Útil para cobros únicos/personalizados. Las Charges son un atajo para ese mismo flujo, con listado filtrado solo para Sessions sin linkId.
Toda credencial está vinculada a un tenant (tu cuenta de seller). Los listados se filtran automáticamente por tenant — nunca ves recursos de otro seller. Los IDs siguen el patrón con prefijo: chk_ (Link), cs_ (Session), ci_ (ítem), cmed_ (media), rec_ (recipient para splits).

​
Mapa de endpoints

Todas las solicitudes de seller usan el header x-api-key. Ver Autenticación.

​
Recursos del seller (autenticados)

MétodoRutaRecursoQué hace
POST/checkout/linksLinkCrea un template de cobro
GET/checkout/linksLinkLista templates (paginado)
GET/checkout/links/{id}LinkBusca un template por ID
PUT/checkout/links/{id}LinkActualiza un template
DELETE/checkout/links/{id}LinkArchiva (soft-delete) un template
POST/checkout/sessionsSessionCrea una Session (a partir de Link o ad-hoc)
GET/checkout/sessionsSessionLista Sessions (paginado)
GET/checkout/sessions/{id}SessionBusca una Session por ID
GET/checkout/chargesChargeLista ventas rápidas (Sessions ad-hoc)
POST/checkout/chargesChargeCrea una venta rápida ad-hoc
GET/checkout/charges/{id}ChargeBusca una venta rápida por ID
POST/checkout/charges/{id}/cancelChargeCancela una venta rápida

​
Endpoints públicos (consumidos por el navegador del comprador)

MétodoRutaQué hace
GET/public/checkout/{id}Obtiene la configuración pública para renderizar la página
POST/public/checkout/{id}/openedMarca la Session como “abierta por el comprador”
POST/public/checkout/{id}/confirmConfirma el pago (tokenId + datos del comprador)
Normalmente no llamas a los endpoints públicos — quien los llama es la página de pago de Z2Pay. Están documentados en Comprador (página pública) con fines de transparencia, o en caso de que quieras construir un checkout personalizado sobre nuestra API.

​
Quickstart

En 3 pasos, de cero al primer pago.
1

Crea un Checkout Link

curl -X POST https://checkout-api.sandbox.z2pay.com/checkout/links \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Curso de Backend",
    "items": [
      { "name": "Curso de Backend — vitalício", "quantity": 1, "unitAmount": 49900 }
    ],
    "paymentMethods": {
      "card":   { "enabled": true, "installments": { "maxInstallments": 12, "freeInstallments": 3 } },
      "pix":    { "enabled": true, "expiresIn": 3600 },
      "boleto": { "enabled": true, "dueDateDays": 3 }
    }
  }'
Respuesta (201):
{
  "id": "chk_abc123...",
  "status": "active",
  "url": "https://pay.sandbox.z2pay.com/c/chk_abc123...",
  "createdAt": "2026-06-24T12:00:00.000Z"
}
unitAmount es un entero en centavos: R$ 499,00 = 49900. Nunca envíes float (499.00) — es rechazado por la validación.
2

Comparte la URL

La url devuelta (https://pay.sandbox.z2pay.com/c/chk_abc123...) es el enlace de pago. Puede compartirse en cualquier canal. Cada vez que alguien abre el enlace, una nueva CheckoutSession se materializa automáticamente.
3

Recibe webhooks

Cada cambio relevante (Session creada, pago aprobado, etc.) dispara un webhook a la URL configurada en el panel. Ver Webhooks para el catálogo completo de eventos del checkout.

​
Estados de la Session (resumen)

created → opened → paying → paid          (terminal ✓)
                         → failed → opened  (retry permitido)
                         → expired         (terminal)
                → canceled                 (terminal)
Los detalles de la máquina de estados están en Checkout Sessions.

​
Ver también

Checkout Links

Crea y gestiona templates de cobro reutilizables.

Checkout Sessions

Instancias de compra, estados y snapshot inmutable.

Charges (venta rápida)

Cobro individual ad-hoc, sin Link.

Comprador (página pública)

Los endpoints que consume la página de pago.

Quickstart

Recibe un pago de prueba de extremo a extremo.

Tarjetas de prueba

Escenarios de aprobación y rechazo en el sandbox.