descrição | API de Iniciação de Pagamentos, responsável por viabilizar as operações de iniciação de pagamentos para o Open Finance Brasil.
Para cada uma das formas de pagamento previstas é necessário obter prévio consentimento do cliente através dos `endpoints` dedicados ao consentimento nesta API. # Orientações
No diretório de participantes duas `Roles` estão relacionadas à presente API: `CONTA`, referente às instituições detentoras de conta participantes do Open Finance Brasil; `PAGTO`, referente às instituições iniciadoras de pagamento participantes do Open Finance Brasil.
Os tokens utilizados para consumo nos endpoints de consentimentos devem possuir o scope `payments` e os `endpoints` de pagamentos devem possuir os `scopes`, `openid` e `payments`.
Esta API não requer a implementação de `permissions` para sua utilização. Todas as requisições e respostas devem ser assinadas seguindo o protocolo estabelecido na sessão <a href="https://openbanking-brasil.github.io/areadesenvolvedor/#assinaturas" target="_blank">Assinaturas</a> do guia de segurança.
## Regras do arranjo Pix
A implementação e o uso da API de Pagamentos Pix devem seguir as regras do arranjo Pix do Banco Central, que podem ser encontradas no link abaixo:
[https://www.bcb.gov.br/estabilidadefinanceira/pix?modalAberto=regulamentacao_pix](https://www.bcb.gov.br/estabilidadefinanceira/pix?modalAberto=regulamentacao_pix) ## Assinatura de payloads No contexto da API Payment Initiation, os `payloads` de mensagem que trafegam tanto por parte da instituição iniciadora de transação de pagamento quanto por parte da instituição detentora
de conta devem estar assinados. Para o processo de assinatura destes `payloads` as instituições devem seguir as especificações de segurança publicadas no Portal do desenvolvedor:
[[EN] Padrão de Certificados Open Finance Brasil 2.1](https://openfinancebrasil.atlassian.net/wiki/spaces/OF/pages/82084176/EN+Padr+o+de+Certificados+Open+Finance+Brasil+2.1%20%E2%80%8B)
## Controle de acesso Os endpoints de consulta e cancelamento devem suportar somente acesso a partir de access_token emitido por meio de um grant_type do tipo client_credentials. Para a criação do consentimento deve-se utilizar client_credentials e para criação de pagamentos deve-se utilizar authorization_code. ## Aprovações de múltipla alçada
Já para o caso de pagamento agendado, todas as aprovações devem ser realizadas até o exato dia anterior à data/hora prevista para primeira liquidação, respeitando a data/hora limite suportada pela detentora.
Caso não seja possível aprovação, o consentimento deve ser rejeitado pelo detentor.
## Validações para pagamentos recorrentes
o iniciador deve enviar a ordem de pagamento para liquidação com o endToEndId representando o dia seguinte à data prevista para a liquidação.
Se identificado pelo detentor que a data enviada no endToEndId corresponde a um dia inexistente, ele deve rejeitar o pagamento com erro 422,
com código PARAMETRO_INVALIDO e detalhe “Data de liquidação inválida”
assincronamente, é de responsabilidade do detentor realizar a transição para o status SCHD de todos os itens enviados na
lista de pagamentos em até 60 minutos (contados a partir da resposta de sucesso da solicitação).
Caso não seja possível realizar a transição de todos os pagamentos para SCHD, o detentor deverá mover todos os pagamentos
enviados pelo iniciador naquela mesma requisição para RJCT e preencher o motivo de rejeição correspondente,
FALHA_AGENDAMENTO_PAGAMENTOS. O consentimento irá para CONSUMED.
## Validações
**Validações** (*após o processo de DCR e obtenção de token client credential*– não escopo dessa documentação)
Durante a jornada de iniciação de pagamento, diferentes validações são necessárias pela instituição detentora
de conta e devem ocorrer conforme a seguir: Na criação do consentimento (*POST /consents*); Na criação do pagamento - Síncrono (*POST /payments*); Validações na consulta do pagamento (*GET /pix/payments/{paymentId}*); Demais validações executadas durante o processamento assíncrono do pagamento pela detentora, poderão ser consultados pela iniciadora através do endpoint (*GET /pix/payments/{paymentId}*) previstos com retorno HTTP Code 200 - OK com status RJCT (Rejected) e rejectionReason; Demais validações executadas durante o processamento assíncrono do consentimento pela detentora poderão ser consultados pela iniciadora através do endpoint (*GET /consents/{consentId}*) previstos com retorno HTTP Code 200 – OK com status REJECTED e rejectionReason
**Os tipos de validações dispostas abaixo não determinam a ordem em que as instituições devem implementá-las** **Validações na criação do consentimento (_POST /consents_)**
1.1 **Orientações Iniciais**
 1.1.1 Não devem ser retornadas na resposta deste endpointinformações associadas ao usuário/cliente (ex. insuficiência de saldo, conta inexistente/bloqueada).
 1.1.2 Não devem ser executadas validações no DICT (Diretório de Identificadores de Contas Transacionais do Pix), a partir dos dados compartilhados nesse *endpoint*. Tais validações podem ocorrer somente na criação do pagamento;
 1.1.3 Não devem ser realizadas validações de informações sobre o usuário/cliente durante a criação do consentimento.
1.2 **Casos de erro relacionados às permissões de segurança para acesso à API (ex. certificado, access_token, jwt, assinatura)**
 1.2.1 Validação de Certificado: Valida utilização de certificado correto durante processo de DCR - HTTP Code 401 (INVALID_CLIENT);
 1.2.2 Validação de Access_Token: Verifica se Access_Token utilizado está correto - HTTP Code 401 (UNAUTHORIZED);
 1.2.3 Validação de assinatura da mensagem: Valida se assinatura das mensagens enviadas está correta – HTTP Code 400 (BAD_SIGNATURE);
 1.2.4 Validação de Claims (exceto data);
 1.2.4.1 Valida se dados (aud, iss, iat e jti) são válidos - HTTP status code 403 – (INVALID_CLIENT);
 1.2.4.2 Valida reuso de jti - HTTP Code 403 (INVALID_CLIENT).
1.3 **Casos de erro sintáticos e semânticos, previstos com retorno HTTP Code 422 - Unprocessable Entity (detalhamento adicional na documentação técnica da API):**
 1.3.1 **Sintáticos**
 1.3.1.1 Envio de campos obrigatórios: Valida se todos os campos obrigatórios são informados (PARAMETRO_NAO_INFORMADO);
 1.3.1.2 Formatação de parâmetros: Valida se parâmetros informados obedecem a formatação especificada (PARAMETRO_INVALIDO).
 1.3.2 **Semânticos**
 1.3.2.1 Forma de pagamento: Valida se a forma de pagamento é suportada pela detentora (FORMA_PAGAMENTO_INVALIDA) **Obs. No detalhe do erro, a variável “modalidade” deve ser comunicada pela detentora da forma mais clara possível - ex. modalidade de pagamento não suportada (_localInstrument_ - QRES) ou tipo de arranjo pagamento não suportado (_type_ – ex. Pix / TED – previsto para inclusão futura);**
 1.3.2.2 Data de pagamento: Valida se a data de pagamento enviada é válida para a forma de pagamento selecionada (DATA_PAGAMENTO_INVALIDA);
 1.3.2.3 Detalhes do pagamento: Valida se determinado parâmetro informado obedece às regras de negócio (DETALHE_PAGAMENTO_INVALIDO);
 1.3.2.4 Demais validações não explicitamente informadas (ex. suspeita de fraude): (NAO_INFORMADO);
 1.3.2.5 Idempotência: Valida se há divergência entre chave de idempotência e informações enviadas (ERRO_IDEMPOTENCIA).
**Validações na criação do pagamento - Síncrono (_POST /payments_)**
2.1 **Casos de erro relacionados às permissões de segurança para acesso à API (ex. certificado, access_token, jwt, assinatura)**
 2.1.1 Validação de Certificado: Valida utilização de certificado correto durante processo de DCR - HTTP Code 401 (INVALID_CLIENT);
 2.1.2 Validação de Access_Token: Verifica se Access_Token utilizado está correto - HTTP Code 401 (UNAUTHORIZED);
 2.1.3 Validação de assinatura da mensagem: Valida se assinatura das mensagens enviadas está correta – HTTP Code 400 (BAD_SIGNATURE);
 2.1.4 Validação de Claims (exceto data);
 2.1.4.1 Valida se dados (aud, iss, iat e jti) são válidos - HTTP status code 403 – (INVALID_CLIENT);
 2.1.4.2 Valida reuso de jti - HTTP Code 403 (INVALID_CLIENT).
2.2 **Casos de erro sintáticos e semânticos, previstos com retorno HTTP Code 422 - Unprocessable Entity (detalhamento adicional na documentação técnica da API):**
 2.2.1 **Sintáticos**
 2.3.1.1 Envio de campos obrigatórios: Valida se todos os campos obrigatórios são informados (PARAMETRO_NAO_INFORMADO);
 2.3.1.2 Formatação de parâmetros: Valida se parâmetros informados obedecem a formatação especificada (PARAMETRO_INVALIDO).
 2.2.2 **Semânticos**
 2.2.2.1 Saldo do usuário: Valida se a conta selecionada possui saldo suficiente para realizar o pagamento (SALDO_INSUFICIENTE);
 2.2.2.2 Limites da transação: Valida se valor (ou quantidade de transações) ultrapassa faixa de limite parametrizada na detentora (VALOR_ACIMA_LIMITE);
 2.2.2.3 Valor informado (QR Code): Valida se valor enviado é válido para o QR Code informado (VALOR_INVALIDO);
 2.2.2.4 Cobrança inválida: Valida expiração, vencimento e status (COBRANCA_INVALIDA);
 2.2.2.5 Status Consentimento: Valida se o consentimento encontra-se em um dos estados finais “CONSUMED” ou “REJECTED" (CONSENTIMENTO_INVALIDO);
 2.2.2.6 Divergência entre pagamento e consentimento: Valida se dados do pagamento são diferentes dos dados do consentimento (PAGAMENTO_DIVERGENTE_CONSENTIMENTO)
 2.2.2.7 Recusado pela detentora: Valida se pagamento foi recusado pela detentora (PAGAMENTO_RECUSADO_DETENTORA), com a descrição do motivo de recusa (ex. chave Pix inválida, QRCode inválido, conta bloqueada);
 2.2.2.8 Detalhes do pagamento: Valida se determinado parâmetro informado obedece às regras de negócio (DETALHE_PAGAMENTO_INVALIDO);
 2.2.2.9 Demais validações não explicitamente informadas (ex. suspeita de fraude): (NAO_INFORMADO);
 2.2.2.10 Idempotência: Valida se há divergência entre chave de idempotência e informações enviadas (ERRO_IDEMPOTENCIA);
 2.2.2.11 Consentimento pendente de autorização: Em `PARTIALLY_ACCEPTED` aguardando aprovação de múltiplas alçadas. Não consome nem invalida o consentimento (CONSENTIMENTO_PENDENTE_AUTORIZACAO).
2.3 **Casos de erro para validações síncronas no DICT**
 Nesse cenário, o pagamento não é criado, porém o consentimento deve ser alterado para o status CONSUMED Retorno esperado do endpoint POST/Payments: HTTP Code 422 - Unprocessable Entity:
 • Erro por dados inválidos: Conforme item **2.2.2.8**
 • Erro por suspeita de fraude: Conforme item **2.2.2.9**
**Validações na consulta do pagamento (_GET /pix/payments/{paymentId}_)**
3.1 **Casos de erro relacionados às permissões de segurança para acesso à API (ex. certificado, access_token)**
 3.1.1 Validação de Certificado: Valida utilização de certificado correto durante processo de DCR - HTTP Code 401 (INVALID_CLIENT);
 3.1.2 Validação de Access_Token: Verifica se Access_Token utilizado está correto - HTTP Code 401 (UNAUTHORIZED).
**Demais validações executadas durante o processamento assíncrono do pagamento pela detentora, poderão ser consultados pela iniciadora através do endpoint _GET /pix/payments/{paymentId}_ previstos com retorno HTTP Code 200 - OK com status RJCT (Rejected) e rejectionReason conforme abaixo (detalhamento adicional na documentação técnica da API):**
4.1 **Demais validações durante processamento assíncrono**
 4.1.1 Saldo do usuário: Valida se a conta selecionada possui saldo suficiente para realizar o pagamento. No caso de um pagamento agendado, a validação só ocorre na tentativa de liquidação do pagamento (SALDO_INSUFICIENTE);
 4.1.2 Limites da transação: Valida se valor (ou quantidade de transações) ultrapassa faixa de limite parametrizada na detentora (VALOR_ACIMA_LIMITE);
 4.1.3 Valor informado (QR Code): Valida se valor enviado é válido para o QR Code informado (VALOR_INVALIDO);
 4.1.4 Cobrança inválida: Valida expiração, vencimento e status (COBRANCA_INVALIDA);
 4.1.5 Divergência entre pagamento e consentimento: Valida se dados do pagamento são diferentes dos dados do consentimento (PAGAMENTO_DIVERGENTE_CONSENTIMENTO);
 4.1.6 Recusado pela detentora: Valida se pagamento foi recusado pela detentora (PAGAMENTO_RECUSADO_DETENTORA), com a descrição do motivo de recusa (ex. chave Pix inválida, QRCode inválido, conta bloqueada);
 4.1.7 Detalhes do pagamento: Valida se determinado parâmetro informado obedece às regras de negócio (DETALHE_PAGAMENTO_INVALIDO);
 4.1.8 Demais validações não explicitamente informadas (ex. suspeita de fraude): (NAO_INFORMADO);
 4.1.9 Validação SPI: Externaliza validações no SPI (PAGAMENTO_RECUSADO_SPI);
 4.1.10 Falha em agendamentos: Uma ou mais incidências de pagamento não foram possíveis de ser agendadas (FALHA_AGENDAMENTO_PAGAMENTOS);
4.2 **Casos de erro para validações assíncronas no DICT**
 Neste cenário o pagamento é criado com sucesso (status RCVD) e o consentimento é consumido (status CONSUMED), porém, as validações contra o DICT só ocorrerão de forma assíncrona e em caso de negativa será percebido pela iniciadora na consulta do pagamento (GET /Payments).
 Retorno esperado do endpoint GET /Payments: HTTP Code 200 - OK.
 Status do Pagamento: RJCT (Rejected), com as seguintes opções rejectionReason:
 • Erro por dados inválidos: Conforme item **4.1.7**;
 • Erro por suspeita de fraude: Conforme item **4.1.8**.
**Demais validações executadas durante o processamento assíncrono do consentimento pela detentora poderão ser consultados pela iniciadora através do endpoint _GET /consents/{consentId}_ previstos com retorno HTTP Code 200 – OK com status REJECTED e rejectionReason conforme abaixo:**
5.1 **Validações durante o processamento assíncrono**
 5.1.1 - Falha de infraestrutura: Ocorreu algum erro interno na detentora durante processamento da criação do consentimento (FALHA_INFRAESTRUTURA)
 5.1.2 - Tempo de autorização expirado: O usuário não confirmou o consentimento e o mesmo expirou (TEMPO_EXPIRADO_AUTORIZACAO);
 5.1.3 - Rejeitado pelo usuário: O usuário explicitamente rejeitou a autorização do consentimento (REJEITADO_USUARIO);
 5.1.4 - Mesma conta origem/destino: A conta indicada pelo usuário para recebimento é a mesma selecionada para o pagamento (CONTAS_ORIGEM_DESTINO_IGUAIS);
 5.1.5 - Tipo de conta inválida: A conta indicada não permite operações de pagamento (CONTA_NAO_PERMITE_PAGAMENTO);
 5.1.6 - Saldo do usuário: Valida se a conta selecionada possui saldo suficiente para realizar o pagamento. Essa validação não deverá ocorrer no caso de um pagamento agendado (SALDO_INSUFICIENTE);
 5.1.7 - Limites da transação: Valida se o valor ultrapassa o limite estabelecido [na instituição/no arranjo/outro] para permitir a realização de transações pelo cliente (VALOR_ACIMA_LIMITE);
 5.1.8 - QRCode inválido: O QRCode utilizado para a iniciação de pagamento não é válido (QRCODE_INVALIDO);
 5.1.9 - Valor inválido: O valor enviado não é válido para o QR Code informado (VALOR_INVALIDO);
 5.1.10 - Não informado: Demais validações não explicitamente informadas (ex. suspeita de fraude) e consentimentos rejeitados em versões que não existiam o campo rejectionReason na API de Pagamentos (NAO_INFORMADO)
 5.1.11 - Tempo expirado consumo: O usuário não finalizou o fluxo de pagamento e o consentimento expirou (TEMPO_EXPIRADO_CONSUMO).
5.2 **[Momentos obrigatórios de validação dos rejectionReasons de acordo com o funil de consentimentos.](https://openfinancebrasil.atlassian.net/wiki/spaces/OF/pages/150863940) Para casos em que um consentimento for rejeitado por mais de um motivo, seguir a ordem de prioridade da tabela.**
```
|----------------------------------|------------------------------|---------------------|
| Etapas do funil de consentimento | rejectionReason/code | Ordem de prioridade |
|----------------------------------|------------------------------|---------------------|
| | TEMPO_EXPIRADO_AUTORIZACAO | 1 |
| Início da autenticação | FALHA_INFRAESTRUTURA | 2 |
| | NAO_INFORMADO | 3 |
|----------------------------------|------------------------------|---------------------|
| | TEMPO_EXPIRADO_AUTORIZACAO | 1 |
| | REJEITADO_USUARIO | 2 |
| Conclusão da autenticação | FALHA_INFRAESTRUTURA | 3 |
| | NAO_INFORMADO | 4 |
|----------------------------------|------------------------------|---------------------|
| | CONTA_NAO_PERMITE_PAGAMENTO | 1 |
| | CONTAS_ORIGEM_DESTINO_IGUAIS | 2 |
| | VALOR_INVALIDO | 3 |
| Autorização do cliente | QRCODE_INVALIDO | 4 |
| | VALOR_ACIMA_LIMITE | 5 |
| | SALDO_INSUFICIENTE | 6 |
| | FALHA_INFRAESTRUTURA | 7 |
| | NAO_INFORMADO | 8 |
|----------------------------------|------------------------------|---------------------|
| | FALHA_INFRAESTRUTURA | 1 |
| Authorisation code emitido | NAO_INFORMADO | 2 |
| | TEMPO_EXPIRADO_CONSUMO | 3 |
|----------------------------------|------------------------------|---------------------|
```
Existem dois `endpoints` para cancelamento de pagamentos, um deles é o _PATCH /pix/payments/{paymentId}_ e o outro é o _PATCH /pix/payments/consents/{consentId}_.
O _PATCH /pix/payments/{paymentId}_ deve ser utilizado para o cancelamento de um pagamento de forma unitária. Não deve ser utilizado para o cancelamento de todos os agendamentos recorrentes associados a um consentimento. O _PATCH /pix/payments/consents/{consentId}_ deve ser utilizado no cancelamento de todas as ocorrências de pagamentos agendados presentes em uma recorrência de pagamentos. Todos os pagamentos associados ao consentimento informado e passíveis de cancelamento (ainda não liquidados, com os status PDNG e SCHD) deverão ser cancelados.
## Quantidade máxima permitida para agendamentos recorrentes
A quantidade máxima de pagamentos que podem transitar do iniciador para o detentor são de 60 pagamentos, independente do modelo de recorrência definido no consentimento, respeitando o prazo máximo de dois anos para agendamentos.
Caso a opção de recorrência enviada pelo iniciador não respeite a regra acima, o detentor deve retornar o erro 422 "PARAMETRO_INVALIDO" com o detalhe "Quantidade permitida de pagamentos excedida".
| API de Iniciação de Pagamentos, responsável por viabilizar as operações de iniciação de pagamentos para o Open Finance Brasil.
Para cada uma das formas de pagamento previstas é necessário obter prévio consentimento do cliente através dos `endpoints` dedicados ao consentimento nesta API. # Orientações
No diretório de participantes duas `Roles` estão relacionadas à presente API: `CONTA`, referente às instituições detentoras de conta participantes do Open Finance Brasil; `PAGTO`, referente às instituições iniciadoras de pagamento participantes do Open Finance Brasil.
Os tokens utilizados para consumo nos endpoints de consentimentos devem possuir o scope `payments` e os `endpoints` de pagamentos devem possuir os `scopes`, `openid` e `payments`.
Esta API não requer a implementação de `permissions` para sua utilização. Todas as requisições e respostas devem ser assinadas seguindo o protocolo estabelecido na sessão <a href="https://openbanking-brasil.github.io/areadesenvolvedor/#assinaturas" target="_blank">Assinaturas</a> do guia de segurança.
## Regras do arranjo Pix
A implementação e o uso da API de Pagamentos Pix devem seguir as regras do arranjo Pix do Banco Central, que podem ser encontradas no link abaixo:
[https://www.bcb.gov.br/estabilidadefinanceira/pix?modalAberto=regulamentacao_pix](https://www.bcb.gov.br/estabilidadefinanceira/pix?modalAberto=regulamentacao_pix) ## Assinatura de payloads No contexto da API Payment Initiation, os `payloads` de mensagem que trafegam tanto por parte da instituição iniciadora de transação de pagamento quanto por parte da instituição detentora
de conta devem estar assinados. Para o processo de assinatura destes `payloads` as instituições devem seguir as especificações de segurança publicadas no Portal do desenvolvedor:
[[EN] Padrão de Certificados Open Finance Brasil 2.1](https://openfinancebrasil.atlassian.net/wiki/spaces/OF/pages/82084176/EN+Padr+o+de+Certificados+Open+Finance+Brasil+2.1%20%E2%80%8B)
## Controle de acesso Os endpoints de consulta e cancelamento devem suportar somente acesso a partir de access_token emitido por meio de um grant_type do tipo client_credentials. Para a criação do consentimento deve-se utilizar client_credentials e para criação de pagamentos deve-se utilizar authorization_code. ## Aprovações de múltipla alçada
Já para o caso de pagamento agendado, todas as aprovações devem ser realizadas até o exato dia anterior à data/hora prevista para primeira liquidação, respeitando a data/hora limite suportada pela detentora.
Caso não seja possível aprovação, o consentimento deve ser rejeitado pelo detentor.
## Validações para pagamentos recorrentes
o iniciador deve enviar a ordem de pagamento para liquidação com o endToEndId representando o dia seguinte à data prevista para a liquidação.
Se identificado pelo detentor que a data enviada no endToEndId corresponde a um dia inexistente, ele deve rejeitar o pagamento com erro 422,
com código PARAMETRO_INVALIDO e detalhe “Data de liquidação inválida”
assincronamente, é de responsabilidade do detentor realizar a transição para o status SCHD de todos os itens enviados na
lista de pagamentos em até 60 minutos (contados a partir da resposta de sucesso da solicitação).
Caso não seja possível realizar a transição de todos os pagamentos para SCHD, o detentor deverá mover todos os pagamentos
enviados pelo iniciador naquela mesma requisição para RJCT e preencher o motivo de rejeição correspondente,
FALHA_AGENDAMENTO_PAGAMENTOS. O consentimento irá para CONSUMED.
Durante a liquidação de pagamentos agendados, seguindo a resolução BCB n402, de 22/07/2024, previamente ao envio de um
pagamento à liquidação, o detentor deve consultar a chave utilizada para o agendamento no DICT. Se a consulta retornar que
a chave Pix não está registrada ou que os dados da chave divergem dos dados durante o agendamento, o detentor não deve
enviar o Pix para Liquidação. Todos os pagamentos associados a esse consentimento devem ser rejeitados com o
motivo CHAVE_PIX_DIVERGENTE_AGENDAMENTO_LIQUIDACAO, e o usuário pagador deve ser notificado
## Pix Saque e Troco A partir da versão 5.0.0 da API Pagamentos passa a ser possível a realização de Saques e Trocos através das funcionalidades disponíveis para tal no arranjo Pix. Para a realização das operações, as ITPs devem passar a reportar o payloadJWS completo que foi gerado pelo PSP do Recebedor, o qual contém todos os dados necessários para a validação das informações da operação em questão. Ao receber um pedido de criação de consentimento que esteja marcado como ```WITHDRAW``` ou ```CHANGE``` no campo ```/data/payment/purpose```, o PSP do Pagador (Detentor) deverá consultar os dados do agente e do facilitador do serviço dentro do payloadJWS enviado pelo ITP, assim como os outros dados pertinentes a operação solicitada. A identificação também deverá ser realizada pelo PSP do Pagador ao enviar a mensagem ```PACS.008``` ao SPI, com a marcação correta da finalidade da transação sendo realizada, bem como outras informações necessárias para a correta liquidação da operação de Saque ou Troco. Apenas pagamentos iniciados por usuários com plenos poderes de aprovação (que não necessitam de outras aprovações para autorização do consentimento) são permitidos. Pagamentos dependentes de múltiplas alçadas aprovadoras devem ter o consentimento rejeitado, após a autorização do primeiro aprovador, com o motivo PERMISSAO_INSUFICIENTE. Outras regras que devem ser observadas durante a validação e liquidação do QRCode de Pix Saque ou Pix Troco podem ser encontrados no Manual de Padrões para Iniciação do Pix, disponível no site do Banco Central.
## Validações
**Validações** (*após o processo de DCR e obtenção de token client credential*– não escopo dessa documentação)
Durante a jornada de iniciação de pagamento, diferentes validações são necessárias pela instituição detentora
de conta e devem ocorrer conforme a seguir: Na criação do consentimento (*POST /consents*); Na criação do pagamento - Síncrono (*POST /payments*); Validações na consulta do pagamento (*GET /pix/payments/{paymentId}*); Demais validações executadas durante o processamento assíncrono do pagamento pela detentora, poderão ser consultados pela iniciadora através do endpoint (*GET /pix/payments/{paymentId}*) previstos com retorno HTTP Code 200 - OK com status RJCT (Rejected) e rejectionReason; Demais validações executadas durante o processamento assíncrono do consentimento pela detentora poderão ser consultados pela iniciadora através do endpoint (*GET /consents/{consentId}*) previstos com retorno HTTP Code 200 – OK com status REJECTED e rejectionReason
**Os tipos de validações dispostas abaixo não determinam a ordem em que as instituições devem implementá-las** **Validações na criação do consentimento (_POST /consents_)**
1.1 **Orientações Iniciais**
 1.1.1 Não devem ser retornadas na resposta deste endpointinformações associadas ao usuário/cliente (ex. insuficiência de saldo, conta inexistente/bloqueada).
 1.1.2 Não devem ser executadas validações no DICT (Diretório de Identificadores de Contas Transacionais do Pix), a partir dos dados compartilhados nesse *endpoint*. Tais validações podem ocorrer somente na criação do pagamento;
 1.1.3 Não devem ser realizadas validações de informações sobre o usuário/cliente durante a criação do consentimento.
1.2 **Casos de erro relacionados às permissões de segurança para acesso à API (ex. certificado, access_token, jwt, assinatura)**
 1.2.1 Validação de Certificado: Valida utilização de certificado correto durante processo de DCR - HTTP Code 401 (INVALID_CLIENT);
 1.2.2 Validação de Access_Token: Verifica se Access_Token utilizado está correto - HTTP Code 401 (UNAUTHORIZED);
 1.2.3 Validação de assinatura da mensagem: Valida se assinatura das mensagens enviadas está correta – HTTP Code 400 (BAD_SIGNATURE);
 1.2.4 Validação de Claims (exceto data);
 1.2.4.1 Valida se dados (aud, iss, iat e jti) são válidos - HTTP status code 403 – (INVALID_CLIENT);
 1.2.4.2 Valida reuso de jti - HTTP Code 403 (INVALID_CLIENT).
1.3 **Casos de erro sintáticos e semânticos, previstos com retorno HTTP Code 422 - Unprocessable Entity (detalhamento adicional na documentação técnica da API):**
 1.3.1 **Sintáticos**
 1.3.1.1 Envio de campos obrigatórios: Valida se todos os campos obrigatórios são informados (PARAMETRO_NAO_INFORMADO);
 1.3.1.2 Formatação de parâmetros: Valida se parâmetros informados obedecem a formatação especificada (PARAMETRO_INVALIDO).
 1.3.2 **Semânticos**
 1.3.2.1 Forma de pagamento: Valida se a forma de pagamento é suportada pela detentora (FORMA_PAGAMENTO_INVALIDA) **Obs. No detalhe do erro, a variável “modalidade” deve ser comunicada pela detentora da forma mais clara possível - ex. modalidade de pagamento não suportada (_localInstrument_ - QRES) ou tipo de arranjo pagamento não suportado (_type_ – ex. Pix / TED – previsto para inclusão futura);**
 1.3.2.2 Data de pagamento: Valida se a data de pagamento enviada é válida para a forma de pagamento selecionada (DATA_PAGAMENTO_INVALIDA);
 1.3.2.3 Detalhes do pagamento: Valida se determinado parâmetro informado obedece às regras de negócio (DETALHE_PAGAMENTO_INVALIDO);
 1.3.2.4 Demais validações não explicitamente informadas (ex. suspeita de fraude): (NAO_INFORMADO);
 1.3.2.5 Idempotência: Valida se há divergência entre chave de idempotência e informações enviadas (ERRO_IDEMPOTENCIA).
 1.3.2.6 O propósito informado é incompatível com os dados presentes na transação. (PROPOSITO_INVALIDO)
**Validações na criação do pagamento - Síncrono (_POST /payments_)**
2.1 **Casos de erro relacionados às permissões de segurança para acesso à API (ex. certificado, access_token, jwt, assinatura)**
 2.1.1 Validação de Certificado: Valida utilização de certificado correto durante processo de DCR - HTTP Code 401 (INVALID_CLIENT);
 2.1.2 Validação de Access_Token: Verifica se Access_Token utilizado está correto - HTTP Code 401 (UNAUTHORIZED);
 2.1.3 Validação de assinatura da mensagem: Valida se assinatura das mensagens enviadas está correta – HTTP Code 400 (BAD_SIGNATURE);
 2.1.4 Validação de Claims (exceto data);
 2.1.4.1 Valida se dados (aud, iss, iat e jti) são válidos - HTTP status code 403 – (INVALID_CLIENT);
 2.1.4.2 Valida reuso de jti - HTTP Code 403 (INVALID_CLIENT).
2.2 **Casos de erro sintáticos e semânticos, previstos com retorno HTTP Code 422 - Unprocessable Entity (detalhamento adicional na documentação técnica da API):**
 2.2.1 **Sintáticos**
 2.3.1.1 Envio de campos obrigatórios: Valida se todos os campos obrigatórios são informados (PARAMETRO_NAO_INFORMADO);
 2.3.1.2 Formatação de parâmetros: Valida se parâmetros informados obedecem a formatação especificada (PARAMETRO_INVALIDO).
 2.2.2 **Semânticos**
 2.2.2.1 Saldo do usuário: Valida se a conta selecionada possui saldo suficiente para realizar o pagamento (SALDO_INSUFICIENTE);
 2.2.2.2 Limites da transação: Valida se valor (ou quantidade de transações) ultrapassa faixa de limite parametrizada na detentora (VALOR_ACIMA_LIMITE);
 2.2.2.3 Valor informado (QR Code): Valida se valor enviado é válido para o QR Code informado (VALOR_INVALIDO);
 2.2.2.4 Cobrança inválida: Valida expiração, vencimento e status (COBRANCA_INVALIDA);
 2.2.2.5 Status Consentimento: Valida se o consentimento encontra-se em um dos estados finais “CONSUMED” ou “REJECTED" (CONSENTIMENTO_INVALIDO);
 2.2.2.6 Divergência entre pagamento e consentimento: Valida se dados do pagamento são diferentes dos dados do consentimento (PAGAMENTO_DIVERGENTE_CONSENTIMENTO)
 2.2.2.7 Recusado pela detentora: Valida se pagamento foi recusado pela detentora (PAGAMENTO_RECUSADO_DETENTORA), com a descrição do motivo de recusa (ex. chave Pix inválida, QRCode inválido, conta bloqueada);
 2.2.2.8 Detalhes do pagamento: Valida se determinado parâmetro informado obedece às regras de negócio (DETALHE_PAGAMENTO_INVALIDO);
 2.2.2.9 Demais validações não explicitamente informadas (ex. suspeita de fraude): (NAO_INFORMADO);
 2.2.2.10 Idempotência: Valida se há divergência entre chave de idempotência e informações enviadas (ERRO_IDEMPOTENCIA);
 2.2.2.11 Consentimento pendente de autorização: Em `PARTIALLY_ACCEPTED` aguardando aprovação de múltiplas alçadas. Não consome nem invalida o consentimento (CONSENTIMENTO_PENDENTE_AUTORIZACAO).
2.3 **Casos de erro para validações síncronas no DICT**
 Nesse cenário, o pagamento não é criado, porém o consentimento deve ser alterado para o status CONSUMED Retorno esperado do endpoint POST/Payments: HTTP Code 422 - Unprocessable Entity:
 • Erro por dados inválidos: Conforme item **2.2.2.8**
 • Erro por suspeita de fraude: Conforme item **2.2.2.9**
**Validações na consulta do pagamento (_GET /pix/payments/{paymentId}_)**
3.1 **Casos de erro relacionados às permissões de segurança para acesso à API (ex. certificado, access_token)**
 3.1.1 Validação de Certificado: Valida utilização de certificado correto durante processo de DCR - HTTP Code 401 (INVALID_CLIENT);
 3.1.2 Validação de Access_Token: Verifica se Access_Token utilizado está correto - HTTP Code 401 (UNAUTHORIZED).
**Demais validações executadas durante o processamento assíncrono do pagamento pela detentora, poderão ser consultados pela iniciadora através do endpoint _GET /pix/payments/{paymentId}_ previstos com retorno HTTP Code 200 - OK com status RJCT (Rejected) e rejectionReason conforme abaixo (detalhamento adicional na documentação técnica da API):**
4.1 **Demais validações durante processamento assíncrono**
 4.1.1 Saldo do usuário: Valida se a conta selecionada possui saldo suficiente para realizar o pagamento. No caso de um pagamento agendado, a validação só ocorre na tentativa de liquidação do pagamento (SALDO_INSUFICIENTE);
 4.1.2 Limites da transação: Valida se valor (ou quantidade de transações) ultrapassa faixa de limite parametrizada na detentora (VALOR_ACIMA_LIMITE);
 4.1.3 Valor informado (QR Code): Valida se valor enviado é válido para o QR Code informado (VALOR_INVALIDO);
 4.1.4 Cobrança inválida: Valida expiração, vencimento e status (COBRANCA_INVALIDA);
 4.1.5 Divergência entre pagamento e consentimento: Valida se dados do pagamento são diferentes dos dados do consentimento (PAGAMENTO_DIVERGENTE_CONSENTIMENTO);
 4.1.6 Recusado pela detentora: Valida se pagamento foi recusado pela detentora (PAGAMENTO_RECUSADO_DETENTORA), com a descrição do motivo de recusa (ex. chave Pix inválida, QRCode inválido, conta bloqueada);
 4.1.7 Detalhes do pagamento: Valida se determinado parâmetro informado obedece às regras de negócio (DETALHE_PAGAMENTO_INVALIDO);
 4.1.8 Demais validações não explicitamente informadas (ex. suspeita de fraude): (NAO_INFORMADO);
 4.1.9 Validação SPI: Externaliza validações no SPI (PAGAMENTO_RECUSADO_SPI);
 4.1.10 Falha em agendamentos: Uma ou mais incidências de pagamento não foram possíveis de ser agendadas (FALHA_AGENDAMENTO_PAGAMENTOS);
 4.1.11 Divergências entre dados das chaves pix para agendamento e liquidação: O pagamento agendado não pode ser enviado para liquidação devido a divergências entre dados da chave recebedora utilizada para criação do agendamento com a chave recebedora em momento de liquidação (CHAVE_PIX_DIVERGENTE_AGENDAMENTO_LIQUIDACAO);
 4.1.12 Erro de infraestrutura na consulta ao DICT: Ocorreu uma falha de infraestrutura durante a consulta ao DICT (FALHA_INFRAESTRUTURA_DICT);
 4.1.13 Erro de infraestrutura na consulta ao ICP: Ocorreu uma falha de infraestrutura durante a consulta ao ICP (FALHA_INFRAESTRUTURA_ICP);
 4.1.14 Erro de infraestrutura na comunicação com o PSP do recebedor: Ocorreu uma falha de infraestrutura durante a comunicação com o PSP do recebedor (FALHA_INFRAESTRUTURA_PSP_RECEBEDOR);
 4.1.15 Erro de infraestrutura interno na detentora: Ocorreu uma falha de infraestrutura interna na detentora durante o processamento do pagamento (FALHA_INFRAESTRUTURA_DETENTORA);
 4.1.16 Erro de infraestrutura na consulta ao SPI: Ocorreu uma falha de infraestrutura durante a consulta ao SPI (FALHA_INFRAESTRUTURA_SPI).
4.2 **Casos de erro para validações assíncronas no DICT**
 Neste cenário o pagamento é criado com sucesso (status RCVD) e o consentimento é consumido (status CONSUMED), porém, as validações contra o DICT só ocorrerão de forma assíncrona e em caso de negativa será percebido pela iniciadora na consulta do pagamento (GET /Payments).
 Retorno esperado do endpoint GET /Payments: HTTP Code 200 - OK.
 Status do Pagamento: RJCT (Rejected), com as seguintes opções rejectionReason:
 • Erro por dados inválidos: Conforme item **4.1.7**;
 • Erro por suspeita de fraude: Conforme item **4.1.8**.
**Demais validações executadas durante o processamento assíncrono do consentimento pela detentora poderão ser consultados pela iniciadora através do endpoint _GET /consents/{consentId}_ previstos com retorno HTTP Code 200 – OK com status REJECTED e rejectionReason conforme abaixo:**
5.1 **Validações durante o processamento assíncrono**
 5.1.1 - Falha de infraestrutura: Ocorreu algum erro interno na detentora durante processamento da criação do consentimento (FALHA_INFRAESTRUTURA)
 5.1.2 - Tempo de autorização expirado: O usuário não confirmou o consentimento e o mesmo expirou (TEMPO_EXPIRADO_AUTORIZACAO);
 5.1.3 - Rejeitado pelo usuário: O usuário explicitamente rejeitou a autorização do consentimento (REJEITADO_USUARIO);
 5.1.4 - Mesma conta origem/destino: A conta indicada pelo usuário para recebimento é a mesma selecionada para o pagamento (CONTAS_ORIGEM_DESTINO_IGUAIS);
 5.1.5 - Tipo de conta inválida: A conta indicada não permite operações de pagamento (CONTA_NAO_PERMITE_PAGAMENTO);
 5.1.6 - Saldo do usuário: Valida se a conta selecionada possui saldo suficiente para realizar o pagamento. Essa validação não deverá ocorrer no caso de um pagamento agendado (SALDO_INSUFICIENTE);
 5.1.7 - Limites da transação: Valida se o valor ultrapassa o limite estabelecido [na instituição/no arranjo/outro] para permitir a realização de transações pelo cliente (VALOR_ACIMA_LIMITE);
 5.1.8 - QRCode inválido: O QRCode utilizado para a iniciação de pagamento não é válido (QRCODE_INVALIDO);
 5.1.9 - Valor inválido: O valor enviado não é válido para o QR Code informado (VALOR_INVALIDO);
 5.1.10 - Não informado: Demais validações não explicitamente informadas (ex. suspeita de fraude) e consentimentos rejeitados em versões que não existiam o campo rejectionReason na API de Pagamentos (NAO_INFORMADO)
 5.1.11 - Tempo expirado consumo: O usuário não finalizou o fluxo de pagamento e o consentimento expirou (TEMPO_EXPIRADO_CONSUMO).
 5.1.12 - Autenticação divergente: O usuário autenticado no ambiente da detentora não é o mesmo usuário autenticado no ambiente da iniciadora e que criou o consentimento (AUTENTICACAO_DIVERGENTE).
 5.1.13 - Permissão insuficiente: A solicitação de Saque ou Troco foi realizada por um usuário sem plenos poderes de aprovação (PERMISSAO_INSUFICIENTE).
5.2 **[Momentos obrigatórios de validação dos rejectionReasons de acordo com o funil de consentimentos.](https://openfinancebrasil.atlassian.net/wiki/spaces/OF/pages/150863940) Para casos em que um consentimento for rejeitado por mais de um motivo, seguir a ordem de prioridade da tabela.**
```
|----------------------------------|------------------------------|---------------------|
| Etapas do funil de consentimento | rejectionReason/code | Ordem de prioridade |
|----------------------------------|------------------------------|---------------------|
| | TEMPO_EXPIRADO_AUTORIZACAO | 1 |
| Início da autenticação | FALHA_INFRAESTRUTURA | 2 |
| | NAO_INFORMADO | 3 |
|----------------------------------|------------------------------|---------------------|
| | TEMPO_EXPIRADO_AUTORIZACAO | 1 |
| | REJEITADO_USUARIO | 2 |
| Conclusão da autenticação | FALHA_INFRAESTRUTURA | 3 |
| | NAO_INFORMADO | 4 |
|----------------------------------|------------------------------|---------------------|
| | AUTENTICACAO_DIVERGENTE | 1 |
| | CONTA_NAO_PERMITE_PAGAMENTO | 2 |
| | CONTAS_ORIGEM_DESTINO_IGUAIS | 3 |
| | VALOR_INVALIDO | 4 |
| Autorização do cliente | QRCODE_INVALIDO | 5 |
| | VALOR_ACIMA_LIMITE | 6 |
| | SALDO_INSUFICIENTE | 7 |
| | FALHA_INFRAESTRUTURA | 8 |
| | NAO_INFORMADO | 9 |
|----------------------------------|------------------------------|---------------------|
| | FALHA_INFRAESTRUTURA | 1 |
| Authorisation code emitido | NAO_INFORMADO | 2 |
| | TEMPO_EXPIRADO_CONSUMO | 3 |
|----------------------------------|------------------------------|---------------------|
```
5.3 **Momentos obrigatórios de validação dos rejectionReasons de consentimentos autorizados via JSR**
Consentimentos autorizados a partir do fluxo sem redirecionamento possuem um funil de conversão diferente, dado que não há o redirecionamento e este é um grande segregador das etapas do funil.
Devido a isso, as validações e a ordem que estas devem ser feitas, descritas no tópico anterior, não se aplicam integralmente aos consentimentos que foram autorizados no fluxo sem redirecionamento. Para consentimentos autorizados via fluxo sem redirecionamento, os únicos motivos de rejeição cabíveis são:
TEMPO_EXPIRADO_AUTORIZACAO – Utilizado quando o gesto FIDO não foi realizado a tempo pelo cliente final TEMPO_EXPIRADO_CONSUMO – Utilizado quando o ITP, em posse do consentimento autorizado, não envia o pagamento. FALHA_INFRAESTRUTURA – Utilizado quando uma falha sistêmica impediu o avanço no processo do consentimento.
Demais validações que antes ocorriam no consentimento, agora devem ocorrer apenas em momento de pagamento. Permitindo assim que a detentora de contas tenha tempo de realizar as validações de maneira assíncrona a autorização do consentimento
### Cancelamento de Pagamentos
Existem dois `endpoints` para cancelamento de pagamentos, um deles é o _PATCH /pix/payments/{paymentId}_ e o outro é o _PATCH /consents/{consentId}/pix/payments_. O _PATCH /pix/payments/{paymentId}_ deve ser utilizado para o cancelamento de um pagamento de forma unitária. Não deve ser utilizado para o cancelamento de todos os agendamentos recorrentes associados a um consentimento. O _PATCH /consents/{consentId}/pix/payments_ deve ser utilizado no cancelamento de todas as ocorrências de pagamentos agendados presentes em uma recorrência de pagamentos. Todos os pagamentos associados ao consentimento informado e passíveis de cancelamento (ainda não liquidados, com os status PDNG e SCHD) deverão ser cancelados.
## Quantidade máxima permitida para agendamentos recorrentes
A quantidade máxima de pagamentos que podem transitar do iniciador para o detentor são de 60 pagamentos, independente do modelo de recorrência definido no consentimento, respeitando o prazo máximo de dois anos para agendamentos.
Caso a opção de recorrência enviada pelo iniciador não respeite a regra acima, o detentor deve retornar o erro 422 "PARAMETRO_INVALIDO" com o detalhe "Quantidade permitida de pagamentos excedida".
|