There are two stages in the Direct Debit product:

Your user must first authorize Fintoc to debit his account. We call this authorization a Subscription.
Once the user authorize Fintoc, you can create charges to debit your user's account.

The following diagram shows how Fintoc interacts with both your backend and your frontend on both stages.

Authorization flow

Before you can start creating charges, your user must authorize Fintoc to debit their account. This authorization is what we call a Subscription. As in most of Fintoc's products, your user must go through the Widget in order to create the subscription.

There are three steps to create subscriptions using Fintoc:

On your backend, create a SubscriptionIntent using your Secret Key
Open the widget on your frontend using your Public Key
Handle post-subscription events

Create a Subscription Intent

To start the subscription process you must first create a Subscription Intent from your backend.

curl --request POST "https://api.fintoc.com/v1/subscription_intents" \
--header 'Authorization: sk_live_0000000000000000' \
--header 'Content-Type: application/json'

The response should look like this:

{
  "id": "si_m7N9rAWJS9dWDKEe",
  "object": "subscription_intent",
  "widget_token": "si_XXXXXXXX_sec_YYYYYYYY",
  "status": "created",
  "bank_account": null,
  "subscription": null,
  "business_profile": {
    "name": "Merchant Name"
  },
  "created_at": "2021-11-11T02:29:16Z"
}

Notice that the Subscription Intent includes a widget_token. This token is necessary in order to open the Widget in your applications' frontend. The next section contains more details about this.

📘
Business Profile Name
You can send the business_profile.name to customize the name to be shown as the "Recipient Company" on the widget screens.

Open the widget for Subscriptions

Once the Subscription Intent is created, you must send its widget_token to your frontend and use it to configure the widget and the workflow that the user will follow.

📘
Widget Token
The widget_token prevents your application from having to send sensitive data to Fintoc from your frontend. The token is temporary and will expire 10 minutes after its creation.

Here's an example of the widget configured with the widget_token:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Fintoc Demo</title>
    <script src="https://js.fintoc.com/v1/"></script>
  </head>
  <body>
    <script>
      window.onload = () => {
        const widget = Fintoc.create({
          holderType: 'individual',
          widgetToken: 'si_XXXXXXXX_sec_YYYYYYYY',
          product: 'subscriptions',
          publicKey: 'pk_live_0000000000',
          onSuccess: () => {},
        };
        widget.open();
      });
      </script>
  </body>
</html>

❗️
Use the Widget callbacks and events correctly
Never use the onSuccess, onExit or onEvent callbacks to get the state of the Subscription being created. You should only use these callbacks to handle the flow of your frontend application, while waiting backend confirmation via Webhooks. Frontend events can also be used to generate metrics about general widget usage, but you should never rely solely on them to assume a Subscription was created or failed to be created.

To read more about the widget and its configuration, head over to the widget section.

Handle post-subscription events

Once a Subscription Intent finishes, you handle the subscription result in your frontend and complete the subscription in your backend. For your frontend you will use the widget callback, and for your backend you will use the events sent by webhooks.

Handle the subscription result on your frontend

Once a Subscription Intent finishes successfully, the widget executes the onSuccess callback. You need to pass this function to the widget upon creation.

With this callback, you can decide what to do with your user's frontend once the subscription is complete, for example:

Redirect the user to a post-subscription view
Show the user a success screen.

Handle errors

You don't only need to handle the succeeded case because subscriptions can also fail. For example, your customer left the process before completing the subscription.

When a subscription fails or is rejected by your customer, the widget executes the onExit callback. With this callback, you can handle errors on your frontend. For example, you can invite your customer to use retry the process.

Store the created subscription

To receive notifications about the subscription process, you must first have created a Webhook Endpoint using Fintoc and assign to it the events that you want to receive.

It is very important that you subscribe to the subscription_intent.succeeded event. Also you must store the included subscription_id in a safe place you can access later. The subscription_id is needed in order to create Charges later on.

The subscription process may generate 3 different events that are sent to your webhook endpoint:

Event	Description
`subscription_intent.succeeded`	Event that triggers when a subscription intent is validated as successful. The `subscription_intent` includes the resulting `subscription` object.
`subscription_intent.failed`	Event that triggers when a subscription intent fails due to a problem with the bank or Fintoc.
`subscription_intent.rejected`	Event that triggers when a subscription intent is rejected by the user. This may happen when the user rejects the MFA step or if it is entered incorrectly.

📘
Backend's webhook vs widget's onSuccess
It is very important for you to wait for the webhook event on your backend to finish the process. You should never finish the flow solely based on the onSuccess function from the widget. Some users may close the widget before the callback to send the webhook to your backend gets executed.

Wait for subscription activation

The created subscription starts with a pending status. This indicates that the subscription was created correctly but charges can not be created yet. First, Fintoc needs the bank to confirm that the subscription is operational.

A new subscription can take up to 3 business days for it to be operational. Once a subscription is validated as ready to receive charges, a subscription.activated event is triggered and sent via webhooks.

If for any reason the bank informs Fintoc that a subscription has been canceled, a subscription.canceled event will be triggered

