How to use the SDK?

Understand the full integration flow when using Trio Checkout

Suggest Edits

This is a step-by-step guide on how to integrate the Checkout SDK within your business/system.

Some requirements for this tutorial are:

  • Make sure you have created your API Keys through our console (API Keys page), and the client_id and client_secret that belongs to your company from either in a sandbox or production environment.
  • Read the API Reference on how to create a Checkout Session.

1. Embed the SDK

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 also possible to embed our tag by making use of a WebView inside your application.

2. Create a payment session

Since all payment information is sensitive, we allow ourselves to handle information that will be used in the front-end in the back-end beforehand. In order to use the SDK, then, we offer the creation of a session, which represents an instance of a transaction inside our front-end application. All sessions must be created with a payload, and the payload will vary depending on the type of session you want to create.
The field "options.session_type" defines which type will be created, and must be one of the four available "payin", "payout", "guest_onboarding", "user_onboarding". To understand more about each type, its use cases and how to create a session for each one please follow the links bellow:

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 the expiration time ends, 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.

3. 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).

4. 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>

5. Getting information about transactions

Every payment processed by Trio will generate a new document. You can handle the transactions either by dealing with the onEvent callback, or by receiving webhooks for the document.

Pay-in webhook (collecting document)

Payout webhook (payment document)

You can also access the documents inside our Dashboard:

  1. In Sandbox:
    1. Pay-in - console.sandbox.trio.com.br/documents/in/{document_id}
    2. Payout - console.sandbox.trio.com.br/documents/out/{document_id}
  2. In Production
    1. Pay-in - console.trio.com.br/documents/in/{document_id}
    2. Payout - console.trio.com.br/documents/out/{document_id}

Updated 10 days ago

Veja mais