Pix

Descrição detalhada

Operações destinadas ao Pix do SPI (Sistema de Pagamentos Instantâneos).

Pix

As APIs do módulo Pix são destinadas ao uso das funcionalidades de assinatura, verificação, envio e recebimentos de requisições HTTP Pix.

Rede

O HSM não faz acessos direto aos servidores Pix/DICT, sendo posicionado na rede para uso dos servidores internos do PSP.

--- title: Diagrama físico de rede --- %%{ init: { 'flowchart': { 'curve': 'basis' } } }%% flowchart LR psp[Aplicação PSP] hsm[HSM] fw[Firewall] rsfn{{RSFN}} spi["SPI (Pix/Dict)"] subgraph redepsp [Rede PSP] hsm <--> psp psp <--> fw end fw <--> rsfn rsfn <--> spi

Assinatura e verificação

As APIs de assinatura e verificação Pix tem como base o padrão ISO 20.022, as APIs DICT seguem o formato XMLDSig, ambas definidas pelo SPI no documento "Anexo IV – Manual de Segurança".

As funções de API para uso com assinatura Pix e DICT exigem o armazenamento interno no HSM dos certificados digitais para assinatura digital e da cadeia completa de confiança dos certificados para verificação.

Para um gravar um certificado digital (ou arquivo) no HSM utilize a console de gerenciamento remoto ou a API DWriteFile().

O certificado digital para assinatura deverá estar codificado no formato binário ASN1 DER e também seguir o padrão X.509 . O arquivo contendo a cadeia de confiança para verificação de assinatura digital deverá estar codificada no formato PKCS#7 (Public Key Cryptography Standard #7 – Cryptographic Message Syntax Standard).

As funções de assinatura e validação JWS Pix seguem a RFC 7515 e a documentação do SPI.

Requisições HTTP

As APIs de requisições HTTP Pix disponibilizam a comunicação segura HTTP com os servidores Pix ou DICT, utilizando as chaves e certificados protegidos pelo HSM.

As funções de comunicação segura padrão Pix que seguem as definições descritas nos seguintes documentos: "Anexo IV – Manual de Segurança", "Especificações técnicas e de negócio do ecossistema de pagamentos instantâneos brasileiro" e "Anexo III - Manual das Interfaces de comunicação" definidos no SPI.

Funcionamento

A conexão segura é feita entre o servidor do PSP e o servidor do Pix/DICT, o HSM é utilizado apenas para uso de objetos e chave privada do PSP.

O acesso ao HSM ocorre apenas no momento do handshake TLS. Após o fechamento do túnel a comunicação é mantida apenas entre o servidor do PSP e o servidor do Pix/DICT.

--- title: Visão geral handshake TLS utilizando o HSM --- %%{ init: { 'flowchart': { 'curve': 'basis' }} }%% sequenceDiagram participant hsm as HSM participant psp as PSP participant spi as SPI (Pix/Dict) Note over hsm: certificado TLS psp ->> spi: Inicia handshake TLS spi ->> psp: Requisita
credenciais do PSP psp ->> psp: Autentica SPI psp ->> hsm: Requisita informações
de autenticação hsm ->> hsm: Gera assinatura
para autenticação TLS destroy hsm hsm ->> psp: Envia assinatura psp ->> spi: Envia dados
de autenticação spi ->> spi: Autentica PSP loop Canal TLS %% necessário manter o espaço após o spi: (ou usar um text) psp-->spi: psp ->> spi: Requisição
Pix/Dict spi ->> psp: Resposta end

Uma conexão HTTP está associada ao handle de sessão do HSM que foi utilizado na abertura da sessão HTTP. Isto permite manter a associação e o acesso aos objetos de conexão (chave privada, certificado e cadeia de certificados) dentro do HSM.

--- title: Handle de sessão do HSM --- %%{ init: { 'flowchart': { 'curve': 'basis' } } }%% flowchart TB hsm[Sessão HSM] http[Sessão HTTP] %% necessário manter os espaços após o subpgraph (ou usar um text) subgraph hsm http end

• A abertura da sessão HTTP só é feita nas chamadas de requisição HTTP Pix.
• O fechamento da sessão HTTP acontece quando sua respectiva sessão do HSM é fechada físicamente (fechamento da sessão com cache desabilitado ou explicitamente definido para fechamento físico da sessão).
• Uma sessão fechada (sem definição explícita de fechamento físico e sem cache desabilitado) não fecha a sessão HTTP associada pois não há fechamento físico da sessão.
• A sessão HTTP é reutilizada em chamadas HTTP posteriores, independente do tipo de operação HTTP (POST, GET, DELETE ou PUT) utilizada.
• A sessão HTTP não é reutilizada quando os parâmetros de conexão (IP, porta) são alterados.

Por exemplo: suponha que uma operação de POST é feita, a sessão HTTP é mantida aberta dentro do handle de sessão do HSM. Ao fechar a sessão do HSM (sem desabilitar o cache de sessões) a sessão é guardada no cache de sessões juntamente com a sessão HTTP. Pedindo a abertura de uma nova sessão, a sessão guardada em cache será retornada. Ao reutilizar o handle de sessão do HSM para uma operação GET, a sessão HTTP é reutilizada pois estava guardada no handle de sessão do HSM.

Boas práticas

Geral

1. Reutilizar sessões (se beneficiar do cache de sessões). Use o cache de sessões do HSM e ganhe performance reutilizando as sessões do HSM e HTTP. Neste caso recomenda-se abrir uma sessão, fazer as operações que deseja e logo após fechar; permitindo que a sessão possa ser reutilizada rapidamente, diminuindo assim o tempo ocioso.
2. Garantir o fechamento das sessões. O fechamento das sessões garante a liberação do recurso, tanto no HSM quanto no cliente. Certifique-se que as sessões sejam fechadas inclusive nas operações com código de retorno diferente de sucesso.
3. Utilizar sessões concorrentes. Usar sessões concorrentes/paralelas com o HSM ajuda a extrair o máximo de performance. Deve-se atentar para o excesso de sessões com os HSMs, para não causar um uso desnecessário de recursos. A curva de throughput tende a subir e encontrar um platô.

Requisições HTTP Pix

1. Definir um intervalo de recarregamento de objetos de conexão. É possível otimizar a quantidade de vezes em que ocorre o carregamento das chaves e objetos do HSM definindo um intervalo de recarregamento de objetos do HSM. Como a atualização de chave/certificado/cadeia da instituição é feita poucas vezes e de forma programada, é vantajoso definir um intervalo de recarregamento desses objetos. Atentar para timeouts de ativos de rede menores do que esse valor, isto evita desconexões prematuras e erros desnecessários. Veja mais detalhes e como configurar aqui.

Configurações Importantes

Geral

1. Definir os timeouts de conexão com o HSM. Quando não definido o timeout do HSM o padrão é o do sistema operacional. Em casos de falha de conexão a aplicação pode ficar em espera excessiva. É importante SEMPRE definir o timeout de envio e recebimento do HSM. Outros parâmetros de conexão podem ser vistos aqui.

Requisições HTTP Pix

1. Definir os timeouts da operação HTTP. Quando não definido o timeout padrão da operação HTTP é sem limite. Em casos de falha de conexão HTTP a aplicação pode ficar em espera indefinidamente. É importante SEMPRE definir o timeout nas chamadas de requisições HTTP.

Funções
byte[]	signPIX (String strKeyId, String strCertId, int nFlags, byte[] baUnsignedPIXEnvelope) throws TacException
	Assina digitalmente um XML no formato ISO 20.022 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
byte[]	signPIX (String strKeyId, String strCertId, byte[] baUnsignedPIXEnvelope) throws TacException
	Assina digitalmente um XML no formato ISO 20.022 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
byte[]	signPIXDict (String strKeyId, String strCertId, int nFlags, byte[] baUnsignedDictEnvelope) throws TacException
	Assina digitalmente um XML no formato XMLDSig seguindo o padrão DICT definido no SPI (Sistema de Pagamentos Instantâneos).
byte[]	signPIXDict (String strKeyId, String strCertId, byte[] baUnsignedDictEnvelope) throws TacException
	Assina digitalmente um XML no formato XMLDSig seguindo o padrão DICT definido no SPI (Sistema de Pagamentos Instantâneos).
