Crear un comando de terminal | Documentación API de Recurrente

Envía un comando de cobro a una terminal POS. Recurrente crea un checkout y lo despacha a la terminal indicada. Si ya existe un comando activo con el mismo external_id, retorna el comando existente en vez de crear uno nuevo (idempotencia).

Cuando la terminal recibe el comando, muestra automáticamente la pantalla de cobro para que el cliente pague con tarjeta.

Flujo

Tu sistema envía POST /api/terminal_session_commands con el monto, moneda y terminal.
Recurrente crea un checkout y un comando en estado pending.
La terminal levanta el comando y lo pasa a dispatched.
El cliente paga en la terminal.
Recibes un webhook payment_intent.succeeded con el resultado.

Idempotencia

Si envías dos requests con el mismo external_id, el segundo retorna el comando original sin crear uno duplicado. Esto te permite reintentar de forma segura.

Superseding

Si envías un nuevo comando a la misma terminal (con un external_id diferente), los comandos anteriores pendientes se marcan como superseded y la terminal solo procesa el más reciente.

Envía un comando de cobro a una terminal POS. Recurrente crea un checkout y lo despacha a la terminal indicada. Si ya existe un comando activo con el mismo `external_id`, retorna el comando existente en vez de crear uno nuevo (idempotencia). Cuando la terminal recibe el comando, muestra automáticamente la pantalla de cobro para que el cliente pague con tarjeta. ### Flujo 1. Tu sistema envía `POST /api/terminal_session_commands` con el monto, moneda y terminal. 2. Recurrente crea un checkout y un comando en estado `pending`. 3. La terminal levanta el comando y lo pasa a `dispatched`. 4. El cliente paga en la terminal. 5. Recibes un webhook `payment_intent.succeeded` con el resultado. ### Idempotencia Si envías dos requests con el mismo `external_id`, el segundo retorna el comando original sin crear uno duplicado. Esto te permite reintentar de forma segura. ### Superseding Si envías un nuevo comando a la misma terminal (con un `external_id` diferente), los comandos anteriores pendientes se marcan como `superseded` y la terminal solo procesa el más reciente.

Authentication

X-PUBLIC-KEYstring

Tu llave pública de API

X-SECRET-KEYstring

Tu llave secreta de API

Request

This endpoint expects an object.

terminal_idstringRequired

ID de la terminal POS donde se enviará el cobro

currencyenumRequired

Moneda del cobro

Allowed values:

external_idstringRequired

ID único de tu sistema para este cobro. Se usa para idempotencia — si envías el mismo external_id dos veces, no se crea un duplicado.

amount_in_centsintegerOptional

Monto a cobrar en centavos. Envía amount_in_cents o amount, no ambos.

amountdoubleOptional

Monto a cobrar en unidades (ej. 50.00). Alternativa a amount_in_cents.

Response

Comando creado exitosamente

idinteger

ID interno del comando

external_idstring

ID único de tu sistema

statusenum

Estado del comando

Allowed values:

terminal_idstring

ID de la terminal POS

amount_in_centsinteger

Monto en centavos

currencyenum

Moneda del cobro

Allowed values:

checkout_idstring

ID del checkout generado

checkout_urlstringformat: "uri"

URL del checkout (la terminal usa esta URL internamente)

Errors

422

Unprocessable Entity Error

Cuando la terminal recibe el comando, muestra automáticamente la pantalla de cobro para que el cliente pague con tarjeta.

Flujo

Tu sistema envía POST /api/terminal_session_commands con el monto, moneda y terminal.
Recurrente crea un checkout y un comando en estado pending.
La terminal levanta el comando y lo pasa a dispatched.
El cliente paga en la terminal.
Recibes un webhook payment_intent.succeeded con el resultado.

Idempotencia

Si envías dos requests con el mismo external_id, el segundo retorna el comando original sin crear uno duplicado. Esto te permite reintentar de forma segura.

Superseding

Si envías un nuevo comando a la misma terminal (con un external_id diferente), los comandos anteriores pendientes se marcan como superseded y la terminal solo procesa el más reciente.

1	curl -X POST https://app.recurrente.com/api/terminal_session_commands \
2	-H "X-PUBLIC-KEY: <apiKey>" \
3	-H "Content-Type: application/json" \
4	-d '{
5	"terminal_id": "trm_abc123",
6	"currency": "GTQ",
7	"external_id": "order-1234",
8	"amount_in_cents": 5000
9	}'

1	{
2	"id": 42,
3	"external_id": "order-1234",
4	"status": "pending",
5	"terminal_id": "trm_abc123",
6	"amount_in_cents": 5000,
7	"currency": "GTQ",
8	"checkout_id": "ch_xyz789",
9	"checkout_url": "https://app.recurrente.com/checkout-session/ch_xyz789"
10	}