Valor Final x Valor Original

[gpneto]

@ninrod,

criamos o nosso app seguindo o manual do padrão de iniciação 2.0.

Neste manual consta que o valor final é obrigatório no retorno do payload, ou seja, sempre que for lido um QR Code Dinâmico o nosso app vai buscar os dados na URL e utilizará o campo valor final para enviar na ordem de pagamento(se não permite alteração), justamente porque no documento consta "valor.final: [obrigatório] valor obtido depois de aplicados, ao valor original, juros, multa, descontos ou abatimentos.".

Agora estamos construindo nossa API PIX, e o payload que retorna de cobranças criadas pela API PIX não consta o valor final.

Isso nos gerou uma dúvida, porquê nosso app foi construído usando o Manual de Iniciação e todos os payloads de outras instituições que testamos também tem o valor final. O problema é o que fazer quando for lido um QR Code gerado pela API PIX 2.0.0, o app deve ignorar o valor final, mesmo constando como obrigatório no Manual?

Devemos utilizar a lógica de se tiver valor final utilizar o valor final, se não tiver valor final considerar o valor original?

Lembrando que o valor Original também tem uma anotação de rodapé "O campo “valor.original” é opcional para a Secretaria do Tesouro Nacional."

[ninrod]

ninrod,

criamos o nosso app seguindo o manual do padrão de iniciação 2.0.

Neste manual consta que o valor final é obrigatório no retorno do payload, ou seja, sempre que for lido um QR Code Dinâmico o nosso app vai buscar os dados na URL e utilizará o campo valor final para enviar na ordem de pagamento(se não permite alteração), justamente porque no documento consta "valor.final: [obrigatório] valor obtido depois de aplicados, ao valor original, juros, multa, descontos ou abatimentos.".

Agora estamos construindo nossa API PIX, e o payload que retorna de cobranças criadas pela API PIX não consta o valor final.

Isso nos gerou uma dúvida, porquê nosso app foi construído usando o Manual de Iniciação e todos os payloads de outras instituições que testamos também tem o valor final. O problema é o que fazer quando for lido um QR Code gerado pela API PIX 2.0.0, o app deve ignorar o valor final, mesmo constando como obrigatório no Manual?

Devemos utilizar a lógica de se tiver valor final utilizar o valor final, se não tiver valor final considerar o valor original?

Lembrando que o valor Original também tem uma anotação de rodapé "O campo “valor.original” é opcional para a Secretaria do Tesouro Nacional."

bom dia @gpneto,

Ressalto que, na dúvida, a API Pix, este repositório, é a referência mais precisa. Note que a nota de rodapé 36 estabelece que este campo estava em revisão.

Recomendo, para fins de implementação, consultar a API Pix.

No caso específico, o valor.final, para a cobrança imediata, que é a cobrança a que você se refere, não tem valor final, apenas valor.original.

[gpneto]

@ninrod, ainda estou com a dúvida.

Por exemplo olha os payloads que estão sendo construído:

Itau: spi-h.itau.com.br/pix/v1/qr/7f9a8bc5-c0d6-45ac-b574-2cc75bc0a144 { "versao": "1.0.0", "revisao": 0, "calendario": { "criacao": "2020-11-04T16:31:33.39Z", "apresentacao": "2020-11-05T16:17:01.24Z", "recebivelAposVencimento": false }, "valor": { "original": "1.00", "final": "1.00", "permiteAlteracao": false }, "txid": "054892128ae14bc3a994251acd8d442b", "status": "ATIVA", "chave": "34276822858" }

SICOOB: https://pix-h.sicoob.com.br/qr/payload/208bc654-089b-4ec9-8ba9-373c8621f7fa { "revisao": 1, "calendario": { "criacao": "2020-10-30T18:11:08.116Z", "apresentacao": "2020-11-05T19:19:51.617Z", "vencimento": "2020-10-31" }, "valor": { "original": "27.79", "juros": "0.00", "multa": "0.00", "desconto": "0.00", "final": "27.79", "permiteAlteracao": true }, "chave": "83933592011", "txid": "U9N0540379161604070668115", "solicitacaoPagador": "8cU4Y", "infoAdicionais": [ { "nome": "INFO ADD", "valor": "INFO ADD1" } ], "status": "ATIVA", "devedor": { "cpf": "74429669694", "nome": "Elsa Kohler" } }

Banrisul: https://api-h.banrisul.com.br/pix/qrcode/Ne22_Oc9jHhNjKwA3A4qL2kXE2g

