Construída para o seu time de produto integrar
API REST documentada, webhooks para cada mudança de estado, Checkout embedável via SDK e um sandbox completo. Do primeiro request ao Go Live, com um Analista de Integração dedicado.
1.0 API REST
API REST
com convenções previsíveis
JSON sobre HTTPS, com as mesmas regras em todos os endpoints: autenticação, valores, paginação, erros e limites. O seu time aprende uma vez e aplica em toda a integração.
Convenções da API- 01Ambientes
Produção e sandbox
Uma URL base por ambiente, e todo caminho da API começa com /v2. O sandbox é uma cópia completa e isolada da API para testes.
api.trio.com.br · api.sandbox.trio.com.br - 02Autenticação
HTTP Basic e Trio-Version
client_id como usuário e client_secret como senha, e o header Trio-Version em toda requisição. As credenciais são criadas no app, em Chaves de API, valem para um único ambiente e podem ser só de leitura.
Trio-Version: 2026-10-19.v2 - 03Valores
Inteiros em centavos
Todo valor monetário é um número inteiro em centavos de real, sem casas decimais para arredondar.
100000 → R$ 1.000,00 - 04Idempotência
external_id único
Enviado em cada cash-in e cash-out, serve para idempotência, conciliação e rastreio de webhooks. A janela de idempotência é de 24 horas.
"external_id": "PGTO-4821-0097" - 05Paginação
Cursores
Listagens retornam metadata.after, metadata.before e has_more, com 50 registros por página por padrão e até 100.
GET /v2/documents/in?after=… - 06Limites
60 requisições por segundo
Em produção; no sandbox, 5. Valem por conta e por endpoint. Um 429 indica que é hora de esperar e tentar de novo com backoff.
HTTP/1.1 429 Too Many Requests - 07Rastreio
X-Request-Id
Toda resposta traz um identificador único da requisição, também visível nos logs do app. Informe-o ao suporte para agilizar a investigação.
X-Request-Id: GEzmrWO6-L7HK28FP0eD - 08Erros
Status HTTP e código
Falhas usam os códigos HTTP, com 422 para validação, e um corpo JSON com error_code, error_message e a lista errors, documentados um a um.
"error_code": "REQUIRED_PARAMETER" - 09Datas
UTC em ISO 8601
Datas e horários enviados e retornados pela API estão sempre em UTC, no formato ISO 8601.
2026-10-15T17:02:18Z
2.0 Webhooks
Webhooks
para cada mudança de estado
Toda movimentação de dinheiro é um documento: de entrada, de saída ou de transferência. Como a maioria das operações é assíncrona, os webhooks entregam o estado final de cada documento direto no seu sistema, com o seu external_id. Integrações criadas antes da v2 continuam recebendo os nomes antigos (api_version v100).
Guia de webhooksCategoriaTipos
in_documentRecebimentoscreatedconfirmedkycsettledfailedin_document_refundEstornos de recebimentocreatedconfirmedsettledfailedout_documentPagamentoscreatedconfirmedsettledfailedout_document_refundEstornos de pagamentocreatedconfirmedsettledfailedtransfer_documentTransferências entre suas contascreatedsettledfailedboletoBoletoscreatedconfirmedupdatedsettledprotestedrefundedfailedcancelledrecurrencePix Automático: recorrênciascreatedapprovedrejectedexpiredcancelledrecurrence_collectionPix Automático: cobrançascreatedactivesettledexpiredrejectedcancelledrecurrence_collection_attemptPix Automático: tentativasrequestedscheduledsettledcancelledrejectedexpiredfailedentityEntidadesin_reviewapprovedrejected
3.0 Checkout SDK
Checkout SDK
pay‑in e pay‑out no seu app
O Trio Checkout leva o Pix para o seu site ou para o seu app via WebView. Sessão, pagamento, erros e notificações de cada etapa ficam por conta do Checkout.
Documentação do SDK4.0 Sandbox
Sandbox
para testar sem risco financeiro
Um ambiente isolado e gratuito que replica o comportamento da API de produção. Simule depósitos, pagamentos, estornos e cenários de falha, e valide cada evento de webhook antes do Go Live.
Criar conta no Sandbox5.0 Do Design ao Go Live
Do Design ao Go Live
com um Analista de Integração dedicado
Uma integração padrão via API pode ficar pronta em uma semana, e já tivemos integrações completas em um único dia. Integrações customizadas seguem uma trilha com acompanhamento técnico em cada fase, sem taxa de setup durante a integração.
- planejamentoFase 1
Design
Mapeie produtos, fluxos e os sistemas internos que entram na integração, como ERP e plataforma contábil.
- sandboxFase 2
Setup
Crie a organização no sandbox, gere o client_id e o client_secret e registre o primeiro webhook.
- sandboxFase 3
Build
Implemente cash-in, cash-out e a leitura de documentos, sempre com um external_id único.
- sandboxFase 4
Test
Valide Pix, cash-out, entrega e assinatura de webhooks, tratamento de erros, retentativas e idempotência.
- produçãoFase 5
Go Live
Com o contrato assinado e o compliance validado, crie as credenciais e os webhooks de produção.
Suportedurante e depois da integração
- IntegraçãoSeg. a sex., 9h às 18h
Orientação sobre API, webhooks, sandbox e boas práticas com o time de integração.
- Operação24 horas, 7 dias por semana
Incidentes, verificação de transações, apoio à conciliação e emergências a qualquer hora.
- Analista de IntegraçãoIncluso no processo
Um especialista técnico acompanha o seu time do primeiro request ao Go Live, sem taxa de setup.
Referência da API
organizada pelo que o seu time precisa fazer
Cada endpoint documentado com parâmetros, exemplos e respostas, mais a especificação OpenAPI da v2 para gerar clientes.
Abrir a referência completa- Contas
Contas e contrapartes
Entidades, contas, saldos, extratos, métricas e contrapartes, e o onboarding das empresas que você atende.
GET/v2/bank_accounts - Cash-in
Recebimentos
QR Codes Pix estáticos, dinâmicos e com vencimento, chaves Pix e estornos.
POST/v2/in/pix/qrcodes - Pix Automático
Recorrências
Recorrências, cobranças e tentativas de cada cobrança.
POST/v2/in/pix/recurrences - Cash-out
Pagamentos
Pix por chave, BR Code ou conta, com consulta antes de pagar, boletos, contas de consumo, tributos e DARF.
POST/v2/out/pix/async - Conciliação
Documentos
Listagem e busca de documentos por external_id ou end-to-end ID.
GET/v2/documents/out/search - Cartões
Cartões corporativos
Emissão, bloqueio, recarga de saldo, faturas e compras.
POST/v2/cards - Boletos
Boletos com Pix
Emissão de boleto com QR Code Pix, alteração de vencimento, protesto e cancelamento.
POST/v2/in/boletos - Webhooks
Gestão de webhooks
Cadastre, edite e remova webhooks, com a versão do payload de cada um.
POST/v2/webhooks
Pronta para agentes de IA
da integração à operação
Agentes que escrevem a sua integração leem a documentação da Trio em formatos feitos para eles: um índice llms.txt, a documentação completa em um único arquivo e cada página em Markdown. Agentes que trabalham com o seu time financeiro se conectam à conta pelo Trio MCP, o servidor MCP bancário da Trio.
- Índicellms.txtOs fatos essenciais da API e o mapa de todas as páginas.
docs.trio.com.br/llms.txt - Completallms-full.txtTodas as páginas da documentação em um único arquivo Markdown.
docs.trio.com.br/llms-full.txt - MarkdownQualquer página em .mdAcrescente .md ao endereço de qualquer página da documentação.
/v2/webhooks/introduction.md - OpenAPIEspecificaçõesBanking API v2, com onboarding.
/v2/api-reference/openapi.json
MCP
O Trio MCP
conecta agentes de IA à sua conta
Conecte o Claude ou outro cliente compatível com MCP à conta da sua empresa. O acesso é feito com o login do app Trio, sem chave de API, e o agente vê apenas os dados da organização: entidades, saldos, extratos, transferências, documentos, cartões e faturas. Todas as ferramentas são de leitura: o agente consulta e analisa, e os pagamentos continuam com as pessoas do seu time.
Conheça o Trio MCPAutorizada pelo Banco Central, com conexão direta ao Pix.
Instituição de Pagamento autorizada pelo Banco Central, com política pública de segurança da informação e infraestrutura própria de alta disponibilidade.
- IP 619Autorizada pelo Banco Central
- BCB 85/2021Política de Segurança da Informação
- LGPDProteção de dados, com encarregado (DPO)
- 99,99%Uptime
Perguntas
frequentes
Quanto tempo leva para integrar?
Uma integração padrão via API pode ficar pronta em uma semana, e já tivemos integrações completas em um único dia; as maiores levam até três meses, conforme o escopo e a disponibilidade do time técnico. Os fluxos customizados seguem a trilha Design → Setup → Build → Test → Go Live, com acompanhamento técnico em cada fase.
A Trio cobra por integração ou por suporte técnico?
Não. O Analista de Integração dedicado está incluso no processo, sem taxa de setup durante a integração.
Como consigo as credenciais do sandbox?
O seu próprio time cria as credenciais no Internet Banking do sandbox: registre a organização em app.sandbox.trio.com.br, acesse o app e gere o client_id e o client_secret. Credenciais de sandbox e de produção são gerenciadas separadamente.
Preciso cadastrar IPs para usar a API?
Sim. Ao criar as credenciais de API, você registra o IP do seu servidor. Se a sua infraestrutura também exigir a liberação dos IPs da Trio, o IP do sandbox está na documentação e o de produção é compartilhado após o contrato.
Sandbox e produção usam o mesmo segredo de webhook?
Não. São ambientes totalmente separados: cada um tem a sua configuração de webhook e o seu próprio segredo. Um segredo do sandbox não deve ser usado em produção.
O que acontece se o meu endpoint não receber um webhook?
O seu endpoint tem 1 segundo para responder com 200, 201, 202 ou 204. Se a resposta for um erro, a Trio tenta de novo: a primeira vez 5 segundos depois, com o intervalo dobrando a cada falha até 3 minutos, por até 24 tentativas ou 1 hora. Timeouts não são repetidos, então responda rápido e processe o evento depois. Como um evento pode chegar mais de uma vez, ignore os repetidos pela combinação de ref_id, category e type.
Como passo para a produção?
O acesso à produção é liberado após a assinatura do contrato com o time comercial e a validação de compliance. A partir daí, o seu time cria as credenciais, as contas e os webhooks de produção. Antes do Go Live, valide no mínimo Pix cash-in, cash-out, entrega e assinatura de webhooks, ciclo de vida dos documentos, erros, retentativas e idempotência.