There are three steps to accept recurring payments using Fintoc:

On your backend, create a Checkout Session with flow: subscription
Redirect your user to complete the enrollment at the Fintoc-hosted checkout page
Handle post-enrollment and recurring payment events (webhooks)

The following diagram shows how Fintoc interacts with both your backend and your frontend:

Create a Session

The Checkout Session object represents your intent to enroll a payment method for recurring charges (PAC), and to create a subscription with a fixed amount and periodicity.

Using your Secret Key, create a Checkout Session on your backend with flow set to subscription.

curl --request POST "https://api.fintoc.com/v2/checkout_sessions" \
  --header "Authorization: YOUR_TEST_SECRET_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "flow": "subscription",
    "amount": 350000,
    "currency": "CLP",
    "success_url": "https://merchant.com/success",
    "cancel_url": "https://merchant.com/987654321",
    "payment_method_types": [
      "pac"
    ],
    "customer_data": {
      "tax_id": {
        "type": "cl_rut",
        "value": "12088191"
      },
      "name": "Felipe Castro",
      "email": "[email protected]",
      "metadata": {}
    },
    "line_items": [
      {
        "price_data": {
          "currency": "CLP",
          "unit_amount": 350000,
          "product_data": {
            "name": "SoyFocus plan"
          },
          "recurring": {
            "interval": "month",
            "interval_count": 1
          }
        },
        "quantity": 1
      }
    ],
    "metadata": {
      "subscription_external_id": "sub_987654321"
    }
  }'

const { Fintoc } = require('fintoc');

const fintoc = new Fintoc('YOUR_SECRET_KEY');

const checkoutSession = await fintoc.checkoutSessions.create({
  amount: 1000,
  currency: 'mxn',
  customer_email: '[email protected]'
});

from fintoc import Fintoc

client = Fintoc('YOUR_TEST_SECRET_API_KEY')

checkout_session = client.checkout_sessions.create(
  amount=1000,
  currency='clp',
  customer_email='[email protected]'
)

require 'net/http'
require 'uri'
require 'json'

checkout_session = {
  amount: 1000,
  currency: 'clp',
  customer_email: '[email protected]'
}

uri = URI("https://api.fintoc.com/v1/checkout_sessions")

header = {
  Accept: 'application/json', Authorization: 'YOUR_TEST_SECRET_API_KEY'
}

http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri, header)
request.body = checkout_session.to_json

response = http.request(request)

Parameter	Example	Description
`amount`	2476	Amount of money that needs to be paid. It's represented as integer with no decimals in the smallest possible unit of the currency you are using. If your payment uses Chilean peso, an amount of CLP 2476 is represented as 2476. If your payment uses Mexican peso, an amount of MXN 24.76 is represented as 2476. Read here to learn more.
`currency`	CLP	Currency that is being used for the recurring payments. Currently Fintoc only supports CLP.
`flow`	`subscription`	Required type of the flow for the session. The types available are `payment`, `setup` and `subscription`
`success_url`	`https://merchant.com/success`	Required URL to redirect the user in case of payment succeeded.
`cancel_url`	`https://merchant.com/987654321`	Required URL to redirect the user in case they decide to cancel the payment and return to your website.
`customer`	`cus_alm1321knjl1233`	Id of an already created customer. One of `customer` or `customer_data` is required.
`customer_data`	`(object)`	Data for inline customer creation. One of `customer` or `customer_data` is required.
`payment_method_types`	`["pac"]`	Optional list of allowed payment methods during enrollment. pac represents charges on a banking account.
`line_items`	`(array)`	Required subscription items.
`metadata`	`{"order": "987654321"}`	Optional set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

Include Customer Data (Required for subscriptions)

When creating a Checkout Session with flow: subscription, you must include customer information. You can do this either by referencing an existing customer ID (customer) or by sending customer_data to create one inline:

Attribute	Type	Description
`tax_id`	`object`	Required object that identifies the customer at a fiscal or regulatory level. It includes a `type` field indicating the format or country-specific identifier (for example, "`cl_rut`" for Chilean RUT) and a `value` field containing the actual tax identification number as a string.
`name`	`string`	Optional full name of the customer.
`email`	`string`	Optional customer email linked to a Checkout Session. This is used to notify a user in case of a refund.
`metadata`	`object`	Optional custom data that can store additional information about the customer (e.g., internal IDs, CRM references, or tags)

