Transferências Inteligentes - Sweeping Accounts

Pré requisitos para implementação:

Possuir uma chave api da Celcoin, para mais informações acessar esse link

Visão Geral

Sweeping Accounts (Transferências Inteligentes) é uma modalidade de pagamento automático do Open Finance Brasil que permite ao usuário autorizar, com um único consentimento, múltiplas transferências Pix entre suas próprias contas, em instituições diferentes, de forma autônoma e sem necessidade de autenticação a cada transação.

O produto é regulamentado pelo Banco Central do Brasil dentro do escopo de Pagamentos Automáticos (SV Pagamentos Automáticos v1.0.0) e se diferencia do Pix Automático convencional por uma característica fundamental: o pagador e o recebedor são a mesma pessoa (CPF).

Casos de uso típicos incluem:

Transferência automática de saldo excedente de conta corrente para conta investimento
Manutenção de saldo mínimo entre contas
Consolidação de recursos em uma conta principal
Automação de aportes financeiros periódicos

Como Funciona

O fluxo do Sweeping Accounts é composto por duas etapas principais:

1. Criação do Consentimento (Payment Initiation)

A instituição iniciadora (ITP) cria uma payment initiation com as regras de autorização recorrente — limites de valor, periodicidade e conta de destino. O usuário é redirecionado para a detentora de conta para autenticação e aprovação do consentimento.

Após aprovação, a ITP recebe um code via callback e o troca por um consentimento ativo.

2. Execução dos Pagamentos

Com o consentimento ativo, a ITP pode disparar pagamentos Pix dentro dos limites definidos, sem nova autenticação do usuário, chamando o endpoint de execução de pagamento com o paymentInitiationId já autorizado.

Diferenças em Relação ao Pix Automático

Característica	Pix Automático	Sweeping Accounts
Relação pagador/recebedor	Pagador → Terceiro	Mesma pessoa (mesmo CPF)
Caso de uso	Cobranças recorrentes	Transferências entre contas próprias
Configuração de limites	Por período	Por período + limite total
Iniciação	ITP / Recebedor	ITP (iniciadora)
API OFB	Automatic Payments v2	Automatic Payments v2 (modalidade sweeping)

Requisitos

Credenciais válidas na plataforma Celcoin (client_id / client_secret)
Conta habilitada para Open Finance como instituição iniciadora
O CPF do loggedUser deve ser o mesmo do creditor (usuário é pagador e recebedor)
A conta destino deve estar registrada e acessível via Open Finance

Pontos de Atenção

⚠️
Identidade do creditor: No Sweeping Accounts, o CPF informado no campo creditors[].cpfCnpj obrigatoriamente deve ser o mesmo do loggedUser.document.identification. Divergências causam rejeição do consentimento.

⚠️
Limites hierárquicos: Os limites de day, week, month e year devem ser coerentes entre si. Um limite diário maior que o semanal, por exemplo, causará erro de validação.

⚠️
totalAllowedAmount: Este campo define o teto total de débito autorizado durante toda a vigência do consentimento. Uma vez atingido, o consentimento é automaticamente expirado.

⚠️
transactionLimit: Define o valor máximo por transação individual. Tentativas de pagamento acima deste valor serão rejeitadas com erro PAGAMENTO_DIVERGENTE_CONSENTIMENTO.

⚠️
Expiração do authorization code: Após a etapa de Approve na detentora, o code retornado no callback tem validade curta. O endpoint de callback deve ser chamado imediatamente para evitar expiração.

⚠️
Sandbox: Em ambiente sandbox (Bricks Demo), é esperado que o endpoint de pagamento retorne 422 PAGAMENTO_DIVERGENTE_CONSENTIMENTO em alguns cenários.

Transferências Inteligentes - Sweeping Accounts

Visão Geral

Como Funciona

1. Criação do Consentimento (Payment Initiation)

2. Execução dos Pagamentos

Diferenças em Relação ao Pix Automático

Requisitos

Pontos de Atenção

Identidade do creditor: No Sweeping Accounts, o CPF informado no campo `creditors[].cpfCnpj` obrigatoriamente deve ser o mesmo do `loggedUser.document.identification`. Divergências causam rejeição do consentimento.

Limites hierárquicos: Os limites de `day`, `week`, `month` e `year` devem ser coerentes entre si. Um limite diário maior que o semanal, por exemplo, causará erro de validação.

`totalAllowedAmount`: Este campo define o teto total de débito autorizado durante toda a vigência do consentimento. Uma vez atingido, o consentimento é automaticamente expirado.

`transactionLimit`: Define o valor máximo por transação individual. Tentativas de pagamento acima deste valor serão rejeitadas com erro `PAGAMENTO_DIVERGENTE_CONSENTIMENTO`.

Expiração do authorization code: Após a etapa de `Approve` na detentora, o `code` retornado no callback tem validade curta. O endpoint de callback deve ser chamado imediatamente para evitar expiração.

Sandbox: Em ambiente sandbox (Bricks Demo), é esperado que o endpoint de pagamento retorne `422 PAGAMENTO_DIVERGENTE_CONSENTIMENTO` em alguns cenários.

Navegação

Visão Geral

Como Funciona

1. Criação do Consentimento (Payment Initiation)

2. Execução dos Pagamentos

Diferenças em Relação ao Pix Automático

Requisitos

Pontos de Atenção

Identidade do creditor: No Sweeping Accounts, o CPF informado no campo creditors[].cpfCnpj obrigatoriamente deve ser o mesmo do loggedUser.document.identification. Divergências causam rejeição do consentimento.

Limites hierárquicos: Os limites de day, week, month e year devem ser coerentes entre si. Um limite diário maior que o semanal, por exemplo, causará erro de validação.

totalAllowedAmount: Este campo define o teto total de débito autorizado durante toda a vigência do consentimento. Uma vez atingido, o consentimento é automaticamente expirado.

transactionLimit: Define o valor máximo por transação individual. Tentativas de pagamento acima deste valor serão rejeitadas com erro PAGAMENTO_DIVERGENTE_CONSENTIMENTO.

Expiração do authorization code: Após a etapa de Approve na detentora, o code retornado no callback tem validade curta. O endpoint de callback deve ser chamado imediatamente para evitar expiração.

Sandbox: Em ambiente sandbox (Bricks Demo), é esperado que o endpoint de pagamento retorne 422 PAGAMENTO_DIVERGENTE_CONSENTIMENTO em alguns cenários.

Navegação

Identidade do creditor: No Sweeping Accounts, o CPF informado no campo `creditors[].cpfCnpj` obrigatoriamente deve ser o mesmo do `loggedUser.document.identification`. Divergências causam rejeição do consentimento.

Limites hierárquicos: Os limites de `day`, `week`, `month` e `year` devem ser coerentes entre si. Um limite diário maior que o semanal, por exemplo, causará erro de validação.

`totalAllowedAmount`: Este campo define o teto total de débito autorizado durante toda a vigência do consentimento. Uma vez atingido, o consentimento é automaticamente expirado.

`transactionLimit`: Define o valor máximo por transação individual. Tentativas de pagamento acima deste valor serão rejeitadas com erro `PAGAMENTO_DIVERGENTE_CONSENTIMENTO`.

Expiração do authorization code: Após a etapa de `Approve` na detentora, o `code` retornado no callback tem validade curta. O endpoint de callback deve ser chamado imediatamente para evitar expiração.

Sandbox: Em ambiente sandbox (Bricks Demo), é esperado que o endpoint de pagamento retorne `422 PAGAMENTO_DIVERGENTE_CONSENTIMENTO` em alguns cenários.