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_tokenprevents 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
onSuccessfunction 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.succeededevent with the activesubscription.idwill be sent.
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,
"metadata": {},
"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.
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 |
Updated 28 days ago