APOSTILA: Manual de Padrões para Iniciação do Pix

APOSTILA: Manual de Padrões para Iniciação do Pix = PDF DOWLOAD

Manual de Padrões

para Iniciação do Pix

Versão 2.6.3

Histórico de revisão

Data	Versão	Descrição das alterações
11/8/2020	1.0	Versão inicial
23/9/2020	1.1	· Ajustes nas definições nos campos do payload, especialmente na semântica do campo txid. · Incluídos os Anexos I e II, tratando dos Conceitos de Negócio da API Pix e das suas especificações técnicas.
13/10/2020	2.0	· Seção 1.5.2: incluídas explicações sobre caracteres permitidos no campo txid. · Seção 1.6.1: incluído texto para deixar claro que o QR Code dinâmico pode ser gerado por meio de aplicativo. · Seção 1.6.6: excluído texto para deixar claro que o QR Code dinâmico não precisa ser necessariamente gerado por meio da API Pix. · Seção 1.6.8: ajuste na explicação do campo “calendario.vencimento” e exclusão do campo “calendario.recebivelAposVencimento”. · Seção 1.6.17: inclusão de nota de rodapé no campo 62 “Additional Data Field”. · Seção 1.6.18: incluído texto para deixar claro que o QR Code dinâmico pode ser gerado por meio de aplicativo. · Incluída a seção 1.7, que trata sobre a funcionalidade “Pix Copia e Cola”. · Seção 6.3.3 do Anexo I: correção da função associada à alteração da cobrança via API Pix.
06/11/2020	2.1	· Seção 1.6: atualização dos campos do Payload JSON, com a inclusão de campos referentes às funcionalidades de cobrança para pagamentos com vencimento (juros, multa, abatimento, desconto e correlatos); reorganização das subseções para refletir as diferenças de campos entre as cobranças para pagamentos imediatos e pagamentos com vencimento; · Adicionados ao Anexo I casos de uso relacionados ao “Reuso de Location”, cenários incluindo cobrança para pagamentos com vencimento e geração de cobranças em lotes. · Inclusão do Anexo III tratando sobre criação, atualização e cálculo de cobranças para pagamentos com vencimento.
09/12/2020	2.2	· Seção 1.6.6.2: inserção na tabela que exibe a estrutura do payload JSON para cobranças com vencimento da informação calendario.validadeAposVencimento. · Anexo II – Seção 3.1: inserção de recomendação relativa ao uso de certificados nos webhooks.
12/02/2021	2.2.1	· Seção 1.6.6.1: adicionada explicação para a regra de incrementos do campo. · Seção 1.6.6.2: adicionados esclarecimentos sobre o funcionamento do campo calendário.validadeAposVencimento

· Seção 2.1: alterado de obrigatório para opcional o preenchimento dos campos logradouro, cidade, UF e CEP do campo “devedor” na criação de uma cobrança com vencimento.

· Seção 1.6.1: Excluído o trecho que erroneamente se referia a um

possível valor “0” no campo de valor EMV.

22/03/2021

2.3.0

· Seção 1.4: removidas notas de rodapé e adicionadas explicações para explicitar que a regra de formatação das chaves Pix segue as determinações constantes do Manual Operacional do DICT.

· Seção 1.6.3: removido o fragmento que indica a versão do

location.

· Seção 1.6.6: ajuste redacional para esclarecer que o código do município a ser informado pelo PSP do pagador deve corresponder à informação cadastral de endereço do usuário pagador.

· Seção 1.6.6.1: adicionado o campo modalidadeAlteracao no

objeto “valor” para Pix Cobrança para pagamentos imediatos.

· Seção 1.6.6.2: inseridos esclarecimentos sobre o comportamento da data de vencimento e da validade após vencimento em caso de fim de semana e de feriado para o usuário pagador.

· Seção 1.6.7: exemplo revisado: valor (EMV, opcional) retirado;

Ref.Label (txid) modificado (enfatiza que vale o payload da

cobrança); fragmento ‘v2’ (tornado opcional) retirado da location

(url da cobrança).

· Anexo III: inseridos esclarecimentos sobre o comportamento da data de vencimento em caso de fim de semana e de feriado para o usuário pagador e sobre os consequentes impactos nos campos que façam referência a esta data (validadeAposVencimento;

desconto; juros e multa).

22/07/2021

2.4.0

· Seção 1: Generalização de ‘celular’ para ‘dispositivo móvel’;

· Seção 1.2.2: Reforçando obrigatoriedade da chave;

· Seção 1.6.2. Nota de rodapé promovida para evidenciar reuso de QR Codes;

· Seção 1.6.3. Correção de fdqnPspRecebdor para fqdnPspRecebedor;

· Seção 1.6.6. Estruturando pontos de atenção;

· Seção 1.6.6.1: na descrição do campo valor, texto alterado para refletir que o campo segue a regex especificada na API Pix:

\d{1,10}\.\d{2};

· Seção 1.6.6.2: na descrição do campo valor, texto alterado para refletir que o campo segue a regex especificada na API Pix:

\d{1,10|\.\d{2}; corrigida a obrigatoriedade dos campos logradouro, cidade, uf e cep, pertencentes ao objeto `recebedor`. Estes campos estavam constando erroneamente como opcionais.

· Seção 1.6.6.2: Remoção da obrigatoriedade do calendario.validadeAposVencimento;

		· Seção 1.8: Inclusão de campos para o serviço de iniciação de transação de pagamento · Seção 2: Informações gerais sobre como mapear os campos do serviço de iniciação de transação de pagamento · Anexo III: Seção 2.1: Obrigatoriedade do campo calendario.validadeAposVencimento removida. · Anexo III: Seção 2.3.3.2: Definição da precisão a ser utilizada no cálculo do fator de juros
26/08/2021	2.5.0	· Seção 1: Esclarecimentos no texto · Seção 1.2 e 1.5: Inclusão do novo campo de FSS relativos ao Pix Saque no QR Estático · Seção 1.5.1: Inclusão de situação em que o campo fss é utilizado · Seção 1.6: Inclusão dos campos relativos ao Pix Saque e Pix Troco no QR Dinâmico · Seção 1.6.6.2: Adequação da descrição e da obrigatoriedade do campo calendario.validadeAposVencimento à especificação da API Pix · Seção 1.8: Alteração no quadro com as informações obrigatórias sobre iniciação através do serviço de iniciação de transação de pagamento · Seção 2: Inclusão dos campos nas mensagens de pagamento relativos ao Pix Saque e Pix Troco · Anexo I: Seção 1: Inclusão das funcionalidades relacionadas ao Pix Saque e ao Pix Troco dentre as contempladas pela API Pix · Anexo I: Seção 4: Inclusão da definição de FSS · Anexo I: Seção 5.4.2: Inclusão das funcionalidades obrigatórias por produto ofertado · Anexo III: Seção 2.1: Adequação da obrigatoriedade do campo calendario.validadeAposVencimento à especificação da API Pix · Anexo 4: Inclusão do cronograma de implementação das funcionalidades obrigatórias
17/09/2021	2.6.0	· Seção 2: Adequação das informações contidas nos campos das mensagens de pagamento e inclusão de orientações referentes a um Pix Saque via QR Code estático
29/10/2021	2.6.1	· Seção 1.6.1: Alteração de texto da nota de rodapé 35 sobre o código do município · Seção 1.6.6.1: Correção de AGTET para AGTEC · Seção 1.6.6.1: Adequação sobre o conteúdo do campo valor.retirada.troco. modalidadeAgente para o Pix Troco · Seção 1.6.6.2: Reforço da obrigatoriedade do campo calendario.validadeAposVencimento no retorno · Seção 1.8: Inclusão de campos para o serviço de iniciação de transação de pagamento

· Seção 2.3: Inclusão de campo do serviço de iniciação de transação de pagamento para pacs.008

09/12/2021

· Seção 1: Adequação das terminologias relacionadas ao Pix Saque e Pix Troco

· Seção 1.5.4, 1.6.6.1 e 2.2: Inclusão dos correspondentes bancários como agente de Saque (modalidade AGTOT)

30/08/2022

· Seção 1.5: Alteração na denominação do campo pss para fss no QR Code estático, com semântica equivalente

· Seções 1 e 2: Adequação das terminologias relacionadas ao Pix Saque e Pix Troco, em relação ao Facilitador de Serviço de Saque

· Seção 1.8: Alteração no quadro com as informações obrigatórias sobre iniciação através do serviço de iniciação de transação de pagamento, com adequação da data de obrigatoriedade da geração do código <EndToEndId> pelo iniciador e inclusão de informação sobre o codMun do usuário pagador

· Anexo III. Seção 2.1: Inseridos esclarecimentos sobre os campos valor e valor do desconto, na composição do valor da cobrança

· Anexo III. Seção 2.3.2: Ajuste no cálculo do valor do desconto, na cobrança com vencimento, podendo ser aplicado para datas menores ou iguais à data de vencimento, conforme especificação da API Pix.

Sumário

INICIAÇÃO DO PIX POR QR CODE……………………………………………………………………… 1
MAPEAMENTO PARA MENSAGENS ISO 20022…………………………………………………….. 25

ANEXO I – API PIX: CONCEITOS DE NEGÓCIO…………………………………………………………….. 30

INTRODUÇÃO…………………………………………………………………………………………….. 30
DOCUMENTAÇÃO DA API PIX…………………………………………………………………………. 30
CONTEXTO DA API PIX………………………………………………………………………………….. 31
CONCEITOS GERAIS……………………………………………………………………………………… 32
FUNCIONALIDADES DA API PIX……………………………………………………………………….. 33

CASOS DE USO 37

ANEXO II – API PIX: ESPECIFICAÇÃO TÉCNICA……………………………………………………………………………………………………………………….. 45

INTRODUÇÃO 45
PROTOCOLOS E TECNOLOGIAS 45
SEGURANÇA 45

ANEXO III – COBRANÇAS PARA PAGAMENTOS COM VENCIMENTO: CRIAÇÃO, ALTERAÇÃO E CÁLCULO……………………………………………………………………………………………………………………….. 48

INTRODUÇÃO 48
CRIANDO UMA COBRANÇA PARA PAGAMENTO COM VENCIMENTO 48
- ESTRUTURA PARA CRIAÇÃO E ATUALIZAÇÃO DE UMA COBRANÇA PARA PAGAMENTO COM VENCIMENTO 48
- CÁLCULO DO VALOR DA COBRANÇA 54

ANEXO IV – PRAZOS PARA IMPLEMENTAÇÃO DAS FUNCIONALIDADES……………………………………………………………………………………………………………………….. 63

INTRODUÇÃO 63

Iniciação do Pix por QR Code

O QR Code dinâmico e o QR Code estático, enquanto mecanismos para envio ou disponibilização prévia de informações para fins de iniciação de um Pix, seguirão o padrão do BR Code, nos termos do Manual do BR Code¹. Nesses casos, o usuário recebedor disponibiliza os dados de pagamento em um QR Code, para ser capturado por imagem pelo usuário pagador.

Podem atuar na emissão de QR Code o prestador de serviços de pagamento (PSP) do recebedor, a Secretaria do Tesouro Nacional (STN) e, em casos de uso específicos, órgãos do governo federal², enquanto usuários finais do Pix, desde que possuam contrato firmado com o BCB para fins de utilização do Sisbacen e que apresentem a certificação de segurança requerida para essa finalidade³.

O aplicativo do PSP do usuário pagador, que deve estar instalado em seu dispositivo móvel e que é utilizado para a leitura do QR Code, acessará o backend⁴ do PSP do pagador, que gera a ordem de pagamento.

Iniciação do Pix com EMV-MPM: Merchant Presented Mode

O BR Code adota o padrão EMV para uso de QR Codes em sistemas de pagamento (EMV-QRCPS), o qual consiste em dois casos de uso (modos) distintos: apresentado pelo recebedor (Merchant Presented Mode – MPM)⁵ ou apresentado pelo pagador (Consumer Presented Mode – CPM)⁶. O BR Code trata do caso EMV-MPM.

Tipos de QR Codes

QR Code Estático

O QR Code estático apresenta um rol de funcionalidades restrito. São apenas cinco opções de configuração. Primeiramente, o usuário do QR Code estático precisa necessariamente configurá-lo com uma chave válida no Diretório de Identificadores de Contas Transacionais (DICT), nos termos do Manual Operacional do DICT⁷. As outras quatro configurações são opcionais: i) identificador da

1 Disponível em <https://www.bcb.gov.br/estabilidadefinanceira/arranjosintegrantesspb>.

2 Exclusivamente para realizar recolhimentos relativos às suas atividades típicas.

3 Para fins de simplificação, doravante neste documento a expressão “PSP do recebedor” contemplará também a STN e os

órgãos do governo federal que poderão emitir QR Codes no âmbito do Pix.

4 O backend do PSP do pagador é o servidor do PSP do pagador que está conectado ao Sistema de Pagamentos Instantâneos (SPI) via interface ICOM na Rede do Sistema Financeiro Nacional. O aplicativo do PSP do pagador está conectado ao SPI indiretamente por meio desse servidor.

5 Disponível em <https://www.emvco.com/terms-of-use/?u=/wp-content/uploads/documents/ EMVCo-Merchant-Presented-QR-Specification-v1-1.pdf>.

6 Disponível em <https://www.emvco.com/terms-of-use/?u=/wp-content/uploads/documents/ EMVCo-Consumer-Presented-QR-Specification-v1-1.pdf>.

7 Um QR Code estático pode potencialmente ser gerado com uma chave inválida, mas será um QR Code inválido, de forma que nenhum leitor conseguirá processar o QR Code, porque não haverá como rotear o pagamento.

transação⁸, ii) campo de texto livre, iii) valor do pagamento, e iv) identificação do facilitador de serviço de saque. (NR)

QR Code Dinâmico

O QR Code dinâmico dispõe de um rol de funcionalidades abrangente, tais como conciliação via identificador da transação, configuração de valor e de campos livres estruturados⁹. O QR Code dinâmico também deve, necessariamente, ser configurado para apresentar uma chave do DICT.

A característica que define o QR Code dinâmico é sua flexibilidade. O QR Code dinâmico, em sua estrutura interna, é configurado com uma URL que é acessada no momento de sua leitura. Essa funcionalidade abre diversas possibilidades de uso, dado que as informações trazidas pela URL podem variar em função de diversos parâmetros.

A URL também cumpre o papel de reduzir a quantidade de dados codificados diretamente na imagem¹⁰. O QR Code dinâmico contém somente as informações básicas do usuário recebedor. O restante das informações é obtido em um webservice do PSP do recebedor, com base nessa URL.

Definições gerais em relação ao BR Code

Conforme especificado no Manual do BR Code, o Pix precisa definir seu GUI (identificador único do arranjo) para ser utilizado ao longo dos IDs raiz 26-51:

GUI do PIX	Valor	Tamanho
GUI – Globally Unique Identifier	br.gov.bcb.pix¹¹	14 caracteres

O Manual do BR Code apresenta a possibilidade de abrigar informações específicas do arranjo na faixa 26..51 e, como complemento, na faixa 80..99. A tabela abaixo apresenta a estrutura do Pix dentro dos campos extensíveis do BR Code.

ID	Nome EMV	Tamanho	Uso¹²	Descrição
26..5113	Merchant Account Information	23..99	M	“26” – indica arranjo específico; “00” (GUI) obrigatório:
				ID	Nome	Tam	Uso	Descrição
				00	GUI	14	M	br.gov.bcb.pix
				01..99	conforme PIX
	Unreserved Templates	23..99	O	ID	Nome	Tam	Uso	Descrição

8 O identificador da transação é uma informação que abre a possibilidade de conciliação para o usuário recebedor. O PSP do recebedor recebe essa informação no processo de liquidação do valor apresentado por meio do QR Code estático, por meio da mensagem pacs.002.

9 O PSP do recebedor pode configurar uma lista estruturada de campos livres. Essa funcionalidade possibilita uma apresentação de maior quantidade e qualidade de informações para o pagador no momento da confirmação de um pagamento.

10 Um QR Code com muitas informações pode dificultar ou inviabilizar a decodificação dos dados a partir da imagem, que se torna muito densa.

11 O GUI – DNS reverso – é case insensitive.

12 M – Mandatório; O – opcional.

13 O ID pode ser qualquer um dos identificadores dentro da faixa 26-51.

80..9914

GUI

br.gov.bcb.pix

01..99

conforme PIX

O detalhamento dos dados dos objetos tem interpretação específica definida nas seções a seguir, conforme os casos QR Code estático ou dinâmico, quando o GUI corresponder a br.gov.bcb.pix.

É importante ressaltar que o padrão BR Code possui outros campos nativos e opcionais, que podem ser utilizados na iniciação de pagamento. As possibilidades de mapeamento desses campos nativos EMV®, além dos campos específicos do arranjo proposto, para os dados de iniciação da ordem de pagamento que será emitida pelo PSP do pagador são apresentadas em seção específica neste Manual, em que se descreve o mapeamento dos dados de pagamento para mensagens ISO 20022.

Formatação das chaves do DICT no BR Code

A regra para formatação das chaves Pix no BR Code com trilho Pix segue estritamente as regras definidas no Manual Operacional do DICT.

E-mail

O e-mail será codificado no seguinte formato:

e-mail: [email protected]

CPF ou CNPJ

O CPF e o CNPJ serão codificados no seguinte formato: CPF: 12345678900

CNPJ: 00038166000105

Número de telefone celular

O telefone será codificado seguindo o formato internacional:

+5561912345678

Em que:

+55: código do país.

61: código do território ou estado. 912345678: número do telefone celular.

Chave aleatória

A chave aleatória será codificada juntamente com a pontuação, como segue: 123e4567-e12b-12d1-a456-426655440000

14 O ID pode ser qualquer um dos identificadores dentro da faixa 80-99.

Iniciação do Pix via QR Code Estático

O QR Code estático no Pix conterá o seguinte conjunto de informações:

*QR Code* Estático**
#	Campo	Tipo
1	Chave Pix	Obrigatório
2	Valor	BR Code ID5415
3	Conjunto livre de caracteres, com limite de tamanho (infoAdicional)	Opcional
4	Identificador da transação “TransactionIdentification <TxId>”	BR Code ID62-0516
5	Facilitador de serviço de saque (NR)	Opcional

