> For the complete documentation index, see [llms.txt](https://docs.trio.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trio.com.br/guides/recurrences/using-pix-automatico.md). # 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](https://claude.ai/chat/5d1e0ddf-cd69-4a30-b603-be1cec1e7791#opcoes-e-configuracoes-na-criacao)). #### 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 { "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 { "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 { "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 { "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 } } ``` #### 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 { "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 QR Code; `app` envia a solicitação direto ao app 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. | | `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 cobra em feriados; transfere 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](https://claude.ai/chat/5d1e0ddf-cd69-4a30-b603-be1cec1e7791#gestao-manual). #### Retentativa e o cliente que não paga A `retry_policy` controla o que acontece quando uma cobrança não é liquidada: * **`3r_7d`** — a cobrança é retentada 3 vezes ao longo de 7 dias, em dias alternados. Cada retentativa gera uma nova *tentativa* (`attempt`). Se nenhuma tentativa for liquidada, a cobrança vai para um status final de falha/expiração. * **`none`** — não há retentativa. Uma tentativa falha encerra a cobrança. > **Cancelar a recorrência quando o cliente não paga.** A política de retentativa 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 tentativa (`recurrence_collection_attempt` com tipo `failed`/`expired`) e/ou de cobrança (`recurrence_collection` com tipo `expired`/`rejected`) e, ao detectar o esgotamento das retentativas, chame o [cancelamento da recorrência](https://claude.ai/chat/5d1e0ddf-cd69-4a30-b603-be1cec1e7791#cancelando-a-recorrencia). Assim você implementa o "cancelamento automático por inadimplência" de forma controlada pela sua aplicação. *** ### 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 { "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 { "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 { "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 { "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 { "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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.trio.com.br/guides/recurrences/using-pix-automatico.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.