Sesiones de pago

Las sesiones de pago crean una URL de checkout hospedada por Quentli. Úsalas para cobrar un importe puntual, varios conceptos o facturas existentes desde tu integración.

Si el cobro representa un adeudo que debes programar y gestionar con recordatorios o reintentos automáticos, sigue Sincroniza facturas en Quentli.

Crea la sesión desde tu servidor. Nunca expongas tu API key de Quentli en el navegador o una aplicación móvil.

¿Cuándo usar una sesión de pago?

Para enviar un link de checkout de un cobro puntual.
Para cobrar varios conceptos en una misma sesión.
Para mostrar una sesión que paga facturas existentes.

Si solo necesitas guardar un método de pago sin cobrar ahora, usa una sesión de inscripción.

1. Crea una sesión de pago

Envía un cliente y elige exactamente una de estas tres formas de definir el cobro. No combines invoiceIds con importes o conceptos.

Importe puntual
Conceptos
Facturas existentes

Usa amount, currency y description para crear un cobro único con un solo concepto.

POST /v1/payment-sessions

{
  "input": {
    "amount": 150000,
    "currency": "MXN",
    "description": "Colegiatura Enero 2026",
    "customer": {
      "name": "Ana Rodríguez",
      "externalId": "cliente-123",
      "email": "ana@example.com",
      "phoneNumber": "+525512345678"
    },
    "displayMode": "CUSTOMER_PORTAL",
    "returnUrl": "https://miapp.com/pago-exitoso",
    "cancelUrl": "https://miapp.com/pago-cancelado",
    "meta": {
      "externalSessionId": "checkout-2026-001"
    }
  }
}

Usa items para cobrar varios conceptos. El total se calcula sumando amount * quantity de cada elemento.

POST /v1/payment-sessions

{
  "input": {
    "items": [
      {
        "description": "Colegiatura Enero 2026",
        "amount": 150000,
        "quantity": 1,
        "currency": "MXN"
      },
      {
        "description": "Inscripción",
        "amount": 50000,
        "quantity": 1,
        "currency": "MXN"
      }
    ],
    "customer": {
      "name": "Ana Rodríguez",
      "externalId": "cliente-123",
      "email": "ana@example.com",
      "phoneNumber": "+525512345678"
    },
    "displayMode": "CUSTOMER_PORTAL",
    "returnUrl": "https://miapp.com/pago-exitoso",
    "cancelUrl": "https://miapp.com/pago-cancelado"
  }
}

Usa invoiceIds para cobrar el saldo pendiente de una o más facturas del cliente.

POST /v1/payment-sessions

{
  "input": {
    "invoiceIds": [
      "inv_1234567890abcdefghij",
      "inv_abcdefghij1234567890"
    ],
    "customer": {
      "name": "Ana Rodríguez",
      "externalId": "cliente-123",
      "email": "ana@example.com",
      "phoneNumber": "+525512345678"
    },
    "displayMode": "CUSTOMER_PORTAL",
    "returnUrl": "https://miapp.com/pago-exitoso",
    "cancelUrl": "https://miapp.com/pago-cancelado"
  }
}

Los importes se expresan en centavos. Todos los elementos de items y todas las facturas de una sesión deben usar la misma moneda. La sesión toma el saldo pendiente actual de las facturas al crearla.

Ejemplo desde el servidor

const response = await fetch('https://api.quentli.com/v1/payment-sessions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.QUENTLI_API_KEY}`,
  },
  body: JSON.stringify({ input }),
});

if (!response.ok) throw new Error('No se pudo crear la sesión de pago');

const { url, session, paymentSession } = await response.json();

2. Muestra el checkout al cliente

La respuesta incluye la url del checkout, el objeto paymentSession y las credenciales temporales session. Estas credenciales se usan con @quentli/js para mostrar el checkout dentro de tu aplicación.

Respuesta

{
  "url": "https://portal.quentli.com/acme/s/ps_1234567890",
  "session": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "csrfToken": "abc123def456",
    "expiresAt": "2026-01-15T22:00:00.000Z"
  },
  "paymentSession": {
    "id": "ps_1234567890",
    "status": "PENDING",
    "expiresAt": null
  }
}

Opción 1: Customer Portal

Con CUSTOMER_PORTAL, el modo predeterminado, redirige al cliente a la URL hospedada por Quentli:

window.location.assign(url);

También puedes usar el SDK para la redirección:

import { Quentli } from '@quentli/js';

const quentli = new Quentli();
quentli.paymentSessions.displayPage({ url });

Usa displayMode: "EMBEDDED" al crear la sesión y abre el checkout en un popup. El cliente permanece en tu aplicación y recibes callbacks al completar, cancelar o fallar el flujo.

npm install @quentli/js

pnpm add @quentli/js

bun add @quentli/js