Include a Items list (Required for subscriptions)

When creating a Checkout Session, you can also include information about session items. This enables Fintoc to display this information on the checkout page and show only the payment methods available for specific products.

Attribute	Type	Description
`quantity`	`integer`	Requirednumber of units of this item being purchased.
`price_data`	`object`	Data used to generate a new recurring price inline. One of price or price_data is required.

Each line_item needs one of price_data or price.

price_data Object

Attribute	Type	Description
`product_data`	`object`	Data used to generate a new Product object inline. One of product or product_data is required.
`currency`	string	Currency used for the subscription. We currently only support CLP.
`unit_amount`	`integer`	Required price per unit of the item, expressed in the smallest currency unit (e.g., CLP without decimals).
`recurring`	`(object)`	Required recurring configuration (e.g. interval: month, interval_count: 1).

product_data Object

Attribute	Type	Description
`name`	`string`	Required name of the product or service being purchased.

Response when creating a Checkout Session

After making the request to create the Checkout Session, Fintoc should respond with something like this:

{
  "id": "cs_li5531onlFDi235",
  "flow": "subscription",
  "customer": {
      "name": "Felipe Castro",
      "email": "[email protected]",
      "metadata": {},
      "tax_id": {
        "type": "cl_rut",
        "value": "12088191"
      }
    },
  "line_items": [
    {
      "price": {
        "product": {
          "name": "Plan A",
          "description": "Pago recurrente monto fijo"
        },
        "currency": "CLP",
        "unit_amount": 350000,
        "recurring": {
          "interval": "month",
          "interval_count": 1
        }
      },
      "quantity": 1
    }
  ],
  "success_url": "https://merchant.example/success",
  "cancel_url": "https://merchant.example/cancel",
  "redirect_url": "https://pay.fintoc.com/checkout/cs_123"
}

In the response, you should receive the url attribute. In the following step, you'll use this attribute to redirect the user to complete the subscription.

Redirect the user to complete the payment

Next, you will redirect users to the Fintoc Checkout page. After completing the payment, they'll be automatically redirected back to your site.

Based on the result, the user will be redirected to either the success or cancel URL.

Handle post-session events

Once a Checkout Session finishes, you handle the result in your frontend and complete the subscription in your backend. For your backend, you will use the events sent by webhooks.

Complete the subscription on your backend

Fintoc sends a checkout_session.finished event when the session completes.

In a subscription flow, this event includes information about the session and references to the subscription and payment_method created during enrollment.

{
  "id": "evt_a4xK32BanKWYn",
  "object": "event",
  "type": "checkout_session.finished",
  "data": {
    "id": "cs_li5531onlFDi235",
    "flow": "subscription",
    "customer": {
      "name": "Felipe Castro",
      "email": "[email protected]",
      "metadata": {},
      "tax_id": {
        "type": "cl_rut",
        "value": "12088191"
      }
    },
    "payment_method_types": ["pac"],
    "status": "finished",
    "payment_status": "succeeded",
    "subscription": "sub_NffrFeUfNV2Hib",
    "payment_method": "pm_NffrFeUfNV2Hib"
  }
}

You should handle the following post-session events :

Event	Description	Action
`checkout_session.finished`	Sent when an subscription Checkout Session reaches a final state	Activate the subscription on your side based on the final status, and store the created ids (`subscription`, `payment_method`, `customer`).
`checkout_session.expired`	Sent when a session expires	Offer the customer another attempt to subscribe.
`payment_intent.succeeded`	Sent when a payment intent succeeds, like a charge on a bank account or card.	Confirm to your customer that the charge of the subscription was successfully done
`payment_intent.failed`	Sent when a payment intent fails	Offer the customer another attempt to pay the subscription.

Test your integration (Coming soon)

To confirm that your integration works correctly, you can simulate subscriptions and scheduled recurring payments without moving any money

1) Create a subscription Checkout Session using test users credencials

Using your test mode API Secret Key, create a Checkout Session of flow: subscription on your backend and complete the subscription enrollment flow on the fintoc-hosted page using the following credentials:

Test credentials

Username (RUT): 41614850-3
Password: jonsnow

2) Handle simulated scheduled payments of the subscription

In test mode, once the subscription is created, Fintoc will immediately trigger successful and failed payment intents, allowing you to test the handling of all post-session events.