TRtrytoku
Transactions

Crear Charge

Cobra a una Account los Invoices o el monto indicados, con los medios de pago que se envíen.

Se usa para ejecutar un cobro a demanda desde una integración: el cuerpo indica la Account, el medio de pago (id_payment_instrument o id_payment_methods) y qué cobrar (id_invoices, un amount, o ambos). Las rutas /cl, /mx y /br son equivalentes: el país con que se procesa el cobro lo determina la Organization dueña de la Account, no el prefijo de la ruta.

El cobro se ejecuta durante la llamada, así que la respuesta trae las Transactions resultantes con el estado que alcanzaron. Cuando el cuerpo pide esperar el resultado de la inscripción del medio de pago, la respuesta agrega el medio de pago inscrito y un actions_status que resume cómo terminaron el cobro y la inscripción.

Los reintentos se deduplican por idempotency_key: una segunda llamada con la misma llave no vuelve a cobrar y responde con las Transactions del cobro original, con el estado que tienen al momento del reintento. La deduplicación dura 12 horas; pasado ese plazo la misma llave inicia un cobro nuevo.

Responde 401 cuando la Account, los Invoices, los medios de pago o el instrumento de pago no pertenecen a la Organization autenticada, y 400 cuando los medios de pago enviados mezclan Transbank OneClick con medios que se cobran por orquestación, cuando traen más de un medio Transbank OneClick, o cuando ninguno de los medios enviados existe.

Límite de tasa: 20 solicitudes por segundo. Al superarlo, la API responde 429. Ver Límites de tasa.

post/{country_code}/charge

Request

  • Base URL
    https://api.trytoku.com
  • URL
    https://api.trytoku.com/{country_code}/charge
  • Auth
    API key in header x-api-key

Path parameters

country_code'cl' | 'mx' | 'br' required

País de la organización sobre la que se opera, como primer segmento de la ruta: cl (Chile), mx (México) o br (Brasil).

Headers

x-api-versionstring 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.

Example:2026-10-08
x-account-keystring

Llave de API de una Account, para operar sobre esa Account en lugar de la principal.

Request body

amountnumber

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_idstring

Referencia externa que la Organization asigna a la Transaction del cobro.

id_accountstring required

Identificador público de la Account a la que se le cobra.

id_invoicesstring[]

Identificadores públicos de los Invoices que se quieren saldar. Debe enviarse este campo o amount.

id_orchestration_treestring

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_instrumentstring

Identificador público del instrumento de pago con que se cobra. Debe enviarse este campo o id_payment_methods.

id_payment_methodsstring[]

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_keystring

Llave con que se deduplican los reintentos del cobro; si se omite, se genera una.

metadataobject

Datos libres que la Organization adjunta al cobro.

should_await_inscription_resultboolean

Cuando es true, la respuesta espera el resultado de la inscripción del medio de pago y agrega actions_status.

unique_external_idstring

Referencia externa única del cobro; si se omite, se genera una.

Example request

{
  "capture_method": "AUTOMATIC",
  "id_account": "acc_7bQ2mN4pR6sT8vX0yZ2aB4cD6eF8gH0j",
  "id_invoices": [
    "in_5dF7hJ9kM1nP3rT5vX7zB9dF1hJ3lN5p"
  ],
  "id_payment_methods": [
    "pm_3kL5nP7qR9sU1wY3aC5eG7iK9mO1qS3u"
  ]
}

Response

Transactions que dejó el cobro y, si se pidió, el medio de pago inscrito.

actions_status'PAYMENT_FAILED_INSCRIPTION_SKIPPED' | 'PAYMENT_FAILED_INSCRIPTION_FAILED' | 'PAYMENT_FAILED_INSCRIPTION_SUCCESS' | 'PAYMENT_SUCCESS_INSCRIPTION_PENDING' | 'PAYMENT_SUCCESS_INSCRIPTION_FAILED' | 'PAYMENT_SUCCESS_INSCRIPTION_SUCCESS'

Estado combinado de las acciones de pago e inscripción.

Example response

{
  "transactions": [
    {
      "transaction": {
        "additional_data": {
          "refund": {
            "id": "re_D8kR2mV5xQ0pT7yN4wZbL1eJsH6cF3uG",
            "reason": "Cobro duplicado"
          },
          "transaction": {
            "id": "trs_7QpK4mZ0RbS2vXhTyLnE9wJdA3cF6uGx",
            "type": "PAYMENT"
          }
        },
        "amount": 19990,
        "expiration_date": "2025-03-17T14:31:58.204671Z",
        "external_id": "cobro-marzo-2025-000123",
        "gateway": "transbank_oneclick",
        "id": "trs_7QpK4mZ0RbS2vXhTyLnE9wJdA3cF6uGx",
        "id_account": "acc_gzD0XoUTFxbUFcItpWOCqN686noSd9HQ",
        "id_charge_scheduled_date": "csd_9Kq2LwZ7pR4tV1xB6nM3cH8yJ0dF5sGa",
        "id_checkout_session": "cs_bT5xN2wQ8gLpH0vYzK4mR7eJdF1sUcA3qW9tXbNv",
        "id_organization": "org_dhn3lnrfAjFyWuyEz8Q3DFaFPnzc9bXk",
        "id_payout": "pyt_L3vQ9xW1sT6yB0nZmK8pR4eJdH2cF5uG",
        "initialization_date": "2025-03-10T14:31:58.204671Z",
        "installment_amount": 1000,
        "number_of_installments": 12,
        "original_response_message": "[51] EXCEDE SALDO MAXIMO. Intente de nuevo mas tarde",
        "provider_external_id": "123456789012345678901234567890",
        "remediation_detail": "Cobro reprocesado tras corregir el medio de pago",
        "response_code": "SUTOK0000",
        "toku_product": "toku_card_on_file",
        "transaction_date": "2025-03-10T14:32:05.482913Z",
        "transaction_metadata": {
          "card_type": "credit"
        }
      }
    }
  ]
}

Changes

No recorded changes to this operation across all 2 revisions of this API.