MANUAL E LAYOUT API PIX 2.0.0 PIX - exclusive.bradesco

1 MANUAL E LAYOUT API PIX PIX Vers o 03 Outubro/ 2020 SUM RIO Altera o de vers 3 A solu 3 Integra 3 3 MANUAL Banco 3 1. Gerar credenciais de acesso 6 2. Requisi o para obter token de 6 3. Chamada API 7 4. Revoga 7 5. Implementa 8 Conceito 9 1. Gerenciamento de Cobran 12 Criar Cobran 12 Revisar cobran 16 Consultar Cobran 20 Consultar Lista de Cobran 25 2. Gerenciamento de Pix 31 Solicitar devolu 31 Consultar devolu 33 Consultar 35 Consultar Pix 38 3. Gerenciamento de Notifica 42 Configurar o Webhook 42 43 Exibir informa es acerca do Webook 46 Cancelar o Webook 47 Gloss 48 02 Vers o 03 Outubro/ 2020 Altera o de vers o As altera es de vers o ser o comunicadas neste campo.

2 Vers o 02: ajuste inclus o URL de homologa o. Vers o 03: ajuste no fluxo de implementa o e URL homologa o e produ o. A solu o Com Pix poss vel receber pagamentos e transfer ncias, 24 horas por dia, 365 dias no ano, inclusive aos finais de semana e feriados. O cr dito cai na hora, inclusive entre diferentes institui es Integra o O objetivo deste MANUAL orientar o desenvolvedor sobre como realizar integra o da API Pix. Objetivo Este MANUAL apresentar o modelo de acesso API Pix Interface de Programa o de Aplicativos normatizada pelo Bacen, com foco no processo de autentica o e autoriza o de aplica es servidor ao servidor. Ser demonstrado o passo a passo para automatizar o uso da API Pix. O padr o de autentica o adotado ser o OAUTH2. Conforme MANUAL do Banco Central os PSPs devem desenvolver e implementar a API seguindo boas pr ticas de seguran a, atendendo aos requisitos obrigat rios abaixo e s recomenda es detalhadas nesta se o.

3 MANUAL Banco Central Requisitos de seguran a obrigat rios O PSP deve obrigatoriamente observar os seguintes requisitos: 1. A conex o API deve ser criptografada utilizando o protocolo TLS vers o ou superior, permitindo apenas cipher suites que atendam ao requisito de forward secrecy63. 2. O PSP deve implementar o framework OAuth (RFC 6749)64 com TLS m tuo (mTLS RFC 870565) para autentica o na API, conforme especifica es abaixo: a. Os certificados digitais dos clientes da API poder o ser emitidos pelo pr prio PSP ou por ACs externas, conforme definido por cada PSP. N o dever o ser aceitos certificados auto-assinados pelo cliente. b. Cada PSP deve possuir seu pr prio Authorization Server e Resource Server associado API Pix, e ambos devem implementar TLS m tuo. c. O Authorization Server do PSP deve implementar a t cnica de vincula o do certificado do cliente aos access tokens emitidos ( Client Certificate-Bound Access Tokens ), conforme se o 3 da RFC 8705.

4 Vers o 03 Outubro/ 2020 03 d. O Resource Server do PSP deve confirmar que o thumbprint do certificado associado ao access token apresentado pelo cliente o mesmo do utilizado na autentica o TLS (proof-of-possession). e. O fluxo OAuth a ser utilizado o Client Credentials Flow . f. Os escopos OAuth ser o definidos na especifica o Open API da API Pix e permitir o associar diferentes perfis de autoriza o ao software cliente. 3. O processo de cadastro/onboarding do cliente para acesso API deve ser realizado em ambiente logado no PSP, e deve incluir um canal seguro para envio das credenciais ao usu rio, de forma a permitir a rastreabilidade das a es executadas. 4. A API deve suportar m ltiplos n veis de autoriza o ou pap is, segregando as funcionalidades de acordo com perfis (escopos OAuth) dos usu rios clientes.

5 5. O PSP deve implementar tecnologia que permita garantir a alta disponibilidade da API. 6. A API deve garantir a confidencialidade e a integridade das informa es dos usu rios e de suas transa es, tanto em tr nsito como em repouso. 7. O PSP deve manter logs de auditoria dos acessos API pelo per odo m nimo de 1 ano. 8. A credencial de acesso utilizada na autentica o (Client_ID) deve ser vinculada ao CNPJ ou CPF do usu rio recebedor e deve permitir acesso a recursos apenas de contas transacionais de titularidade do CNPJ ou CPF associado. Recomenda es de seguran a recomendado ao PSP: 1. Implementar m ltiplos fatores de autentica o para o processo de cadastro/onboarding na API. 2. Desenvolver e implementar a API seguindo boas pr ticas de seguran a, de forma a eliminar/reduzir ao m ximo os riscos de seguran a conforme ltima vers o dos guias OWASP API Security Top Ten66 e CWE Top 25 Software Weaknesses67.

