Integration Flow
Understand the full integration flow when using payment initiation
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 backendopen()
, 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 theTrio.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
:
Updated 8 days ago