> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade your API version

> Move your account to the latest API version without breaking your existing integration.

Move your account to API version `2026-02-01` without breaking your existing integration.

Fintoc pins your account to an API version and applies that version to every request that does not send the `Fintoc-Version` header. The header always takes precedence over the pinned version. For more details, see [API version](/api/fintoc-api/authentication#api-version).

The upgrade changes the shape of request bodies, response bodies, and webhook events, but does not change your API keys, webhook endpoints, or webhook signature verification.

<Note>
  Use this guide to upgrade your account's API version. The guide does not cover moving from v1 endpoints to v2 endpoints. Some v1 and v2 endpoints work differently, such as `/v1/payment_intents` and `/v2/payment_intents`. To use a v2 endpoint, see its API reference.
</Note>

## 1. Find your current API version

Go to the [Fintoc Dashboard](https://dashboard.fintoc.com) and open **your organization name** (top left) > **Settings** > **Company profile** > **API Version**.

If your version is `2026-02-01`, your account already uses the latest version and you can skip this guide.

## 2. Review the changes

Version `2026-02-01` introduces the following changes. They affect your v1 requests, your v2 requests, and your webhook events:

| Object | Before `2026-02-01` | Starting in `2026-02-01` |
| - | - | - |
| `CheckoutSession` | The payment methods field is `payment_methods`. | The payment methods field is `payment_method_types`. |
| `CheckoutSession` | Payment method values are `payment_intent`, `installments_payment`, `card`, and `cash`. | Payment method values are `bank_transfer`, `installments`, `card`, and `cash`. |
| `CheckoutSession` | `payment_method_options` keys are `payment_intent`, `installments_payment`, `card`, and `cash`. | `payment_method_options` keys are `bank_transfer`, `installments`, `card`, and `cash`. |
| `PaymentIntent` | `sender_account` is `null` when Fintoc only knows the sender's bank. | `sender_account` contains the `institution_id` of the sender's bank, with `holder_id`, `number`, and `type` set to `null`. |

The renames apply to request bodies, response bodies, and error messages.

If your account is pinned to `2023-11-15`, the changes in version `2025-08-13` also apply to you:

| Object | Before `2025-08-13` | Starting in `2025-08-13` |
| - | - | - |
| `Movement` | The object has no `status` field. | The object includes a `status` field. |
| `Movement` | `GET /v1/accounts/{id}/movements` returns only confirmed movements, regardless of the `confirmed_only` value you send. | `GET /v1/accounts/{id}/movements` returns only confirmed movements unless you send `confirmed_only=false`. |

## 3. Prepare your webhook handler

Webhook events do not carry the `Fintoc-Version` header. Fintoc serializes every event with your account's pinned version, so `checkout_session.*` and `payment_intent.*` events change shape when your account moves to `2026-02-01`.

Update your webhook handler to accept both shapes described in [step 2](#2-review-the-changes), and deploy the handler before you request the upgrade. For example, read the payment methods of a checkout session in either shape:

<CodeGroup>
  ```javascript Webhook handler (Node.js) theme={null}
  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);
  }
  ```

  ```python Webhook handler (Python) theme={null}
  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"]]
  ```
</CodeGroup>

Apply the same mapping to the keys of `payment_method_options`. For `payment_intent.*` events, accept a `sender_account` that contains the `institution_id` of the sender's bank, with `holder_id`, `number`, and `type` set to `null`.

## 4. Adapt your requests

Update your code to the changes in [step 2](#2-review-the-changes) and send `Fintoc-Version: 2026-02-01` on every request, to both v1 and v2 endpoints:

```text Requests theme={null}
Fintoc-Version: 2026-02-01
```

You can adapt your requests one endpoint at a time. Requests without the header keep using your current version until the upgrade.

<Note>
  While your account is pinned to an earlier version, the v2 Checkout Session, Payment Intent, and Setup Intent endpoints return a `404 Not Found` error with code `unrecognized_request` unless you send the header.
</Note>

If you use `fintoc-python`, set the version on the client. The client sends the header with each request, so use one client per version while you adapt your integration:

```python Server (Python) theme={null}
from fintoc import Fintoc

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

`fintoc-node` does not send the `Fintoc-Version` header. If you use `fintoc-node`, send the requests you adapt with an HTTP client, such as `fetch`, and include your secret key in the `Authorization` header and `Fintoc-Version: 2026-02-01`. Keep the rest of your requests in `fintoc-node` until the upgrade, and update your code to accept both shapes from [step 2](#2-review-the-changes).

## 5. Test your changes

Test your changes with your `test` API keys:

1. Send your v1 and v2 requests with `Fintoc-Version: 2026-02-01` and confirm your code handles the new response shapes.
2. Test your webhook handler with sample payloads in both shapes from [step 2](#2-review-the-changes).

Your `test` webhook events keep your current version until the upgrade, so you cannot receive events in the new shape before you request it.

## 6. Request the upgrade

<Warning>
  After the upgrade, a v1 request that sends `payment_methods` without the `Fintoc-Version` header does not fail. Fintoc ignores `payment_methods` and the checkout session defaults to `bank_transfer`. Adapt every request before you upgrade, or send `Fintoc-Version` with your previous version on requests you have not adapted yet.
</Warning>

Ask your Fintoc account representative or Fintoc support to upgrade your account to `2026-02-01`. The upgrade applies to `test` and `live` modes at once.

After the upgrade, requests without the `Fintoc-Version` header use `2026-02-01`, and Fintoc sends webhook events in the new shape.

## 7. Clean up your integration

Remove any `Fintoc-Version: 2026-02-01` headers from your requests. Your account already uses `2026-02-01`, so those headers no longer change the version. If some requests still send `Fintoc-Version` with your previous version, adapt those requests and then remove the header too.

Fintoc keeps the previous shape for `checkout_session.*` events created before the upgrade. This behavior applies to [retries](/guides/resources/webhooks-walkthrough/webhooks-creating-guide#handle-retries-and-failed-deliveries) and to events you [list](/api/main-resources/events-reference/events-list) or [get](/api/main-resources/events-reference/events-get). Remove support for the previous shape from your webhook handler once those retries end. Keep support for the previous shape in code that reads events created before the upgrade.