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.

Meses sin intereses (installments)

Si quieres que el cobro se procese en cuotas, envía installments con el número de meses. Solo aplica a cobros en GTQ y los valores permitidos son 3, 6, 12 o 18 (algunas cuentas tienen configuraciones distintas). Si la tarjeta del cliente no soporta la opción elegida, el cobro se rechaza con unsupported_installments.

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. ### Meses sin intereses (installments) Si quieres que el cobro se procese en cuotas, envía `installments` con el número de meses. Solo aplica a cobros en `GTQ` y los valores permitidos son `3`, `6`, `12` o `18` (algunas cuentas tienen configuraciones distintas). Si la tarjeta del cliente no soporta la opción elegida, el cobro se rechaza con `unsupported_installments`.

Authentication

X-SECRET-KEYstring

Tu clave 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.

installmentsenumOptional

Número de meses sin intereses. Solo válido con currency: GTQ. Valores permitidos por defecto [3, 6, 12, 18] (puede variar por cuenta).

Allowed values:

account_idstringOptional

(Opcional) ID de la cuenta conectada (hijo) que será el comercio de registro del cobro (modelo directo: emite su propia factura fiscal). No disponible con terminales Celular como POS, donde el comercio de registro debe ser la cuenta dueña de la terminal.

transfer_setupslist of objectsOptional

(Opcional) Transferencias a ejecutar tras un cobro exitoso. Úsalo para enrutar fondos a una cuenta conectada (modelo destino) o para cobrar una comisión a una subcuenta. El destinatario debe ser tu cuenta o una cuenta conectada.

Response

Comando creado exitosamente

idinteger

ID interno del comando

external_idstring

ID único de tu sistema

statusenum

Estado del comando

terminal_idstring

ID de la terminal POS

amount_in_centsinteger

Monto en centavos

currencyenum

Moneda del cobro

installmentsinteger or null

Meses sin intereses solicitados, o null si el cobro va sin cuotas

checkout_idstring

ID del checkout generado

checkout_urlstringformat: "uri"

URL del checkout (la terminal usa esta URL internamente)

Errors

422

Unprocessable Entity Error