Este documento tem por objetivo definir as especificações e os critérios técnicos necessários para adesão dos Prestadores de Serviços de Pagamento (PSPs) ao Modelo de Credenciamento do sistema PagTesouro que foi instituído pela Secretaria do Tesouro Nacional (STN), tendo como principal objetivo o pagamento das Guias de Recolhimento da União (GRUs) pelos contribuintes de forma digital como, por exemplo, via cartão de crédito.

O conteúdo deste manual destina-se a programadores e desenvolvedores de plataformas de comércio eletrônico que desejam integrar-se ao PagTesouro para recebimento de pagamentos de GRUs, a partir do desenvolvimento e disponibilização de serviços web conforme documentados na seção "API".

Para a perfeita integração do PSP com o PagTesouro, as seguintes premissas deverão ser atendidas:

• Os serviços descritos na seção "API/PagTesouro" deverão ser implementados pelo PSP e consumidos pelo PagTesouro de forma padronizada, enquanto o serviço para recebimento das notificações de pagamentos finalizados, descrito na seção "API/PSP", será construído pelo PagTesouro e acionado pelo PSP.
• A integração do PagTesouro com o PSP ocorrerá através de redirecionamento para o ambiente seguro do PSP (checkout padrão).
• O PagTesouro não irá tratar a situação de estorno de pagamento. Assim, mesmo que um pagamento concluído seja estornado no PSP, o PagTesouro continuará assumindo a situação de concluído.
• O PSP deverá prover um ambiente para testes de integração com o PagTesouro de forma isolada (por exemplo, a utilização de outra URL ou a mesma URL com outras credenciais), de modo a garantir que a realização dos testes possa ocorrer normalmente mesmo após a entrada em produção.
• O PagTesouro disponibilizará uma Sandbox para que o PSP possa simular a execução do fluxo do pagamento de forma a testar a integração dos serviços implementados.

Os dados serão enviados e recebidos via serviços Web e será adotado o estilo arquitetural REST (Representational State Transfer) na construção dos serviços Web. A tabela abaixo lista os padrões de comunicação definidos para a integração do PSP com o PagTesouro:

Para os serviços disponíveis, a comunicação deverá contemplar os seguintes itens de segurança:

• Uso de conexão criptografada via HTTPS (HyperText Transfer Protocol Secure).
• Utilização do protocolo TLS 1.2 pelo HTTPS para garantir a autenticidade e a criptografia dos dados das mensagens trafegadas. Não serão suportadas versões anteriores do TLS.
• Restrição de uso somente aos IPs dos PSPs credenciados (whitelist) para o consumo do serviço de Notificação do Pagamento. O PSP deverá encaminhar a sua lista de IPs à STN.
• Utilização de certificado digital do tipo A1 para autenticação mútua, a fim de garantir a Confidencialidade, Integridade e Autenticidade dos dados trafegados.
• O certificado deve ser emitido por Autoridade Certificadora credenciada pela Infraestrutura de Chaves Públicas Brasileira – ICP-Brasil, devendo conter o CNPJ da pessoa jurídica titular do Certificado digital, que poderá estar armazenado de acordo com seu tipo:
  
  • certificado de equipamento: na entrada Serial Number na estrutura Distinguished Name (DN);
  • certificado de aplicação: no campo otherName OID=2.16.76.1.3.3 da estrutura Subject Alternative Name (SAN).
  
  O certificado deve ter a extensão Extended Key Usage com permissão de "Autenticação Cliente" e a chave do certificado deverá ser no mínimo de 2048 bits.
• A responsabilidade pela aquisição de certificados, tanto para utilização no ambiente de Testes do PagTesouro quanto no ambiente de Produção, é do PSP. A recomendação é que cada PSP tenha certificados diferentes para os referidos ambientes.
• Ao receber uma notificação de pagamento, o PagTesouro validará o CNPJ do PSP presente no certificado recebido. Da mesma forma, ao receber uma solicitação ou consulta de pagamento, o PSP deverá validar o CNPJ do Serpro (33683111000107) contido no certificado enviado na requisição.
• Embora em cada requisição de serviço recebida pelo PagTesouro (notificação de pagamento) ou pelo PSP (solicitação e consulta de pagamento) haja a validação do CNPJ do certificado cliente, não é necessário que as URLs expostas desses serviços façam uso de certificados ICP-Brasil, desde que a cadeia de certificados seja amplamente reconhecida. O domínio do PagTesouro ou do PSP poderiam usar, por exemplo, um certificado Let's Encrypt, GlobalSign etc.

Os tipos de pagamento que estarão disponíveis no PagTesouro, para os quais o PSP poderá se integrar, são os seguintes:

• Cartão de Crédito

No acionamento do serviço de Solicitação de Pagamento, o PagTesouro enviará para o PSP a relação dos tipos permitidos para aquele pagamento de GRU e, dessa forma, este deverá disponibilizar para o contribuinte apenas estas opções em seu ambiente de pagamento.

O domínio de valores possíveis para os tipos de pagamento permitidos no serviço de Solicitação de Pagamento será o seguinte:

• "CARTAO_CREDITO"

Para o PagTesouro um pagamento possuirá apenas três situações possíveis após realizada a solicitação ao PSP, são estas:

• "PENDENTE": indica que o pagamento foi submetido e iniciado no PSP mas ainda está pendente de conclusão.
• "CONCLUIDO": indica que o pagamento no PSP foi concluído com sucesso.
• "REJEITADO": indica que o pagamento no PSP não foi concluído com sucesso, ou seja, ou foi cancelado ou rejeitado.

As situações CONCLUIDO e REJEITADO para o PagTesouro são estados finalísticos, ou seja, não poderão mais ser alterados após o pagamento assumir essa situação.

O serviço de Consulta de Pagamento a ser implementado pelo PSP deverá retornar ao PagTesouro a situação atual do pagamento conforme seu domínio próprio.

Internamente o PagTesouro fará o mapeamento da situação retornada pelo PSP, conforme configuração prévia, para uma das três situações previstas no PagTesouro.

O PSP deverá notificar o PagTesouro, através do serviço Notificação do Pagamento, quando o pagamento for finalizado no PSP ou quando sua situação sofrer alteração.

O PSP terá um prazo de até 24 horas para que a situação do pagamento assuma um estado finalístico, em que este não possa mais ser alterado. Assim, após esse prazo, caso o pagamento não esteja finalizado, o PSP deverá cancelá-lo e notificar o PagTesouro.