boolean	verifyPIX (String strChainId, String strCRLId, int nFlags, byte[] baSignedPIXEnvelope) throws TacException
	Verifica a assinatura de um documento XML assinado digitalmente no formato ISO 20.022 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
boolean	verifyPIX (String strChainId, String strCRLId, byte[] baSignedPIXEnvelope) throws TacException
	Verifica a assinatura de um documento XML assinado digitalmente no formato ISO 20.022 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
boolean	verifyPIXDict (String strChainId, String strCRLId, int nFlags, byte[] baSignedDictEnvelope) throws TacException
	Verifica a assinatura de um documento XML assinado digitalmente no formato XMLDSig seguindo o padrão DICT definido no SPI (Sistema de Pagamentos Instantâneos).
boolean	verifyPIXDict (String strChainId, String strCRLId, byte[] baSignedDictEnvelope) throws TacException
	Verifica a assinatura de um documento XML assinado digitalmente no formato XMLDSig seguindo o padrão DICT definido no SPI (Sistema de Pagamentos Instantâneos).
byte[]	signPIXJWS (String strKeyId, byte[] baHeader, byte[] baPayload) throws TacException
	Faz uma assinatura JWS RFC 7515 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
String	signPIXJWS (String strKeyId, String strHeader, String strPayload) throws TacException
	Faz uma assinatura JWS RFC 7515 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
JwsComponents	checkPIXJWS (String strChainId, String strCRLId, byte[] baJWS, int nFlags) throws TacException
	Valida um JWS assinado RFC 7515 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
JwsComponents	checkPIXJWS (String strChainId, String strCRLId, String strJWS, int nFlags) throws TacException
	Valida um JWS assinado RFC 7515 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
boolean	checkPIXJWS (String strChainId, String strCRLId, byte[] baJWS) throws TacException
	Valida um JWS assinado RFC 7515 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
boolean	checkPIXJWS (String strChainId, String strCRLId, String strJWS) throws TacException
	Valida um JWS assinado RFC 7515 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
PIXResponse	postPIX (String strKeyId, String strCertId, String strPIXCertChainId, String strURL, String[] straRequestHeaderList, byte[] baRequestData, int nTimeOut, boolean bUseGzip, boolean bVerifyHostName) throws TacException
	Faz uma requisição segura HTTP POST seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
PIXResponse	postPIX (String strKeyId, String strCertId, String strPIXCertChainId, String strURL, String[] straRequestHeaderList, byte[] baRequestData, int nTimeOut, int nParam) throws TacException
	Faz uma requisição segura HTTP POST seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
PIXResponse	putPIX (String strKeyId, String strCertId, String strPIXCertChainId, String strURL, String[] straRequestHeaderList, byte[] baRequestData, int nTimeOut, boolean bUseGzip, boolean bVerifyHostName) throws TacException
	Faz uma requisição segura HTTP PUT seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
PIXResponse	putPIX (String strKeyId, String strCertId, String strPIXCertChainId, String strURL, String[] straRequestHeaderList, byte[] baRequestData, int nTimeOut, int nParam) throws TacException
	Faz uma requisição segura HTTP PUT seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
PIXResponse	getPIX (String strKeyId, String strCertId, String strPIXCertChainId, String strURL, String[] straRequestHeaderList, int nTimeOut, boolean bUseGzip, boolean bVerifyHostName) throws TacException
	Faz uma requisição segura HTTP GET seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
PIXResponse	getPIX (String strKeyId, String strCertId, String strPIXCertChainId, String strURL, String[] straRequestHeaderList, int nTimeOut, int nParam) throws TacException
	Faz uma requisição segura HTTP GET seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
PIXResponse	deletePIX (String strKeyId, String strCertId, String strPIXCertChainId, String strURL, String[] straRequestHeaderList, int nTimeOut, boolean bUseGzip, boolean bVerifyHostName) throws TacException
	Faz uma requisição segura HTTP DELETE seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
PIXResponse	deletePIX (String strKeyId, String strCertId, String strPIXCertChainId, String strURL, String[] straRequestHeaderList, int nTimeOut, int nParam) throws TacException
	Faz uma requisição segura HTTP DELETE seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
PIXHTTPReqDetails	getPIXHTTPReqDetails () throws TacException
	Recupera os detalhes da última requisição PIX HTTP (POST, GET...) feita nesta sessão.
long	getPIXHTTPReqCode () throws TacException
	Recupera o código de retorno da última requisição PIX HTTP (POST, GET...) feita nesta sessão.

Funções

signPIX() [1/2]

byte[] signPIX	(	String	strKeyId,
		String	strCertId,
		int	nFlags,
		byte[]	baUnsignedPIXEnvelope ) throws TacException

Assina digitalmente um XML no formato ISO 20.022 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Parâmetros

strKeyId	Nome da chave privada utilizada para assinatura. Correspondente a um certificado CPIA.
strCertId	Nome do certificado digital utilizado para assinatura. Certificado Digital do PSP cadastrado no SPI para assinatura, também conhecido como CPIA ou CERTPIA.
nFlags	Opções de assinatura. Passar 0. Caso precise de alguma opção adicional os seguintes valores são aceitos. Valor Significado TacNDJavaLib.PIX_SIGN_RNS Habilita o uso de namespaces relativas.
baUnsignedPIXEnvelope	XML a ser assinado.

Retorna

Exceções

TacException

Lança exceção no caso de erros na assinatura

Anotações

Recomendamos utilizar a tag de assinatura utilizando o fechamento completo, como visto abaixo, por motivos de performance.

<Sgntr></Sgntr>

A tag com fechamento simples também é aceita, ver abaixo.

<Sgntr/>

signPIX() [2/2]

byte[] signPIX	(	String	strKeyId,
		String	strCertId,
		byte[]	baUnsignedPIXEnvelope ) throws TacException

Assina digitalmente um XML no formato ISO 20.022 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Parâmetros

strKeyId	Nome da chave privada utilizada para assinatura. Correspondente a um certificado CPIA.
strCertId	Nome do certificado digital utilizado para assinatura. Certificado Digital do PSP cadastrado no SPI para assinatura, também conhecido como CPIA ou CERTPIA.
baUnsignedPIXEnvelope	XML a ser assinado.

Retorna

Exceções

TacException

Lança exceção no caso de erros na assinatura

Anotações

Recomendamos utilizar a tag de assinatura utilizando o fechamento completo, como visto abaixo, por motivos de performance.

<Sgntr></Sgntr>

A tag com fechamento simples também é aceita, ver abaixo.

<Sgntr/>

signPIXDict() [1/2]

byte[] signPIXDict	(	String	strKeyId,
		String	strCertId,
		int	nFlags,
		byte[]	baUnsignedDictEnvelope ) throws TacException

Assina digitalmente um XML no formato XMLDSig seguindo o padrão DICT definido no SPI (Sistema de Pagamentos Instantâneos).

Parâmetros

strKeyId	Nome da chave privada utilizada para assinatura. Correspondente a um certificado CPIA.
strCertId	Nome do certificado digital utilizado para assinatura. Certificado Digital do PSP cadastrado no SPI para assinatura, também conhecido como CPIA ou CERTPIA.
nFlags	Reservado para uso futuro (deve ser 0).
baUnsignedDictEnvelope	XML a ser assinado.

Retorna

Exceções

TacException

Lança exceção no caso de erros na assinatura

Anotações

Não incluir a tag de assinatura, ela será adicionada automaticamente.

signPIXDict() [2/2]

byte[] signPIXDict	(	String	strKeyId,
		String	strCertId,
		byte[]	baUnsignedDictEnvelope ) throws TacException

Assina digitalmente um XML no formato XMLDSig seguindo o padrão DICT definido no SPI (Sistema de Pagamentos Instantâneos).

Parâmetros

strKeyId	Nome da chave privada utilizada para assinatura. Correspondente a um certificado CPIA.
strCertId	Nome do certificado digital utilizado para assinatura. Certificado Digital do PSP cadastrado no SPI para assinatura, também conhecido como CPIA ou CERTPIA.
baUnsignedDictEnvelope	XML a ser assinado.

Retorna

Exceções

TacException

Lança exceção no caso de erros na assinatura

Anotações

Não incluir a tag de assinatura, ela será adicionada automaticamente.

verifyPIX() [1/2]

boolean verifyPIX	(	String	strChainId,
		String	strCRLId,
		int	nFlags,
		byte[]	baSignedPIXEnvelope ) throws TacException

