Saltar al contenido principal
Vamos a procesar un pago de prueba de extremo a extremo usando el Checkout hospedado — la forma más rápida, sin necesidad de manejar datos de tarjeta. Todo ocurre en el sandbox, por lo que no se mueve dinero real.
¿Prefieres la integración transparente (enviar el pago directamente por la API)? Consulta Transactions después de completar esta guía.

​
Requisitos previos

  • Una cuenta en Z2Pay y acceso al entorno de pruebas (sandbox). Consulta Entornos.
  • Tu API key de sandbox (z2_chk_sk_... o z2_psp_sk_...). Consulta Autenticación.
1

Crea un enlace de checkout

Un Checkout Link es una plantilla de cobro reutilizable. Cada vez que alguien abre la URL, se crea una nueva compra (Session).
curl -X POST https://checkout-api.sandbox.z2pay.com/checkout/links \
  -H "x-api-key: z2_chk_sk_suachavedesandbox" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meu primeiro produto",
    "items": [
      { "name": "Plano Pro", "quantity": 1, "unitAmount": 4990 }
    ],
    "paymentMethods": {
      "card":   { "enabled": true, "installments": { "maxInstallments": 12 } },
      "pix":    { "enabled": true },
      "boleto": { "enabled": true }
    }
  }'
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$ 49,90 = 4990. Nunca envíes un valor float (49.90) — será rechazado por la validación.
2

Abre la URL y paga con una tarjeta de prueba

Abre la url devuelta en el navegador. Verás la página de pago hospedada de Z2Pay.Usa el generador a continuación para crear un número de tarjeta válido que será aprobado:→ Generar tarjeta de pruebaCompleta los campos:
  • Número: la tarjeta generada (escenario “Aprobado”).
  • Vencimiento: cualquier fecha futura, ej. 12/30.
  • CVV: cualquier valor, ej. 123.
  • Nombre/datos del comprador: cualquier valor válido.
Para probar un rechazo, genera una tarjeta con el escenario “Tarjeta rechazada”.
3

Confirma el pago

Tras el pago, consulta la transacción por la API. El referenceCode/id aparece en los webhooks y en la respuesta del checkout.
curl https://api.sandbox.z2pay.com/transactions/txn_abc123 \
  -H "x-api-key: z2_psp_sk_suachavedesandbox"
Respuesta (200):
{
  "id": "txn_abc123",
  "status": "paid",
  "amount": 4990,
  "currency": "BRL",
  "paidAt": "2026-06-24T12:01:30.000Z"
}
status: "paid" — pago aprobado en el sandbox. 🎉
4

(Recomendado) Recibe webhooks

En producción no consultas el estado continuamente — recibes una notificación ante cada cambio. Registra un webhook y escucha eventos como transaction.paid:
curl -X POST https://api.sandbox.z2pay.com/webhooks \
  -H "x-api-key: z2_psp_sk_suachavedesandbox" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meu endpoint",
    "url": "https://meusite.com/webhooks/z2pay",
    "events": ["transaction.paid", "transaction.refused"]
  }'
Consulta Webhooks para el catálogo de eventos y cómo validar la firma.

​
Próximos pasos

Tarjetas y escenarios de prueba

Todas las tarjetas que se aprueban y las que fallan, con generador incluido.

API directa (Transactions)

Crea y procesa pagos sin el checkout hospedado.

Suscripciones

Cobros recurrentes, planes y facturas.

Split de pagos

Divide el importe entre varios destinatarios.