search

bacen / pix-api

API Pix: a API do Arranjo de Pagamentos Instantâneos Brasileiro, Pix, criado pelo Banco Central do Brasil.
https://bacen.github.io/pix-api
2.36k stars 268 forks source link

[Dúvida] nos campos valor, apresentacao e solicitacaoPagador #219

Open jocimarcan opened 3 years ago

jocimarcan commented 3 years ago

Prezados,

Há passagens no manual de experiência que me deixaram em dúvida. Não sei se é porque ele está desatualizado ou se ele deve ser realmente seguido. 1) Pelo que tinha entendido o campo valor não seria editável e não poderia ser fornecido pelo usuário pagador, uma vez que é obrigatório no endpoint da Pix API. No entanto, no manual de experiência 2.1 há a seguinte passagem: O usuário pode ou não editar o valor de um QR code dinâmico?

2) O PSP do usuário pagador deverá fazer alguma verificação sobre a data de apresentação? Há essa passagem no manual de experiência que parece estranha. O campo de calendario.apresentacao precisa ser validado com algum outro? Por qual motivo?

3) No endpoint da Pix API o campo solicitacaoPagador (label a ser exibido) está como opcional, mas não parece haver especificação quanto à obrigatoriedade do preenchimento do input referente a esse label que corresponde ao remittanceInformation. A dúvida é a seguinte: uma vez o campo solicitacaoPagador presente, ou seja, preenchido pelo usuário recebedor, o preenchimento pelo usuário pagador do input correspondente (remittanceinformation) deve ser obrigatório ou opcional?

Grato

luizagsilva commented 3 years ago

Bom dia, sobre o ponto 1 também tinha entendido isso, que no dinâmico não seria possível o pagador alterar o valor, porém pelo que vi em um teste a experiência com o Santander está possibilitando alterar o valor mesmo no QR Code dinâmico e o pagamento foi aprovado normalmente pagando um valor menor do que o original. Lendo o texto do manual de experiência do usuário parece que seria uma definição do lado do recebedor de habilitar isso ou não, porém não existe essa flag na API 2.0 e nem 2.1. Também gostaria de uma confirmação dessa funcionalidade, por favor.

rubenskuhl commented 3 years ago

Bom dia, sobre o ponto 1 também tinha entendido isso, que no dinâmico não seria possível o pagador alterar o valor, porém pelo que vi em um teste a experiência com o Santander está possibilitando alterar o valor mesmo no QR Code dinâmico e o pagamento foi aprovado normalmente pagando um valor menor do que o original. Lendo o texto do manual de experiência do usuário parece que seria uma definição do lado do recebedor de habilitar isso ou não, porém não existe essa flag na API 2.0 e nem 2.1. Também gostaria de uma confirmação dessa funcionalidade, por favor.

Eu acho que o PSP recebedor precisa validar se o valor mudou, e na falta de indicação de se o valor poderia ter mudado, exigir o valor original e recusar o Pix.

renatofrota commented 3 years ago

O campo valor.original acata 0.00 assim como os QR Codes estáticos. Então, no caso do QR Code dinâmico (que representa uma cobrança), a informação que "vem do recebedor" seria a presença de valor 0.00. Não vejo outra hipótese.

Porém, cabe salientar que o Santander não vende Pix, vende um tal de "SX", invenção deles... acho que os PSP recebedores de Pix deveriam rejeitar todos os "pagamentos SX" de uma vez, já que não fala a mesma língua. :yawning_face:

rubenskuhl commented 3 years ago

Bom dia, sobre o ponto 1 também tinha entendido isso, que no dinâmico não seria possível o pagador alterar o valor, porém pelo que vi em um teste a experiência com o Santander está possibilitando alterar o valor mesmo no QR Code dinâmico e o pagamento foi aprovado normalmente pagando um valor menor do que o original. Lendo o texto do manual de experiência do usuário parece que seria uma definição do lado do recebedor de habilitar isso ou não, porém não existe essa flag na API 2.0 e nem 2.1. Também gostaria de uma confirmação dessa funcionalidade, por favor.

O pessoal da Gerencianet fez um teste e o próprio Santander recusou e não encaminhou a transação com valor alterado. Assim, apesar do app erradamente dar a opção de alteração, o próprio PSP já conteve a falha. Eu notei algo parecido no Nubank, quando eu tentei fazer devoluções excedendo o valor original; o app disse na 2a. devolução que eu poderia devolver o valor integral, mas tentando um valor menor mas que excederia o Pix original, o back-end do Nubank recusou.

