Ctrlk
HomeBlogLoginSignup
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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.

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.

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.

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.

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.

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. 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

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

  • 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}

  • 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

  • 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

  • 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

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.

rejected

A cobrança foi rejeitada.

expired

A cobrança expirou.

cancelled

A cobrança foi cancelada.

Exemplo de payload

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.

failed

A tentativa falhou.

Exemplo de payload

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.

PreviousUsing Pix KeyNextErrors Table

Last updated