{ "revisao": 0, "calendario": { "criacao": "2020-10-30T13:44:00.13Z", "apresentacao": "2020-11-05T19:21:12.96Z", "expiracao": 31536000, "vencimento": "2020-11-30", "recebivelAposVencimento": true }, "devedor": { "cpf": "41872774040", "nome": "José Pagador" }, "valor": { "original": "131.00", "juros": "5.26", "multa": "0.50", "desconto": "1.23", "permiteAlteracao": false, "final": "135.53" }, "chave": "54356835131@banrisul.com.br", "txid": "BRB20201030104400122277150251195656", "solicitacaoPagador": "Por favor, informe o identificador do título: ", "infoAdicionais": [ { "nome": "mensagem1", "valor": "Texto 1 a ser exibido ao usuário, até nn caracteres,não definido ainda." }, { "nome": "mensagem2", "valor": "Texto 2 a ser exibido ao usuário, até nn caracteres,não definido ainda." } ], "status": "CONCLUIDA" }

==================================================================

Todos eles tem o valor Final e o nosso entendimento também é de que o valor final é obrigatório pelo Manual de Iniciação.

Agora pela API PIX o valor Final não existe, então pode ser que tenha Payloads com o valor final e outros sem o valor final e tudo isso já entrando dia 16/11.

Neste caso ainda permaneço com a dúvida acima(qual campo considerar), visto que se o QR Code foi criado a partir de um Mobile(por exemplo) não foi gerado pela API PIX e foi seguido o manual de Iniciação para o retorno do payload, o qual consta o valor final obrigatório.

[ninrod]

spi-h.itau.com.br/pix/v1/qr/7f9a8bc5-c0d6-45ac-b574-2cc75bc0a144

essa url está quase perfeita, mas o v1 está no lugar errado e a 2.0.0 tem um "bug". não é v1 aí , e sim v2.

spi-h.itau.com.br/pix/qr/v2/7f9a8bc5-c0d6-45ac-b574-2cc75bc0a144

seria a url correta.

outra melhoria que eu implementaria é remover os caracteres - que não agregam segurança e nem funcionalidade e apenas ocupa espaço.

[gpneto]

No Manual de Iniciação não consta que tem que ser a versão 2: "fqdnPspRecebedor/pixEndpoint/pixUrlAccessToken/".

Na API Pix versão 2.0.0 'Recuperar o payload JSON que representa a cobrança." consta "https://{fdqnPSPRecebedor}/{pixEndpoint}/v1/{pixUrlAcessToken}"

Neste caso entendo que tanto o manual de Iniciação quando a API Pix 2.0.0 para a 'Recuperar o payload JSON que representa a cobrança." estão no v1, ou um deles está errado?

Como você mencionou que a API Pix 2.0.0 está errado, agora faz sentido. Os QR Codes v1 eu considero o valor final e os v2 o valor original, é isso?

[ninrod]

No Manual de Iniciação não consta que tem que ser a versão 2: "fqdnPspRecebedor/pixEndpoint/pixUrlAccessToken/".

Não consta, mas deveria estar constando. Consideramos como um bug.

tem que estar no v2.

[ninrod]

porque a api está na 2.x.x

[gpneto]

@ninrod, me desculpa ser redundante.

O cenário que temos hoje na nossa Instituição é a geração do QR Code Dinâmico pelo aplicativo. Neste caso o payload do QR Code Dinâmico cadastrado pelo app, nós seguimos o Manual de Iniciação 2.0, quando for realizado a chamada da URL deste QR Code Dinâmico o payload retornará os valores de juros, multa, desconto e o valor original. Isso porque adicionamos em tela para o usuário informar estes campos quando está criando o QR Code Dinâmico.

O nosso QR Code Dinâmico gerado pelo app está seguindo o Manual de Iniciação e não a API PIX.

A minha dúvida é, o nosso QR Code Dinâmico gerado pelo Mobile que tem os valores de juros, multa e o valor Final é da V1 ou V2?

Os aplicativos tem que ser capazes de interpretar os Payloads que foram gerados a partir do Manual de Iniciação e também a partir da API PIX, visto que os dois possum campos diferentes referentes aos valores?

[ninrod]

@gpneto

O manual de iniciação está sofrendo um processo de alteração em que estamos movendo as questões estritamente técnicas relativas à API Pix para o repositório oficial do BCB no Github: https://github.com/bacen/pix-api (este repositório). Ressalto que o repositório no github para a API é relativamente novo em relação ao manual. Entendemos que você pode ter tido contratempos devido a esta migração.

Além disso, destacamos as seguintes observações contidas no manual de iniciação 2.0:

