--- title: "Crear Charges en lote" method: POST path: "/{country_code}/charge/bulk" tags: ["Transactions"] --- # Crear Charges en lote `POST /{country_code}/charge/bulk` ## Request - Base URL: `https://api.trytoku.com` - URL: `https://api.trytoku.com/{country_code}/charge/bulk` - Auth: API key in header `x-api-key` Cobra un lote de Invoices en una sola llamada. Se usa para ejecutar muchos cobros a demanda sin llamar al endpoint individual por cada uno: el cuerpo lleva la lista `charges_requests`, con el mismo contenido que un cobro individual en cada elemento. Las rutas `/public/cl`, `/public/mx` y `/public/br` son equivalentes: el país de cada cobro lo determina la Organization dueña de su Account, no el prefijo de la ruta. El lote se procesa como una orquestación identificada por `id_bulk_charge`, que la respuesta devuelve para hacer seguimiento. Cuando el cuerpo pide esperar el resultado, la respuesta agrega el resumen del lote y las Transactions que dejó; si no, trae solo el identificador del lote. Cada Transaction que deja el lote queda marcada con ese `id_bulk_charge`, así que las Transactions de un lote que se procesó sin esperar su resultado se consultan después con `GET /public/transactions?id_bulk_charge={id_bulk_charge}`. Acepta como máximo 500 cobros por llamada. **Límite de tasa:** 1 solicitud por segundo. Al superarlo, la API responde `429`. Ver [Límites de tasa](/reference/limites-de-tasa). ## Path parameters - `country_code` 'cl' | 'mx' | 'br', required ## Headers - `x-api-version` string, date: Versión del API para esta petición, como cualquier fecha `YYYY-MM-DD`. Fija el contrato de la respuesta; si se omite, se deriva de la fecha de creación de la organización. - `x-account-key` string ## Request body - ChargeBulkRequest: Lote de cobros a demanda. - `charges_requests` ChargeRequest[], required: Cobros que componen el lote; hasta 500 por llamada. - `actions` ActionData[]: Acciones que compone el cobro: el producto de pago de cada una y si es un pago o una inscripción. Obligatorio salvo cuando se cobra a un medio de pago Transbank OneClick, que no lo usa. - `action_type` 'INSCRIPTION' | 'PAYMENT', required: Qué acción ejecuta un elemento del árbol de orquestación. `PAYMENT` intenta el cobro con el medio de pago del elemento. `INSCRIPTION` inscribe ese medio de pago para cobros futuros, sin cobrar en ese paso. Un mismo árbol puede llevar las dos, y en ese caso el resultado combinado del cobro y de la inscripción queda en `ChargeActionsStatus`. - `toku_product` 'pac_management' | 'pac_inscription' | 'direct_debit_cl' | 'direct_debit_mx' | 'transfer_cl' | 'transbank_oneclick' | 'transbank_webpay_plus' | 'klap_oneclick' | 'patpass' | 'cash' | 'cash_mx_one_time_psp' | 'cash_mx_one_time_pst' | 'cash_mx_psp' | 'cash_mx_pst' | 'toku_gateways' | 'payment_orchestration' | 'payment_orchestration_onetime' | 'multigateway_onetime' | 'toku_card_on_file' | 'toku_onetime' | 'domiciliation' | 'high_value_transfer' | 'codi' | 'wallet_mx' | 'cards_batch_mx_recurring_pst' | 'atoa_batch_mx_recurring_pst' | 'pix_onetime_pst_br' | 'boleto_br_onetime_pst' | 'boleto_br_recurring_pst' | 'pix_br_onetime_pst' | 'pix_br_onetime_psp' | 'pix_br_recurring_psp' | 'pix_bank_br_automatic_pst' | 'pix_bank_br_automatic_psp' | 'pix_bank_br_onetime_psp' | 'pix_openfinance_br_automatic_psp' | 'boleto_bank_br_onetime_psp' | 'cash_pst_cl' | 'transfer_mx_pst' | 'transfer_mx_psp' | 'transfer_cl_pst' | 'transfer_cl_psp' | 'direct_debit_onetime_cl_pst' | 'direct_debit_onetime_cl_psp' | 'bank_button_cl_pst' | 'bank_button_multiple_cl_pst' | 'bank_button_cl_psp' | 'bank_button_multiple_cl_psp' | 'digital_mandate_cl' | 'transfer_mx' | 'cards_br_recurring_pst' | 'cards_br_onetime_pst' | 'cards_br_recurring_psp' | 'cards_br_onetime_psp' | 'atoa_br_recurring_pst' | 'internal_balance' | 'cards_cl_onetime_pst' | 'cards_cl_recurring_pst' | 'cards_cl_pos_pst' | 'br_automatic_debit_pst' | 'external_collector_cl_pst' | 'referenced_payment_mx_psp' | 'in_app_payment_mx_psp' | 'external_payment' | 'collections_ai_agent' | 'bolepix_br_onetime_pst' | 'bolepix_bank_br_onetime_psp' | 'contacted_end_customers' | 'vcc' | 'atoa_batch_mx_recurring_psp' | 'international_transfer_mx_pst' | 'rat' | 'batch_reconciliations' | 'account_payouts' | 'account_payables' | 'transfer_cl_psp_wallet' | 'wallet_mx_psp', required: Producto de cobro de Toku: la combinación de método de pago, país y modalidad con que se ejecuta un cobro. El nombre codifica esas tres cosas — por ejemplo `pix_br_recurring_psp` es Pix recurrente en Brasil bajo el modelo PSP, y `cards_cl_onetime_pst` es tarjetas de un solo pago en Chile bajo el modelo PST. Es el valor que decide con qué integración se ejecuta el cobro, así que buena parte de la lógica que depende del país se resuelve a partir de él. Qué productos tiene habilitados una organización es parte de su configuración: este listado es el universo posible, no lo que una organización determinada puede cobrar hoy. `cash`, `cash_mx_one_time_psp`, `cash_mx_one_time_pst` y `transfer_mx` están deprecados y solo sobreviven por compatibilidad con registros históricos. - `amount` number: Monto a cobrar. Debe enviarse este campo o `id_invoices`. - `capture_method` 'AUTOMATIC' | 'DEFERRED': Cuándo se captura el monto autorizado de un cobro. Con `AUTOMATIC`, el valor por defecto, la autorización y la captura ocurren en el mismo intento. Con `DEFERRED` el cobro queda autorizado en `CAPTURE_PENDING` y el monto se captura en una operación posterior, que puede capturar hasta el total autorizado. - `external_id` string: Referencia externa que la Organization asigna a la Transaction del cobro. - `id_account` string, required: Identificador público de la Account a la que se le cobra. - `id_invoices` string[]: Identificadores públicos de los Invoices que se quieren saldar. Debe enviarse este campo o `amount`. - `id_orchestration_tree` string: Identificador del árbol de orquestación base con que se cobra. Si se omite o no existe, el árbol se arma a partir de `actions`. - `id_payment_instrument` string: Identificador público del instrumento de pago con que se cobra. Debe enviarse este campo o `id_payment_methods`. - `id_payment_methods` string[]: Identificadores públicos de los medios de pago con que se cobra. Debe enviarse este campo o `id_payment_instrument`, y todos deben pertenecer a la Account indicada. - `idempotency_key` string: Llave con que se deduplican los reintentos del cobro; si se omite, se genera una. - `metadata` object: Datos libres que la Organization adjunta al cobro. - `should_await_inscription_result` boolean: Cuando es `true`, la respuesta espera el resultado de la inscripción del medio de pago y agrega `actions_status`. - `unique_external_id` string: Referencia externa única del cobro; si se omite, se genera una. - `wait_for_result` boolean: Cuando es `true`, la respuesta espera que el lote termine y agrega su resumen y sus Transactions. ## Response `200` Identificador del lote y, si se pidió esperar el resultado, su resumen y sus Transactions. - ChargeBulkResponse: Resultado de un cobro masivo pedido desde una integración. - `id_bulk_charge` string: Identificador del lote con que se sigue su procesamiento. - `result` BulkResult: Resumen del avance de un cobro masivo. - `is_done` boolean: Indica si el lote terminó de procesarse. - `total_error` integer: Cantidad de cobros del lote que terminaron con error. - `total_success` integer: Cantidad de cobros del lote que terminaron correctamente. - `transactions` AggregatedTransaction[]: Transactions que dejó el lote, con su Customer, sus Payment Intents y el medio de pago usado. Solo viene cuando el lote pidió esperar su resultado. - `applied_adjustment_documents` AppliedAdjustmentDocument[], required - `amount` number, required - `external_id` string, required - `id` string, required - `type` union, required - 'credit_note' | 'supplier_invoice': Categoría de un documento de ajuste: `credit_note` es una nota de crédito emitida al Customer, que rebaja lo que debe, y `supplier_invoice` una factura de proveedor que se descuenta al momento del cobro. - string - `customer` DTOCustomerV2 - `email` string - `external_id` string - `government_id` string - `id` string, required - `metadata` object - `name` string - `phone_number` string - `payment_instrument` union - ClPaymentInstrument: Instrumento de pago de Chile - compuesto a partir de DTOs individuales - `card` CardPaymentInstrument - `bin` string - `card_brand` string - `card_holder` string - `card_type` string - `country` string - `exp_month` string - `exp_year` string - `external_id` string - `installments_number` integer - `issuer` string - `last_digits` string - `status` string - `three_d_secure` boolean - `token` string - `cash` CashClPaymentInstrument - `accounting_date` string - `country` string - `due_date` string - `external_id` string - `payment_date` string - `source` string - `country` 'CL' - `id` string - `id_checkout_session` string - `pac_management` PacManagementPaymentInstrument - `country` string - `institution_id` string - `mandate_id` string - `payer_government_id` string - `payer_name` string - `sbif` string - `patpass` PatpassPaymentInstrument - `country` string - `service_id` string - `status` string - `transfer` TransferClPaymentInstrument - `account_number` string - `account_type` string - `country` string - `government_id_match` boolean - `institution_id` string - `payer_government_id` string - `type` 'card' | 'transfer' | 'cash' | 'wallet' | 'pix' | 'pac_management' | 'patpass' | 'account' | 'boleto' | 'referenced_payment' | 'external' | 'in_app_payment', required: Tipo del instrumento con el que se movió el dinero, y por lo tanto qué detalle trae el instrumento. `card` es una tarjeta y `account` la cuenta bancaria del pagador o del receptor: es el valor con el que hoy se registran las transferencias y los débitos automáticos. `transfer`, `pac_management` y `patpass` no se almacenan, se derivan del producto de la transacción, y se mantienen porque las integraciones antiguas esperan verlos. Entre esos dos últimos, `pac_management` es el PAC chileno, que debita una cuenta bancaria con un mandato, y `patpass` el PatPass de Transbank, que debita una tarjeta. Los demás son de un país o un canal: `pix` y `boleto` en Brasil; `cash` es pago en efectivo en un punto de pago; y `wallet`, `referenced_payment` e `in_app_payment` son de México, para billetera digital, pago referenciado en el banco y pago hecho dentro de la aplicación de un tercero. `external` es dinero que se movió fuera de los medios de pago de Toku y se registró para conciliarlo, así que no trae ningún detalle asociado. - MxPaymentInstrument: Instrumento de pago de México - compuesto a partir de DTOs individuales - `account` AccountPaymentInstrument - `account` string - `bank_account_type` string - `bank_id` string - `bin` string - `card_brand` string - `card_type` string - `last_digits` string - `status` string - `token` string - `card` CardPaymentInstrument - `bin` string - `card_brand` string - `card_holder` string - `card_type` string - `country` string - `exp_month` string - `exp_year` string - `external_id` string - `installments_number` integer - `issuer` string - `last_digits` string - `status` string - `three_d_secure` boolean - `token` string - `cash` CashMxPaymentInstrument - `auth_code` string - `barcode_url` string - `expiration_date` string, date-time - `is_recurrent` boolean - `reference` string - `store_name` string - `country` 'MX' - `id` string - `id_checkout_session` string - `referenced_payment` ReferencedPaymentMXInstrument - `agreement_identifier` string - `bank_account_identifier` string - `expiration_date` string, date-time - `fixed_amount` number - `provider` string - `reference` string - `transfer` TransferMxPaymentInstrument - `beneficiary_clabe` string - `codi_folio` string - `payer_clabe` string - `payer_name` string - `tracking_id` string - `transaction_date` string, date-time - `type` 'card' | 'transfer' | 'cash' | 'wallet' | 'pix' | 'pac_management' | 'patpass' | 'account' | 'boleto' | 'referenced_payment' | 'external' | 'in_app_payment', required: Tipo del instrumento con el que se movió el dinero, y por lo tanto qué detalle trae el instrumento. `card` es una tarjeta y `account` la cuenta bancaria del pagador o del receptor: es el valor con el que hoy se registran las transferencias y los débitos automáticos. `transfer`, `pac_management` y `patpass` no se almacenan, se derivan del producto de la transacción, y se mantienen porque las integraciones antiguas esperan verlos. Entre esos dos últimos, `pac_management` es el PAC chileno, que debita una cuenta bancaria con un mandato, y `patpass` el PatPass de Transbank, que debita una tarjeta. Los demás son de un país o un canal: `pix` y `boleto` en Brasil; `cash` es pago en efectivo en un punto de pago; y `wallet`, `referenced_payment` e `in_app_payment` son de México, para billetera digital, pago referenciado en el banco y pago hecho dentro de la aplicación de un tercero. `external` es dinero que se movió fuera de los medios de pago de Toku y se registró para conciliarlo, así que no trae ningún detalle asociado. - `wallet` WalletPaymentInstrument - `company` string, required - `installments_number` integer - BrPaymentInstrument: Instrumento de pago de Brasil - compuesto a partir de DTOs individuales - `boleto` BoletoPaymentInstrument - `address` object - `barcode` string - `barcode_url` string - `customer` object - `expiration_date` string - `fine_amount` string - `interest_amount` string - `pdf_url` string - `typeable_line_number` string - `validity_date` string - `card` CardPaymentInstrument - `bin` string - `card_brand` string - `card_holder` string - `card_type` string - `country` string - `exp_month` string - `exp_year` string - `external_id` string - `installments_number` integer - `issuer` string - `last_digits` string - `status` string - `three_d_secure` boolean - `token` string - `country` 'BR' - `id` string - `id_checkout_session` string - `pix` PixPaymentInstrument - `account_type` string - `bank_ispb` string - `bank_name` string - `copy_paste_code` string - `end_to_end_id` string - `error_code` string - `error_message` string - `expiration_date` string, date-time - `internal_bank_id` string - `issuer` string - `number` string - `pix_automatic` object - `provider_request_id` string - `qr_code` string - `redirect_url` string - `tax_id` string - `total_installments` string - `type` 'card' | 'transfer' | 'cash' | 'wallet' | 'pix' | 'pac_management' | 'patpass' | 'account' | 'boleto' | 'referenced_payment' | 'external' | 'in_app_payment', required: Tipo del instrumento con el que se movió el dinero, y por lo tanto qué detalle trae el instrumento. `card` es una tarjeta y `account` la cuenta bancaria del pagador o del receptor: es el valor con el que hoy se registran las transferencias y los débitos automáticos. `transfer`, `pac_management` y `patpass` no se almacenan, se derivan del producto de la transacción, y se mantienen porque las integraciones antiguas esperan verlos. Entre esos dos últimos, `pac_management` es el PAC chileno, que debita una cuenta bancaria con un mandato, y `patpass` el PatPass de Transbank, que debita una tarjeta. Los demás son de un país o un canal: `pix` y `boleto` en Brasil; `cash` es pago en efectivo en un punto de pago; y `wallet`, `referenced_payment` e `in_app_payment` son de México, para billetera digital, pago referenciado en el banco y pago hecho dentro de la aplicación de un tercero. `external` es dinero que se movió fuera de los medios de pago de Toku y se registró para conciliarlo, así que no trae ningún detalle asociado. - `payment_intents` PaymentIntent[], required - `amount` number, required - `billable_exchange_rate` number - `currency` '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. - `gateway` 'transbank_oneclick' | 'klap_oneclick' | 'patpass' | 'toku_onetime' | 'toku_pac' | 'fintoc_pac' | 'universo_pac' | 'ecert_pac' | 'external_pac' | 'manual_pac' | 'internal_psp' | 'domiciliation' | 'mx_banco_bbva' | 'mx_banco_bancomer' | 'payment_orchestration' | 'getnet' | 'getnet_pos' | 'transbank' | 'transbank_webpay_plus' | 'khipu_transfer' | 'fintoc_transfer' | 'floid_transfer' | 'toku_transfer' | 'conciliation' | 'pb_transfer_cl_banco_de_chile' | 'pb_transfer_cl_banco_de_chile-evertec' | 'pb_transfer_cl_banco_santander' | 'pb_transfer_cl_banco_santander-evertec' | 'pb_transfer_cl_banco_santander_direct' | 'pb_transfer_cl_banco_santander-native' | 'pb_transfer_cl_banco_scotiabank' | 'pb_transfer_cl_banco_scotiabank_direct' | 'pb_transfer_cl_banco_scotiabank-native' | 'pb_transfer_cl_banco_bci' | 'pb_transfer_cl_banco_bci-native' | 'pb_transfer_cl_banco_bci_direct' | 'pb_transfer_cl_banco_bci-serviex' | 'pb_transfer_cl_banco_itau' | 'pb_transfer_cl_banco_itau-evertec' | 'pb_transfer_cl_banco_estado' | 'pb_transfer_cl_banco_bice' | 'pb_transfer_cl_banco_falabella' | 'arcus_transfer' | 'stp_transfer' | 'cobre_transfer' | 'monex_transfer' | 'oxxo' | 'paycash' | 'dapp' | 'tapi' | 'puntored' | 'cash_pickup' | 'multigateway_onetime' | 'toku_gateways_conekta' | 'toku_gateways_stripe' | 'toku_gateways_mercado_pago' | 'toku_gateways_open_pay' | 'toku_gateways_pay_u' | 'toku_gateways_paypal' | 'toku_gateways_net_pay' | 'po_open_pay' | 'po_rapyd' | 'po_conekta' | 'po_stripe' | 'po_kushki' | 'po_fiserv' | 'po_evo_payments' | 'po_paypal' | 'po_mit' | 'openpay' | 'rapyd' | 'conekta' | 'stripe' | 'kushki' | 'mit' | 'codi_qr' | 'codi' | 'paypal' | 'br_banco_itau' | 'br_banco_itau_boleto' | 'br_banco_bradesco_boleto' | 'br_banco_bradesco_pix' | 'br_sicredi_boleto' | 'servipag' | 'servipag_portal' | 'servipag_caja_presencial' | 'servipag_caja_express' | 'cards_batch_mx_recurring_pst' | 'amex_batch_mx_recurring_pst' | 'braintree' | 'pagarme' | 'br_paulista_servicios_automatic_debit' | 'mx_banco_santander' | 'mx_banco_bbva_bancomer' | 'mx_banco_banorte' | 'mx_banco_banorte_h2h' | 'mx_banco_scotiabank' | 'mx_banco_hsbc' | 'mx_banco_citibanamex' | 'mx_banco_multiva' | 'mx_amex' | 'mx_banco_banbajio' | 'mx_banco_banregio' | 'mx_banco_sabadell' | 'mx_belvo' | 'mx_bbva_cie' | 'internal_balance' | 'fiserv' | 'cielo' | 'belvo' | 'mx_banco_scotiabank_h2h_external' | 'iniciador' | 'qi_tech' | 'evo_payments' | 'cl_banco_de_chile' | 'cl_banco_bci' | 'cl_banco_santander' | 'cl_banco_scotiabank' | 'cl_banco_security' | 'cl_banco_consorcio_fidi' | 'transdata' | 'br_banco_do_brasil' | 'br_banco_santander' | 'br_banco_citibank' | 'rede' | 'mercadopago' | 'br_caixa_via_accesstage' | 'br_banco_de_brasilia' | 'worldpay' | 'br_banco_de_brasilia_via_accesstage' | 'br_santander_via_accesstage' | 'br_bradesco_via_accesstage' | 'br_banco_do_brasil_via_accesstage' | 'br_c6_via_accesstage' | 'br_sicoob_via_accesstage' | 'br_itau_via_accesstage' | 'external_payment' | 'br_sicoob' | 'br_caixa' | 'br_btg' | 'toku_mx_belvo' | 'toku_mx_banco_bbva_bancomer' | 'servipag_button' | 'servipag_cashier' | 'servipag_web' | 'servipag_express' | 'sencillito_cashier' | 'sencillito_web' | 'scotiabank_cashier' | 'unired': Integración por la que se cursa un intento de cobro: el adquirente, banco o recaudador concreto que lo ejecuta. La mayoría de los valores corresponde a una institución de un solo país; el resto son mecanismos propios de Toku, como `internal_psp`, `manual_pac` o `external_payment`. Es el conjunto más amplio de gateways de Toku y crece cada vez que se habilita una institución nueva, así que conviene leerlo como una lista abierta y no agotar sus valores en el código. Para el gateway con que se inscribió un medio de pago, ver `PaymentMethodGateway`. - `id` string, required - `id_account` string, required - `id_invoice` string, required - `id_subscription` string, required - `invoice_external_id` string - `invoice_metadata` object - `is_last_payment` boolean - `is_partial` boolean - `price_change_amount` number, required - `product_id` string, required - `rendition_file` string - `status` 'FAILED' | 'EXPIRED' | 'DELETED' | 'AUTHORIZED' | 'CHARGEBACK' | 'INITIALIZED' | 'PAC_PENDING' | 'PAC_CREATED' | 'CONSTRAINTS_VIOLATED' | 'REFUNDED' | 'ABORTED' | 'INITIALIZED_NON_BLOCKING' | 'REFUND_INITIALIZED' | 'REFUND_FAILED', required: En qué quedó un intento de cobro. Un Payment Intent es el intento de pagar una deuda con un medio de pago, y este campo es su desenlace. Nace `INITIALIZED`. `AUTHORIZED` es el éxito, y significa dinero efectivamente cobrado: es el único estado que suma al monto pagado de la deuda. Un cobro con captura diferida no llega ahí mientras el dinero está solo retenido; el intento sigue `INITIALIZED` hasta que la captura se confirma. Entre las fallas, `FAILED` es que se intentó el cobro y fue rechazado, y `ABORTED` que no hubo resultado porque el intento se canceló o se dio por perdido. Ahí cae un caso que no es evidente: cuando vence el plazo de una sesión de pago o de un enlace, el intento queda `ABORTED`, no `EXPIRED`. `INITIALIZED_NON_BLOCKING` es un intento abierto que no reserva la deuda: la deja cobrable y disponible para otros intentos. Lo usan los cobros contra un comprobante o una referencia, como boleto, Pix, CoDi o Servipag, donde el cliente puede pagar días después y no corresponde bloquear la deuda mientras tanto. `PAC_CREATED` y `PAC_PENDING` son las dos etapas del débito automático chileno: el intento entró en un archivo de cobro ya generado, y después ese archivo se entregó al banco y espera su respuesta, que lo deja en `AUTHORIZED` o `FAILED`. Las reversas no modifican el intento original, se registran como intentos nuevos sobre la misma deuda. `REFUND_INITIALIZED` es una devolución en curso, que termina en `REFUNDED` o en `REFUND_FAILED`; `CHARGEBACK` es un contracargo, que a diferencia de la devolución lo inicia el tarjetahabiente o su banco. `REFUNDED` y `CHARGEBACK` restan del monto pagado de la deuda. `DELETED` marca un intento eliminado, que no cuenta para nada. `EXPIRED` y `CONSTRAINTS_VIOLATED` son estados heredados: ningún proceso los escribe hoy y solo aparecen en datos antiguos. - `type` 'recurring' | 'one_time': Si el intento de cobro nace de un cobro recurrente sobre un medio de pago ya inscrito (`recurring`) o de un pago puntual que el pagador inicia en el momento (`one_time`). - `transaction` Transaction, required: Intento de cobro sobre un medio de pago, con su resultado. Queda una Transaction cada vez que Toku mueve dinero o intenta moverlo: un cobro pedido por API, un pago hecho en el portal de Toku, un pago que el deudor hizo por fuera y que se registra, o la reversa de cualquiera de ellos. Los intentos fallidos también quedan registrados. Se crea al iniciar el cobro, cuando todavía no se conoce el resultado; es la finalización la que lo define. Recién ahí se saldan las Invoices que la Transaction cubre y se avisa el desenlace por webhook. - `additional_data` object: Información complementaria del movimiento, como el detalle de la devolución cuando la Transaction fue devuelta. - `amount` number, required: Monto del movimiento, expresado en la moneda de `currency`. - `currency` '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. - `expiration_date` string: Fecha y hora, en formato [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) y en UTC, hasta la que la Transaction puede resolverse. Si vence sin resolverse queda `ABORTED`; en una autorización diferida es el plazo hasta el que se puede capturar. Es nulo cuando la Transaction no tiene vencimiento. - `external_id` string: Identificador que entrega la organización para reconocer la Transaction en sus propios sistemas. - `gateway` string: Procesador con el que se cursó el movimiento. - `id` string, required: Identificador único de la Transaction. - `id_account` string: Cuenta de cobro de la organización a la que se imputa el movimiento. - `id_charge_scheduled_date` string: Identificador de la fecha de cobro programada (charge scheduled date) que originó la Transaction, es decir, la que la mandó a cobro. Es nulo cuando la Transaction no nació de una fecha de cobro programada. - `id_checkout_session` string: Checkout Session desde la que se originó el cobro. Es nulo cuando el cobro no partió de un checkout. - `id_organization` string: Organización dueña de la Transaction. - `id_payout` string: Payout con el que se le liquidó a la organización el dinero de esta Transaction. Es nulo mientras no se haya liquidado. - `initialization_date` string: Fecha y hora, en formato [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) y en UTC, en que se creó la Transaction. Se distingue de `transaction_date`, que es la fecha del movimiento de dinero. - `installment_amount` number: Monto de cada mensualidad, en la moneda de la Transaction. - `number_of_installments` integer: Cantidad de mensualidades en que se pactó el cobro. En México corresponde a los meses sin intereses acordados con el tarjetahabiente. Un cobro en un solo pago reporta `1`. - `original_response_message` string: Mensaje con el que el procesador respondió al cobro, tal cual lo entregó. Es nulo cuando no alcanzó a haber respuesta del procesador. - `provider_external_id` string: Identificador con el que el procesador reconoce el cobro. En los productos que se pagan con una referencia, como Pago Directo BBVA, es la referencia con que pagó el cliente final. Es nulo cuando el procesador no entrega un identificador propio. - `remediation_detail` string: Motivo con el que se remedió la Transaction, cuando un cobro que había fallado se rehízo y terminó bien. Es nulo cuando no hubo remediación. - `response_code` string: Código de resultado del cobro, normalizado por Toku a partir de la respuesta del procesador. Se compone de la gravedad (`SU` éxito, `TE` temporal, `PE` permanente, `UE` desconocido), tres letras que identifican la fuente y cuatro dígitos de detalle: `0000` cuando el cobro resultó exitoso y `9999` cuando la respuesta no se pudo clasificar. El listado completo está en [Códigos de pago rechazado](/reference/codigos-de-pago-rechazado). Es nulo mientras el cobro no se resuelve y en los movimientos que no pasan por un procesador, como los pagos registrados por fuera y los contracargos. - `status` 'INITIALIZED' | 'SUCCESS' | 'FAILED' | 'FAILED_INIT' | 'ABORTED' | 'CAPTURE_PENDING', required: Estado de una Transaction. `INITIALIZED` es el intento ya creado y todavía sin resolver; `SUCCESS` y `FAILED` son sus dos desenlaces, y `ABORTED` es el intento cancelado antes de resolverse, ya sea por una cancelación explícita o porque venció su plazo de expiración. `CAPTURE_PENDING` solo aparece en los cobros con captura diferida: el monto quedó autorizado y espera la captura, que lo lleva a `SUCCESS`. `FAILED_INIT` está deprecado: ninguna Transaction nueva lo alcanza y solo sobrevive en registros históricos. - `status_history` StatusHistory[]: Cambios de estado por los que pasó la Transaction, en el orden en que ocurrieron. - `new_status` string, required: Estado al que pasó el objeto. - `old_status` string: Estado en el que estaba el objeto antes del cambio. Es nulo en el primer registro. - `timestamp` string, date-time, required: Fecha y hora en que ocurrió el cambio de estado. - `toku_product` string: Producto de Toku con el que se cobró, que determina el medio de pago usado, por ejemplo `toku_card_on_file` o `transfer_cl`. - `transaction_date` string, required: Fecha y hora, en formato [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) y en UTC, en que se realizó el movimiento de dinero. - `transaction_metadata` object, required: Datos con los que Toku caracteriza el cobro, como el tipo de tarjeta con la que se pagó. Las claves dependen del medio de pago usado. - `type` 'ONETIME' | 'INSCRIPTION' | 'INSCRIPTION_REVERSED' | 'CARD_ON_FILE_PAYMENT' | 'CARDLESS_PAYMENT' | 'PATPASS_PAYMENT' | 'REVERSED' | 'VOID' | 'PAYMENT' | 'CHARGEBACK' | 'EXTERNAL_PAYMENT' | 'CHARGEBACK_REVERSAL', required: Naturaleza de la operación que representa una Transaction. Distingue los cobros (`PAYMENT`, `ONETIME`, `CARD_ON_FILE_PAYMENT`, `CARDLESS_PAYMENT`, `PATPASS_PAYMENT`) de las operaciones que no mueven dinero del pagador, como `INSCRIPTION`, que solo inscribe un medio de pago, y de las que revierten una operación previa (`REVERSED`, `VOID`, `INSCRIPTION_REVERSED`, `CHARGEBACK`, `CHARGEBACK_REVERSAL`). `EXTERNAL_PAYMENT` corresponde a un pago que no procesó Toku y que se registra para dejar saldadas sus Invoices: nace directamente en estado `SUCCESS`. - `voucher` string: Comprobante del cobro que entrega el procesador. Es nulo cuando el procesador no entrega uno. - `wallet_movements` WalletMovement[], required - `amount` number, required - `id` string, required - `type` string, required ## Other responses - `400`: Los medios de pago enviados mezclan Transbank OneClick con medios que se cobran por orquestación, traen más de un medio Transbank OneClick, o ninguno de ellos existe. `actions-or-orchestration-tree-required`: un cobro que no es Transbank OneClick llegó sin `actions`. En un lote, basta un cobro así para rechazar el lote completo antes de cobrar ninguno. - `401`: Faltan las credenciales o son inválidas. - `403`: No tienes acceso a este recurso. - `404`: El recurso solicitado no existe. - `422`: El cuerpo de la petición no pasó la validación. - `429`: Se superó el límite de peticiones permitidas. --- [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)