Event	Description
`subscription.activated`	Event that triggers when the bank has confirmed that the subscription is ready to accept charges.
`subscription.canceled`	Event that triggers when the bank informs Fintoc that the subscription has been canceled.

📘
What happens when the user creates a new Subscription Intent with the same bank account?
Every flow checks for previous subscriptions created between the user and your organization. If already exists and is active, users see a successful screen as a confirmation and the subscription_intent.succeeded event with the active subscription.id will be sent.

Charge flow

Create a Charge

Fintoc uses the Charge object to represent a subscription payment.

From your backend, create a Charge with the amount, currency, and the subscription_id you got in the authorization step. You can also add the business_profile object for category-based billing. Here's an example:

curl --request POST "https://api.fintoc.com/v1/charges" \
--header 'Authorization: sk_live_xxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount": 1000,
  "currency": "CLP",
  "subscription_id": "xxxxxxxxx",
  "business_profile": {
    "name": "Merchant Name",
    "tax_id": "967224006",
    "category": "611090"
  }
}'

The response should look like this:

{
  "id": "ch_m7N9rAWJS9dWDKEe",
  "object": "charge",
  "amount": 1000,
  "currency": "CLP",
  "status": "pending",
  "failure_code": null,
  "metadata": {},
  "created_at": "2021-11-11T02:29:16Z",
}

Charge acknowledgment

A charge can take up to 2 business days before having acknowledgment of its success or failure:

When created, charges have an initial status of pending
Fintoc processes charges once a day at 2 pm. When this happens, the charge transitions to in_progressand can no longer be canceled. Charges created after 2pm (CL time) are processed on the next business day
During the following 2 business days, the charge transitions to either succeeded or failed depending on the user's bank.
Your user sees the charge reflected on their bank statement 1 business day after the charge is created. Your user will know if the charge succeeds before the bank notifies Fintoc.
Charges are transferred to your bank account the next business day after they transitioned to a successful state.

Failures can happen for a number of reasons, such as insufficient funds, the charged amount being higher than the authorized amount, or the customer disabling the authorization from their bank account.

Charges Webhooks

Once the charge is completed, we will send you an event with charge as its type using a webhook.

To subscribe to the event, you must first have created a Webhook Endpoint using Fintoc and assign to it the events that you want to receive.

You must subscribe to these events, as you can use them to identify successful charges from failed ones.

Event	Description
`charge.succeeded`	Event that triggers when a charge is validated as successful.
`charge.failed`	Event that triggers when a charge fails due to insufficient funds, the charged amount being higher than the authorized amount, or the user disabling the authorization.

📘
Charge Succeeded vs Funds transfer
A charge is marked as succeeded when the bank confirms Fintoc that the user has already been charged by the specified amount. This does not mean that those funds are already on your organizations' account. Fintoc has 1 business day to transfer that money to your account.

Receiving funds in your account

Once you create a charge to your user's account, it'll take 3 to 4 business days to be available in your bank account. This depends mainly if the charge is created before/after banking schedule hour. The basic timing schedule is:

Let's see an example of a charge created at 11:00 AM, before the banking cutting hour (02:00 PM):

Now, let's see another example of a charge created at 09:00 PM, after the banking cutting hour (02:00 PM):

Available Banks

Nombre	id
Banco de Chile	`cl_banco_de_chile`
Banco Scotiabank	`cl_banco_scotiabank`
Banco Itaú	`cl_banco_itau`
Banco Bci	`cl_banco_bci`
Banco Falabella	`cl_banco_falabella`
Banco Santander	`cl_banco_santander`
Banco Estado	`cl_banco_estado`

Integration flow

Authorization flow

Create a Subscription Intent

📘
Business Profile Name

Open the widget for Subscriptions

📘
Widget Token

❗️
Use the Widget callbacks and events correctly

Handle post-subscription events

Handle the subscription result on your frontend

Handle errors

Store the created subscription

📘
Backend's webhook vs widget's onSuccess

Wait for subscription activation

📘
What happens when the user creates a new Subscription Intent with the same bank account?

Charge flow

Create a Charge

Charge acknowledgment

Charges Webhooks

📘
Charge Succeeded vs Funds transfer

Receiving funds in your account

Available Banks

Authorization flow

Create a Subscription Intent

📘Business Profile Name

Open the widget for Subscriptions

📘Widget Token

❗️Use the Widget callbacks and events correctly

Handle post-subscription events

Handle the subscription result on your frontend

Handle errors

Store the created subscription

📘Backend's webhook vs widget's onSuccess

Wait for subscription activation

📘What happens when the user creates a new Subscription Intent with the same bank account?

Charge flow

Create a Charge

Charge acknowledgment

Charges Webhooks

📘Charge Succeeded vs Funds transfer

Receiving funds in your account

Available Banks

📘
Business Profile Name

📘
Widget Token

❗️
Use the Widget callbacks and events correctly

📘
Backend's webhook vs widget's onSuccess

📘
What happens when the user creates a new Subscription Intent with the same bank account?

📘
Charge Succeeded vs Funds transfer