Skip to main content
Build a payment flow that collects one-time payments in CLP or MXN through a Fintoc-hosted checkout page. To accept payments with Fintoc, you complete three steps:
  1. On your backend, create a Checkout Session using your Secret Key
  2. Redirect your customer to complete the payment on the Fintoc-hosted checkout page
  3. Handle post-payment events
The following diagram shows how Fintoc interacts with both your backend and your frontend:

Optional: install the backend SDK

If you’re using Python, you can install our Python SDK to make it easier to interact with our API. The SDK automatically handles pagination, lets you easily verify Fintoc’s webhooks, and offers many other helpful features.

Create a session

The Checkout Session object represents your intent to collect a payment from a customer and tracks state changes throughout the payment process. Using your Secret Key, create a Checkout Session from your backend with the required parameters: amount, currency, success_url, and cancel_url, like the example below: Server
Node
Fintoc responds with the created Checkout Session object, including the redirect_url you use to send the customer to the payment:

Business profile (optional)

Send the Business Profile object if you are processing payments for a submerchantYou can also add the business_profile object when creating a session to customize the name displayed as the “Recipient” on the payment flow.Read here to learn more.

Include customer data (optional)

When creating a Checkout Session, you can include customer information by sending a customer_data object (or customer with the id of an existing Customer). This information allows Fintoc to display only the payment methods available for that specific customer. For example, Fintoc hides a bank when the amount exceeds its transaction limit.
Bank specific payment flows for business accounts and high amountsIn Chile, some bank_transfer payments require banks with special payment flows: Banco Estado, Banco de Chile, and Banco Santander. Fintoc limits the session to these banks when the payment exceeds the transaction limits or the customer has a tax_id.value of a business instead of a natural person. You can test this flow with the alternative payment method test guide.

Include a list of items (optional)

When creating a Checkout Session, you can also send the line_items, including information about the items of the session. This enables Fintoc to display this information on the checkout page and show only the payment methods available for specific products. Each item should have:

The price_data object

The product_data object

The price_data object contains a product_data object with product information: The example below creates a Checkout Session with a single line item: Server
Node
Fintoc responds with the created Checkout Session object. Each item in line_items includes a price with the product details you sent:

Pre-select a payment method (optional)

You can create a Checkout Session without specifying payment methods. In this case, customers can select from all available options on the Fintoc-hosted checkout page, based on the session parameters (amount, customer, currency) and the payment methods you have enabled in Fintoc. Alternatively, you can explicitly define the payment method type(s) for the session. For example, the request below sets the bank_transfer method and uses payment_method_options to pre-select the institution cl_banco_estado for the customer. In this scenario, the payment flow presented to the customer is limited to this specific method and bank. Server
Node
With card, the checkout also shows Apple Pay on devices that support it, in both live and test mode. Fintoc responds with the created Checkout Session object, echoing the pre-selected method and institution:

**Left**: Default view showing all available methods in Chile (bank transfer and cards) when no `payment_method_types` parameter is set. **Center**: Pre-selected `bank_transfer` flow for Banco Estado, displaying the institution-specific payment form directly. **Right**: Pre-selected `card` flow.

Using your own Checkout PageWhen you have your own checkout page, you should set the payment_method_types to redirect customers to the Fintoc-hosted checkout after they’ve already selected their preferred payment method.This skips Fintoc’s payment method selection screen and directs customers straight to the specific payment flow, instead of letting Fintoc manage the full checkout experience.

Offer cash in MXN sessions

In MXN sessions, you can offer cash on its own or combine it with card and bank_transfer. Your customer picks how to pay on the Fintoc-hosted checkout page. You can’t combine cash with installments. For example, the following request lets your customer pay with a card or in cash: Server
Fintoc responds with the session object, including cash in payment_method_types:
If a card or bank transfer payment fails and cash is available in the session, your customer can retry the payment in cash. See Accept cash payments in Mexico for how cash payments work.

Accept only some cards (optional)

To accept only cards from some banks, send their bank identification numbers (BINs) in payment_method_options.card.bins. A BIN is the first 6 or 8 digits of a card number, and it identifies the bank that issued the card. For example, use bins to offer a discount that a bank funds for its own cards. The request below creates a session that accepts only cards that start with 411111 or 455555: Server
Node
Fintoc responds with the session object, including bins in payment_method_options:
The bins restriction follows these rules:
  • bins is a non-empty array of strings, each with 6 or 8 digits. If you send an empty array, a BIN with a different length, or a BIN with non-digit characters, Fintoc returns 400 Bad Request with the invalid_payment_method_options error.
  • bins applies only to payment flow sessions.
  • bins restricts only cards. If the session also offers another payment method, such as bank_transfer, your customer can still pay with that method.
  • Fintoc checks the card when your customer enters it, not when you create the session. If the card doesn’t start with one of the BINs, the checkout rejects the card before charging it and asks your customer for another card.
  • A session with bins doesn’t offer Apple Pay, Google Pay, saved cards, or Hites cards (hites in payment_method_options.card.types). In an Express Checkout session, Fintoc rejects the Apple Pay payment, so don’t send bins there.
