Using the SDK

This is a step-by-step guide to integrating the Trio Checkout SDK into your system. Before you start, make sure that:

You have created your API credentials in the Trio App (see Creating your first API credential) and have the client_id and client_secret of your company, in the sandbox or in production.
You have read how to create a checkout session in the Initiation API reference.

Embed the SDK

Add the SDK through a script tag just before the closing </head> tag of your HTML:

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

If you have a mobile application, you can embed the same tag in a WebView inside your application.

Create a payment session

All payment information is sensitive, so the data the front end will use is prepared in your back end beforehand. To use the SDK you create a session, which represents an instance of a transaction inside Trio’s front end application. Every session is created with a payload, and the payload varies with the type of session.The field options.session_type defines which type is created and must be one of the four available: payin, payout, guest_onboarding or user_onboarding. To learn about each type, its use cases and how to create a session for it, see:

After creating a session, save the id it returns: you need it to instantiate the SDK interface. When its expiration time ends, the session expires automatically and cannot be used again.

Always generate a session in the back end of your application. Generating it in your front end exposes your client_secret, which your end users could intercept.

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. It has two primary functions:

create() prepares the information to be sent to your back end;
open() pops up the user experience for the end user, so the transaction can be completed.

Trio.create() takes an object with the following properties.

Property	Required	Description
`environment`	No	`sandbox` or `production`. Defaults to `production` when omitted.
`session`	Yes	The `id` of the session to use, for example `01GYR8ZJR9ZH5X82ACN8QQ2GMK`.
`onSuccess`	No	Called when a payment completes successfully. Receives the `data` object with information about the created payment.
`onExit`	No	Called when the end user closes the Trio Checkout.
`onEvent`	No	Called after each event during the flow, for fine-grained control of failures and secondary events.
`onLoad`	No	Called when the SDK bridge is initialized by `Trio.create()`.

Open the checkout

Once you have everything needed to initiate a payment, call Trio.create() and then 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 it by running Trio.open():

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

Get information about the transactions

Every payment processed by Trio generates a document: an in document for a PayIn and an out document for a PayOut. You can handle the transactions through the onEvent callback or by receiving the webhook events of the document.You can also open the documents in the Trio App:

Environment	PayIn	PayOut
Sandbox	`app.sandbox.trio.com.br/documents/in/{document_id}`	`app.sandbox.trio.com.br/documents/out/{document_id}`
Production	`app.trio.com.br/documents/in/{document_id}`	`app.trio.com.br/documents/out/{document_id}`

Next steps

PayIn flow: the session payload to receive money.
PayOut flow: the session payload to pay a user.
Local example: a runnable back end and front end.
Webhooks: receive the document events instead of polling.

Onboarding

Receivables

Payments

Operations

Trio MCP

Trio SDK

Next steps

​Next steps

Next steps