O mapeamento para o QR Code gerado pelo recebedor, segundo o manual do BR Code, utiliza os campos a seguir:

ID	*Merchant Account Information*
26..51	ID	Nome	Tamanho	Uso	Descrição
	00	GUI	14	M	br.gov.bcb.pix
	01	chave	01..77 17	M	Chave Pix
	02	infoAdicional¹⁸	01..72 19	O	Conjunto livre de caracteres com limite de tamanho.
	03	fss	08	O	ISPB do facilitador de serviço de saque (NR)

Campos chave, infoAdicional e fss

O campo chave é limitado pelo tamanho máximo do template 26-51, conforme padronizado pela especificação EMV® para QR Codes: 99 caracteres. Mais especificamente, 77 caracteres quando os campos infoAdicional e fss não forem utilizados. Não é possível que os campos chave e infoAdicional cheguem simultaneamente a seus tamanhos máximos potenciais, menos ainda se também houver preenchimento do campo fss, uma vez que esse campo consome 12 (2+2+8) caracteres. Um exemplo ilustra melhor a situação. Supondo uma chave de tamanho 9, temos:

Identificador ID + indicador de tamanho da GUI: 4
Identificador ID + indicador de tamanho da chave: 4
Tamanho do valor no campo GUI: 14
Tamanho do valor no campo chave: 9
4 + 4 + 14 + 9 =

15 Transaction Amount.

16 Additional Data Field – Reference Label, sempre presente em um BRCode.

17 Máximo Chave: 99 – 8 (Identificador ID[2] + indicador de tamanho de GUI[2] + Identificador ID[2] + indicador do tamanho de chave[2]) – 14 (tamanho do valor em GUI): 77

18 Esse item será mostrado para o pagador no momento do rastreamento do QR. Pode servir, imagina-se, como uma pequena

“descrição” do item. O limite de caracteres é um fator limitador que deve ser levado em consideração.

19 Máx. Referência: 99 – 27 (GUI[4+14] + Chave Mínima[5] + ID[2] e tamanho do infoAdicional[2]): 72

Sobram, no exemplo acima, portanto, 68 caracteres para o campo texto livre (99 – 31 = 68), incluindo o ID ‘02’ e tamanho (2 caracteres) para o campo infoAdicional, restando, portanto, 64 caracteres de texto livre, no máximo. Se a chave fosse maior, menor seria o espaço destinado ao texto livre. Em outras palavras, os campos: chave, infoAdicional e fss disputam o espaço de 99 caracteres do ID raiz (na faixa 26-51).

Convém observar que no exemplo acima, se houver o uso do campo fss, retariam apenas 68 – 12 (identificador do campo fss[2] + indicador tamanho do campo [2] + valor do campo [8]) = 56 caracteres para o campo infoAdicional incluindo o ID e tamanho, ou seja, 56 – 4 = 52 caracteres para o valor em infoAdicional.

A presença do campo fss, com um ISPB válido junto às regras do arranjo Pix, no QR Code, indica que esse é um QR Code para Pix Saque. Não há funcionalidade de Pix Troco para QR Codes estáticos, apenas para QR Codes dinâmicos.

Identificador de transação: txid no QR Code estático

O objeto primitivo EMV 62-05 Reference Label, conforme especificado no manual do BR Code, é limitado a 25 caracteres e, quando em efeito²⁰, deve ser utilizado para conciliar pagamentos. Trata-se de um identificador de transação que deve ser retransmitido intacto pelo PSP do pagador ao gerar a ordem de pagamento. Essa informação permitirá ao recebedor identificar e correlacionar a transferência, quando recebida, com a apresentação das instruções ao pagador.

Os caracteres permitidos no contexto do Pix para o campo txid (EMV 62-05) são:

Letras minúsculas, de ‘a’ a ‘z’
Letras maiúsculas, de ‘A’ a ‘Z’
Dígitos decimais, de ‘0’ a ‘9’

Mapeamento 008

O mapeamento entre os dados de iniciação de pagamento apresentados pelo PSP do recebedor via QR Code (sejam campos nativos EMV/BR Code ou campos específicos do Pix) e as ordens de pagamento que devem ser geradas pelo PSP do pagador após a confirmação do usuário pagador são apresentados na seção Mapeamento para mensagens ISO 20022.

Exemplo de QR Code estático

No exemplo abaixo, define-se um Merchant Name (nome do recebedor) fictício, obrigatório no contexto EMV®/BR Code. O valor da transação não é fornecido. Portanto, ele deverá ser solicitado ao pagador. O campo BR Code 62-05 (ID da transação) não é utilizado. O campo 3-infoAdicionais (campo livre) não é utilizado. O campo fss também não é utilizado. O QR Code foi gerado com uma chave aleatória.

20 Conforme EMV QRCPS–MPM QR Codes for Payment Systems – Merchant Presented Mode, seção 4.8.1.2: “If present, the content of the data object value for IDs “01” to “08” shall be either “***” or a value defined by the merchant. The presence of “***” indicates that the mobile application is responsible for obtaining the necessary information”. Conclui-se que, se o gerador do QR optar por não utilizar um transactionID, o valor ‘***’ deverá ser usado para indicar essa escolha.

Nome do Recebedor : Fulano de Tal ²¹

Chave Pix : 123e4567-e12b-12d1-a456-426655440000

Valor : não informado

ID	Nome BR Code	Tam	Valor
00	Payload Format Indicator	02	01
26	Merchant Account Information22	58	ID	Nome	Tam	Valor
			00	GUI	14	br.gov.bcb.pix
			01	chave	36	123e4567-e12b-12d1-a456- 426655440000
52	Merchant Category Code	04	0000 (não informado)
53	Transaction Currency	03	986 (R$)
58	Country Code	02	BR
59	Merchant Name	13	Fulano de Tal
60	Merchant City	08	BRASILIA
62	Additional Data Field Template	07	ID	Nome	Tam	Valor
62	Additional Data Field Template	07	05	txid	03	*******
63	CRC1623	04	0x1D3D – incluindo “6304” (ID 63 e tamanho 04)

A sequência de caracteres correspondente ao payload do QR Code no padrão BR Code, grifada na tabela, fica evidenciada abaixo, com quebras de linha adicionais para favorecer a compreensão:

000201

2658

0014br.gov.bcb.pix

0136123e4567-e12b-12d1-a456-426655440000

52040000

5303986

5802BR

5913Fulano de Tal 6008BRASILIA

6207

0503***

63041D3D

O respectivo QR Code estático está abaixo:

21 O nome a apresentar ao pagador será necessariamente o nome retornado na consulta ao DICT. O MerchantName será ignorado pelo pagador.

22 Um ou mais campos Merchant Account Information (IDs 02 a 51) podem estar presentes no QR Code; identificando os diferentes arranjos de pagamento que podem ser utilizados.

23 Polinômio 0x1021, C.I. 0xFFFF. A ordem dos objetos modifica o CRC.

00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-426655440000

5204000053039865802BR5913Fulano de Tal6008BRASILIA62070503***63041D3D

O QR Code Estático na API Pix

O QR estático pode ser criado diretamente pela automação do usuário recebedor, ou por algum outro elemento de software em função dos parâmetros: valor, txid, chave Pix, infoAdicional e fss. A criação²⁴ do QR Code estático NÃO é uma funcionalidade que faz parte da API Pix.

Apesar de a criação do QR Code estático não fazer parte das funcionalidades da API Pix, os Pix recebidos que tenham sido iniciados via QR Codes estáticos que estejam associados a um txid podem ser consultados via API Pix. Maiores detalhes sobre essa funcionalidade podem ser encontrados no repositório oficial da API Pix no perfil do BCB no Github: https://github.com/bacen/pix-api.

Iniciação do Pix via QR Code Dinâmico

A API Pix

O QR Code dinâmico no Pix deve ser gerado pelo usuário recebedor por meio da API Pix, exceto no fluxo de geração de QR dinâmico via app mobile do PSP²⁵. A API Pix é uma API padronizada pelo BCB com o objetivo de facilitar o processo de integração ao arranjo Pix por parte das soluções de automação, ampliar a concorrência no setor e possibilitar menores custos aos usuários finais.

A versão vigente da API Pix contempla a especificação das funcionalidades e campos relativos aos casos de negócio focados em recebimento de pagamentos imediatos, a exemplo de pontos de venda em lojas físicas e de soluções para comércio eletrônico, ou com data de vencimento específica,

24 Ou, em outras palavras, a montagem da string específica que representa o QR Code, no Padrão BR Code, que segue o EMV para QR codes Merchant presented Mode, string esta que pode ser “renderizada” ou transformada visualmente como um QR code, está fora do escopo definido pela API Pix.

25 A API específica utilizada pelo aplicativo do PSP do recebedor para interagir com o backend do PSP do recebedor encontra- se fora do escopo deste documento.

incorporando ainda os cálculos referentes a descontos e abatimentos, juros e multas, quando aplicáveis. Na versão atual estão contempladas também a geração de cobranças imediatas com saque ou troco, quando a estrutura opcional valor.retirada estiver preenchida no payload. A API Pix continuará evoluindo para agregar novas funcionalidades.

A especificação e detalhamento da API Pix está disponível nos seguintes documentos:

Anexo I “API Pix – Definições de Negócio”;
Anexo II “API Pix: Especificação Técnica”;
Anexo III “Cobranças para pagamentos com vencimento: Criação, alteração e cálculo”; e
“Especificação Técnica Detalhada”, apresentada no formato OpenAPI 0, disponível em

https://github.com/bacen/pix-api

O QR Code dinâmico

O QR Code dinâmico conterá as seguintes informações:

*QR Code* Dinâmico**
#	Campo	Tipo
1	Valor	BR Code ID5426
2	Identificador da transação “TransactionIdentification <TxId>”	BR Code ID62-0527
3	Link URL	Obrigatório

O campo Link URL representa uma URL que será utilizada para recuperação dos dados que fazem parte do pagamento. O formato dessa URL, bem como os demais detalhes sobre segurança relacionados ao QR Code, está detalhado no Manual de Segurança do SFN.

Os campos Valor e Identificador da Transação (txid) não devem ser preenchidos no QR Code Dinâmico. Se preenchidos, seu conteúdo deve ser ignorado, prevalecendo sempre os campos obtidos através da URL (payload JSON).

Esses campos podem ter os mesmos valores do payload JSON²⁸, quando possível. No Pix, como um mesmo BR Code dinâmico pode ser reutilizado para vários pagamentos, valor e txid obtidos via URL podem mudar a cada transação. Assim, esses campos BR Code devem ser ignorados pelo pagador em

qualquer caso de uso de QR Code dinâmico.

O mapeamento do QR Code dinâmico para o padrão BR Code utiliza os campos a seguir:

ID	*Merchant Account Information*
26..51	ID	Nome	Tam	Uso	Descrição
26..51	00	GUI	14	M	br.gov.bcb.pix

²⁶ Transaction Amount

²⁷ Additional Data Field – Reference Label

²⁸ A consistência de campos entre múltiplos arranjos de pagamento com BR Code está fora do escopo desta especificação.

3-URL

01..77

Link para payload JSON

A URL hospedada no PSP do recebedor: “Location”

A URL presente no QR Code dinâmico, também chamada de “location”, não deve incluir prefixo de protocolo. O acesso deverá ser realizado após²⁹ validações³⁰, incluindo o domínio válido autorizado pelo PSP do recebedor para geração de QR Codes dinâmicos, exclusivamente via HTTPS³¹.

Além disto, a URL permitirá diferenciar os QR Codes dinâmicos associados a cobranças para pagamento imediato daqueles associados a pagamentos com vencimento, conforme exposto a seguir, observando-se a estrutura do fragmento “pixEndpoint”.

Respeitadas as regras de formação de URL³², a URL terá esse layout:

{fqdnPspRecebedor}/{pixEndpoint}/{pixUrlAccessToken}

Onde:

fqdnPspRecebedor: Fully Qualified Domain Name do Provedor de Serviços de Pagamento da ponta Recebedora.
pixEndpoint: será utilizado pelo PSP recebedor para organizar suas URLs, definir a versão da API Pix e definir o tipo de cobrança que está sendo Está estruturado da seguinte maneira:
- {endpointOpcional}/{fragmentoTipoCobrança}

Onde:

endpointOpcional: fragmento opcionalmente utilizado pelo PSP recebedor para fins de organização de URLs em um domínio. Por exemplo “/pix/123/”. Pode ser vazio;
fragmentoTipoCobrança: define o tipo de cobrança. Na presente versão, diferencia entre cobrança para pagamento imediato ou cobrança para pagamento com Quando vazio, significa que a cobrança é para pagamento imediato. Se apresentado o valor “/cobv/”, significa que se trata de uma cobrança com vencimento.

pixUrlAccessToken: fragmento que incorpora uma característica de segurança à location, tornando-a difícil de ser pressuposta³³.

O tamanho máximo da URL completa (sem o prefixo de protocolo) é de 77 caracteres.

Maiores informações a respeito de segurança e demais detalhes podem ser encontrados diretamente no Manual de Segurança do SFN.

URL do QR Code dinâmico

29 A URL obtida no campo #3 deve ser completamente avaliada quanto à presença de caracteres inválidos e suas partes constituintes (prefixo, domínio, aplicação e demais fragmentos) antes de qualquer tentativa de acesso.

30 Todos os campos da estrutura JSON associada ao acesso à URL, incluindo os opcionais, devem estar nulos e só devem ser preenchidos depois que o acesso for realizado e todas as verificações de segurança forem positivas.

31 Restrições adicionais de segurança e outros detalhes estão definidos do Manual de Segurança do SFN.

32 Ver <https://www.ietf.org/rfc/rfc3986.txt>.

33 Em outras palavras, torna a location uma “URL de capacidade”. Maiores informações sobre esta questão encontram-se no Manual de Segurança do SFN.

Qualquer PSP pode hospedar URLs de QR Codes dinâmicos em seus respectivos domínios.

O PSP que atua como participante responsável ou liquidante de outro participante do Pix pode ofertar ao PSP contratante o serviço de hospedagem de payloads de QR Codes dinâmicos.

Sobre cobranças concluídas

A critério do PSP recebedor, payloads que representem cobranças já concluídas, expiradas ou removidas podem retornar um http status que apresente semântica adequada³⁴.

O payload JSON

O payload JSON é o conteúdo recuperado a partir da chamada à URL, lida a partir do QR Code dinâmico (ou a partir do “Pix Copia e Cola”) e representa uma cobrança. A estrutura do payload JSON varia de acordo com o tipo de cobrança associada ao QR Code, seja ela para pagamentos imediatos ou para pagamentos com vencimento.

No caso da cobrança para pagamento imediato, o PSP do pagador irá acessar a URL, não havendo necessidade de envio de parâmetros. O PSP do recebedor devolve diretamente no payload os dados relativos à cobrança para pagamento.

No caso da cobrança referente a pagamento com vencimento, o PSP do pagador irá acessar a URL e enviar a informação do código do município³⁵ (codMun) do usuário pagador e a Data de Pagamento Pretendida (DPP). Estas informações são importantes para que o PSP do recebedor possa calcular corretamente o valor a ser pago, considerando feriados estaduais e municipais que possam impactar o valor da cobrança. A informação referente ao código do município do usuário pagador poderá não ser enviada somente nas hipóteses em que, em decorrência de regulamentação específica relativa ao tipo de conta do usuário final, o PSP do pagador não possuir esta informação.

Pontos de atenção:

Caso a informação referente ao município não seja enviada; o PSP do recebedor assumirá que não existem feriados estaduais e municipais no período em questão;
Caso a informação referente à Data de Pagamento Pretendida (DPP) não seja enviada; o PSP do recebedor procederá da seguinte forma para o cálculo da cobrança:
- Cobrança não está vencida (data da consulta é menor ou igual à data de vencimento da cobrança): PSP do recebedor deve assumir a data de vencimento como a Data de Pagamento Pretendida; ou
- Cobrança está vencida (data da consulta é posterior à data de vencimento da cobrança): PSP do recebedor deve assumir a data da consulta como a Data de Pagamento Pretendida (DPP).

34 Por exemplo, o PSP recebedor pode optar por retornar o HTTP status 410 ‘gone’ ou ainda 404 ‘not found’.

35 Esta informação corresponde ao município que consta na informação cadastral de endereço do usuário pagador, baseado na Tabela de Códigos de Municípios do IBGE, que apresenta a lista dos municípios brasileiros associados a um código composto por 7 dígitos, sendo os dois primeiros referentes ao código da Unidade da Federação.

Para mais detalhes técnicos, consultar a documentação da API Pix³⁶.

O aplicativo do PSP do pagador utilizará as informações contidas no payload JSON para apresentar os elementos da cobrança ao usuário pagador.

Payload para cobrança para pagamentos imediatos

A estrutura do payload JSON para cobranças para pagamento imediato é a seguinte:

#	Campo	Mult.	Nome Campo JSON	Tipo	OU
1	Revisão da cobrança	[1..1]	revisao	Number
2.1	Timestamp de criação da cobrança associada ao QR Code	[1..1]	calendario.criacao	String
2.2	Timestamp de apresentação da cobrança associada ao QR Code	[1..1]	calendario.apresentacao	String
2.3	Expiração da cobrança associada ao QR Code em segundos	[0..1]	calendario.expiracao	Number
3.1	CPF do usuário devedor	[0..1]	devedor.cpf	String	OU(
3.2	CNPJ do usuário devedor	[0..1]	devedor.cnpj	String	)
3.3	Nome do usuário devedor	[0..1]	devedor.nome	String
4.1	Valor original do documento	[1..1]	valor.original	String
4.2	Modalidade de alteração de valor	[0..1]	valor.modalidadeAlteracao	Number
4.3.1	Valor do saque	[0..1]	valor.retirada.saque.valor	String	OU( saque
4.3.2	Modalidade de alteração de valor do saque	[0..1]	valor.retirada.saque.modalidadeA lteracao	Number	saque
4.3.3	ISPB do facilitador de serviço de saque (NR)	[0..1]	valor.retirada.saque.prestadorDo ServicoDeSaque	String	saque
4.3.4	Modalidade do agente	[0..1]	valor.retirada.saque.modalidadeA gente	String	saque
4.4.1	Valor do troco	[0..1]	valor.retirada.troco.valor	String	troco
4.4.2	Modalidade de alteração de valor do troco	[0..1]	valor.retirada.troco.modalidadeA lteracao	Number	troco
4.4.3	ISPB do facilitador de serviço de saque (NR)	[0..1]	valor.retirada.troco.prestadorDo ServicoDeSaque	String	troco
4.4.4	Modalidade do agente	[0..1]	valor.retirada.troco.modalidadeA gente	String	troco )
5	Chave Pix do recebedor	[1..1]	chave	String
6	Identificador da transação	[1..1]	txid	String
7	Solicitação ao Pagador	[0..1]	solicitacaoPagador	String
8	Conjunto livre de caracteres, com limite de tamanho	[0..1]	infoAdicionais	Array[InfoAdicional]
9	Assinatura	[1..1]	–	<JWS Signature>³⁷
10	Situação da cobrança	[1..1]	status	String

