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.

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

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

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

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

{
  "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

{
  "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

{
  "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}

{
  "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

{
  "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

{
  "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

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

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

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.

Practical Guide

Operations

Using pix automatic

Using Pix Automatico

Endpoints

Criando uma recorrência

Valor fixo x valor variável

Variações por jornada

Resposta da criação

Opções e configurações na criação

Gestão de cobrança automática

Retentativas e clientes que não pagam

Gestão de cobranças (collections)

Gestão manual: criar a próxima cobrança

Agendar uma cobrança (gestão manual)

Atualizar o valor de uma cobrança antes do envio

Cancelar uma cobrança

Cancelando a recorrência

Consultas

Consultar uma recorrência

Listar recorrências

Consultar uma solicitação de autorização

Consultar e listar cobranças

Consultar e listar tentativas

Webhooks

Recorrência — categoria `recurrence`

Cobrança — categoria `recurrence_collection`

Tentativa da cobrança — categoria `recurrence_collection_attempt`

Resumo do fluxo de ponta a ponta

​Using Pix Automatico

​Endpoints

​Criando uma recorrência

​Valor fixo x valor variável

​Variações por jornada

​Resposta da criação

​Opções e configurações na criação

​Gestão de cobrança automática

​Retentativas e clientes que não pagam

​Gestão de cobranças (collections)

​Gestão manual: criar a próxima cobrança

​Agendar uma cobrança (gestão manual)

​Atualizar o valor de uma cobrança antes do envio

​Cancelar uma cobrança

​Cancelando a recorrência

​Consultas

​Consultar uma recorrência

​Listar recorrências

​Consultar uma solicitação de autorização

​Consultar e listar cobranças

​Consultar e listar tentativas

​Webhooks

​Recorrência — categoria recurrence

​Cobrança — categoria recurrence_collection

​Tentativa da cobrança — categoria recurrence_collection_attempt

​Resumo do fluxo de ponta a ponta

Using Pix Automatico

Endpoints

Criando uma recorrência

Valor fixo x valor variável

Variações por jornada

Resposta da criação

Opções e configurações na criação

Gestão de cobrança automática

Retentativas e clientes que não pagam

Gestão de cobranças (collections)

Gestão manual: criar a próxima cobrança

Agendar uma cobrança (gestão manual)

Atualizar o valor de uma cobrança antes do envio

Cancelar uma cobrança

Cancelando a recorrência

Consultas

Consultar uma recorrência

Listar recorrências

Consultar uma solicitação de autorização

Consultar e listar cobranças

Consultar e listar tentativas

Webhooks

Recorrência — categoria `recurrence`

Cobrança — categoria `recurrence_collection`

Tentativa da cobrança — categoria `recurrence_collection_attempt`

Resumo do fluxo de ponta a ponta