Pix Automático e Sweeping Accounts

Pagamentos automáticos e Sweeping Accounts (Assim como o VRP) vão utilizar o mesmo endpoint de criação de consentimentos de longa duração, o POST /recurring-consents;

O payload de criação do consentimento contém o objeto "recurringConfiguration", o qual atende ao conceito de oneOf, onde cada uma das possibilidades de preenchimento representam um produto e cada um dos produtos estarão associados a um único consentimento de longa duração;

Agora, pensando em casos de uso e em como utilizar o endpoint de criação de consentimentos de longa duração, vamos considerar dois casos de uso. O primeiro, para exemplificar o Pagamento Automático, é a adesão de um usuário a um serviço de assinatura de streaming qualquer. Já o segundo caso de uso que abordaremos aqui, para exemplificar o Sweeping Accounts, será o investimento inteligente, entraremos nos detalhes de cada um a seguir.

Produtos dessa natureza comumente exigem um pagamento imediato para permitir o consumo do serviço pelo usuário Pagador imediatamente, caso o pagamento imediato seja necessário, o payload precisará ser preenchido de acordo, como veremos mais a frente. Abaixo, vamos descriminar algumas definições necessárias para o entendimento do preenchimento do payload.

• O valor base da assinatura será R$50,00.

  • Esse valor não é enviado na criação do consentimento de longa duração.

  • O campo “/data/recurringConfiguration/automatic/amount" representa que é um valor fixo de cobrança mensal.

  • O campo “/data/recurringConfiguration/automatic/transactionLimit" representa que é um valor de cobrança mensal com um limite máximo por cobrança definido pelo usuário.

• O cliente pode comprar produtos dentro da plataforma que aumentem o valor da cobrança, assim como mudar seu plano para valores maiores ou menores e continuar com seu consentimento válido;

• Há um pagamento imediato também no valor de R$ 50,00;

• O usuário determinou que o consentimento irá durar um ano, a partir da data de criação, aqui definida como por exemplo 22/09/2023;

• No payload abaixo, iremos exemplificar como ficaria a solicitação de criação de consentimento de longa duração que respeite esses critérios:

  • {
        "data": {
            "loggedUser": {
                "document": {
                    "identification": "11111111111",
                    "rel": "CPF"
                }
            },
            "businessEntity": {
                "document": {
                    "identification": "41331654000185",
                    "rel": "CNPJ"
                }
            },
            "creditors": [
                {
                    "personType": "PESSOA_JURIDICA",
                    "cpfCnpj": "20162457000100",
                    "name": "VideoFlix"
                }
            ],
            "startDateTime": "2023-09-22T08:30:00Z",
            "expirationDateTime": "2024-09-21T08:30:00Z",
            "additionalInformation": "Minha recorrência",
            "debtorAccount": {
                "ispb": "87654321",
                "issuer": "2885",
                "number": "56789012341",
                "accountType": "CACC"
            },
            "recurringConfiguration": {
                "automatic": {
                    "contractId": "YZXYZ000323002893",
                    "transactionLimit": "100.00",
                    "period": "MENSAL",
                    "dayOfMonth": 22,
                    "contractDebtor": {
                        "name": "Policarpo Quaresma",
                        "document": {
                            "identification": "41331654000185",
                            "rel": "CNPJ"
                        }
                    },
                    "immediatePayment": {
                        "type": "PIX",
                        "date": "2023-09-22",
                        "currency": "BRL",
                        "amount": "50.00",
                        "creditorAccount": {
                            "ispb": "12345678",
                            "issuer": "1774",
                            "number": "1234567890",
                            "accountType": "CACC"
                        }
                    }
                }
            }
        }
    }

Como no caso de uso anterior, precisamos definir algumas regras para entendermos a aplicação;

• O investimento ocorrerá semanalmente, todas as quinta-feiras, a partir do dia 22/09/2023;

• O valor de investimento fixo foi definido como R$150,00, observem no payload abaixo que este valor não aparece em canto nenhum, isto se dá devido ao fato do campo “/data/recurringConfiguration/sweeping/amount" ser o valor máximo total permitido para ser transacionado via este consentimento, enquanto o campo "/data/recurringConfiguration/sweeping/transactionLimit" representa o limite máximo por transação, independente de qualquer limite periódico, sendo os outros campos de "transactionLimit", pertencentes ao objeto "periodicLimits", abaixo do "/data/recurringConfiguration/sweeping/transactionLimit" em ordem de validação.

• Podem ocorrer ofertas de investimentos que aumentem o valor investido durante o mês, por isso o usuário definiu um limite de R$1000,00;