<script type="module">
  import { Quentli } from 'https://cdn.jsdelivr.net/npm/@quentli/js@1.1.1/dist/index.js';

  const quentli = new Quentli();
  // Usa quentli.paymentSessions con la URL y sesión creadas por tu backend.
</script>

import { Quentli } from '@quentli/js';

const quentli = new Quentli();

await quentli.paymentSessions.displayPopup({
  url,
  session: {
    accessToken: session.accessToken,
    csrfToken: session.csrfToken,
  },
  onComplete: data => {
    console.log('Pago completado:', data.paymentSessionId);
    // Actualiza la interfaz. Confirma el pago con el webhook en tu servidor.
  },
  onCancel: () => {
    console.log('El cliente canceló el checkout');
  },
  onError: error => {
    console.error('No se pudo mostrar el checkout:', error);
  },
  width: 500,
  height: 700,
});

Opción 3: Iframe con `@quentli/js`

Usa displayMode: "CUSTOM" para incrustar el checkout en un contenedor de tu página:

<div id="payment-container"></div>

import { Quentli } from '@quentli/js';

const container = document.getElementById('payment-container');
if (!container) throw new Error('No se encontró el contenedor del checkout');

const quentli = new Quentli();

await quentli.paymentSessions.displayEmbedded({
  url,
  session: {
    accessToken: session.accessToken,
    csrfToken: session.csrfToken,
  },
  target: container,
  onComplete: data => {
    console.log('Pago completado:', data.paymentSessionId);
  },
  onCancel: () => {
    console.log('El cliente canceló el checkout');
  },
  onError: error => {
    console.error('No se pudo mostrar el checkout:', error);
  },
  width: '100%',
  height: '600px',
});

Para los modos popup e iframe, entrega url y session desde tu backend a tu frontend. No guardes las credenciales de session; son temporales. Llama a quentli.destroy() cuando desmontes el componente o termines de usar la instancia.

Modo	`displayMode`	Experiencia	Callbacks	Requiere SDK
Customer Portal	`CUSTOMER_PORTAL`	Redirección a Quentli	No	No
Popup	`EMBEDDED`	Abre una ventana popup	Sí	Sí
Iframe	`CUSTOM`	Integrado en tu página	Sí	Sí

Para CUSTOMER_PORTAL, normalmente solo necesitas url. Para popup e iframe, session contiene los tokens que requiere el SDK.

3. Confirma el resultado

No marques el cobro como pagado solo porque el cliente llegue a returnUrl o se invoque onComplete. Procesa el webhook PAYMENT_COMPLETED y conserva su eventId de forma idempotente. También puedes consultar la sesión sin API key; el endpoint devuelve null cuando no existe:

GET /v1/payment-sessions/{id}

Una sesión puede estar PENDING, FINALIZED, CANCELED o EXPIRED.

Resolución del cliente

Quentli busca o crea el cliente usando estos campos, en este orden:

externalId: identificador único de tu sistema, guardado como username en Quentli.
phoneNumber: teléfono en formato E.164.
email: correo electrónico del cliente.

Si no existe ningún cliente con esos datos, Quentli crea uno nuevo. externalId tiene prioridad cuando encuentra un cliente. Usa meta para guardar identificadores externos tanto en el cliente como en la sesión. No envíes meta y el campo deprecado metadata en la misma solicitud.

Usa `forceUpdate` con cuidado

Usa forceUpdate: true solo cuando tu sistema sea la fuente de verdad de los datos de contacto. Si otro cliente de la misma organización tiene el email o phoneNumber enviado, Quentli mueve ese dato al cliente resuelto. Sin forceUpdate, Quentli no mueve correos ni teléfonos entre clientes y la solicitud falla ante una coincidencia que podría sobrescribir datos por accidente.

forceUpdate puede mover un correo o teléfono de un cliente a otro dentro de la misma organización.

Conceptos

Guías

Endpoints

Schemas

¿Cuándo usar una sesión de pago?

1. Crea una sesión de pago

Ejemplo desde el servidor

2. Muestra el checkout al cliente

Opción 1: Customer Portal

Opción 3: Iframe con `@quentli/js`

3. Confirma el resultado

Resolución del cliente

Usa `forceUpdate` con cuidado

​¿Cuándo usar una sesión de pago?

​1. Crea una sesión de pago

​Ejemplo desde el servidor

​2. Muestra el checkout al cliente

​Opción 1: Customer Portal

​Opción 2: Popup con @quentli/js

​Opción 3: Iframe con @quentli/js

​3. Confirma el resultado

​Resolución del cliente

​Usa forceUpdate con cuidado

¿Cuándo usar una sesión de pago?

1. Crea una sesión de pago

Ejemplo desde el servidor

2. Muestra el checkout al cliente

Opción 1: Customer Portal

Opción 2: Popup con `@quentli/js`

Opción 3: Iframe con `@quentli/js`

3. Confirma el resultado

Resolución del cliente

Usa `forceUpdate` con cuidado