Actualiza tu versión de la API

Cambia tu cuenta a la versión 2026-02-01 de la API sin romper tu integración actual. Fintoc fija tu cuenta en una versión de la API y aplica esa versión a cada solicitud que no envía el header Fintoc-Version. El header siempre tiene prioridad sobre la versión fijada. Para más detalles, revisa Versión de la API. La actualización cambia la forma del cuerpo de las solicitudes, de las respuestas y de los eventos de webhook, pero no cambia tus API keys, tus webhook endpoints ni la verificación de la firma de los webhooks.

Usa esta guía para actualizar la versión de la API de tu cuenta. La guía no cubre el paso de endpoints v1 a endpoints v2. Algunos endpoints v1 y v2 funcionan distinto, como /v1/payment_intents y /v2/payment_intents. Para usar un endpoint v2, revisa su referencia de la API.

1. Encuentra tu versión actual de la API

Ve al Dashboard de Fintoc y entra a nombre de tu organización (arriba a la izquierda) > Configuración > Perfil de empresa > Versión API. Si tu versión es 2026-02-01, tu cuenta ya usa la última versión y no necesitas seguir esta guía.

2. Revisa los cambios

La versión 2026-02-01 trae los siguientes cambios. Afectan a tus solicitudes a v1, a tus solicitudes a v2 y a tus eventos de webhook:

Objeto	Antes de `2026-02-01`	Desde `2026-02-01`
`CheckoutSession`	El campo de métodos de pago es `payment_methods`.	El campo de métodos de pago es `payment_method_types`.
`CheckoutSession`	Los valores de método de pago son `payment_intent`, `installments_payment`, `card` y `cash`.	Los valores de método de pago son `bank_transfer`, `installments`, `card` y `cash`.
`CheckoutSession`	Las keys de `payment_method_options` son `payment_intent`, `installments_payment`, `card` y `cash`.	Las keys de `payment_method_options` son `bank_transfer`, `installments`, `card` y `cash`.
`PaymentIntent`	`sender_account` es `null` cuando Fintoc solo conoce el banco del pagador.	`sender_account` contiene el `institution_id` del banco del pagador, con `holder_id`, `number` y `type` en `null`.

Los cambios de nombre aplican al cuerpo de las solicitudes y respuestas, y a los mensajes de error. Si tu cuenta está fijada en 2023-11-15, también te aplican los cambios de la versión 2025-08-13:

Objeto	Antes de `2025-08-13`	Desde `2025-08-13`
`Movement`	El objeto no tiene el campo `status`.	El objeto incluye el campo `status`.
`Movement`	`GET /v1/accounts/{id}/movements` retorna solo movimientos confirmados, sin importar el valor de `confirmed_only` que envíes.	`GET /v1/accounts/{id}/movements` retorna solo movimientos confirmados, salvo que envíes `confirmed_only=false`.

3. Prepara tu webhook handler

Los eventos de webhook no llevan el header Fintoc-Version. Fintoc serializa cada evento con la versión fijada en tu cuenta, así que los eventos checkout_session.* y payment_intent.* cambian de forma cuando tu cuenta pase a 2026-02-01. Ajusta tu webhook handler para que acepte ambas formas descritas en el paso 2 y despliega el handler antes de pedir la actualización. Por ejemplo, lee los métodos de pago de una checkout session en cualquiera de las dos formas:

const LEGACY_TO_NEW = {
  payment_intent: 'bank_transfer',
  installments_payment: 'installments',
};

function paymentMethodTypes(checkoutSession) {
  if (checkoutSession.payment_method_types) {
    return checkoutSession.payment_method_types;
  }

  return checkoutSession.payment_methods.map((pm) => LEGACY_TO_NEW[pm] ?? pm);
}

LEGACY_TO_NEW = {
    "payment_intent": "bank_transfer",
    "installments_payment": "installments",
}

def payment_method_types(checkout_session):
    if "payment_method_types" in checkout_session:
        return checkout_session["payment_method_types"]

    return [LEGACY_TO_NEW.get(pm, pm) for pm in checkout_session["payment_methods"]]