6 3. Possuir processo peri dico de an lise de vulnerabilidades, tanto est tica como din mica da API. 4. Assegurar a seguran a do desenvolvimento do software cliente68 da API, mesmo que desenvolvido por terceiros. Sugere-se que o PSP institua e mantenha processo de homologa o dos softwares clientes, estabelecendo crit rios m nimos de seguran a para que eles sejam autorizados a interagir com a API. Nesse caso, a API deve negar tentativas de comunica o de clientes n o homologados. 5. Os usu rios recebedores, como clientes da API, s o um elo importante na seguran a do sistema, e, portanto, recomenda-se que o PSP tome a es para mitigar os riscos do ambiente computacional dos seus usu rios, uma vez que caso 04 Vers o 03 Outubro/ 2020 um risco se materialize em um incidente, o pr prio PSP poder ser afetado. A es recomendadas (sem preju zo para outras a es que o PSP julgar importantes): a.

7 Instituir e acompanhar programa de melhoria cont nua da seguran a dos usu rios recebedores que utilizam a API; b. Realizar campanhas de conscientiza o e compartilhamento de informa es de seguran a junto aos usu rios; c. Definir uma pol tica de troca peri dica do certificado, senha e outras credenciais utilizadas no acesso API; d. Validar a seguran a do ambiente computacional dos usu rios nos aspectos de infraestrutura, implementa o e configura o do software cliente da API. e. Exigir que as empresas e institui es que utilizem a API tenham uma Pol tica de Seguran a da Informa o formalmente institu da. O BC entende que os PSPs poder o adotar as tecnologias e solu es de seguran a para a API que mais acharem apropriados, desde que sejam atendidos os requisitos obrigat rios de seguran a e, sempre que poss vel, as recomenda es descritas acima, com aten o tamb m aos elementos listados nos t picos a seguir.

8 Jornada de ades o Por jornada de ades o, entende-se o processo por meio do qual um usu rio recebedor passa a utilizar os servi os de um PSP espec fico. Do ponto de vista da API Pix, tal processo deve incluir o fornecimento de credenciais de acesso (Client_IDs e Client_Secrets) e de certificados ao usu rio recebedor. Cada PSP ter autonomia para definir a jornada de Ades o para os seus clientes, utilizando os canais que julgar mais adequados. No processo de ades o, o Client_ID disponibilizado pelo PSP deve possuir um conjunto de escopos que determinar o as funcionalidades s quais o Usu rio Recebedor ter acesso. Os crit rios de autoriza o nos escopos s o de responsabilidade do PSP, que pode criar crit rios diferenciados em fun o das caracter sticas do Usu rio Recebedor. Dessa forma, poss vel, por exemplo, que determinadas funcionalidades estejam acess veis apenas por usu rios que cumpram requisitos adicionais de seguran a estipulados por cada PSP.

9 Vers o 03 Outubro/ 2020 05 1. Gerar credenciais de acesso Para gera o das credencias de acesso (client_id e client_secret) necess rio enviar os dados da Empresa (Nome, CNPJ, dados para contato) e informa es sobre seu Aplicativo/Website (finalidade e endpoints ser o utilizados) juntamente com o certificado digital gerado por uma autoridade certificadora p blica reconhecida no Brasil, conforme detalhado na documenta o do Pix. 2. Requisi o para obter token de acesso Ap s o passo 1 as credenciais client_id e client_secret ser o enviados para a empresa que solicitou o cadastro. Com posse dessas informa es uma requisi o ao dom nio PIX do Bradesco dever ser realizada para obten o do token de acesso (JWT) seguindo as informa es abaixo. Estabelecer uma conex o mTLS (utilizando o certificado digital enviado no primeiro passo) com a URL: "https:// " enviando uma requisi o (request) com as seguintes caracter sticas: - HTTP method = POST - Content-type = application/x-www-form-urlencoded Headers da requisi o: - Authorization = Basic encodeBase64(client_id:client_secret) Exemplo: Authorization = Basic ZWI4 MTkxNmYtODQ0Yi00 YjQ5 LTk4 ODEtM2M0 OTJjYmM0 YTk5 OjcxY2 VkNDljLTkxMGEtNDg2MS04 YjgxLWYzNmM5 MWEyNmE3Yw== Parametros/Body da requisi o: - grant_type = client_credentials (obrigat rio) - scope = (opcional - pode ser vazio ou com informa es dos escopos do Pix separado por espa o Ex.)

10 **inserir os escopos que foi informado para o Pix**) 06 Vers o 03 Outubro/ 2020 O resultado da requisi o possuir os valores: - access_token = Token de acesso em formato JWT contento as claims necess rias para valida o do acesso - token_type = Bearer (token de portador) - expires_in = Tempo para expira o do Token (em segundos) Com estas informa es j ser poss vel realizar requisi es para os endpoints do Pix. 3. Chamada API Pix Em posse das informa es produzidas pelo passo 2, a empresa dever informar o token de acesso (JWT) junto com o token_type em um campo Authorization no cabe alho de qualquer requisi o para os endpoints referentes aos servi os do Pix, Cria uma requisi o para API do Pix - HTTP method: GET|POST|PUT|DELETE <api_path> { .. } Headers da requisi o: Authorization = Bearer <access_token> Parametros/Body da requisi o: - Informa es necess rias para execu o do servi o do Pix (JSON, etc.