• Para facilitar a gestão de quantos investimentos ele tem, o usuário decidiu que, por mês, ele vai fazer no máximo dez investimentos;

• O usuário também definiu que esse investimento em um ano, valor total investido por ele chegue até a R$5000,00.

• A duração do consentimento, ou seja, sua data de expiração (que também foi definida pelo usuário) é de um ano.

  • {
        "data": {
            "loggedUser": {
                "document": {
                    "identification": "20162457000",
                    "rel": "CPF"
                }
            },
            "creditors": [
                {
                    "personType": "PESSOA_FISICA",
                    "cpfCnpj": "20162457000",
                    "name": "Benjamin Constant"
                }
            ],
            "startDateTime": "2023-09-22",
            "expirationDateTime": "2024-09-21",
            "additionalInformation": "Minha recorrência",
            "debtorAccount": {
                "ispb": "12345678",
                "issuer": "1774",
                "number": "1234567890",
                "accountType": "CACC"
            },
            "recurringConfiguration": {
                "sweeping": {
                    "periodicLimits": {
                        "day":{
                            "quantityLimit": 2,
                            "transactionLimit": "500.00"
                        },
                        "month":{
                            "quantityLimit": 10,
                            "transactionLimit": "1000.00"
                        },
                        "year": {
                            "transactionLimit": "5000.00"
                        }
                    }
                }
            }
        }
    }

     

A partir do sucesso da chamada deste passo, iniciam-se as validações assíncronas do consentimento.

Detentor precisa realizar as validações assíncronas levando em consideração os momentos descritos no quadro abaixo.

A instituição Detentora precisa estar atenta durante o processamento da solicitação de consentimento referente a presença do objeto “/data/recurringConfiguration/automatic/immediatePayment”. Caso esse campo esteja preenchido, o detentor deverá, em momento posterior a criação do consentimento permitir uma solicitação de pagamento imediata que siga os parâmetros definidos dentro do objeto.

Serviços dessa natureza, geralmente exigem esse pagamento para que a assinatura seja válida. Para não gerar inconsistência entre consentimentos de longa duração aprovados e quais realmente estarão em uso, caso um consentimento de longa duração possua, na sua criação, uma declaração de pagamento imediato e o cliente não possuir saldo ou limite no momento da adesão, o PSP do pagador deve rejeitar assincronamente o consentimento e utilizar o “rejection/reason/code" cabível:

• Caso o cliente tenha limite habilitado na conta selecionada mas o valor cobrado seja superior ao limite disponível, preencher o “rejection/reason/code" com VALOR_ACIMA_LIMITE;

• Caso o cliente não tenha limite e o saldo disponível em conta não é suficiente, preencher o “rejection/reason/code" com o valor SALDO_INSUFICIENTE.

Na situação onde o iniciador possui o mecanismo de Webhook, não há necessidade de realizar as consultas (GET /recurring-consents/{recurringConsentId}) durante esse passo, basta aguardar a notificação de alteração de status que virá do detentor e realizar uma única consulta já com a informação atualizada. Caso não possua Webhook, pode realizar o polling normalmente.

O atingimento de limites periódicos não move o consentimento para o status “CONSUMED”, apenas impede que outra transação ocorra dentro do período estipulado no preenchimento dos campos. Os casos que movem o consentimento para “CONSUMED” são:

• Ele ter chego na sua data de expiração;

• Atingir o valor definido no campo “/data/recurringConfiguration/sweeping/amount";

