← IntegracionesGuía para desarrolladores

Conecta tu POS con Recurrente usando Terminal Sessions y Webhooks

Envía cobros desde tu ERP, punto de venta o sistema interno a una terminal POS de Recurrente, y recibe el resultado automáticamente en tu backend.

Ver documentación Guía de webhooks

curl -X POST https://app.recurrente.com/api/terminal_session_commands \
  -H "X-SECRET-KEY: tu_llave_secreta" \
  -H "Content-Type: application/json" \
  -d '{
    "terminal_id": "trm_abc123",
    "amount_in_cents": 5000,
    "currency": "GTQ",
    "external_id": "orden-1234"
  }'

Guía

Automatiza cobros presenciales y conciliación

✓Inicializa cobros desde tu ERP, POS o sistema interno

✓Cada pago queda conectado con su orden usando external_id

✓Webhooks actualizan la venta sin conciliación manual

Ver documentación

Tu sistema

ERP, POS o backend

API→

←WEBHOOK

Cobro enviado

Q500

Pagar

Cómo funciona el flujo

Terminal Sessions controla el cobro en la terminal. Webhooks confirma el resultado en tu sistema para que puedas cerrar la orden, emitir recibos o actualizar inventario.

Prepara tu terminal

Ten una terminal POS vinculada a tu cuenta y colócala en modo espera para que pueda recibir cobros desde tu sistema.

Envía el cobro por API

Tu ERP, POS o backend crea un Terminal Session Command con terminal_id, monto, moneda y external_id.

La terminal cobra al cliente

La terminal levanta el comando automáticamente, muestra la pantalla de cobro y procesa el pago con tarjeta.

Recibe el resultado por webhook

Tu sistema escucha eventos como payment_intent.succeeded o payment_intent.failed para actualizar la orden.

Integración recomendada

Un cobro externo, una confirmación automática

Tu sistema mantiene la lógica de la orden. Recurrente procesa el pago en la terminal y te avisa por webhook cuando el intento de pago cambia de estado.

✓Usa llaves de API de Recurrente desde Configuración → Llaves API.

✓Guarda el terminal_id de cada terminal que quieras controlar desde tu sistema.

✓Envía un external_id único por orden para evitar cobros duplicados.

✓Registra un webhook endpoint HTTPS y valida las firmas de Svix en producción.

✓Trata los webhooks como idempotentes: pueden llegar más de una vez.

✓Para pruebas de punta a punta con webhooks, usa llaves live y un pago real pequeño; los checkouts test no disparan webhooks.

Evento de webhook esperado

{
  "event_type": "payment_intent.succeeded",
  "checkout": {
    "id": "ch_xyz789",
    "status": "paid"
  },
  "amount_in_cents": 5000,
  "currency": "GTQ",
  "payment_method": {
    "type": "card"
  }
}

También debes manejar eventos fallidos o duplicados según la guía de webhooks.

Referencias técnicas

Esta guía resume el flujo. Para parámetros, respuestas y cambios futuros, usa siempre la documentación oficial como fuente de verdad.