Saltar al contenido principal
Las Charges son un atajo para crear Sessions ad-hoc (sin Link). Úsalas cuando tu caso es un cobro individual — un pedido específico, una factura puntual — y no un link difundido de forma masiva. Técnicamente, /checkout/charges crea las mismas Checkout Sessions que /checkout/sessions ad-hoc, pero el listado está filtrado para mostrar únicamente Sessions sin linkId — dejando el dashboard más limpio para los flujos de venta directa. Además, ofrece un endpoint de cancelación.
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, usa https://checkout-api.z2pay.com y https://pay.z2pay.com. Las solicitudes usan el header x-api-key — consulta Autenticación.

​
Endpoints

MétodoRutaDescripción
GET/checkout/chargesLista ventas rápidas (Sessions ad-hoc)
POST/checkout/chargesCrea una venta rápida ad-hoc
GET/checkout/charges/{id}Obtiene una venta rápida por ID
POST/checkout/charges/{id}/cancelCancela una venta rápida

​
Crear charge

POST /checkout/charges
Crea una Session ad-hoc con configuración inline. El body es idéntico al de POST /checkout/sessions en forma ad-hoc — mismo schema de items, paymentMethods, branding, splits, customer, etc. Retorna 201 con la Session creada y la url lista para enviar. Admite idempotencia mediante el header Idempotency-Key. 
curl -X POST https://checkout-api.sandbox.z2pay.com/checkout/charges \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -d '{
    "items": [{ "name": "Consultoria 1h", "quantity": 1, "unitAmount": 30000 }],
    "paymentMethods": { "pix": { "enabled": true } },
    "customer": { "name": "Cliente X", "email": "x@example.com" }
  }'
La respuesta es una CheckoutSession (con linkId: null) y la url para compartir a través de tu canal.

​
Listar charges

GET /checkout/charges
Listado paginado de Sessions ad-hoc (sin linkId) del tenant.
​
status
string
Filtra por estado (CSV). Valores: created, opened, paying, partially_paid, paid, failed, expired, canceled.
​
search
string
Busca por ID de Session o datos del comprador (nombre, correo electrónico, documento).
​
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/charges \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -d status=paid \
  -d page=1 \
  -d limit=20

​
Obtener charge por ID

GET /checkout/charges/{id}
Idéntico a GET /checkout/sessions/{id} — retorna la vista completa de la Session ad-hoc. 
curl https://checkout-api.sandbox.z2pay.com/checkout/charges/cs_a1b2c3d4... \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Estados posibles: 200 (encontrada) · 404 (no encontrada).

​
Cancelar charge

POST /checkout/charges/{id}/cancel
Mueve la Session al estado canceled. Solo permitido si el estado actual es created, opened o failed. Retorna 200. Admite idempotencia. 
curl -X POST https://checkout-api.sandbox.z2pay.com/checkout/charges/cs_a1b2c3d4.../cancel \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Estados posibles: 200 (cancelada) · 404 (no encontrada) · 409 (session_not_cancellable — el estado actual no permite la cancelación, ej. paid).
No es posible cancelar una Session ya pagada (paid) o en procesamiento (paying). El intento retorna 409 session_not_cancellable. Consulta Errores.

​
Ejemplo: cobro individual recurrente

Caso de uso habitual: enviar una factura mensual por boleto, con datos del comprador pre-rellenados y una vigencia prolongada. 
{
  "mode": "payment",
  "currency": "BRL",
  "locale": "pt-BR",
  "items": [{ "name": "Cobrança fatura jan/2026", "quantity": 1, "unitAmount": 25000 }],
  "paymentMethods": { "boleto": { "enabled": true, "dueDateDays": 7 } },
  "customer": {
    "name": "João Silva",
    "email": "joao@example.com",
    "document": "12345678900",
    "documentType": "cpf"
  },
  "metadata": { "invoice_id": "inv_2026_01_joao" },
  "expirationMinutes": 10080
}
Los datos del comprador ya vienen pre-rellenados (no los vuelve a ingresar) y la Session expira en 7 días (10080 min). Envía la url retornada a través de tu canal (correo electrónico, WhatsApp).
Para cobros recurrentes de verdad (planes, renovación automática, facturas generadas por el sistema), consulta Suscripciones — las Charges son para cobros puntuales armados por ti.

​
Ver también

Checkout Sessions

El recurso detrás de las Charges: estados, schema y listado.

Checkout Links

Para difusión masiva, prefiere un Link.

Comprador (página pública)

Lo que ocurre cuando el comprador abre la url.

Errores

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