--- title: "Cobrar en un terminal POS" method: POST path: "/{country_code}/checkout-sessions/pos-charge" tags: ["Checkout Session"] --- # Cobrar en un terminal POS `POST /{country_code}/checkout-sessions/pos-charge` ## Request - Base URL: `https://api.trytoku.com` - URL: `https://api.trytoku.com/{country_code}/checkout-sessions/pos-charge` - Auth: API key in header `x-api-key` Cobra en un terminal POS físico y devuelve la transacción que quedó esperando a que el cliente final pase la tarjeta. **El `201` no significa que el cliente pagó**: significa que el terminal tomó la venta y todavía tiene que operarla. El resultado del cobro llega por el webhook de transacción —[`transaction.success`](/reference/transaction-success) o [`transaction.failed`](/reference/transaction-failed)—, que devuelve el `external_id` con el que la caja correlaciona la operación. Ese mismo estado se puede consultar con `GET /transactions/{public_id_transaction}`: el cobro POS no tiene un endpoint de estado propio. Se envía una de tres formas, nunca más de una: `ids_invoice`, para saldar deudas ya creadas; `amount` junto con `currency` e `id_account`, para cobrar un monto suelto; o `invoice_data` junto con `id_account` y un Customer (`id_customer` o `customer_data`), para crear la deuda y saldarla en el mismo paso. No se envía medio de pago: la tarjeta la lee el terminal. Abre una Checkout Session en estado `OPEN` y despacha la venta al terminal. Esa sesión es el contenedor del intento de cobro y se cierra sola cuando el cobro termina: a diferencia de los demás productos, no es una página que se renderice ni tiene una `url` a la que derivar al cliente. Si el terminal no toma la venta, la sesión queda `EXPIRED` y no se cobra nada. El terminal y las deudas tienen que pertenecer a la organización autenticada, y hoy los únicos terminales habilitados son los chilenos (`country_code` = `cl`). Cualquier campo que no esté en el contrato se rechaza con 422: la caja no cobra distinto de lo que pidió. Si se envía `idempotency_key`, ese valor no puede repetirse dentro de la organización: un reintento por timeout se rechaza con 409 en vez de cobrar dos veces. ## Path parameters - `country_code` 'cl' | 'mx' | 'br', required ## Request body - PosChargeRequestDecryption: Datos con los que la caja cobra en un terminal POS. - `additional_metadata` object, nullable: Datos propios de la organización que se guardan junto a la Checkout Session. - `allow_partial_payment` boolean, nullable: Indica si el cliente final puede abonar solo una parte del total. - `amount` number, nullable: Monto que se cobra en la Checkout Session. Excluyente con `ids_invoice` y con `invoice_data`, y cuando se envía, `currency` e `id_account` son obligatorios. - `currency` 'CLP' | 'CLF' | 'MXN' | 'BRL' | 'USD': Moneda, en código [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). Cubre las monedas de los países donde Toku opera —`CLP` (peso chileno), `MXN` (peso mexicano) y `BRL` (real)— más `USD` y `CLF`, la Unidad de Fomento chilena. La moneda determina cuántos decimales admiten los montos: `CLP` no admite decimales, `MXN`, `BRL` y `USD` admiten dos, y `CLF` cuatro. - `customer_data` CustomerDataRequest: Datos con los que se busca o se crea el Customer de la Checkout Session. - `external_id` string, nullable - `government_id` string, nullable - `mail` string, nullable - `name` string, nullable - `phone_number` string, nullable - `external_id` string, nullable: Identificador que entrega la organización para reconocer después la operación. Vuelve en el webhook de transacción como `external_id`: es con lo que la caja correlaciona el resultado del cobro. - `flow_name` string, nullable: Flow con el que se crea la Checkout Session. Determina la configuración de POS que se aplica en el terminal. - `id_account` string, encrypted-id, nullable: Identificador de la Account. Si se omite, se resuelve desde las deudas. - `id_customer` string, encrypted-id, nullable: Identificador del Customer. Si se omite, se resuelve desde las deudas. - `id_pos_terminal` string, encrypted-id, required: Terminal POS en el que se cobra. Tiene que pertenecer a la organización autenticada. - `idempotency_key` string, nullable: Identificador propio de la organización que, si se envía, no puede repetirse: un reintento por timeout se rechaza con 409 en vez de cobrar dos veces. - `ids_invoice` string[], nullable: Identificadores de las deudas que se cobran en la Checkout Session. Excluyente con `amount` y con `invoice_data`: se envía una de las tres. - `invoice_data` InvoiceDataRequest: Datos con los que se crea la Invoice de la Checkout Session. - `amount` number, required: Monto total de la deuda que se cobra en la sesión. - `currency_code` 'CLP' | 'CLF' | 'MXN' | 'BRL' | 'USD', required: Moneda, en código [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). Cubre las monedas de los países donde Toku opera —`CLP` (peso chileno), `MXN` (peso mexicano) y `BRL` (real)— más `USD` y `CLF`, la Unidad de Fomento chilena. La moneda determina cuántos decimales admiten los montos: `CLP` no admite decimales, `MXN`, `BRL` y `USD` admiten dos, y `CLF` cuatro. - `disable_automatic_payment` boolean, nullable: Indica si la deuda queda excluida de los cobros automáticos, de modo que solo se pague desde este checkout. - `due_date` string, nullable - `expiration_action` 'EXPIRE' | 'VOID' | 'DELETE': Acción que se ejecuta sobre una Invoice cuando expira: marcarla como expirada (`EXPIRE`), anularla (`VOID`) o eliminarla (`DELETE`). `EXPIRE` es legado: se mantiene por compatibilidad, pero deja la Invoice en el estado `EXPIRED`, que está deprecado. Para nuevas integraciones usa `VOID` o `DELETE`. - `expiration_date` string, nullable: Fecha en la que la deuda expira, en formato ISO 8601. - `invoice_external_id` string, nullable: Identificador de la deuda en los sistemas de la organización, para poder conciliarla. - `max_collection_attempts` integer, nullable: Cantidad máxima de intentos de cobro automático de la deuda. - `metadata` object, nullable: Datos propios de la organización que se guardan junto a la deuda y no afectan el cobro. - `product_id` string, required: Identificador del producto o servicio que se está cobrando, definido por la organización. - `will_expire` boolean, nullable: Indica si la deuda expira al llegar su fecha de expiración. ## Response `201` La venta quedó despachada al terminal y la Checkout Session abierta. No significa que el cliente haya pagado: el resultado llega por el webhook de transacción. - PosChargeResponse: Checkout Session abierta para el cobro POS junto con su transacción. - `id_checkout_session` string, required: Checkout Session que contiene el intento de cobro. Se cierra sola cuando el cobro termina y no renderiza ninguna página: sirve como referencia de la operación. - `transaction` PosChargeTransactionResponse, required: Transacción que el terminal abrió para el cobro. - `expiration_date` string, nullable: Fecha y hora, en formato ISO 8601, en la que el cobro deja de esperar al terminal. - `id_transaction` string, required: Identificador de la Transaction del cobro. - `provider_external_id` string, nullable: Identificador que el proveedor le asignó a la operación. Viene `null` cuando el proveedor no lo entregó al despachar la venta; en ese caso queda registrado al resolverse el cobro. - `status` string, required: Estado en el que quedó la Transaction. Una venta recién despachada queda en `INITIALIZED`: el cliente todavía no operó el terminal. ## Other responses - `400`: El flow con el que se abre la Checkout Session no existe o no tiene medios de pago válidos. - `404`: El terminal no existe, o el terminal o las deudas no pertenecen a la organización autenticada. - `409`: El terminal está ocupado con otro cobro, la deuda ya tiene un cobro en curso o está pagada, o ya existe una Checkout Session de la organización con el mismo `idempotency_key`. Un terminal atiende un cobro a la vez, así que `terminal_busy` se reintenta cuando termina el que está en curso. `invoice_not_chargeable` se reintenta solo si la deuda tenía un cobro en curso —y aplica aunque el reintento venga de otro terminal—; si ya está pagada, reintentar no sirve. - `422`: Falta un campo obligatorio, se combinó más de una forma de cobro —`ids_invoice`, `amount` o `invoice_data`— o se envió un campo que no está en el contrato. - `502`: No se pudo contactar al terminal o el cobro no se pudo procesar. La Checkout Session queda expirada. ## Changes - **2026-11-03** `a6ef070075b1`: 1 info - endpoint added [Operation history](https://skmtc.dev/trytoku/apis/toku-api/changes/:country_code/checkout-sessions/pos-charge/post.md) --- [API](https://skmtc.dev/trytoku/apis/toku-api.md) - [All operations](https://skmtc.dev/trytoku/apis/toku-api/llms.txt) - [OpenAPI document](https://skmtc.dev/trytoku/apis/toku-api/revisions/a6ef070075b1?raw)