---
title: "Actualizar Payment Method"
method: PUT
path: "/payment-methods"
tags: ["Payment Methods"]
---

# Actualizar Payment Method

`PUT /payment-methods`

## Request

- Base URL: `https://api.trytoku.com`
- URL: `https://api.trytoku.com/payment-methods`
- Auth: API key in header `x-api-key`

Actualiza un Payment Method existente.

El Payment Method se identifica con `id_payment_method` dentro del cuerpo de la petición. La respuesta solo confirma que la actualización se ejecutó: no devuelve el Payment Method resultante.

## Request body

- UpdatePaymentMethodInterface
  - `additional_metadata_tables` union[]
    - union
      - string
      - string
  - `asynchronous` boolean
  - `exclude_from_recurring` boolean
  - `external_id` string
  - `force_status_change` boolean
  - `id_bulk_insertion` string
  - `id_customer` integer
  - `id_payment_method` integer, required
  - `id_subscriptions` integer[]
  - `only_append_subscriptions` boolean
  - `original_response_code` string
  - `original_response_message` string
  - `payment_method_data` object
  - `payment_scope` 'SUBSCRIPTION' | 'CUSTOMER': Qué deudas puede pagar un medio de pago. `SUBSCRIPTION` lo ata a las Subscriptions con las que se inscribió y solo paga deudas de esas Subscriptions. `CUSTOMER` lo ata al Customer y paga cualquier deuda suya, venga de la Subscription que venga.
  - `provider_external_id` string
  - `status` 'deleted' | 'initialized' | 'chargeable' | 'temporary_failed' | 'permanent_failed' | 'three_ds_required' | 'inscription_failed' | 'pending_activation' | 'manually_chargeable' | 'permanent_deletion_in_progress' | 'permanently_deleted' | 'finished' | 'cancelled' | 'pending_deletion': Estado de un medio de pago dentro de su ciclo de vida, desde que se inscribe hasta que se da de baja. Es lo que decide si se le puede cobrar. Se cobra con `chargeable` y también con `temporary_failed`: este último es un cobro que falló por una causa reintentable, así que el motor de cobranza lo sigue tomando. `permanent_failed` queda fuera, aunque la Organization puede configurar que un porcentaje de ellos se reintente igual. `manually_chargeable` solo entra cuando el cobro se dispara a mano; las corridas automáticas lo saltan. La inscripción pasa por `initialized` mientras Toku la procesa, y queda en `pending_activation` cuando terminó de su lado pero falta la confirmación del banco o del proveedor. Si la inscripción misma falla queda en `inscription_failed`, que ya no vuelve a ser cobrable. La baja tiene dos caminos. El lógico conserva el historial del medio de pago: `pending_deletion` es una eliminación diferida, en espera de que terminen los cobros en curso, y `deleted` es la eliminación ya aplicada. El otro camino borra los datos de la tarjeta en el proveedor al cumplirse el plazo de retención, y avanza de `permanent_deletion_in_progress` a `permanently_deleted` cuando el borrado queda confirmado. `finished` y `cancelled` cierran los cobros recurrentes de Pix en Brasil: el primero es que la serie de cobros se completó y el segundo que se canceló antes de completarse. `three_ds_required` es un estado heredado que ya no se usa.
  - `toku_response_code` string
  - `unique_internal_id` string: Clave de deduplicación, para los flujos que la conocen recién al finalizar. Solo se escribe si el medio de pago todavía no tiene una y ninguna otra fila viva la ocupa.
  - `wait_for_result_payment_instrument` boolean

## Response `200`

Successful Response

- ApiPaymentMethodBaseResponse: Confirmación genérica de una operación sobre un Payment Method.
  - `detail` union: Detalle de la operación. Trae los identificadores generados cuando la operación creó algo, un mensaje cuando quedó agendada para procesarse de forma asíncrona, y el motivo del rechazo cuando `success` es `false`.
    - object
    - string
  - `success` boolean, required: Es `true` cuando la operación se ejecutó sin errores.

## Other responses

- `400`: El cambio de estado pedido no está permitido desde el estado actual.
- `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.

## Changes

- **2026-11-03** `a6ef070075b1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/trytoku/apis/toku-api/changes/payment-methods/put.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)