Sandbox
How do I get the sandbox client_id and client_secret?
How do I get the sandbox client_id and client_secret?
Your team creates the sandbox API credentials directly in the sandbox Trio App. Trio does not generate or provide these credentials manually. Your team needs to:
- Create an organization in the sandbox.
- Access the sandbox Trio App.
- Create the API credentials.
- Use the generated credentials to authenticate your API requests.
Where can I find the sandbox bank account ID?
Where can I find the sandbox bank account ID?
The
bank_account_id is available in the sandbox Trio App. After creating your organization:- Go to Accounts.
- Select the bank account you want to use.
- Open the account details.
- Copy the account identifier: that is the
bank_account_id.
GET /v2/bank_accounts. This ID is required for operations such as Pix cash-in testing: every receivable and payment names the bank account it uses.Coming from V1? The virtual account ID (
virtual_account_id) no longer exists. Send bank_account_id instead.Webhooks
How do I create and configure a sandbox webhook?
How do I create and configure a sandbox webhook?
The complete process is in Creating your first webhook. The same concepts apply to the sandbox and to production, but you configure each environment separately.
Where can I get the webhook secret?
Where can I get the webhook secret?
The webhook secret is generated when you create the webhook in the Trio App. Your system uses it to validate the authenticity of the webhook requests it receives. See Webhook authentication for the details of authentication and signatures.
Does my webhook endpoint require IP allowlisting?
Does my webhook endpoint require IP allowlisting?
Yes. When creating your API credentials, you must register your server’s IP address.If your infrastructure also requires Trio’s IP addresses in your allowlist, use the following:
What is the webhook retry policy?
What is the webhook retry policy?
Trio retries failed webhook deliveries up to 5 times, and the interval grows after each failure:
Design your webhook endpoint to handle duplicate events safely: make your processing idempotent so the same event is never processed more than once. See Webhooks for the delivery model.
Pix cash-in testing
How can I simulate a successful Pix payment in the sandbox?
How can I simulate a successful Pix payment in the sandbox?
Follow Simulate a successful deposit.
How can I simulate a failed Pix payment in the sandbox?
How can I simulate a failed Pix payment in the sandbox?
Follow Simulate deposit failures.
Where can I understand the Pix transaction status flow?
Where can I understand the Pix transaction status flow?
Understanding the document lifecycle matters when you implement Pix cash in and the other transaction flows. Read Document lifecycle and follow the summary of the integration best practices.
API rate limits
What are the API rate limits?
What are the API rate limits?
These limits apply to each individual account and each endpoint and are enforced per second. See Rate limit.
What should I do when I reach the API rate limit?
What should I do when I reach the API rate limit?
Implement a retry and backoff strategy. Avoid retrying continuously without waiting between attempts: a backoff reduces unnecessary requests and prevents repeated rate-limit errors.
Pix cash-in compliance
Which Pix cash-in compliance rules can be configured?
Which Pix cash-in compliance rules can be configured?
You configure the following rules directly in the Trio App, according to the requirements of each bank account:
- Block unidentified deposits.
- Block deposits from duplicate QR codes.
- Block deposits with an amount different from the amount issued in the dynamic QR code.
- Block deposits from legal entities.
- Block deposits with a CPF/CNPJ different from the dynamic QR code.
- Block deposits from unauthorized participants.
- Block deposits from a bank account belonging to a different counterparty than the dynamic QR code.
- Automatically return deposits from minors.
- Automatically return deposits from deceased individuals.
- Automatically return deposits from individuals with an irregular and/or invalid CPF/CNPJ.
- Block cash-out transactions to legal entities (CNPJ).
Production
How do I get production credentials and bank account IDs?
How do I get production credentials and bank account IDs?
Production access is provided after the contract is signed with the Trio commercial team. After receiving access to the production Trio App, your team can:
- Create the production API credentials.
- Create and manage bank accounts.
- Obtain the corresponding
bank_account_idof each account. - Configure production webhooks.
Are production and sandbox webhook secrets different?
Are production and sandbox webhook secrets different?
Yes. Sandbox and production are completely separate environments. You configure your webhooks separately in each environment, and each has its own webhook configuration and secret. Never use a sandbox webhook secret in production.
Is there a production certification or go-live checklist?
Is there a production certification or go-live checklist?
After the contract is signed and the Trio team completes the compliance validation, your engineering team validates the complete integration flow before going live. At minimum, validate:
- Pix cash in.
- Cash out.
- Webhook delivery.
- Webhook signature validation.
- Transaction status updates.
- Document lifecycle handling.
- Error handling.
- Retry and idempotency behavior.
Next steps
- Receivables and Payments: step-by-step guides for the common integration scenarios.
- Integration best practices: build and maintain a reliable integration.
- Welcome: the complete documentation, from getting started to the API reference and webhooks.
- Support: channels, availability and what to include when you report an issue.