Aplica la misma conversión a las keys de payment_method_options. Para los eventos payment_intent.*, acepta un sender_account que contiene el institution_id del banco del pagador, con holder_id, number y type en null.

4. Adapta tus solicitudes

Actualiza tu código a los cambios del paso 2 y envía Fintoc-Version: 2026-02-01 en cada solicitud, tanto a endpoints v1 como v2:

Solicitudes

Fintoc-Version: 2026-02-01

Puedes adaptar tus solicitudes un endpoint a la vez. Las solicitudes sin el header siguen usando tu versión actual hasta la actualización.

Mientras tu cuenta esté fijada en una versión anterior, los endpoints v2 de Checkout Session, Payment Intent y Setup Intent responden con un error 404 Not Found con código unrecognized_request si no envías el header.

Si usas fintoc-python, define la versión en el cliente. El cliente envía el header en cada solicitud, así que usa un cliente por versión mientras adaptas tu integración:

Server (Python)

from fintoc import Fintoc

client = Fintoc('YOUR_TEST_SECRET_KEY', api_version='2026-02-01')

fintoc-node no envía el header Fintoc-Version. Si usas fintoc-node, envía las solicitudes que adaptes con un cliente HTTP, como fetch, e incluye tu secret key en el header Authorization y Fintoc-Version: 2026-02-01. Mantén el resto de tus solicitudes en fintoc-node hasta la actualización, y ajusta tu código para que acepte ambas formas del paso 2.

5. Prueba tus cambios

Prueba tus cambios con tus API keys de test:

Envía tus solicitudes a v1 y v2 con Fintoc-Version: 2026-02-01 y confirma que tu código procesa la nueva forma de las respuestas.
Prueba tu webhook handler con payloads de ejemplo en ambas formas del paso 2.

Tus eventos de webhook de test mantienen tu versión actual hasta la actualización, así que no puedes recibir eventos con la nueva forma antes de pedirla.

6. Pide la actualización

Después de la actualización, una solicitud a v1 que envía payment_methods sin el header Fintoc-Version no falla. Fintoc ignora payment_methods y la checkout session usa bank_transfer por defecto. Adapta todas tus solicitudes antes de actualizar, o envía Fintoc-Version con tu versión anterior en las solicitudes que todavía no adaptas.

Pídele a tu ejecutivo de Fintoc o a soporte que actualicen tu cuenta a 2026-02-01. La actualización aplica a los modos test y live a la vez. Después de la actualización, las solicitudes sin el header Fintoc-Version usan 2026-02-01 y Fintoc envía los eventos de webhook con la nueva forma.

7. Limpia tu integración

Quita los headers Fintoc-Version: 2026-02-01 de tus solicitudes. Tu cuenta ya usa 2026-02-01, así que esos headers ya no cambian la versión. Si algunas solicitudes todavía envían Fintoc-Version con tu versión anterior, adapta esas solicitudes y luego quita también el header. Fintoc mantiene la forma anterior de los eventos checkout_session.* creados antes de la actualización. Esto aplica a los reintentos y a los eventos que listas u obtienes. Quita el soporte para la forma anterior de tu webhook handler cuando terminen esos reintentos. Mantén el soporte para la forma anterior en el código que lea eventos creados antes de la actualización.

Inicio

Recursos

Pagos

Business Accounts

Movimientos

Skeleton group medium 9

Actualiza tu versión de la API

1. Encuentra tu versión actual de la API

2. Revisa los cambios

3. Prepara tu webhook handler

4. Adapta tus solicitudes

5. Prueba tus cambios

6. Pide la actualización

7. Limpia tu integración

Inicio

Recursos

Pagos

Business Accounts

Movimientos

Skeleton group medium 9

​1. Encuentra tu versión actual de la API

​2. Revisa los cambios

​3. Prepara tu webhook handler

​4. Adapta tus solicitudes

​5. Prueba tus cambios

​6. Pide la actualización

​7. Limpia tu integración

1. Encuentra tu versión actual de la API

2. Revisa los cambios

3. Prepara tu webhook handler

4. Adapta tus solicitudes

5. Prueba tus cambios

6. Pide la actualización

7. Limpia tu integración