Verifica a assinatura de um documento XML assinado digitalmente no formato ISO 20.022 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Parâmetros

strChainId	Nome da cadeia PKCS#7 (armazenada internamente no HSM) do certificado utilizado na assinatura. A cadeia deverá ser completa contendo da AC raiz até o próprio certificado utilizado na assinatura. Esta formatação é necessária porque a mensagem XML de Pix não traz o certificado usado na assinatura. Opcionalmente, pode ser passado apenas o certificado X.509 utilizado para assinar, no lugar da cadeia completa. A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias. Importante observar que no caso de um objeto PKCS#7 do HSM que contenha múltiplas cadeias, a presença de um certificado expirado em qualquer das cadeias irá gerar na verificação um código de retorno de assinatura válida com certificado expirado (código diferente de zero), mesmo que a assinatura tenha sido realizada com certificado de cadeia não expirada; fica a cargo da aplicação o tratamento correto conforme a política local.
strCRLId	Nome da Lista de Certificados Revogados (CRL) – armazenada internamente no HSM - onde o certificado digital será verificado. É possível passar NULL indicando que não há uma CRL para verificação.
nFlags	Reservado para uso futuro (deve ser 0).
baSignedPIXEnvelope	XML assinado.

Retorna

true se a assinatura for válida e false se for inválida.

Exceções

TacException

verifyPIX() [2/2]

boolean verifyPIX	(	String	strChainId,
		String	strCRLId,
		byte[]	baSignedPIXEnvelope ) throws TacException

Verifica a assinatura de um documento XML assinado digitalmente no formato ISO 20.022 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Parâmetros

strChainId	Nome da cadeia PKCS#7 (armazenada internamente no HSM) do certificado utilizado na assinatura. A cadeia deverá ser completa contendo da AC raiz até o próprio certificado utilizado na assinatura. Esta formatação é necessária porque a mensagem XML de Pix não traz o certificado usado na assinatura. Opcionalmente, pode ser passado apenas o certificado X.509 utilizado para assinar, no lugar da cadeia completa. A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias. Importante observar que no caso de um objeto PKCS#7 do HSM que contenha múltiplas cadeias, a presença de um certificado expirado em qualquer das cadeias irá gerar na verificação um código de retorno de assinatura válida com certificado expirado (código diferente de zero), mesmo que a assinatura tenha sido realizada com certificado de cadeia não expirada; fica a cargo da aplicação o tratamento correto conforme a política local.
strCRLId	Nome da Lista de Certificados Revogados (CRL) – armazenada internamente no HSM - onde o certificado digital será verificado. É possível passar NULL indicando que não há uma CRL para verificação.
baSignedPIXEnvelope	XML assinado.

Retorna

true se a assinatura for válida e false se for inválida.

Exceções

TacException

verifyPIXDict() [1/2]

boolean verifyPIXDict	(	String	strChainId,
		String	strCRLId,
		int	nFlags,
		byte[]	baSignedDictEnvelope ) throws TacException

Verifica a assinatura de um documento XML assinado digitalmente no formato XMLDSig seguindo o padrão DICT definido no SPI (Sistema de Pagamentos Instantâneos).

Parâmetros

strChainId	Nome da cadeia PKCS#7 (armazenada internamente no HSM) do certificado utilizado na assinatura. A cadeia deverá ser completa contendo da AC raiz até o próprio certificado utilizado na assinatura. Esta formatação é necessária porque a mensagem XML de Pix não traz o certificado usado na assinatura. Opcionalmente, pode ser passado apenas o certificado X.509 utilizado para assinar, no lugar da cadeia completa. A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias. Importante observar que no caso de um objeto PKCS#7 do HSM que contenha múltiplas cadeias, a presença de um certificado expirado em qualquer das cadeias irá gerar na verificação um código de retorno de assinatura válida com certificado expirado (código diferente de zero), mesmo que a assinatura tenha sido realizada com certificado de cadeia não expirada; fica a cargo da aplicação o tratamento correto conforme a política local.
strCRLId	Nome da Lista de Certificados Revogados (CRL) – armazenada internamente no HSM - onde o certificado digital será verificado. É possível passar NULL indicando que não há uma CRL para verificação.
nFlags	Reservado para uso futuro (deve ser 0).
baSignedDictEnvelope	XML assinado.

Retorna

true se a assinatura for válida e false se for inválida.

Exceções

TacException

verifyPIXDict() [2/2]

boolean verifyPIXDict	(	String	strChainId,
		String	strCRLId,
		byte[]	baSignedDictEnvelope ) throws TacException

Verifica a assinatura de um documento XML assinado digitalmente no formato XMLDSig seguindo o padrão DICT definido no SPI (Sistema de Pagamentos Instantâneos).

Parâmetros

strChainId	Nome da cadeia PKCS#7 (armazenada internamente no HSM) do certificado utilizado na assinatura. A cadeia deverá ser completa contendo da AC raiz até o próprio certificado utilizado na assinatura. Esta formatação é necessária porque a mensagem XML de Pix não traz o certificado usado na assinatura. Opcionalmente, pode ser passado apenas o certificado X.509 utilizado para assinar, no lugar da cadeia completa. A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias. Importante observar que no caso de um objeto PKCS#7 do HSM que contenha múltiplas cadeias, a presença de um certificado expirado em qualquer das cadeias irá gerar na verificação um código de retorno de assinatura válida com certificado expirado (código diferente de zero), mesmo que a assinatura tenha sido realizada com certificado de cadeia não expirada; fica a cargo da aplicação o tratamento correto conforme a política local.
strCRLId	Nome da Lista de Certificados Revogados (CRL) – armazenada internamente no HSM - onde o certificado digital será verificado. É possível passar NULL indicando que não há uma CRL para verificação.
baSignedDictEnvelope	XML assinado.

Retorna

true se a assinatura for válida e false se for inválida.

Exceções

TacException

signPIXJWS() [1/2]

byte[] signPIXJWS	(	String	strKeyId,
		byte[]	baHeader,
		byte[]	baPayload ) throws TacException

Faz uma assinatura JWS RFC 7515 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Parâmetros

strKeyId	Nome da chave privada utilizada para assinatura. Como definido no manual de segurança do PIX
baHeader	Header JWS para assinatura. Pelo menos o parâmetro de cabeçalho alg deverá ser informado. Valores aceitos para alg. Valor Significado RS256 RSA 2048 PKCS#1v5 RS384 RSA 3072 PKCS#1v5 RS512 RSA 4096 PKCS#1v5 PS256 RSA 2048 PSS PS384 RSA 3072 PSS PS512 RSA 4096 PSS ES256 ECC SECP256R1 ES384 ECC SECP384R1 ES512 ECC SECP521R1
baPayload	Payload JWS para assinatura.

Retorna

JWS assinado.

Exceções

TacException

Lança exceção no caso de erros na assinatura

Anotações

Utiliza o formato Compact Serialization descrito na Section-3.1 da RFC 7515.

signPIXJWS() [2/2]

String signPIXJWS	(	String	strKeyId,
		String	strHeader,
		String	strPayload ) throws TacException

Faz uma assinatura JWS RFC 7515 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Parâmetros

strKeyId	Nome da chave privada utilizada para assinatura. Como definido no manual de segurança do PIX
strHeader	Header JWS para assinatura. Pelo menos o parâmetro de cabeçalho alg deverá ser informado. Valores aceitos para alg. Valor Significado RS256 RSA 2048 PKCS#1v5 RS384 RSA 3072 PKCS#1v5 RS512 RSA 4096 PKCS#1v5 PS256 RSA 2048 PSS PS384 RSA 3072 PSS PS512 RSA 4096 PSS ES256 ECC SECP256R1 ES384 ECC SECP384R1 ES512 ECC SECP521R1
strPayload	Payload JWS para assinatura.

Retorna

JWS assinado.

Exceções

TacException

Lança exceção no caso de erros na assinatura

Anotações

Utiliza o formato Compact Serialization descrito na Section-3.1 da RFC 7515.

checkPIXJWS() [1/4]

JwsComponents checkPIXJWS	(	String	strChainId,
		String	strCRLId,
		byte[]	baJWS,
		int	nFlags ) throws TacException

Valida um JWS assinado RFC 7515 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Parâmetros

