Upgrade your API version

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. 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.

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.

1. Find your current API version

Go to the Fintoc Dashboard 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, and deploy the handler before you request the upgrade. For example, read the payment methods of a checkout session in either shape:

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"]]

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 and send Fintoc-Version: 2026-02-01 on every request, to both v1 and v2 endpoints:

Requests

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.

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.

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:

Server (Python)

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.

5. Test your changes

Test your changes with your test API keys:

Send your v1 and v2 requests with Fintoc-Version: 2026-02-01 and confirm your code handles the new response shapes.
Test your webhook handler with sample payloads in both shapes from step 2.

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

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.

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 and to events you list or 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.

Home

Resources

Payments

Business Accounts

Movements

Skeleton group medium 9

Upgrade your API version

1. Find your current API version

2. Review the changes

3. Prepare your webhook handler

4. Adapt your requests

5. Test your changes

6. Request the upgrade

7. Clean up your integration

Home

Resources

Payments

Business Accounts

Movements

Skeleton group medium 9

​1. Find your current API version

​2. Review the changes

​3. Prepare your webhook handler

​4. Adapt your requests

​5. Test your changes

​6. Request the upgrade

​7. Clean up your integration

1. Find your current API version

2. Review the changes

3. Prepare your webhook handler

4. Adapt your requests

5. Test your changes

6. Request the upgrade

7. Clean up your integration