Built for your product team to integrate
A documented REST API, webhooks for every state change, an embeddable Checkout SDK and a full sandbox. From the first request to Go Live, with a dedicated Integration Analyst.
1.0 REST API
REST API
with predictable conventions
JSON over HTTPS, with the same rules on every endpoint: authentication, amounts, pagination, errors and limits. Your team learns them once and applies them across the whole integration.
API conventions- 01Environments
Production and sandbox
One base URL per environment, and every API path starts with /v2. The sandbox is a complete, isolated copy of the API for testing.
api.trio.com.br · api.sandbox.trio.com.br - 02Authentication
HTTP Basic and Trio-Version
client_id as the username and client_secret as the password, plus the Trio-Version header on every request. Credentials are created in the app, under API Keys, work in a single environment and can be read-only.
Trio-Version: 2026-10-19.v2 - 03Amounts
Integers in cents
Every monetary amount is an integer in centavos (BRL cents), with no decimal places to round.
100000 → R$1,000.00 - 04Idempotency
Unique external_id
Sent with every cash-in and cash-out, it drives idempotency, reconciliation and webhook tracing. The idempotency window is 24 hours.
"external_id": "PGTO-4821-0097" - 05Pagination
Cursors
Lists return metadata.after, metadata.before and has_more, with 50 records per page by default and up to 100.
GET /v2/documents/in?after=… - 06Limits
60 requests per second
In production; 5 in the sandbox. Limits apply per account and per endpoint. A 429 means wait and retry with backoff.
HTTP/1.1 429 Too Many Requests - 07Tracing
X-Request-Id
Every response carries a unique request ID, also visible in the app's logs. Share it with support to speed up the investigation.
X-Request-Id: GEzmrWO6-L7HK28FP0eD - 08Errors
HTTP status and code
Failures use HTTP status codes, with 422 for validation, and a JSON body with error_code, error_message and an errors list, each one documented.
"error_code": "REQUIRED_PARAMETER" - 09Dates
UTC in ISO 8601
Dates and times sent to and returned by the API are always in UTC, in ISO 8601 format.
2026-10-15T17:02:18Z
2.0 Webhooks
Webhooks
for every state change
Every money movement is a document: incoming, outgoing or transfer. Since most operations are asynchronous, webhooks deliver each document's final state straight to your system, with your external_id. Integrations created before V2 keep receiving the old names (api_version v100).
Webhooks guideCategoryTypes
in_documentCollectionscreatedconfirmedkycsettledfailedin_document_refundCollection refundscreatedconfirmedsettledfailedout_documentPaymentscreatedconfirmedsettledfailedout_document_refundPayment refundscreatedconfirmedsettledfailedtransfer_documentTransfers between your accountscreatedsettledfailedboletoBoletoscreatedconfirmedupdatedsettledprotestedrefundedfailedcancelledrecurrencePix Automático: recurrencescreatedapprovedrejectedexpiredcancelledrecurrence_collectionPix Automático: chargescreatedactivesettledexpiredrejectedcancelledrecurrence_collection_attemptPix Automático: attemptsrequestedscheduledsettledcancelledrejectedexpiredfailedentityEntitiesin_reviewapprovedrejected
3.0 Checkout SDK
Checkout SDK
pay‑in and pay‑out in your app
Trio Checkout brings Pix to your website, or to your app through a WebView. Checkout handles the session, payment, errors and notifications at every step.
SDK documentation4.0 Sandbox
Sandbox
to test with no financial risk
A free, isolated environment that replicates the production API's behavior. Simulate deposits, payments, refunds and failure scenarios, and validate every webhook event before Go Live.
Create a sandbox account5.0 From Design to Go Live
From Design to Go Live
with a dedicated Integration Analyst
A standard API integration can be ready in a week, and we've seen complete integrations done in a single day. Custom integrations follow a track with technical guidance at every phase, and no setup fee during the integration.
- planningPhase 1
Design
Map the products, the flows and the internal systems that join the integration, such as your ERP and accounting platform.
- sandboxPhase 2
Setup
Create the organization in the sandbox, generate the client_id and client_secret, and register your first webhook.
- sandboxPhase 3
Build
Implement cash-in, cash-out and document reads, always with a unique external_id.
- sandboxPhase 4
Test
Validate Pix, cash-out, webhook delivery and signatures, error handling, retries and idempotency.
- productionPhase 5
Go Live
Once the contract is signed and compliance is cleared, create your production credentials and webhooks.
Supportduring and after the integration
- IntegrationMon–Fri, 9 AM to 6 PM
Guidance on the API, webhooks, the sandbox and best practices from the integration team.
- Operations24 hours, 7 days a week
Incidents, transaction checks, reconciliation help and emergencies at any hour.
- Integration AnalystIncluded in the process
A technical specialist works with your team from the first request to Go Live, with no setup fee.
API reference
organized by what your team needs to do
Every endpoint documented with parameters, examples and responses, plus the V2 OpenAPI spec to generate clients.
Open the full reference- Accounts
Accounts and counterparties
Entities, accounts, balances, statements, metrics and counterparties, and the onboarding of the companies you serve.
GET/v2/bank_accounts - Cash-in
Collections
Static, dynamic and due-date Pix QR Codes, Pix keys and refunds.
POST/v2/in/pix/qrcodes - Pix Automático
Recurrences
Automatic recurring Pix: recurrences, charges and the attempts behind each charge.
POST/v2/in/pix/recurrences - Cash-out
Payments
Pix by key, BR Code or account, with a check before paying, boletos, utility bills, taxes and DARF.
POST/v2/out/pix/async - Reconciliation
Documents
List and search documents by external_id or end-to-end ID.
GET/v2/documents/out/search - Cards
Corporate cards
Issuing, blocking, balance top-ups, invoices and purchases.
POST/v2/cards - Boletos
Boletos with Pix
Boletos (bank payment slips) with a Pix QR Code: issuing, due-date changes, protest and cancellation.
POST/v2/in/boletos - Webhooks
Webhook management
Create, update and remove webhooks, with each one's payload version.
POST/v2/webhooks
Ready for AI agents
from integration to operations
Agents that write your integration read Trio's docs in formats made for them: an llms.txt index, the full documentation in a single file and every page in Markdown. Agents that work with your finance team connect to the account through Trio MCP, Trio's banking MCP server.
- Indexllms.txtThe API's essential facts and a map of every page.
docs.trio.com.br/llms.txt - Fullllms-full.txtEvery documentation page in a single Markdown file.
docs.trio.com.br/llms-full.txt - MarkdownAny page as .mdAppend .md to the address of any documentation page.
/v2/webhooks/introduction.md - OpenAPISpecsBanking API V2, with onboarding.
/v2/api-reference/openapi.json
MCP
Trio MCP
connects AI agents to your account
Connect Claude or another MCP-compatible client to your company's account. Access uses the Trio App sign-in, with no API key, and the agent sees only the organization's data: entities, balances, statements, transfers, documents, cards and invoices. Every tool is read-only: the agent looks things up and analyzes them, and payments stay with the people on your team.
Explore Trio MCPAuthorized by the Central Bank of Brazil, with a direct Pix connection.
A Payment Institution authorized by the Central Bank of Brazil, with a public information-security policy and high-availability infrastructure of its own.
- IP 619Authorized by the Central Bank of Brazil
- BCB 85/2021Information-security policy (Resolução BCB nº 85/2021)
- LGPDData protection under Brazil's LGPD, with a DPO
- 99.99%Uptime
Frequently asked
questions
How long does an integration take?
A standard API integration can be ready in a week, and we've seen complete integrations done in a single day; the largest take up to three months, depending on scope and your technical team's availability. Custom flows follow the Design → Setup → Build → Test → Go Live track, with technical guidance at every phase.
Does Trio charge for the integration or for technical support?
No. The dedicated Integration Analyst is included in the process, with no setup fee during the integration.
How do I get sandbox credentials?
Your own team creates them in the sandbox Internet Banking: register your organization at app.sandbox.trio.com.br, sign in to the app and generate the client_id and client_secret. Sandbox and production credentials are managed separately.
Do I need to register IP addresses to use the API?
Yes. When you create API credentials, you register your server's IP address. If your infrastructure also requires allowlisting Trio's IPs, the sandbox IP is in the documentation and the production IP is shared after the contract is signed.
Do sandbox and production share the same webhook secret?
No. They are completely separate environments: each has its own webhook configuration and its own secret. Never use a sandbox secret in production.
What happens if my endpoint misses a webhook?
Your endpoint has 1 second to answer with 200, 201, 202 or 204. If the answer is an error, Trio tries again: the first time 5 seconds later, with the interval doubling after each failure up to 3 minutes, for up to 24 attempts or 1 hour. Timeouts are not retried, so answer fast and process the event afterwards. Since an event can arrive more than once, ignore repeats by the combination of ref_id, category and type.
How do I move to production?
Production access opens once the contract is signed with our sales team and compliance is cleared. From then on, your team creates the production credentials, accounts and webhooks. Before Go Live, validate at least Pix cash-in, cash-out, webhook delivery and signatures, the document lifecycle, errors, retries and idempotency.