strChainId	Nome da cadeia PKCS#7 (armazenada internamente no HSM) do certificado utilizado na assinatura. A cadeia deverá ser completa contendo da AC raiz até o próprio certificado utilizado na assinatura. Esta formatação é necessária porque a mensagem XML de Pix não traz o certificado usado na assinatura. Opcionalmente, pode ser passado apenas o certificado X.509 utilizado para assinar, no lugar da cadeia completa. A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias. Importante observar que no caso de um objeto PKCS#7 do HSM que contenha múltiplas cadeias, a presença de um certificado expirado em qualquer das cadeias irá gerar na verificação um código de retorno de assinatura válida com certificado expirado (código diferente de zero), mesmo que a assinatura tenha sido realizada com certificado de cadeia não expirada; fica a cargo da aplicação o tratamento correto conforme a política local.
strCRLId	Nome da Lista de Certificados Revogados (CRL) – armazenada internamente no HSM - onde o certificado digital será verificado. É possível passar NULL indicando que não há uma CRL para verificação.
baJWS	JWS assinado.
nFlags	Opções de verificação. Deverá ser 0.

Retorna

Classe JwsComponents que conterá o código de retorno, o Header e o Payload da mensagem assinada.

Exceções

TacException

checkPIXJWS() [2/4]

JwsComponents checkPIXJWS	(	String	strChainId,
		String	strCRLId,
		String	strJWS,
		int	nFlags ) throws TacException

Valida um JWS assinado RFC 7515 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Parâmetros

strChainId	Nome da cadeia PKCS#7 (armazenada internamente no HSM) do certificado utilizado na assinatura. A cadeia deverá ser completa contendo da AC raiz até o próprio certificado utilizado na assinatura. Esta formatação é necessária porque a mensagem XML de Pix não traz o certificado usado na assinatura. Opcionalmente, pode ser passado apenas o certificado X.509 utilizado para assinar, no lugar da cadeia completa. A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias. Importante observar que no caso de um objeto PKCS#7 do HSM que contenha múltiplas cadeias, a presença de um certificado expirado em qualquer das cadeias irá gerar na verificação um código de retorno de assinatura válida com certificado expirado (código diferente de zero), mesmo que a assinatura tenha sido realizada com certificado de cadeia não expirada; fica a cargo da aplicação o tratamento correto conforme a política local.
strCRLId	Nome da Lista de Certificados Revogados (CRL) – armazenada internamente no HSM - onde o certificado digital será verificado. É possível passar NULL indicando que não há uma CRL para verificação.
strJWS	JWS assinado.
nFlags	Opções de verificação. Deverá ser 0.

Retorna

Classe JwsComponents que conterá o código de retorno, o Header e o Payload da mensagem assinada.

Exceções

TacException

checkPIXJWS() [3/4]

boolean checkPIXJWS	(	String	strChainId,
		String	strCRLId,
		byte[]	baJWS ) throws TacException

Valida um JWS assinado RFC 7515 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Parâmetros

strChainId	Nome da cadeia PKCS#7 (armazenada internamente no HSM) do certificado utilizado na assinatura. A cadeia deverá ser completa contendo da AC raiz até o próprio certificado utilizado na assinatura. Esta formatação é necessária porque a mensagem XML de Pix não traz o certificado usado na assinatura. Opcionalmente, pode ser passado apenas o certificado X.509 utilizado para assinar, no lugar da cadeia completa. A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias. Importante observar que no caso de um objeto PKCS#7 do HSM que contenha múltiplas cadeias, a presença de um certificado expirado em qualquer das cadeias irá gerar na verificação um código de retorno de assinatura válida com certificado expirado (código diferente de zero), mesmo que a assinatura tenha sido realizada com certificado de cadeia não expirada; fica a cargo da aplicação o tratamento correto conforme a política local.
strCRLId	Nome da Lista de Certificados Revogados (CRL) – armazenada internamente no HSM - onde o certificado digital será verificado. É possível passar NULL indicando que não há uma CRL para verificação.
baJWS	JWS assinado.

Retorna

Verdadeiro se a checagem for efetuada com sucesso.

Exceções

TacException

checkPIXJWS() [4/4]

boolean checkPIXJWS	(	String	strChainId,
		String	strCRLId,
		String	strJWS ) throws TacException

Valida um JWS assinado RFC 7515 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Parâmetros

strChainId	Nome da cadeia PKCS#7 (armazenada internamente no HSM) do certificado utilizado na assinatura. A cadeia deverá ser completa contendo da AC raiz até o próprio certificado utilizado na assinatura. Esta formatação é necessária porque a mensagem XML de Pix não traz o certificado usado na assinatura. Opcionalmente, pode ser passado apenas o certificado X.509 utilizado para assinar, no lugar da cadeia completa. A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias. Importante observar que no caso de um objeto PKCS#7 do HSM que contenha múltiplas cadeias, a presença de um certificado expirado em qualquer das cadeias irá gerar na verificação um código de retorno de assinatura válida com certificado expirado (código diferente de zero), mesmo que a assinatura tenha sido realizada com certificado de cadeia não expirada; fica a cargo da aplicação o tratamento correto conforme a política local.
strCRLId	Nome da Lista de Certificados Revogados (CRL) – armazenada internamente no HSM - onde o certificado digital será verificado. É possível passar NULL indicando que não há uma CRL para verificação.
strJWS	JWS assinado.

Retorna

Verdadeiro se a checagem for efetuada com sucesso.

Exceções

TacException

postPIX() [1/2]

PIXResponse postPIX	(	String	strKeyId,
		String	strCertId,
		String	strPIXCertChainId,
		String	strURL,
		String[]	straRequestHeaderList,
		byte[]	baRequestData,
		int	nTimeOut,
		boolean	bUseGzip,
		boolean	bVerifyHostName ) throws TacException

Faz uma requisição segura HTTP POST seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Usa o header HTTP inicial básico.

Observação

Faça as configurações de timeout. Veja mais detalhes na seção Boas práticas.

Parâmetros

strKeyId	Nome da chave privada utilizada para fechamento do túnel. Correspondente a um certificado CPIC.
strCertId	Nome do certificado utilizado para fechamento do túnel. Certificado Digital do PSP cadastrado no SPI para conexão, também conhecido como CPIC ou CERTPIC.
strPIXCertChainId	Nome da cadeia PKCS#7 utilizada para verificar o servidor PIX (ICOM ou DICT). A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias.
strURL	URL do servidor PIX (ICOM ou DICT).
straRequestHeaderList	Linhas contendo os headers HTTP customizados que serão utilizados na requisição. Pode ser passado nulo caso queira utilizar o header padrão sem alterações. Essa opção irá sobrescrever os headers padrão, caso haja sobreposição. Para remover um header passe o nome do header sem valor (Ex. Accept:). Para incluir um header sem conteúdo utilize ; ao invés de : (Ex. Accept;). NÃO utilizar terminadores CRLF nos headers. A passagem desses terminadores poderá causar comportamentos indesejados. A formatação será feita internamente. Esta opção não pode ser utilizada para alterar a primeira linha da requisição (Ex. POST, PUT, GET, DELETE), que não é um header. Deve-se utilizar a API correspondente, descrita neste manual. O header inicial padrão inclui Host, User-Agent e Content-Length.
baRequestData	Dados enviados na requisição.
nTimeOut	Tempo de timeout da operação em milisegundos. Pode ser passado 0 para não ter tempo de timeout.
bUseGzip	Faz a compressão gzip automática dos dados de requisição. Inclui automaticamente os headers necessários (Content-Encoding e Accept-Encoding).
bVerifyHostName	Verifica certificado com o nome do host.

Retorna

Resposta da requisição.

Exceções

TacException

Lança exceção no caso de erros na assinatura

Anotações

Executa uma requisição segura seguindo o padrão PIX definida no SPI nos documentos: "Anexo IV – Manual de Segurança", "Especificações técnicas e de negócio do ecossistema de pagamentos instantâneos brasileiro" e "Anexo III - Manual das Interfaces de comunicação" definidos no SPI.
O túnel negociado é o TLS versão 1.2 com autenticação mútua, utilizando o protocolo HTTP versão 1.1 com Cipher Suite mínima de ECDHE-RSA-AES-128-GCM-SHA256.

Esta API irá descompactar automaticamente uma resposta que venha compactada no padrão gzip. Caso opte pela compactação dos dados de envio, a compactação deverá ser feita pelo chamador da API, no formato gzip.