36 Disponível em <https://github.com/bacen/pix-api>.

37 Detalhes de segurança estão definidos no Manual de Segurança do SFN.

A seguir, apresenta-se uma breve explanação sobre os principais aspectos dos campos listados no

payload acima. Para maiores detalhes técnicos, a API Pix é a referência indicada³⁸.

Revisão

O tipo do campo revisao é um número, começando em zero e que varia em acréscimos de 1.

O campo revisao adiciona rastreabilidade ao payload. Uma vez que se recomenda que o payload assinado seja armazenado pelo PSP do pagador em seus registros, fica facilitada a comunicação entre PSPs acerca de qual payload especificamente está se tratando, no contexto de resolução de possíveis problemas.

Adicionalmente, via API Pix³⁹, é possível acessar as revisões anteriores da cobrança.

O campo revisao deve ser incrementado somente quando forem realizadas alterações na cobrança, via endpoints PATCH ou PUT, conforme especificados na API Pix.

Calendário

Os campos aninhados sob o identificador calendario organizam informações a respeito de controle de tempo da cobrança. Os campos criacao, expiracao e apresentacao, definem elementos temporais do payload. Os campos criacao e apresentacao (timestamps) devem usar como base o tempo conforme entendido pelo PSP do recebedor. Todos os timestamps devem respeitar UTC⁴⁰. O campo expiração é um inteiro apresentado em segundos.

Expostas estas explicações, segue uma descrição detalhada de cada campo do objeto calendário:

criacao: [obrigatório] timestamp que indica o momento em que foi criada a cobrança. Respeita o formato definido na RFC 3339.
apresentacao: [obrigatório] timestamp que indica o momento em que o payload JSON que representa a cobrança foi recuperado. Ou seja, idealmente, é o momento em que o usuário realizou a captura do QR Code para verificar os dados de pagamento. Respeita o formato definido na RFC 3339.
expiracao: [opcional – default 86400] duração que indica limite, com granularidade de segundos, para que o pagamento da cobrança possa ser realizado, a partir da data-hora de criação. Se não for informado, assume-se a duração de 86400 segundos, que corresponde a 24 horas. Exemplo: 3600 (indica validade de 1 hora).

Devedor

Os campos aninhados sob o objeto devedor são opcionais na cobrança para pagamentos imediatos e identificam a pessoa ou a instituição a quem a cobrança está endereçada. Não identifica,

38 Disponível em <https://github.com/bacen/pix-api>

39 Disponível em <https://github.com/bacen/pix-api>

40 UTC: Coordinated Universal Time. Mais detalhes em <https://en.wikipedia.org/wiki/Coordinated_Universal_Time>.

necessariamente, quem irá efetivamente realizar o pagamento. Em outras palavras, o CPF/CNPJ do devedor não é necessariamente o mesmo do CPF/CNPJ do pagador.

Apresenta-se, a seguir, a descrição detalhada de cada campo do objeto devedor:

cpf: [opcional] determina o CPF do devedor.
cnpj: [opcional] determina o CNPJ do devedor.
nome: [opcional] nome da instituição ou pessoa a quem a cobrança está endereçada. O preenchimento do campo devedor.nome é obrigatório se o campo devedor.cpf ou o campo devedor.cnpj estiver preenchido.

Valor

O objeto valor organiza os elementos que compõem o valor da cobrança. No caso da cobrança para pagamento imediato, são os seguintes os campos do objeto valor:

original: [obrigatório] valor do documento para cobrança para pagamento imediato. Este campo obedece às seguintes restrições:
- Para cobranças imediatas que não envolvam saque ou troco: deve apresentar valores maiores do que zero, exceto no caso de o campo modalidadeAlteracao apresentar valor 1;
- Para cobranças imediatas que representem um saque: deve apresentar o valor

0.00 (zero). O valor do saque será preenchido no campo

‘valor.retirada.saque.valor’;

Para cobranças imediatas que sejam com troco: deve apresentar necessariamente valor maior que 0.00 (zero) referente à compra; o valor do troco será preenchido no campo ‘retirada.troco.valor’.

modalidadeAlteracao: [opcional] indica a modalidade de alteração aplicada para a cobrança em questão. Se ausente, assume-se que a modalidade aplicada é a modalidade 0, que significa que não se pode alterar o valor da cobrança. Caso o campo valor.modalidadeAlteracao apresente o valor 1, então o usuário pagador poderá alterar o valor da cobrança. Ainda no caso de o campo valor.modalidadeAlteracao apresentar o valor 1, o campo valor.original pode funcionar como um “valor sugerido”, de forma que, caso o “valor sugerido” atribuído seja zero, o usuário pagador será obrigado a digitar um valor válido, ou seja, um valor maior que zero⁴¹.
retirada.saque: [opcional] indica o valor do saque a ser realizado, no campo valor.retirada.saque.valor e, se é possível ou não sua modificação pelo usuário quando da leitura do QR Code, no campo valor.retirada.saque.modalidadeAlteracao. O campo valor.retirada.saque.modalidadeAlteracao admite dois valores: 0 (zero) quando a alteração não for permitida ou 1 (um) quando a alteração for permitida; na ausência do campo nesta estrutura considera-se que

41 O PSP do pagador não deve permitir a confirmação de um pagamento cuja soma do valor.original + (valor.retirada.saque.valor[se existir] ou valor.retirada.troco.valor[se existir]) seja zero.

valor.retirada.saque.modalidadeAlteracao assume o valor 0 (zero). Convém observar que a estrutura valor.retirada.saque é opcional mas, uma vez preenchida (valor ou modalidade), as regras seguintes se aplicam:

É obrigatório o preenchimento dos campos:
- retirada.saque.modalidadeAgente: indica a modalidade do agente por meio da qual se dá a facilitação do serviço de saque, quais sejam, via estabelecimento comercial (AGTEC), outra espécie de pessoa jurídica que tenha como atividade principal ou secundária a prestação de serviços auxiliares a serviços financeiros ou afins ou correspondente no País (AGTOT) ou diretamente pelo facilitador de serviço de saque (AGPSS⁴²), conforme especificado na API; (NR)
- retirada.saque.prestadorDoServicoDeSaque:

indica o ISPB do facilitador de serviço de saque. (NR)

O valor em original deve ser sempre igual a 0.00 (zero);
O valor em modalidadeAlteracao deve ser sempre igual a 0 (zero)

– sem possibilidade de alteração – explicitamente, ou implicitamente 0 (zero) quando não preenchido;

O campo retirada.saque.valor:
- Deve ser maior que 00 (zero) se valor.retirada.saque.modalidadeAlteracao for 0 (zero). Neste cenário o usuário não pode alterar o valor.retirada.saque.valor informado no QR Code, portanto ele deve ser indicado previamente;
- Pode ser 00 (zero) se valor.retirada.saque.modalidadeAlteracao for 1, ou ter um valor preenchido diferente de 0.00 (zero) que serve como valor sugerido inicial de saque e pode ser alterado pelo usuário, assim como explicado para o campo valor.original. A restrição da app mobile de evitar preenchimento com 0.00 (zero) continua não permitindo saques com valor 0.00 (zero).
retirada.troco: [opcional] que indica o valor do troco a ser realizado, no campo valor.retirada.troco.valor e, se é possível ou não sua modificação pelo usuário quando da leitura do QR Code, no campo valor.retirada.troco.modalidadeAlteracao. O campo valor.retirada.troco.modalidadeAlteracao admite dois valores: 0 (zero) quando a alteração não for permitida ou 1 (um) quando a alteração for permitida; na ausência do campo nesta estrutura considera-se que valor.retirada.troco.modalidadeAlteracao assume o valor 0 (zero). Convém observar que a estrutura valor.retirada.troco é opcional mas, uma vez preenchida (valor ou modalidade), as regras seguintes se aplicam:
- É obrigatório o preenchimento dos campos:
  - retirada.troco.modalidadeAgente: indica a modalidade do agente por meio da qual se dá a facilitação do serviço de

⁴² Observação: no mapeamento para o campo ‘modalidadeAgente’, da pacs.008, esse valor deve ser substituído por AGFSS

saque; no caso do Pix Troco, estará sempre restrita ao estabelecimento comercial (AGTEC) ou ao correspondente no País (AGTOT), conforme especificado na API Pix; (NR)

retirada.troco.prestadorDoServicoDeSaque:

indica o ISPB do facilitador de serviço de saque. (NR)

O valor em original deve ser sempre maior que 0.00 (zero);
O valor em modalidadeAlteracao deve ser sempre igual a 0 (zero)

– sem possibilidade de alteração – explicitamente ou implicitamente 0 (zero) quando não preenchido;

O campo retirada.troco.valor:
- Deve ser maior que 00 (zero) se valor.retirada.troco.modalidadeAlteracao for 0 (zero). Neste cenário, o usuário não pode alterar o valor.retirada.troco.valor informado no QR Code, portanto ele deve ser indicado previamente;
- Pode ser 00 (zero) se valor.retirada.troco.modalidadeAlteracao for 1, ou ter um valor preenchido diferente de 0.00 (zero) que serve como sugestão inicial e pode ser alterado pelo usuário assim como explicado para o campo valor.original. A restrição da app mobile de evitar preenchimento com 0.00 (zero) continua, não permitindo trocos com valor 0.00 (zero).

Sobre as estruturas valor.retirada.saque e valor.retirada.troco não é possível que ambas sejam fornecidas em conjunto, são estruturalmente e mutuamente excludentes, quando há “saque” não há “troco” e vice-versa.

Todos os campos que indicam valores monetários obedecem ao pattern ou regex \d{1,10}\.\d{2}. Exemplos de valores aderentes ao padrão seriam: “0.00”, “1.00”, “123.99”, “123456789.23”.

Em síntese:

Valor

original

modalidade Alteracao

Retirada

Saque

Troco

valor

modalidade

Alteracao

valor

modalidade

Alteracao

Pix Cobrança para pagamento imediato

Com alteração de valor da cobrança /

compra

0 ou valor sugerido

–

Sem alteração de valor da cobrança /

compra

Valor da cobrança ou compra

–

Pix Saque

Com alteração do valor do

saque

0 ou valor sugerido

do saque

–

Sem alteração do valor do

saque

Valor do saque

–

Pix Troco (não admite alteração de valor da compra)

Com alteração do valor do

troco

Valor da compra

–

0 ou valor sugerido

do troco

Sem alteração do valor do

troco

Valor da compra

–

Valor do troco

Convém observar que na estrutura da tabela acima, por simplicidade, os campos

modalidadeAgente e prestadorDoServicoDeSaque, que são obrigatórios, foram omitidos.

Chave

O campo chave [obrigatório] determina a chave Pix registrada no DICT que será utilizada para a cobrança. Essa chave será lida pelo aplicativo do PSP do pagador para consulta ao DICT, que retornará a informação que identificará o recebedor da cobrança.

txid

O campo txid [obrigatório] determina o identificador da transação. O objetivo desse campo é ser um elemento que possibilite ao PSP do recebedor apresentar ao usuário recebedor a funcionalidade de conciliação de pagamentos (possibilitando associar a transação Pix à cobrança correlata).

Na pacs.008, é referenciado como TransactionIdentification <TxId> ou idConciliacaoRecebedor. O campo txid, no caso do QR Dinâmico, deve ter, no mínimo, 26 caracteres e, no máximo, 35 caracteres.

Em termos de fluxo de funcionamento, o txid é lido pelo aplicativo do PSP do pagador e, depois de confirmado o pagamento, se o usuário recebedor tem conta em outro PSP, é enviado para o SPI via pacs.008. Por sua vez, o SPI envia uma pacs.008 ao PSP do recebedor, contendo, além de todas as informações usuais do pagamento, o txid. Ao receber uma mensagem com o campo txid preenchido, o PSP do recebedor está apto a se comunicar com o usuário recebedor, informando que um pagamento específico foi liquidado.

O txid, no contexto da API Pix, é criado pelo usuário recebedor e encontra-se sob sua responsabilidade⁴³. O txid, no contexto de representação de uma cobrança, seja ela para pagamento imediato ou com vencimento, é único por CPF/CNPJ do usuário recebedor e PSP. Cabe ao PSP do recebedor validar essa regra na API Pix.

Mais informações sobre o campo txid podem ser encontradas no Anexo I (“API Pix: Conceitos de Negócio”, seção 4).

Solicitação ao Pagador

⁴³ No caso das cobranças para pagamento imediato, a criação do txid poderá ser delegada ao PSP do pagador.

O campo solicitacaoPagador [opcional] determina um texto a ser apresentado ao pagador para que este possa digitar uma informação correlata, em formato livre, a ser enviada ao usuário recebedor. Esta informação correlata⁴⁴ será preenchida, na pacs.008, pelo PSP do pagador, no campo RemittanceInformation <RmtInf>. O tamanho do campo <RmtInf> na pacs.008 está limitado a 140 caracteres.

Informações Adicionais

O campo infoAdicionais, se estiver presente, se refere a uma lista em que cada elemento deve utilizar o esquema abaixo:

Subcampo JSON

(infoAdicionais)

Presença

Tipo JSON

Propósito

nome

Obrigatório

String

Nome do campo

valor

Obrigatório

String

Dados do campo

Os limites relativos ao tamanho de cada campo e à quantidade de elementos da lista estão tratados na especificação da API Pix⁴⁵.

Cada respectiva informação adicional contida na lista (nome e valor) deve ser apresentada ao pagador. Exemplo: campo infoAdicionais no JWSPayload:

infoAdicionais[0].nome: “campo1” infoAdicionais[0].valor: “informação adicional 01” infoAdicionais[1].nome: “campo2” infoAdicionais[1].valor: “informação adicional 02”...

Assinatura

Todos os campos, excluído o campo assinatura, compõem um payload JSON assinado. Maiores detalhes sobre a assinatura desse payload JSON podem ser encontrados no Manual de Segurança do SFN.

Status

O campo status representa a situação da cobrança para pagamentos imediatos, podendo assumir os seguintes estados: “ATIVA”, “CONCLUIDA”, “REMOVIDA_PELO_USUARIO_RECEBEDOR”, “REMOVIDA_PELO_PSP”

Payload para cobrança para pagamentos com vencimento

Quando o PSP do pagador, por meio da URL encaminhada no QR Code dinâmico, também chamada de

“location”, ou no “Pix Copia e Cola”, acessa o payload de uma cobrança para pagamentos com

44 Importante destacar que é a informação correlata digitada livremente pelo pagador que é enviada na pacs.008, e não o texto apresentado no campo solicitacaoPagador.

45 Disponível em <https://github.com/bacen/pix-api>.

vencimento, ele dá início ao cálculo do valor da cobrança pelo PSP do recebedor, que enviará os campos do payload devidamente preenchidos.

É importante notar que se a obrigação não estiver vencida e o PSP do pagador não enviar a data desejada, o PSP do recebedor irá assumir a data de vencimento como a data a ser utilizada no cálculo do valor a ser pago.

Por outro lado, se a obrigação já estiver vencida e o PSP do pagador não enviar a data desejada, o PSP do recebedor irá assumir a data da consulta como aquela a ser utilizada no cálculo do valor a ser pago.

Vale lembrar que cabe ao PSP do pagador enviar o código do município do pagador, a fim de que o PSP do recebedor possa calcular corretamente o valor a ser pago, considerando feriados estaduais e municipais aplicáveis. Nas hipóteses em que o PSP do pagador não possuir essa informação e, portanto, não a enviar (naqueles casos em que a regulação não exige que o PSP do pagador tenha, em seu cadastro, o endereço do usuário pagador), o PSP do recebedor assumirá que não existem feriados estaduais e municipais no período em questão. Para mais detalhes técnicos, consultar a documentação da API Pix⁴⁶.

A estrutura do payload JSON para cobranças para pagamentos com vencimento é:

#	Campo	Mult.	Nome Campo JSON	Tipo	OU
1	Revisão da cobrança	[1..1]	revisão	Number
2.1	Timestamp de criação da cobrança associada ao QR Code	[1..1]	calendario.criacao	String
2.2	Timestamp de apresentação da cobrança associada ao QR Code	[1..1]	calendario.apresentacao	String
2.3	Data de vencimento do pagamento	[1..1]	calendario.dataDeVencimento	String
2.4	Validade da cobrança após vencimento em dias corridos	[1..1]	calendario.validadeAposVencimento	Number
3.1	CPF do usuário devedor	[0..1]	devedor.cpf	String	OU(
3.2	CNPJ do usuário devedor	[0..1]	devedor.cnpj	String	)
3.3	Nome do usuário devedor	[1..1]	devedor.nome	String
4.1	Valor original do documento	[0..1]	valor.original	String
4.2	Valor do abatimento	[0..1]	valor.abatimento	String
4.3	Valor dos descontos	[0..1]	valor.desconto	String
4.4	Valor dos juros	[0..1]	valor.juros	String
4.5	Valor da multa	[0..1]	valor.multa	String
4.6	Valor final do documento	[1..1]	valor.final	String
5	Chave Pix do recebedor	[1..1]	chave	String
6.1	CPF do recebedor	[0..1]	recebedor.cpf	String	OU(
6.2	CNPJ do recebedor	[0..1]	recebedor.cnpj	String	)