rubenskuhl commented 3 years ago

De toda forma, atualizações da documentação esclarecendo a experiência do usuário e as regras seriam bem-vindas, @ninrod e @dmkamers . Delimitar se:

renatofrota commented 3 years ago

Se quando a alteração de valor não é permitida, se o app já tem que não dar a opção ou basta o PSP pagador evitar isso de alguma forma

Não faz sentido nenhum permitir editar no app e não poder pagar de fato com o valor editado.

Se o PSP recebedor precisa fazer double-check desse critério ou não

Como você me falou no privado: princípio da robustez. É bom o PSP recebedor validar, apesar de já ser regra. Se houvesse um período de validação do BACEN junto aos PSPs antes de abrir pro público geral, não permitindo PSPs que descumprem as regras entrarem em operação aberta ao pública, isso não seria necessário, mas como não teve...

Se especificar um valor de QR-Code dinâmico como "0.00" é a maneira de permitir receber um QR dinâmico com valor definido pelo pagador ou se isso é exclusivo do QR-Code estático

Se for exclusivo de QR estático, também não deveria constar como valor aceito para o valor.original no payload o valor 0.00. Talvez seja interessante o valor ser definido pelo pagador em situações como doações, recargas de serviços pré-pagos, etc. Não se se alguma não é coberta por QR estáticos com txid de valor 0.00.

luizagsilva commented 3 years ago

@rubenskuhl , nesse teste que vocês fizeram, quem recusou foi o PSP do recebedor, certo? No app do santander para gerar o qr code dinâmico tem a possibilidade de escolher habilitar para o recebedor alterar o valor ou não, mas eu não encontrei essa flag nas api's. Vc encontrou?

jocimarcan commented 3 years ago

@rubenskuhl e @renatofrota eu já havia lido anteriormente algo de que se o valor fosse igual a 0.00 no QR code estático, então o usuário pagador poderia preencher com qualquer valor. Vocês sabem me informar em que parte da documentação/especificação do Bacen estaria essa informação? Porque o exemplo dado no manual de iniciação do Pix quando o valor está ausente, é a ausência do ID BR Code que corresponde ao valor e não o preenchimento com zero. Há uma parte da documentação, mas que se refere a QR code dinâmico, em que é dito que caso o valor do BR Code seja zero, ele deve ser recuperado de outra fonte, especificado como o payloadJSON, o que faz sentido nesse caso. No entanto, não encontrei especificação de que a fonte externa seria o usuário pagador, no caso do QR code estático preenchido com valor=0. Como dito, o exemplo dado no manual também parece refutar isso.

rubenskuhl commented 3 years ago

@rubenskuhl , nesse teste que vocês fizeram, quem recusou foi o PSP do recebedor, certo? No app do santander para gerar o qr code dinâmico tem a possibilidade de escolher habilitar para o recebedor alterar o valor ou não, mas eu não encontrei essa flag nas api's. Vc encontrou?

No teste feito pela Gerencianet (eu não sou de lá), quem recusou foi já o Santander mesmo. Eles verificaram o que você mencionou do app a princípio deixar alterar, mas o próprio back-end do Santander já rejeitou a transação antes de enviar para a Gerencianet, que era o PSP recebedor do teste.

Eu não encontrei flag, mas gosto da idéia do @renatofrota de que se colocar valor "0.00", o dinâmico possa ter escolha de valor, já que um Pix precisa ser de pelo menos 1 centavo.

luizagsilva commented 3 years ago

@rubenskuhl obrigada pela confirmação. O estranho foi que eu consegui pagar normal um valor menor que a cobrança e foi aprovado. Mas vamos esperar uma confirmação oficial então.

rubenskuhl commented 3 years ago

@rubenskuhl obrigada pela confirmação. O estranho foi que eu consegui pagar normal um valor menor que a cobrança e foi aprovado. Mas vamos esperar uma confirmação oficial então.

A Gerencianet quando testou não conseguiu reproduzir o problema em termos de efetivar a transação. Talvez passar para o Santander o E2EID (caso tenha) para eles analisarem ?

renatofrota commented 3 years ago

