Integration Flow

To initiate integration with the Trio Checkout SDK, make sure you have the client_id and client_secret that belongs to your company, either in a sandbox or production environment.

First of all, you need to embed our SDK through a script tag just before the closing of the <head> tag in your HTML:

<head>
  <script src="https://cdn.trio.com.br/checkout-js-sdk.min.js"></script>
</head>

In case you have a mobile application, it is possible to embed our tag by making use of a WebView inside our application.

After doing so, you can start the SDK by following these 3 steps:

1. Create a payment session

Since all payment information is sensitive, we prepare all the information that will be handled in the front-end application in the back-end beforehand. In order to execute it, we offer the creation of a session, which contains all necessary information about the initiation. Below is an example of a payload following the payload:

{
    "transaction": {
        "tax_number": "23725474028", //customer document tax number
        "name": "John Doe", //customer name
        "amount": 1, //total amount in cents
        "external_id": "01H7DKA58YDWPA7ZBCCAVWFM5E", //reference for your system
        "description": "Paid to example.com" //additional information about the transaction
    },
    "receiver": {
        "virtual_account_id": "018a66ca-0451-9cd7-1cfa-8dca325db29f" //unique identifier for the virtual account that will receive the money 
    },
    "options": {
        "payment_methods": [
            "pix_qrcode",
            "pix_open_finance"
        ], //available payment methods, if not informed default is pix_open_finance
        "theme": {
            "colors": {
                "backdrop_color": "#ffffff", //hex color for the background (optional, accepts any color)
                "button_color": "#f6df69", //hex color for the interface primary action button (optional, accepts any color)
                "button_label_color": "#000000", //hex color for the interface primary action text (optional, accepts only #000000 or #ffffff)
                "link_color": "#426b55", //hex color for links (optional, accepts any color)
                "navbar_action_color": "#ffffff", //hex color for the background (optional, accepts only #000000 or #ffffff)
                "navbar_color": "#426b55" //hex color for top navbar background color (optional, accepts any color)
            },
            "logo_url": "https://linktologo.com/link.png" //url for the logo that will be added to the initiation flow
        }
    }
}

You can also customize your end-user experience utilizing the options field, with the respective xxxx_color fields. Below, you can see an example of wholly implemented customization:

And with the correct payload, you can call the endpoint to create a new session:

curl -X POST 'https://production.trio.com.br/checkout/sessions' \
-H 'Content-Type: application/json' \
-d '{
    "transaction": {
        "tax_number": "23725474028",
        "name": "John Doe",
        "amount": 1,
        "external_id": "01H7DKA58YDWPA7ZBCCAVWFM5E",
        "description": "Paid to example.com"
    },
    "receiver": {
        "virtual_account_id": "018a66ca-0451-9cd7-1cfa-8dca325db29f"
    },
    "options": {
        "payment_methods": [
            "pix_qrcode",
            "pix_open_finance"
        ],
        "theme": {
            "colors": {
                "backdrop_color": "#ffffff",
                "button_color": "#f6df69",
                "button_label_color": "#000000",
                "link_color": "#426b55",
                "navbar_action_color": "#ffffff",
                "navbar_color": "#426b55"
            },
            "logo_url": "https://mylogo.com/logo.png"
        }
    }
}' \
-u {client_id}:{client_secret}

By making an appropriate request, you will receive a response akin to:

{
    "data": {
        "company_id": "a56c6e42-10c8-4876-946f-7d71595cecdc",
        "expiration_timestamp": "2023-11-24T14:37:00.912473Z",
        "id": "01HG0VAZPGJ3MZ631G1FJ6GPK7",
        "options": {
            "payment_methods": [
                "pix_qrcode",
                "pix_open_finance"
            ],
            "theme": {
                "colors": {
                    "backdrop_color": "#ffffff",
                    "button_color": "#f6df69",
                    "button_label_color": "#000000",
                    "link_color": "#426b55",
                    "navbar_action_color": "#ffffff",
                    "navbar_color": "#426b55"
                },
                "logo_url": "https://mylogo.com/logo.png"
            }
        },
        "participants": null,
        "receiver": {
            "virtual_account_id": "c6377347-7891-46ac-ac2e-368d01ac0305"
        },
        "timestamp": "2023-11-24T14:22:00.912473Z",
        "transaction": {
            "amount": {
                "amount": 1,
                "currency": "BRL"
            },
            "description": "Paid to example.com",
            "email": null,
            "external_id": "01H7DKA58YDWPA7ZBCCAVWFM5E",
            "name": "John Doe",
            "phone_number": null,
            "redirect_url": "https://checkout.trio.com.br/summary",
            "tax_number": "23725474028"
        }
    }
}

After creating a session, make sure that you saved the id returned. It will be necessary in order to open an instance the SDK interface. After 15 minutes, a created session automatically expires, and cannot be used again.

📘
Be wary
A session must always be generated inside the back-end of your application, for security reasons.
Generating it inside your front-end may expose your client_secret, making it interceptable by your end-users.

2. Create a new instance of the SDK

With the session_id in hand and the SDK installed, you have access to a module called Trio in the browser console. This module has 2 primary functions:

create(), which is responsible for preparing the information to be sent to your backend
open(), which pops up the user experience for the final user, so the transaction can be completed.

To instantiate the SDK, first use the Trio.create, which requires a object as parameter that must contain such information:

Environment

A property defining the environment:

environment: 'production'

Could be either: sandbox or production. If the property is not informed, the default will be production.

Session - Required

A property defining what session will be used:

session: '01GYR8ZJR9ZH5X82ACN8QQ2GMK'

Callbacks

We have some callbacks that can help you control the flow of the initiation itself:

onSuccess: is triggered when a payment is completed successfully. The data object is returned, containing information about the created payment.
onExit: is triggered when the Trio Checkout is closed by the end-user.
onEvent: is triggered after each event during the initiation flow. Allows for more fine-grained control of event, such as failures and secondary events.
onLoad: is triggered when the SDK Bridge is successfully initialized (through the Trio.create() function).

3. Open checkout

Once you have prepared all the necessary information to initiate a payment, use the functions Trio.create() and Trio.open():

try {
  Trio.create({
    environment: 'production',

    session: '01GYR8ZJR9ZH5X82ACN8QQ2GMK',

    onSuccess: (data) => {
      console.log('onSuccess triggered')
      console.log(data)
    },

    onExit: () => {
      console.log('onExit triggered')
    },

    onEvent: (event_type, data) => {
      console.log('onEvent triggered')
      console.log(event_type)
      console.log(data)
    },

    onLoad: () => {
      console.log('onLoad triggered')
    }
  })
}
catch (error) {
  console.error(error)
}

Then open by running Trio.open()

<button type="button" onclick="Trio.open()">Open checkout</button>

Getting information about the Payment Initiation Document

Every payment initiation processed by Trio, will generate a new Payment Initiation Document. This document could be accessed using the following endpoints using our id or either your external_id:

Get an initiation document