46 Disponível em <https://github.com/bacen/pix-api>.

6.3	Nome ou razão social do recebedor	[1..1]	recebedor.nome	String
6.4	Nome de fantasia do recebedor	[0..1]	recebedor.nomeFantasia	String
6.5	Logradouro do recebedor	[1..1]	recebedor.logradouro	String
6.6	Cidade do recebedor	[1..1]	recebedor.cidade	String
6.7	Unidade da federação do recebedor	[1..1]	recebedor.uf	String
6.8	CEP do recebedor	[1..1]	recebedor.cep	String
7	Identificador da transação	[1..1]	txid	String
8	Solicitação ao Pagador	[0..1]	solicitacaoPagador	String
9	Conjunto livre de caracteres, com limite de tamanho	[0..1]	infoAdicionais	Array[InfoAdicional]
10	Assinatura	[1..1]	–	<JWS Signature>⁴⁷
11	Situação da cobrança	[1..1]	status	String

A seguir apresenta-se uma breve explanação sobre os campos do payload de cobranças para pagamentos com vencimento que não são utilizados na cobrança para pagamentos imediatos ou cuja explicação precise ser adequada para o contexto das cobranças para pagamentos com vencimento. Para maiores detalhes técnico, a API Pix é a referência indicada⁴⁸.

Calendário

Campos do objeto calendário:

criacao: idem à cobrança para pagamentos imediatos;
apresentacao: idem à cobrança para pagamentos imediatos;
dataDeVencimento: [obrigatório] trata-se de uma data, no formato ‘yyyy-mm-dd’, segundo ISO 8601. É a data de vencimento da cobrança, que pode ser paga em qualquer horário do dia. Exemplo: 2020-10-19⁴⁹;
validadeAposVencimento: [obrigatório] (int32) Trata-se da quantidade de dias corridos após calendario.dataDeVencimento em que a cobrança poderá ser paga. Aplica-se o valor deste campo sobre o vencimento original da cobrança acrescentando-se o número de dias corridos nos quais a cobrança ainda poderá ser paga, após vencida⁵⁰.

Devedor

47 Detalhes de segurança estão definidos no Manual de Segurança do SFN.

⁴⁸ Disponível em <https://github.com/bacen/pix-api>

⁴⁹ Sempre que a data de vencimento cair em um fim de semana ou em um feriado para o usuário pagador, ela deve ser automaticamente prorrogada para o primeiro dia útil subsequente.

⁵⁰ Sempre que a data de validade após o vencimento cair em um fim de semana ou em um feriado para o usuário pagador, ela deve ser automaticamente prorrogada para o primeiro dia útil subsequente.

Diferentemente da cobrança para pagamentos imediatos, no caso de uma cobrança para pagamentos com vencimento, o objeto devedor é obrigatório. As demais observações sobre o objeto e seus campos permanecem válidas.

Valor

O objeto valor organiza os elementos que compõem o valor da cobrança: juros, multa, desconto, abatimento, entre outros elementos correlatos.

Apresenta-se, a seguir, a descrição detalhada de cada campo do objeto valor:

original: [opcional] valor original do documento, antes de possíveis multas, juros, descontos ou abatimentos.
abatimento: [opcional] valor do abatimento aplicado à cobrança. Não será enviado se for igual a 0 (zero);

o valor.desconto: [opcional] valor do desconto aplicado à cobrança em virtude de pagamento antecipado. Não será enviado se for igual a 0 (zero);

juros: [opcional] valor dos juros aplicados à cobrança em atraso. Não será enviado se for igual a 0 (zero);
multa: [opcional] valor da multa aplicada à cobrança em atraso. Não será enviado se for igual a 0 (zero);
final: [obrigatório] valor final da cobrança, considerados abatimentos, desconto, juros e multa. Ressalvado o campo original, se todos os demais campos estiverem zerados, o App do PSP do pagador deve exibir apenas o campo final.

Recebedor

O objeto Recebedor organiza as informações sobre o credor da cobrança. Apresenta-se, a seguir, a descrição detalhada de cada campo do objeto Recebedor:

cpf: CPF do recebedor, se pessoa natural, conforme cadastro da conta transacional associada à chave Pix.

o recebedor.cnpj: CNPJ do recebedor, se ele estiver inscrito no Cadastro Nacional da Pessoa Jurídica, mantido junto à Receita Federal, conforme cadastro da conta transacional associada à chave Pix. Se este campo estiver preenchido, o campo recebedor.cpf não deverá ser preenchido.

nome: [obrigatório] nome ou razão social do recebedor, conforme cadastro da conta transacional associada à chave Pix.
nomeFantasia: [opcional] nome fantasia, no caso de recebedor inscrito no Cadastro Nacional da Pessoa Jurídica, conforme cadastro da conta transacional associada à chave Pix.

logradouro: [obrigatório] logradouro do recebedor, conforme cadastro da conta transacional associada à chave Pix;
cidade: [obrigatório] cidade do recebedor, conforme cadastro da conta transacional associada à chave Pix;
uf: [obrigatório] unidade da federação (estado ou DF) do recebedor, conforme cadastrado na conta transacional associada à chave Pix;

o recebedor.cep: [obrigatório] Código de endereçamento postal (CEP) do recebedor, conforme cadastrado na conta transacional associada à chave Pix.

Exemplo de QR Code Dinâmico

No exemplo abaixo, para uma cobrança para pagamentos imediatos, define-se um Merchant Name (nome do recebedor) fictício, obrigatório no contexto do BR Code. O valor da transação deve ser obtido no payload da cobrança. A URL deverá ser validada e consultada após a leitura do QR Code para apresentar ao pagador as informações completas do beneficiário e o contexto do pagamento. O campo BR Code 01 (Point of Initiation Method), opcional, está presente para indicar que não deve ser iniciado mais de um pagamento com este mesmo QR Code.

Nome EMV do recebedor ⁵¹ : Fulano de Tal Valor : R$ 123,45

URL do PSP do recebedor : pix.example.com/8b3da2f39a4140d1a91abd93113bd441

ID	Nome EMV	Tam	Valor
00	Payload Format Indicator	02	01
01	Point of Initiation Method	02	12 (não deve ser utilizado mais de uma vez) ⁵²
26	Merchant Account Information	70	ID	Nome	Tam	Valor
			00	GUI	14	br.gov.bcb.pix
			25	URL	48	pix.example.com/8b3da2f39a41 40d1a91abd93113bd441
52	Merchant Category Code	04	0000 (não informado)
53	Transaction Currency	03	986 (R$)
58	Country Code	02	BR
59	Merchant Name	13	Fulano de Tal
60	Merchant City	08	BRASILIA
62	Additional Data Field	07	ID	Nome	Tam	Valor
62	Additional Data Field	07	05	Reference Label	03	***
63	CRC16	04	0x64E4

51 O nome que deve ser apresentado ao pagador é o nome do usuário recebedor conforme registrado no DICT.

52 Favorece melhor controle da experiência do usuário, evitando tentar a iniciação de pagamento de um QR Code que já foi processado com sucesso (por exemplo, baseado em Instituição e Reference Label), evitando assim acesso à URL e o envio de mensagens desnecessárias (que serão provavelmente rejeitadas).

A sequência de caracteres correspondente ao payload do QR Code dinâmico no padrão BR Code gerado pelo recebedor, grifada na tabela, fica evidenciada abaixo:

000201

010212

2670

0014br.gov.bcb.pix 2548pix.example.com/8b3da2f39a4140d1a91abd93113bd441

52040000

5303986

5802BR

5913Fulano de Tal 6008BRASILIA

6207

0503***

630464E4

O respectivo QR Code dinâmico está abaixo:

00020101021226700014br.gov.bcb.pix2548pix.example.com/8b3da2f39a4140d1a91abd93113bd44 15204000053039865802BR5913Fulano de Tal6008BRASILIA62070503***630464E4

Recupera-se a URL do payload JSON com os dados do pagamento:

pix.example.com/8b3da2f39a4140d1a91abd93113bd441

Verificado o domínio “example.com” como autorizado⁵³ e obtida a chave pública de assinatura (PSPRECPUBKEY), recupera-se o payload JSON:

HTTPS Request: https://pix.example.com/8b3da2f39a4140d1a91abd93113bd441

⁵³ Conforme Manual de Segurança do SFN.

HTTPS Response:

JWSHeader.JWSPayload.JWSSignature

Se (e somente se) JWS-AssinaturaVálida⁵⁴ (JWSHeader, JWSPayload, JWSSignature, PSPRECPUBKEY), procede-se ao parsing dos dados da estrutura JSON:

JSONPayload = base64url⁵⁵-decode (JWSPayload).

Um exemplo de payload JSON pode ser encontrado na API Pix⁵⁶ Exemplo de apresentação para confirmação do Pagador:

PAGAMENTO – 31/03/2020 15:20:30

** ATENÇÃO – Verifique os dados do pagamento **

Valor : R$ 123,45

Obtido por consulta ao DICT pela chave do recebedor:

4b7b4eb3-d426-48f1-8ecf-998bda62c0a1

Para : FULANO DE TAL EIRELI

CNPJ 00.123.456/7891-23

Expira em: 31/03/2020 17:00:0057

Detalhes do Pagamento: Informação Adicional do PSP do Recebedor

Confirma?

O QR Code Dinâmico na API Pix

O QR Code Dinâmico, em um contexto de integração automatizada⁵⁸, não pode ser criado diretamente pelo usuário recebedor. É preciso que o usuário recebedor, em seu software de automação comercial

/ TEF / Gateway configure o endpoint⁵⁹ que será responsável por retornar as informações relativas à cobrança que o QR Code Dinâmico busca representar. A API Pix não monta a string para a renderização do QR Code nem retorna um arquivo com o QR Code gerado; desta forma, estas funcionalidades poderão ser ofertadas pelo PSP do recebedor ou providas diretamente pela solução de automação comercial adotada pelo usuário recebedor ou ainda via outro elemento de software.

Para maiores informações a respeito da dinâmica de gerenciamento de cobranças, pode-se consultar a API Pix⁶⁰.

Pix Copia e Cola

Eventualmente, em cenários de iniciação de um Pix, ler o QR Code pode ser impraticável, como, por exemplo, navegar em uma loja online via web browser mobile, comprar em aplicativos instalados no

⁵⁴ Conforme Manual de Segurança do SFN.

⁵⁵ RFC 4648, disponível em <https://tools.ietf.org/html/rfc4648>. base64url corresponde à codificação base64 alterada para

evitar o uso de “+”, “/” e “=”, pois esses caracteres causariam efeitos adversos em URLs.

⁵⁶ https://github.com/bacen/pix-api

⁵⁷ Note-se que o payload utiliza UTC.

58 Em outras palavras, fora do cenário de criação do QR Dinâmico por meio do aplicativo do PSP recebedor.

59 Uma URL que ao acessada retorna como resposta um conjunto de informações, também chamada de “location”.

60 https://github.com/bacen/pix-api

telefone celular e enviar um QR Code via aplicativo de mensagens. Nessas situações, como o telefone celular é o dispositivo usado para ler o QR Code, não é possível utilizá-lo para ler um QR Code disponibilizado em sua própria tela. A funcionalidade “Pix Copia e Cola” foi pensada para ser uma alternativa nesses casos.

Para utilizar a funcionalidade “Pix Copia e Cola”, o usuário recebedor deve poder oferecer ao pagador uma maneira de copiar o inteiro teor da sequência de caracteres que representa o BR Code. Em outras palavras, deve ser copiada exatamente a mesma sequência de caracteres que seria lida pelo leitor de QR Code no momento da leitura do QR Code em questão. Essa funcionalidade é possível tanto para o QR Code estático quanto para o QR Code dinâmico.

Iniciação através de Serviço de Iniciação de Transação de Pagamento

Um Pix pode ser iniciado através do serviço de iniciação de transação de pagamento vinculado à implementação do Sistema Financeiro Aberto, tanto pelo participante iniciador, quanto pelo participante provedor de conta transacional.

A iniciação de um Pix através do serviço de iniciação de transação de pagamento acima referido deve conter, minimamente, o conjunto de dados listados abaixo.

Envio das Informações pelo Prestador de Serviço de Iniciação para o Detentor da Conta

Nome do Campo	Obrigatoriedade
Nome do Campo	Inserção Manual	Chave Pix	Usuário Recebedor com Chave	QR Code Estático	QR Code Dinâmico
Tipo de Iniciação	MANU	DICT	INIC	QRES (**)	QRDN
Iniciador de pagamento (CNPJ)	Sim	Sim	Sim	Sim	Sim
EndToEndId (*)	Sim	Sim	Sim	Sim	Sim
QrCode (Pix Copia e Cola)	Não	Não	Não	Sim	Sim
Código da cidade IBGE (CodMun) (***)	Não	Não	Não	Não	Não
Identificação do recebedor (CPF/CNPJ)	Sim	Sim	Sim	Sim	Sim
Instituição do recebedor participante do Pix	Sim	Sim	Sim	Sim	Sim
Agência do recebedor	Não	Não	Não	Não	Não
Conta do recebedor	Sim	Sim	Sim	Sim	Sim
Tipo de Conta do recebedor	Sim	Sim	Sim	Sim	Sim
Valor	Sim	Sim	Sim	Sim	Sim
Moeda	Sim	Sim	Sim	Sim	Sim
Campo de descrição	Não (**)	Não (**)	Não (**)	Não (**)	Não (**)
Chave Pix	Não	Sim	Sim	Sim	Sim
Código de Conciliação	Não	Não	Sim	Não	Sim

(*) A regra de obrigatoriedade de geração do <EndToEndId> pelo iniciador entrará em produção em 25/09/22. Até esta data, admite-se que o <EndToEndId> seja gerado pelo participante direto, pelo participante indireto ou pelo iniciador de pagamento.

(**) É obrigatório o envio da informação da descrição quando o usuário preencher o campo.

(***) No caso de QR Code Dinâmico com vencimento, deve prevalecer o código do município do usuário pagador informado pelo prestador do serviço de iniciação.

Mapeamento para mensagens ISO 20022

Alguns campos de iniciação de Pix apresentados pelo PSP do recebedor e pelo ente governamental por meio de QR Code devem ser mapeados pelo PSP do pagador nas mensagens de pagamento ISO 20022, como especificado abaixo. Os demais campos do pagamento, por exemplo: o valor.final – IntrBkSttlmAmt – da transação, devem seguir a lógica de negócio desenhada no Catálogo de Serviços do SFN. Outros exemplos: os Purp.Cd e RmtInf.Strd.RfrdDocInf.AdjstmntAmtAndRsn variam de acordo com a natureza do Pix realizado:

cobrança ou transferência sem saque/troco;
saque com QR Estático (id 03: fss presente com um ISPB);
saque com QR Dinâmico (estrutura retirada.saque presente);
troco com QR Dinâmico (estrutura retirada.troco presente)

O catálogo de mensagens tem exemplos de como deve ser feito o preenchimento em cada um dos casos (sem saque/troco, com saque e com troco).

Mapeamento do QR Code estático para 008

Os dados a serem mapeados pelo PSP do pagador do QR Code estático para a mensagem de pagamento são:

Campos EMV

Nome no Arranjo

Nome EMV

ISO 20022 pacs.008

Transaction Amount⁶¹

Se Purp.Cd for “IPAY” então InterbankSettlementAmount <IntrBkSttlmAmt> = transaction amount

Se Purp.Cd for “OTHR” então

RemittanceInformation <RmtInf> Structured <Strd>

ReferredDocumentAmount <RfrdDocAmt> AdjustmentAmountAndReason

<AdjstmntAmtAndRsn>

Amount <Amt> = transaction amount

Reason <Rsn> = “VLDN”

IntrBkSttlmAmt – O valor da transação ou do saque, quando informado em um QR code estático. Quando o QR Code estático tiver o propósito de Pix Saque:

RmtInf.Strd.RfrdDocAmt.AdjstmntAmtAndRsn.Amt – Deve ser utilizado para informar o valor do saque.

RmtInf.Strd.RfrdDocAmt.AdjstmntAmtAndRsn.Rsn – Deve sempre ser preenchido com o valor

VLDN.

61 De preenchimento não obrigatório, mas quando preenchido, deve ser utilizado como valor da transação.

Purp.Cd – Deve sempre ser preenchido com o valor OTHR.

Campos EMV Especiais

Nome no Arranjo

Nome EMV

ISO 20022 pacs.008

26-

Merchant Account Information

Nome no Arranjo

Nome EMV

pacs.008

chave

CreditorAccount <CdtrAcct> Proxy <Prxy>

Identification <Id>

fss

RemittanceInformation <RmtInf> Structured <Strd>

ReferredDocumentInformation <RfrdDocInf> Type <Tp>

Issuer <Issr>

Additional Data Field

Nome no Arranjo

Nome EMV

pacs.008

txid ⁶²

Reference Label

PaymentIdentification <PmtId> TransactionIdentification <TxId>

CdtrAcct.Prxy.Id – A chave Pix que identifica o recebedor do pagamento sempre deve ser mapeada para esse campo.

PmtId.TxId – Quando diferente de ‘***’, deve ser retransmitido intacto pelo PSP do pagador ao gerar a ordem de pagamento.

Quando o QR Code estático tiver o propósito de Pix Saque (id 03: fss presente com um ISPB):

RmtInf.Strd.RfrdDocInf.Tp.Issr – Deve ser utilizado para indicar o ISPB do facilitador de serviço de saque (id 03: fss). (NR)

RmtInf.Strd.RfrdDocInf.Tp.CdOrPrtry.Prtry – Deve sempre ser preenchido com o valor AGTEC. Caso a modalidade do agente de saque seja Agente Outra Espécie de Pessoa Jurídica que tenha como atividade principal ou secundária a prestação de serviços auxiliares a serviços financeiros ou afins ou correspondente no País (valor AGTOT) ou Agente Facilitador de Serviço de Saque (valor AGFSS), deve ser utilizado o QR Code dinâmico. (NR)

Mapeamento payload JSON para 008

Os dados do recebedor, provenientes do payload JSON, que devem ser mapeados pelo PSP do pagador para a mensagem de pagamento, são definidos abaixo:

Campos Comuns nos Produtos Pix

Campo

Uso

campo JSON