Para minimizar os riscos para usuário, ao utilizar o produto “Sweeping Accounts” é imprescindível que o usuário defina ao menos um dos limites, seja limite global de valor total (“/data/recurringConfiguration/sweeping/amount"), limite de valor máximo por transação ("/data/recurringConfiguration/sweeping/transactionLimit") ou periódico ("/data/recurringConfiguration/sweeping/periodicLimits"). A necessidade se justifica pelo falo do “Sweeping Accounts” caracterizar uma transferência instantânea de fundos, o que pode acarretar em diversos problemas de segurança e alguns desses podem ser mitigados por essa ação.

Sobre o access_token que será utilizado na iniciação de pagamentos para o Pix Automático. Temos basicamente dois cenários possíveis:

• Primeiro caso: Considerado o mais simples, onde o iniciador possui um authorization_code ainda válido, recebido durante o processo de adesão, o qual poderá utilizar para trocar por um access_token e realizar a transação.

• Segundo caso: O iniciador está agendando uma transação quando o access_token da adesão não é mais válido. Nesse cenário, o iniciador deve antes de criar uma solicitação de pagamento, realizar uma solicitação de refresh_token ao PSP do pagador. Informações sobre o mecanismo de refresh_token podem ser encontrados em [PT] Open Finance Brasil Financial-grade API Security Profile 1.0 Implementers Draft 3 - 7.1. Mecanismo de Autorização.

Considerando o primeiro caso de uso, “Pagamento mensal de streaming via API de Pagamento automático onde o usuário aplica valor máximo de R$100,00 para o consentimento”:

• Uma vez que há a presença do pagamento imediato, o iniciador pode gerar imediatamente uma cobrança na conta do usuário no PSP Pagador.

• Após 30 dias da adesão, ocorre novamente uma cobrança. A data dessa cobrança precisa ser agendada seguindo a regra do arranjo do Pix Automático, ou seja, 2 a 10 dias antes da sua data de liquidação o recebedor deve enviar a cobrança ao Iniciador, que por sua vez encaminha ao PSP do pagador. Além disso, temos mais algumas regras que são necessárias, sendo elas:

  • A geração do endToEndId deve seguir a data de cadastro do usuário no PSP pagador. O campo “/data/ibgeTownCode “ será retornado obrigatoriamente na consulta do consentimento de longa duração(GET /recurring-consents/{recurringConsentId}) quando o consentimento estiver com status "AUTHORISED".

  • Para o Pix automático, pagamentos podem ocorrer apenas em dias úteis. Caso a data de liquidação caia em um dia que não seja considerado dia útil, o pagamento deve ser agendado para ocorrer no dia útil mais próximo, assim como o endToEndId também precisa ser ajustado para esse dia.

  • Pagamentos imediatos declarados na criação do consentimento de longa duração podem ocorrer via canal primário e em qualquer horário.

• Uma vez que o recebedor exigiu uma cobrança imediata e o usuário autorizou essa cobrança, o iniciador precisa enviar o payload de pagamento:

  • {
        "data": {
            "endToEndId": "E9040088820210128000800123873170",
            "date": "2023-09-22",
            "payment": {
                "amount": "50.00",
                "currency": "BRL"
            },
            "creditorAccount": {
                "ispb": "12345678",
                "issuer": "1774",
                "number": "1234567890",
                "accountType": "CACC"
            },
            "remittanceInformation": "Pagamento da nota XPTO035-002.",
            "cnpjInitiator": "50685362000135",
            "ibgeTownCode": "5300108",
            "authorisationFlow": "HYBRID_FLOW"
        }
    }

• As cobranças subsequentes, como já mencionado, devem ocorrer entre 2 a 10 dias antes da data de liquidação.

• Caso exista a necessidade de enviar a solicitação de cobrança imediata e uma solicitação de cobrança agendada, para o mesmo consentimento de longa duração, devem ser feitas duas chamadas a API de pagamentos automáticos, no endpoint POST /pix/recurring-payments, a primeira para o pagamento imediato, seguida de uma segunda requisição responsável por realizar o agendamento da cobrança na data especificada e seguindo todas as regras já mencionadas até aqui.

Nesta etapa, o PSP do pagador precisa validar as informações recebidas do iniciador e verificar se elas estão condizentes com as regras definidas na criação do consentimento de longa duração, alguns pontos a serem observados são:

• Valor da cobrança x Limite transacional: Caso o usuário tenha definido um limite transacional no iniciador no momento de adesão e a solicitação de cobrança ultrapasse esse limite, o detentor deve retornar o erro VALOR_ACIMA_LIMITE;

• Se a data enviada para liquidação condiz com as configurações de período aceitas pelo usuário pagador no momento da autorização;

• Além de todos os erros síncronos e assíncronos que podem ocorrer durante as validações e listados na especificação da API.

Quando, na criação do consentimento de longa duração, for declarada a necessidade de um pagamento imediato associado a este consentimento(objeto “/data/recurringConfiguration/automatic/immediatePayment" preenchido), é necessário que o detentor aceite uma requisição de pagamento com liquidação imediata. Pensando em casos de uso de serviços de streaming, seria a cobrança inicial para permissão de utilização do serviço até o próximo ciclo de fechamento.

Caso o serviço não possua uma cobrança imediata, caberá ao PSP do pagador validar se o agendamento segue as regras do arranjo Pix Automático, além das outras validações necessárias descritas no header da API de pagamentos automáticos.

O iniciador, com posse do recurringPaymentId, precisa consultar o PSP do pagador, via polling e no endpoint GET /pix/recurring-payments/{recurringPaymentId}, o status da sua solicitação. Caso seja um pagamento imediato necessário à consolidação de um contrato, deve realizar a consulta até o atingimento do status final da liquidação, ACSC, confirmando assim a finalização da transação.

Para pagamentos automáticos agendados, deve-se consultar até que o mesmo possua o status SCHD.

Caso ocorra algum erro dentro do PSP Pagador durante o processamento da liquidação, também pode ser recuperado via chamada ao endpoint supracitado.

Caso o iniciador queria consultar todos os pagamentos associados a um consentimento de longa duração específico, pode fazer via endpoint GET /pix/recurring-payments, onde precisa passar um parâmetro do tipo query, o recurringConsentId, além de poder especificar períodos específicos de cobranças através dos campos startDate e endDate, também passados como parâmetros do tipo query.

Caso o Iniciador possua implementado o mecanismo de Webhook, não há necessidade de realizar consultas periódicas no PSP do pagador (polling) para verificar o status do pagamento, basta aguardar a notificação via Webhook e realizar a consulta para verificar as alterações.

As contas habilitadas são aquelas as quais o usuário possui um consentimento de longa duração válido entre o PSP Pagador e o Iniciador e que tenham sido liberadas para esta funcionalidade pelo usuário contratante do serviço.

Usuário pagador ou usuário contratante, representam a mesma figura.

As regras aqui mencionadas nada mais são que os parâmetros definidos no corpo da mensagem de criação do consentimento de longa duração, caso necessário o Iniciador pode consultar essas regras/parâmetros realizando GET /recurring-consents/{recurringConsentId} no PSP do Pagador.

Para o caso de uso que vamos trabalhar como exemplo, também criamos essas regras, elas podem ser conferidas expandindo o tópico 12 - "Cria o consentimento (POST /recurring-consents)" item 3, presente na etapa de adesão.

Sobre o access_token que será utilizado na iniciação de pagamentos para o Pix Automático. Temos basicamente dois cenários possíveis:

• Primeiro caso: Considerado o mais simples, onde o iniciador possui um authorization_code ainda válido, recebido durante o processo de adesão, o qual poderá utilizar para trocar por um access_token e realizar a transação.

• Segundo caso: O iniciador está agendando uma transação quando o access_token da adesão não é mais válido. Nesse cenário, o iniciador deve antes de criar uma solicitação de pagamento, realizar uma solicitação de refresh_token ao PSP do pagador. Informações sobre o mecanismo de refresh_token podem ser encontrados em [PT] Open Finance Brasil Financial-grade API Security Profile 1.0 Implementers Draft 3 - 7.1. Mecanismo de Autorização.

Sinais de risco:

• Por se tratar de uma transferência automática entre instituições, por mais que exista a checagem de titularidade, entende-se que mais algumas informações podem ser necessárias para autorizar ou não a iniciação de pagamentos automáticos. A API de pagamentos automáticos, como o próprio nome deixa claro, poderá comandar solicitações de pagamento e transferências entre instituições de maneira automática, ou seja, pode ou não estar na presença do usuário. A API de pagamentos automáticos hoje possui, devido a necessidade do arranjo Pix, o mecanismo de temporização no qual as instituições utilizam para poder realizar algumas validações de antifraude, podendo o PSP do pagador aprovar ou negar a solicitação de pagamento advinda do iniciador.

• Para minimizar os riscos, foi colocado dentro do POST /pix/recurring-payments um objeto para receber informações sobre o usuário, seu dispositivo e sua conexão, aqui chamados de Sinais de risco.

• O objeto que contem os sinais de risco é o “/data/riskSignals", sendo os sinais de risco divididos em duas categorias, uma representa o usuário online no ambiente do iniciador (o que será indicado pela preenchimento do objeto "/data/riskSignals/manual" e seus campos) ou sem a presença do usuário no ambiente do iniciador (indicado pelo preenchimento do objeto "/data/riskSignals/automatic" e seus campos).

Transferências automáticas entre contas de mesma titularidade podem ocorrer todos os dias da semana, em qualquer horário, devem ser liquidadas via canal primário e seguir as regras do arranjo.

Para o caso de uso que estamos tratando aqui, na primeira quinta-feira após o dia 22/09/2023, o iniciador deverá enviar uma requisição de pagamento automático (POST /pix/recurring-payments), contendo a primeira solicitação de transferência, assim como definido pelo usuário e sem a presença dele:

• {
      "data": {
          "endToEndId": "E9040088820210128000800123873170",
          "date": "2023-09-28",
          "payment": {
              "amount": "150.00",
              "currency": "BRL"
          },
          "creditorAccount": {
              "ispb": "12345678",
              "issuer": "1774",
              "number": "1234567890",
              "accountType": "CACC"
          },
          "remittanceInformation": "Pagamento da nota XPTO035-002.",
          "cnpjInitiator": "50685362000135",
          "ibgeTownCode": "5300108",
          "authorisationFlow": "HYBRID_FLOW",
          "riskSignals": {
            "automatic": {
              "lastLoginDateTime": "2023-10-09T08:15:00Z",
              "pixKeyRegistrationDateTime": "2023-10-09T08:20:00Z
            }
          }
      }
  }

   

Agora, vamos fazer uma conta simples, se o usuário autorizou R$ 150,00 por semana, em 4 semanas são R$ 600,00. Após 33 semanas apenas de movimentações planejadas, sem nenhum investimento inteligente, teremos então um total de R$ 4.950,00 investidos, muito próximo do valor total especificado pelo usuário no momento de consentimento, que é de R$ 5.000,00 por ano. Sendo assim, o PSP Pagador (Detentor), na 34ª solicitação irá retornar um erro para o iniciador, informando que o limite definido pelo usuário foi atingindo.

Um outro limite possível de ser atingido é o limite de quantidades de transações, que por sua vez também é definido pelo usuário. No nosso exemplo, quando criamos o consentimento, definimos o limite de quantidade de investimentos por dia em 2, ou seja, a partir da terceira tentativa de investimento no mesmo dia, que esteja dentro do valor total permitido também por dia (R$ 500,00), um erro também será retornado.

Abaixo temos dois possíveis erros relacionados aos limites acima citados, são eles:

• LIMITE_PERIODO_VALOR_EXCEDIDO: É o erro aplicável no primeiro exemplo citado. Uma vez que a transação seria negada porque o limite que foi atingido foi o limite anual de valor definido pelo usuário (campo “/data/recurringConfiguration/sweeping/periodicLimits/year/amount" preenchido na criação do consentimento), impossibilitando novas transações. Importante salientar que, caso o Iniciador, ao invés de tentar fazer o valor de investimento com o valor predefinido pelo usuário fosse fazer um investimento inteligente, também consentido pelo usuário, no valor de R$ 50,00, seria aceito normalmente, pois não passaria o valor máximo definido para o período (1 ano).

• LIMITE_PERIODO_QUANTIDADE_EXCEDIDO: É o erro aplicável ao segundo exemplo. A transação seria negada não por ter atingindo uma quantidade pré definida de valores, mais sim uma quantidade pre definida de investimentos realizados em um determinado periodo definido pelo usuário (campo “/data/recurringConfiguration/sweeping/periodicLimits/day/quantityLimit" preenchido na criação do consentimento). Se o Iniciador tentar novamente no próximo dia e caso essa seja a única regra que estava impedindo-o de realizar a transferência, a transferência poderá ser realizada.

Nesta etapa, o PSP do pagador precisa validar as informações recebidas do iniciador e verificar se elas estão condizentes com as regras definidas na criação do consentimento de longa duração, alguns pontos a serem observados são:

• Valor da transferência x Limite transacional: Caso o usuário tenha definido um limite transacional no iniciador no momento de adesão e a solicitação de transferência ultrapasse esse limite, o detentor deve retornar o erro VALOR_ACIMA_LIMITE;

• Se a data enviada para liquidação condiz com as configurações de período aceitas pelo usuário pagador no momento da autorização do consentimento;

• Além de todos os erros síncronos e assíncronos que podem ocorrer durante as validações e listados na especificação da API.

O iniciador, com posse do recurringPaymentId, precisa consultar o PSP do pagador, via polling e no endpoint GET /pix/recurring-payments/{recurringPaymentId}, o status da sua solicitação. Deve realizar a consulta até o atingimento do status final da liquidação, ACSC (caso tenha sido completada com sucesso) ou RJCT (caso tenha ocorrido algum problema na liquidação), confirmando assim a finalização da transação.

Caso ocorra algum erro dentro do PSP Pagador durante o processamento da liquidação, também pode ser recuperado via chamada ao endpoint citado acima, observando os motivos de rejeição.

Caso o iniciador queria consultar todos os pagamentos associados a um consentimento de longa duração específico, pode fazer via endpoint GET /pix/recurring-payments, onde precisa passar um parâmetro do tipo query, o recurringConsentId, além de poder especificar períodos específicos de cobranças através dos campos startDate e endDate, também passados como parâmetros do tipo query.

Caso o Iniciador possua implementado o mecanismo de Webhook, não há necessidade de realizar consultas periódicas no PSP do pagador (polling) para verificar o status do pagamento, basta aguardar a notificação via Webhook e realizar a consulta para verificar as alterações.