Esta requisição utiliza os seguintes headers como padrão.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", onde 0.0.0.0 é a versão da biblioteca cliente do HSM utilizada.

A validação de certificado com o nome do host é feita verificando se os campos Common Name field ou Subject Alternate Name do certificado coincidem com o host name da URL passada como parâmetro.

Ao fazer um request HTTP são feitas 2 operações, uma de uso dos objetos do HSM (chave privada, certificado e cadeia, usados para autenticação do túnel) e outra de abertura da sessão HTTP com o servidor HTTP.
Para otimizar os recursos a sessão com o servidor HTTP é mantida aberta e guardada em cache, igualmente, a sessão com o HSM é guardada em cache por padrão (a sessão do HSM pode ser, opcionalmente, definida para não ser guardada em cache).
A sessão HTTP fica associada à sessão aberta com o HSM, isto significa que para reutilizar uma sessão HTTP deve-se usar a mesma sessão do HSM utilizada anteriormente para abrir a sessão HTTP.
A sessão HTTP é fechada físicamente quando a sessão com o HSM é fechada físicamente.
A sessão do HSM e a HTTP tem afinidade thread-sessão, não podendo ser utilizada simultâneamente entre várias threads.

O ajuste do Long Polling é feito definindo o timeout da operação HTTP (POST/GET/DELETE) de acordo com as configurações do servidor HTTP.

postPIX() [2/2]

PIXResponse postPIX	(	String	strKeyId,
		String	strCertId,
		String	strPIXCertChainId,
		String	strURL,
		String[]	straRequestHeaderList,
		byte[]	baRequestData,
		int	nTimeOut,
		int	nParam ) throws TacException

Faz uma requisição segura HTTP POST seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Observação

Faça as configurações de timeout. Veja mais detalhes na seção Boas práticas.

Parâmetros

strKeyId	Nome da chave privada utilizada para fechamento do túnel. Correspondente a um certificado CPIC.
strCertId	Nome do certificado utilizado para fechamento do túnel. Certificado Digital do PSP cadastrado no SPI para conexão, também conhecido como CPIC ou CERTPIC.
strPIXCertChainId	Nome da cadeia PKCS#7 utilizada para verificar o servidor PIX (ICOM ou DICT). A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias.
strURL	URL do servidor PIX (ICOM ou DICT).
straRequestHeaderList	Linhas contendo os headers HTTP customizados que serão utilizados na requisição. Pode ser passado nulo caso queira utilizar o header padrão sem alterações. Essa opção irá sobrescrever os headers padrão, caso haja sobreposição. Para remover um header passe o nome do header sem valor (Ex. Accept:). Para incluir um header sem conteúdo utilize ; ao invés de : (Ex. Accept;). NÃO utilizar terminadores CRLF nos headers. A passagem desses terminadores poderá causar comportamentos indesejados. A formatação será feita internamente. Esta opção não pode ser utilizada para alterar a primeira linha da requisição (Ex. POST, PUT, GET, DELETE), que não é um header. Deve-se utilizar a API correspondente, descrita neste manual. O header inicial padrão inclui Host, User-Agent, Accept, Accept-Encoding, Content-Type, Expect e Content-Length.
baRequestData	Dados enviados na requisição.
nTimeOut	Tempo de timeout da operação em milisegundos. Pode ser passado 0 para não ter tempo de timeout.
nParam	Valor Significado 0 Opção padrão. Não verifica o certificado com o nome do host. TacNDJavaLib.PIX_VERIFY_HOST_NAME Verifica certificado com o nome do host. TacNDJavaLib.PIX_BASIC_HTTP_HEADER Usa o header HTTP inicial básico. Inclui Host, User-Agent e Content-Length. TacNDJavaLib.PIX_GZIP Faz a compressão gzip automática dos dados de requisição. Inclui automaticamente os headers necessários (Content-Encoding e Accept-Encoding).

Retorna

Resposta da requisição.

Exceções

TacException

Lança exceção no caso de erros na assinatura

Anotações

Executa uma requisição segura seguindo o padrão PIX definida no SPI nos documentos: "Anexo IV – Manual de Segurança", "Especificações técnicas e de negócio do ecossistema de pagamentos instantâneos brasileiro" e "Anexo III - Manual das Interfaces de comunicação" definidos no SPI.
O túnel negociado é o TLS versão 1.2 com autenticação mútua, utilizando o protocolo HTTP versão 1.1 com Cipher Suite mínima de ECDHE-RSA-AES-128-GCM-SHA256.

Esta API irá descompactar automaticamente uma resposta que venha compactada no padrão gzip. Caso opte pela compactação dos dados de envio, a compactação deverá ser feita pelo chamador da API, no formato gzip.

Esta requisição utiliza os seguintes headers como padrão.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", onde 0.0.0.0 é a versão da biblioteca cliente do HSM utilizada.

A validação de certificado com o nome do host é feita verificando se os campos Common Name field ou Subject Alternate Name do certificado coincidem com o host name da URL passada como parâmetro.

Ao fazer um request HTTP são feitas 2 operações, uma de uso dos objetos do HSM (chave privada, certificado e cadeia, usados para autenticação do túnel) e outra de abertura da sessão HTTP com o servidor HTTP.
Para otimizar os recursos a sessão com o servidor HTTP é mantida aberta e guardada em cache, igualmente, a sessão com o HSM é guardada em cache por padrão (a sessão do HSM pode ser, opcionalmente, definida para não ser guardada em cache).
A sessão HTTP fica associada à sessão aberta com o HSM, isto significa que para reutilizar uma sessão HTTP deve-se usar a mesma sessão do HSM utilizada anteriormente para abrir a sessão HTTP.
A sessão HTTP é fechada físicamente quando a sessão com o HSM é fechada físicamente.
A sessão do HSM e a HTTP tem afinidade thread-sessão, não podendo ser utilizada simultâneamente entre várias threads.

O ajuste do Long Polling é feito definindo o timeout da operação HTTP (POST/GET/DELETE) de acordo com as configurações do servidor HTTP.

putPIX() [1/2]

PIXResponse putPIX	(	String	strKeyId,
		String	strCertId,
		String	strPIXCertChainId,
		String	strURL,
		String[]	straRequestHeaderList,
		byte[]	baRequestData,
		int	nTimeOut,
		boolean	bUseGzip,
		boolean	bVerifyHostName ) throws TacException

Faz uma requisição segura HTTP PUT seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Usa o header HTTP inicial básico.

Observação

Faça as configurações de timeout. Veja mais detalhes na seção Boas práticas.

Parâmetros

strKeyId	Nome da chave privada utilizada para fechamento do túnel. Correspondente a um certificado CPIC.
strCertId	Nome do certificado utilizado para fechamento do túnel. Certificado Digital do PSP cadastrado no SPI para conexão, também conhecido como CPIC ou CERTPIC.
strPIXCertChainId	Nome da cadeia PKCS#7 utilizada para verificar o servidor PIX (ICOM ou DICT). A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias.
strURL	URL do servidor PIX (ICOM ou DICT).
straRequestHeaderList	Linhas contendo os headers HTTP customizados que serão utilizados na requisição. Pode ser passado nulo caso queira utilizar o header padrão sem alterações. Essa opção irá sobrescrever os headers padrão, caso haja sobreposição. Para remover um header passe o nome do header sem valor (Ex. Accept:). Para incluir um header sem conteúdo utilize ; ao invés de : (Ex. Accept;). NÃO utilizar terminadores CRLF nos headers. A passagem desses terminadores poderá causar comportamentos indesejados. A formatação será feita internamente. Esta opção não pode ser utilizada para alterar a primeira linha da requisição (Ex. POST, PUT, GET, DELETE), que não é um header. Deve-se utilizar a API correspondente, descrita neste manual. O header inicial padrão inclui Host, User-Agent e Content-Length.
baRequestData	Dados enviados na requisição.
nTimeOut	Tempo de timeout da operação em milisegundos. Pode ser passado 0 para não ter tempo de timeout.
bUseGzip	Faz a compressão gzip automática dos dados de requisição. Inclui automaticamente os headers necessários (Content-Encoding e Accept-Encoding).
bVerifyHostName	Verifica certificado com o nome do host.

Retorna

Resposta da requisição.

Exceções

TacException

Lança exceção no caso de erros na assinatura

Anotações

