For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Guías (Español)Guides (English)Referencia API
  • Referencia API
      • POSTCrear un comando de terminal
LogoLogo
Referencia APITerminal Session Commands

Crear un comando de terminal

POST
https://app.recurrente.com/api/terminal_session_commands
POST
/api/terminal_session_commands
$curl -X POST https://app.recurrente.com/api/terminal_session_commands \
>     -H "X-SECRET-KEY: <apiKey>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "terminal_id": "trm_abc123",
>  "currency": "GTQ",
>  "external_id": "order-1234",
>  "amount_in_cents": 5000
>}'
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}
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`.
Was this page helpful?

Prueba tus credenciales de autenticación

Next
Built with

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

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:

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:
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