Payment Methods

Listar Payment Methods

Changed on

Devuelve los Payment Methods de la organización autenticada, paginados y filtrados por los query params que se envíen.

Cada elemento llega en la forma agregada del Payment Method: el medio de pago, su Customer, los product_id y las Subscriptions asociadas. El header x-api-version selecciona la versión de esa forma.

total_results cuenta todos los Payment Methods que cumplen los filtros, no solo los de la página devuelta. El listado no incluye los Payment Methods eliminados. Un Payment Method cuya forma agregada no se pueda construir queda fuera de la página, aunque total_results lo siga contando.

get/payment-methods

Request

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

Query parameters

page_sizeinteger

Cantidad de Payment Methods por página.

pageinteger

Página a devolver, partiendo de 1.

id_customerstring

Devuelve solo los Payment Methods de este Customer.

Example:cus_Ht7Kd2vRq0XbNm4Y_3ZpLcJfW9Ee1AsU
id_accountstring

Devuelve solo los Payment Methods de esta Account.

Example:acc_Qw9Zx3cVb1nMk7Jh_5TyUiOpAsDfGh2L
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.

Devuelve solo los Payment Methods en este estado.

gatewaystring

Devuelve solo los Payment Methods inscritos a través de este gateway.

toku_productstring

Devuelve solo los Payment Methods inscritos con este toku_product.

external_idstring

Devuelve solo los Payment Methods con este external_id, el identificador del medio de pago en el sistema de la Organization.

Example:PM-000123
start_datestring date-time

Devuelve solo los Payment Methods inscritos desde esta fecha. Acepta YYYY-MM-DD, YYYY-MM-DD HH:MM:SS o YYYY-MM-DDTHH:MM:SS.

end_datestring date-time

Devuelve solo los Payment Methods inscritos hasta esta fecha. Acepta los mismos formatos que start_date; cuando se envía solo la fecha, el día indicado queda incluido.

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.

Response

Successful Response

total_resultsinteger required

Cantidad total de Payment Methods que cumplen los filtros, contando todas las páginas.

Changes

    • breaking

      for the query request parameter page_size, default value was changed from 10 to 50

    • breaking

      the response's body type changed from array to object for status

    • warning

      for the query request parameter page_size, the max was set to 100.00

    • warning

      for the query request parameter page, the min was set to 1.00

    • warning

      for the query request parameter page_size, the min was set to 1.00

    • info

      api operation id list-all-payment-methods-1 removed and replaced with get_payment_methods

    • info

      api tag Payment Methods added

    • info

      added the new optional header request parameter x-account-key

    • info

      added the new optional query request parameter external_id

    • info

      the query request parameter page became optional

    • info

      for the query request parameter end_date, the format was generalized from date to date-time

    • info

      for the query request parameter page, the format was generalized from int32 to no format

    • info

      for the query request parameter page_size, the format was generalized from int32 to no format

    • info

      for the query request parameter start_date, the format was generalized from date to date-time

    • info

      for the query request parameter status, the type was generalized from string to no type

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      removed the non-success response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status