@rubenskuhl e @renatofrota eu já havia lido anteriormente algo de que se o valor fosse igual a 0.00 no QR code estático, então o usuário pagador poderia preencher com qualquer valor. Vocês sabem me informar em que parte da documentação/especificação do Bacen estaria essa informação? Porque o exemplo dado no manual de iniciação do Pix quando o valor está ausente, é a ausência do ID BR Code que corresponde ao valor e não o preenchimento com zero. Há uma parte da documentação, mas que se refere a QR code dinâmico, em que é dito que caso o valor do BR Code seja zero, ele deve ser recuperado de outra fonte, especificado como o payloadJSON, o que faz sentido nesse caso. No entanto, não encontrei especificação de que a fonte externa seria o usuário pagador, no caso do QR code estático preenchido com valor=0. Como dito, o exemplo dado no manual também parece refutar isso.

Na verdade o documentado para o QR Code estático é que a omissão do campo 54 TransactionAmount (que é opcional) que determinaria que o valor será digitado pelo pagador. Como 0.00 é insuficiente para a efetivação de um Pix, na prática o comportamento tem sido equivalente à omissão do campo em todos os PSPs que testei até o momento.

Não entendi o que você falou a respeito do exemplo dado no manual. Pode ser mais claro a respeito de qual exemplo você está falando (e o que ele refuta)?

jocimarcan commented 3 years ago

@renatofrota é isso mesmo que o exemplo do manual confirma: o campo 54 TransactionAmount deve ser omitido e não preenchido com 0.00 caso se deseja que o usuário pagador preencha esse campo. Não encontrei documentação que permita inferir que um valor preenchido com 0.00 deva ser preenchido pelo usuário pagador.

renatofrota commented 3 years ago

@renatofrota é isso mesmo que o exemplo do manual confirma: o campo 54 TransactionAmount deve ser omitido e não preenchido com 0.00 caso se deseja que o usuário pagador preencha esse campo. Não encontrei documentação que permita inferir que um valor preenchido com 0.00 deva ser preenchido pelo usuário pagador.