ISO 20022 pacs.008

Chave Pix do recebedor

Chave

CreditorAccount <CdtrAcct> Proxy <Prxy>

Identification <Id>

Identificador da

Transação

Txid

PaymentIdentification <PmtId> TransactionIdentification <TxId>

62 Quando em efeito (ou seja, diferente de ‘***’).

Informações Adicionais pelo

Pagador

(resposta ao campo solicitacaoPagador63)

RemittanceInformation <RmtInf>

CdtrAcct.Prxy.Id – A chave Pix que identifica o recebedor do pagamento sempre deve ser mapeada para esse campo.

PmtId.TxId – Deve ser retransmitido intacto pelo PSP do pagador. O campo presente no QR Code é

ignorado, mesmo que diferente de ‘***’, quando o QR Code for do tipo dinâmico.

RmtInf – O campo JSON solicitacaoPagador, opcional, conforme consta na API Pix⁶⁴, especifica um texto descritivo a ser exibido em tela ao usuário pagador para que este possa digitar a informação correlata, em formato livre, a ser enviada ao recebedor. O campo <RmtInf> na pacs.008 é limitado a 140 caracteres. O conteúdo deste campo deve ser negociado com o PSP.

Campos de Valor para Cobrança para Pagamento Imediato, Saque e Troco

Campo

Uso

campo JSON

ISO 20022 pacs.008

Valor da cobrança ou da compra

valor.original

Se Purp.Cd for “IPAY” então InterbankSettlementAmount <IntrBkSttlmAmt> = valor.original

Se Purp.Cd for “GSCB” então

RemittanceInformation <RmtInf> Structured <Strd>

ReferredDocumentAmount <RfrdDocAmt> AdjustmentAmountAndReason

Amount <Amt> = valor.original Reason <Rsn> = “VLCP”

Valor do saque

valor.retirada.saque.valor

Se Purp.Cd for “OTHR” então

RemittanceInformation <RmtInf> Structured <Strd>

ReferredDocumentAmount <RfrdDocAmt> AdjustmentAmountAndReason

Amount <Amt> = valor.retirada.saque.valor

Reason <Rsn> = “VLDN”

Valor do troco

valor.retirada.troco.valor

Se Purp.Cd for “GSCB” então

RemittanceInformation <RmtInf> Structured <Strd>

ReferredDocumentAmount <RfrdDocAmt> AdjustmentAmountAndReason

Amount <Amt> = valor.retirada.troco.valor

Reason <Rsn> = “VLDN”

63 Destaca-se que não é o conteúdo do campo “solicitacaoPagador” que deve ser preenchido no campo <RmtInf> da pacs.008, mas sim a resposta digitada pelo usuário pagador em função de “solicitacaoPagador”. O usuário pagador é instado a preencher alguma informação decorrente do texto que conste em “solicitacaoPagador”, e é exatamente esse texto que o usuário pagador escreveu que deve ser preenchido no campo <RmtInf> da pacs.008.

⁶⁴ Disponível em: <https://github.com/bacen/pix-api>

IntrBkSttlmAmt – O valor informado no campo InterbankSettlementAmount equivale à soma dos três campos (valor.original + valor.retirada.saque.valor + valor.retirada.troco.valor).

RmtInf.Strd.RfrdDocAmt.AdjstmntAmtAndRsn.Amt – Deve ser utilizado para informar valor de saque/troco ou compra, a depender do motivo.

RmtInf.Strd.RfrdDocAmt.AdjstmntAmtAndRsn.Rsn – Deve ser utilizado para informar o motivo do detalhamento (se saque/troco, ou se compra).

Purp.Cd – Deve ser utilizado para informar se a transação se refere a um Pix Saque (valor OTHR), Pix Troco (valor GSCB), ou outra transação Pix (valor IPAY).

Campos Adicionais para os Produtos Pix Saque e Pix Troco

Campo

Uso

campo JSON

ISO 20022 pacs.008

Modalidade do agente de saque

valor.retirada.(saque ou troco).modalidadeAgent e

RemittanceInformation <RmtInf> Structured <Strd>

ReferredDocumentInformation <RfrdDocInf> Type <Tp>

CodeOrProprietary <CdOrPrtry>

Proprietary <Prtry>

ISPB do facilitador de serviço de saque (NR)

valor.retirada.(saque ou troco). prestadorDoServicoDeSa

que

RemittanceInformation <RmtInf> Structured <Strd>

ReferredDocumentInformation <RfrdDocInf> Type <Tp>

Issuer <Issr>

Quando Purp.Cd=OTHR (Pix Saque) ou Purp.Cd=GSCB (Pix Troco), além dos aspectos relacionados aos valores acima citados, os respectivos campos de modalidadeAgente e prestadorDoServicoDeSaque serão de preenchimento obrigatório.

RmtInf.Strd.RfrdDocInf.Tp.CdOrPrtry.Prtry – Deve ser utilizado para indicar a modalidade do agente, com um dos valores possíveis do catálogo: Agente Estabelecimento Comercial (valor AGTEC), Agente Outra Espécie de Pessoa Jurídica que tenha como atividade principal ou secundária a prestação de serviços auxiliares a serviços financeiros ou afins ou correspondente no País (valor AGTOT) ou Agente Facilitador de Serviço de Saque (valor AGFSS65). Quando se tratar de um Pix Troco (Purp.Cd=GSCB), a modalidade do agente poderá ser AGTEC ou AGTOT66. (NR)

RmtInf.Strd.RfrdDocInf.Tp.Issr – Deve ser utilizado para indicar o ISPB do facilitador de serviço de saque. (NR)

Campos de Valor para Cobrança para Pagamento com Vencimento

Campo

Uso

campo JSON

ISO 20022 pacs.008

Valor do

pagamento

valor.final

InterbankSettlementAmount <IntrBkSttlmAmt>

⁶⁵ Observação: no mapeamento do campo da API Pix (AGPSS) para o campo ‘modalidadeAgente’, da pacs.008, o domínio a ser considerado é AGFSS.

⁶⁶ No caso do Pix Troco, a modalidade do agente será AGTOT apenas quando se tratar de correspondente no País. Não é permitida a disponibilização do Pix Troco por Agente Outra Espécie de Pessoa Jurídica que tenha como atividade principal ou secundária a prestação de serviços auxiliares a serviços financeiros ou afins.

IntrBkSttlmAmt – O valor informado no campo InterbankSettlementAmount equivale ao valor final transacionado (valor.original + valor.multa + valor.juros – valor.abatimento – valor.desconto).

Mapeamento do Serviço de Iniciação de Transação de Pagamento para 008

Nos casos em que participantes do Pix prestadores do serviço de iniciação se utilizam do serviço de iniciação, um conjunto de dados é transmitido desse prestador de serviço de iniciação ao PSP detentor da conta. A tabela abaixo refere-se ao mapeamento dos dados transitados no serviço de iniciação para a ordem de pagamento que deve ser enviada pelo PSP ao SPI na pacs.008.

Campos do Serviço de Iniciação de Transação de Pagamento

Nome do Campo	ISO 20022 pacs.008
Tipo de Iniciação	MandateRelatedInformation <MndtRltdInf> Type <Tp> LocalInstrument <LclInstrm> Proprietary <Prtry>
Identificação do iniciador de pagamento (CNPJ)	InitiatingParty <InitgPty> Identification <Id> OrganisationIdentification <OrgId> Other <Othr> Identification <Id>
Identificação do recebedor (CPF/CNPJ)	Creditor <Cdtr> Identification <Id> PrivateIdentification <PrvtId> Other <Othr> Identification <Id>
Instituição do recebedor participante do Pix	CreditorAgent <CdtrAgt> FinancialInstitutionIdentification <FinInstnId> ClearingSystemMemberIdentification <ClrSysMmbId MemberIdentification <MmbId>
Agência do recebedor	CreditorAccount <CdtrAcct> Identification <Id> Other <Othr> Issuer <Issr>
Conta do recebedor	CreditorAccount <CdtrAcct> Identification <Id> Other <Othr> Identification <Id>
Tipo de Conta do recebedor	CreditorAccount <CdtrAcct> Type <Tp> Code <Cd>
Valor	InterbankSettlementAmount <IntrBkSttlmAmt>
Moeda	InterbankSettlementAmount <IntrBkSttlmAmt Ccy=”” >
Campo de descrição	RemittanceInformation <RmtInf>
Chave Pix	CreditorAccount <CdtrAcct> Proxy <Prxy>
Código de Conciliação	PaymentIdentification <PmtId> TransactionIdentification <TxId>

ANEXO I – API Pix: Conceitos de Negócio

Introdução

O presente anexo tem por objetivo apresentar os conceitos de negócio e os casos de uso envolvendo a utilização da API Pix, sendo complementado pelas especificações técnicas da API, conforme explicitado na seção 2 deste documento.

A API Pix contempla as funcionalidades necessárias para viabilizar:

o recebimento de cobranças em 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, ou com data de vencimento específica, incorporando ainda os cálculos referentes a descontos e abatimentos, juros e multas, quando aplicáveis; e,
a transação Pix, com finalidade de saque ou de troco, iniciada por meio de QR Code dinâmico.

Documentação da API Pix

O conjunto completo de documentação da API Pix é composto pelos seguintes artefatos:

Anexo I: API Pix: Conceitos de Negócio – este anexo, disponível em https://www.bcb.gov.br/estabilidadefinanceira/pagamentosinstantaneos

Anexo II: API Pix: Especificação técnica – disponível em https://www.bcb.gov.br/estabilidadefinanceira/pagamentosinstantaneos

Anexo III: Cobranças para pagamentos com data de vencimento: criação, alteração e cálculo

– disponível em https://www.bcb.gov.br/estabilidadefinanceira/pagamentosinstantaneos

API Pix: Especificação técnica detalhada – apresentada no formato OpenAPI 3.0 e disponível em https://github.com/bacen/pix-api.

Para acessar a documentação técnica constante no item 3, deve ser recuperada a última versão disponível. Para cada versão, é gerada uma “tag” no Github contendo o seu número, no formato “major.minor.patch” (exemplo: 2.1.0).

Contexto da API Pix

Figura 1: A API Pix

A API Pix é o componente do arranjo que visa possibilitar que o usuário pagador ou recebedor, no contexto P2B⁶⁷ ou B2B⁶⁸, possa automatizar a interação com seu prestador de serviços de pagamento (PSP), a fim de realizar ou receber transações no âmbito do arranjo Pix.

Nesse contexto, a presente versão da API Pix busca automatizar a interação do usuário recebedor com seu prestador de serviços de pagamento (PSP), a fim de gerar cobranças e confirmar o recebimento do pagamento dessas cobranças por meio do Pix. Na figura 1, pode-se visualizar possíveis caminhos de integração dos sistemas do usuário recebedor com a API Pix do PSP.

O usuário recebedor poderá, via API Pix:

I – gerar cobranças que poderão ser pagas via QR Code pelos seus clientes; II – alterar dados da cobrança;

III – remover dados da cobrança, em caso de necessidade de cancelamento; IV – verificar a liquidação da cobrança por meio de Pix recebidos;

– realizar a conciliação dos pagamentos de maneira facilitada;

67 “Person to Business”, trata-se de uma interação de Pessoa para Negócio/empresa/estabelecimento.

68 “Business to Business”, trata-se de interações entre negócios/empresas/estabelecimentos.

– suportar o processo de devolução de valores, que pode ser acionado em função, por exemplo, da devolução de uma compra.

A seguir são detalhados os aspectos gerais que dizem respeito à API Pix.

Conceitos gerais

Para os fins deste documento, as expressões e os termos relacionados são assim definidos:

– client_ID: componente de acesso a API Pix que identifica um elemento de software cliente do usuário. Para acessar a API, é necessário utilizar, por exemplo, o Client_ID e um segredo, ambos fornecidos pelo PSP do usuário no processo de Pode existir mais de um elemento software cliente na infraestrutura do usuário e, portanto, para um usuário pode existir mais de um client_ID.
– escopos: definem as autorizações associadas a cada um dos serviços da Por sua vez, os Client_IDs possuem acesso a um ou mais escopos, o que definirá quais serviços podem ser acessados por cada Client_ID;
– payload JSON: conteúdo recuperado a partir da chamada à URL, lida a partir do QR Code dinâmico e que representa uma cobrança;
– PSP Pagador: participante do Pix no qual o usuário pagador possui uma conta transacional;
– PSP Recebedor: participante do Pix no qual o usuário recebedor possui uma conta transacional que será usada para recebimentos de O PSP Recebedor que quiser disponibilizar a seus clientes uma solução de integração automatizada com o arranjo Pix deve fazê-lo por meio da API Pix, seguindo as especificações de negócio e técnicas definidas pelo Banco Central do Brasil neste documento e nos outros documentos trazidos na seção 2.
– transactionId (txid): identificador da transação, na perspectiva do usuário Esse número é gerado pelo usuário recebedor e repassado ao PSP recebedor na chamada da API Pix, no momento da criação da cobrança, a fim de identificar unicamente aquela cobrança⁶⁹. Assim, o txid é utilizado pelo usuário recebedor, em seus processos de conciliação de pagamentos recebidos por meio de Pix. No caso das cobranças criadas por meio da API Pix, o PSP recebedor deve garantir que o txid seja único para um dado usuário recebedor (CPF/CNPJ).
– usuário pagador: aquele que efetua o pagamento de uma cobrança por meio do
– usuário recebedor: pessoa natural ou jurídica que deseja receber cobranças – para pagamentos imediatos ou com vencimento – por meio do Pix e se vale da API Pix para automação dos seus processos de geração dessas cobranças e para conciliação de pagamentos recebidos por meio do
– facilitador de serviço de saque (fss): participante do Pix, que se enquadre na modalidade provedor de conta transacional e que seja autorizado a funcionar pelo Banco Central do Brasil, que, em caráter facultativo, venha a facilitar o serviço de saque, diretamente, ou por meio de agente de saque, mediante estabelecimento de relação contratual para essa (NR)

⁶⁹ Nas cobranças para pagamento imediato, é possível ao usuário recebedor delegar a geração do txid para seu PSP. Para mais detalhes, veja a seção 5.3.1

Funcionalidades da API Pix
- Definições das entidades

A API Pix está estruturada em torno de algumas entidades de negócio, que agrupam conjuntos de atributos, conforme definido abaixo:

– Cobrança (/cob e /cobv): representa cada uma das cobranças geradas por meio da API Pix, a fim de permitir que o usuário pagador efetue um pagamento identificado para o usuário recebedor. A cobrança é caracterizada por um conjunto de informações que são utilizadas para que o usuário pagador execute um pagamento por meio do Pix, geralmente, em função de acordo comercial entre o usuário pagador e o usuário recebedor, sem se confundir com o pagamento Pix em si. A cobrança se subdivide em duas espécies: cobranças para pagamento imediato e cobranças para pagamento com

Estados da cobrança:

ATIVA: indica que a cobrança foi gerada e pronta para ser paga;
CONCLUÍDA: indica que a cobrança já foi paga e, por conseguinte, não pode acolher outro pagamento⁷⁰;
REMOVIDO_PELO_USUARIO_RECEBEDOR: indica que o usuário recebedor solicitou a remoção da cobrança; e
REMOVIDO_PELO_PSP: indica que o PSP Recebedor solicitou a remoção da cobrança.

– Pix (/pix): representa um pagamento recebido por meio do arranjo de pagamentos
– Devolução (devolução): representa uma solicitação de devolução de um Pix realizado, cujos fundos já se encontrem disponíveis na conta transacional do usuário recebedor.

Estados da devolução:

EM_PROCESSAMENTO: indica que a devolução foi solicitada, mas ainda está em processamento no SPI;
DEVOLVIDO: indica que a devolução foi liquidada pelo SPI; e
NAO_REALIZADO: indica que a devolução não pode ser realizada em função de algum erro durante a liquidação (exemplo: saldo insuficiente).

– Webhook(/webhook): é um recurso técnico que permite que o PSP Recebedor informe diretamente o usuário recebedor quando um Pix associado a um txid foi creditado na sua conta Nesse caso, a lógica do processo é invertida em relação ao funcionamento padrão da API, para garantir uma melhor performance ao processo. O usuário recebedor deixa de consultar o PSP Recebedor a todo momento (polling) e passa a ser informado na ocorrência de uma liquidação. Somente Pix associados a um txid serão informados via a funcionalidade webhook.
– PayloadLocation)(/loc): é um recurso que permite ao PSP Recebedor reusar uma URL, retornando diferentes cobranças (paylods JSON) ao longo do tempo, , mas apenas uma por vez. Tipicamente, é utilizado quando o usuário recebedor precisa apresentar um QR Code impresso, mas que seja dinâmico.

70 Importante observar que o estado CONCLUIDA refere-se à Cobrança gerada e não à obrigação associada. Dessa forma, esse estado não indica a liquidação da obrigação em si, mas apenas que aquela Cobrança não admite novos pagamentos.

Cardinalidade entre as entidades

– Uma Cobrança pode estar associada a um ou mais Pix (mesmo txid);
– Um Pix pode estar associado a uma única Cobrança. O Pix, no entanto, pode existir independentemente da existência de uma Cobrança;
– Um Pix pode ter uma ou mais Devoluções associadas a Uma Devolução está sempre associada a um Pix.
– Uma Cobrança somente pode estar associada a um PayloadLocation e, num determinado momento, o PayloadLocation só pode estar associado a uma cobrança.

Ciclo de vida do TransactionID (txid)

Há duas situações de uso para o campo TransactionId (txid), que envolvem regras distintas para seu preenchimento, conforme tratado a seguir.

txid no contexto das Cobranças

As cobranças para pagamentos imediatos ou com vencimento criadas por meio da API Pix são identificadas unicamente por meio de um txid. O txid pode ser enviado pelo usuário recebedor⁷¹ quando da geração da cobrança, e não poderá se repetir entre cobranças distintas⁷², a fim de garantir a correta conciliação dos pagamentos. Alternativamente, no caso de cobranças para pagamento imediato, é possível que o usuário recebedor delegue a geração do txid para o seu PSP⁷³.