Executa uma requisição segura seguindo o padrão PIX definida no SPI nos documentos: "Anexo IV – Manual de Segurança", "Especificações técnicas e de negócio do ecossistema de pagamentos instantâneos brasileiro" e "Anexo III - Manual das Interfaces de comunicação" definidos no SPI.
O túnel negociado é o TLS versão 1.2 com autenticação mútua, utilizando o protocolo HTTP versão 1.1 com Cipher Suite mínima de ECDHE-RSA-AES-128-GCM-SHA256.

Esta API irá descompactar automaticamente uma resposta que venha compactada no padrão gzip. Caso opte pela compactação dos dados de envio, a compactação deverá ser feita pelo chamador da API, no formato gzip.

Esta requisição utiliza os seguintes headers como padrão.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", onde 0.0.0.0 é a versão da biblioteca cliente do HSM utilizada.

A validação de certificado com o nome do host é feita verificando se os campos Common Name field ou Subject Alternate Name do certificado coincidem com o host name da URL passada como parâmetro.

Ao fazer um request HTTP são feitas 2 operações, uma de uso dos objetos do HSM (chave privada, certificado e cadeia, usados para autenticação do túnel) e outra de abertura da sessão HTTP com o servidor HTTP.
Para otimizar os recursos a sessão com o servidor HTTP é mantida aberta e guardada em cache, igualmente, a sessão com o HSM é guardada em cache por padrão (a sessão do HSM pode ser, opcionalmente, definida para não ser guardada em cache).
A sessão HTTP fica associada à sessão aberta com o HSM, isto significa que para reutilizar uma sessão HTTP deve-se usar a mesma sessão do HSM utilizada anteriormente para abrir a sessão HTTP.
A sessão HTTP é fechada físicamente quando a sessão com o HSM é fechada físicamente.
A sessão do HSM e a HTTP tem afinidade thread-sessão, não podendo ser utilizada simultâneamente entre várias threads.

O ajuste do Long Polling é feito definindo o timeout da operação HTTP (POST/GET/DELETE) de acordo com as configurações do servidor HTTP.

putPIX() [2/2]

PIXResponse putPIX	(	String	strKeyId,
		String	strCertId,
		String	strPIXCertChainId,
		String	strURL,
		String[]	straRequestHeaderList,
		byte[]	baRequestData,
		int	nTimeOut,
		int	nParam ) throws TacException

Faz uma requisição segura HTTP PUT seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Observação

Faça as configurações de timeout. Veja mais detalhes na seção Boas práticas.

Parâmetros

strKeyId	Nome da chave privada utilizada para fechamento do túnel. Correspondente a um certificado CPIC.
strCertId	Nome do certificado utilizado para fechamento do túnel. Certificado Digital do PSP cadastrado no SPI para conexão, também conhecido como CPIC ou CERTPIC.
strPIXCertChainId	Nome da cadeia PKCS#7 utilizada para verificar o servidor PIX (ICOM ou DICT). A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias.
strURL	URL do servidor PIX (ICOM ou DICT).
straRequestHeaderList	Linhas contendo os headers HTTP customizados que serão utilizados na requisição. Pode ser passado nulo caso queira utilizar o header padrão sem alterações. Essa opção irá sobrescrever os headers padrão, caso haja sobreposição. Para remover um header passe o nome do header sem valor (Ex. Accept:). Para incluir um header sem conteúdo utilize ; ao invés de : (Ex. Accept;). NÃO utilizar terminadores CRLF nos headers. A passagem desses terminadores poderá causar comportamentos indesejados. A formatação será feita internamente. Esta opção não pode ser utilizada para alterar a primeira linha da requisição (Ex. POST, PUT, GET, DELETE), que não é um header. Deve-se utilizar a API correspondente, descrita neste manual. O header inicial padrão inclui Host, User-Agent, Accept, Accept-Encoding, Expect e Content-Length.
baRequestData	Dados enviados na requisição.
nTimeOut	Tempo de timeout da operação em milisegundos. Pode ser passado 0 para não ter tempo de timeout.
nParam	Valor Significado 0 Opção padrão. Não verifica o certificado com o nome do host. TacNDJavaLib.PIX_VERIFY_HOST_NAME Verifica certificado com o nome do host. TacNDJavaLib.PIX_BASIC_HTTP_HEADER Usa o header HTTP inicial básico. Inclui Host, User-Agent e Content-Length. TacNDJavaLib.PIX_GZIP Faz a compressão gzip automática dos dados de requisição. Inclui automaticamente os headers necessários (Content-Encoding e Accept-Encoding).

Retorna

Resposta da requisição.

Exceções

TacException

Lança exceção no caso de erros na assinatura

Anotações

Executa uma requisição segura seguindo o padrão PIX definida no SPI nos documentos: "Anexo IV – Manual de Segurança", "Especificações técnicas e de negócio do ecossistema de pagamentos instantâneos brasileiro" e "Anexo III - Manual das Interfaces de comunicação" definidos no SPI.
O túnel negociado é o TLS versão 1.2 com autenticação mútua, utilizando o protocolo HTTP versão 1.1 com Cipher Suite mínima de ECDHE-RSA-AES-128-GCM-SHA256.

Esta API irá descompactar automaticamente uma resposta que venha compactada no padrão gzip. Caso opte pela compactação dos dados de envio, a compactação deverá ser feita pelo chamador da API, no formato gzip.

Esta requisição utiliza os seguintes headers como padrão.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", onde 0.0.0.0 é a versão da biblioteca cliente do HSM utilizada.

A validação de certificado com o nome do host é feita verificando se os campos Common Name field ou Subject Alternate Name do certificado coincidem com o host name da URL passada como parâmetro.

Ao fazer um request HTTP são feitas 2 operações, uma de uso dos objetos do HSM (chave privada, certificado e cadeia, usados para autenticação do túnel) e outra de abertura da sessão HTTP com o servidor HTTP.
Para otimizar os recursos a sessão com o servidor HTTP é mantida aberta e guardada em cache, igualmente, a sessão com o HSM é guardada em cache por padrão (a sessão do HSM pode ser, opcionalmente, definida para não ser guardada em cache).
A sessão HTTP fica associada à sessão aberta com o HSM, isto significa que para reutilizar uma sessão HTTP deve-se usar a mesma sessão do HSM utilizada anteriormente para abrir a sessão HTTP.
A sessão HTTP é fechada físicamente quando a sessão com o HSM é fechada físicamente.
A sessão do HSM e a HTTP tem afinidade thread-sessão, não podendo ser utilizada simultâneamente entre várias threads.

O ajuste do Long Polling é feito definindo o timeout da operação HTTP (POST/GET/DELETE) de acordo com as configurações do servidor HTTP.

getPIX() [1/2]

PIXResponse getPIX	(	String	strKeyId,
		String	strCertId,
		String	strPIXCertChainId,
		String	strURL,
		String[]	straRequestHeaderList,
		int	nTimeOut,
		boolean	bUseGzip,
		boolean	bVerifyHostName ) throws TacException

Faz uma requisição segura HTTP GET seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Usa o header HTTP inicial básico.

Observação

Faça as configurações de timeout. Veja mais detalhes na seção Boas práticas.

Parâmetros

strKeyId	Nome da chave privada utilizada para fechamento do túnel. Correspondente a um certificado CPIC.
strCertId	Nome do certificado utilizado para fechamento do túnel. Certificado Digital do PSP cadastrado no SPI para conexão, também conhecido como CPIC ou CERTPIC.
strPIXCertChainId	Nome da cadeia PKCS#7 utilizada para verificar o servidor PIX (ICOM ou DICT). A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias.
strURL	URL do servidor PIX (ICOM ou DICT).
straRequestHeaderList	Linhas contendo os headers HTTP customizados que serão utilizados na requisição. Pode ser passado nulo caso queira utilizar o header padrão sem alterações. Essa opção irá sobrescrever os headers padrão, caso haja sobreposição. Para remover um header passe o nome do header sem valor (Ex. Accept:). Para incluir um header sem conteúdo utilize ; ao invés de : (Ex. Accept;). NÃO utilizar terminadores CRLF nos headers. A passagem desses terminadores poderá causar comportamentos indesejados. A formatação será feita internamente. Esta opção não pode ser utilizada para alterar a primeira linha da requisição (Ex. POST, PUT, GET, DELETE), que não é um header. Deve-se utilizar a API correspondente, descrita neste manual. O header inicial padrão inclui Host, User-Agent, Accept, Accept-Encoding.
nTimeOut	Tempo de timeout da operação em milisegundos. Pode ser passado 0 para não ter tempo de timeout.
bUseGzip	Inclui o header Accept-Encoding: gzip caso basic header esteja habilitado.
bVerifyHostName	Verifica certificado com o nome do host.

