> ## Documentation Index > Fetch the complete documentation index at: https://docs.trio.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Using pix automatic # Using Pix Automatico 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). 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.