# Get Bank Account Source: https://docs.trio.com.br/api-reference/banking-api/bank-accounts/get-bank-account api-reference/banking-api/openapi.json GET /banking/bank_accounts/{id} Get a bank account by ID # Get Bank Account Balances Source: https://docs.trio.com.br/api-reference/banking-api/bank-accounts/get-bank-account-balances api-reference/banking-api/openapi.json GET /banking/bank_accounts/{id}/balances Get balances for a bank account # List Bank Account Transactions Source: https://docs.trio.com.br/api-reference/banking-api/bank-accounts/list-bank-account-transactions api-reference/banking-api/openapi.json GET /banking/bank_accounts/{id}/transactions List transactions for a bank account # List Bank Accounts Source: https://docs.trio.com.br/api-reference/banking-api/bank-accounts/list-bank-accounts api-reference/banking-api/openapi.json GET /banking/bank_accounts List all bank accounts # Block Card Source: https://docs.trio.com.br/api-reference/banking-api/cards/block-card api-reference/banking-api/openapi.json POST /banking/cards/{id}/block Block an existing card # Cancel Card Source: https://docs.trio.com.br/api-reference/banking-api/cards/cancel-card api-reference/banking-api/openapi.json POST /banking/cards/{id}/cancel Cancel an existing card # Create Card Source: https://docs.trio.com.br/api-reference/banking-api/cards/create-card api-reference/banking-api/openapi.json POST /banking/cards Create a new card # Generate Card Invoice Statement CSV URL Source: https://docs.trio.com.br/api-reference/banking-api/cards/generate-card-invoice-statement-csv-url api-reference/banking-api/openapi.json GET /banking/cards/invoices/{id}/export Generate Card Invoice Statement CSV URL for an invoice # Get Card Source: https://docs.trio.com.br/api-reference/banking-api/cards/get-card api-reference/banking-api/openapi.json GET /banking/cards/{id} Get an existing card # Get Card Current Invoice Source: https://docs.trio.com.br/api-reference/banking-api/cards/get-card-current-invoice api-reference/banking-api/openapi.json GET /banking/cards/invoices/current Get Card current Invoice # Get Card Details Source: https://docs.trio.com.br/api-reference/banking-api/cards/get-card-details api-reference/banking-api/openapi.json GET /banking/cards/{id}/info Card sensitive information: holder name, card number, expiration date and cvv # List Card Invoice Lines Source: https://docs.trio.com.br/api-reference/banking-api/cards/list-card-invoice-lines api-reference/banking-api/openapi.json GET /banking/cards/invoices/{id}/lines List lines for a specific Card Invoice # List Card Invoices Source: https://docs.trio.com.br/api-reference/banking-api/cards/list-card-invoices api-reference/banking-api/openapi.json GET /banking/cards/invoices List Card Invoices # List Card Purchase Documents Source: https://docs.trio.com.br/api-reference/banking-api/cards/list-card-purchase-documents api-reference/banking-api/openapi.json GET /banking/cards/purchases List Card purchase documents # List Cards Source: https://docs.trio.com.br/api-reference/banking-api/cards/list-cards api-reference/banking-api/openapi.json GET /banking/cards List cards # Show card purchase document by end to end id Source: https://docs.trio.com.br/api-reference/banking-api/cards/show-card-purchase-document-by-end-to-end-id api-reference/banking-api/openapi.json GET /banking/cards/purchases/e2e/{id} Show card purchase document by end to end id # Show Card Purchase Document by ID Source: https://docs.trio.com.br/api-reference/banking-api/cards/show-card-purchase-document-by-id api-reference/banking-api/openapi.json GET /banking/cards/purchases/{id} Show Card purchase document by id # Top Up Card Balance Source: https://docs.trio.com.br/api-reference/banking-api/cards/top-up-card-balance api-reference/banking-api/openapi.json POST /banking/cards/{id}/topup Top Up card balance # Transfer Card Balance Source: https://docs.trio.com.br/api-reference/banking-api/cards/transfer-card-balance api-reference/banking-api/openapi.json POST /banking/cards/{id}/transfer_balance Transfer card balance to another card # Unblock Card Source: https://docs.trio.com.br/api-reference/banking-api/cards/unblock-card api-reference/banking-api/openapi.json POST /banking/cards/{id}/unblock Unblock an existing card # Update Card Source: https://docs.trio.com.br/api-reference/banking-api/cards/update-card api-reference/banking-api/openapi.json PUT /banking/cards/{id} Update card display name # Create Counterparty Source: https://docs.trio.com.br/api-reference/banking-api/counterparties/create-counterparty api-reference/banking-api/openapi.json POST /banking/counterparties Create a new counterparty # Create Counterparty Bank Account Source: https://docs.trio.com.br/api-reference/banking-api/counterparties/create-counterparty-bank-account api-reference/banking-api/openapi.json POST /banking/counterparties/{counterparty_id}/bank_accounts Create a bank account for a counterparty # Create Counterparty Split Recipient Source: https://docs.trio.com.br/api-reference/banking-api/counterparties/create-counterparty-split-recipient api-reference/banking-api/openapi.json POST /banking/counterparties/{counterparty_id}/split_recipients Create a split recipient for a counterparty # Get Counterparty Source: https://docs.trio.com.br/api-reference/banking-api/counterparties/get-counterparty api-reference/banking-api/openapi.json GET /banking/counterparties/{id} Get a counterparty by ID # Get Counterparty Bank Account Source: https://docs.trio.com.br/api-reference/banking-api/counterparties/get-counterparty-bank-account api-reference/banking-api/openapi.json GET /banking/counterparties/{counterparty_id}/bank_accounts/{counterparty_bank_account_id} Get a counterparty bank account # Get Counterparty Split Recipient Source: https://docs.trio.com.br/api-reference/banking-api/counterparties/get-counterparty-split-recipient api-reference/banking-api/openapi.json GET /banking/counterparties/{counterparty_id}/split_recipients/{counterparty_split_recipient_id} Get a counterparty split recipient # List Counterparties Source: https://docs.trio.com.br/api-reference/banking-api/counterparties/list-counterparties api-reference/banking-api/openapi.json GET /banking/counterparties List counterparties # List Counterparty Bank Accounts Source: https://docs.trio.com.br/api-reference/banking-api/counterparties/list-counterparty-bank-accounts api-reference/banking-api/openapi.json GET /banking/counterparties/{counterparty_id}/bank_accounts List bank accounts for a counterparty # List Counterparty Split Recipients Source: https://docs.trio.com.br/api-reference/banking-api/counterparties/list-counterparty-split-recipients api-reference/banking-api/openapi.json GET /banking/counterparties/{counterparty_id}/split_recipients List split recipients for a counterparty # Update Counterparty Source: https://docs.trio.com.br/api-reference/banking-api/counterparties/update-counterparty api-reference/banking-api/openapi.json PUT /banking/counterparties/{id} Update a counterparty # Create Webhook Source: https://docs.trio.com.br/api-reference/banking-api/developers/webhooks/create-webhook api-reference/banking-api/openapi.json POST /webhooks Create a new webhook # Delete Webhook Source: https://docs.trio.com.br/api-reference/banking-api/developers/webhooks/delete-webhook api-reference/banking-api/openapi.json DELETE /webhooks/{webhook_id} Delete a webhook # Get Webhook Source: https://docs.trio.com.br/api-reference/banking-api/developers/webhooks/get-webhook api-reference/banking-api/openapi.json GET /webhooks/{webhook_id} Get a webhook by ID # List Webhooks Source: https://docs.trio.com.br/api-reference/banking-api/developers/webhooks/list-webhooks api-reference/banking-api/openapi.json GET /webhooks List all registered webhooks # Update Webhook Source: https://docs.trio.com.br/api-reference/banking-api/developers/webhooks/update-webhook api-reference/banking-api/openapi.json PUT /webhooks/{webhook_id} Update a webhook # Get Bank Account Metrics Source: https://docs.trio.com.br/api-reference/banking-api/documents/metrics/get-bank-account-metrics api-reference/banking-api/openapi.json GET /banking/metric Get settled and failed totals for collecting and payment documents # Get Payment Refund Source: https://docs.trio.com.br/api-reference/banking-api/documents/payments-refunds/get-payment-refund api-reference/banking-api/openapi.json GET /banking/cashout/refunds/{id} Get a payment refund # List Payment Refunds Source: https://docs.trio.com.br/api-reference/banking-api/documents/payments-refunds/list-payment-refunds api-reference/banking-api/openapi.json GET /banking/cashout/refunds List payment refunds # Search Payment Refunds Source: https://docs.trio.com.br/api-reference/banking-api/documents/payments-refunds/search-payment-refunds api-reference/banking-api/openapi.json GET /banking/cashout/refunds/search Search payment refunds # Get Payment Source: https://docs.trio.com.br/api-reference/banking-api/documents/payments/get-payment api-reference/banking-api/openapi.json GET /banking/cashout/documents/{id} Get a payment document # List Payments Source: https://docs.trio.com.br/api-reference/banking-api/documents/payments/list-payments api-reference/banking-api/openapi.json GET /banking/cashout/documents List payment documents # Search Payments Source: https://docs.trio.com.br/api-reference/banking-api/documents/payments/search-payments api-reference/banking-api/openapi.json GET /banking/cashout/documents/search Search payment documents # Get Receivable Refund Source: https://docs.trio.com.br/api-reference/banking-api/documents/receivables-refunds/get-receivable-refund api-reference/banking-api/openapi.json GET /banking/cashin/refunds/{id} Get a receivable refund # List Receivable Refunds Source: https://docs.trio.com.br/api-reference/banking-api/documents/receivables-refunds/list-receivable-refunds api-reference/banking-api/openapi.json GET /banking/cashin/refunds List receivable refunds # Search Receivable Refunds Source: https://docs.trio.com.br/api-reference/banking-api/documents/receivables-refunds/search-receivable-refunds api-reference/banking-api/openapi.json GET /banking/cashin/refunds/search Search receivable refunds # Get Receivable Source: https://docs.trio.com.br/api-reference/banking-api/documents/receivables/get-receivable api-reference/banking-api/openapi.json GET /banking/cashin/documents/{id} Get a receivable document # List Receivables Source: https://docs.trio.com.br/api-reference/banking-api/documents/receivables/list-receivables api-reference/banking-api/openapi.json GET /banking/cashin/documents List receivable documents # Search Receivables Source: https://docs.trio.com.br/api-reference/banking-api/documents/receivables/search-receivables api-reference/banking-api/openapi.json GET /banking/cashin/documents/search Search receivable documents # Get Transfer Source: https://docs.trio.com.br/api-reference/banking-api/documents/transfers/get-transfer api-reference/banking-api/openapi.json GET /banking/cashout/transfer/{id} Get a transfer document # List Transfers Source: https://docs.trio.com.br/api-reference/banking-api/documents/transfers/list-transfers api-reference/banking-api/openapi.json GET /banking/cashout/transfer List transfer documents # Create entity Source: https://docs.trio.com.br/api-reference/banking-api/entities/create api-reference/banking-api/openapi.json POST /banking/entities Create a new entity # Get entity by ID Source: https://docs.trio.com.br/api-reference/banking-api/entities/get api-reference/banking-api/openapi.json GET /banking/entities/{id} Get an entity by ID # List entities Source: https://docs.trio.com.br/api-reference/banking-api/entities/list api-reference/banking-api/openapi.json GET /banking/entities Returns all entities from current organization # List institutions Source: https://docs.trio.com.br/api-reference/banking-api/institutions/list api-reference/banking-api/openapi.json GET /banking/institutions Returns all institutions # Check boleto Source: https://docs.trio.com.br/api-reference/banking-api/payments/boleto/check-boleto api-reference/banking-api/openapi.json POST /banking/cashout/boleto/check Check a boleto barcode or line code # Pay boleto Source: https://docs.trio.com.br/api-reference/banking-api/payments/boleto/pay-boleto api-reference/banking-api/openapi.json POST /banking/cashout/boleto/pay Generate a boleto payment # Pay boleto v2 Source: https://docs.trio.com.br/api-reference/banking-api/payments/boleto/pay-boleto-v2 api-reference/banking-api/openapi.json POST /banking/cashout/boleto/pay/v2 Generate a boleto payment using the v2 endpoint # Check Pix BR Code Source: https://docs.trio.com.br/api-reference/banking-api/payments/brcode/check-brcode api-reference/banking-api/openapi.json POST /banking/cashout/pix/brcodes/check Validate a Pix BR Code before creating a payment # Generate a Pix Payment (BR Code) Source: https://docs.trio.com.br/api-reference/banking-api/payments/brcode/generate-pix-payment-brcode api-reference/banking-api/openapi.json POST /banking/cashout/pix Generate a Pix payment using a BR Code # Check DARF Source: https://docs.trio.com.br/api-reference/banking-api/payments/darf/check-darf api-reference/banking-api/openapi.json POST /banking/cashout/darf/check Check a DARF # Pay DARF (v1) Source: https://docs.trio.com.br/api-reference/banking-api/payments/darf/pay-darf-v1 api-reference/banking-api/openapi.json POST /banking/cashout/darf/pay Generate a DARF payment using the v1 endpoint # Pay DARF (v2) Source: https://docs.trio.com.br/api-reference/banking-api/payments/darf/pay-darf-v2 api-reference/banking-api/openapi.json POST /banking/cashout/darf/pay/v2 Generate a DARF payment using the v2 endpoint # Check Tax Source: https://docs.trio.com.br/api-reference/banking-api/payments/tax/check-tax api-reference/banking-api/openapi.json POST /banking/cashout/tax/check Check a tax barcode or line code # Pay Tax (v1) Source: https://docs.trio.com.br/api-reference/banking-api/payments/tax/pay-tax-v1 api-reference/banking-api/openapi.json POST /banking/cashout/tax/pay Generate a tax payment using the v1 endpoint # Pay Tax (v2) Source: https://docs.trio.com.br/api-reference/banking-api/payments/tax/pay-tax-v2 api-reference/banking-api/openapi.json POST /banking/cashout/tax/pay/v2 Generate a tax payment using the v2 endpoint # Check Pix Key Source: https://docs.trio.com.br/api-reference/banking-api/payments/transfer-pix/check-key api-reference/banking-api/openapi.json POST /banking/cashout/pix/keys/check Validate a Pix key before creating a payment (v1) # Generate a Pix Payment (v1) Source: https://docs.trio.com.br/api-reference/banking-api/payments/transfer-pix/generate-pix-payment-v1 api-reference/banking-api/openapi.json POST /banking/cashout/pix Generate a Pix payment using the v1 endpoint after using Check Key Endpoint # Generate a Pix Payment (v2) Source: https://docs.trio.com.br/api-reference/banking-api/payments/transfer-pix/generate-pix-payment-v2 api-reference/banking-api/openapi.json POST /banking/cashout/pix/v2 Generate a Pix payment using the v2 endpoint, pix key direct # Check Utility Source: https://docs.trio.com.br/api-reference/banking-api/payments/utility/check-utility api-reference/banking-api/openapi.json POST /banking/cashout/utility/check Check a utility barcode or line code # Pay Utility (v1) Source: https://docs.trio.com.br/api-reference/banking-api/payments/utility/pay-utility-v1 api-reference/banking-api/openapi.json POST /banking/cashout/utility/pay Generate a utility payment using the v1 endpoint # Pay Utility (v2) Source: https://docs.trio.com.br/api-reference/banking-api/payments/utility/pay-utility-v2 api-reference/banking-api/openapi.json POST /banking/cashout/utility/pay/v2 Generate a utility payment using the v2 endpoint # Authorize payment Source: https://docs.trio.com.br/api-reference/banking-api/receivables/biometrics/authorize-payment api-reference/banking-api/receivables/biometrics/openapi.json POST /banking/cashin/pix/biometrics/enrollments/{enrollment_id}/payments/{payment_id}/authorize Authorizes a payment using a FIDO assertion. # Create enrollment Source: https://docs.trio.com.br/api-reference/banking-api/receivables/biometrics/create-enrollment api-reference/banking-api/receivables/biometrics/openapi.json POST /banking/cashin/pix/biometrics/enrollments Creates a biometrics enrollment for a device in a participant. # Create payment from enrollment Source: https://docs.trio.com.br/api-reference/banking-api/receivables/biometrics/create-payment api-reference/banking-api/receivables/biometrics/openapi.json POST /banking/cashin/pix/biometrics/enrollments/{enrollment_id}/payments Creates a payment initiation for a biometrics enrollment. # Find or create device Source: https://docs.trio.com.br/api-reference/banking-api/receivables/biometrics/find-or-create-device api-reference/banking-api/receivables/biometrics/openapi.json POST /banking/cashin/pix/biometrics/devices Finds or creates a biometrics device associated with a counterparty. # Get payment authorization options Source: https://docs.trio.com.br/api-reference/banking-api/receivables/biometrics/get-authorization-options api-reference/banking-api/receivables/biometrics/openapi.json GET /banking/cashin/pix/biometrics/enrollments/{enrollment_id}/payments/{payment_id}/credentials Returns FIDO authorization options for a payment. # Get payment status Source: https://docs.trio.com.br/api-reference/banking-api/receivables/biometrics/get-payment api-reference/banking-api/receivables/biometrics/openapi.json GET /banking/cashin/pix/biometrics/enrollments/{enrollment_id}/payments/{payment_id} Returns the current status of a biometric payment. # Get enrollment registration options Source: https://docs.trio.com.br/api-reference/banking-api/receivables/biometrics/get-registration-options api-reference/banking-api/receivables/biometrics/openapi.json GET /banking/cashin/pix/biometrics/enrollments/{enrollment_id}/credentials Returns FIDO registration options for the enrollment. # List enrollments Source: https://docs.trio.com.br/api-reference/banking-api/receivables/biometrics/list-enrollments api-reference/banking-api/receivables/biometrics/openapi.json GET /banking/cashin/pix/biometrics/enrollments Retrieves a list of biometrics enrollments for a given device. # List participants Source: https://docs.trio.com.br/api-reference/banking-api/receivables/biometrics/list-participants api-reference/banking-api/receivables/biometrics/openapi.json GET /banking/cashin/pix/biometrics/participants Lists participants for a device with optional enrollment info. # Register enrollment credential Source: https://docs.trio.com.br/api-reference/banking-api/receivables/biometrics/register-credential api-reference/banking-api/receivables/biometrics/openapi.json POST /banking/cashin/pix/biometrics/enrollments/{enrollment_id}/register Registers a FIDO credential for the enrollment. # Cancel boleto Source: https://docs.trio.com.br/api-reference/banking-api/receivables/boletos/cancel api-reference/banking-api/openapi.json PUT /banking/cashin/boletos/{id}/cancel Cancel a boleto # Get boleto Source: https://docs.trio.com.br/api-reference/banking-api/receivables/boletos/get api-reference/banking-api/openapi.json GET /banking/cashin/boletos/{id} Get a boleto by ID # List boletos Source: https://docs.trio.com.br/api-reference/banking-api/receivables/boletos/list api-reference/banking-api/openapi.json GET /banking/cashin/boletos List all boletos # Create boleto Source: https://docs.trio.com.br/api-reference/banking-api/receivables/boletos/post api-reference/banking-api/openapi.json POST /banking/cashin/boletos Creates a boleto # Update boleto Source: https://docs.trio.com.br/api-reference/banking-api/receivables/boletos/update api-reference/banking-api/openapi.json PUT /banking/cashin/boletos/{id} Updates a boleto # Get dynamic QR code Source: https://docs.trio.com.br/api-reference/banking-api/receivables/qrcode-dynamic/get api-reference/banking-api/openapi.json GET /banking/cashin/pix/qrcodes/{id} Gets a dynamic QR code by ID # Get dynamic QR code hash Source: https://docs.trio.com.br/api-reference/banking-api/receivables/qrcode-dynamic/get-hash api-reference/banking-api/openapi.json GET /banking/cashin/pix/qrcodes/{id}/hash Gets a dynamic QR code hash by ID # Get dynamic QR code image Source: https://docs.trio.com.br/api-reference/banking-api/receivables/qrcode-dynamic/get-image api-reference/banking-api/openapi.json GET /banking/cashin/pix/qrcodes/{id}/image Gets a dynamic QR code image by ID # Create dynamic QR code Source: https://docs.trio.com.br/api-reference/banking-api/receivables/qrcode-dynamic/post api-reference/banking-api/openapi.json POST /banking/cashin/pix/qrcodes Creates a dynamic QR code # Get static QR code Source: https://docs.trio.com.br/api-reference/banking-api/receivables/qrcode-static/get api-reference/banking-api/openapi.json GET /banking/cashin/pix/qrcodes/static/{id} Gets a static QR code by ID # Get static QR code hash Source: https://docs.trio.com.br/api-reference/banking-api/receivables/qrcode-static/get-hash api-reference/banking-api/openapi.json GET /banking/cashin/pix/qrcodes/static/{id}/hash Gets a static QR code hash by ID # Get static QR code image Source: https://docs.trio.com.br/api-reference/banking-api/receivables/qrcode-static/get-image api-reference/banking-api/openapi.json GET /banking/cashin/pix/qrcodes/static/{id}/image Gets a static QR code image by ID # Create static QR code Source: https://docs.trio.com.br/api-reference/banking-api/receivables/qrcode-static/post api-reference/banking-api/openapi.json POST /banking/cashin/pix/qrcodes/static Creates a static QR code # Cancel Collection Source: https://docs.trio.com.br/api-reference/banking-api/receivables/recurrences/cancel-collection api-reference/banking-api/openapi.json POST /banking/cashin/pix/recurrences/collections/{id}/cancel Cancel recurrence collection # Cancel Recurrence Source: https://docs.trio.com.br/api-reference/banking-api/receivables/recurrences/cancel-recurrence api-reference/banking-api/openapi.json POST /banking/cashin/pix/recurrences/{id}/cancel Cancel recurrence by ID # Create Next Collection Source: https://docs.trio.com.br/api-reference/banking-api/receivables/recurrences/create-next-collection api-reference/banking-api/openapi.json POST /banking/cashin/pix/recurrences/collections/create_next_collection Create the next recurrence collection # Generate a Recurrence Source: https://docs.trio.com.br/api-reference/banking-api/receivables/recurrences/generate-recurrence api-reference/banking-api/openapi.json POST /banking/cashin/pix/recurrences Generate a recurrence # Get Collection Source: https://docs.trio.com.br/api-reference/banking-api/receivables/recurrences/get-collection api-reference/banking-api/openapi.json GET /banking/cashin/pix/recurrences/collections/{id} Get recurrence collection # Get Collection Attempt Source: https://docs.trio.com.br/api-reference/banking-api/receivables/recurrences/get-collection-attempt api-reference/banking-api/openapi.json GET /banking/cashin/pix/recurrences/collections/attempts/{id} Get recurrence collection attempt # Get Recurrence Source: https://docs.trio.com.br/api-reference/banking-api/receivables/recurrences/get-recurrence api-reference/banking-api/openapi.json GET /banking/cashin/pix/recurrences/{id} Get recurrence with stages # Get Recurrence Request Source: https://docs.trio.com.br/api-reference/banking-api/receivables/recurrences/get-recurrence-request api-reference/banking-api/openapi.json GET /banking/cashin/pix/recurrences/requests/{id} Get recurrence request # List Collection Attempts Source: https://docs.trio.com.br/api-reference/banking-api/receivables/recurrences/list-collection-attempts api-reference/banking-api/openapi.json GET /banking/cashin/pix/recurrences/collections/attempts List recurrence collection attempts with parameters # List Recurrence Collections Source: https://docs.trio.com.br/api-reference/banking-api/receivables/recurrences/list-recurrence-collections api-reference/banking-api/openapi.json GET /banking/cashin/pix/recurrences/collections List recurrence collections with parameters # List Recurrences Source: https://docs.trio.com.br/api-reference/banking-api/receivables/recurrences/list-recurrences api-reference/banking-api/openapi.json GET /banking/cashin/pix/recurrences List recurrences with parameters # Schedule Collection Source: https://docs.trio.com.br/api-reference/banking-api/receivables/recurrences/schedule-collection api-reference/banking-api/openapi.json POST /banking/cashin/pix/recurrences/collections/{id}/schedule Schedule collection # Update Collection Source: https://docs.trio.com.br/api-reference/banking-api/receivables/recurrences/update-collection api-reference/banking-api/openapi.json PUT /banking/cashin/pix/recurrences/collections/{id} Update recurrence collection # Refund Pix Source: https://docs.trio.com.br/api-reference/banking-api/receivables/refunds/post api-reference/banking-api/openapi.json POST /banking/cashin/documents/{id}/refund Refund a collecting document # Transfer Source: https://docs.trio.com.br/api-reference/banking-api/transfers/transfer api-reference/banking-api/openapi.json POST /banking/cashout/transfer Transfer amount between virtual accounts # Get Virtual Account Source: https://docs.trio.com.br/api-reference/banking-api/virtual-accounts/get-virtual-account api-reference/banking-api/openapi.json GET /banking/virtual_accounts/{id} Get a virtual account by ID # Get Virtual Account Balances Source: https://docs.trio.com.br/api-reference/banking-api/virtual-accounts/get-virtual-account-balances api-reference/banking-api/openapi.json GET /banking/virtual_accounts/{id}/balances Get balances for a virtual account # List Virtual Account Transactions Source: https://docs.trio.com.br/api-reference/banking-api/virtual-accounts/list-virtual-account-transactions api-reference/banking-api/openapi.json GET /banking/virtual_accounts/{id}/transactions List transactions for a virtual account # List Virtual Accounts Source: https://docs.trio.com.br/api-reference/banking-api/virtual-accounts/list-virtual-accounts api-reference/banking-api/openapi.json GET /banking/virtual_accounts List all virtual accounts # Update Virtual Account Source: https://docs.trio.com.br/api-reference/banking-api/virtual-accounts/update-virtual-account api-reference/banking-api/openapi.json PUT /banking/virtual_accounts/{id} Update a virtual account # Authentication Source: https://docs.trio.com.br/developers/authentication Trio uses [basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) to authenticate the API. You can create `sandbox` and `production` client secret keys in the developer console. We're also offering a company unique identifier to be used as username in the authentication process. Use your company unique identifier (client\_id) as username and generated secret key (client\_secret) as password to authenticate: ```text theme={null} curl https://api.sandbox.trio.com.br/banking/entities \ -H "Content-Type: application/json" \ -u {client_id}:{client_secret} ``` # Concepts Source: https://docs.trio.com.br/developers/concepts Before we get into on how to programmatically move money, it's important that you learn some core concepts and aspects of our API and how your business could fit within our solution. ### **Company** A company object represents a top-level structure from your business and can be composed by one or more legal entities. As a company, you are able to add multiple users with varying permissions, monitor API logs and so on. ### **Entity** The entity object represents a legal entity from your company, it represents a Brazilian entity with their own CNPJ. Each entity may hold one or more bank accounts. ### **Bank account** A bank account is a valid account that holds and moves money. Throughout our bank accounts, it is possible to look at balances, transactions and movement in real time. In order to move money within a bank account. ### **Virtual account** A virtual account is the core of everything we do at Trio. It's a layer below the standard bank account. It can receive incoming payments in place of a bank account, and divide up the balance of the linked bank account. Moreover, a virtual account reports its own balance and transactions. ### **Documents** A document can be interpreted as a transaction inside Trio. It can be a payment or collecting document. Every time that there is money movement in your account, this transaction will have a document representing it. # Date & Time Source: https://docs.trio.com.br/developers/date-and-time All dates and times managed and returned by our API are represented in the Coordinated Universal Time (UTC) timezone and adhere to the ISO 8601 format. [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) is an internationally recognized standard for representing date and time in a human-readable and machine-parsable manner. ### **Format** The ISO 8601 format for date and time representation follows this pattern: `YYYY-MM-DDTHH:mm:ssZ` Where: * YYYY represents the 4-digit year * MM represents the 2-digit month (01-12) * DD represents the 2-digit day of the month (01-31) * T is the separator between the date and time components * HH represents the 2-digit hour (00-23) * mm represents the 2-digit minute (00-59) * ss represents the 2-digit second (00-59) * Z indicates that the date and time are in the Coordinated Universal Time (UTC) #### **Example** An example of a date and time represented in the ISO 8601 format: `2023-03-21T14:30:00Z` This represents the date and time: March 21, 2023, 14:30:00 (UTC). # Environments Source: https://docs.trio.com.br/developers/environments In order to better serve your development team and facilitate a smooth development and testing process, we offer two distinct environments: `production` and `sandbox`. Each environment has its own base URL, which is used when making API requests. ### **Production Environment** The `production` environment is the live environment where your application will interact with our API when it is deployed and running for end users. This environment provides access to real data and should be used with care to prevent unintended actions or data manipulation. #### **Base URL:** > [https://api.trio.com.br](https://api.trio.com.br) ### **Sandbox Environment** The `sandbox` environment is a separate, isolated environment designed specifically for development, testing, and experimentation purposes. This environment allows your development team to work with our API without affecting real data or causing unintended consequences in the production environment. #### **Base URL:** > [https://api.sandbox.trio.com.br](https://api.sandbox.trio.com.br) ### **Switching Between Environments** When developing your application, it is crucial to ensure that the appropriate base URL is used for each environment. Typically, this can be achieved by using environment-specific configuration files or environment variables. When transitioning from development and testing to deployment, make sure to update your application's configuration to use the production environment's base URL. This ensures that your application interacts with the correct environment and real data when it is live. # Error table Source: https://docs.trio.com.br/developers/error-table We try to handle the errors and mistakes beautifully as possible. So we use HTTP codes convention to group the errors: * `2xx` status codes confirm that your request worked as expected * `4xx` status codes indicate that the request failed due some invalid information or a validation error * `5xx` status codes are use when something went wrong at Trio servers and systems. To better error handling during the integration, we always return the errors in the response body using the following fields: Example for credentials erros ```json theme={null} { "error": "Invalid credentials" } ``` All erros example ```json theme={null} { "error": { "error_code": "UNAUTHORIZED_RESOURCE", "error_message": "Resource being accessed is unauthorized." } } ``` ### HTTP status codes summary
CodeTypeDescription
200SuccessEverything worked as expected.
201SuccessResource created successfully.
204SuccessEverything worked as expected with empty body
400Bad requestRequest returned an error, detail in content.
401UnauthorizedInvalid authentication credentials.
404Not FoundThe requested resource was not found.
408TimeoutThe request timed out and was terminated by the server.
429Too Many RequestsToo many concurrent requests
500Server ErrorSomething went wrong in Trio's infrastructure.
### General error handling
CodeStatusMessage
TRIO\_SERVICE\_UNAVAILABLE503Serviço indisponível
TRIO\_SERVICE\_REQUEST\_TIMED\_OUT408Timeout
TRIO\_SERVICE\_REQUEST\_METHOD\_FORBIDDEN405Método não permitido
ALREADY\_EXISTS\_RESOURCE400Já existe um para a referência informada.
INVALID\_RESOURCE400 é inválido.
NOT\_FOUND\_RESOURCE404 não foi encontrado.
INVALID\_PARAMETER400Campo é inválido.
REQUIRED\_PARAMETER400Campo é obrigatório.
### Authentication error handling | Code | Status | Message | | ----------------------------- | ------ | ----------------------- | | UNAUTHORIZED\_RESOURCE | 403 | Recurso não autorizado | | TRIO\_CLIENT\_SECRET\_INVALID | 401 | Client secret inválida. | | TRIO\_CLIENT\_ID\_INVALID | 404 | Client id inválida. | ### Integrations error handling
CodeStatusMessage
INTEGRATION\_ERROR500Ocorreu um erro inesperado na integração bancária.
INTEGRATION\_TIMEOUT408O tempo de integração bancária foi maior que o esperado.
### Business error handling
CodeStatusMessage
ENTITY\_IN\_ANALYSIS404Entidade está em análise, aguarde a aprovação. Referência: #.
ENTITY\_INVALID\_CURRENCY400Moeda da transação diferente da informada na entidade. Utilize a moeda #.
ENTITY\_INVALID\_ADDRESS404Entidade não possui endereço válido. Referência: #.
BANK\_ACCOUNT\_IN\_ANALYSIS404Conta bancária está em análise, aguarde a aprovação. Referência: #.
BANK\_ACCOUNT\_DAILY\_TRANS\_LIMIT\_REACHED400Limite diário de transações atingido.
BANK\_ACCOUNT\_DAILY\_AMOUNT\_LIMIT\_REACHED400Limite diário de valor de transações atingido.
BANK\_ACCOUNT\_OVERNIGHT\_TRANS\_LIMIT\_REACHED400Limite noturno de transações atingido.
BANK\_ACCOUNT\_OVERNIGHT\_AMOUNT\_LIMIT\_REACHED400Limite noturo de valor de transações atingido.
BANK\_ACCOUNT\_MIN\_SINGLE\_TRANS\_AMOUNT\_REACHED400Limite mínimo do valor da transação não foi atingido.
BANK\_ACCOUNT\_MAX\_SINGLE\_TRANS\_AMOUNT\_REACHED400Limite máximo do valor da transação atingido.
BANK\_ACCOUNT\_MAX\_COUNTERPARTY\_TRANS\_REACHED400Limite diário de transações para uma contrapartida atingido.
BANK\_ACCOUNT\_MAX\_COUNTERPARTY\_AMOUNT\_REACHED400Limite diário de valor de transações para uma contrapartida atingido.
PIX\_KEY\_CANCELED400Chave Pix está cancelada. Referência: #.
PIX\_KEY\_CONFIRMED400Chave Pix já foi confirmada. Referência: #.
PIX\_KEY\_ALREADY\_EXISTS400Já existe uma chave Pix criada ou confirmada. Referência: #.
PIX\_KEY\_INVALID\_KEY400--
PIX\_KEY\_REQUIRED400A chave deve ser informada quando o tipo é 'random\_key'.
PIX\_KEY\_INVALID\_TYPE400O tipo deve ser: 'tax\_number', 'email', 'phone' ou 'random\_key.'
PIX\_KEY\_CONFIRMATION\_TYPE\_INVALID400Confirmação com código deve ser executada somente para chaves Pix do tipo: 'email' ou 'phone'.
PIX\_KEY\_PENDING404Chave Pix não foi confirmada. Referência: #.
COLLECTING\_DOCUMENT\_NOT\_SETTLED400Documento de recebimento não está liquidado. Referência: #.
COLLECTING\_DOCUMENT\_WITHOUT\_BALANCE400Valor da devolução #, maior que o saldo # do documento de recebimento.
PAYMENT\_BRCODE\_ALREADY\_USED400Brcode #, já possui um documento vinculado #.
PAYMENT\_AMOUNT\_ERROR400Valor de pagamento # deve ser igual ao valor do brcode #, valor #.
PAYMENT\_ACCOUNT\_WITHOUT\_BALANCE400Saldo insuficiente para executar o pagamento. Saldo atual #.
QUERY\_LIMIT\_REACHED400Limite de consultas atingido. Tente novamente em 1 minuto.
KEY\_NOT\_FOUND404Chave Pix não foi encontrada. Referência: .
BRCODE\_NOT\_FOUND404Brcode não foi encontrado. Referência: .
KEY\_NOT\_FOUND\_MULTI\_ATTEMPTS404Chave Pix não foi encontrada. Crie a chave e tente novamente em 1 hora. Referência: .
VIRTUAL\_TRANSFER\_DIFFERENT\_BANK\_ACCOUNT400Conta bancária das contas virtuais origem e destino são diferentes. Para transferências virtuais devem ser a mesma.
# Pagination Source: https://docs.trio.com.br/developers/pagination In order to enhance the performance of our API and to ensure the scalability and stability of our services, we use cursor-based pagination for navigating large data sets. This document will guide you through the process of understanding and implementing cursor-based pagination for our API. ### **Cursor-based Pagination** Cursor-based pagination allows for efficient traversal through large data sets by using a pointer (a.k.a. cursor) to a specific item in the data set. Instead of relying on numbered pages, cursor-based pagination focuses on a unique identifier for each item, making it possible to fetch subsequent items without duplicating or missing any results. ### **How It Works** When making a request to an API endpoint that supports pagination, the API will return a set of results along with two cursor values and one helper variable: * `after`: A value that points to the next item in the data set. * `before`: A value that points to the previous item in the data set. * `has_next`: Indicate if the next cursor has value in the data set. By default our endpoints have a max limit of 50 records per page. These cursor values can then be passed as query parameters in the subsequent API requests to fetch the next or previous set of results. They are mutually exclusive, meaning that only one of them can be set at the time to iterate through the results. ```text theme={null} curl https://api.sandbox.trio.com.br/banking/cashin/documents?after=g3QAAAACZAACaWRtAAAAJGQyNmE3YTVmLTVlOTAtNDdkZS1hNmM5LWQyNzM1NDA4OTNmOGQAEHRyYW5zYWN0aW9uX2RhdGV0AAAADWQACl9fc3RydWN0X19kAA9FbGl4aXIuRGF0ZVRpbWVkAAhjYWxlbmRhcmQAE0VsaXhpci5DYWxlbmRhci5JU09kAANkYXlhCmQABGhvdXJhDGQAC21pY3Jvc2Vjb25kaAJhAGEGZAAGbWludXRlYThkAAVtb250aGEKZAAGc2Vjb25kYTpkAApzdGRfb2Zmc2V0YQBkAAl0aW1lX3pvbmVtAAAAB0V0Yy9VVENkAAp1dGNfb2Zmc2V0YQBkAAR5ZWFyYgAAB-ZkAAl6b25lX2FiYnJtAAAAA1VUQw== \ -H "Content-Type: application/json" \ -u {client_id}:{client_secret} ``` The cursor values are encapsulated at `metadata` object on responses that supports pagination. The `metadata` and will look like this: ```text theme={null} { "data": "", "metadata": { "before": null, "after": "g3QAAAACZAACaWRtAAAAJGQyNmE3YTVmLTVlOTAtNDdkZS1hNmM5LWQyNzM1NDA4OTNmOGQAEHRyYW5zYWN0aW9uX2RhdGV0AAAADWQACl9fc3RydWN0X19kAA9FbGl4aXIuRGF0ZVRpbWVkAAhjYWxlbmRhcmQAE0VsaXhpci5DYWxlbmRhci5JU09kAANkYXlhCmQABGhvdXJhDGQAC21pY3Jvc2Vjb25kaAJhAGEGZAAGbWludXRlYThkAAVtb250aGEKZAAGc2Vjb25kYTpkAApzdGRfb2Zmc2V0YQBkAAl0aW1lX3pvbmVtAAAAB0V0Yy9VVENkAAp1dGNfb2Zmc2V0YQBkAAR5ZWFyYgAAB-ZkAAl6b25lX2FiYnJtAAAAA1VUQw==", "has_next": true } } ``` # Rate limit Source: https://docs.trio.com.br/developers/rate-limit There are some rate limiting policies implemented in our API to ensure fair usage and prevent abuse. It is important to understand and respect these rate limits when interacting with our API to avoid disruptions in service. ### **Default Rate Limits** Our API enforces the following default rate limits: * Production environment: 60 requests per second * Sandbox environment: 5 requests per second These limits apply to each individual account and **to each endpoint**, and are enforced on a per-second basis. ### **Rate Limit Exceeded** When an account exceeds the allowed rate limit, our API will respond with a `429` status code, indicating that the rate limit has been reached. This response will be accompanied by a message in the body, providing more information about the exceeded rate limit. #### **Example** A sample response when the rate limit has been exceeded: ```text theme={null} HTTP/1.1 429 Too Many Requests Content-Type: application/json { "error": "Rate limit exceeded", "message": "You have reached the maximum allowed requests per second. If you need more bandwidth request to our support team." } ``` ### **Handling Rate Limit Exceeded Errors** When receiving a `429` status code in response to an API request, it is crucial to implement a back-off strategy in your application. This may include: * Retrying the request after a short delay * Implementing an exponential back-off algorithm to gradually increase the delay between retries * Using a queue system to manage requests and distribute them evenly over time By implementing a back-off strategy, you can ensure that your application gracefully handles rate limit exceeded errors and continues to function correctly. ### **Upgrading Rate Limits** If your application requires a higher rate limit, you may be eligible for an upgrade. Please contact our support team to discuss your requirements and explore the available options for increasing your account's rate limits. # Request identification Source: https://docs.trio.com.br/developers/request-identification Request identifiers are unique values associated with each API request, allowing for efficient tracking and troubleshooting of individual requests. ### **Request Identifier** Each API request made to our service is assigned a unique request identifier. This identifier can be found in the response headers under the `X-Request-Id` key. Additionally, the request identifiers are present in the URLs of individual request logs in your [app](https://app.sandbox.trio.com.br/developers/logs). #### **Example** ```text theme={null} X-Request-Id: GEzmrWO6-L7HK28FP0eD ``` ### **Contacting Support** **If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.** By including the request identifier in your support query, our support team can quickly locate and investigate the specific request in question. This enables us to efficiently diagnose any issues, provide insights, and offer guidance or solutions to resolve your concerns. When contacting support, please include the following information: * The request identifier (found in the X-Request-Id header or the development console) * A description of the issue you are experiencing * Any relevant code snippets or additional details that may help with the investigation Remember to always include the request identifier to expedite the resolution process and ensure a swift and effective response from our support team. # FAQ — Sandbox and Production Integration Source: https://docs.trio.com.br/faq Frequently asked questions about Sandbox setup, credentials, webhooks, PIX testing, API limits, compliance rules, and Production onboarding. # FAQ — Sandbox and Production Integration This FAQ covers the most common questions about the Trio integration, including **Sandbox setup, API credentials, Virtual Accounts, webhooks, PIX testing, rate limits, compliance rules, and Production onboarding**. > **Tip:** Before starting the integration, we recommend reading the [Trio Guides](https://docs.trio.com.br/guides) and our [Integration Best Practices](https://docs.trio.com.br/operations/best_practices_for_integration). *** ## Sandbox ### How do I get the Sandbox `client_id` and `client_secret`? Sandbox API credentials are created by your team directly through the **Sandbox Internet Banking**. Trio does not generate or provide these credentials manually. Your team needs to: 1. Create an organization in the Sandbox. 2. Access the Sandbox Internet Banking. 3. Create the API credentials. 4. Use the generated credentials for API authentication. For more information, see the [Sandbox Account Guide](https://docs.trio.com.br/guides/sandbox_account). *** ### Where can I find the Sandbox Virtual Account ID? The **Virtual Account ID** is available in the Sandbox Internet Banking. After creating your organization: 1. Go to **Accounts**. 2. Select the bank account you want to use. 3. Open the account details. 4. Find the account identifier, which is the `virtual_account_id`. This ID is required for operations such as PIX Cash-in testing. *** ## Webhooks ### How do I create and configure a Sandbox webhook? The complete process for creating a webhook is available in our guide: [Creating Your First Webhook](https://docs.trio.com.br/guides/creating-your-first-webhook) The same concepts apply to both Sandbox and Production, but each environment must be configured separately. *** ### Where can I get the webhook secret? The webhook secret is generated when you create the webhook through the Internet Banking. The secret is used to validate the authenticity of webhook requests received by your system. For details about webhook authentication and signatures, see: [Webhook Authentication](https://docs.trio.com.br/webhooks/authentication) *** ### 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 to be added to your allowlist (whitelist), use the following: | Environment | Trio IP | | ----------- | ----------------------- | | Production | `Shared after contract` | | Sandbox | `34.194.173.207` | *** ### What is the webhook retry policy? Trio has a retry mechanism for failed webhook deliveries. If a webhook delivery fails, our system will retry the delivery up to **5 times**. The retry interval increases after each failure: | Retry | Delay | | ------------------ | ----------------------------: | | 1st retry | 16 seconds | | 2nd retry | 32 seconds | | 3rd retry | 104 seconds | | 4th retry | 208 seconds | | Additional retries | According to the retry policy | Your webhook endpoint should be designed to safely handle **duplicate events**. We recommend implementing **idempotency** in your webhook processing to prevent the same event from being processed more than once. *** ## PIX Cash-in Testing ### How can I simulate a successful PIX payment in Sandbox? You can simulate a successful PIX deposit using the procedure described in our guide: [Simulating Deposit Success](https://docs.trio.com.br/guides/simulating-deposit-success) *** ### How can I simulate a failed PIX payment in Sandbox? You can simulate failed PIX deposits using the following guide: [Simulating Deposit Failures](https://docs.trio.com.br/guides/simulating-deposit-failures) *** ### Where can I understand the PIX transaction status flow? Understanding the document lifecycle is important when implementing PIX Cash-in and other transaction flows. We recommend reading: [Document Lifecycle](https://docs.trio.com.br/guides/document-lifecycle) It is also important to follow our recommended integration practices: [Integration Best Practices — Final Summary](https://docs.trio.com.br/operations/best_practices_for_integration#final-summary) *** ## API Rate Limits ### What are the API rate limits? The API rate limits are: | Environment | Rate Limit | | ----------- | -------------------: | | Production | `60 requests/second` | | Sandbox | `5 requests/second` | These limits apply to **each individual account and each endpoint** and are enforced on a per-second basis. *** ### What should I do when I reach the API rate limit? When a rate limit is reached, we recommend implementing a **retry and backoff strategy**. Avoid continuously retrying requests without waiting between attempts. A backoff strategy helps reduce unnecessary requests and prevents repeated rate-limit errors. *** ## PIX Cash-in Compliance ### Which PIX Cash-in compliance rules can be configured? The following rules can be configured directly through the Internet Banking: * 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). These settings can be reviewed and configured according to the requirements of your Virtual Account. *** ## Production ### How do I get Production credentials and Virtual Account IDs? Production access is provided after the contract has been signed with the **Trio Commercial Team**. After receiving access to the Production Internet Banking, your team can: * Create the Production API credentials. * Create and manage Virtual Accounts. * Obtain the corresponding Virtual Account IDs. * Configure Production webhooks. Production credentials and Sandbox credentials are managed separately. *** ### Are Production and Sandbox webhook secrets different? Yes. **Sandbox and Production are completely separate environments.** You must configure your webhooks separately in each environment, and each environment has its own webhook configuration and secret. A Sandbox webhook secret should not be used in Production. *** ### Is there a Production certification or go-live checklist? After the contract is signed and the compliance validation is completed by the Trio team, your engineering team should validate the complete integration flow before going live. At minimum, we recommend validating: * PIX Cash-in. * Cash-out. * Webhook delivery. * Webhook signature validation. * Transaction status updates. * Document lifecycle handling. * Error handling. * Retry and idempotency behavior. For the recommended integration approach, see: [Integration Best Practices](https://docs.trio.com.br/operations/best_practices_for_integration) *** ## Additional Resources For more detailed information, check the following resources: ### Guides [Trio Guides](https://docs.trio.com.br/guides) Step-by-step guides covering common integration scenarios. ### Integration Best Practices [Integration Best Practices](https://docs.trio.com.br/operations/best_practices_for_integration) Recommended practices for building and maintaining a reliable integration. ### API Documentation [Trio API Documentation](https://docs.trio.com.br/) Complete documentation including: * Getting Started * Guides * API Reference * Webhooks * Authentication * Transaction lifecycle > **Recommended reading:** We strongly recommend reviewing the documentation before starting the Production integration. Most common integration questions and configuration details are covered in the guides and API reference. # Plan your Integration Source: https://docs.trio.com.br/getting_started/plan-your-integration Integrating with Trio allows you to accept payments, receive payouts, and seamlessly reconcile your accounts. With **Trio Checkout**, you can easily create a payment flow—either embedding it directly on your website or hosting it on Trio’s platform. Our APIs provide a **secure and efficient** way to process payments in Brazil, while the **Trio Dashboard (internet banking)** centralizes reporting, giving you **real-time visibility** into charges, fees, refunds, and transfers. To get started, simply [**log in**](https://app.trio.com.br/) or [**register**](https://onboarding.trio.com.br/) for a Trio account. ### **Get started** While a Trio integration can be completed in as little as **one week**, the timeline may vary depending on the complexity of your internal systems. For businesses with additional integration requirements, the process can take anywhere from **less than a week to up to three months**. Key factors influencing this timeline include: * **Engineering resources** available for development and testing; * **Integration with internal systems** such as ERP or accounting platforms; * **Change management** across impacted teams. Understanding these dependencies will help you plan a smooth and efficient integration. ### **Suggested Schedule** Image Image # Support Source: https://docs.trio.com.br/getting_started/support Trio provides multiple support channels to assist you during integration, operational usage, and incident handling. You can contact our team through: * Our support portal: [suporte.trio.com.br](http://suporte.trio.com.br); * Email: [suporte@trio.com.br](mailto:suporte@trio.com.br). *** # Support Availability ## Operational Support ### Availability ```text theme={null} 24 hours a day, 7 days a week (24/7) ``` This includes: * Operational incidents; * Transaction verification; * Financial reconciliation assistance; * Emergency support; * Instability reports. *** ## Integration Support Our integration team is available during business hours only. ### Availability | Region | Working Hours | | -------------- | -------------------------------- | | Brazil (UTC-3) | Monday to Friday, 09:00 to 18:00 | Integration support includes: * API integration guidance; * Webhook implementation questions; * Sandbox assistance; * Technical troubleshooting; * Integration best practices. *** # User Manual A complete user manual is also available for operational guidance and platform usage instructions. * User Manual: [https://suporte.trio.com.br/manual-de-uso-trio](https://suporte.trio.com.br/manual-de-uso-trio) The manual includes: * Internet banking usage; * Operational procedures; * Account management; * Financial operations guidance; *** # Reporting Issues When reporting bugs or unexpected behaviors, please provide as much context as possible, including: * Request payloads; * Transaction identifiers; * `external_id`; * Error messages; * Webhook payloads; * Approximate timestamps; * Environment used (`sandbox` or `production`). Providing detailed information helps our team investigate and resolve issues faster. *** # Response Process After your request is submitted: 1. Your case will be registered by our support team; 2. The appropriate internal team will review the request; 3. You will receive follow-up communication as soon as possible. Our 24/7 support team maintains an average response and resolution time of less than 5 minutes from the moment the request is submitted. # Invoice & Wallet Type Source: https://docs.trio.com.br/guides/boleto-types Invoice Type & Wallet Type When issuing a boleto, there are two fields used to classify the payment: * **Invoice Type**: identifies **which document or obligation originated the charge**. * **Wallet Type**: identifies **how the boleto will be registered and managed by the bank**. Although both fields are used when issuing boletos, they serve different purposes. *** # Invoice Type The **Invoice Type** represents the **type of document that originated the charge**. In other words, it describes **the reason the boleto was issued**, such as an invoice, tax invoice, school fee, or duplicate. ## Most commonly used types | Value | Description | | ---------------------- | ---------------------------------- | | `invoice` | Fatura | | `invoice_note` | Nota Fiscal | | `receipt` | Recibo | | `commercial_duplicate` | Duplicata Mercantil | | `service_duplicate` | Duplicata de Prestação de Serviços | | `promissory_note` | Nota Promissória | | `school_fee` | Mensalidade Escolar | | `condominium_fee` | Taxa de Condomínio | | `credit_card` | Fatura de Cartão de Crédito | | `others` | Outros | > If there is no specific type that matches your charge, use `others`. ## All Invoice Types | Value | Description | | -------------------------------- | ----------------------------------- | | `commercial_duplicate` | Duplicata Mercantil | | `indicated_commercial_duplicate` | Duplicata Mercantil por Indicação | | `service_duplicate` | Duplicata de Prestação de Serviços | | `indicated_service_duplicate` | Duplicata de Serviços por Indicação | | `rural_duplicate` | Duplicata Rural | | `bill_of_exchange` | Letra de Câmbio | | `commercial_credit_note` | Nota de Crédito Comercial | | `export_credit_note` | Nota de Crédito à Exportação | | `industrial_credit_note` | Nota de Crédito Industrial | | `rural_credit_note` | Nota de Crédito Rural | | `promissory_note` | Nota Promissória | | `rural_promissory_note` | Nota Promissória Rural | | `triplicate_commercial` | Triplicata Mercantil | | `triplicate_service` | Triplicata de Serviços | | `insurance_note` | Nota de Seguro | | `receipt` | Recibo | | `invoice` | Fatura | | `debit_note` | Nota de Débito | | `insurance_policy` | Apólice de Seguro | | `school_fee` | Mensalidade Escolar | | `consortium_installment` | Parcela de Consórcio | | `invoice_note` | Nota Fiscal | | `debt_document` | Documento de Dívida | | `rural_product_certificate` | Cédula de Produto Rural (CPR) | | `warrant` | Warrant | | `state_active_debt` | Dívida Ativa Estadual | | `municipal_active_debt` | Dívida Ativa Municipal | | `federal_active_debt` | Dívida Ativa Federal | | `condominium_fee` | Taxa de Condomínio | | `credit_card` | Fatura de Cartão de Crédito | | `others` | Outros | *** # Wallet Type The **Wallet Type** (Collection Wallet) defines **the operational method used by the bank to register, issue, and manage the boleto**. This field **does not change the information displayed to the payer**. It is only used to tell the bank how the boleto should be processed. ## Default value By default, use the following value: | Value | Description | | -------------------------------- | ----------------------------------------- | | `book_entry_electronic_bloquete` | Carteira Escritural Eletrônica (Bloquete) | ## All Wallet Types | Value | Description | | ------------------------------------------------------ | ------------------------------------------------------------ | | `direct_electronic_partial_emission_booklet` | Cobrança Direta Eletrônica com emissão parcial de boleto | | `book_entry_electronic_booklet` | Carteira Escritural Eletrônica (Boleto) | | `direct_electronic_with_emission_booklet` | Cobrança Direta Eletrônica com emissão do boleto | | `direct_electronic_no_emission_block_client` | Cobrança Direta Eletrônica sem emissão (cliente emite) | | `direct_electronic_no_emission_block_us` | Cobrança Direta Eletrônica sem emissão (modalidade do banco) | | `book_entry_electronic_bloquete` | Carteira Escritural Eletrônica (Bloquete) | | `direct_electronic_no_emission_block_client2` | Cobrança Direta Eletrônica sem emissão (variante) | | `direct_electronic_partial_emission_bloquete` | Cobrança Direta Eletrônica com emissão parcial (Bloquete) | | `direct_electronic_with_emission_bloquete` | Cobrança Direta Eletrônica com emissão (Bloquete) | | `direct_electronic_no_emission_us_emission` | Cobrança Direta Eletrônica sem emissão (variante) | | `direct_electronic_our_number_emission_banks_bloquete` | Banco responsável pela geração do Nosso Número (Bloquete) | | `direct_electronic_our_number_emission_banks_booklet` | Banco responsável pela geração do Nosso Número (Boleto) | *** # Cash in Source: https://docs.trio.com.br/guides/cash-in The term **Cash In** refers to all incoming transactions or deposits into an account — for example, when a Dynamic QR Code is generated and successfully paid. Now that you are familiar with the core concepts such as QR Codes, Entities, Organizations, Bank Accounts, and Virtual Accounts, you can generate your first Dynamic QR Code using the Trio API. *** ## Before You Start With your API credentials already generated, we recommend reviewing the API Reference for Dynamic QR Code creation, where all request parameters, attributes, and behaviors are fully documented. Documentation: [https://docs.trio.com.br/api\_reference/banking-api/collecting/dynamic-qr-codes#post-banking-cashin-pix-qrcodes](https://docs.trio.com.br/api_reference/banking-api/collecting/dynamic-qr-codes#post-banking-cashin-pix-qrcodes) To help you get started faster, the example below demonstrates a real Dynamic QR Code creation request using the Sandbox API. *** ## Endpoint ```http theme={null} POST https://api.sandbox.trio.com.br/banking/cashin/pix/qrcodes ``` *** ## Request Example ```json theme={null} { "virtual_account_id": "0196346c-ffa2-e861-be85-3c2736d0005f", "counterparty": { "tax_number": "12385407400", "name": "Payer Name" }, "amount": 320000, "external_id": "{{$randomUUID}}", "description": "Pay in Sandbox", "options": { "show_qrcode_image": false } } ``` ### Field Description * `virtual_account_id`: ID of the Virtual Account that will receive the funds. Always use the Virtual Account ID, not the Bank Account ID; * `counterparty`: payer information, including tax number and name; * `amount`: transaction amount in cents (`10000` = BRL 100.00); * `external_id`: external transaction identifier used for reconciliation and webhook tracking; * `description`: transaction description; * `options.show_qrcode_image`: when set to `true`, the API also returns the QR Code image in Base64 format. *** ## Response Example ```json theme={null} { "data": { "id": "0192bebb-fbdb-b6f3-6be1-7153e373b609", "status": "created", "timestamp": "2024-10-24T13:34:03.739892Z", "description": "Pago a trio.com.br", "hash": "00020101021226790014br.gov.bcb.pix2557brcode-h.trio.com.br/check/cob/01JAZBQYYVPVSPQRBHAFHQ7DG95204000053039865802BR5906BRCODE6008Curitiba62070503***6304736E", "amount": { "currency": "BRL", "amount": 100 }, "external_id": "49d754c2-ac14-4219-bbe4-3e78e9ab8067", "stages": [ { "id": "0192bebb-fbdb-3375-5e39-90152c82abeb", "timestamp": "2024-10-24T13:34:03.739892Z", "type": "created" } ], "virtual_account_id": "019296ff-1f72-2ad7-0201-41de08355fda", "origin_id": "01929738-5e7e-46d1-d8af-ea9629302b80", "origin_type": "api_client", "counterparty_id": "0013ebcc-d457-e4f8-0079-4e996002d082", "pix_key_id": "019296ff-1f94-ecec-2220-96bfd06e8e59", "expiration_datetime": null, "allow_change_the_amount_on_payment": false } } ``` *** ## Using Pix Copy and Paste If the QR Code image was not requested, you can use the `hash` field returned by the API. This value represents the Pix “Copy and Paste” payload that can be shared directly with the payer. *** ## Learn More For additional details about Dynamic QR Code creation, including all attributes, response structures, and error messages, refer to the API Reference: [https://docs.trio.com.br/api\_reference/banking-api/collecting/dynamic-qr-codes#post-banking-cashin-pix-qrcodes](https://docs.trio.com.br/api_reference/banking-api/collecting/dynamic-qr-codes#post-banking-cashin-pix-qrcodes) # Cash out Source: https://docs.trio.com.br/guides/cash-out Cash Out operations represent outgoing transfers from your Virtual Account, allowing you to perform payments and withdrawals directly through the Trio API. Compared to QR Code generation, Cash Out operations are simpler and require fewer parameters, making them ideal for automated payouts and transfers. The most important requirement is informing the `virtual_account_id` that will be debited during the transaction. *** ## Documentation For complete details about Cash Out operations, refer to the official API Reference: [Generate a Pix Payment (v2)](https://docs.trio.com.br/api-reference/banking-api/payments/transfer-pix/generate-pix-payment-v2) ## Cash Out Example The example below demonstrates a Cash Out request using the Sandbox environment. ### Endpoint ```http theme={null} POST https://api.sandbox.trio.com.br/banking/cashout/pix/v2 ``` *** ## Request Body ```json theme={null} { "virtual_account_id": "{{virtual_account_id_out}}", "type": "key", "reference": "*5541900000000", "external_id": "{{$randomUUID}}", "amount": 50000, "description": "Withdrawal test" } ``` ### Field Description * `virtual_account_id`: ID of the Virtual Account that will be debited; * `type`: destination payment type: * `key` → Pix Key payment; * `bank_account` → direct bank account transfer; * `brcode` → Pix Copy and Paste payment; * `reference`: destination Pix Key, such as CPF, CNPJ, email, phone number, or random key; * `external_id`: external transaction identifier used for reconciliation and webhook tracking; * `amount`: transaction amount in cents (`10000` = BRL 100.00); * `description`: transaction description stored for history and reporting purposes. *** ## Successful Response After the request is processed, the API immediately returns a transaction identifier (`payment_document_id`). This identifier can be used to track the transaction status through webhooks or by querying the payment endpoint directly. ```json theme={null} { "data": { "payment_document_id": "41234d60-f6a9-4c9c-8cc3-5769ce9bbea2" } } ``` *** After creation, the transaction status can be monitored through webhook notifications or direct payment status queries using the returned `payment_document_id`. # Create Boleto Source: https://docs.trio.com.br/guides/create-boleto Guide to create boleto Create a boleto receivable by defining the charge, payer, payment conditions, and boleto configuration. This guide focuses on the **request body** and explains how each part of the boleto works, especially the payment rules such as discounts, fines, and interest. > All examples use fictitious data. # Request body A boleto request is mainly composed of: ```text theme={null} Boleto │ ├── Charge │ ├── amount │ ├── description │ └── external_id │ ├── Payer │ └── counterparty │ ├── Payment conditions │ └── due_detail │ ├── due_date │ ├── discount │ ├── fine │ └── interest │ ├── Boleto configuration │ ├── virtual_account_id │ ├── expiration_date │ ├── invoice_type │ └── wallet_type │ └── Optional ├── notes ``` The following example shows a complete boleto: ```json theme={null} { "description": "Mensalidade agosto", "amount": 10000, "external_id": "boleto-demo-2026-001", "virtual_account_id": "019f0000-1234-5678-9abc-000000000001", "counterparty": { "name": "Maria Silva", "state": "SP", "address": "Rua das Flores, 100", "city": "Sao Paulo", "tax_number": "12345678901", "district": "Centro", "postal_code": "01001000" }, "expiration_date": "2026-10-30", "invoice_type": "invoice", "wallet_type": "book_entry_electronic_bloquete", "notes": null, "due_detail": { "due_date": "2026-08-17", "fine": { "amount": 150, "calculation_type": "percentage" }, "interest": { "amount": 300, "calculation_type": "monthly_fee" }, "discount": { "fixed_until_due": { "amounts": [ { "amount": 500, "date": "2026-08-16" } ], "calculation_type": "percentage" } } } } ``` This example represents a **R\$ 100.00** boleto with: * due date on August 17, 2026; * 5% discount until August 16; * 1.5% fine after the due date; * 3% monthly interest after the due date. # Charge The charge section defines what is being collected and how your system identifies the boleto. ## `amount` Defines the boleto amount. The value is sent in **cents**. ```json theme={null} "amount": 10000 ``` means: ```text theme={null} R$ 100.00 ``` Examples: ```text theme={null} 1500 → R$ 15.00 10000 → R$ 100.00 402 → R$ 4.02 ``` This is the original amount of the boleto. Discounts, fines, and interest are payment conditions that can change the amount the customer must pay depending on when the boleto is paid. *** ## `description` A short description of the charge. ```json theme={null} "description": "Mensalidade agosto" ``` Use it to identify what the customer is being charged for. For example: ```text theme={null} Mensalidade agosto Pedido 12345 Plano Premium Serviço de consultoria ``` *** ## `external_id` An identifier generated by your own system. ```json theme={null} "external_id": "boleto-demo-2026-001" ``` It does not replace the Trio boleto ID. Instead, it allows your system to associate the boleto with an internal record. For example: ```text theme={null} Your system │ ├── Order: 12345 ├── Invoice: 2026-08-001 └── external_id: boleto-demo-2026-001 │ ▼ Trio boleto ``` This is particularly useful for reconciliation. # Payer The `counterparty` object identifies the person or company that will pay the boleto. ```json theme={null} "counterparty": { "name": "Maria Silva", "state": "SP", "address": "Rua das Flores, 100", "city": "Sao Paulo", "tax_number": "12345678901", "district": "Centro", "postal_code": "01001000" } ``` The fields describe the payer: | Field | What it represents | | ------------- | ------------------------- | | `name` | Payer's name | | `tax_number` | CPF or CNPJ | | `address` | Street and address number | | `city` | Payer's city | | `state` | Brazilian state | | `district` | Neighborhood | | `postal_code` | CEP | The information should correspond to the actual payer associated with the boleto. # Payment conditions The `due_detail` object is where the main payment rules are configured. ```json theme={null} "due_detail": { "due_date": "2026-08-17", "discount": {}, "fine": {}, "interest": {} } ``` It controls what happens **before, on, and after the due date**. ```text theme={null} BOLETO Before due date │ ▼ Discount │ ▼ Due date │ ┌────────┴────────┐ │ │ Payment Late payment │ ┌─────┴─────┐ ▼ ▼ Fine Interest ``` # Due date ## `due_detail.due_date` Defines the date on which the boleto becomes due. ```json theme={null} "due_date": "2026-08-17" ``` In this example: ```text theme={null} Due date = August 17, 2026 ``` The due date is the reference point for the payment rules. Before this date, a discount may apply. After this date, the configured fine and interest may apply. # Discounts A discount is a benefit given to the customer for paying before the due date. Discounts are configured inside: ```json theme={null} "due_detail": { "discount": {} } ``` The API supports two discount models: ```text theme={null} fixed_until_due per_day_antecipated ``` ## Fixed discount before the due date Use `fixed_until_due` when you want to define a specific discount for one or more dates before the due date. Example: ```json theme={null} "discount": { "fixed_until_due": { "amounts": [ { "amount": 500, "date": "2026-08-16" } ], "calculation_type": "percentage" } } ``` Here: ```text theme={null} amount = 500 calculation_type = percentage ``` means **5%**. For a R\$ 100.00 boleto: ```text theme={null} Original amount R$ 100.00 Discount 5% Discount value R$ 5.00 Amount to pay R$ 95.00 ``` The discount is available on the configured date. ### Different discounts for different dates You can define multiple discount dates: ```json theme={null} "fixed_until_due": { "amounts": [ { "amount": 500, "date": "2026-08-14" }, { "amount": 300, "date": "2026-08-15" }, { "amount": 100, "date": "2026-08-16" } ], "calculation_type": "percentage" } ``` This represents: ```text theme={null} Aug 14 → 5% discount Aug 15 → 3% discount Aug 16 → 1% discount Aug 17 → Due date ``` This model is useful when the discount becomes smaller as the due date approaches. *** ## Discount per anticipated day The `per_day_antecipated` model calculates the discount based on how early the customer pays. Example: ```json theme={null} "discount": { "per_day_antecipated": { "amount": 100, "calculation_days": "calendar", "calculation_type": "percentage" } } ``` Here: * `amount` defines the discount value; * `calculation_type` defines whether the value is an amount or percentage; * `calculation_days` defines how days are counted. The available day calculation modes are: ```text theme={null} working calendar ``` Use `working` for working days or `calendar` for calendar days. *** ## Discount calculation type The discount can be calculated as: ```text theme={null} amount percentage ``` ### Percentage ```json theme={null} "calculation_type": "percentage" ``` The value represents a percentage. For example: ```json theme={null} "amount": 500 ``` means: ```text theme={null} 5% ``` ### Fixed amount ```json theme={null} "calculation_type": "amount" ``` The value represents a monetary amount. # Fine The fine is a penalty applied when the boleto is paid after the due date. It is configured with: ```json theme={null} "fine": { "amount": 150, "calculation_type": "percentage" } ``` There are two calculation types: ```text theme={null} amount percentage ``` ## Percentage fine ```json theme={null} "amount": 150, "calculation_type": "percentage" ``` represents a **1.5% fine**. For a R\$ 100.00 boleto: ```text theme={null} Original amount: R$ 100.00 Fine: 1.5% Fine amount: R$ 1.50 ``` ## Fixed fine ```json theme={null} "amount": 150, "calculation_type": "amount" ``` represents a fixed monetary fine. The important distinction is: ```text theme={null} percentage → percentage of the boleto amount amount → fixed monetary value ``` # Interest Interest is another charge that can apply after the due date. It is configured with: ```json theme={null} "interest": { "amount": 300, "calculation_type": "monthly_fee" } ``` The available calculation types are: ```text theme={null} daily_rate monthly_fee exempt bank_control ``` Each type determines how the interest value is interpreted. ## Daily interest ```json theme={null} "interest": { "amount": 10, "calculation_type": "daily_rate" } ``` The interest is configured as a daily rate. ## Monthly interest ```json theme={null} "interest": { "amount": 300, "calculation_type": "monthly_fee" } ``` Here: ```text theme={null} 300 + monthly_fee ``` represents **3% per month**. For a R\$ 100.00 boleto, the configured monthly interest rate is: ```text theme={null} 3% per month ``` ## Exempt from interest ```json theme={null} "interest": { "amount": 0, "calculation_type": "exempt" } ``` Indicates that interest is exempt. ## Bank-controlled interest ```json theme={null} "interest": { "amount": 0, "calculation_type": "bank_control" } ``` The interest calculation follows the bank-controlled configuration. # Fine vs. interest Fine and interest are different concepts. ### Fine A penalty for paying after the due date. ```text theme={null} Late payment │ └── Fine ``` ### Interest A charge related to the period the payment remains overdue. ```text theme={null} Late payment │ └── Interest │ └── Based on the configured rate ``` They can be configured together. For example: ```json theme={null} "fine": { "amount": 150, "calculation_type": "percentage" }, "interest": { "amount": 300, "calculation_type": "monthly_fee" } ``` means: ```text theme={null} Fine → 1.5% Interest → 3% monthly ``` # Boleto expiration ## `expiration_date` Defines the boleto expiration date. ```json theme={null} "expiration_date": "2026-10-30" ``` This should be understood separately from the due date. ```text theme={null} due_date │ └── Payment due date expiration_date │ └── Boleto expiration ``` For example: ```json theme={null} "due_detail": { "due_date": "2026-08-17" }, "expiration_date": "2026-10-30" ``` The boleto is due on August 17, while its expiration is October 30. # Receiving account ## `virtual_account_id` Identifies the virtual account associated with the boleto. ```json theme={null} "virtual_account_id": "019f0000-1234-5678-9abc-000000000001" ``` This is the virtual account that is associated with the boleto receivable. Always make sure the selected virtual account is the account intended to receive the payment. # Boleto type The request contains two fields that define the boleto configuration: ```json theme={null} "invoice_type": "invoice", "wallet_type": "book_entry_electronic_bloquete" ``` These fields determine the type of document and wallet used for the boleto. Because there are multiple possible values and the correct combination depends on the boleto use case, the complete explanation is maintained in a dedicated guide. **For details about `invoice_type` and `wallet_type`, open the [Boleto Types](/guides/boleto-types) guide.** There you can find: * available `invoice_type` values; * available `wallet_type` values; * what each option represents; * when each type should be used; * examples of different boleto configurations. # Notes ## `notes` Optional additional information associated with the boleto. Example: ```json theme={null} "notes": [ "Customer reference", "Monthly subscription" ] ``` If there are no notes: ```json theme={null} "notes": null ``` Use notes for additional information that does not need to be part of the main charge description. # Example: complete payment configuration Suppose you want to create a boleto with: ```text theme={null} Amount: R$ 100.00 Due date: 17/08/2026 Discount: 5% until 16/08/2026 Fine after due date: 1.5% Interest: 3% monthly ``` The payment rules are: ```json theme={null} "due_detail": { "due_date": "2026-08-17", "discount": { "fixed_until_due": { "amounts": [ { "amount": 500, "date": "2026-08-16" } ], "calculation_type": "percentage" } }, "fine": { "amount": 150, "calculation_type": "percentage" }, "interest": { "amount": 300, "calculation_type": "monthly_fee" } } ``` The resulting behavior can be understood as: ```text theme={null} R$ 100.00 │ ┌───────────┴───────────┐ │ │ Pay before due Pay after due │ │ 5% discount 1.5% fine │ + 3% monthly │ interest ▼ ▼ R$ 95.00* Updated amount ``` `*` Assuming the 5% discount applies on the payment date and no other charge applies. # Complete request example ```json theme={null} { "description": "Mensalidade agosto", "amount": 10000, "external_id": "boleto-demo-2026-001", "virtual_account_id": "019f0000-1234-5678-9abc-000000000001", "counterparty": { "name": "Maria Silva", "state": "SP", "address": "Rua das Flores, 100", "city": "Sao Paulo", "tax_number": "12345678901", "district": "Centro", "postal_code": "01001000" }, "expiration_date": "2026-10-30", "invoice_type": "invoice", "wallet_type": "book_entry_electronic_bloquete", "notes": null, "due_detail": { "due_date": "2026-08-17", "fine": { "amount": 150, "calculation_type": "percentage" }, "interest": { "amount": 300, "calculation_type": "monthly_fee" }, "discount": { "fixed_until_due": { "amounts": [ { "amount": 500, "date": "2026-08-16" } ], "calculation_type": "percentage" } } } } ``` In this request: | Field | Meaning | | -------------------- | ---------------------------------------------- | | `amount` | Original boleto value: R\$ 100.00 | | `description` | Description of the charge | | `external_id` | Internal reference from the client system | | `virtual_account_id` | Virtual account associated with the receivable | | `counterparty` | Payer information | | `due_date` | Payment due date | | `discount` | Early-payment benefit | | `fine` | Late-payment penalty | | `interest` | Late-payment interest | | `expiration_date` | Boleto expiration | | `invoice_type` | Document type | | `wallet_type` | Boleto wallet configuration | | `notes` | Optional additional information | For more information about the document and wallet configuration, see the [Boleto Types](/guides/boleto-types) guide. # First API Credential Source: https://docs.trio.com.br/guides/creating-your-first-api-credential After accessing the Trio App, you can create your API credentials by following the steps below: 1. In the lower-left menu, click the **Settings** icon; Image (21) 2. In the dropdown menu, select **“API Keys”**; Image (22) 3. Click **“Create Key”**; Image (23) 4. Enter a name or identifier for the credential; Image (24) 5. Define whether the credential will have **Read and Write** or **Read-Only** permissions; 6. Configure the **allowed IP addresses** for the credential. You must register the IP address of the server responsible for making API requests and processing transactions. If you have any questions regarding this configuration, please contact Trio Support. Example configuration: Image (25) 7. Click **“Save Key”**; 8. Enter your password and OTP code; Image (26) 9. Store the Secret Key in a secure location, then click **Confirm** and **Go to Key Details**; Image (27) 10. Save the Client ID displayed on the next screen; Image (28) Your API credentials are now generated and ready to use. To authenticate with the API, use the Client ID and Secret Key as described in the authentication documentation: [https://docs.trio.com.br/developers/authentication](https://docs.trio.com.br/developers/authentication) # First Webhook Source: https://docs.trio.com.br/guides/creating-your-first-webhook *** Webhooks allow Trio to notify your application whenever an event occurs, eliminating the need to constantly poll the API for updates. To create your first webhook, follow the steps below. 1. In the lower-left menu, click the **Settings** icon; Image 2. In the dropdown menu, select **"Webhooks"**; Image 3. Click **"Create Webhook"**; Image 4. Fill in the **Notification URL**. Image This is the HTTPS endpoint where Trio will deliver webhook notifications. Make sure your endpoint is publicly accessible and capable of receiving HTTP POST requests. 5. (Optional) Select an **Entity**. Image If you leave this field empty, the webhook will receive events from **all entities** in your account. If you select a specific entity, the webhook will only receive events related to that entity. 6. (Optional) Select a **Bank Account**. Image After selecting an Entity, you can further filter notifications by choosing one of its Bank Accounts. Only events generated by that Bank Account will be delivered to this webhook. 7. Select the **Events that will trigger the webhook**. Image Choose the event types your application should receive. For most Pix integrations, the recommended events are: * **Payment Document** (Pix Cash Out) * **Collecting Document** (Pix Cash In) You can also subscribe to any other events that are relevant to your integration. 8. Enter a **Secret**. Image You can also subscribe to any other events that are relevant to your integration. Enter a Secret. Choose any secret value that only your application knows. This value is used by Trio to generate a unique signing key for your webhook. Whenever a webhook is delivered, Trio includes HTTP header: x-webhook-signature – contains the HMAC-SHA256 signature of the request body. Your application should compute the HMAC-SHA256 hash of the received payload using the webhook signing key available in the webhook details page, then compare it with the value received in x-webhook-signature. If both signatures match, you can safely verify that: * the request was sent by Trio; * the payload was not modified during transmission. 9. Click **Save Webhook**. Image 10. Save the webhook secret in details Image Your webhook is now active and ready to receive notifications. For more information about webhook payloads, events, and signature validation, see the Webhooks documentation. [Webhook Documentation](/webhooks/introduction) # Document Lifecycle Source: https://docs.trio.com.br/guides/document-lifecycle Every payout processed by Trio goes through a sequence of stages that represent the transaction lifecycle in our system. ### Transaction Statuses * **Created** — The transaction was received and queued for processing. * **Confirmed** — The settlement process has started. * **Settled** — The transaction was successfully processed and settled. The balance is deducted from your account. This is a final status. * **Failed** — The transaction could not be processed due to invalid information or because it was rejected by the bank. This is a final status. ### Transaction Flow The following diagram illustrates the transaction flow: ```mermaid theme={null} flowchart LR A[Created] --> B[Confirmed] B --> C[Settled] B --> D[Failed] ``` **Final statuses:** `Settled` and `Failed`. Once a payout reaches a final status, its lifecycle is complete. # Pix biometrics API (web) Source: https://docs.trio.com.br/guides/pix-biometrics-web Pix biometrics allows your customers to authorize Pix payments using biometric authentication (WebAuthn/FIDO) instead of being redirected to their bank app each time. The customer authorizes once at their bank to create an **enrollment**, registers their biometric credential, and from that point on can authorize payments with a fingerprint or face scan directly in your application. The flow consists of two main phases: 1. **Enrollment** — a one-time setup where the customer links their bank account and registers a biometric credential. 2. **Payment** — creating and authorizing payments using the registered biometric credential. > All examples use the **sandbox** environment (`https://api.sandbox.trio.com.br`). In production, use `https://api.trio.com.br`. *** ### Endpoints | Action | Method | Endpoint | | ------------------------- | ------ | ---------------------------------------------------------------------------------------------- | | Find or create device | `POST` | `/banking/cashin/pix/biometrics/devices` | | List participants | `GET` | `/banking/cashin/pix/biometrics/participants` | | List enrollments | `GET` | `/banking/cashin/pix/biometrics/enrollments` | | Create enrollment | `POST` | `/banking/cashin/pix/biometrics/enrollments` | | Get registration options | `GET` | `/banking/cashin/pix/biometrics/enrollments/{enrollment_id}/credentials` | | Register FIDO credential | `POST` | `/banking/cashin/pix/biometrics/enrollments/{enrollment_id}/register` | | Create payment | `POST` | `/banking/cashin/pix/biometrics/enrollments/{enrollment_id}/payments` | | Get payment | `GET` | `/banking/cashin/pix/biometrics/enrollments/{enrollment_id}/payments/{payment_id}` | | Get authorization options | `GET` | `/banking/cashin/pix/biometrics/enrollments/{enrollment_id}/payments/{payment_id}/credentials` | | Authorize payment | `POST` | `/banking/cashin/pix/biometrics/enrollments/{enrollment_id}/payments/{payment_id}/authorize` | For complete endpoint documentation, see the [Biometrics API Reference](/api-reference/banking-api/receivables/biometrics/find-or-create-device). *** ## Step 1: Device Setup Before interacting with the biometrics API, you need to identify the customer's device. Collect the device information using a fingerprinting library such as [FingerprintJS](https://fingerprint.com/) and send it to the API. The device must support biometric authentication for this flow to work. You can verify this on the frontend before proceeding: ```js theme={null} async function isBiometricsAvailable() { if (!window.PublicKeyCredential) return false; try { return await PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable(); } catch { return false; } } // Usage const supported = await isBiometricsAvailable(); if (!supported) { // Show a message that biometric authentication is not available on this device } ``` ### Create Device ```http theme={null} POST https://api.sandbox.trio.com.br/banking/cashin/pix/biometrics/devices ``` ```json theme={null} { "fingerprint": "a1b2c3d4e5f6", "os": "iOS", "os_version": "17.4", "language": "pt-BR", "screen_width": 390, "screen_height": 844, "counterparty_tax_number": "12345678900", "counterparty_name": "Maria Silva", "account_tenure": "2023-01-15", "timezone_offset": "-03:00", "load_enrollments": true } ``` The `load_enrollments` parameter, when set to `true`, includes the device's existing enrollments in the response. This is useful to determine if the customer already has an active enrollment and can skip directly to the payment flow. If the device already exists (matched by `fingerprint` and `counterparty_tax_number`), the existing device is returned. For complete request and response details, see the [Find or Create Device](/api-reference/banking-api/receivables/biometrics/find-or-create-device) API reference. *** ## Step 2: List Participants Retrieve the list of available banking participants (institutions) that support biometric enrollment. Each participant represents a bank the customer can enroll with. By providing the `device_id` from Step 1, the response also indicates whether the customer already has an active enrollment with each participant — so you can determine the next step: * **Already enrolled** → skip to [Payment Creation](#step-4-create-payment) * **Not enrolled** → proceed to [Enrollment Registration](#step-3-enrollment-registration) ```http theme={null} GET https://api.sandbox.trio.com.br/banking/cashin/pix/biometrics/participants?device_id={device_id} ``` Without a `device_id`, only the participant list is returned (no enrollment info). You can also fetch enrollments separately via [List Enrollments](/api-reference/banking-api/receivables/biometrics/list-enrollments) and match them on your end — useful if you want to cache the participant list (which is the same for every user) and only fetch enrollments per device. > Participants are synchronized hourly with the Open Finance environment, and unstable participants are proactively disabled. If you choose to cache the participant list, be aware it may become out of sync. For complete response details, see the [List Participants](/api-reference/banking-api/receivables/biometrics/list-participants) API reference. *** ## Step 3: Enrollment Registration When a customer selects a participant and has no active enrollment for that device, you need to create one. This is a one-time process per participant per device\_id. ### 3.1 Create Enrollment ```http theme={null} POST https://api.sandbox.trio.com.br/banking/cashin/pix/biometrics/enrollments ``` ```json theme={null} { "device_id": "000e2ac2-840c-ccb3-0add-9132af7e300d", "participant_id": "019f9bca-a3e0-3fba-a997-f31ae2c0c40b", "return_to_url": "https://yourapp.com/enrollment/complete", "external_id": "your-internal-reference-123", "account_info": { "ispb": "12345678", "issuer": "0001", "number": "123456", "account_type": "CACC" } } ``` **Parameters:** * `device_id` — the device ID from Step 1 * `participant_id` — the participant chosen by the customer * `return_to_url` — where to redirect after biometric registration is complete * `external_id` — (optional) your internal reference * `account_info` — (optional) suggested bank account. The bank may accept or ignore this suggestion. If the bank returns a different account, the enrollment will be blocked The response includes a `redirect_url`. **Redirect the customer to this URL** to start the bank authorization flow. For complete details, see the [Create Enrollment](/api-reference/banking-api/receivables/biometrics/create-enrollment) API reference. ### 3.2 Bank Authorization After redirecting, the customer authorizes the enrollment in their banking app. During this step: 1. The customer is redirected to their bank 2. The customer authorizes the biometric enrollment 3. The bank redirects the customer to Trio's whitelabel biometric registration page 4. The customer registers their biometric credential (fingerprint or face) 5. After completion, the customer is redirected to your `return_to_url` > The biometric registration (WebAuthn) is restricted to Trio's domain due to security requirements, so this step is handled automatically through a whitelabel page. ### 3.3 Enrollment Webhooks Listen for enrollment status webhooks with the category `pix_biometrics_enrollment`: **Authorized** — the enrollment is ready for payments: ```json theme={null} { "data": { "id": "000e2ac2-840c-f37c-80a8-48bfa57d2338", "status": "authorized", "inserted_at": "2026-07-26T23:18:01.931556Z", "updated_at": "2026-07-26T23:18:41.884626Z", "external_id": "your-internal-reference-123", "redirect_url": "https://...", "expiration_datetime": null, "participant_id": "019f9bca-a3e0-3fba-a997-f31ae2c0c40b", "device_id": "000e2ac2-840c-ccb3-0add-9132af7e300d", "account_info": null }, "timestamp": "2026-07-26T23:18:42.213037Z", "type": "authorized", "category": "pix_biometrics_enrollment", "ref_id": "000e2ac2-840c-f37c-80a8-48bfa57d2338" } ``` Once you receive the `authorized` webhook, the enrollment is complete and you can create payments. ### Enrollment Lifecycle | Status | Description | | ------------------------------------ | --------------------------------------------------------------------------------- | | `awaiting_account_holder_validation` | Enrollment created, waiting for customer to authorize at bank | | `awaiting_enrollment` | Bank authorization completed, waiting for registering biometrics on Trio's domain | | `authorized` | Enrollment is active and ready for payments | | `rejected` | Bank rejected the enrollment | | `revoked` | Customer revoked the enrollment on the bank's end | | `inactive` | Enrollment expired | *** ## Step 4: Create Payment Once the customer has an active enrollment, you can create payments that will be authorized using their biometric credential. ### 4.1 Create Payment from Enrollment Using the `enrollment_id` from the active enrollment, create a payment: ```http theme={null} POST https://api.sandbox.trio.com.br/banking/cashin/pix/biometrics/enrollments/{enrollment_id}/payments ``` ```json theme={null} { "entity_id": "019f9fbf-2c55-8e72-2fcd-0017e7303e00", "virtual_account_id": "019f9fbf-2c57-3533-9ffc-f34868af636a", "amount": 1500, "description": "Order #12345", "external_id": "payment-ref-456" } ``` **Required fields:** * `entity_id` — your entity ID * `virtual_account_id` — the virtual account that will receive the funds * `amount` — amount in cents (e.g., `1500` = BRL 15.00) * `description` — payment description **Optional fields:** * `external_id` — your internal reference for reconciliation For complete details, see the [Create Payment](/api-reference/banking-api/receivables/biometrics/create-payment) API reference. ### 4.2 Get Authorization Options Retrieve the FIDO authorization options needed for the WebAuthn authentication: ```http theme={null} GET https://api.sandbox.trio.com.br/banking/cashin/pix/biometrics/enrollments/{enrollment_id}/payments/{payment_id}/credentials ``` The response contains a `public_key_encoded` value — a JSON-encoded string with the WebAuthn `publicKeyCredentialRequestOptions`. You will pass this to the auth widget in the next step. For details, see the [Get Authorization Options](/api-reference/banking-api/receivables/biometrics/get-authorization-options) API reference. *** ## Step 5: Authorize Payment with Biometrics To authorize the payment, the customer must perform a WebAuthn authentication using Trio's auth widget iframe. This iframe overlay handles the `credentials.get` WebAuthn operation on Trio's domain. ### 5.1 Set Up the Auth Widget Embed the iframe positioned over a button element in your page: ```html theme={null}
``` The iframe is transparent and overlays the button, so when the customer clicks "Authorize Payment", the click is captured by the iframe and triggers the WebAuthn operation. > The `allow` attribute is required for WebAuthn to work inside the iframe. ### 5.2 Communication Protocol The widget communicates via `postMessage`. All messages from the widget include `source: "trio-biometrics-sdk"`. **1. Wait for the iframe to load:** ```js theme={null} const iframe = document.getElementById("trio-auth"); window.addEventListener("message", (e) => { if (e.data?.source !== "trio-biometrics-sdk") return; switch (e.data.type) { case "loaded": // iframe is ready — send the authorization options iframe.contentWindow.postMessage({ action: "get", options: publicKeyOptions, // public_key_encoded from Step 4.2 requestId: "payment-auth-1" }, "*"); break; case "ready": // widget is waiting for user click break; case "success": // send e.data.credential to authorize the payment (Step 5.3) authorizePayment(e.data.credential); break; case "error": console.error("WebAuthn error:", e.data.error, e.data.message); break; } }); ``` **2. The customer clicks the button.** The WebAuthn prompt appears (fingerprint scanner, face recognition, etc.). **3. On success**, the widget returns the FIDO assertion credential in `e.data.credential`. ### 5.3 Send the Authorization Take the credential from the widget response and send it to authorize the payment: ```http theme={null} POST https://api.sandbox.trio.com.br/banking/cashin/pix/biometrics/enrollments/{enrollment_id}/payments/{payment_id}/authorize ``` ```json theme={null} { "fido_assertion": { "id": "credential-id", "raw_id": "base64url-encoded-raw-id", "type": "public-key", "response": { "authenticator_data": "base64url-encoded", "client_data_json": "base64url-encoded", "signature": "base64url-encoded", "user_handle": "base64url-encoded" } } } ``` For complete details, see the [Authorize Payment](/api-reference/banking-api/receivables/biometrics/authorize-payment) API reference. *** ## Payment Webhooks After creating a payment, you will receive `initiation_document` webhooks for each status change. The initiation document works similarly to a QR code — it's the initiation method for a Pix transaction. It carries all the status updates and will ultimately trigger a regular Pix transaction webhook as well. To validate the settlement, you should listen to Pix cash-in webhooks, as they are the ones that actually confirm SPI has processed the transaction. All payment webhooks share the same `initiation_document` category and include the full payment data. The `type` field indicates the current status. ### Payment Lifecycle | Status | Description | | ------------------ | ----------------------------------------------------------------- | | `created` | Payment created, waiting for biometric authorization | | `awaiting_consent` | Waiting for the customer to authorize via biometrics | | `awaiting_payment` | Biometric authorization completed, bank is processing the payment | | `settled` | Payment completed successfully (final) | | `failed` | Payment failed (final) | | `rejected` | Payment was rejected by the participant (final) | ### Webhook Examples #### initiation\_document — created ```json theme={null} { "data": { "id": "019fa156-a7e1-35f9-670b-acc72e2eaeff", "status": "created", "amount": { "currency": "BRL", "amount": 1000 }, "session_id": null, "inserted_at": "2026-07-27T02:10:38.800558Z", "updated_at": "2026-07-27T02:10:38.800558Z", "external_id": "my-external-ref-001", "end_to_end_id": "E12345678202607270210vcUjWGmFBGo", "transaction_date": "2026-07-27T02:10:38.689111Z", "virtual_account_id": "01991648-0f53-cd50-b24f-0003b45b45f9", "redirect_url": null, "origin_id": "019f9b20-65fd-c516-da43-95843e4d0881", "origin_type": "api_client", "ref_id": "000e2ac2-840c-f37c-80a8-48bfa57d2338", "entity_id": "01991647-e564-c2eb-bd8c-07682cfa7d13", "ref_type": "enrollment", "counterparty_id": "000e2ac2-840c-fd63-9b04-c43e6c6ed4e2", "reconciliation_id": "019fa156-a7e1-8dd8-9ff7-5fa03bd7af72", "integration_id": "019fa156-a7e1-cfb2-4b48-327f88bf55b2", "participant_id": "019f9bca-a3e0-3fba-a997-f31ae2c0c40b", "consent_id": null }, "timestamp": "2026-07-27T02:10:38.689043Z", "type": "created", "category": "initiation_document", "ref_id": "019fa156-a7e1-35f9-670b-acc72e2eaeff", "context_type": "internet_banking", "context_id": "926b0dac-b5e9-43cd-ae79-ba55c33e124a" } ``` #### initiation\_document — awaiting\_consent The payment is waiting for the customer to authorize via biometrics (WebAuthn). ```json theme={null} { "data": { "id": "019fa156-a7e1-35f9-670b-acc72e2eaeff", "status": "awaiting_consent", "amount": { "currency": "BRL", "amount": 1000 }, "external_id": "my-external-ref-001", "end_to_end_id": "E12345678202607270210vcUjWGmFBGo", "transaction_date": "2026-07-27T02:10:38.689111Z", "virtual_account_id": "01991648-0f53-cd50-b24f-0003b45b45f9", "origin_id": "019f9b20-65fd-c516-da43-95843e4d0881", "origin_type": "api_client", "ref_id": "000e2ac2-840c-f37c-80a8-48bfa57d2338", "entity_id": "01991647-e564-c2eb-bd8c-07682cfa7d13", "ref_type": "enrollment", "counterparty_id": "000e2ac2-840c-fd63-9b04-c43e6c6ed4e2", "reconciliation_id": "019fa156-a7e1-8dd8-9ff7-5fa03bd7af72", "participant_id": "019f9bca-a3e0-3fba-a997-f31ae2c0c40b", "consent_id": null }, "timestamp": "2026-07-27T02:10:38.689043Z", "type": "awaiting_consent", "category": "initiation_document", "ref_id": "019fa156-a7e1-35f9-670b-acc72e2eaeff", "context_type": "internet_banking", "context_id": "926b0dac-b5e9-43cd-ae79-ba55c33e124a" } ``` #### initiation\_document — awaiting\_payment Biometric authorization is complete. The bank is processing the payment. ```json theme={null} { "data": { "id": "019fa156-a7e1-35f9-670b-acc72e2eaeff", "status": "awaiting_payment", "amount": { "currency": "BRL", "amount": 1000 }, "external_id": "my-external-ref-001", "end_to_end_id": "E12345678202607270210vcUjWGmFBGo", "transaction_date": "2026-07-27T02:10:38.689111Z", "virtual_account_id": "01991648-0f53-cd50-b24f-0003b45b45f9", "origin_id": "019f9b20-65fd-c516-da43-95843e4d0881", "origin_type": "api_client", "ref_id": "000e2ac2-840c-f37c-80a8-48bfa57d2338", "entity_id": "01991647-e564-c2eb-bd8c-07682cfa7d13", "ref_type": "enrollment", "counterparty_id": "000e2ac2-840c-fd63-9b04-c43e6c6ed4e2", "reconciliation_id": "019fa156-a7e1-8dd8-9ff7-5fa03bd7af72", "participant_id": "019f9bca-a3e0-3fba-a997-f31ae2c0c40b", "consent_id": null }, "timestamp": "2026-07-27T02:10:38.689043Z", "type": "awaiting_payment", "category": "initiation_document", "ref_id": "019fa156-a7e1-35f9-670b-acc72e2eaeff", "context_type": "internet_banking", "context_id": "926b0dac-b5e9-43cd-ae79-ba55c33e124a" } ``` #### initiation\_document — settled Payment completed successfully. Funds have been transferred. ```json theme={null} { "data": { "id": "019fa156-a7e1-35f9-670b-acc72e2eaeff", "status": "settled", "amount": { "currency": "BRL", "amount": 1000 }, "external_id": "my-external-ref-001", "end_to_end_id": "E12345678202607270210vcUjWGmFBGo", "transaction_date": "2026-07-27T02:10:38.689111Z", "virtual_account_id": "01991648-0f53-cd50-b24f-0003b45b45f9", "origin_id": "019f9b20-65fd-c516-da43-95843e4d0881", "origin_type": "api_client", "ref_id": "000e2ac2-840c-f37c-80a8-48bfa57d2338", "entity_id": "01991647-e564-c2eb-bd8c-07682cfa7d13", "ref_type": "enrollment", "counterparty_id": "000e2ac2-840c-fd63-9b04-c43e6c6ed4e2", "reconciliation_id": "019fa156-a7e1-8dd8-9ff7-5fa03bd7af72", "participant_id": "019f9bca-a3e0-3fba-a997-f31ae2c0c40b", "consent_id": "019fa158-8065-eb54-986e-6aa7c8f9609e" }, "timestamp": "2026-07-27T02:10:38.689043Z", "type": "settled", "category": "initiation_document", "ref_id": "019fa156-a7e1-35f9-670b-acc72e2eaeff", "context_type": "internet_banking", "context_id": "926b0dac-b5e9-43cd-ae79-ba55c33e124a" } ``` *** ## End-to-End Flow Summary | Step | Action | Who | Endpoint / Action | | ---- | ------------------------------ | ------------- | --------------------------------------------------------------- | | 1 | Collect device fingerprint | Your frontend | FingerprintJS or similar | | 2 | Find or create device | Your backend | `POST /banking/cashin/pix/biometrics/devices` | | 3 | List participants | Your backend | `GET /banking/cashin/pix/biometrics/participants` | | 4a | Create enrollment (first time) | Your backend | `POST /banking/cashin/pix/biometrics/enrollments` | | 4b | Customer authorizes at bank | Customer | Redirect to `redirect_url` | | 4c | Biometric registration | Customer | Trio whitelabel page (automatic) | | 5 | Create payment | Your backend | `POST /banking/cashin/pix/biometrics/enrollments/{id}/payments` | | 6 | Get authorization options | Your backend | `GET .../payments/{id}/credentials` | | 7 | Customer authorizes payment | Customer | Auth widget (WebAuthn) | | 8 | Submit authorization | Your backend | `POST .../payments/{id}/authorize` | | 9 | Receive settlement webhook | Your backend | Webhook listener | Steps 4a–4c only happen once per participant. After enrollment, the customer goes directly from step 5 onwards for subsequent payments. # QR codes Types Source: https://docs.trio.com.br/guides/qr-codes QR Codes in the Pix ecosystem provide a fast, secure, and efficient way to process payments and collections. There are two primary categories of Pix QR Codes: **Static QR Codes** and **Dynamic QR Codes**. As most Trio customers are online merchants and PSPs, this guide focuses on the use of Dynamic QR Codes for automated integrations. *** ## Static QR Code A Static QR Code contains fixed payment information that does not change between transactions. It is recommended for recurring or standardized payments where the amount and payment details remain the same. ### Main Characteristics * Fixed and reusable payment information; * Suitable for recurring collections; * Can be permanently displayed or printed. *** ## Dynamic QR Code A Dynamic QR Code is uniquely generated for each transaction and contains transaction-specific information. It is recommended for e-commerce platforms, PSPs, and automated payment flows. ### Main Characteristics * Unique transaction information for each payment; * Supports custom identifiers and metadata; * Enables automated reconciliation and tracking. *** # Generating a Dynamic QR Code To generate a Dynamic QR Code, you must provide the required transaction information, including: * `virtual_account_id`: the virtual account that will receive the funds; * `external_id`: your internal transaction reference; * `amount`: transaction amount in cents (example: `1200` = BRL 12.00); * `counterparty`: payer information, including `tax_number` and `name`; * `expiration_datetime`: QR Code expiration date in ISO 8601 format. The default expiration time is 1 day, and the minimum allowed expiration time is 5 minutes. *** ## Create QR Code Endpoint To generate a Dynamic QR Code, send a `POST` request to the endpoint below: ```http theme={null} POST https://api.sandbox.trio.com.br/banking/cashin/pix/qrcodes ``` Example request payload: ```json theme={null} { "virtual_account_id": "018af380-cedc-3a53-29c0-e329bf0e109b", "counterparty": { "tax_number": "70004764005", "name": "Jhon Doe" }, "amount": 1200, "external_id": "01HBSXY7GN8V6NHJ51Z0NX8QK9", "description": "Pay in Sandbox", "expiration_datetime": "2023-10-04T20:00:00.000000Z", "options": { "allow_change_the_amount_on_payment": false, "show_qrcode_image": false } } ``` *** ## Successful Response If the request is successfully processed, the API will return a `201 Created` response similar to the example below: ```json theme={null} { "data": { "allow_change_the_amount_on_payment": false, "amount": { "amount": 1200, "currency": "BRL" }, "bank_account_id": "018af380-ced7-436a-b118-1cf3bd54243f", "counterparty_id": "018af3e0-63b4-d4fc-9c84-459314081895", "description": "Pay in Sandbox", "entity_id": "018af380-789f-4c52-fb8a-8160ad66182a", "expiration_datetime": "2023-10-04T20:00:00.000000Z", "external_id": "01HBSXY7GN8V6NHJ51Z0NX8QK9", "hash": "00020101021126640014br.gov.bcb.pix0114041715452853610224018afba3-4924-6ed6-7847-520400005303986540412.05802BR5907Capstan6008Curitiba61088025010462070503***63043277", "id": "018afba3-491b-4fd2-e8e2-edee87faab18", "pix_key_id": "018af380-eb7e-93a9-4b9f-c08af1d7772f", "status": "created", "timestamp": "2023-10-04T17:01:36.923773Z", "virtual_account_id": "018af380-cedc-3a53-29c0-e329bf0e109b" } } ``` *** # Payment Methods After generating the QR Code, you can provide the payment information to the user using: * **Pix Copy and Paste**: send the generated `hash` value so the user can paste it into their banking application; * **QR Code Image**: generate a QR Code image using the `hash` value so the user can scan it with their banking application. *** # Document Lifecycle Each QR Code transaction progresses through the following lifecycle stages: * `created`: transaction received and queued for processing; * `registering`: transaction is being processed; * `settled`: transaction successfully processed and settled (final state); * `failed`: transaction refused due to validation or compliance rules (final state for cash out). Follow a diagram that represents the flow: Image (29) *** # Sandbox Account Source: https://docs.trio.com.br/guides/sandbox_account Before starting your integration with the Trio API, the first step is to create an account in the Sandbox environment — our secure and free testing environment. Access: [https://app.sandbox.trio.com.br/signup](https://app.sandbox.trio.com.br/signup) *** ## About the Sandbox Environment The Sandbox environment is an isolated environment that replicates the behavior of the production API, allowing you to: * Simulate transactions such as payments, withdrawals, and refunds; * Test validation and error-handling flows, including failure and blocked transaction scenarios; * Develop and validate your integration without financial risk. *** ## Organization Registration When accessing the Sandbox environment, you will be required to register your organization. The registration process is fast, free, and available to any company interested in evaluating and validating Trio’s solution before moving to production. Use the Sandbox environment to test all API operations and webhook events. This ensures that your integration is fully validated and production-ready before migrating to the live environment. Image (19) The Trio Sandbox App is the testing version of our internet banking platform, designed to mirror the production environment. It allows you to explore the platform features, validate operational flows, and prepare your API integration in a secure and isolated environment. *** ## Exploring the Trio App Image (20) For a complete overview of the platform features and capabilities, access the Trio App practical guide: [https://suporte.trio.com.br/manual-de-uso-trio](https://suporte.trio.com.br/manual-de-uso-trio) Within the App, you can: * Manage accounts and balances; * Perform transactions and monitor account activity; * Access settings and operational reports; * Configure and validate API and webhook integrations. # Simulating deposit failures Source: https://docs.trio.com.br/guides/simulating-deposit-failures To proceed effectively, it is essential to understand the two-account mechanism used to create and simulate QR Code payments. If you need a refresher on this topic, please review the previous guide before continuing: [Simulating Deposit Success](/guides/deposits/simulating-deposit-success.md) ### Account Configuration for Transaction Restrictions To ensure security and data integrity, you can configure account settings to restrict specific transaction types, such as invalid third-party payments. It is also important to test scenarios involving incorrect or incomplete data, including: * Invalid CPF or CNPJ values * Incomplete tax numbers * Malformed strings or invalid values When testing failure scenarios, you can follow two approaches: 1. **Enforce Data Validation**\ Implement validation rules to prevent and properly handle invalid input. 2. **Simulate Invalid Scenarios**\ Create test cases using incomplete or malformed data to observe how the system behaves. The second approach requires changes to the account configuration in order to reproduce specific failure scenarios and explore a broader range of possibilities. The following sections explain the configurations required to test these scenarios and better understand the system’s capabilities and limitations. *** ## Configuring the Account To test failure scenarios, start by configuring your account settings. First, list your virtual accounts and click the **Actions** button to open the virtual account details. This account will be used to generate the QR Code for the payment. Image (37) At the bottom of the details page, you will find a set of security and compliance rules available for the virtual Pix account. These rules apply business logic and fraud-prevention measures to incoming and outgoing transactions. Understanding these rules is essential both for your integration and for properly testing different transaction scenarios. | Rule ID | Rule | Description | | ------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | | **1** | **Block payins from unidentified individuals** | Rejects payments where the sender's identity could not be verified. | | **2** | **Block duplicated QR Code payins** | Prevents repeated payments using the same QR Code. | | **3** | **Block payins with a different amount from the dynamic QR Code amount** | Ensures that the received amount matches the amount defined in the dynamic QR Code. | | **4** | **Block payins from legal entities** | Prevents receiving funds from companies (CNPJ), allowing only individuals (CPF). | | **5** | **Block payins from tax numbers different from the dynamic QR Code tax number** | Ensures that the payer’s tax ID matches the one associated with the QR Code. | | **6** | **Block payins from unauthorized participants** | Blocks payments from blacklisted participants. | | **7** | **Block payins from counterparty bank accounts different from the QR Code** | Verifies that the sender’s bank account matches the account expected for the QR Code payment. | | **8** | **Automatic refund for deposits incoming from minors** | Automatically refunds deposits made by individuals under 18 years old. | | **9** | **Automatic refund for deposits incoming from deceased individuals** | Automatically refunds payments made by individuals marked as deceased in official records. | | **10** | **Automatic refund for deposits incoming from individuals with invalid tax numbers** | Automatically refunds payments from individuals with invalid CPF or CNPJ values. | | **11** | **Block payouts to legal entities (CNPJ)** | Prevents outgoing payouts to companies, allowing payouts only to individuals. | By enabling or disabling these rules, you can simulate different failure scenarios during testing. > **Note**\ > Most payment failures occur during the initial validation process, and the error is immediately returned to the payer’s banking application. > > In these cases, no transaction record is created on the Trio side, and no additional integration handling is required. > > This early rejection behavior applies to rules **#1**, **#2**, **#5**, **#6**, **#8**, **#9**, and **#10**. When an invalid payment is attempted, the following error message will appear in the banking application: `Invalid Pix Key/Copy & Paste` This behavior is similar to what end users experience in production environments. Image (36) # Simulating deposit success Source: https://docs.trio.com.br/guides/simulating-deposit-success Next, we present a step-by-step approach for you to complete (**settle**) your deposits. To simulate a complete transaction flow, you'll need two accounts: one to create payments and another to process them. First, you need to create a secondary virtual account. Access the menu and click on **Account > Virtual Accounts**. In the listing page, at the top right, click on **Create Virtual Account.** Select your real bank account (typically there will be only one) and provide a simple description for this account. Once created, this new account will appear in the listing interface, with its own ID and balance. By default, your first account starts with 1,000,000 BRL, while the new account starts with 0 BRL. ### **Paying a Deposit** 1. Create a new payment with QR code pointing to the new account. In the request body, specify the newly created account ID in the virtual\_account\_id, as shown below. * POST [https://api.sandbox.trio.com.br/banking/cashin/pix/qrcodes](https://api.sandbox.trio.com.br/banking/cashin/pix/qrcodes) Copy ```text theme={null} { "virtual_account_id": "0196102e-f67b-d5f9-300c-f587094bfc5a", "counterparty": { "tax_number": "41.491.440/0000-11", "name": "My Test Company" }, "amount": 5000, "external_id": "{{$randomUUID}}", "description": "Test Payment in Sandbox", "options": { "allow_change_the_amount_on_payment": false, "show_qrcode_image": false } } ``` 2. The account with a 0.00 BRL balance will receive a deposit of 50 BRL. To pay this deposit, you'll use your first account that has the full balance. To do this, go to **Move your account > Pix**. 1. Select the origin account, which should be the first one, with full balance. 1. Paste que hash code created in your Deposit Request, via API. 1. Follow a few completion steps, and you will have your deposit Completed, with webhook sent and the transaction listed in your transactions list. # Using Pix Automatic Source: https://docs.trio.com.br/guides/using-pix-automatic O **Pix Automático** permite que você cobre seus clientes de forma recorrente (assinaturas, mensalidades, serviços) sem que o pagador precise autorizar cada cobrança individualmente. O cliente autoriza **uma única vez** a recorrência no app do próprio banco e, a partir daí, cada cobrança (chamada de *collection*) é debitada automaticamente na data combinada, dentro dos limites que foram autorizados. Na Trio, o Pix Automático é composto por três objetos encadeados: * **Recorrência (`recurrence`)**: o "contrato" de autorização entre você e o pagador. Define periodicidade, valor (fixo ou variável), datas e regras de retentativa. * **Cobrança (`collection`)**: cada ocorrência de cobrança gerada a partir da recorrência (por exemplo, a mensalidade de outubro). * **Tentativa (`attempt`)**: cada tentativa de liquidação de uma cobrança. Uma mesma cobrança pode ter mais de uma tentativa, de acordo com a política de retentativa configurada. Este guia cobre o ciclo completo: criação da recorrência e suas variações de jornada, configurações no momento da criação, gestão automática e manual das cobranças, atualização de valor, cancelamentos, consultas e os webhooks disparados em cada etapa. > Todos os exemplos usam o ambiente de **sandbox** (`https://api.sandbox.trio.com.br`). Em produção, troque a base para `https://api.trio.com.br`. *** ### Endpoints | Ação | Método | Endpoint | | -------------------------------------- | ------ | ------------------------------------------------- | | Criar recorrência | `POST` | `/recurrences` | | Listar recorrências | `GET` | `/recurrences` | | Consultar recorrência | `GET` | `/recurrences/{id}` | | Cancelar recorrência | `POST` | `/recurrences/{id}/cancel` | | Consultar solicitação de autorização | `GET` | `/recurrences/requests/{id}` | | Listar cobranças | `GET` | `/recurrences/collections` | | Consultar cobrança | `GET` | `/recurrences/collections/{id}` | | Criar próxima cobrança (gestão manual) | `POST` | `/recurrences/collections/create_next_collection` | | Atualizar valor da cobrança | `PUT` | `/recurrences/collections/{id}` | | Agendar cobrança (gestão manual) | `POST` | `/recurrences/collections/{id}/schedule` | | Cancelar cobrança | `POST` | `/recurrences/collections/{id}/cancel` | | Listar tentativas | `GET` | `/recurrences/collections/attempts` | | Consultar tentativa | `GET` | `/recurrences/collections/attempts/{id}` | *** ### Criando uma recorrência A recorrência é criada com um `POST` para o endpoint de criação. Antes de ver as variações por jornada, conheça os parâmetros que você sempre precisa enviar. `POST: https://api.sandbox.trio.com.br/banking/cashin/pix/recurrences` Campos obrigatórios: * **`virtual_account_id`**: conta virtual que receberá as cobranças. * **`counterparty`**: dados do pagador. `tax_number` e `name` são obrigatórios. Para autorização via app (jornada `app`), também é obrigatório o `bank_account` do pagador. * **`description`**: descrição da recorrência (máx. 35 caracteres). Aparece para o pagador na autorização. * **`periodicity`**: frequência da cobrança. * **`contract_number`**: número do contrato/assinatura no seu sistema (máx. 35 caracteres). * **`start_date`**: data de início da recorrência (ISO 8601) - No minimo 3 dias após a data atual. Valores possíveis de **`periodicity`**: | Valor | Significado | | ------ | -------------- | | `week` | A cada semana | | `mnth` | A cada mês | | `qurt` | A cada 3 meses | | `mian` | A cada 6 meses | | `year` | A cada ano | Campos opcionais relevantes: * **`end_date`**: data final da recorrência. Se omitido, a recorrência não tem prazo de término. * **`external_id`**: sua referência interna para a recorrência. * **`amounts`**: define o valor (ver abaixo). Se omitido, a recorrência é criada com **valor variável sem mínimo**. * **`first_payment`**: configura o primeiro pagamento conjugado à autorização (ver variações de jornada). * **`options`**: bloco de configurações da recorrência (ver seção [Opções e configurações](#)). #### Valor fixo x valor variável O bloco `amounts` define como o valor de cada cobrança é determinado: * **Valor fixo** — envie `amounts.fixed` (em centavos). Toda cobrança terá esse valor e ele **não pode ser alterado** antes do envio. * **Valor variável com mínimo** — envie `amounts.minimum` (em centavos). O pagador não pode autorizar um limite menor que o mínimo. **Cada cobrança precisa ter o valor informado antes da data de cobrança.** * **Valor variável sem mínimo** — omita o bloco `amounts`. Também exige informar o valor antes de cada cobrança. > Em recorrências de valor variável, informar o valor antes do envio é obrigatório. Use a atualização de valor (`PUT`) ou informe o `amount` no agendamento, conforme a seção de gestão de cobranças. #### Variações por jornada O Pix Automático prevê diferentes **jornadas de autorização**. Na Trio, a jornada resultante é determinada pela combinação de três parâmetros e é retornada no campo `journey` (`aut1`–`aut4`) do objeto de recorrência: * **`options.authorization_type`** — `qrcode` (gera um QR Code para o pagador autorizar) ou `app` (envia a solicitação de autorização direto para o app do banco do pagador). * **`first_payment`** — presente ou ausente: define se há um primeiro pagamento conjugado à autorização. * **`first_payment.recurrence_required`** — `true` aprova recorrência e primeiro pagamento numa única autorização; `false` permite que o pagador pague o primeiro pagamento e recuse a recorrência. O campo `reference_type` no retorno indica o canal usado: `qrdn` (QR Code dinâmico), `qres` (QR Code estático) ou `requ` (solicitação enviada ao app). A seguir, as variações mais comuns utilizadas por nossos clientes: **Jornada A — Autorização via QR Code, valor fixo, sem primeiro pagamento** O cliente lê um QR Code e autoriza a recorrência. Nenhuma cobrança é feita no ato da autorização. ```json theme={null} { "virtual_account_id": "018af380-cedc-3a53-29c0-e329bf0e109b", "counterparty": { "tax_number": "70004764005", "name": "Jhon Doe" }, "description": "Assinatura mensal", "contract_number": "CONTRATO-2025-001", "periodicity": "mnth", "start_date": "2025-11-01T00:00:00.000000Z", "amounts": { "fixed": 4990 }, "options": { "authorization_type": "qrcode" } } ``` **Jornada B — Autorização + primeiro pagamento conjugados (QR Code)** A autorização da recorrência e a primeira cobrança são aprovadas numa única ação do pagador. Útil quando a assinatura já começa com uma cobrança imediata. O `due_detail` permite configurar vencimento, juros, multa e descontos do primeiro pagamento. ```json theme={null} { "virtual_account_id": "018af380-cedc-3a53-29c0-e329bf0e109b", "counterparty": { "tax_number": "70004764005", "name": "Jhon Doe" }, "description": "Assinatura mensal", "contract_number": "CONTRATO-2025-002", "periodicity": "mnth", "start_date": "2025-11-01T00:00:00.000000Z", "amounts": { "fixed": 4990 }, "first_payment": { "amount": 4990, "dict_key": "chave-pix-da-sua-virtual-account", "recurrence_required": true, "due_detail": { "due_date": "2025-10-25" } }, "options": { "authorization_type": "qrcode", "qrcode_expiration_seconds": 86400 } } ``` > Definindo `recurrence_required: false`, o pagador pode pagar o primeiro pagamento e ainda assim recusar a recorrência. Com `true`, recorrência e primeiro pagamento são aprovados juntos, em uma única autorização. **Jornada C — Solicitação enviada direto ao app do pagador** Em vez de gerar um QR Code, a solicitação de autorização é enviada diretamente para o app do banco do pagador. Nesse caso, o `counterparty.bank_account` é **obrigatório** — é a conta que receberá o pedido de aprovação. ```json theme={null} { "virtual_account_id": "018af380-cedc-3a53-29c0-e329bf0e109b", "counterparty": { "tax_number": "70004764005", "name": "Jhon Doe", "bank_account": { "ispb": "49931906", "branch": "0001", "number": "12345678", "digit": "9" } }, "description": "Plano anual", "contract_number": "CONTRATO-2025-003", "periodicity": "year", "start_date": "2025-11-01T00:00:00.000000Z", "amounts": { "fixed": 59900 }, "options": { "authorization_type": "app" } } ``` Quando a autorização é por app, a Trio cria uma **solicitação de autorização** (`recurrence request`), que você pode acompanhar com `load_requests` na consulta da recorrência ou pelo endpoint `GET /recurrences/requests/{id}`. Os status da solicitação são: `created`, `sent`, `received`, `rejected`, `accepted`, `expired`, `cancelled`. **Jornada D — Valor variável com mínimo** Para assinaturas em que o valor muda a cada ciclo (consumo, uso, parcelas variáveis), informe apenas o mínimo. O valor de cada cobrança deverá ser informado antes do envio. ```json theme={null} { "virtual_account_id": "018af380-cedc-3a53-29c0-e329bf0e109b", "counterparty": { "tax_number": "70004764005", "name": "Jhon Doe" }, "description": "Conta de consumo", "contract_number": "CONTRATO-2025-004", "periodicity": "mnth", "start_date": "2025-11-01T00:00:00.000000Z", "amounts": { "minimum": 1000 }, "options": { "authorization_type": "qrcode", "automatic_schedule": false, "automated_attempt_retry": true } } ``` #### Resposta da criação Em caso de sucesso você recebe `201` com o objeto da recorrência. Para jornadas via QR Code, o bloco `qrcode` traz o `hash` (Copia e Cola) e o `id` do QR Code. O `id_rec` é o identificador da recorrência no SPI/Bacen e o `id` é o identificador interno na Trio. ```json theme={null} { "data": { "id": "0199d478-de39-fcf3-87a9-e8bded7db468", "id_rec": "RR4993190620251011181155657BH", "status": "created", "journey": "aut3", "reference_type": "qrdn", "periodicity": "mnth", "description": "Assinatura mensal", "contract_number": "CONTRATO-2025-001", "fixed_amount": { "amount": "4990", "currency": "BRL" }, "start_date": "2025-11-01T00:00:00.000000Z", "first_payment_date": "2025-11-01T00:00:00.000000Z", "automatic_schedule": "true", "retry_policy": "3r_7d", "next_working_day": "false", "virtual_account_id": "018af380-cedc-3a53-29c0-e329bf0e109b", "qrcode": { "id": "0199d478-...-qr", "type": "dynamic", "hash": "00020101021126640014br.gov.bcb.pix..." } } } ``` Ofereça ao pagador o `hash` em "Copia e Cola" e/ou renderize a imagem do QR Code a partir dele. A recorrência só passa a valer depois que o pagador a autoriza — você acompanha isso pelo webhook `recurrence.approved` (ou `recurrence.rejected` / `recurrence.expired`). *** ### Opções e configurações na criação O bloco `options` define o comportamento da recorrência ao longo do tempo. Todos os campos são opcionais e têm valores padrão. | Campo | Padrão | Descrição | | --------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `authorization_type` | `qrcode` | `qrcode` gera um QR Code; `app` envia a solicitação diretamente para o aplicativo do pagador (exige `counterparty.bank_account`). | | `automatic_schedule` | `true` | Gestão automática das cobranças. Se `false`, cada cobrança precisa ser criada e agendada manualmente. | | `automated_attempt_retry` | `true` | Define quem gerencia as retentativas em caso de falha no pagamento. Se `true`, a Trio gerencia automaticamente as retentativas. Se `false`, elas ficam sob responsabilidade do cliente. | | `retry_policy` | `3r_7d` | Política de retentativa quando a cobrança falha. `3r_7d`: 3 retentativas em 7 dias, em dias alternados. `none`: sem retentativa. | | `next_working_day` | `false` | Se `true`, não realiza cobranças em feriados, transferindo a cobrança para o próximo dia útil do pagador. | | `qrcode_expiration_seconds` | `86400` | Tempo de expiração (em segundos) do QR Code dinâmico. Ignorado para QR Code estático. | #### Gestão de cobrança automática Com `automatic_schedule: true` (padrão), a Trio cria e agenda automaticamente cada cobrança na periodicidade definida. Você não precisa fazer nada a cada ciclo — basta reagir aos webhooks. Use este modo quando o valor é fixo ou quando você já consegue determinar o valor com antecedência. Com `automatic_schedule: false` (gestão manual), você é responsável por criar e agendar cada cobrança a cada ciclo. Esse modo é necessário, por exemplo, quando o valor variável só é conhecido perto da data de cobrança. Veja a seção [Gestão manual de cobranças](#). #### Retentativas e clientes que não pagam A `retry_policy` define o que acontece quando uma cobrança não é liquidada. Se `automated_attempt_retry` for enviado como `true`, a **Trio** será responsável por criar e gerenciar automaticamente essas retentativas. Caso seja enviado como `false`, o gerenciamento das retentativas fica sob responsabilidade da sua aplicação. * **`3r_7d`** — a cobrança é retentada 3 vezes ao longo de 7 dias, em dias alternados. Cada retentativa gera uma nova *attempt*. Se nenhuma tentativa for liquidada, a cobrança vai para um status final de falha ou expiração. * **`none`** — não há retentativas. Uma tentativa com falha encerra a cobrança. > **Cancelar a recorrência quando o cliente não paga.** A política de retentativas atua no nível da *cobrança*, não da recorrência. Se a sua regra de negócio é encerrar a assinatura após uma cobrança não paga, monitore os webhooks de *attempt* (`recurrence_collection_attempt` com tipo `failed` ou `expired`) e/ou de cobrança (`recurrence_collection` com tipo `expired` ou `rejected`). Ao detectar o esgotamento das retentativas, chame o endpoint de cancelamento da recorrência para implementar o cancelamento automático por inadimplência. *** ### Gestão de cobranças (collections) Cada cobrança representa uma ocorrência de débito da recorrência. O ciclo de vida de uma cobrança passa pelos status: `created`, `active`, `settled`, `expired`, `rejected`, `cancelled`. As tentativas de liquidação têm os status: `requested`, `scheduled`, `settled`, `cancelled`, `rejected`, `expired`, `failed`. #### Gestão manual: criar a próxima cobrança Com `automatic_schedule: false`, crie a próxima cobrança da recorrência: `POST: https://api.sandbox.trio.com.br/banking/cashin/pix/recurrences/collections/create_next_collection` ```json theme={null} { "recurrence_id": "0199d478-de39-fcf3-87a9-e8bded7db468" } ``` A resposta `200` traz a cobrança criada (`RecurrenceCollection`) com seus estágios (`stages`) e tentativas (`attempts`). #### Agendar uma cobrança (gestão manual) Depois de criada, a cobrança precisa ser **agendada** para ser enviada ao banco recebedor. O agendamento deve ocorrer **entre 2 e 10 dias antes** da data de pagamento do ciclo. No agendamento você pode, opcionalmente, informar o valor (para recorrências de valor variável), a data de vencimento e um `external_id`. `POST: https://api.sandbox.trio.com.br/banking/cashin/pix/recurrences/collections/{id}/schedule` ```json theme={null} { "amount": 12990, "due_date": "2025-11-01T00:00:00.000000Z", "external_id": "COBR-2025-11" } ``` * **`amount`**: valor em centavos. Use para informar/atualizar o valor antes de agendar. **Não funciona em recorrências de valor fixo.** * **`due_date`**: data de vencimento da tentativa. * **`external_id`**: sua referência para a tentativa. A resposta de sucesso é `204 No Content`. Acompanhe o resultado pelo webhook `recurrence_collection_attempt` com tipo `scheduled` e, depois, `settled` ou `failed`. #### Atualizar o valor de uma cobrança antes do envio Para recorrências de **valor variável**, você pode atualizar o valor de uma cobrança que ainda não foi enviada ao banco recebedor: `PUT: https://api.sandbox.trio.com.br/banking/cashin/pix/recurrences/collections/{id}` ```json theme={null} { "amount": 13500 } ``` * **`amount`**: novo valor em centavos. * Só é possível atualizar enquanto a cobrança ainda não foi enviada. Em recorrências de **valor fixo**, o valor não pode ser alterado. A resposta `200` retorna a cobrança atualizada. #### Cancelar uma cobrança Você pode cancelar uma cobrança específica (sem cancelar a recorrência inteira): `POST: https://api.sandbox.trio.com.br/banking/cashin/pix/recurrences/collections/{id}/cancel` ```json theme={null} { "requester_tax_number": "12345678000190", "entity_id": "019953ad-1738-b094-097c-7941a0c642a5" } ``` * **`requester_tax_number`** (obrigatório): CPF/CNPJ de quem está solicitando o cancelamento. * **`entity_id`** (opcional): identificador da entidade. A resposta `200` retorna a cobrança com status `cancelled`. As próximas cobranças da recorrência seguem normalmente. *** ### Cancelando a recorrência Para encerrar a recorrência por completo (nenhuma cobrança futura será gerada): `POST: https://api.sandbox.trio.com.br/banking/cashin/pix/recurrences/{id}/cancel` ```json theme={null} { "requester_tax_number": "12345678000190" } ``` * **`requester_tax_number`** (obrigatório): CPF/CNPJ de quem solicita o cancelamento. A resposta `200` retorna a recorrência com status `cancelled`. Você também recebe o webhook `recurrence.cancelled`. *** ### Consultas #### Consultar uma recorrência `GET: https://api.sandbox.trio.com.br/banking/cashin/pix/recurrences/{id}` Parâmetros de query úteis: * **`load_stages`** (`true`/`false`): inclui o histórico de estágios da recorrência. * **`load_requests`** (`true`/`false`): inclui as solicitações de autorização (jornada `app`). * **`entity_id`**, **`bank_account_id`**, **`virtual_account_id`**: filtros opcionais. #### Listar recorrências `GET: https://api.sandbox.trio.com.br/banking/cashin/pix/recurrences` * **`from_datetime`** e **`to_datetime`** (obrigatórios): janela de tempo. * **`virtual_account_id`**, **`entity_id`**: filtros opcionais. * **`limit`**, **`before`**, **`after`**: paginação. #### Consultar uma solicitação de autorização `GET: https://api.sandbox.trio.com.br/banking/cashin/pix/recurrences/requests/{id}` Use `load_stages` para incluir os estágios da solicitação. #### Consultar e listar cobranças Consultar uma cobrança específica, com estágios e tentativas: `GET: https://api.sandbox.trio.com.br/banking/cashin/pix/recurrences/collections/{id}` * **`load_stages`** e **`load_attempts`**: incluem estágios e tentativas. Listar cobranças de uma recorrência: `GET: https://api.sandbox.trio.com.br/banking/cashin/pix/recurrences/collections` * **`recurrence_id`** (obrigatório), **`from_datetime`** e **`to_datetime`** (obrigatórios). * **`limit`**, **`before`**, **`after`**: paginação. #### Consultar e listar tentativas Listar tentativas de uma cobrança: `GET: https://api.sandbox.trio.com.br/banking/cashin/pix/recurrences/collections/attempts` * **`recurrence_id`** e **`collection_id`** (obrigatórios). * `from_datetime`, `to_datetime`, `limit`, `before`, `after`: opcionais. Consultar uma tentativa específica: `GET: https://api.sandbox.trio.com.br/banking/cashin/pix/recurrences/collections/attempts/{id}` * **`load_stages`**: inclui os estágios da tentativa. *** ### Webhooks A comunicação assíncrona em cada etapa é feita por webhooks. Há três categorias relacionadas ao Pix Automático. #### Recorrência — categoria `recurrence` Disparada nas mudanças de estado da recorrência (o "contrato" de autorização). | Tipo | Significado | | ----------- | ----------------------------------------------------------- | | `created` | A recorrência foi criada. | | `approved` | A recorrência foi aprovada pelo pagador. | | `rejected` | A recorrência foi rejeitada. | | `expired` | A recorrência expirou (autorização não concluída no prazo). | | `cancelled` | A recorrência foi cancelada. | [Exemplo de payload](https://docs.trio.com.br/developers/webooks/events/recurrence) #### Cobrança — categoria `recurrence_collection` Disparada nas mudanças de estado de cada cobrança. | Tipo | Significado | | ----------- | ------------------------------------------------------- | | `created` | A cobrança foi criada. | | `active` | A cobrança ficou ativa (agendada/enviada ao recebedor). | | `settled` | A cobrança foi liquidada. | | `expired` | A cobrança expirou. | | `rejected` | A cobrança foi rejeitada. | | `cancelled` | A cobrança foi cancelada. | [Exemplo de payload](https://docs.trio.com.br/developers/webooks/events/recurrences-collection) #### Tentativa da cobrança — categoria `recurrence_collection_attempt` Disparada em cada tentativa de liquidação de uma cobrança. É aqui que você acompanha o resultado efetivo do débito e as retentativas. | Tipo | Significado | | ----------- | ------------------------------------------------ | | `requested` | Uma tentativa foi criada. | | `scheduled` | A tentativa foi agendada. | | `settled` | A tentativa foi liquidada (pagamento efetivado). | | `cancelled` | A tentativa foi cancelada. | | `rejected` | A tentativa foi rejeitada. | | `expired` | A tentativa expirou. | | `failed` | A tentativa falhou. | [Exemplo de payload](https://docs.trio.com.br/developers/webooks/events/recurrence-collections-attempt) *** ### Resumo do fluxo de ponta a ponta A tabela abaixo amarra cada etapa do processo ao endpoint e ao webhook correspondente. | Etapa | O que você faz | Webhook esperado | | ----------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | 1. Criar recorrência | `POST /recurrences` e entrega do QR Code / envio da solicitação ao app | `recurrence.created` | | 2. Autorização do pagador | (ação do pagador) | `recurrence.approved` · `recurrence.rejected` · `recurrence.expired` | | 3a. Cobrança automática | nada (gestão automática) | `recurrence_collection.created` → `active` | | 3b. Cobrança manual | `create_next_collection` + `schedule` (com `amount`/`due_date` se variável) | `recurrence_collection.created` → `active` | | 4. Ajuste de valor (variável) | `PUT /recurrences/collections/{id}` antes do envio | — | | 5. Liquidação | (processamento) | `recurrence_collection_attempt.scheduled` → `settled` | | 6. Falha / inadimplência | reagir conforme `retry_policy` | `recurrence_collection_attempt.failed` · `recurrence_collection.expired` | | 7. Cancelar cobrança | `POST /recurrences/collections/{id}/cancel` | `recurrence_collection.cancelled` | | 8. Cancelar recorrência | `POST /recurrences/{id}/cancel` | `recurrence.cancelled` | > **Boa prática:** trate sempre os estados finais via webhook (`settled`, `failed`, `expired`, `cancelled`) e use as consultas (`GET`) para reconciliação. Para inadimplência, combine o monitoramento das tentativas com a `retry_policy` e decida, na sua aplicação, se cancela a recorrência. # Pix key Regex Source: https://docs.trio.com.br/guides/using-pix-key Considering that a Pix key represents a bank account within the Pix ecosystem, this is the most straightforward way to complete a payout using Pix. The only information required from the customer is their Pix key. Currently, we support 5 different key types, and we use **RegEx** validation to verify the format. > **Note:** As of July 01, 2026, the **CNPJ** may contain alphanumeric characters. Our validation supports both the legacy numeric format and the new alphanumeric format defined by the Brazilian Federal Revenue Service. | Type | Regex | Example | | ----------------- | ---------------------------------------------------------------- | -------------------------------------------------- | | Email | `^[a-z0-9.!#$%&'*+/=?^_{}~-]+@[a-z0-9-]+(?:\.[a-z0-9-]+)*$` | `johndoe@example.com` | | Phone Number | `^\+[1-9][0-9]\d{1,14}$` | `+5510998765432` | | CPF (Tax Number) | `^[0-9]{11}$` | `12345678901` | | CNPJ (Tax Number) | `^[A-Z0-9]{12}[0-9]{2}$` | `AB12CD3400EF95` *(also accepts `12345678901234`)* | | Random Key | `^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$` | `123e4567-e89b-12d3-a456-426655440000` | # Structure Source: https://docs.trio.com.br/guides/webhook Webhooks allow Trio to send automatic notifications to your system whenever an important event occurs, such as a successful Cash In or Cash Out transaction. Notifications are typically triggered when a transaction reaches a final state such as `settled` or `failed`. *** ## Webhook Structure All webhook events sent by Trio follow the same JSON structure: ```json theme={null} { "ref_id": "", "category": "", "type": "", "timestamp": "", "data": {} } ``` | Field | Description | | ----------- | ------------------------------------------------------------------------- | | `ref_id` | Unique identifier of the event. | | `category` | Main event category (example: `collecting_document`, `payment_document`). | | `type` | Event type within the category (example: `created`, `settled`, `failed`). | | `timestamp` | Event creation timestamp. | | `data` | Object containing transaction-specific information. | *** ## Available Event Categories | Category | Description | | ------------------------------- | -------------------------------------- | | `collecting_document` | Cash In and deposit lifecycle events. | | `collecting_document_refund` | Deposit refund events. | | `payment_document` | Cash Out and payment lifecycle events. | | `payment_document_refund` | Payment refund events. | | `transfer_document` | Transfer lifecycle events. | | `recurrence` | Recurrence creation and update events. | | `recurrence_collection` | Recurring collection lifecycle events. | | `recurrence_collection_attempt` | Recurring collection attempt events. | *** ## Cash In Webhook Example Category: `collecting_document`\ Type: `settled` ```json theme={null} { "data": { "amount": { "amount": 100, "currency": "BRL" }, "counterparty": { "company_id": "91978496-c904-40d0-9322-5f2838efb542", "id": "29b6d0bc-7226-483b-99aa-aa815521ebb0", "name": "Conta 002", "tax_number": "45865162797606" }, "description": null, "end_to_end_id": "E49931906202501311822NX1S6J7KaOm", "id": "0194bd99-65cd-5ee9-70f6-44d61ae5aa41", "receipt_url": "https://receipts.sandbox.trio.com.br/019108db-d49f-c744-5b79-736a2849ddf5/in/0194bd99-65cd-5ee9-70f6-44d61ae5aa41", "transaction_date": "2025-01-31T18:22:14.510717Z", "type": "pix", "virtual_account_id": "0194412c-c559-5452-942e-7f4b4975c666" }, "timestamp": "2025-01-31T18:22:14.477163Z", "type": "settled", "category": "collecting_document", "ref_id": "0194bd99-65cd-5ee9-70f6-44d61ae5aa41" } ``` This event indicates that a Cash In transaction was successfully processed and the funds are available in the Virtual Account. *** ## Cash Out Webhook Example Category: `payment_document`\ Type: `settled` ```json theme={null} { "data": { "amount": { "amount": 100, "currency": "BRL" }, "counterparty": { "company_id": "91978496-c904-40d0-9322-5f2838efb542", "id": "29b6d0bc-7226-483b-99aa-aa815521ebb0", "name": "Conta bancária 1 padrão", "tax_number": "45865162797606" }, "description": null, "end_to_end_id": "E49931906202502031248GP6ibT9SHqT", "external_id": "Pix Console 0194cbda-8c8c-ff83-9f1d-c3c50f5ec0df", "id": "0194cbda-a2ca-5ecd-9796-99be6b7f4485", "receipt_url": "https://receipts.sandbox.trio.com.br/019108db-d49f-c744-5b79-736a2849ddf5/out/0194cbda-a2ca-5ecd-9796-99be6b7f4485", "transaction_date": "2025-02-03T12:48:21.405797Z", "type": "pix", "virtual_account_id": "019440cd-a30f-c102-ff8c-a9d4e6939d48" }, "timestamp": "2025-02-03T12:48:10.954083Z", "type": "settled", "category": "payment_document", "ref_id": "0194cbda-a2ca-5ecd-9796-99be6b7f4485" } ``` This event indicates that a Cash Out transaction was successfully processed and the funds were debited from the Virtual Account. *** These are the primary webhook events used in most integrations. For the complete list of supported webhook events, access: [#/developers/webooks/events](#/developers/webooks/events) # Welcome Source: https://docs.trio.com.br/index Trio is a complete banking solution for companies, designed to automate financial operations, move money at scale, and manage corporate treasury efficiently. We are authorized by the Central Bank of Brazil (No. 619 and ISPB 49931906) and offer a modern and secure infrastructure to integrate financial services directly into your system. This documentation has been created to guide you through our concepts, best practices, and tutorials, as well as showing you how to interact with your account programmatically via our API. ## **How to Navigate the Documentation** Trio’s documentation is organized into three main sections to support your integration journey — from your first API request to full production implementation. ## **1. Getting Started** ### **Start here** Follow our quick start guide and complete your first integration steps in just a few minutes. This introductory section is designed for developers who are integrating with Trio for the first time. Here you’ll learn how to: * Understand the basic API concepts * Configure your environment * Generate API credentials * Authenticate requests * Make your first API calls * Error table It is the best place to begin before moving on to more advanced topics. *** ## **2. Guides** ### **Practical integration guides** The **Guides** section contains practical and technical tutorials focused on integration scenarios. These guides are designed to help developers quickly implement and test the main Trio features during the first stages of integration. Here you’ll find: * Step-by-step implementation examples * Practical testing flows * Sandbox simulation guides * Authentication and webhook examples * Explanations transaction flows * Integration best practices This is the recommended section for developers actively building and validating their integration. *** ## **3. API Reference** ### **Complete API specification** The **API Reference** section is the complete technical catalog of all available endpoints. It provides detailed information about: * Request and response examples * Parameters and headers * Data structures * Authentication requirements * Status codes and error responses This section serves as a quick and reliable reference during development and troubleshooting. # Best practices for integration Source: https://docs.trio.com.br/operations/best_practices_for_integration # Understanding Cash In and Cash Out IDs During the integration process with the **Trio API**, it is important to understand how identifiers behave differently between **Cash In** and **Cash Out** operations. These identifiers are essential for: * Financial reconciliation; * Transaction tracking; * Idempotency validation; * Duplicate prevention; * Transaction lookup; * Operational investigations. *** # Identifier Overview | Transaction Type | Identifier Returned on Creation | Final Financial Identifier Availability | | ---------------- | ------------------------------- | --------------------------------------- | | Cash Out | `data.out_document_id` | Immediately | | Cash In | `data.id` (`ref_id`) | After `settled` webhook | *** # Cash Out ## How Cash Out Identifiers Work For Cash Out operations, the financial transaction is created immediately during the request. Because of this, the API instantly returns the final transaction identifier: ```json theme={null} { "data": { "out_document_id": "0192057d-ab3f-3651-f054-6ef9c8e68f20" } } ``` The returned `out_document_id` already represents the finalized financial document. *** ## Recommended Usage The identifier should be persisted and used for: * Transaction status queries; * Financial reconciliation; * Receipt validation; * Operational support investigations; * Audit trails. *** ## Cash Out Lifecycle ```text theme={null} processing → settled ``` or ```text theme={null} processing → failed ``` Both `settled` and `failed` are final states. Once either status is reached: * No further events will occur; * The transaction lifecycle is permanently closed. *** ## Understanding `failed` If a Cash Out reaches `failed`: * The withdrawal was not completed; * The transaction is finalized immediately; * No additional updates will occur. Possible causes include: * Invalid Pix key; * Banking rejection; * Insufficient balance; * Banking processing failures. *** ## Understanding `settled` When a Cash Out reaches `settled`: * The transfer was completed successfully; * Funds were delivered; * The transaction becomes immutable. *** ## Response Time Expectations | Scenario | Expected Time | | -------------------------- | --------------- | | Stable environment average | `200ms ~ 280ms` | | Temporary oscillation | Up to `1000ms` | *** ## Timeout Handling If a Cash Out request times out: ```text theme={null} Do not immediately create another withdrawal request. ``` The transaction may still have been processed successfully. Before retrying: 1. Query using the same `external_id`; 2. Validate webhook notifications; 3. Validate reconciliation status; 4. Contact Trio support if necessary. Creating another request without validation may generate duplicate payouts. *** # Cash In ## How Cash In Identifiers Work For Cash In operations, the initial request creates only the QR Code request. At this stage: * The payment has not yet happened; * No financial settlement exists yet; * No final transaction document exists. The API returns only the QR Code identifier (`ref_id`). ```json theme={null} { "data": { "id": "0192bebb-fbdb-b6f3-6be1-7153e373b609", "status": "created", "description": "Paid to merchant.com", "hash": "00020101021226790014br.gov.bcb.pix2557brcode-h.trio.com.br/...", "amount": { "currency": "BRL", "amount": 100 }, "external_id": "49d754c2-ac14-4219-bbe4-3e78e9ab8067", "virtual_account_id": "019296ff-1f72-2ad7-0201-41de08355fda", "origin_type": "api_client", "pix_key_id": "019296ff-1f94-ecec-2220-96bfd06e8e59" } } ``` *** ## Important The returned `data.id` should be interpreted as: ```text theme={null} QR Code Identifier (ref_id) ``` and not as the final financial transaction identifier. The final `document_id` is generated only after successful settlement. *** ## Settlement Flow Once the payment is completed successfully, Trio sends a `settled` webhook containing: * `external_id`; * `ref_id`; * Final transaction `id`. This structure allows the association between: ```text theme={null} QR Code Request → Payment Confirmation → Final Financial Transaction ``` *** ## Cash In `settled` Webhook Example ```json theme={null} { "data": { "amount": { "amount": 100, "currency": "BRL" }, "external_id": "49d754c2-ac14-4219-bbe4-3e78e9ab8067", "id": "0194bd99-65cd-5ee9-70f6-44d61ae5aa41", "receipt_url": "https://receipts.sandbox.trio.com.br/.../in/0194bd99-65cd-5ee9-70f6-44d61ae5aa41", "ref_id": "0192bebb-fbdb-b6f3-6be1-7153e373b609", "type": "pix", "virtual_account_id": "0194412c-c559-5452-942e-7f4b4975c666" }, "type": "settled", "category": "collecting_document", "timestamp": "2025-01-31T18:22:14.477163Z" } ``` *** ## Cash In Lifecycle Possible lifecycle sequences: ```text theme={null} created → settled ``` ```text theme={null} created → failed → settled ``` ```text theme={null} created → failed → failed → settled ``` *** ## Important Lifecycle Behavior For Cash In operations, `failed` is not necessarily a final status. A `failed` event only means: ```text theme={null} A payment attempt was rejected ``` It does not mean: * The QR Code expired; * The QR Code was canceled; * The operation is permanently closed. The QR Code remains active and may still receive future payment attempts. *** ## Common `failed` Scenarios Examples include: * Third-party payment attempts; * Rejected payer validations; * Business rule validation failures. *** ## Understanding `settled` Once a Cash In reaches `settled`: * The payment is finalized; * The final `document_id` is generated; * The QR Code is automatically closed; * No further events will occur. After settlement, additional `failed` events are not possible. *** ## Response Time Expectations | Scenario | Expected Time | | ----------------------------- | -------------- | | Stable environment average | `80ms ~ 100ms` | | Recommended timeout threshold | Up to `500ms` | *** ## Retry Recommendation If no response is received within `500ms` during QR Code generation: * A new request may be created; * A new `external_id` must be used. *** # `external_id` and Idempotency The `external_id` field is the primary reconciliation identifier between your platform and Trio. This field must be unique for every operation. *** ## Idempotency Window Cash In and Cash Out operations enforce an idempotency window of: ```text theme={null} 24 hours (1 day) ``` During this period: * The same `external_id` cannot be reused; * Duplicate requests may return the previous transaction; * This prevents accidental duplicate operations. *** ## Best Practices Recommended: * Use UUIDs; * Persist all identifiers in your database; * Associate identifiers with internal orders/payments; * Query transactions before retrying requests. Avoid: * Reusing identifiers; * Sequential IDs; * Blind automatic retries; * Creating new operations without previous validation. *** # Webhook Processing Recommendations For production environments: * Process webhooks asynchronously; * Return `HTTP 200 OK` immediately; * Persist webhook payloads; * Maintain audit history; * Avoid long-running synchronous processing. Webhooks should always be treated as the source of truth for final transaction status updates. *** # Final Summary Cash In and Cash Out operations behave differently and should be handled differently during integration. For Cash Out: * The final transaction identifier is returned immediately; * `failed` and `settled` are terminal states; * Timeout retries must be handled carefully to avoid duplicate payouts. For Cash In: * The initial request creates only the QR Code reference (`ref_id`); * The final financial transaction exists only after settlement; * `failed` does not necessarily represent a permanent failure; * Multiple payment attempts may occur before settlement; * The final `document_id` is received only through webhook notification. For both operation types: * `external_id` should always be unique; * All identifiers should be persisted for reconciliation; * Webhooks should be considered the authoritative source of transaction state; * Proper timeout and retry handling is critical to prevent duplicate operations and reconciliation inconsistencies. # How to ensure the closed loop? Source: https://docs.trio.com.br/operations/how_to_ensure_the_closed_loop When sending or receiving transactions, one might ask oneself how Trio manages to offer a fully secure closed loop, without any hiccuping or missing transactions, whilst also providing protection against frauds. For this sort of control, we offer plentiful parameterization aligned with compliance rules when making any movement, so you know exactly what happened throughout your operation. ### Deposits Regarding money coming in, we apply some compliance rules that decide whether money from a single transaction will be received or not. Whenever a compliance rule is being infringed in a transaction, we take it upon ourselves to receive the money and automatically refuse it back to the sender's account. A refused transaction will generate a failed event, so you can handle the experience and show the information to your users. Here you can see the pay-in related compliance rules that can be enabled for a virtual account:
Compliance ruleEditable?Possible situation
Unidentified depositsYesWhen a payment is done via the bank account directly or via the bank account's Pix key, we block the payment so you can know exactly who the money came from.
Deposits from duplicated QR code paymentsYesWhen a payment is done twice to the same QR Code, we block the payment, so each payment can be received separately in order to avoid confusion.
Deposits with value different from dynamic QR codeYesWhen a payment is done with an amount different from the initially stated in the QR Code. Useful for controlling the exact amount of transactions, and avoiding the need to create two QR Codes for the same transaction. We tend to recommend clients to always leave this parameter on.
Deposits with tax number different from dynamic QR codeYesWhen a payment is done by an individual with a tax number different from the tax number initially set in the QR Code creation.
Deposits with bank accounts different from dynamic QR codeYesWhen a payment is done by a bank account different from the bank accounts initially set in the QR Code creation.
Deposits from legal entitiesYesWhen a payment is not done by an individual with a natural person tax number (CPF in Brazil), but from a legal entity with a legal tax number (CNPJ in Brazil).
Deposits from unauthorized participantsYesWhen payment is done by an institution that is not authorized by the Central Bank of Brazil
Compliance ruleEditable?Possible situation
Unidentified depositsYesWhen a payment is done via the bank account directly or via the bank account's Pix key, we block the payment so you can know exactly who the money came from.
Deposits from duplicated QR code paymentsYesWhen a payment is done twice to the same QR Code, we block the payment, so each payment can be received separately in order to avoid confusion.
Deposits with value different from dynamic QR codeYesWhen a payment is done with an amount different from the initially stated in the QR Code. Useful for controlling the exact amount of transactions, and avoiding the need to create two QR Codes for the same transaction. We tend to recommend clients to always leave this parameter on.
Deposits with tax number different from dynamic QR codeYesWhen a payment is done by an individual with a tax number different from the tax number initially set in the QR Code creation.
Deposits with bank accounts different from dynamic QR codeYesWhen a payment is done by a bank account different from the bank accounts initially set in the QR Code creation.
Deposits from legal entitiesYesWhen a payment is not done by an individual with a natural person tax number (CPF in Brazil), but from a legal entity with a legal tax number (CNPJ in Brazil).
Deposits from unauthorized participantsYesWhen payment is done by an institution that is not authorized by the Central Bank of Brazil
A complete guide of implementation can be found here: Pay-in using a QR Code. ### Payout Regarding money going out, we also apply some compliance rules and control cash out processes that decide whether a payment will be transferred, only as a form of protecting our client base. Here you can see the payout related compliance rules that are enabled for a virtual account:
Compliance ruleEditable?Possible situation
Block payouts to legal entitiesYesWhen attempting to make a payment to an account that belongs to a legal entity represented by a legal tax number (CNPJ in Brasil).
Block payouts to different tax numberYesWhen attempting to pay out an account that not belongs to the tax number informed on the payload field: reference\_tax\_number
Block payouts to different bank accountsYesWhen attempting to pay out an account that not informed on the payload field: reference\_bank\_accounts
Compliance ruleEditable?Possible situation
Unidentified depositsYesWhen a payment is done via the bank account directly or via the bank account's Pix key, we block the payment so you can know exactly who the money came from.
Deposits from duplicated QR code paymentsYesWhen a payment is done twice to the same QR Code, we block the payment, so each payment can be received separately in order to avoid confusion.
Deposits with value different from dynamic QR codeYesWhen a payment is done with an amount different from the initially stated in the QR Code. Useful for controlling the exact amount of transactions, and avoiding the need to create two QR Codes for the same transaction. We tend to recommend clients to always leave this parameter on.
Deposits with tax number different from dynamic QR codeYesWhen a payment is done by an individual with a tax number different from the tax number initially set in the QR Code creation.
Deposits with bank accounts different from dynamic QR codeYesWhen a payment is done by a bank account different from the bank accounts initially set in the QR Code creation.
Deposits from legal entitiesYesWhen a payment is not done by an individual with a natural person tax number (CPF in Brazil), but from a legal entity with a legal tax number (CNPJ in Brazil).
Deposits from unauthorized participantsYesWhen payment is done by an institution that is not authorized by the Central Bank of Brazil
Compliance ruleEditable?Possible situation
Block payouts to legal entitiesYesWhen attempting to make a payment to an account that belongs to a legal entity represented by a legal tax number (CNPJ in Brasil).
Block payouts to different tax numberYesWhen attempting to pay out an account that not belongs to the tax number informed on the payload field: reference\_tax\_number
Block payouts to different bank accountsYesWhen attempting to pay out an account that not informed on the payload field: reference\_bank\_accounts
A complete guide of implementation can be found here: Payout using a Pix key.
Compliance ruleEditable?Possible situation
Block payouts to legal entitiesYesWhen attempting to make a payment to an account that belongs to a legal entity represented by a legal tax number (CNPJ in Brasil).
Block payouts to different tax numberYesWhen attempting to pay out an account that not belongs to the tax number informed on the payload field: reference\_tax\_number
Block payouts to different bank accountsYesWhen attempting to pay out an account that not informed on the payload field: reference\_bank\_accounts
Compliance ruleEditable?Possible situation
Block payouts to legal entitiesYesWhen attempting to make a payment to an account that belongs to a legal entity represented by a legal tax number (CNPJ in Brasil).
Block payouts to different tax numberYesWhen attempting to pay out an account that not belongs to the tax number informed on the payload field: reference\_tax\_number
Block payouts to different bank accountsYesWhen attempting to pay out an account that not informed on the payload field: reference\_bank\_accounts
# Quickstart Source: https://docs.trio.com.br/quickstart Welcome to the Trio API documentation! The best way to get started is by creating your Sandbox account. This guide walks you through the initial setup and prepares your environment for testing all Trio APIs. 👉 **Start here:** [/guides/sandbox\_account](/guides/sandbox_account) Once your Sandbox account is ready, you'll be able to: * Generate your API credentials. * Configure webhooks. * Test all available banking APIs in a safe environment. * Follow the integration guides throughout this documentation. If you're new to Trio, we recommend completing the Sandbox Account guide before exploring the API Reference. # Payin Source: https://docs.trio.com.br/trio-sdk/flows/payin The pay-in flow shall be used whenever you want users to cash in some money with almost zero friction. In order to generate a pay-in through our Checkout SDK, you must create a Checkout Session. Below, there are some important parameters that you will need to pay attention to (\* for required fields): * **options** * `session_type`\*: session type, in this case **payin**. * `expiration_in_seconds`: integer value. If set, the Checkout session will only remain active up until this time. If not, the default time is 300 seconds (5 minutes). * **transaction** * `tax_number`\*: the document/tax number (CPF/CNPJ) that represents the person you intend to receive money from. * `amount`\*: Value of the deposit. Always represented in cents. * `phone_number`: Additional information about the person you intend to receive money from. * `email`: Additional information about the person you intend to receive money from. * `redirect_url`: the URL the user will be redirected after completing an open finance transaction. (default will be a Trio confirmation URL) #### **White label** You can also customize your end-user experience by utilizing the Checkout as a *white label*. You can do so by utilizing the `options` field, with the respective `xxxx_color` fields. Below, you can see an example of a wholly implemented customization: In order to create a session, you must make a `POST` request to `/checkout/sessions` with the following payload: ```json theme={null} { "transaction": { "tax_number": "23725474028", // John Doe's document/tax number "phone_number": "+5541999999999", // John Doe's Pix Key "email": "user@trio.com.br", // John Doe's Pix Key "name": "John Doe", // Customer name "amount": 1, // total amount in cents "external_id": "01H7DKA58YDWPA7ZBCCAVWFM5E", // reference for your system "description": "Paid to example.com", // additional information about the transaction "redirect_url": "http://your.url.here", // URL the user will be redirected after completing an open finance transaction }, "receiver": { "virtual_account_id": "018a66ca-0451-9cd7-1cfa-8dca325db29f" // unique identifier for the virtual account that will receive the money }, "options": { "session_type": "payin", // Session type (must be payin) "expiration_in_seconds": "86400", // session expiration time, integer value "theme": { "colors": { "backdrop_color": "#ffffff", //hex color for the background (optional, accepts any color) "button_color": "#f6df69", //hex color for the interface primary action button (optional, accepts any color) "button_label_color": "#000000", //hex color for the interface primary action text (optional, accepts only #000000 or #ffffff) "link_color": "#426b55", //hex color for links (optional, accepts any color) "navbar_action_color": "#ffffff", //hex color for the background (optional, accepts only #000000 or #ffffff) "navbar_color": "#426b55" //hex color for top navbar background color (optional, accepts any color) }, "logo_url": "https://linktologo.com/link.png" //url for the logo that will be added to the initiation flow } } } ``` If you input the correct parameters, you will receive an *HTTP 200* response akin to: ```json theme={null} { "data": { "company_id": "018da8cb-17da-5287-40c4-724ed90e2a0e", "expiration_timestamp": "2024-05-04T19:44:11.960965Z", "id": "018f4002-6d38-7d42-7c5f-c2dd50842d51", "options": { "allow_other_pix_key": null, "session_type": "payin", "theme": { "colors": { "backdrop_color": "#888888", "button_color": "#15294B", "button_label_color": "#FFFFFF", "link_color": "#15294B", "navbar_action_color": "#000000", "navbar_color": "#FFFFFF" }, "logo_url": "https://www.trio.com.br/_next/static/media/Logo.341273f5.svg" } }, "participants": null, "receiver": { "virtual_account_id": "018e3df6-d70f-9489-2c7e-ca880a25ea46" }, "timestamp": "2024-05-03T19:50:51.960965Z", "transaction": { "amount": { "amount": 1, "currency": "BRL" }, "available_withdraw_amount": null, "description": "Paid to example.com", "email": "user@trio.com.br", "expiration_in_seconds": 86000, "external_id": "Sessão de Teste", "name": "John Doe", "phone_number": "+5541999999999", "redirect_url": "http://your.url.here", "tax_number": "23725474028" } } } ``` #### **Flow** When making use of the Checkout, the following screens will appear: # Payout Source: https://docs.trio.com.br/trio-sdk/flows/payout The payout session type shall be used whenever you want users to cash out their data. In order to generate a payout through our Checkout SDK, you must create a Checkout Session. In it, there are some parameters that you will need to pay attention to (\* for required fields): * **options** * `session_type`\*: session type, in this case **payout**. * `expiration_in_seconds`: integer value. If set, the Checkout session will only remain active up until this time. If not, the default time is 300 seconds (5 minutes). * `allow_other_pix_key`: boolean value. If true, the Checkout will allow for a Pix Key different from the ones informed in the Session creation to be input. At the Cash-Out step, they will be verified and only successfully paid if the Pix key belongs to the tax number initially provided. If not, the payment will fail. * **transaction** * `tax_number`\*: the document/tax number (CPF/CNPJ) that represents the person you intend to pay money to. * `phone_number`: a Pix key in the format of a *phone number* that you would like to allow the user to select. Optional. * `email`: a Pix key in the format of an *email* that you would like to allow the user to select. Optional. * `available_withdraw_amount`\*: the maximum quantity you would like to allow your client to withdraw in this transaction. Keep in mind that the user can choose to withdraw less than the available you set. * `amount`: This amount will be the value pre-set on the user's input field, if this amount is set larger than the available withdrawal amount, the session will be created utilizing the `available_withdraw_amount` field as the correct amount. #### **White label** You can also customize your end-user experience by utilizing the Checkout as a *white label*. You can do so by utilizing the `options` field, with the respective `xxxx_color` fields. Below, you can see an example of a wholly implemented customization: #### **Create Session** In order to create a session, you must make a `POST` request to `/checkout/sessions` with the following payload: ```json theme={null} { "transaction": { "tax_number": "23725474028", // John Doe's document/tax number "phone_number": "+5541999999999", // John Doe's phone Pix key "email": "user@trio.com.br", // John Doe's e-mail Pix key "name": "John Doe", // Customer name "available_withdraw_amount": 100, // maximum withdraw amount in cents, integer value "amount": 1, // total amount in cents "external_id": "01H7DKA58YDWPA7ZBCCAVWFM5E", // reference for your system "description": "Paid to example.com" // additional information about the transaction }, "receiver": { "virtual_account_id": "018a66ca-0451-9cd7-1cfa-8dca325db29f" // unique identifier for the virtual account that will receive the money }, "options": { "session_type": "payout", // Session type (must be payout) "allow_other_pix_key": false, // boolean "expiration_in_seconds": "86400", // session expiration time, integer value "theme": { "colors": { "backdrop_color": "#ffffff", //hex color for the background (optional, accepts any color) "button_color": "#f6df69", //hex color for the interface primary action button (optional, accepts any color) "button_label_color": "#000000", //hex color for the interface primary action text (optional, accepts only #000000 or #ffffff) "link_color": "#426b55", //hex color for links (optional, accepts any color) "navbar_action_color": "#ffffff", //hex color for the background (optional, accepts only #000000 or #ffffff) "navbar_color": "#426b55" //hex color for top navbar background color (optional, accepts any color) }, "logo_url": "https://linktologo.com/link.png" //url for the logo that will be added to the initiation flow } } } ``` If you input the correct parameters, you will receive a *HTTP 200* response akin to: ```json theme={null} { "data": { "company_id": "018da8cb-17da-5287-40c4-724ed90e2a0e", "expiration_timestamp": "2024-05-04T19:44:11.960965Z", "id": "018f4002-6d38-7d42-7c5f-c2dd50842d51", "options": { "allow_other_pix_key": false, "session_type": "payout", "theme": { "colors": { "backdrop_color": "#888888", "button_color": "#15294B", "button_label_color": "#FFFFFF", "link_color": "#15294B", "navbar_action_color": "#000000", "navbar_color": "#FFFFFF" }, "logo_url": "https://www.trio.com.br/_next/static/media/Logo.341273f5.svg" } }, "participants": null, "receiver": { "virtual_account_id": "018e3df6-d70f-9489-2c7e-ca880a25ea46" }, "timestamp": "2024-05-03T19:50:51.960965Z", "transaction": { "amount": { "amount": 1, "currency": "BRL" }, "available_withdraw_amount": 100, "description": "Paid to example.com", "email": null, "expiration_in_seconds": 86000, "external_id": "Sessão de Teste", "name": null, "phone_number": null, "redirect_url": "http://your.url.here", "tax_number": null } } } ``` #### **Flow** When making use of the Checkout, the following screens will appear: # Introduction Source: https://docs.trio.com.br/trio-sdk/introduction Our **SDK**, or as we call it, **Trio Checkout**, is a tool that allows your users to implement Trio's payment system in a straightforward manner. By using an SDK embedded in your website, you will be able to offer your clients both Payment Initiation and the whole PayIn/PayOut processes offered by our API, always handling it with isolated end-to-end security when linking to banks and financial institutions. Everything done through Checkout is done simply and without much code needed, and all stages of the consent and payment process are managed through the **Trio Checkout**, from credential validation and authentication to error handling and notifications pertaining to each payment flow. # Local example Source: https://docs.trio.com.br/trio-sdk/local-example # Trio Checkout SDK Example This project demonstrates how to integrate the Trio Checkout SDK using: * A local Node.js backend (`server.js`) * A local frontend (`index.html`) * Python HTTP Server for frontend hosting *** # Requirements Before starting, make sure you have installed: * Node.js (v18+ recommended) * npm * Python 3 *** # Project Structure ```bash theme={null} local-example/ ├── server.js ├── package.json └── index.html ``` *** # 1. Install Backend Dependencies Create a `package.json` file: ```bash theme={null} npm init -y ``` Install the required dependencies: ```bash theme={null} npm install express cors ``` *** # 2. Configure Credentials Inside `server.js`, replace the following values: ```js theme={null} const CLIENT_ID = "YOUR_CLIENT_ID"; const CLIENT_SECRET = "YOUR_CLIENT_SECRET"; ``` With your Trio Sandbox credentials. *** # 3. Run the Backend Server Start the server using: ```bash theme={null} node server.js ``` You should see: ```bash theme={null} Servidor rodando na porta 3000 ``` The backend will now be available at: ```bash theme={null} http://localhost:3000 ``` *** # 4. Run the Frontend Locally The frontend uses the browser SDK and must be served through an HTTP server. Open a new terminal in the project folder and run: ```bash theme={null} python3 -m http.server 8080 ``` If `python3` does not work, try: ```bash theme={null} python -m http.server 8080 ``` The frontend will now be available at: ```bash theme={null} http://localhost:8080 ``` *** # 5. Open the Application Open your browser and access: ```bash theme={null} http://localhost:8080 ``` *** # How It Works 1. The frontend collects: * Transaction type * CPF * Amount 2. The frontend sends a request to: ```bash theme={null} POST http://localhost:3000/create-session ``` 3. The backend creates a Trio Checkout Session using the Trio API. 4. The backend returns the `session_id`. 5. The frontend initializes the Trio SDK: ```js theme={null} Trio.create({ environment: "sandbox", session: session_id }); ``` 6. The checkout modal opens automatically. *** # Available Transaction Types ```txt theme={null} payin payout ``` *** # Sandbox Environment This example uses the Trio Sandbox API: ```bash theme={null} https://api.sandbox.trio.com.br ``` *** # Important Notes * Make sure port `3000` is available for the backend. * Make sure port `8080` is available for the frontend. * CORS is enabled in the backend for local development. * Never expose production credentials publicly. *** # Example Request Payload ```json theme={null} { "type": "payin", "cpf": "12345678900", "amount": 15000 } ``` Amount must be sent in cents. Example: ```txt theme={null} 150.00 BRL = 15000 ``` *** # Troubleshooting ## Port already in use Change the port in `server.js`: ```js theme={null} const PORT = 3000; ``` And update the frontend request URL if necessary. *** ## Python command not found Install Python 3 or use: ```bash theme={null} python3 -m http.server 8080 ``` *** ## CORS errors Ensure the backend server is running before opening the frontend. *** # Support For integration support, contact: * [support@trio.com.br](mailto:support@trio.com.br) * [https://suporte.trio.com.br](https://suporte.trio.com.br) *** # Download Example Project You can download the complete local example project here: [Download the ZIP file](./local-example.zip) The ZIP package includes: * `server.js` * `index.html` * Local backend example * Frontend checkout example * SDK integration example # Using the sdk Source: https://docs.trio.com.br/trio-sdk/using-the-sdk 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](https://app.trio.com.br/developers/api_keys)), 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](#/reference/banking-api/checkout). ### 1. Embed the SDK First, you need to embed our SDK through a `script` tag just before the closing of the `` tag in your HTML: ```html theme={null} ``` 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 "pay in", "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 below: * [Pay-in](#/guides/sdk/flows/pay-in) * [Payout](#/guides/sdk/flows/payout) After creating a session, make sure that you saved the `id` returned. It will be necessary in order to 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 an object as parameter that must contain such information: **Environment** A property defining the environment: ```json theme={null} 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: ```json theme={null} 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()`: ```javascript theme={null} 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()` ```html theme={null} ``` ### 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)](#/developers/webooks/events/collecting-document) * [Payout webhook (payment document)](#/developers/webooks/events/payment-document) You can also access the documents inside our Dashboard: 1. In Sandbox: 1. Pay-in - `app.sandbox.trio.com.br/documents/in/{document_id}` 2. Payout - `app.sandbox.trio.com.br/documents/out/{document_id}` 2. In Production 1. Pay-in - `app.trio.com.br/documents/in/{document_id}` 2. Payout - `app.trio.com.br/documents/out/{document_id}` # Authentication Source: https://docs.trio.com.br/webhooks/authentication When you create a webhook, it's necessary to fill the `Secret`field, this information will be sent through as the HTTP header `x-webhook-secret`. You can use the to authenticate at your side. And to verify that a webhook was actually sent by Trio, every payload is signed with a signature that is passed through as the HTTP header `x-webhook-signature`. The signature is encoded and can be replicated by applying HMAC-SHA-256 to the body of the webhook with your specific webhook key, which can be found in your webhook settings page. Below, a simple example of how to generate the signature using Node.js: ```text theme={null} import { createHmac, timingSafeEqual } from "crypto" const expectedSignature = req.headers["x-webhook-signature"] const algorithm = "sha256" const signatureKey = "your_signature_key" const message = JSON.stringify(req.body) const computedSignature = createHmac(algorithm, signatureKey) .update(message) .digest("hex") .toUpperCase() const isValid = timingSafeEqual( Buffer.from(expectedSignature), Buffer.from(computedSignature) ) ``` Please contact support if your webhook key is accidentally made public. We will rotate the key and coordinate the change with you. # Content and Structure Source: https://docs.trio.com.br/webhooks/content-and-structure All the notifications sent by Trio uses the following structure: * `ref_id` is the identification from the reference * `category` specifies which category the event belongs * `type` specifies what type of event from the category ```text theme={null} { "ref_id": "", "category": "", "type": "", "timestamp": "", "data": {} } ``` # Collecting document Source: https://docs.trio.com.br/webhooks/events/collecting-document Events that belong to the category `collecting_document`. | | | --------------------------------------------------------------------------------------------------------- | | A collecting document (cash-in) was successfully received and registered in the system. | | A collecting document (cash-in) was received but could not be processed and was refused. | ### Examples #### collecting\_document.settled ```json theme={null} { "data": { "amount": { "amount": 100, "currency": "BRL" }, "counterparty": { "company_id": "91978496-c904-40d0-9322-5f2838efb542", "id": "29b6d0bc-7226-483b-99aa-aa815521ebb0", "name": "Conta 002", "tax_number": "45865162797606" }, "counterparty_bank_account": { "branch": "0001", "digit": "5", "id": "29b6d0bc-7226-5af3-c274-d4242429236f", "ispb": "49931906", "number": "47919554", "type": "checking" }, "description": null, "end_to_end_id": "E49931906202501311822NX1S6J7KaOm", "external_id": null, "id": "0194bd99-65cd-5ee9-70f6-44d61ae5aa41", "origin_id": "8180b04e-e436-44e5-bd24-f6ed79dffe08", "origin_type": "console_user", "receipt_url": "https://receipts.sandbox.trio.com.br/019108db-d49f-c744-5b79-736a2849ddf5/in/0194bd99-65cd-5ee9-70f6-44d61ae5aa41", "reconciliation_id": "0194bd99-65cd-b51d-4f8f-78735341777b", "ref_id": "0194bd96-9e39-2a47-9420-1e047cb762b3", "ref_type": "pix_qrcode", "transaction_date": "2025-01-31T18:22:14.510717Z", "type": "pix", "virtual_account_id": "0194412c-c559-5452-942e-7f4b4975c666" }, "timestamp": "2025-01-31T18:22:14.477163Z", "type": "settled", "category": "collecting_document", "context_id": "91978496-c904-40d0-9322-5f2838efb542", "context_type": "internet_banking", "ref_id": "0194bd99-65cd-5ee9-70f6-44d61ae5aa41" } ``` #### collecting\_document.failed ```json theme={null} { "data": { "amount": { "amount": 100, "currency": "BRL" }, "counterparty": { "company_id": "91978496-c904-40d0-9322-5f2838efb542", "id": "29b6d0bc-7226-483b-99aa-aa815521ebb0", "name": "Conta 002", "tax_number": "45865162797606" }, "counterparty_bank_account": { "branch": "0001", "digit": "5", "id": "29b6d0bc-7226-5af3-c274-d4242429236f", "ispb": "49931906", "number": "47919554", "type": "checking" }, "description": null, "end_to_end_id": "E49931906202501311825zSQGRMknozm", "error_code": "BE17", "error_message": ""Brcode possui contrapartida diferente"", "external_id": "1", "id": "0194bd9c-90b4-b8b2-12e9-675fe55340a8", "origin_id": "8180b04e-e436-44e5-bd24-f6ed79dffe08", "origin_type": "console_user", "receipt_url": "https://receipts.sandbox.trio.com.br/019108db-d49f-c744-5b79-736a2849ddf5/in/0194bd9c-90b4-b8b2-12e9-675fe55340a8", "reconciliation_id": "0194bd9c-90b4-7202-dd06-65685ce89efb", "ref_id": "0194bd9b-d0c1-8201-f41c-15d69a2d5e6b", "ref_type": "pix_qrcode", "rule": "pix_qrcode_different_tax_number", "transaction_date": null, "type": "pix", "virtual_account_id": "0194412c-c559-5452-942e-7f4b4975c666" }, "timestamp": "2025-01-31T18:25:42.068091Z", "type": "failed", "category": "collecting_document", "context_id": "91978496-c904-40d0-9322-5f2838efb542", "ref_id": "0194bd9c-90b4-b8b2-12e9-675fe55340a8", "context_type": "internet_banking" } ``` # Collecting document refund Source: https://docs.trio.com.br/webhooks/events/collecting-document-refund Events that belong to the category `collecting_document_refund`.
TypeDescription
createdA collecting document refund was created.
settledA collecting document refund was successfully settled and registered.
failedA collecting document refund has failed due to an error.
### Examples #### collecting\_document\_refund.created ```json theme={null} { "data": { "amount": { "amount": 100, "currency": "BRL" }, "collecting_document_id": "0194cbda-ccda-c86b-b7c3-464c5344109c", "description": "Devolução manual feita por Jessica Barcellos", "end_to_end_id": "D49931906202502031257bAqO8f0YhUH", "external_id": null, "id": "0194cbe3-6145-abc7-d309-b56da0381cd4", "origin_id": "8180b04e-e436-44e5-bd24-f6ed79dffe08", "origin_type": "console_user", "receipt_url": "https://receipts.sandbox.trio.com.br/019108db-d49f-c744-5b79-736a2849ddf5/in_refund/0194cbe3-6145-abc7-d309-b56da0381cd4", "reconciliation_id": "0194cbe3-6145-8baa-226c-4eaa75c5ed8a", "rule": "manual", "transaction_date": null, "virtual_account_id": "0194412c-c559-5452-942e-7f4b4975c666" }, "timestamp": "2025-02-03T12:57:44.005471Z", "type": "created", "category": "collecting_document_refund", "context_id": "91978496-c904-40d0-9322-5f2838efb542", "context_type": "internet_banking", "ref_id": "0194cbe3-6145-abc7-d309-b56da0381cd4" } ``` #### collecting\_document\_refund.settled ```json theme={null} { "data": { "amount": { "amount": 100, "currency": "BRL" }, "collecting_document_id": "0194cbda-ccda-c86b-b7c3-464c5344109c", "description": "Devolução manual feita por Jessica Barcellos", "end_to_end_id": "D49931906202502031257bAqO8f0YhUH", "external_id": null, "id": "0194cbe3-6145-abc7-d309-b56da0381cd4", "origin_id": "8180b04e-e436-44e5-bd24-f6ed79dffe08", "origin_type": "console_user", "receipt_url": "https://receipts.sandbox.trio.com.br/019108db-d49f-c744-5b79-736a2849ddf5/in_refund/0194cbe3-6145-abc7-d309-b56da0381cd4", "reconciliation_id": "0194cbe3-6145-8baa-226c-4eaa75c5ed8a", "rule": "manual", "transaction_date": "2025-02-03T12:57:44.574180Z", "virtual_account_id": "0194412c-c559-5452-942e-7f4b4975c666", }, "timestamp": "2025-02-03T12:57:44.005471Z", "type": "settled", "category": "collecting_document_refund", "context_id": "91978496-c904-40d0-9322-5f2838efb542", "context_type": "internet_banking", "ref_id": "0194cbe3-6145-abc7-d309-b56da0381cd4", } ``` # Initiation document Source: https://docs.trio.com.br/webhooks/events/initiation-document Events that belong to the category `initiation_document`. These events track the lifecycle of a payment initiated through Pix biometrics. All status updates include the full payment document data.
TypeDescription
createdA biometrics payment has been created.
awaiting\_consentThe payment is waiting for the customer to authorize via biometrics (WebAuthn).
awaiting\_paymentBiometric authorization completed, the bank is processing the payment.
settledThe payment was completed successfully.
rejectedThe payment was rejected by the participant.
failedThe payment failed due to an error.
### Examples #### initiation\_document.created ```json theme={null} { "data": { "id": "019fa156-a7e1-35f9-670b-acc72e2eaeff", "status": "created", "amount": { "currency": "BRL", "amount": 1000 }, "session_id": null, "inserted_at": "2026-07-27T02:10:38.800558Z", "updated_at": "2026-07-27T02:10:38.800558Z", "external_id": "my-external-ref-001", "end_to_end_id": "E12345678202607270210vcUjWGmFBGo", "transaction_date": "2026-07-27T02:10:38.689111Z", "virtual_account_id": "01991648-0f53-cd50-b24f-0003b45b45f9", "redirect_url": null, "origin_id": "019f9b20-65fd-c516-da43-95843e4d0881", "origin_type": "api_client", "ref_id": "000e2ac2-840c-f37c-80a8-48bfa57d2338", "entity_id": "01991647-e564-c2eb-bd8c-07682cfa7d13", "ref_type": "enrollment", "counterparty_id": "000e2ac2-840c-fd63-9b04-c43e6c6ed4e2", "reconciliation_id": "019fa156-a7e1-8dd8-9ff7-5fa03bd7af72", "integration_id": "019fa156-a7e1-cfb2-4b48-327f88bf55b2", "participant_id": "019f9bca-a3e0-3fba-a997-f31ae2c0c40b", "consent_id": null }, "timestamp": "2026-07-27T02:10:38.689043Z", "type": "created", "category": "initiation_document", "ref_id": "019fa156-a7e1-35f9-670b-acc72e2eaeff", "context_type": "internet_banking", "context_id": "926b0dac-b5e9-43cd-ae79-ba55c33e124a" } ``` #### initiation\_document.awaiting\_consent ```json theme={null} { "data": { "id": "019fa156-a7e1-35f9-670b-acc72e2eaeff", "status": "awaiting_consent", "amount": { "currency": "BRL", "amount": 1000 }, "session_id": null, "inserted_at": "2026-07-27T02:10:38.800558Z", "updated_at": "2026-07-27T02:10:38.800558Z", "external_id": "my-external-ref-001", "end_to_end_id": "E12345678202607270210vcUjWGmFBGo", "transaction_date": "2026-07-27T02:10:38.689111Z", "virtual_account_id": "01991648-0f53-cd50-b24f-0003b45b45f9", "redirect_url": null, "origin_id": "019f9b20-65fd-c516-da43-95843e4d0881", "origin_type": "api_client", "ref_id": "000e2ac2-840c-f37c-80a8-48bfa57d2338", "entity_id": "01991647-e564-c2eb-bd8c-07682cfa7d13", "ref_type": "enrollment", "counterparty_id": "000e2ac2-840c-fd63-9b04-c43e6c6ed4e2", "reconciliation_id": "019fa156-a7e1-8dd8-9ff7-5fa03bd7af72", "integration_id": "019fa156-a7e1-cfb2-4b48-327f88bf55b2", "participant_id": "019f9bca-a3e0-3fba-a997-f31ae2c0c40b", "consent_id": null }, "timestamp": "2026-07-27T02:10:38.689043Z", "type": "awaiting_consent", "category": "initiation_document", "ref_id": "019fa156-a7e1-35f9-670b-acc72e2eaeff", "context_type": "internet_banking", "context_id": "926b0dac-b5e9-43cd-ae79-ba55c33e124a" } ``` #### initiation\_document.awaiting\_payment ```json theme={null} { "data": { "id": "019fa156-a7e1-35f9-670b-acc72e2eaeff", "status": "awaiting_payment", "amount": { "currency": "BRL", "amount": 1000 }, "session_id": null, "inserted_at": "2026-07-27T02:10:38.800558Z", "updated_at": "2026-07-27T02:10:44.587366Z", "external_id": "my-external-ref-001", "end_to_end_id": "E12345678202607270210vcUjWGmFBGo", "transaction_date": "2026-07-27T02:10:38.689111Z", "virtual_account_id": "01991648-0f53-cd50-b24f-0003b45b45f9", "redirect_url": null, "origin_id": "019f9b20-65fd-c516-da43-95843e4d0881", "origin_type": "api_client", "ref_id": "000e2ac2-840c-f37c-80a8-48bfa57d2338", "entity_id": "01991647-e564-c2eb-bd8c-07682cfa7d13", "ref_type": "enrollment", "counterparty_id": "000e2ac2-840c-fd63-9b04-c43e6c6ed4e2", "reconciliation_id": "019fa156-a7e1-8dd8-9ff7-5fa03bd7af72", "integration_id": "019fa156-a7e1-cfb2-4b48-327f88bf55b2", "participant_id": "019f9bca-a3e0-3fba-a997-f31ae2c0c40b", "consent_id": null }, "timestamp": "2026-07-27T02:10:38.689043Z", "type": "awaiting_payment", "category": "initiation_document", "ref_id": "019fa156-a7e1-35f9-670b-acc72e2eaeff", "context_type": "internet_banking", "context_id": "926b0dac-b5e9-43cd-ae79-ba55c33e124a" } ``` #### initiation\_document.settled ```json theme={null} { "data": { "id": "019fa156-a7e1-35f9-670b-acc72e2eaeff", "status": "settled", "amount": { "currency": "BRL", "amount": 1000 }, "session_id": null, "inserted_at": "2026-07-27T02:10:38.800558Z", "updated_at": "2026-07-27T02:12:40.102228Z", "external_id": "my-external-ref-001", "end_to_end_id": "E12345678202607270210vcUjWGmFBGo", "transaction_date": "2026-07-27T02:10:38.689111Z", "virtual_account_id": "01991648-0f53-cd50-b24f-0003b45b45f9", "redirect_url": null, "origin_id": "019f9b20-65fd-c516-da43-95843e4d0881", "origin_type": "api_client", "ref_id": "000e2ac2-840c-f37c-80a8-48bfa57d2338", "entity_id": "01991647-e564-c2eb-bd8c-07682cfa7d13", "ref_type": "enrollment", "counterparty_id": "000e2ac2-840c-fd63-9b04-c43e6c6ed4e2", "reconciliation_id": "019fa156-a7e1-8dd8-9ff7-5fa03bd7af72", "integration_id": "019fa156-a7e1-cfb2-4b48-327f88bf55b2", "participant_id": "019f9bca-a3e0-3fba-a997-f31ae2c0c40b", "consent_id": "019fa158-8065-eb54-986e-6aa7c8f9609e" }, "timestamp": "2026-07-27T02:10:38.689043Z", "type": "settled", "category": "initiation_document", "ref_id": "019fa156-a7e1-35f9-670b-acc72e2eaeff", "context_type": "internet_banking", "context_id": "926b0dac-b5e9-43cd-ae79-ba55c33e124a" } ``` # Payment document Source: https://docs.trio.com.br/webhooks/events/payment-document Events that belong to the category `payment_document`.
TypeDescription
createdA payment document has been created.
settledA payment document was confirmed and successfully registered.
failedA payment document was sent and not processed due to invalid information or declined by the bank.
### Examples #### payment\_document.created ```json theme={null} { "data": { "amount": { "amount": 100, "currency": "BRL" }, "counterparty": { "company_id": "91978496-c904-40d0-9322-5f2838efb542", "id": "29b6d0bc-7226-483b-99aa-aa815521ebb0", "name": "Conta bancária 1 padrão", "tax_number": "45865162797606" }, "counterparty_bank_account": { "branch": "0001", "digit": "0", "id": "29b6d0bc-7226-22d9-d45f-71d7d25e2d4c", "ispb": "49931906", "number": "54455708", "type": "checking" }, "description": null, "end_to_end_id": "E49931906202502031248GP6ibT9SHqT", "external_id": "Pix Console 0194cbda-8c8c-ff83-9f1d-c3c50f5ec0df", "id": "0194cbda-a2ca-5ecd-9796-99be6b7f4485", "origin_id": null, "origin_type": "none", "receipt_url": "https://receipts.sandbox.trio.com.br/019108db-d49f-c744-5b79-736a2849ddf5/out/0194cbda-a2ca-5ecd-9796-99be6b7f4485", "reconciliation_id": "0194cbda-a2ca-e301-d18f-6775388a2c8f", "ref_id": "0194cbda-a2ca-5ecd-9796-99be6b7f4485", "ref_type": "pix_qrcode", "transaction_date": null, "type": "pix", "virtual_account_id": "019440cd-a30f-c102-ff8c-a9d4e6939d48" }, "timestamp": "2025-02-03T12:48:10.954083Z", "type": "created", "category": "payment_document", "context_id": "91978496-c904-40d0-9322-5f2838efb542", "context_type": "internet_banking", "ref_id": "0194cbda-a2ca-5ecd-9796-99be6b7f4485" } ``` #### payment\_document.settled ```json theme={null} { "data": { "amount": { "amount": 100, "currency": "BRL" }, "counterparty": { "company_id": "91978496-c904-40d0-9322-5f2838efb542", "id": "29b6d0bc-7226-483b-99aa-aa815521ebb0", "name": "Conta bancária 1 padrão", "tax_number": "45865162797606" }, "counterparty_bank_account": { "branch": "0001", "digit": "0", "id": "29b6d0bc-7226-22d9-d45f-71d7d25e2d4c", "ispb": "49931906", "number": "54455708", "type": "checking" }, "description": null, "end_to_end_id": "E49931906202502031248GP6ibT9SHqT", "external_id": "Pix Console 0194cbda-8c8c-ff83-9f1d-c3c50f5ec0df", "id": "0194cbda-a2ca-5ecd-9796-99be6b7f4485", "origin_id": null, "origin_type": "none", "receipt_url": "https://receipts.sandbox.trio.com.br/019108db-d49f-c744-5b79-736a2849ddf5/out/0194cbda-a2ca-5ecd-9796-99be6b7f4485", "reconciliation_id": "0194cbda-a2ca-e301-d18f-6775388a2c8f", "ref_id": "0194cbda-a2ca-5ecd-9796-99be6b7f4485", "ref_type": "pix_qrcode", "transaction_date": "2025-02-03T12:48:21.405797Z", "type": "pix", "virtual_account_id": "019440cd-a30f-c102-ff8c-a9d4e6939d48" }, "timestamp": "2025-02-03T12:48:10.954083Z", "type": "settled", "category": "payment_document", "context_id": "91978496-c904-40d0-9322-5f2838efb542", "context_type": "internet_banking", "ref_id": "0194cbda-a2ca-5ecd-9796-99be6b7f4485" } ``` # Payment document refund Source: https://docs.trio.com.br/webhooks/events/payment-document-refund Events that belong to the category `payment_document_refund`.
TypeDescription
settledA refund payment document was successfully settled.
### Examples #### payment\_document.settled ```json theme={null} { "data": { "amount": { "amount": 100, "currency": "BRL" }, "description": null, "end_to_end_id": "D49931906202502031257bAqO8f0YhUH", "external_id": "Pix Console 0194cbda-8c8c-ff83-9f1d-c3c50f5ec0df", "id": "0194cbe3-63ea-e00f-3749-044a4e1b673c", "origin_id": null, "origin_type": "none", "payment_document_id": "0194cbda-a2ca-5ecd-9796-99be6b7f4485", "receipt_url": "https://receipts.sandbox.trio.com.br/019108db-d49f-c744-5b79-736a2849ddf5/out_refund/0194cbe3-63ea-e00f-3749-044a4e1b673c", "reconciliation_id": "0194cbe3-63ea-c748-90b0-7ddb1a193acb", "rule": "manual", "transaction_date": "2025-02-03T12:57:44.787470Z", "virtual_account_id": "019440cd-a30f-c102-ff8c-a9d4e6939d48" }, "timestamp": "2025-02-03T12:57:44.682219Z", "type": "settled", "category": "payment_document_refund", "context_id": "91978496-c904-40d0-9322-5f2838efb542", "context_type": "internet_banking", "ref_id": "0194cbe3-63ea-e00f-3749-044a4e1b673c" } ``` # Pix biometrics enrollment Source: https://docs.trio.com.br/webhooks/events/pix-biometrics-enrollment Events that belong to the category `pix_biometrics_enrollment`. | | | ---------------------------------------------------------------------------------------------------------------------------------------- | | The enrollment status has been updated to **awaiting\_account\_holder\_validation** — waiting for the customer to authorize at the bank. | | The enrollment status has been updated to **awaiting\_enrollment** — bank authorization completed, waiting for biometric registration. | | The enrollment has been **authorized** and is ready for payments. | | The enrollment has been **rejected** by the bank. | | The enrollment has been **revoked** by the customer on the bank's end. | | The enrollment has become **inactive** (expired). | ### Examples #### pix\_biometrics\_enrollment.authorized ```json theme={null} { "data": { "id": "000e2ac2-840c-f37c-80a8-48bfa57d2338", "status": "authorized", "inserted_at": "2026-07-26T23:18:01.931556Z", "updated_at": "2026-07-26T23:18:41.884626Z", "external_id": "12345", "redirect_url": "https://checkout.of.sandbox.trio.com.br/sandbox/banking/enrollment?enrollment_id=000e2ac2-840c-f37c-80a8-48bfa57d2338", "expiration_datetime": null, "participant_id": "019f9bca-a3e0-3fba-a997-f31ae2c0c40b", "device_id": "000e2ac2-840c-ccb3-0add-9132af7e300d", "account_info": null }, "timestamp": "2026-07-26T23:18:42.213037Z", "type": "authorized", "category": "pix_biometrics_enrollment", "inserted_at": "2026-07-26T23:18:42.213082Z", "origin_type": "api_client", "ref_id": "000e2ac2-840c-f37c-80a8-48bfa57d2338", "context_type": "internet_banking", "context_id": "926b0dac-b5e9-43cd-ae79-ba55c33e124a" } ``` # Recurrence Source: https://docs.trio.com.br/webhooks/events/recurrence Events that belong to the category `recurrence`.
TypeDescription
createdA recurrence was created.
approvedA recurrence was approved.
rejectedA recurrence was rejected.
expiredA recurrence was expired.
cancelledA recurrence was cancelled.
### Examples #### recurrence.approved ```json theme={null} { "event": { "data": { "retry_policy": "3r_7d", "stages": "[{\"id\":\"0199d478-de39-e970-7b2b-d643b148340d\",\"status\":\"created\",\"timestamp\":\"2025-10-11T18:11:55.065746Z\",\"request_id\":null,\"error_code\":null,\"error_message\":null,\"inserted_at\":\"2025-10-11T18:11:55.079001Z\",\"updated_at\":\"2025-10-11T18:11:55.079001Z\",\"request_timestamp\":null,\"recurrence_id\":\"0199d478-de39-fcf3-87a9-e8bded7db468\",\"bank_account_id\":null,\"reference_type\":\"qrdn\",\"reference_id\":null,\"collection_id\":null,\"collection_timestamp\":null,\"cancelation_code\":null,\"cancelation_description\":null,\"cancelation_origin\":null,\"rejection_code\":null,\"rejection_description\":null,\"journey\":\"aut3\"},{\"id\":\"0199d478-de39-957a-43b6-19c19f5f7620\",\"status\":\"approved\",\"timestamp\":\"2025-10-11T18:11:55.065746Z\",\"request_id\":null,\"error_code\":null,\"error_message\":null,\"inserted_at\":\"2025-10-11T18:13:28.874345Z\",\"updated_at\":\"2025-10-11T18:13:28.874345Z\",\"request_timestamp\":null,\"recurrence_id\":\"0199d478-de39-fcf3-87a9-e8bded7db468\",\"bank_account_id\":null,\"reference_type\":\"qrdn\",\"reference_id\":null,\"collection_id\":null,\"collection_timestamp\":null,\"cancelation_code\":null,\"cancelation_description\":null,\"cancelation_origin\":null,\"rejection_code\":null,\"rejection_description\":null,\"journey\":\"aut3\"}]", "end_date": null, "number_of_collections": null, "contract_number": "565d00c968754605b41e122e7679d260", "type": "in", "reference_type": "qrdn", "authorization_date": "2025-10-11T18:13:27.000000Z", "org_id": "34713ca3-0b83-47d8-a173-cdc26609edbc", "description": "Obrigado por sua doação", "next_working_day": false, "id": "0199d478-de39-fcf3-87a9-e8bded7db468", "periodicity": "mnth", "txid": "01K7A7HQHSZKSRFAF8QQPQVD38", "version": 3, "timestamp": "2025-10-11T18:11:55.065746Z", "bank_account_id": "019953b0-535d-e973-4334-aa0f29ac9441", "automated_collecting": false, "counterparty_seq": 11, "reference_id": null, "start_date": "2025-11-11T18:11:54.433341Z", "status": "approved", "maximum_amount": null, "external_id": "565d00c968754605b41e122e7679d260", "origin_id": "01985b9a-2a0b-e7ca-954b-acfe68553971", "counterparty_id": "0002b135-5463-763d-55a8-7ad885f521d7", "origin_type": "api_client", "company_id": "019489e6-f64f-5cfe-770b-79b671ec66f0", "journey": "aut3", "updated_at": "2025-10-11T18:13:28.887893Z", "first_payment_amount": null, "first_payment_date": "2025-11-11T15:00:00.000000Z", "counterparty_bank_account_id": "0002b135-5463-379f-c7ea-941f1f02841f", "update_date": "2025-10-11T18:13:26.000000Z", "fixed_amount": 2000, "inserted_at": "2025-10-11T18:11:55.070544Z", "id_rec": "RR4993190620251011181155657BH", "minimum_amount": null, "entity_id": "019953ad-1738-b094-097c-7941a0c642a5", "sign": null, "counterparty_info_id": "0002b135-5463-e469-ce49-dc8f22ba6b0c", "group_id": "019953b0-5338-8673-88a4-cdee1b24de3c", "ispb": "49931906" }, "timestamp": "2025-10-11T18:11:55.065746Z", "type": "approved", "category": "recurrence", "inserted_at": "2025-10-11T18:13:29.350461Z", "origin_type": null, "ref_stage_id": null, "ref_id": "0199d478-de39-fcf3-87a9-e8bded7db468", "context_type": "bacen", "context_id": "019489e6-f64f-5cfe-770b-79b671ec66f0" } } ``` # Recurrence collections attempt Source: https://docs.trio.com.br/webhooks/events/recurrence-collections-attempt Events that belong to the category `recurrence's collections`.
TypeDescription
requestedA recurrence collection's attempt was created.
scheduledA recurrence collection's attempt was scheduled.
settledA recurrence collection's attempt was settled.
cancelledA recurrence collection's attempt was cancelled.
rejectedA recurrence collection's attempt was rejected.
expiredA recurrence collection's attempt was expired.
failedA recurrence collection's attempt was failed.
### Examples #### recurrence.scheduled ```json theme={null} { "event": { "data": { "id": "019a0222-6580-a64a-cfca-408b51642e22", "status": "scheduled", "timestamp": "2025-10-20T15:00:00.000000Z", "type": "AGND", "version": 2, "sign": null, "inserted_at": "2025-10-11T03:15:01.370394Z", "updated_at": "2025-10-11T03:15:07.623385Z", "external_id": "external_id", "stages": "[]", "end_to_end_id": "E49931906202510201500ReKBJaYDKWA", "transaction_date": null, "txid": "01K8124SC0MS5CZJJ0HD8P8BH2", "out_document_id": null, "out_document_timestamp": null, "due_date": "2025-10-20T15:00:00.000000Z", "collection_id": "019a0222-6580-e104-fce2-957756930115", "collection_timestamp": "2025-10-20T15:00:00.000000Z" }, "timestamp": "2025-10-20T15:00:00.000000Z", "type": "scheduled", "category": "recurrence_collection_attempt", "inserted_at": "2025-10-11T03:15:07.680443Z", "origin_type": null, "context_id": "019489e6-f64f-5cfe-770b-79b671ec66f0", "ref_stage_id": null, "ref_id": "019a0222-6580-a64a-cfca-408b51642e22", "context_type": "bacen" } } ``` # Recurrences collection Source: https://docs.trio.com.br/webhooks/events/recurrences-collection Events that belong to the category `recurrence's collections`.
TypeDescription
createdA recurrence's collection was created.
activeA recurrence's collection was active.
settledA recurrence's collection was settled.
expiredA recurrence's collection was expired.
rejectedA recurrence's collection was rejected.
cancelledA recurrence's collection was cancelled.
### Examples #### recurrence.action ```json theme={null} { "event": { "data": { "id": "019a0222-6580-e104-fce2-957756930115", "status": "active", "timestamp": "2025-10-20T15:00:00.000000Z", "version": 2, "sign": null, "amount": 1000, "group_id": "0198af49-717e-6f67-19d4-2e6cc84f498d", "inserted_at": "2025-10-09T00:15:01.773766Z", "updated_at": "2025-10-11T03:15:01.397667Z", "stages": "[]", "transaction_date": null, "company_id": "019489e6-f64f-5cfe-770b-79b671ec66f0", "org_id": "e370408d-9a0e-490b-92b1-8c4a0055dec2", "entity_id": "0198af47-e620-1507-295a-d96017946693", "recurrence_id": "0199c598-fee6-4c6b-5d6b-6cc86f2b0677", "bank_account_id": "0198af49-718a-a5e3-6c22-f1baabc1698c", "txid": "01K8124SC0W42FSRMNEXB9608N", "counterparty_info_id": "00016a74-c182-75ab-8d51-de42181733a3", "next_working_day": false, "aditional_info": null, "final_date": null, "recurrence_timestamp": "2025-10-08T20:52:42.342331Z", "attempts": "[]" }, "timestamp": "2025-10-20T15:00:00.000000Z", "type": "active", "category": "recurrence_collection", "inserted_at": "2025-10-11T03:15:07.680130Z", "origin_type": null, "ref_stage_id": null, "ref_id": "019a0222-6580-e104-fce2-957756930115", "context_type": "bacen", "context_id": "019489e6-f64f-5cfe-770b-79b671ec66f0" } } ``` # Transfer document Source: https://docs.trio.com.br/webhooks/events/transfer-document Events that belong to the category `transfer_document`.
TypeDescription
settledA transfer document was confirmed and successfully registered.
### Examples #### transfer\_document.settled ```json theme={null} { "data": { "amount": { "amount": 1000, "currency": "BRL" }, "description": "Transferência interna", "external_id": "Transferência interna - Console 0194cbe1-5b88-9057-b3d6-315c1451a699", "from_virtual_account_id": "019440cd-a30f-c102-ff8c-a9d4e6939d48", "id": "0194cbe1-a7bf-e03f-6fa7-79c432da1481", "origin_id": "8180b04e-e436-44e5-bd24-f6ed79dffe08", "origin_type": "console_user", "reconciliation_id": "0194cbe1-a7bf-73dd-e543-ac26409707bf", "to_virtual_account_id": "0194412c-c559-5452-942e-7f4b4975c666", "transaction_date": "2025-02-03T12:55:51.178153Z" }, "timestamp": "2025-02-03T12:55:50.975833Z", "type": "settled", "category": "transfer_document", "context_id": "91978496-c904-40d0-9322-5f2838efb542", "context_type": "internet_banking", "ref_id": "0194cbe1-a7bf-e03f-6fa7-79c432da1481" } ``` # Introduction Source: https://docs.trio.com.br/webhooks/introduction # Webhooks Most of the transactions at Trio's integration are asynchronous, which means that we have some process in background to finish and commit the transaction. In order to effective communicate with external systems and customers, we use [webhooks](https://pt.wikipedia.org/wiki/Webhook). ### **Technical details** All registered endpoints must be configured to receive an HTTP POST with JSON payload. We have a default timeout configured of 3 seconds waiting a 2XX HTTP status code in order to mark the payload as delivered. We have a special failure schema, our systems will try 5 times, with a retry configure for 16 seconds for the first failure and doubling the time each failure: 16s, 32s, 104s, 208s, etc. Furthermore, we recommend that all registered endpoints uses the HTTPS protocol to secure the in-transit payload.