Retorna

Resposta da requisição.

Exceções

TacException

Lança exceção no caso de erros na assinatura

Anotações

Executa uma requisição segura seguindo o padrão PIX definida no SPI nos documentos: "Anexo IV – Manual de Segurança", "Especificações técnicas e de negócio do ecossistema de pagamentos instantâneos brasileiro" e "Anexo III - Manual das Interfaces de comunicação" definidos no SPI.
O túnel negociado é o TLS versão 1.2 com autenticação mútua, utilizando o protocolo HTTP versão 1.1 com Cipher Suite mínima de ECDHE-RSA-AES-128-GCM-SHA256.

Esta API irá descompactar automaticamente uma resposta que venha compactada no padrão gzip. Caso opte pela compactação dos dados de envio, a compactação deverá ser feita pelo chamador da API, no formato gzip.

Esta requisição utiliza os seguintes headers como padrão.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", onde 0.0.0.0 é a versão da biblioteca cliente do HSM utilizada.

A validação de certificado com o nome do host é feita verificando se os campos Common Name field ou Subject Alternate Name do certificado coincidem com o host name da URL passada como parâmetro.

Ao fazer um request HTTP são feitas 2 operações, uma de uso dos objetos do HSM (chave privada, certificado e cadeia, usados para autenticação do túnel) e outra de abertura da sessão HTTP com o servidor HTTP.
Para otimizar os recursos a sessão com o servidor HTTP é mantida aberta e guardada em cache, igualmente, a sessão com o HSM é guardada em cache por padrão (a sessão do HSM pode ser, opcionalmente, definida para não ser guardada em cache).
A sessão HTTP fica associada à sessão aberta com o HSM, isto significa que para reutilizar uma sessão HTTP deve-se usar a mesma sessão do HSM utilizada anteriormente para abrir a sessão HTTP.
A sessão HTTP é fechada físicamente quando a sessão com o HSM é fechada físicamente.
A sessão do HSM e a HTTP tem afinidade thread-sessão, não podendo ser utilizada simultâneamente entre várias threads.

O ajuste do Long Polling é feito definindo o timeout da operação HTTP (POST/GET/DELETE) de acordo com as configurações do servidor HTTP.

getPIX() [2/2]

PIXResponse getPIX	(	String	strKeyId,
		String	strCertId,
		String	strPIXCertChainId,
		String	strURL,
		String[]	straRequestHeaderList,
		int	nTimeOut,
		int	nParam ) throws TacException

Faz uma requisição segura HTTP GET seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Observação

Faça as configurações de timeout. Veja mais detalhes na seção Boas práticas.

Parâmetros

strKeyId	Nome da chave privada utilizada para fechamento do túnel. Correspondente a um certificado CPIC.
strCertId	Nome do certificado utilizado para fechamento do túnel. Certificado Digital do PSP cadastrado no SPI para conexão, também conhecido como CPIC ou CERTPIC.
strPIXCertChainId	Nome da cadeia PKCS#7 utilizada para verificar o servidor PIX (ICOM ou DICT). A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias.
strURL	URL do servidor PIX (ICOM ou DICT).
straRequestHeaderList	Linhas contendo os headers HTTP customizados que serão utilizados na requisição. Pode ser passado nulo caso queira utilizar o header padrão sem alterações. Essa opção irá sobrescrever os headers padrão, caso haja sobreposição. Para remover um header passe o nome do header sem valor (Ex. Accept:). Para incluir um header sem conteúdo utilize ; ao invés de : (Ex. Accept;). NÃO utilizar terminadores CRLF nos headers. A passagem desses terminadores poderá causar comportamentos indesejados. A formatação será feita internamente. Esta opção não pode ser utilizada para alterar a primeira linha da requisição (Ex. POST, PUT, GET, DELETE), que não é um header. Deve-se utilizar a API correspondente, descrita neste manual. O header inicial padrão inclui Host, User-Agent, Accept, Accept-Encoding.
nTimeOut	Tempo de timeout da operação em milisegundos. Pode ser passado 0 para não ter tempo de timeout.
nParam	Valor Significado 0 Opção padrão.Não verifica o certificado com o nome do host. TacNDJavaLib.PIX_VERIFY_HOST_NAME Verifica certificado com o nome do host. TacNDJavaLib.PIX_BASIC_HTTP_HEADER Usa o header HTTP inicial básico. Inclui Host e User-Agent. TacNDJavaLib.PIX_GZIP Inclui o header Accept-Encoding: gzip caso basic header esteja habilitado.

Retorna

Resposta da requisição.

Exceções

TacException

Lança exceção no caso de erros na assinatura

Anotações

Executa uma requisição segura seguindo o padrão PIX definida no SPI nos documentos: "Anexo IV – Manual de Segurança", "Especificações técnicas e de negócio do ecossistema de pagamentos instantâneos brasileiro" e "Anexo III - Manual das Interfaces de comunicação" definidos no SPI.
O túnel negociado é o TLS versão 1.2 com autenticação mútua, utilizando o protocolo HTTP versão 1.1 com Cipher Suite mínima de ECDHE-RSA-AES-128-GCM-SHA256.

Esta API irá descompactar automaticamente uma resposta que venha compactada no padrão gzip. Caso opte pela compactação dos dados de envio, a compactação deverá ser feita pelo chamador da API, no formato gzip.

Esta requisição utiliza os seguintes headers como padrão.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", onde 0.0.0.0 é a versão da biblioteca cliente do HSM utilizada.

A validação de certificado com o nome do host é feita verificando se os campos Common Name field ou Subject Alternate Name do certificado coincidem com o host name da URL passada como parâmetro.

Ao fazer um request HTTP são feitas 2 operações, uma de uso dos objetos do HSM (chave privada, certificado e cadeia, usados para autenticação do túnel) e outra de abertura da sessão HTTP com o servidor HTTP.
Para otimizar os recursos a sessão com o servidor HTTP é mantida aberta e guardada em cache, igualmente, a sessão com o HSM é guardada em cache por padrão (a sessão do HSM pode ser, opcionalmente, definida para não ser guardada em cache).
A sessão HTTP fica associada à sessão aberta com o HSM, isto significa que para reutilizar uma sessão HTTP deve-se usar a mesma sessão do HSM utilizada anteriormente para abrir a sessão HTTP.
A sessão HTTP é fechada físicamente quando a sessão com o HSM é fechada físicamente.
A sessão do HSM e a HTTP tem afinidade thread-sessão, não podendo ser utilizada simultâneamente entre várias threads.

O ajuste do Long Polling é feito definindo o timeout da operação HTTP (POST/GET/DELETE) de acordo com as configurações do servidor HTTP.

deletePIX() [1/2]

PIXResponse deletePIX	(	String	strKeyId,
		String	strCertId,
		String	strPIXCertChainId,
		String	strURL,
		String[]	straRequestHeaderList,
		int	nTimeOut,
		boolean	bUseGzip,
		boolean	bVerifyHostName ) throws TacException

Faz uma requisição segura HTTP DELETE seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Usa o header HTTP inicial básico.

Observação

Faça as configurações de timeout. Veja mais detalhes na seção Boas práticas.

Parâmetros

strKeyId	Nome da chave privada utilizada para fechamento do túnel. Correspondente a um certificado CPIC.
strCertId	Nome do certificado utilizado para fechamento do túnel. Certificado Digital do PSP cadastrado no SPI para conexão, também conhecido como CPIC ou CERTPIC.
strPIXCertChainId	Nome da cadeia PKCS#7 utilizada para verificar o servidor PIX (ICOM ou DICT). A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias.
strURL	URL do servidor PIX (ICOM ou DICT).
straRequestHeaderList	Linhas contendo os headers HTTP customizados que serão utilizados na requisição. Pode ser passado nulo caso queira utilizar o header padrão sem alterações. Essa opção irá sobrescrever os headers padrão, caso haja sobreposição. Para remover um header passe o nome do header sem valor (Ex. Accept:). Para incluir um header sem conteúdo utilize ; ao invés de : (Ex. Accept;). NÃO utilizar terminadores CRLF nos headers. A passagem desses terminadores poderá causar comportamentos indesejados. A formatação será feita internamente. Esta opção não pode ser utilizada para alterar a primeira linha da requisição (Ex. POST, PUT, GET, DELETE), que não é um header. Deve-se utilizar a API correspondente, descrita neste manual. O header inicial padrão inclui Host e User-Agent.
nTimeOut	Tempo de timeout da operação em milisegundos. Pode ser passado 0 para não ter tempo de timeout.
bUseGzip	Inclui o header Accept-Encoding: gzip caso basic header esteja habilitado.
bVerifyHostName	Verifica certificado com o nome do host.

