Checkout Sessions - Z2Pay Developers

Una Checkout Session (cs_) es una instancia concreta de compra. A diferencia del Link (plantilla), tiene un monto congelado y un estado que avanza conforme el comprador interactúa. El id tiene 48 chars hex (192 bits de entropía), seguro para exponer en URL.

Los ejemplos utilizan el sandbox: API en https://checkout-api.sandbox.z2pay.com y página en https://pay.sandbox.z2pay.com. En producción, use https://checkout-api.z2pay.com y https://pay.z2pay.com. Las solicitudes del seller usan el header x-api-key — consulte Autenticación.

Endpoints

Método	Ruta	Descripción
`POST`	`/checkout/sessions`	Crea una Session (a partir de un Link o ad-hoc)
`GET`	`/checkout/sessions`	Lista Sessions (paginado)
`GET`	`/checkout/sessions/{id}`	Obtiene una Session por ID

Para crear Sessions ad-hoc con listado separado (venta directa), consulte también Charges — el atajo /checkout/charges.

Snapshot inmutable

Al crear una Session a partir de un Link, todos los datos (items, precio, splits, branding, métodos) se copian en la Session. Editar el Link después no afecta las Sessions ya creadas. Esto garantiza que lo que el comprador vio al momento del pago es exactamente lo que paga.

Crear Session

POST /checkout/sessions

Acepta dos formas, discriminadas por la presencia del campo linkId. Retorna 201. Soporta idempotencia mediante el header Idempotency-Key (consulte Convenciones).

Forma A — a partir de un Link

Materializa la Session copiando el snapshot del Link.

linkId

string

requerido

ID del CheckoutLink (chk_*). La presencia de este campo es lo que discrimina el body como “a partir de Link”.

customer

object

Precarga los datos del comprador. Consulte Customer.

metadata

object

Metadata específico de esta Session (sobreescribe el del Link).

curl -X POST https://checkout-api.sandbox.z2pay.com/checkout/sessions \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -d '{
    "linkId": "chk_abc123...",
    "customer": {
      "name": "João Silva",
      "email": "joao@example.com",
      "document": "12345678900",
      "documentType": "cpf"
    },
    "metadata": { "order_id": "ord_42", "shop": "loja-principal" }
  }'

Forma B — ad-hoc (sin Link)

Body completo con la configuración inline. Equivalente al body de crear Link, con pequeñas diferencias: sin name/slug, con customer (precarga el comprador) y con description (mostrada en la página).

curl -X POST https://checkout-api.sandbox.z2pay.com/checkout/sessions \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "payment",
    "currency": "BRL",
    "locale": "pt-BR",
    "items": [{ "name": "Pedido #1234", "quantity": 1, "unitAmount": 8500 }],
    "paymentMethods": {
      "card": { "enabled": true },
      "pix":  { "enabled": true }
    },
    "customer": { "email": "joao@example.com" },
    "successUrl": "https://meu-site.com/obrigado",
    "expirationMinutes": 30,
    "metadata": { "order_id": "ord_42" }
  }'

Los campos de configuración (items, paymentMethods, branding, splits, requiredFields, customFields, successUrl, cancelUrl, expirationMinutes) siguen exactamente el mismo schema del Checkout Link.

Respuesta (201):

{
  "id": "cs_a1b2c3d4...48hex",
  "tenantId": "ten_xyz...",
  "linkId": "chk_abc123...",
  "status": "created",
  "mode": "payment",
  "currency": "BRL",
  "locale": "pt-BR",
  "config": {
    "items": [{ "...": "..." }],
    "paymentMethods": { "...": "..." },
    "splits": null,
    "branding": { "...": "..." },
    "requiredFields": ["email", "document", "phone"],
    "customFields": [],
    "successUrl": "https://meu-site.com/obrigado",
    "cancelUrl": null
  },
  "customer": { "name": "João Silva", "email": "joao@example.com" },
  "subtotal": 8500,
  "discountTotal": 0,
  "amount": 8500,
  "discounts": null,
  "paymentAttempts": 0,
  "transactionId": null,
  "metadata": { "order_id": "ord_42" },
  "createdAt": "2026-06-24T12:00:00.000Z",
  "updatedAt": "2026-06-24T12:00:00.000Z",
  "openedAt": null,
  "paidAt": null,
  "canceledAt": null,
  "expiresAt": "2026-06-25T12:00:00.000Z",
  "deletedAt": null,
  "version": 0,
  "url": "https://pay.sandbox.z2pay.com/c/cs_a1b2c3d4..."
}

En Sessions ad-hoc, linkId es null. La url retornada ya está lista para entregar al comprador.

Errores comunes

HTTP	Code	Cuándo
`400`	`validation_failed`	Body inválido
`404`	`not_found`	`linkId` no existe o fue archivado
`409`	`link_not_active`	El Link existe pero está archivado