“A versão vigente da API Pix contempla a especificação das funcionalidades e campos relativos aos casos de negócio focados em pagamentos imediatos, a exemplo de pontos de venda em lojas físicas e de soluções para comércio eletrônico. Os demais campos serão especificados na próxima versão da API Pix, e contemplarão os casos de negócio de cobrança com vencimento.”

“Os campos 2.4, 2.5, 4.2, 4.3, 4.4, 4.5 e 4.6 estão em discussão no âmbito da construção das funcionalidades da API Pix relacionadas aos casos de uso envolvendo cobrança com vencimento e poderão sofrer ajustes”.

Nesse sentido, recomendo aguardar a API Pix versão 2.1.0 para endereçar questões relativas a vencimento.

Ainda destaco que a versão oficial do API Pix é a versão 2.0.0 e é ela que contem a versão oficial do payload que será retornado pelo PSP recebedor.

Verificar aqui

O payload está definido aqui no arquivo OpenAPI 3.0 (yaml):

Em tempo, no payload, na 2.0.0, só existe valor.original.

[christianf2029]

Em tempo, no payload, na 2.0.0, só existe valor.original.

Ufa @ninrod , ainda bem que você esclareceu isso.

[cryptographix]

No Manual de Iniciação não consta que tem que ser a versão 2: "fqdnPspRecebedor/pixEndpoint/pixUrlAccessToken/".

Não consta, mas deveria estar constando. Consideramos como um bug.

tem que estar no v2.

@ninrod .. há algum requisito ou recomendação de que o pagador DEVE olhar e validar a versão presente no URL?

Pergunto isso porque estamos a uma semana do go-live e vejo que vários PSPs ainda não estão com esse 'v2'. Por favor, esclareça e oriente o que um PSP pagador DEVE fazer se receber um url cm /v1/ ou mesmo sem versão?

[ninrod]

Pergunto isso porque estamos a uma semana do go-live e vejo que vários PSPs ainda não estão com esse 'v2'. Por favor, esclareça e oriente o que um PSP pagador DEVE fazer se receber um url cm /v1/ ou mesmo sem versão?

Deve. O fato de estar na 2.0.0 como v1 era um bug. Não que haverá um problema de compatibilidade imediato, mas é importante os PSPs observarem esse aspecto para estarmos alinhados com o major version.

[cryptographix]

Pergunto isso porque estamos a uma semana do go-live e vejo que vários PSPs ainda não estão com esse 'v2'. Por favor, esclareça e oriente o que um PSP pagador DEVE fazer se receber um url cm /v1/ ou mesmo sem versão?

Deve. O fato de estar na 2.0.0 como v1 era um bug. Não que haverá um problema de compatibilidade imediato, mas é importante os PSPs observarem esse aspecto para estarmos alinhados com o major version.

Obrigado @ninrod.

"Deve" neste sentido significa que o PSP pagador DEVE desprezar um URL que não contém o v2? Qual a semântica que o BACEN entende ser a mais correta neste momento?

Caso concreto - hoje tem PSPs gerando com v1 e outros sem versão explícita no URL. Vocês prevêem problemas de interoperação das "cobranças imediatas" por causa disso? Os PSPs devem mudar para incluir /v2/ antes do dia 16/11?

[ninrod]

"Deve" neste sentido significa que o PSP pagador DEVE desprezar um URL que não contém o v2? Qual a semântica que o BACEN entende ser a mais correta neste momento?

boa pergunta, como estamos perto do go live, acredito ser prudente não desprezar as URLs que não apresentem o v2 neste momento, mas sim a partir de 04.01.2021, que é quando será obrigatório para os PSPs estarem aptos a lerem o a cobrança com vencimento.

Por outro lado, não imagino maiores dificuldades para que os PSPs recebedores adequem suas implementações considerando este detalhe.

[cryptographix]

Por outro lado, não imagino maiores dificuldades para que os PSPs recebedores adequem suas implementações considerando este detalhe.

Se não fosse o deadline do dia 16, não seria problema nenhum. Agora, reconfigurar gerenciador de API e as rotas fixas em aplicações, implantar em -h, homologar e ainda colocar em produção não acontece de uma hora para outra, mais ainda em bancos que seguem a política de "freezing".

Como sabemos, mudanças da última hora são sempre potenciais causas de falhas e devem ser evitadas .. até estranhei a publicação do 2.1 tão próxima do dia 16 ... em função do risco de criar confusão ... talvez compensava esperar mais 7 dias ... mas enfim .. vamos que vamos.

Valeu o retorno e um abraço.