Integration flow for Direct Debit

Before you can start creating charges, your user must authorize you 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. Here are the steps involved in the process:

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

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.

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>

📘

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.

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

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

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. 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"
}'

The response should look like this:

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

Charge acknowledgement

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

  • When created, charges have an initial status of pending
  • Fintoc processes charges once a day, at 2 pm Chilean time. Charges created after 2 pm CL 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.

It is very important that you 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.

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


Did this page help you?