Retorna

Resposta da requisição.

Exceções

TacException

Lança exceção no caso de erros na assinatura

Anotações

Executa uma requisição segura seguindo o padrão PIX definida no SPI nos documentos: "Anexo IV – Manual de Segurança", "Especificações técnicas e de negócio do ecossistema de pagamentos instantâneos brasileiro" e "Anexo III - Manual das Interfaces de comunicação" definidos no SPI.
O túnel negociado é o TLS versão 1.2 com autenticação mútua, utilizando o protocolo HTTP versão 1.1 com Cipher Suite mínima de ECDHE-RSA-AES-128-GCM-SHA256.

Esta API irá descompactar automaticamente uma resposta que venha compactada no padrão gzip. Caso opte pela compactação dos dados de envio, a compactação deverá ser feita pelo chamador da API, no formato gzip.

Esta requisição utiliza os seguintes headers como padrão.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", onde 0.0.0.0 é a versão da biblioteca cliente do HSM utilizada.

A validação de certificado com o nome do host é feita verificando se os campos Common Name field ou Subject Alternate Name do certificado coincidem com o host name da URL passada como parâmetro.

Ao fazer um request HTTP são feitas 2 operações, uma de uso dos objetos do HSM (chave privada, certificado e cadeia, usados para autenticação do túnel) e outra de abertura da sessão HTTP com o servidor HTTP.
Para otimizar os recursos a sessão com o servidor HTTP é mantida aberta e guardada em cache, igualmente, a sessão com o HSM é guardada em cache por padrão (a sessão do HSM pode ser, opcionalmente, definida para não ser guardada em cache).
A sessão HTTP fica associada à sessão aberta com o HSM, isto significa que para reutilizar uma sessão HTTP deve-se usar a mesma sessão do HSM utilizada anteriormente para abrir a sessão HTTP.
A sessão HTTP é fechada físicamente quando a sessão com o HSM é fechada físicamente.
A sessão do HSM e a HTTP tem afinidade thread-sessão, não podendo ser utilizada simultâneamente entre várias threads.

O ajuste do Long Polling é feito definindo o timeout da operação HTTP (POST/GET/DELETE) de acordo com as configurações do servidor HTTP.

deletePIX() [2/2]

PIXResponse deletePIX	(	String	strKeyId,
		String	strCertId,
		String	strPIXCertChainId,
		String	strURL,
		String[]	straRequestHeaderList,
		int	nTimeOut,
		int	nParam ) throws TacException

Faz uma requisição segura HTTP DELETE seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Observação

Faça as configurações de timeout. Veja mais detalhes na seção Boas práticas.

Parâmetros

strKeyId	Nome da chave privada utilizada para fechamento do túnel. Correspondente a um certificado CPIC.
strCertId	Nome do certificado utilizado para fechamento do túnel. Certificado Digital do PSP cadastrado no SPI para conexão, também conhecido como CPIC ou CERTPIC.
strPIXCertChainId	Nome da cadeia PKCS#7 utilizada para verificar o servidor PIX (ICOM ou DICT). A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias.
strURL	URL do servidor PIX (ICOM ou DICT).
straRequestHeaderList	Linhas contendo os headers HTTP customizados que serão utilizados na requisição. Pode ser passado nulo caso queira utilizar o header padrão sem alterações. Essa opção irá sobrescrever os headers padrão, caso haja sobreposição. Para remover um header passe o nome do header sem valor (Ex. Accept:). Para incluir um header sem conteúdo utilize ; ao invés de : (Ex. Accept;). NÃO utilizar terminadores CRLF nos headers. A passagem desses terminadores poderá causar comportamentos indesejados. A formatação será feita internamente. Esta opção não pode ser utilizada para alterar a primeira linha da requisição (Ex. POST, PUT, GET, DELETE), que não é um header. Deve-se utilizar a API correspondente, descrita neste manual. O header inicial padrão inclui Host, User-Agent, Accept, Accept-Encoding.
nTimeOut	Tempo de timeout da operação em milisegundos. Pode ser passado 0 para não ter tempo de timeout.
nParam	Valor Significado 0 Opção padrão.Não verifica o certificado com o nome do host. TacNDJavaLib.PIX_VERIFY_HOST_NAME Verifica certificado com o nome do host. TacNDJavaLib.PIX_BASIC_HTTP_HEADER Usa o header HTTP inicial básico. Inclui Host e User-Agent. TacNDJavaLib.PIX_GZIP Inclui o header Accept-Encoding: gzip caso basic header esteja habilitado.

Retorna

Resposta da requisição.

Exceções

TacException

Lança exceção no caso de erros na assinatura

Anotações

Executa uma requisição segura seguindo o padrão PIX definida no SPI nos documentos: "Anexo IV – Manual de Segurança", "Especificações técnicas e de negócio do ecossistema de pagamentos instantâneos brasileiro" e "Anexo III - Manual das Interfaces de comunicação" definidos no SPI.
O túnel negociado é o TLS versão 1.2 com autenticação mútua, utilizando o protocolo HTTP versão 1.1 com Cipher Suite mínima de ECDHE-RSA-AES-128-GCM-SHA256.

Esta API irá descompactar automaticamente uma resposta que venha compactada no padrão gzip. Caso opte pela compactação dos dados de envio, a compactação deverá ser feita pelo chamador da API, no formato gzip.

Esta requisição utiliza os seguintes headers como padrão.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", onde 0.0.0.0 é a versão da biblioteca cliente do HSM utilizada.

A validação de certificado com o nome do host é feita verificando se os campos Common Name field ou Subject Alternate Name do certificado coincidem com o host name da URL passada como parâmetro.

Ao fazer um request HTTP são feitas 2 operações, uma de uso dos objetos do HSM (chave privada, certificado e cadeia, usados para autenticação do túnel) e outra de abertura da sessão HTTP com o servidor HTTP.
Para otimizar os recursos a sessão com o servidor HTTP é mantida aberta e guardada em cache, igualmente, a sessão com o HSM é guardada em cache por padrão (a sessão do HSM pode ser, opcionalmente, definida para não ser guardada em cache).
A sessão HTTP fica associada à sessão aberta com o HSM, isto significa que para reutilizar uma sessão HTTP deve-se usar a mesma sessão do HSM utilizada anteriormente para abrir a sessão HTTP.
A sessão HTTP é fechada físicamente quando a sessão com o HSM é fechada físicamente.
A sessão do HSM e a HTTP tem afinidade thread-sessão, não podendo ser utilizada simultâneamente entre várias threads.

O ajuste do Long Polling é feito definindo o timeout da operação HTTP (POST/GET/DELETE) de acordo com as configurações do servidor HTTP.

getPIXHTTPReqDetails()

PIXHTTPReqDetails getPIXHTTPReqDetails

(

)

throws TacException

Recupera os detalhes da última requisição PIX HTTP (POST, GET...) feita nesta sessão.

Esta operação deve ser chamada logo após a chamada da API de requisição PIX. Deve ser chamada utilizando a mesma sessão. Não fazer outras operações entre estas chamadas.

Retorna

Detalhes da última requisição PIX HTTP desta sessão.

Exceções

TacException

Lança exceção no caso de erros na assinatura

getPIXHTTPReqCode()

long getPIXHTTPReqCode

(

)

throws TacException

Recupera o código de retorno da última requisição PIX HTTP (POST, GET...) feita nesta sessão.

Esta operação deve ser chamada logo após a chamada da API de requisição PIX. Deve ser chamada utilizando a mesma sessão. Não fazer outras operações entre estas chamadas.

Retorna

Código de retorno HTTP.

Exceções

TacException

Lança exceção no caso de erro