Skip to navigation

Cancelar un comando de terminal

Solicita la cancelación de forma idempotente. Un comando pending pasa directamente a canceled y responde 200. Si la terminal ya lo tomó, responde 202 con cancel_requested; la terminal detiene la lectura y confirma canceled cuando el dispositivo reporta la cancelación.

Durante una autorización no se confirma la cancelación: el comando permanece en cancel_requested hasta resolver como canceled, consumed o failed. Consulta el comando hasta que final sea true. Esta separación evita declarar cancelado un pago que ya pudo llegar al procesador.

Authentication

X-SECRET-KEYstring

Tu clave secreta de API.

Una llave de cuenta (sk_live_..., sk_test_...) opera sobre su propia cuenta y, con X-ACCOUNT-ID, sobre sus cuentas conectadas.

La llave también fija el ambiente: una sk_test_ solo lista y resuelve objetos de prueba (live_mode: false) y una sk_live_ solo objetos reales. Un ID del otro ambiente responde 404 (401 en /customers).

Una llave de organización (sk_org_live_..., sk_org_test_...) alcanza todas las cuentas de una organización y solo sirve para leer: saldos, movimientos y reportes. Para operar sobre una cuenta debe nombrarla con X-ACCOUNT-ID; omitirlo en una lectura devuelve todas las cuentas de la organización. Cualquier otro endpoint responde 403 con code: organization_key_unsupported.

Path parameters

random_idstringRequired

ID público aleatorio del comando, con formato tsc_....

Headers

X-ACCOUNT-IDstringOptional

ID de una cuenta hija conectada. Ejecuta el request dentro de esa cuenta, como Stripe-Account en Stripe Connect. La plataforma puede acceder a todos los recursos API que pertenecen a la hija, sin filtrar por creador. Solo aplica a hijas directas: si la cuenta no está conectada a la tuya, el request responde 404 con code: connected_account_not_found.

Con una llave de organización este header nombra la cuenta miembro sobre la que quieres operar; si no pertenece a la organización, el request responde 404 con code: organization_account_not_found. En una lectura puedes omitirlo para abarcar todas las cuentas de la organización.

Response

Cancelación confirmada o ya confirmada

idstringOptional

ID público aleatorio del comando

external_idstringOptional

ID único de tu sistema dentro de la cuenta autenticada

statusenumOptional
Estado del comando
finalbooleanOptional

true cuando el comando alcanzó un resultado definitivo y ya no puede cambiar

terminal_idstringOptional
ID de la terminal POS
amount_in_centsintegerOptional

Monto en centavos. Para un cobro con items, la suma de los items.

currencyenumOptional
Moneda del cobro
Allowed values:
installmentsinteger or nullOptional

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

descriptionstring or nullOptional

Concepto del cobro enviado al crear el comando, o null si no se envió uno

show_post_payment_screensbooleanOptional

Indica si el comando solicita mostrar las pantallas post-pago de NIT, correo y teléfono

print_receiptbooleanOptional

Indica si el comando solicita imprimir automáticamente el comprobante de pago

tax_idstring or nullOptional

NIT del comprador enviado con el cobro, o null si no se envió uno

delivery_modeenumOptional
Modo de entrega del comando
Allowed values:
app_urlstring or nullOptionalformat: "uri"

Deep link para iniciar el cobro NFC en el Android asociado; null en modo standby. Requiere sesión autenticada y no contiene una llave API.

terminal_availabilityenumOptional
Disponibilidad observada de la terminal para recibir comandos
Allowed values:
checkout_idstringOptional
ID del checkout generado
checkout_urlstringOptionalformat: "uri"

URL del checkout generado. En el flujo de terminal no es el deep link para abrir la app Recurrente; la pantalla de Modo espera navega internamente a la sesión cuando recibe el comando.

checkout_statusenumOptional
Estado actual del checkout asociado
cancellation_requested_atdatetime or nullOptional

Momento en que se solicitó detener un comando ya despachado

canceled_atdatetime or nullOptional

Momento en que la cancelación se volvió definitiva

Errors

404
Not Found Error
409
Conflict Error