Mas a presença de um campo com valor 0.00 no QR Code estático está desencadeando o mesmo processo que a ausência dele, quando da leitura pelo PSP pagador: abre-se o campo para digitação (princípio da robustez: valida-se o que é necessário validar, mas admite-se variações onde for possível para não interromper o processo de pagamento). edit: com ressalvas. Nem todos os bancos procedem assim. Alguns invalidam o QR Code quando lidos com valor 0.00. O que não contraria o manual do Pix (que deixa a existência do campo com 0.00 numa "área cinza") mas acaba contrariando o manual do BRCode (que admite valor 0.00 (ou mesmo 0).

Já no caso de um QR Code dinâmico, o campo valor.original no payload JSON é de presença obrigatória e um dos valores admitidos pelo manual é justamente 0.00, então é a única forma possível para a indicação do "caso permitido pelo recebedor" em que o campo valor pode ser modificado pelo pagador na hora do pagamento.

franciscotfmc commented 3 years ago

Olhando para a especificação da API Pix, não há atributos que indiquem que uma cobrança possa ter o valor definido pelo pagador.

Isso confirma um primeiro entendimento que tivemos antes mesmo da especificação 2.1:

Mas e o caso de uso de doações? Me parece remeter mais ao QR Code Estático do que ao Dinâmico.

Mas e se eu quiser implementar o caso de uso doações com o QR Dinâmico? Ideia: Pedir o valor da doação ao usuário antes de gerar a cobrança.

Apenas tentando contribuir com a minha leitura da situação.

renatofrota commented 3 years ago

Olhando para a especificação da API Pix, não há atributos que indiquem que uma cobrança possa ter o valor definido pelo pagador.

Isso confirma um primeiro entendimento que tivemos antes mesmo da especificação 2.1:

* QR Code Dinâmico: não permitir alteração do valor;

* QR Code Estático:

  * Valor foi definido pelo recebedor?
    **Se sim**, _não permitir alteração do valor;_
    **Se não**, _permitir que o pagador defina o valor;_

Mas e o caso de uso de doações? Me parece remeter mais ao QR Code Estático do que ao Dinâmico.

Mas e se eu quiser implementar o caso de uso doações com o QR Dinâmico? Ideia: Pedir o valor da doação ao usuário antes de gerar a cobrança.

Apenas tentando contribuir com a minha leitura da situação.

Concordo que não faz qualquer sentido a existência de uma cobrança de valor original 0.00. Porém, só estou expondo a minha opinião a respeito da única possibilidade que encontrei para a sinalização, por parte do recebedor, de que um pagador poderia arbitrar o valor do pagamento. Ou seja: a hipótese prevista no manual de UX para abrir o campo de valor para edição por parte do pagador, só se daria no caso da cobrança ter valor final igual a zero. Por nenhum outro meio essa indicação me parece possível.

Ademais, a documentação admite 0.00 para "todos os campos que indicam valores monetários". Talvez coubesse a ressalva que o valor.original e o valor.final devem ser positivos, aí não existiriam cobranças de valor final igual a zero. E, a partir disso, o manual de UX poderia ser atualizado, com a remoção da previsão de que o pagamento por QR Code dinâmico pode ter seu valor alterado por parte do pagador (já que nada mais restaria como indicativo, por parte do recebedor, de que essa possibilidade existe).

franciscotfmc commented 3 years ago

Ademais, a documentação admite 0.00 para "todos os campos que indicam valores monetários". Talvez coubesse a ressalva que o valor.original e o valor.final devem ser positivos, aí não existiriam cobranças de valor final igual a zero. E, a partir disso, o manual de UX poderia ser atualizado, com a remoção da previsão de que o pagamento por QR Code dinâmico pode ter seu valor alterado por parte do pagador (já que nada mais restaria como indicativo, por parte do recebedor, de que essa possibilidade existe)

Concordo 100%.

rubenskuhl commented 3 years ago

Ademais, a documentação admite 0.00 para "todos os campos que indicam valores monetários". Talvez coubesse a ressalva que o valor.original e o valor.final devem ser positivos, aí não existiriam cobranças de valor final igual a zero. E, a partir disso, o manual de UX poderia ser atualizado, com a remoção da previsão de que o pagamento por QR Code dinâmico pode ter seu valor alterado por parte do pagador (já que nada mais restaria como indicativo, por parte do recebedor, de que essa possibilidade existe).

Preciosismo matemático: 0 é um número positivo. Ele não é porém estritamente positivo, então se o objetivo for excluir o valor 0 a restrição precisa ser "ser estritamente positivo".

renatofrota commented 3 years ago

Preciosismo matemático: 0 é um número positivo. Ele não é porém estritamente positivo, então se o objetivo for excluir o valor 0 a restrição precisa ser "ser estritamente positivo".

Eu nem diria que é preciosismo. Em se definindo "serem positivos", o 0 ainda seria válido e não estaria mudando em nada os efeitos da documentação atual, só a sua redação.

Obrigado pela correção. :+1:

ninrod commented 3 years ago

Prezados.

o QR Dinâmico não pode apresentar valor 0.

jocimarcan commented 3 years ago

@ninrod, portanto o usuário pagador não pode editar o valor. Certo? Ainda tenho dúvida no item 2 e item 3

ninrod commented 3 years ago

@ninrod, portanto o usuário pagador não pode editar o valor. Certo?

No dinâmico, não pode. No estático só pode ser o valor estiver ausente.

O PSP do usuário pagador deverá fazer alguma verificação sobre a data de apresentação? Há essa passagem no manual de experiência que parece estranha. O campo de calendario.apresentacao precisa ser validado com algum outro? Por qual motivo?

Aqui o manual só este querendo dizer que se você leu um payload com a DPP do dia X, não deveria ser enviada uma pacs.008 cuja data de pagamento seja diferente de X. Como não há menção ao conceito de DPP, realmente agrega alguma confusão. Será melhorada a redação, possivelmente.

A dúvida é a seguinte: uma vez o campo solicitacaoPagador presente, ou seja, preenchido pelo usuário recebedor, o preenchimento pelo usuário pagador do input correspondente (remittanceinformation) deve ser obrigatório ou opcional?

Boa pergunta. Vou verificar.

jocimarcan commented 3 years ago

Obrigado pelo esclarecimento, @ninrod . Aguardarei o retorno do item 3 para fechar a issue.

ninrod commented 3 years ago

Obrigado pelo esclarecimento, @ninrod . Aguardarei o retorno do item 3 para fechar a issue.

Não está escrito, mas está encaminhando para que o usuário pagador possa escolher deixar em branco porque como a pergunta pode ser "qualquer uma", nada garante que o usuário saiba a resposta, então é complicado exigir que se digite "alguma coisa".