Uma vez que seja solicitada a criação de uma cobrança por meio da API Pix, o PSP Recebedor deve assegurar que não exista repetição do txid para o mesmo usuário recebedor, seja ele enviado pelo usuário ou gerado pelo próprio PSP. Assim, o conjunto CNPJ ou CPF e txid deve ser único para um dado PSP.

O txid deve ter, no mínimo, 26 caracteres e, no máximo, 35 caracteres de tamanho. Os caracteres aceitos neste contexto são: A-Z, a-z, 0-9.

⁷¹ A importância de que o txid seja enviado pelo usuário recebedor está relacionada à garantia da idempotência da API Pix. Dessa forma, evita-se a criação de múltiplas cobranças para uma mesma obrigação original, devido a uma falha na chamada da API que cause incerteza quanto a se a cobrança já teria sido criada ou não.

72 Cabe enfatizar, inclusive, que não pode existir uma cobrança para pagamento imediato e uma cobrança para pagamento com vencimento que utilizem o mesmo txid.

⁷³ Caberá ao PSP do usuário recebedor explicar que, nesse caso, a idempotência não poderá ser garantida. Sendo assim, podem ser geradas cobranças que nunca serão retornadas ao usuário recebedor. O modelo de negócios do usuário recebedor deve ser analisado pelo seu PSP, a fim de garantir a adequação desse modelo (em que o PSP gera o txid) ao modelo de negócios praticado pelo usuário recebedor.

txid no contexto dos QR Codes Estáticos

Um aspecto importante a ser observado é que o PSP Recebedor não tem a possibilidade de assegurar que o txid não se repita em QR Codes estáticos, uma vez que eles não são gerados por meio da API Pix e, portanto, não são previamente registrados pelo PSP recebedor.

Além disso, há casos de uso em que a repetição de um txid em QR Codes estáticos é desejável (ex. 6.1.1) e outros em que deve ser evitada (ex. 6.1.3). Desta forma, a consistência dos pagamentos realizados por meio de QR Codes estáticos fica totalmente a cargo do usuário recebedor⁷⁴.

Assim, em relação a QR Codes estáticos, a única funcionalidade atualmente prevista na API Pix refere- se a retornar as transações Pix para o usuário recebedor com o txid em questão, possibilitando algum nível básico de confirmação/conciliação de pagamentos relacionados a essa modalidade de QR Code.

Grupos de funcionalidades

Funcionalidades e respectivos endpoints

As funcionalidades da API Pix, na versão atual, estão definidas em seis grupos:

– Gerenciamento de Cobranças com pagamento imediato (Cob), que trata do ciclo de vida da entidade

Cobrança:

Criação e atualização de cobrança	PUT /cob/{txid}
Criação de uma cobrança sem passar txid	POST /cob
Consulta de uma cobrança	GET /cob/{txid}
Consulta de lista de cobranças	GET /cob/
Alteração de uma cobrança	PATCH /cob/{txid}

– Gerenciamento de Cobranças para pagamento com vencimento (CobV), que trata do ciclo de vida da entidade Cobrança para pagamentos com vencimento:

Criação e atualização de cobrança	PUT /cobv/{txid}
Consulta de uma cobrança	GET /cobv/{txid}
Consulta de lista de cobranças	GET /cobv/
Alteração de uma cobrança	PATCH /cobv/{txid}

– Gerenciamento de lote de Cobranças para pagamento com vencimento (LoteCobV), que trata do ciclo de vida da entidade Lote de cobranças com vencimento:

Criação de lote de cobrança	PUT /lotecobv/{id}
Consulta de um lote de cobrança	GET /lotecobv/{id}

74 O contexto explorado aqui é a API Pix. O preenchimento do txid em um cenário de geração de QR Codes diretamente via o aplicativo do PSP do recebedor fica a cargo do PSP do recebedor, desde que seguidos os preceitos mínimos estabelecidos no Manual de requisitos Mínimos para a Experiência do Usuário.

Consulta lista de lotes de cobranças

GET /lotecobv/

– Gerenciamento de Pix Recebidos (Pix), que trata do ciclo de vida das entidades Pix e Devolução:

Consulta de um Pix específico	GET /pix/{e2eid}
Consulta de lista de Pix	GET /pix/
Solicitação de devolução	PUT /pix/{e2eid}/devolucao/{id}
Consulta de devolução	GET /pix/{e2eid}/devolucao/{id}

– Gerenciamento de “Localizações”⁷⁵, que trata da entidade PayloadLocation:

Criação de uma nova “location”	POST /loc
Consulta de lista de “locations”	GET /loc
Consulta de uma location específica	GET /loc/{id}
Desvincular uma cobrança de uma location	DELETE /loc/{id}/txid

– Gerenciamento de Notificações (Webhook), que trata da entidade Webhook:

Associa URL ao webhook	PUT /webhook/{chave}
Consulta o status da webhook	GET /webhook/{chave}
Remove o webhook	DELETE /webhook/{chave}
Consulta webhooks cadastrados	GET /webhook

Funcionalidades obrigatórias por produtos

No contexto da API Pix, devem ser implementadas as seguintes funcionalidades para cada produto:

Tags	Produtos
	Pix Cobrança		Pix Saque e Pix Troco
	*Pagamento Imediato*	*Pagamento com* *Vencimento*
Cob	x		x
CobV		x
LoteCobV		x
Pix	x	x	x
PayloadLocation	x	x	x
Webhook	x	x	x

75 Chamamos aqui de “localização” as URLs que servem payloads JSON que representam uma cobrança.

Casos de Uso

O objetivo dessa seção é trazer exemplos de como a API Pix pode ser utilizada na automação das interações entre usuários recebedores e seus respectivos PSPs em transações associadas ao Pix. Esses casos de uso NÃO pretendem esgotar as formas de utilização ou as funções disponibilizadas pela API Pix.

QR Code Estático

Para o contexto de QR Code Estático, a API Pix será estruturada em torno dos casos de uso listados a seguir⁷⁶:

Pagamento no ato da compra com QR Code Estático fixo e sem valor

Aplicação: aplicável em diversos cenários, especialmente em negócios com pequeno volume de transações.

Premissa: a conciliação de pagamento, se necessária, só pode ser feita de forma bem simplificada, sem a possibilidade de tratar transações em paralelo.

O usuário recebedor imprime um QR Code com a sua Chave Pix, um identificador de transação (txid) e sem valor Como todas as transações terão o mesmo txid, a capacidade de conciliação posterior é limitada;
O usuário recebedor afixa o QR Code impresso em um local visível no seu estabelecimento, por exemplo, próximo ao caixa;
O usuário pagador, ao realizar a compra ou no checkout, lê o QR Code impresso por meio do App de seu PSP, informa o valor e efetua o pagamento;
O software de automação do usuário recebedor consulta, por meio da API Pix, os últimos Pix recebidos com aquele txid:

Serviço invocado: GET /pix?txid={txid} à Podem ser informados parâmetros para limitar a consulta aos últimos minutos, por exemplo (parâmetros “início” e “fim” podem ser usados).

O usuário recebedor verifica a lista de pagamentos que foram creditados, observando sempre o último pagamento e o valor pago; e
O cliente é liberado, após a confirmação do pagamento, e pode seguir com a mercadoria ou sair do

Este caso de uso pode ser implementado sem a necessidade de acesso à API Pix. Nesse caso, suprime- se o passo 4, mantendo o passo 5 com a confirmação da efetivação do crédito pelo usuário recebedor por meio do App provido pelo PSP Recebedor.

Pagamento no ato da compra com QR Code Estático fixo com valor definido

⁷⁶ Vale lembrar que a API Pix não é utilizada para a geração de QR Codes estáticos.

Aplicação: similar ao caso anterior, para cenários envolvendo a venda de produtos padronizados, vendidos a preço fixo.

Premissa: conciliação de pagamento, se necessária, só pode ser feita de forma bem simplificada, sem a possibilidade de tratar transações em paralelo.

O usuário recebedor imprime um ou mais QR Codes com a sua Chave Pix, um identificador da transação (txid) e com um valor Em caso de mais de um produto sendo vendido, a alternativa é a criação de vários QR Codes impressos, cada um com um txid diferente, associado, por exemplo, a um código de um produto distinto;
O usuário recebedor afixa o QR Code impresso em um local visível no seu estabelecimento;
O usuário pagador, ao realizar a compra ou o checkout, lê o QR Code impresso por meio do App de seu PSP e efetua o pagamento;
O software de automação do usuário recebedor consulta, por meio da API Pix, os últimos Pix recebidos:

Serviço invocado: GET /pix?txid={txid} à Podem ser informados parâmetros para limitar a consulta aos últimos minutos, por exemplo (parâmetros “início” e “fim” podem ser usados).

O usuário recebedor verifica a lista de pagamentos que foram creditados, observando sempre o último pagamento e o valor pago; e
O cliente é liberado, após a validação, e pode seguir com a mercadoria ou sair do

Um eventual uso do txid como identificação do produto permite algum nível de controle posterior (e.g., quantos produtos de cada tipo foram vendidos em uma determinada data ou período), por meio de consultas ao extrato ou à própria API Pix.

Pagamento no ato da compra com QR Code Estático gerado no ato da compra

Aplicação: cenários diversos, em especial envolvendo negócios de pequeno porte, mas que exigem um processo de conciliação dos recebimentos.

Premissa: software de automação que saiba gerar QR Codes Estáticos.

O usuário recebedor, por meio do software de automação, imprime um QR Code estático com a sua chave, e um identificador da transação (txid) único (i.e., que não tenha sido usado anteriormente);
O usuário pagador, ao realizar a compra ou no checkout, lê o QR Code impresso por meio do App de seu PSP e efetua o pagamento;
O software de automação do usuário recebedor consulta, por meio da API Pix, se foi recebido um Pix com aquele txid:

Serviço invocado: GET /pix?txid={txid} à Deve ser informado o parâmetro “txid” para

limitar a consulta.

O usuário recebedor verifica a liquidação do recebimento; e
O cliente é liberado, após a validação, e pode seguir com a mercadoria ou sair do

Alternativamente, o passo 3 pode ser realizado com o uso de webhooks configurados no serviço correspondente. Nesse caso, o usuário recebedor seria informado pelo PSP Recebedor do crédito de um Pix associado a um txid na sua conta transacional.

QR Code Dinâmico

Pagamento imediato (no ato da compra) com QR Code Dinâmico

Aplicação: Comerciantes com volumes de vendas médios ou altos. Comércios online.

O usuário pagador, ao realizar a compra, informa que deseja pagar com Pix;
O software de automação utilizado pelo usuário recebedor acessa a API Pix para criação de uma cobrança e, com os dados recebidos como resposta, gera um QR Code Dinâmico, que é apresentado em um dispositivo de exibição qualquer:
1. em uma compra presencial, tipicamente uma tela próxima ao caixa ou mesmo um POS;
2. nas compras online, no dispositivo em uso pelo

Serviço invocado: PUT /cob/{txid} à Devem ser informados todos os dados necessários para criação do payload da cobrança, conforme especificação detalhada. Alternativamente, se o usuário recebedor não quiser identificar a cobrança imediata com seu próprio número {txid}, pode-se optar por utilizar o método POST /cob⁷⁷.

O usuário pagador lê, a seguir, o QR Code com o App do seu PSP e efetua o pagamento;
O usuário recebedor, de forma automatizada, por meio de nova consulta à API Pix, verifica se o pagamento foi realizado:

Serviço invocado: GET /cob/{txid}

O usuário recebedor libera os produtos para o usuário pagador ou, no caso das compras online, confirma o recebimento do

Alternativamente, o passo 4 pode ser realizado com o uso de webhooks configurados no serviço correspondente. Nesse caso, o usuário recebedor seria informado pelo PSP Recebedor do crédito de um Pix associado a um txid na sua conta transacional.

QR Code dinâmico para pagamentos com vencimento

77 A consequência de se utilizar POST /cob no lugar de PUT /cob/{txid} é que o método POST /cob não apresenta idempotência, enquanto o método PUT /cob/{txid} apresenta. A idempotência está presente em PUT /cob/{txid} porque no evento de um erro (por exemplo, uma falha na comunicação entre o usuário recebedor e seu PSP) pode acontecer de não se saber se a cobrança foi ou não criada de fato; nesse caso, a chamada poderia ser simplesmente repetida sem nenhum problema ou efeito adverso: caso a cobrança já tenha sido criada, a nova chamada PUT /cob/{txid} retornaria a mesma informação que deveria ter sido inicialmente retornada. Não é o caso com POST /cob: em caso de problemas, não se sabe se a cobrança foi criada e não há um identificador previamente conhecido, que permita verificar o status da cobrança. Assim, a chamada, ao ser repetida (POST /cob), ensejará a criação de uma nova cobrança.

Aplicação: cobranças com prazo para pagamento pelo usuário pagador; cobranças de mensalidades referentes a serviços cobrados no modelo de assinatura; outras situações correlatas.

O usuário recebedor, por meio do software de automação utilizado por ele, acessa a API Pix para criação de uma cobrança, informando, entre outros dados, a data de vencimento, o valor da obrigação, descontos, multa e juros aplicáveis à cobrança. Com os dados recebidos da API Pix, gera um QR Code Dinâmico, que é enviado ao usuário pagador (por exemplo, por e-mail)

Serviço invocado: PUT /cobv/{txid} à Devem ser informados todos os dados necessários para criação do payload da cobrança, conforme especificação detalhada.

O usuário pagador lê, a seguir, o QR Code dinâmico com o App do seu
O APP do PSP extrai a “location” do Qr Code dinâmico.
O APP do PSP pagador, depois de efetuar as validações de segurança, acessa a location incorporando os parâmetros: município do pagador e DPP configurada para a data de
O PSP pagador recupera os elementos de configuração de cobrança, em particular, o valor
O usuário pagador confirma as informações e agenda o pagamento para a data de
Com o pagamento tendo sido agendado, na data agendada, o PSP pagador escolhe o melhor momento, dentro do dia especificado, para realizar a transação
O usuário recebedor, a fim de confirmar o recebimento de suas cobranças, pode realizar uma consulta na API do PSP Recebedor:

Serviço invocado: GET /cobv/{txid}.

Alternativamente, o usuário pode ser notificado de que a cobrança foi honrada, por meio de serviço de notificação previamente configurado:

Serviço invocado: PUT /Webhook/{chave}

O usuário recebedor dá quitação à obrigação, liberando, por exemplo, a continuação do uso do produto ou serviço por parte do usuário

Lote de Cobranças com vencimento

Aplicação: usuários recebedores que disponham de uma quantidade expressiva de cobranças para serem criadas, de maneira que seja mais eficiente solicitar a criação de um conjunto grande de cobranças de umas só vez.

O usuário recebedor, por meio do software de automação utilizado por ele, acessa a API Pix para criação de um lote de cobranças, informando, para cada cobrança, entre outros dados, a data de vencimento, o valor da obrigação, descontos, multa e juros aplicáveis à cobrança, juntamente com seu identificador txid.

Serviço invocado: PUT /lotecobv/{id} à devem ser informados todos os dados necessários para criação dos payloads das cobranças, conforme especificação detalhada.

Como retorno, o usuário recebedor recebe uma mensagem de sucesso significando que a solicitação foi recebida e está em

O usuário recebedor, quando achar conveniente, valendo-se do “id” utilizado para criar o lote de cobranças, verifica o status de sua requisição para identificar o status de criação de cada cobrança individual:

Serviço invocado: GET /lotecobv/{id} à deve ser informado o “id” utilizado para criação

do lote.

O usuário recebedor, como retorno do endpoint “GET /lotecobv/{id}”, recebe uma lista de

status correspondentes a cada solicitação de criação de cobranças.

Quando o usuário recebedor achar conveniente, pode acessar as informações específicas das cobranças criadas com sucesso:

Serviço invocado: GET /cobv?lotecobvid={id} à deve ser informado o “id” que foi utilizado para criação do lote.

Como retorno, o usuário recebedor recebe uma consulta paginada contendo todas as cobranças criadas com sucesso associadas ao lote em questão.
O usuário recebedor utiliza as informações obtidas no passo anterior para efetuar a criação de seus QR Codes ou “Pix Copia e Cola”.
O usuário recebedor envia as cobranças criadas com sucesso em lote aos seus devedores correspondentes usando o meio que achar mais

O QR Code dinâmico “impresso”

Aplicação: estabelecimentos comerciais cujos caixas são conectados ao sistema de automação comercial, mas não dispõem de dispositivo para exibição de QR Codes; cenários variados de uso.

