To start using Fintoc's Payment Initiation API, you just need to create an account on our Dashboard and follow these five steps:

1. Get your test API Keys
2. Create a Payment Intent
3. Open the Widget
4. Handle post-payments events
5. Make your first payment

Step 1: Get your test API Keys

Every interaction with the Fintoc API must be authenticated with the API Keys of your Fintoc account. If an interaction with the API does not include your API Key or includes an incorrect API Key, Fintoc will return an error.

Every Fintoc account has two key pairs: one corresponds to the test mode, while the other corresponds to the actual API environment. Every resource is stored either in test mode or in live mode, and resources from one environment cannot be manipulated by resources from the other environment.

Your API Keys will be available in the Dashboard. First you need to create an account on the Fintoc Dashboard. Once your Fintoc account has been created, you will be able to get your API Keys. In this case, you must use the Public Key and Secret Key from test mode. To easily identify them, we added the prefix pk_test_ and sk_test_, respectively.

Step 2: Create a Payment Intent

Using your test Secret Key, create a Payment Intent from your backend with the amount and currency of the payment. Always create the Payment Intent from your backend, or a malicious user could alter any of those fields.

If you plan on using the Refunds product, you must include a customer_email in the Payment Intent request.

Here's an example of creating a Payment Intent for Chile:

curl --request POST "https://api.fintoc.com/v1/payment_intents" \
-- header 'Authorization: YOUR_SECRET_API_KEY' \
-- header 'Content-Type: application/json' \
--data-raw '{
  "amount": 2476,
  "currency": "CLP",
  "customer_email":"[email protected]"
}'

const fetch = require('node-fetch');

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

fetch('https://api.fintoc.com/v1/payment_intents', {
  	method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'YOUR_SECRET_API_KEY'
    },
    body: JSON.stringify(payment_intent),
  },
)

import requests

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

headers = {
  'Accept': 'application/json', 'Authorization': 'YOUR_SECRET_API_KEY'
}

r = requests.post(
  'https://api.fintoc.com/v1/payment_intents',
  json=payment_intent,
  headers=headers
)

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

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

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

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

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

response = http.request(request)

If you want to create a Payment Intent for Mexico, change the currency to MXN.

🚧

Currencies are represented as integers

The Fintoc API represents currencies in its smallest possible units with no decimals (as an integer). That means that an amount of MXN 10.29 gets represented by Fintoc as 1029. You can read more about currencies here.

The response should look like this:

{
  "id": "pi_BO381oEATXonG6bj",
  "object": "payment_intent",
  "amount": 1000,
  "currency": "CLP",
  "widget_token": "pi_BO381oEATXonG6bj_sec_a4xK32BanKWYn",
  "status": "created",
  "metadata": {},
  "reference_id": null,
  "recipient_account": {
    "holder_id": "183917137",
    "number": "123456",
    "type": "checking_account",
    "institution_id": "cl_banco_de_chile"
  },
  "sender_account": null,
  "created_at": "2021-10-15T15:23:11.474Z",
}

Step 3: Open the Widget

Your new created PaymentIntent should contain the widget_token attribute. You must use that attribute and your test Public Key to set up the widget and the user's workflow.

📘

The widget token is temporary

The widget_token is temporary and will expire 10 minutes after its creation.

Here's an example of how you can open the widget with your Public Key andwidget_token configured for a Chilean payment:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta name="viewport" content="width=device-width,initial-scale=1.0, maximum-scale=1.0">
    <title>Fintoc Demo</title>
    <script src="https://js.fintoc.com/v1/"></script>
  </head>
  <body>
    <script>
      window.onload = () => {
        const widget = Fintoc.create({
          holderType: 'individual',
          widgetToken: 'pi_XXXXXXXX_sec_YYYYYYYY',
          product: 'payments',
          country: 'cl',
          publicKey: 'YOUR_PUBLIC_KEY',
          onSuccess: () => {},
        });
        widget.open();
      };
    </script>
  </body>
</html>

You should only use holderType as individual since our Payment Initiation API is designed for individual accounts.

If you want a Mexican payment, change the country parameter to mx.

To learn more about the Widget, its integration, and how to listen to Widget events, take a look to the Widget guide.

❗️

Use the Widget callbacks and events correctly

Never use the onSuccess, onExit or onEvent callbacks to get the state of the Payment Intent 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 Payment Intent was created or failed to be created.

Step 4: Handle post-payment events

Fintoc sends a payment_intent.succeeded event when the payment completes. Use the webhook guide to receive these events and run actions, such as sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow.

Listen for these events rather than waiting on a callback from the client. On the client, the customer could close the browser window or quit the app before the callback executes, and malicious clients could manipulate the response.

We recommend handling the following events:

📘

Learn more about webhooks

To learn more about how to create your own webhook endpoint, test your webhook endpoint and security best practices read our Webhooks guide.

Step 5: Make your first payment

Once the widget appears on your screen, follow the payment flow using Fintoc's test special values. For a successful payment, you can use one of these values:

• In Chile, select any bank and login using the 41614850-3 rut and jonsnow password. Once you are logged in to the bank, select the account with the number 422159212. After you select that account, wait 5 seconds and the payment should be successful.
• For Mexico, select any bank and write the number 5555555555. Wait 5 seconds and the payment should be successful.

You should have received a payment_intent.succeeded event in your webhook endpoint.

Congratulations! You just made your first Fintoc payment! To test different payment flows, see Fintoc's test special values.