To test the restriction in test mode, create the session above and pay with the Chilean test card 4111111111111111. The checkout rejects any test card that starts with other digits, such as 4456524869770255.

Offer a discount for some cards

You can’t change the amount of a Checkout Session after you create it. To offer a discount for the cards of one bank, show your customer two ways to pay. Tell your customer which cards get the discount, because the checkout doesn’t show your promotion. When your customer chooses a way to pay, create the corresponding session:
  • Discounted payment: a session with the discounted amount, payment_method_types set to ["card"], and the BINs the bank gives you in payment_method_options.card.bins.
  • Regular payment: a session with the full amount and without bins.
Set only card in the discounted session. Otherwise, your customer can pay the discounted amount with another payment method. Set the cancel_url of the discounted session to the page where your customer chooses how to pay. A customer without a card from that bank can then go back and pay the full amount. When your customer comes back through cancel_url, expire the discounted session so your customer can’t pay it later.

Response when creating a Checkout Session

After you make the request to create the Checkout Session, Fintoc responds with the session object:
The response includes the redirect_url attribute. In the following step, you’ll use this attribute to redirect the customer to complete the payment.

Redirect the customer to complete the payment

Next, redirect customers to the Fintoc-hosted checkout page. After they complete the payment, Fintoc automatically redirects them back to your site: to the success_url after a successful payment, or to the cancel_url if they cancel. The Fintoc-hosted checkout does not support iframe integrations. Do not load the redirect_url in an iframe; redirect the full browser page instead. Client
To keep customers on your site instead, render the same Checkout Session with the embedded Widget. Pass the session’s session_token as the Widget’s sessionToken option. See Integrate the Widget on the web or WebView integration for mobile apps. You don’t create a Payment Intent for a Checkout Session. Fintoc creates the Payment Intent automatically when your customer starts a payment attempt. The session’s payment_resource field exposes the Payment Intent and stays null until then.

Handle post-payment events

Once a Checkout Session finishes, you handle the payment result in your frontend and complete the payment in your backend. On your backend, use the events that Fintoc sends through webhooks.

Complete the payment on your backend

Fintoc sends a checkout_session.finished and a payment_intent.succeeded event when the session completes and the payment is successful. Follow 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. The checkout_session.finished event includes information about the session and the payment_intent:
Fintoc emits these events across the payment lifecycle, including the failure and pending paths. Handle each one:
Handling async payments after the Checkout Session endsIn some cases, the Checkout Session may finish with a payment that does not yet have a final status, such as requires_action. This can happen, for example, when a bank transfer from a business account requires approval from more than one representative.Fintoc does not send a separate event for this status. You receive checkout_session.finished with data.payment_resource.payment_intent.status set to requires_action, so inform the customer that the payment is pending approval. When the payment reaches its final status, Fintoc sends payment_intent.succeeded or payment_intent.failed. Notify the customer of the final status when you receive it.

Customer email notifications

Fintoc emails your customer a payment receipt after a successful payment. Fintoc sends the receipt when either of these is true:
  • You set customer_email when you create the Checkout Session.
  • Your customer enters an email address on the success screen of the payment flow and requests the receipt.
If you set customer_email, Fintoc also uses it to notify your customer about refunds. To stop Fintoc from sending payment receipts automatically, leave out customer_email when you create the Checkout Session. Your customer can still request the receipt from the success screen. Without customer_email, Fintoc also doesn’t send refund notifications. To turn off all payment receipts for your account, including receipts customers request from the success screen, contact Fintoc support at soporte@fintoc.com.

Test your integration

Using your test mode API Secret Key, you can create payments that simulate successful and failed outcomes without moving any money. This lets you validate your full payment flow end-to-end:
  • Your backend API requests (creating sessions and handling responses)
  • The redirect flow from your frontend to the redirect_url and back to the success_url or cancel_url after the payment
  • The webhooks for post-payment events
A successful test session reaches status finished and triggers the checkout_session.finished and payment_intent.succeeded webhooks; a failed one triggers payment_intent.failed. To trigger specific scenarios, use the test credentials and special test values described in our testing guide.