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 Checkout Session
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 Checkout Session

Using your test Secret Key, create a Checkout Session from your backend with the amount and currency of the payment. Always create the Checkout Session 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 Checkout Session request.

Here's an example of creating a Checkout Session for Chile:

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

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

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

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

import requests

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

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

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

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)

If you want to create a Checkout Session 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: "cs_li5531onlFDi235",
  created_at: "2021-10-15T15:22:11.474Z",
  object: "checkout_session",
  currency: "CLP",
  amount: 2476,
  customer_email: "[email protected]",
  expires_at: "1718634045", // timestamp en UTC
  mode: "test",
  return_url: "https://example.com/return?id=cs_li5531onlFDi235",
  status: "created",
  session_token: "cs_li5531onlFDi235_sec_a4xK32BanKWYn",
  metadata: {},
  business_profile: {}
}

Step 3: Open the Widget

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

📘

The session token is temporary

The session_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 andsession_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({
          sessionToken: 'cs_XXXXXXXX_sec_YYYYYYYY',
          product: 'payments',
          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 Checkout Session being created or its related payment intents. 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 Checkout Session was created or failed to be created.

Step 4: Handle post-payment events

Fintoc sends a checkout_session.completed event when the payment is complete. 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. From the client side, 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 checkout_session.finished event containing a successful payment in your webhook endpoint.

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