Para configurar a API Pix para esse caso de uso, o primeiro passo é criar uma “location” (a URL que exibirá as cobranças, e que será configurada no QR Code dinâmico:

Serviço invocado: POST /loc à será retornado o identificador da “location” e a URL a qual será utilizada para exibir as cobranças. Deve ser informado se a location servirá cobranças imediatas (cob) ou cobranças para pagamento com vencimento (cobv). No presente exemplo, será uma location que servirá cobranças imediatas.

O usuário recebedor, em seguida, por meio de seus softwares de automação, imprime um QR Code Dinâmico configurado com a “location” obtida e o afixa em um local apropriado, próximo a seu caixa (podem ser gerados e impressos QR Codes distintos, cada um com sua própria “location”, caso existam múltiplos caixas na loja).
Quando o primeiro cliente comparece ao caixa para realizar o checkout, o caixa, via automação, cria uma cobrança estabelecendo que será utilizado a “location” previamente criada (o software deverá associar a cobrança à “location” configurada no QR Code impresso que fica próximo ao caixa em que o checkout está sendo realizado):

Serviço invocado: PUT /cob/{txid} à Devem ser informados todos os dados necessários para criação do payload da cobrança, conforme especificação detalhada. Em particular, é informado o parâmetro “location” (loc.id) detalhando que esta cobrança específica utilizará a “location” previamente criada.

O usuário pagador, usando o aplicativo mobile de seu PSP pagador escolhido, realiza a leitura do QR Code impresso, confere as informações e confirma o

A automação comercial verifica que o pagamento foi liquidado:

Serviço invocado: GET /cob/{txid} à deve ser utilizado o mesmo ‘txid’ passado na criação do payload da cobrança.

O cliente é liberado, após a validação, e pode seguir com a mercadoria ou sair do estabelecimento;
Uma vez que o cliente foi liberado, a automação desvincula o QR Code Dinâmico impresso

desta cobrança já liquidada, comandando a “location” a não exibir nenhuma cobrança:

Serviço invocado: DELETE /loc/{id}/txid à O identificador da location, {id}, a ser informado, é o identificador obtido ao se estabelecer uma “location” (loc.id) para o caixa em questão.

O caixa encontra-se, neste ponto, preparado para receber o próximo cliente. O QR Code impresso, neste ponto, não exibirá nenhuma cobrança ao ser lido.

Outros casos de uso
- Efetuar uma devolução

Aplicação: várias (devolução de produto, erro na cobrança, indisponibilidade do produto em estoque etc.)

Premissa: um pagamento foi recebido via Pix.

O usuário pagador solicita ao usuário recebedor, via algum meio de comunicação adequado, a devolução total ou parcial de um pagamento realizado;
O usuário recebedor concorda e identifica o pagamento original realizado pelo Há duas situações possíveis:
1. Quando o Pix está associado a uma Cobrança:

Serviço invocado: GET /cob/{txid} à Como resultado, será recebida uma entidade Cobrança que contém uma relação dos Pix recebidos, cada um com a sua identificação (EndToEndId).

Quando o Pix não está associado a uma Cobrança. Nesse caso, é necessário saber, por outros meios, o EndToEndId do Pix original. Alternativamente, pode ser uma consulta ampla, trazendo a relação dos Pix recebidos.

Serviço invocado: GET /pix/ à Podem ser informados parâmetros para limitar a consulta temporalmente (parâmetros início e “fim” podem ser usados). Além disso, pode-se limitar a busca a um usuário pagador específico, por meio do CNPJ/CPF do pagador.

O software de automação do usuário recebedor aciona a API Pix para realizar a devolução. Serviço invocado: PUT /pix/{e2eid}/devolucao/{id} à No caso, “id” é um código gerado pelo sistema do usuário recebedor que identifica a devolução associada ao Pix Observar, que um Pix pode ter várias devoluções associadas a ele, desde que o montante das devoluções não ultrapasse o valor do Pix original. O “id” deve ser único por EndToEndID Pix.

O software de automação do usuário recebedor aciona a API Pix para verificar se a devolução foi liquidada:

Serviço invocado: GET /pix/{e2eid}/devolucao/{id}

O usuário pagador recebe um Pix com o valor de devolução

Remover uma Cobrança

Aplicação: várias (por exemplo: quando um QR Code foi gerado, mas não é mais válido, pois o cliente desistiu da compra).

Premissa: há uma Cobrança gerada e válida.

O usuário recebedor percebe que, por alguma razão, precisa remover uma cobrança que foi anteriormente gerada;
O usuário recebedor solicita a remoção da cobrança via API Pix;

Serviço invocado: PATCH /cob[v]/{txid} à Deve ser atribuído o Status para REMOVIDO_PELO_USUARIO_RECEBEDOR.

A cobrança é removida e, se mesmo assim, o usuário pagador ler o QR Code, o PSP Pagador deverá indicar que a cobrança foi excluída;
Não se pode alterar e nem remover uma cobrança cujo status esteja em CONCLUÍDA. O Status CONCLUÍDA é final;
Uma cobrança terá seu status alterado para CONCLUÍDA quando um Pix associado ao txid da cobrança for recebido.

Alterar uma cobrança

Aplicação: várias (por exemplo: quando uma cobrança foi gerada, mas o cliente solicitou um produto a mais; ou quando se percebe um erro no valor total).

Premissa: há uma cobrança gerada e válida.

O usuário recebedor percebe que, por alguma razão, precisa alterar uma cobrança que foi anteriormente gerada;
O usuário recebedor solicita a alteração da cobrança via API Pix;

Serviço invocado: PATCH/cob[v]/{txid}⁷⁸ à Devem ser passadas todas as informações corrigidas, conforme especificação detalhada.

A cobrança é alterada e, numa nova leitura do QR Code, as informações estarão atualizadas;
Não se pode alterar e nem remover uma cobrança cujo status esteja em CONCLUÍDA. O Status CONCLUÍDA é final;
Uma cobrança terá seu status alterado para CONCLUÍDA quando um Pix associado ao txid da cobrança for recebido.

Configuração de Webhooks

78 Pode-se alterar tanto uma cobrança imediata quanto uma cobrança com vencimento.

Aplicação: para usuários recebedores que trabalham com grande número de recebimentos via Pix e que desejam evitar um oneroso processo de polling na API Pix de seu PSP recebedor.

Premissa: o usuário recebedor possui uma infraestrutura de TI apta para tratar os webhooks.

O usuário recebedor aciona a API Pix, indicando a URL na qual deseja receber as informações sobre Pix

Serviço invocado: PUT /webhook/{chave} à Deve ser atribuída a URL base que receberá os callbacks enviados pelo PSP Recebedor ao usuário recebedor. Cada webhook está associado a uma chave Pix de maneira que os Pix informados a um webhook estão associados à chave Pix que também está associada ao webhook em questão. Se um Pix recebido estiver associado a uma chave que não esteja associado a um webhook, não haverá notificação.

A partir desse momento, o usuário Recebedor receberá chamadas nesse endpoint com a lista de Pix recebidos associados a um txid, e associados à respectiva chave Pix, conforme esses Pix forem sendo liquidados. Pix recebidos que não estejam associados a um txid não gerarão chamadas.

ANEXO II – API Pix: Especificação Técnica

Introdução

O presente anexo tem por objetivo apresentar a especificação da API Pix, que normatiza a comunicação entre usuários e respectivos PSPs nas operações relacionadas ao Pix. Para as definições que seguem, o Banco Central do Brasil (BC) valeu-se de subsídios colhidos junto ao mercado por meio de consultas previamente enviadas e de reuniões bilaterais com participantes e associações, seguindo o modelo de criação conjunta, adotado desde o começo dos trabalhos no âmbito do Fórum Pagamentos Instantâneos.

Protocolos e tecnologias

A API Pix adotará os seguintes protocolos e tecnologias:

Definição da API: A API Pix está detalhada no formato OpenAPI 3.0⁷⁹.

Formato: O formato de dados utilizados é o JSON⁸⁰.

Protocolo: a automação do usuário recebedor interage com a API utilizando web services baseados em REST⁸¹ sobre HTTPS.

Segurança

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.

Requisitos de segurança obrigatórios

O PSP deve obrigatoriamente observar os seguintes requisitos:

A conexão à API deve ser criptografada utilizando o protocolo TLS versão 2 ou superior, permitindo apenas cipher suites que atendam ao requisito de forward secrecy⁸².
O PSP deve implementar o framework OAuth 0 (RFC 6749)⁸³ com TLS mútuo (mTLS – RFC

8705⁸⁴) para autenticação na API, conforme especificações abaixo:

79 http://spec.openapis.org/oas/v3.0.3

80 JSON: JavaScript Object Notation.

https://developer.mozilla.org/pt-BR/docs/Web/JavaScript/Reference/Global_Objects/JSON

81 Os webservices da API Pix serão baseados no estilo arquitetural REST, usando métodos HTTP para realizar as chamadas à API. Mais detalhes em: https://en.wikipedia.org/wiki/Representational_state_transfer

82 https://tools.ietf.org/html/bcp195#section-6.3

83 https://tools.ietf.org/html/rfc6749

84 https://tools.ietf.org/html/rfc8705

Os certificados digitais dos clientes da API poderão ser emitidos pelo próprio PSP ou por ACs externas, conforme definido por cada Não deverão ser aceitos certificados auto-assinados pelo cliente.
Cada PSP deve possuir seu próprio Authorization Server e Resource Server associado à API Pix, e ambos devem implementar TLS mútuo.
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
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).
O fluxo OAuth a ser utilizado é o “Client Credentials Flow”.
Os escopos OAuth serão definidos na especificação Open API 0 da API Pix e permitirão associar diferentes perfis de autorização ao software cliente.

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
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
O PSP deve implementar tecnologia que permita garantir a alta disponibilidade da
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.
O PSP deve manter logs de auditoria dos acessos à API pelo período mínimo de 1
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
Para a funcionalidade de webhooks, as notificações oriundas do PSP recebedor ao usuário recebedor trafegarão utilizando um canal mTLS.
1. Recomenda-se que os certificados utilizados para autenticação mútua no canal TLS do webhook sejam os mesmos da API Pix. De todo modo, não há objeção quanto à utilização de outros certificados, mediante acordo entre o PSP e o usuário

Recomendações de segurança

É recomendado ao PSP:

Implementar múltiplos fatores de autenticação para o processo de cadastro/onboarding na
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 Ten⁸⁵ e CWE Top 25 Software Weaknesses⁸⁶.
Possuir processo periódico de análise de vulnerabilidades, tanto estática como dinâmica da

⁸⁵ https://owasp.org/www-project-api-security/

⁸⁶ https://cwe.mitre.org/top25/archive/2020/2020_cwe_top25.html

Assegurar a segurança do desenvolvimento do software cliente⁸⁷ da API, mesmo que desenvolvido por 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.
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 um risco se materialize em um incidente, o próprio PSP poderá ser Ações recomendadas (sem prejuízo para outras ações que

o PSP julgar importantes):

Instituir e acompanhar programa de melhoria contínua da segurança dos usuários recebedores que utilizam a API;
Realizar campanhas de conscientização e compartilhamento de informações de segurança junto aos usuários;
Definir uma política de troca periódica do certificado, senha e outras credenciais utilizadas no acesso à API;
Validar a segurança do ambiente computacional dos usuários nos aspectos de infraestrutura, implementação e configuração do software cliente da
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.

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 senhas) 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.

⁸⁷ No contexto, o termo “cliente” é utilizado para designar o hardware e o software utilizado pelo Usuário Recebedor, ou por terceiro por ele selecionado, para interagir com a API Pix provida por um PSP.

ANEXO III – Cobranças para pagamentos com vencimento: Criação, alteração e cálculo

Introdução

O presente anexo tem por objetivo apresentar como são criadas e atualizadas as cobranças com data de vencimento. Descreve, ainda, como o PSP do recebedor deve calcular, a partir das informações apresentadas pelo usuário recebedor ao criar e/ou atualizar uma cobrança para pagamentos com vencimento, o valor final de uma cobrança para pagamento com vencimento, de forma a incorporar as componentes relacionadas aos abatimentos, descontos, juros e multas que podem incidir sobre essas cobranças.

Criando uma cobrança para pagamento com vencimento

Para criar uma cobrança para pagamentos com vencimento, é necessário que o usuário recebedor conecte seus sistemas (ou de terceiros por ele contratados) à API Pix provida pelo PSP por ele contratado.

Estrutura para criação e atualização de uma cobrança para pagamento com vencimento

Para cada cobrança a ser criada, o usuário recebedor deverá enviar as seguintes informações:

#	Campo	Mult.	Nome Campo JSON	Tipo	OU
1.1	Data de vencimento do pagamento	[1..1]	calendario.dataDeVencimento	String
1.2	Validade Após Vencimento em dias corridos	[0..1]	calendario.validadeAposVencimento	Integer
2.1	CPF do usuário devedor	[0..1]	devedor.cpf	String	OU(
2.2	CNPJ do usuário devedor	[0..1]	devedor.cnpj	String	)
2.3	Nome do usuário devedor	[1..1]	devedor.nome	String
2.4	e-Mail do usuário devedor	[0..1]	devedor.email	String
2.5	Logradouro do devedor	[0..1]	devedor.logradouro	String
2.6	Cidade do devedor	[0..1]	devedor.cidade	String
2.7	Unidade da federação do devedor	[0..1]	devedor.uf	String
2.8	CEP do devedor	[0..1]	devedor.cep	String
3	Identificador da localização do payload associado à cobrança	[0..1]	loc.id	Integer
4.1	Valor original do documento	[1..1]	valor.original	String
4.2.1	Modalidade de abatimentos ou outras deduções, conforme tabela de domínios	[0..1]	valor.abatimento.modalidade	Integer
4.2.2	Abatimentos ou outras deduções aplicadas ao documento, em	[0..1]	valor.abatimento.valorPerc	String

	valor absoluto ou percentual do valor original do documento
4.3.1	Modalidade de desconto, conforme tabela de domínios.	[0..1]	valor.desconto.modalidade	Integer
4.3.2	Descontos por pagamento antecipado, com data fixa. Matriz com até três elementos, sendo que cada elemento é composto por um par “data e valorPerc”, para estabelecer descontos percentuais ou absolutos, até aquela data de pagamento.	[0..1]	valor.desconto.descontoDataFixa	Array	OU(
4.3.3	Desconto em valor absoluto ou percentual por dia, útil ou corrido, conforme valor.desconto.modalidade	[0..1]	valor.desconto.valorPerc	String	)
4.4.1	Modalidade de juros, conforme tabela de domínios.	[0..1]	valor.juros.modalidade	Integer
4.4.2	Valor absoluto ou percentual dos juros, a ser utilizado no cálculo dos juros, conforme “valor.juros.modalidade”	[0..1]	valor.juros.valorPerc	String
4.5.1	Modalidade da multa, conforme tabela de domínios.	[0..1]	valor.multa.modalidade	Integer
4.5.2	Multa em valor absoluto ou percentual, conforme “valor.multa.modalidade”	[0..1]	valor.multa.valorPerc	String
5	Chave Pix do recebedor	[1..1]	chave	String
6	Identificador da transação	[1..1]	txid	String
7	Solicitação ao Pagador	[0..1]	solicitacaoPagador	String
8	Conjunto livre de caracteres, com limite de tamanho	[0..1]	infoAdicionais	Array[Inf oAdiciona l]

A seguir, apresenta-se uma breve explanação sobre os principais campos listados para a criação de uma cobrança para pagamento com vencimento. Para informações em maior detalhe técnico, a API Pix é a referência indicada⁸⁸.

⁸⁸ Disponível em <https://github.com/bacen/pix-api> (ver “Cobv: PUT” para criação de uma única cobrança; e “LoteCobV: PUT” para criação de um lote de cobranças).

Calendário

Campos do objeto calendário:

dataDeVencimento: [obrigatório] trata-se de uma data, no formato ‘yyyy-mm-dd’, segundo ISO 8601. É a data de vencimento da cobrança, que pode ser paga em qualquer horário do dia. Exemplo: 2020-10-19.

Sempre que a data de vencimento cair em um fim de semana ou em um feriado para o usuário pagador, ela deve ser automaticamente prorrogada para o primeiro dia útil subsequente. Todos os campos que façam referência a esta data (validadeAposVencimento; desconto; juros e multa) devem assumir essa prorrogação, quando for o caso.

validadeAposVencimento: [opcional] (int32) Trata-se da quantidade de dias corridos após calendario.dataDeVencimento em que a cobrança poderá ser paga. Aplica-se o valor deste campo sobre o vencimento original da cobrança acrescentando-se o número de dias corridos nos quais a cobrança ainda poderá ser paga, após vencida.

Sempre que a data de validade após o vencimento cair em um fim de semana ou em um feriado para o usuário pagador, ela deve ser automaticamente prorrogada para o primeiro dia útil subsequente.

Valor

Além do campo valor.original a ser preenchido na criação da cobrança, os demais campos deverão seguir as instruções abaixo referenciadas. Como regra, não devem ser geradas cobranças cujo valor do desconto possa ser superior ao valor da cobrança original.

o valor.abatimento.modalidade: indica como o valor do abatimento deve ser calculado. Pode assumir os seguintes valores:

Descrição	Domínio
Valor Fixo	1
Percentual	2

o valor.abatimento.valorPerc: valor ou percentual do abatimento aplicado à cobrança. É obrigatório se modalidade for preenchida.

o valor.desconto.modalidade: [opcional] indica como o valor do desconto deve ser calculado. Pode assumir os seguintes valores:

Descrição	Domínio
Valor Fixo até a data informada	1

Percentual até a data informada	2
Valor por antecipação dia corrido	3
Valor por antecipação dia útil	4
Percentual por antecipação dia corrido	5
Percentual por antecipação dia útil	6

o valor.desconto.descontoDataFixa: [opcional] descontos no valor da cobrança se pago até determinada data. Este objeto é composto por uma matriz com até três elementos, sendo que cada elemento é composto por um par “data e valorPerc”, para estabelecer descontos percentuais ou absolutos, até a data de pagamento em questão. Só deve ser preenchido se o campo modalidade for preenchido e assumir o valor “1” ou “2”. Exemplos de preenchimento:

valor.desconto.modalidade = 1

valor.desconto.descontoDataFixa[0].data = “2020-10-13”

valor.desconto.descontoDataFixa[0].valorPerc = “200.00”

valor.desconto.descontoDataFixa[1].data = “2020-10-19”

valor.desconto.descontoDataFixa[1].valorPerc = “100.00”

Sempre que a data limite para desconto cair em um fim de semana ou em um feriado para o usuário pagador, ela deve ser automaticamente prorrogada para o primeiro dia útil subsequente.

o valor.desconto.valorPerc: [opcional] valor absoluto ou percentual a ser utilizado no cálculo do desconto, conforme a modalidade de desconto escolhida. Só deve ser preenchido se o campo modalidade for preenchido e assumir o valor “3” a “6”.

o valor.juros.modalidade: [opcional] indica como o valor dos juros aplicáveis ao pagamento da cobrança em atraso deve ser calculado. Pode assumir os seguintes valores:

Descrição	Domínio
Valor (dias corridos)	1
Percentual ao dia (dias corridos)	2
Percentual ao mês (dias corridos)	3
Percentual ao ano (dias corridos)	4
Valor (dias úteis)	5
Percentual ao dia (dias úteis)	6
Percentual ao mês (dias úteis)	7
Percentual ao ano (dias úteis)	8

juros.valorPerc: [opcional] valor absoluto ou percentual a ser utilizado no cálculo do desconto, conforme a modalidade de desconto escolhida. Se modalidade tiver sido preenchida, então este campo também deve ser preenchido.

multa.modalidade: [opcional] indica como o valor da multa aplicável ao pagamento da cobrança em atraso deve ser calculado. Pode assumir os seguintes valores:

Descrição	Domínio
Valor fixo	1
Percentual	2