Consulte Errores para el formato completo.

Objeto Customer

name

string

Nombre completo (≤ 255 chars).

string

E-mail (≤ 255 chars). Siempre obligatorio en el confirm — consulte required fields.

document

string

CPF, CNPJ o pasaporte (6–30 chars; solo dígitos para CPF/CNPJ).

documentType

string

"cpf", "cnpj" o "passport".

phone

string

Teléfono (≤ 30 chars). Recomendado E.164: +5511999999999.

address

object

Dirección (zipCode, street, number, complement, neighborhood, city, state, country default "BR"). Opt-in: solo requerido si "address" está en requiredFields.

Listar Sessions

GET /checkout/sessions

Listado paginado de Sessions del tenant.

status

string

Filtra por status (CSV). Ej.: ?status=paid,opened. Valores: created, opened, paying, partially_paid, paid, failed, expired, canceled.

linkId

string

Filtra Sessions de un Link específico.

string

Búsqueda por ID de Session o nombre/email/documento del comprador.

page

number

predeterminado:"1"

Número de página (≥ 1).

limit

number

predeterminado:"20"

Elementos por página (1–100).

curl -G https://checkout-api.sandbox.z2pay.com/checkout/sessions \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -d status=paid \
  -d page=1 \
  -d limit=20

Respuesta (200): objeto paginado { data, total, page, limit }.

Obtener Session por ID

GET /checkout/sessions/{id}

Retorna la vista completa del seller (incluye tenantId, metadata, transactionId).

curl https://checkout-api.sandbox.z2pay.com/checkout/sessions/cs_a1b2c3d4... \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

Estados posibles: 200 (encontrada) · 404 (no encontrada).

Estados y transiciones

created → opened → paying → paid          (terminal ✓)
                         → failed → opened  (retry permitido)
                         → expired         (terminal)
                → expired                  (sin llegar a opened)
                → canceled                 (terminal)

opened  → expired                          (timeout sin confirmar)
        → canceled

Tabla de transiciones válidas

De	Para
`created`	`opened`, `expired`, `canceled`
`opened`	`paying`, `expired`, `canceled`
`paying`	`paid`, `partially_paid`, `failed`, `expired`
`partially_paid`	`paid`, `failed`
`failed`	`opened` (retry), `expired`, `canceled`
`paid`	— (terminal)
`expired`	— (terminal)
`canceled`	— (terminal)

Significado de cada estado

Estado	Significado
`created`	Session creada (vía API), el comprador aún no abrió la página
`opened`	El comprador abrió la página de pago
`paying`	El comprador hizo clic en “Pagar”; transacción siendo procesada por el gateway
`partially_paid`	Pago combinado: al menos un payment confirmó, pero el agregado aún no coincide con `session.amount` (ej: PIX pagado, tarjeta pendiente)
`paid`	Pago confirmado. Webhook `checkout.session.payment_succeeded` disparado
`failed`	Pago rechazado. La Session vuelve a `opened` automáticamente para permitir el reintento
`expired`	`expiresAt` alcanzado sin confirmación
`canceled`	Cancelación manual (vía `POST /charges/{id}/cancel` o panel)

partially_paid es exclusivo del flujo combinado. En pago single-method, la Session va directo de paying a paid o failed.

Toda Session tiene un campo version (entero) que se incrementa en cada transición (optimistic locking). Si dos threads intentan confirmar la misma Session, solo una gana; la otra recibe session_already_processing o invalid_status_transition. Normalmente no necesita preocuparse por esto.

Reconciliación

Toda Session tiene un transactionId (completado después de entrar en paying) que vincula la Session al registro de pago en la PSP. Use el transactionId para obtener detalles de procesamiento (gateway, NSU, autorización, etc.) en la API de transacciones, si necesita hacer conciliación financiera.

Véase también

Visión general del Checkout

Conceptos, casos de uso y mapa de endpoints.

Checkout Links

Plantillas reutilizables y schema completo de la configuración.

Charges (venta rápida)

Sessions ad-hoc con listado separado y cancelación.

Comprador (página pública)

Cómo la Session avanza de created a paid.

Webhooks

Eventos de cambio de estado de la Session.

Errores

Formato de errores y códigos de dominio del checkout.

​Endpoints

​Snapshot inmutable

​Crear Session

​Errores comunes

​Objeto Customer

​Listar Sessions

​Obtener Session por ID

​Estados y transiciones

​Tabla de transiciones válidas

​Significado de cada estado

​Reconciliación

​Véase también

Visión general del Checkout

Checkout Links

Charges (venta rápida)

Comprador (página pública)

Webhooks

Errores

Endpoints

Snapshot inmutable

Crear Session

Errores comunes

Objeto Customer

Listar Sessions

Obtener Session por ID

Estados y transiciones

Tabla de transiciones válidas

Significado de cada estado

Reconciliación

Véase también