multa.valorPerc: [opcional] valor absoluto ou percentual a ser utilizado no cálculo da multa, conforme a modalidade de escolhida. Se modalidade tiver sido preenchida, então este campo também deve ser preenchido.

Chave

O campo chave, obrigatório, determina a chave Pix registrada no DICT que será utilizada para a cobrança, identificando o usuário recebedor, bem como os dados da conta transacional à qual a cobrança deve estar atrelada.

txid

O txid, no contexto de uma cobrança para pagamento com vencimento, é criado pelo usuário recebedor e encontra-se sob sua responsabilidade, devendo ser único para um mesmo PSP por ele contratado, seja a cobrança para pagamentos imediatos ou com vencimento (único por CPF/CNPJ do usuário recebedor e PSP). Cabe ao PSP recebedor validar essa regra na API Pix.

O objetivo desse campo é possibilitar ao usuário recebedor realizar a conciliação de pagamentos referentes a suas cobranças. Na pacs.008, o PSP do Pagador deve enviar essa informação como TransactionIdentification <TxId>.⁸⁹ O campo txid deve ter, no mínimo, 26 caracteres e, no máximo, 35 caracteres.

Solicitação ao Pagador

O campo solicitacaoPagador, opcional, determina um texto a ser apresentado ao pagador para que ele possa digitar uma informação correlata, em formato livre, a ser enviada ao recebedor. Esse texto⁹⁰ será preenchido, na pacs.008, pelo PSP do pagador, no campo RemittanceInformation

<RmtInf>. O tamanho do campo <RmtInf> na pacs.008 está limitado a 140 caracteres.

Informações Adicionais

O campo infoAdicionais, se estiver presente, se refere a uma lista em que cada elemento deve utilizar o esquema abaixo:

⁸⁹ Vale lembrar que, no JSON, “txid” é escrito todo em minúsculas, enquanto a tag “TxId” da pacs.008 alterna

maiúsculas e minúsculas.

90 Importante destacar que é o texto digitado livremente pelo pagador que é enviado na pacs.008, e não o texto apresentado no campo solicitacaoPagador.

Subcampo JSON

(infoAdicionais)

Presença

Tipo JSON

Propósito

Nome

Obrigatório

String

Nome do campo

Valor

Obrigatório

String

Dados do campo

Os limites relativos ao tamanho de cada campo e à quantidade de elementos da lista estão tratados na especificação da API Pix⁹¹.

Cada respectiva informação adicional contida na lista (nome e valor) deve ser apresentada ao pagador. Exemplo: campo infoAdicionais no JWSPayload:

infoAdicionais[0].nome: “campo1” infoAdicionais[0].valor: “informação adicional 01” infoAdicionais[1].nome: “campo2” infoAdicionais[1].valor: “informação adicional 02”

Esse campo deve ser utilizado para indicar as regras que regem o cálculo do valor da cobrança (descontos, juros e multas), entre outras informações que o usuário recebedor queira transmitir ao usuário pagador.

91 Disponível em <https://github.com/bacen/pix-api>.

Cálculo do valor da cobrança

O valor final da Cobrança, a ser calculado pelo PSP recebedor, deve ser calculado de acordo com a fórmula a seguir:

𝑽𝒇 = 𝑽𝒐 − 𝑽𝒂 − 𝑽𝒅 + 𝑽𝒋 + 𝑽𝒎

Equação 1

Onde:

Vf: valor final da cobrança, que deve pago pelo usuário pagador;

Vo: valor original da cobrança;

Va: valor de abatimento aplicável à cobrança;

Vd: valor de desconto aplicável à cobrança;

Vj: valor de juros aplicável pelo atraso no pagamento da cobrança;

Vm: valor de multa aplicável pelo atraso no pagamento da cobrança.

Na apresentação do valor a ser pago pelo usuário pagador, as componentes com valor zero não devem ser apresentadas ao usuário pagador. As componentes do valor final da cobrança com valor não nulo devem ser apresentadas de forma individualizada. Se o valor final da cobrança é igual ao valor nominal da cobrança, então apenas o valor nominal da cobrança deve ser apresentado.

Cálculo do valor de abatimento (Va)

Por padrão, uma Cobrança Pix é criada sem abatimentos. O abatimento deve ser acordado entre o devedor e o beneficiário da cobrança, que é quem pode atualizar o valor da cobrança junto a seu prestador de serviços de pagamento.

O abatimento pode ser realizado em valor absoluto ou em percentual do valor original, conforme modalidade do abatimento. Se a modalidade escolhida pelo recebedor for por valor fixo, então o valor a ser abatido é o próprio valor informado pelo recebedor. Se for informado o valor percentual, então o valor de abatimento será calculado conforme a fórmula a seguir:

𝑽𝒂

= 𝑽𝒐

𝑰𝒂

𝟏𝟎𝟎

Equação 2

Onde:

Va: valor de abatimento aplicável à cobrança;

Vo: valor original da cobrança;

Ia: percentual de abatimento, informado com 2 casas decimais.

O valor calculado para Va deve ser truncado com duas casas decimais.

Campos JSON referenciados:

valor.original (Vo) valor.abatimento.modalidade valor.abatimento.valorPerc (Ia)

O campo valor.abatimento.modalidade pode assumir os seguintes valores:

Descrição	Domínio
Valor Fixo	1
Percentual	2

Cálculo do valor de desconto (Vd)

Fixo até a data informada⁹²

Nesse caso, o usuário recebedor terá que indicar descontos, até uma determinada data. O usuário recebedor poderá fixar até três datas menores ou iguais à data do vencimento. Além disso, ele poderá indicar se o desconto será um valor absoluto ou um percentual do valor do documento. Se o valor do desconto for dado em percentual, será calculado pela fórmula a seguir:

𝑽𝒅

= (𝑽𝒐

− 𝑽𝒂

𝑰𝒅

) × ( )

𝟏𝟎𝟎

Equação 3

Onde:

Vd: valor do desconto;

Vo: valor original da cobrança;

Va: valor de abatimento aplicável à cobrança;

Id: percentual de desconto, informado com 2 casas decimais.

Podem ser informadas até 3 datas para aplicação de desconto até a data de vencimento, inclusive. A data de cálculo deve ser comparada com a data mais antiga (elemento1) na matriz. Se a data for menor ou igual a essa data; aplica-se o valor de desconto (absoluto ou percentual) associado a esse elemento. Se a data for maior, compara-se com a data do segundo elemento e assim por diante.

Sempre que a data limite para desconto cair em um fim de semana ou em um feriado para o usuário pagador, ela deve ser automaticamente prorrogada para o primeiro dia útil subsequente.

⁹² Modalidades de desconto com domínio “1” ou “2”.

O valor calculado para Vd deve ser truncado com duas casas decimais.

Campos JSON referenciados:

valor.original (Vo) valor.desconto.modalidade valor.desconto.descontoDataFixa[n].data

valor.desconto.descontoDataFixa[n].valorPerc (Id)

O valor de “n”, em destaque amarelo nos campos relacionados a data fixa, varia de 0 a 2. Veja-se o exemplo:

valor.desconto.modalidade = 1 (“Valor Fixo até a data informada”)

valor.desconto.descontoDataFixa[0].data= “2020-12-10”

valor.desconto.descontoDataFixa[0].valorPerc = “300.00”

Nesse exemplo, caso o pagamento seja efetuado até o final do dia 10 de dezembro de 2020, o usuário terá um desconto de R$ 300,00 (trezentos reais) no valor a ser pago.

Desconto por dia de antecipação⁹³

O desconto pode, alternativamente, ser informado em valor absoluto ou percentual, por dia corrido ou útil antes da data de vencimento.

Se o desconto foi informado em valor absoluto por dia de antecipação, deverá ser calculado pela fórmula a seguir:

𝑽𝒅 = 𝑽𝒅𝒅 × 𝑫𝑎

Equação 4

Onde:

Vd: valor do desconto;

Vdd: valor do desconto por dia de antecipação;

Dα: dias úteis ou corridos, conforme modalidade

Se dias corridos: Dα = Dc

Se dias úteis: Dα = Du

⁹³ Modalidades de desconto com domínio “3” a “6”.

Dc número de dias corridos entre o dia de realização do cálculo e a data de vencimento. Se o resultado da subtração for menor que zero, então Dc deve ser zero:

𝑫𝒄 = 𝒎𝒂𝒙(𝟎; (𝑫𝒂𝒕𝒂𝑽𝒆𝒏𝒄 − 𝑫𝒂𝒕𝒂𝑪𝒂𝒍𝒄))

Equação 5

Onde:

DataVenc – DataCalc: diferença entre a data de vencimento e a data do cálculo da cobrança, em dias corridos.

Em se tratando de dias corridos, DataVenc deverá considerar a data original, independentemente de ela cair em fim de semana ou feriado para o usuário pagador.

Du: número de dias úteis entre o dia de realização do cálculo e a data de vencimento. Se o resultado da subtração for menor que zero, então Du deve ser zero:

𝑫𝒖 = 𝒎𝒂𝒙(𝟎; (𝑫𝒂𝒕𝒂𝑽𝒆𝒏𝒄 − 𝑫𝒂𝒕𝒂𝑪𝒂𝒍𝒄))

Equação 6

Onde:

DataVenc – DataCalc: diferença entre a data de vencimento e a data de cálculo da cobrança, em dias úteis.

Se o desconto foi informado por percentual por dia de antecipação, deverá ser calculado pela fórmula a seguir:

𝑽 = (𝑽

− 𝑽

𝑰𝒅𝒅

) × ( ) × 𝑫

𝒅 𝒐

𝒂

Equação 7

𝟏𝟎𝟎 ^𝑎

Onde:

Vd: valor do desconto;

Vo: valor original da cobrança;

Va: valor de abatimento aplicável à cobrança;

Idd: Percentual de desconto por dia de antecipação, informado com 2 casas decimais;

Dα: dias úteis ou corridos, conforme modalidade

Se dias corridos: Dα = Dc (vide Equação 5) Se dias úteis: Dα = Du (vide Equação 6)

Campos JSON referenciados:

calendario.dataDeVencimento valor.original (Vo)

valor.desconto.modalidade valor.desconto.valorPerc

Veja-se o exemplo a seguir:

valor.desconto.modalidade = 3 (“Valor por antecipação dia corrido”)

valor.desconto.valorPerc = “100.00”

Nesse exemplo, imagine que a data de vencimento é 10 de dezembro de 2020 e que o usuário realiza o pagamento em 7 de dezembro. O número de dias corridos antecipados foi 3 (10 – 7), tendo o usuário direito a um desconto de R$ 300,00 (3 x 100 reais) no valor a ser pago. Por outro lado, se o usuário paga na data de vencimento, não houve antecipação e, portanto, o usuário não terá direito a desconto.

O campo valor.desconto.modalidade pode assumir os seguintes valores:

Descrição	Domínio
Valor Fixo até a data informada	1
Percentual até a data informada	2
Valor por antecipação dia corrido	3
Valor por antecipação dia útil	4
Percentual por antecipação dia corrido	5
Percentual por antecipação dia útil	6

Cálculo do valor de juros (Vj)

Os juros podem ser informados em valor absoluto, por dia corrido ou útil; podem ainda ser referenciados em percentual ao dia, mês ou ano.

Valor absoluto diário:

Se os juros forem informados em valor absoluto, deverá ser calculado pela fórmula a seguir:

𝑽𝒋 = 𝑽𝒋𝒅 × 𝑫𝑎

Equação 8

Onde:

Vj: valor de juros aplicável pelo atraso no pagamento da cobrança; Vjd: valor de juros por dia de atraso no pagamento da cobrança; Dα: dias úteis ou corridos, conforme modalidade

Se dias corridos: Dα = Dc

Se dias úteis: Dα = Du

Dc número de dias corridos entre a data de vencimento e o dia de realização do cálculo informado pelo recebedor. Se o resultado da subtração for menor que zero, então Dc deve ser zero:

𝑫𝒄 = 𝒎𝒂𝒙(𝟎; (𝑫𝒂𝒕𝒂𝑪𝒂𝒍𝒄 − 𝑫𝒂𝒕𝒂𝒗𝒆𝒏𝒄))

Equação 9

Onde:

DataCalc – Datavenc: diferença entre a data de cálculo e a data do vencimento da cobrança, em dias corridos

Du: número de dias úteis entre a data de vencimento e o dia de realização do cálculo informado pelo recebedor. Se o resultado da subtração for menor que zero, então Du deve ser zero:

𝑫𝒖 = 𝒎𝒂𝒙(𝟎; (𝑫𝒂𝒕𝒂𝑪𝒂𝒍𝒄 − 𝑫𝒂𝒕𝒂𝒗𝒆𝒏𝒄))

Equação 10

Onde:

DataCalc – Datavenc: diferença entre a data de cálculo e a data do vencimento da cobrança, em dias úteis

Campos JSON referenciados:

calendario.dataDeVencimento (Datavenc) valor.juros.modalidade valor.juros.valorPerc (Vjd)

Se DataVenc cair em um fim de semana ou em um feriado para o usuário pagador, ela deve ser automaticamente prorrogada para o primeiro dia útil subsequente.

Percentual de juros diário, mensal ou anual:

Se os juros forem informados em percentual, o valor de juros deverá ser calculado pela fórmula a seguir:

𝑽𝒋

= (𝑽𝒐

− 𝑽𝒂

) × (

𝑰𝒋

(𝟏𝟎𝟎)

𝒏

) × 𝑫_𝑎

Equação 11

Onde:

Vj: valor de juros aplicável pelo atraso no pagamento da cobrança;

Vo: valor original da cobrança;

Va: valor de abatimento aplicável à cobrança;

𝑰𝒋

( )

( 𝟏𝟎𝟎 ) × 𝑫

: fator de juros, a ser calculado com precisão de 6 casas decimais sem

𝒏 𝒂

arredondamento (truncado);

Ij: taxa de juros (percentual), informada com 2 casas decimais;

Se modalidade for “dias corridos”, então:

n: 1, 30 ou 360, conforme a taxa de juros seja diária, mensal ou anual;

Dα = Dc (vide Equação 9).

Se modalidade for “dias úteis”, então:

n: 1, 21 ou 252, conforme a taxa de juros seja diária, mensal ou anual;

Dα = Du: (vide Equação 10).

Campos JSON referenciados:

calendario.dataDeVencimento (Datavenc) valor.juros.modalidade valor.juros.valorPerc (Ij) valor.original (Vo)

Se DataVenc cair em um fim de semana ou em um feriado para o usuário pagador, ela deve ser automaticamente prorrogada para o primeiro dia útil subsequente.

O valor calculado para Vj deve ser truncado com duas casas decimais.

O campo valor.juros.modalidade pode assumir os seguintes valores:

Descrição	Domínio
Valor (dias corridos)	1
Percentual ao dia (dias corridos)	2
Percentual ao mês (dias corridos)	3
Percentual ao ano (dias corridos)	4
Valor (dias úteis)	5
Percentual ao dia (dias úteis)	6
Percentual ao mês (dias úteis)	7
Percentual ao ano (dias úteis)	8

Cálculo do valor de multa (Vm)

A multa pode ser informada em valor absoluto ou como percentual da obrigação. Se a modalidade escolhida pelo recebedor for por valor fixo, então o valor da multa é o próprio valor informado pelo recebedor.

Se for informado o valor absoluto, então o valor da multa será calculado conforme a fórmula a seguir:

𝑽𝒎 = 𝑽𝒎 × 𝒌

Equação 12

Onde:

Vm: valor da multa

k(Dα): assume os seguintes valores, em função de Dα

𝑫𝑎

𝒌 =

𝒎𝒂𝒙(𝟏, 𝑫𝑎)

Equação 13

Onde:

Dα: calculado conforme descrito na Equação 9 ou na Equação 10, conforme os dias sem juros sejam dias corridos ou dias úteis.

Assim, K assume o valor 0 (zero) se Dα for zero; e assume o valor 1 (um), para valores positivos não nulos de Dα.

Se for informado o valor percentual, então o valor da multa será calculado conforme a fórmula a seguir:

𝑽𝒎

= (𝑽𝒐

− 𝑽𝒂

𝑰𝒎

) × × 𝒌

𝟏𝟎𝟎

Equação 14

Onde:

Vm: valor da multa;

Vo: valor original da cobrança;

Va: valor de abatimento aplicável à cobrança;

Im: percentual de multa, informado com 2 casas decimais;

k(Dα): ver Equação 13.

Campos JSON referenciados:

calendario.dataDeVencimento (Datavenc)

valor.multa.modalidade

valor.multa.valorPerc (Vm ou Im ,conforme a modalidade da multa)

Se DataVenc cair em um fim de semana ou em um feriado para o usuário pagador, ela deve ser automaticamente prorrogada para o primeiro dia útil subsequente.

O valor calculado para Vm deve ser truncado com duas casas decimais.

O campo valor.multa.modalidade pode assumir os seguintes valores:

Descrição	Domínio
Valor fixo	1
Percentual	2

ANEXO IV – Prazos para implementação das funcionalidades

Introdução

O presente anexo tem por objetivo apresentar quadro informativo com os prazos para implementação das funcionalidades de oferta obrigatória no âmbito da API Pix.

Data da atualização: 26/08/2021

Prazo para implementação

Funcionalidade

29/11/2021

Disponibilização do Pix com a finalidade de saque ou de troco

De acordo com cronograma de implementação do Open

Banking

Iniciação pelo prestador de serviço de iniciação

Cookie	Duração	Descrição
cookielawinfo-checkbox-analytics	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Analytics".
cookielawinfo-checkbox-functional	11 months	The cookie is set by GDPR cookie consent to record the user consent for the cookies in the category "Functional".
cookielawinfo-checkbox-necessary	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookies is used to store the user consent for the cookies in the category "Necessary".
cookielawinfo-checkbox-others	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Other.
cookielawinfo-checkbox-performance	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Performance".
viewed_cookie_policy	11 months	The cookie is set by the GDPR Cookie Consent plugin and is used to store whether or not user has consented to the use of cookies. It does not store any personal data.

Talvez você goste também

Passo a passo para Requerer o Passaporte

INTRODUÇÃO AO DIREITO AMBIENTAL BRASILEIRO PDF

Geografia política

Deixe um comentário Cancelar resposta