Detailed description

Operations destined for Pix of the SPI (Instant Payments System).

See HSM technical documentation about operating details, specifications used, licenses and module trade name.

Best practices

General

Reuse sessions (benefit from session caching). Utilize the HSM session cache to improve performance by reusing both HSM and HTTP sessions. In this scenario, it is recommended to open a session, perform the desired operations, and then close it; this allows the session to be quickly reused, thereby reducing idle time.
Ensure session closure. Closing sessions guarantees resource release, both on the HSM and the client. Ensure that sessions are closed even for operations with a return code other than success.
Utilize concurrent sessions. Using concurrent/parallel sessions with the HSM helps extract maximum performance. Care should be taken to avoid an excessive number of sessions with HSMs, to prevent unnecessary resource consumption. The throughput curve tends to rise and then plateau.

HTTP requests Pix

Setting a connection object reload interval. You can optimize the number of times HSM keys and objects are loaded by setting a reload interval for HSM objects. As the institution's key/certificate/chain update is done infrequently and on a scheduled basis, it is advantageous to define a reload interval for these objects. Watch out for network asset timeouts shorter than this value, which could cause premature disconnections.

Important Configurations

General

Set the HSM connection timeouts. When the HSM timeout is not set, the default is that of the operating system. In the event of a connection failure, the application may wait too long. It is important to ALWAYS set the HSM's send and receive timeouts. Other connection parameters can be found here.

HTTP requests Pix

Define the HTTP operation timeouts. If not defined, the default HTTP operation timeout is unlimited. In the event of an HTTP connection failure, the application may wait indefinitely. It is ALWAYS important to define the timeout for HTTP request calls.

Transactions intended for Pix (Instant Payment System) Pix . More...

Functions
byte[]	signPIX (String strKeyId, String strCertId, int nFlags, byte[] baUnsignedPIXEnvelope) throws TacException
	Digitally signs an XML in ISO 20.022 format following the PIX standard defined in the SPI (Instant Payment System).

byte[]	signPIX (String strKeyId, String strCertId, byte[] baUnsignedPIXEnvelope) throws TacException
	Digitally signs an XML in ISO 20.022 format following the PIX standard defined in the SPI (Instant Payment System).

byte[]	signPIXDict (String strKeyId, String strCertId, int nFlags, byte[] baUnsignedDictEnvelope) throws TacException
	Digitally signs an XML in XMLDSig format, following the DICT standard defined in the SPI (Instant Payment System).

byte[]	signPIXDict (String strKeyId, String strCertId, byte[] baUnsignedDictEnvelope) throws TacException
	Digitally signs an XML in XMLDSig format, following the DICT standard defined in the SPI (Instant Payment System).

boolean	verifyPIX (String strChainId, String strCRLId, int nFlags, byte[] baSignedPIXEnvelope) throws TacException
	Checks the signature of a digitally signed XML document in ISO 20.022 format following the PIX standard defined in the SPI (Instant Payment System).

boolean	verifyPIX (String strChainId, String strCRLId, byte[] baSignedPIXEnvelope) throws TacException
	Checks the signature of a digitally signed XML document in ISO 20.022 format following the PIX standard defined in the SPI (Instant Payment System).

boolean	verifyPIXDict (String strChainId, String strCRLId, int nFlags, byte[] baSignedDictEnvelope) throws TacException
	Verifies the signature of a digitally signed XML document in XMLDSig format, following the DICT standard defined in the SPI (Instant Payment System).

boolean	verifyPIXDict (String strChainId, String strCRLId, byte[] baSignedDictEnvelope) throws TacException
	Verifies the signature of a digitally signed XML document in XMLDSig format, following the DICT standard defined in the SPI (Instant Payment System).

byte[]	signPIXJWS (String strKeyId, byte[] baHeader, byte[] baPayload) throws TacException
	Makes a JWS RFC 7515 signature following the PIX standard defined in the SPI (Instant Payment System).

String	signPIXJWS (String strKeyId, String strHeader, String strPayload) throws TacException
	Makes a JWS RFC 7515 signature following the PIX standard defined in the SPI (Instant Payment System).

JwsComponents	checkPIXJWS (String strChainId, String strCRLId, byte[] baJWS, int nFlags) throws TacException
	Validates an RFC 7515 signed JWS following the PIX standard defined in the SPI (Instant Payment System).

JwsComponents	checkPIXJWS (String strChainId, String strCRLId, String strJWS, int nFlags) throws TacException
	Validates an RFC 7515 signed JWS following the PIX standard defined in the SPI (Instant Payment System).

boolean	checkPIXJWS (String strChainId, String strCRLId, byte[] baJWS) throws TacException
	Validates an RFC 7515 signed JWS following the PIX standard defined in the SPI (Instant Payment System).

boolean	checkPIXJWS (String strChainId, String strCRLId, String strJWS) throws TacException
	Validates an RFC 7515 signed JWS following the PIX standard defined in the SPI (Instant Payment System).

PixResponse	postPIX (String strKeyId, String strCertId, String strPIXCertChainId, String strURL, String[] straRequestHeaderList, byte[] baRequestData, int nTimeOut, boolean bUseGzip, boolean bVerifyHostName) throws TacException
	It makes a secure HTTP POST request following the PIX standard defined in SPI (Instant Payment System).

PixResponse	postPIX (String strKeyId, String strCertId, String strPIXCertChainId, String strURL, String[] straRequestHeaderList, byte[] baRequestData, int nTimeOut, int nParam) throws TacException
	It makes a secure HTTP POST request following the PIX standard defined in SPI (Instant Payment System).

PixResponse	putPIX (String strKeyId, String strCertId, String strPIXCertChainId, String strURL, String[] straRequestHeaderList, byte[] baRequestData, int nTimeOut, boolean bUseGzip, boolean bVerifyHostName) throws TacException
	It makes a secure HTTP PUT request following the PIX standard defined in the SPI (Instant Payment System).

PixResponse	putPIX (String strKeyId, String strCertId, String strPIXCertChainId, String strURL, String[] straRequestHeaderList, byte[] baRequestData, int nTimeOut, int nParam) throws TacException
	It makes a secure HTTP PUT request following the PIX standard defined in the SPI (Instant Payment System).

PixResponse	getPIX (String strKeyId, String strCertId, String strPIXCertChainId, String strURL, String[] straRequestHeaderList, int nTimeOut, boolean bUseGzip, boolean bVerifyHostName) throws TacException
	It makes a secure HTTP GET request following the PIX standard defined in the SPI (Instant Payment System).

PixResponse	getPIX (String strKeyId, String strCertId, String strPIXCertChainId, String strURL, String[] straRequestHeaderList, int nTimeOut, int nParam) throws TacException
	It makes a secure HTTP GET request following the PIX standard defined in the SPI (Instant Payment System).

PixResponse	deletePIX (String strKeyId, String strCertId, String strPIXCertChainId, String strURL, String[] straRequestHeaderList, int nTimeOut, boolean bUseGzip, boolean bVerifyHostName) throws TacException
	It makes a secure HTTP DELETE request following the PIX standard defined in SPI (Instant Payment System).

PixResponse	deletePIX (String strKeyId, String strCertId, String strPIXCertChainId, String strURL, String[] straRequestHeaderList, int nTimeOut, int nParam) throws TacException
	It makes a secure HTTP DELETE request following the PIX standard defined in SPI (Instant Payment System).

PixHTTPReqDetails	getPIXHTTPReqDetails () throws TacException
	Retrieves the details of the last PIX HTTP request (POST, GET...) made in this session.

long	getPIXHTTPReqCode () throws TacException
	Retrieves the return code of the last PIX HTTP request (POST, GET...) made in this session.

Functions

◆ signPix() [1/2]

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

Digitally signs an XML in ISO 20.022 format following the PIX standard defined in the SPI (Instant Payment System).

Parameters

strKeyId Name of the private key used for signing. Corresponds to a CPIA certificate.

strCertId Name of the digital certificate used for signing. This is the PSP's Digital Certificate registered with SPI for signing, also known as CPIA or CERTPIA.

nFlags

Signing options. Pass 0. If additional options are required, the following values are accepted.

Value	Meaning
TacNDJavaLib.PIX_SIGN_RNS	Enables the use of relative namespaces.

baUnsignedPIXEnvelope XML to be signed.

Returns

Exceptions

TacException Throws an exception in case of signature errors.

Notes: For performance reasons, we recommend using the signature tag with a complete closing, as shown below.
<Sgntr></Sgntr>

The tag with a simple closing is also accepted; see below.
<Sgntr/>

◆ signPix() [2/2]

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

Digitally signs an XML in ISO 20.022 format following the PIX standard defined in the SPI (Instant Payment System).

Parameters

strKeyId	Name of the private key used for signing. Corresponds to a CPIA certificate.
strCertId	Name of the digital certificate used for signing. This is the PSP's Digital Certificate registered with SPI for signing, also known as CPIA or CERTPIA.
baUnsignedPIXEnvelope	XML to be signed.

Returns

Exceptions

TacException Throws an exception in case of signature errors.

Notes: For performance reasons, we recommend using the signature tag with a complete closing, as shown below.
<Sgntr></Sgntr>

The tag with a simple closing is also accepted; see below.
<Sgntr/>

◆ signPixDict() [1/2]

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

Digitally signs an XML in XMLDSig format, following the DICT standard defined in the SPI (Instant Payment System).

Parameters

strKeyId	Name of the private key used for signing. Corresponds to a CPIA certificate.
strCertId	Name of the digital certificate used for signing. This is the PSP's Digital Certificate registered with SPI for signing, also known as CPIA or CERTPIA.
nFlags	Reserved for future use (must be 0).
baUnsignedDictEnvelope	XML to be signed.

Returns

Exceptions

TacException Throws an exception in case of signature errors.

Notes: Do not include the signature tag; it will be added automatically.

◆ signPixDict() [2/2]

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

Digitally signs an XML in XMLDSig format, following the DICT standard defined in the SPI (Instant Payment System).

Parameters

strKeyId	Name of the private key used for signing. Corresponds to a CPIA certificate.
strCertId	Name of the digital certificate used for signing. This is the PSP's Digital Certificate registered with SPI for signing, also known as CPIA or CERTPIA.
baUnsignedDictEnvelope	XML to be signed.

Returns

Exceptions

TacException Throws an exception in case of signature errors.

Notes: Do not include the signature tag; it will be added automatically.

◆ verifyPix() [1/2]

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

Checks the signature of a digitally signed XML document in ISO 20.022 format following the PIX standard defined in the SPI (Instant Payment System).

Parameters

strChainId	Name of the PKCS#7 chain (stored internally in the HSM) of the certificate used in the signature. The chain must be complete, from the root CA to the certificate used in the signature. This formatting is necessary because the XML message from Pix does not contain the certificate used in the signature. Optionally, only the X.509 certificate used to sign can be passed instead of the complete chain. As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object that contains several chains. It is important to note that in the case of an HSM PKCS#7 object containing multiple chains, the presence of an expired certificate in any of the chains will generate a valid signature return code with an expired certificate (non-zero code) in the verification, even if the signature was made with a certificate from a non-expired chain; it is up to the application to handle this correctly according to local policy.
strCRLId	Certificate Revocation List (CRL) Name – stored internally in the HSM – where the digital certificate will be verified. NULL can be passed to indicate that no CRL is available for verification.
nFlags	Reserved for future use (must be 0).
baSignedPIXEnvelope	Signed XML.

Returns: true if the signature is valid, and false if it is invalid.

Exceptions

TacException

◆ verifyPix() [2/2]

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

Checks the signature of a digitally signed XML document in ISO 20.022 format following the PIX standard defined in the SPI (Instant Payment System).

Parameters

strChainId	Name of the PKCS#7 chain (stored internally in the HSM) of the certificate used in the signature. The chain must be complete, from the root CA to the certificate used in the signature. This formatting is necessary because the XML message from Pix does not contain the certificate used in the signature. Optionally, only the X.509 certificate used to sign can be passed instead of the complete chain. As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object that contains several chains. It is important to note that in the case of an HSM PKCS#7 object containing multiple chains, the presence of an expired certificate in any of the chains will generate a valid signature return code with an expired certificate (non-zero code) in the verification, even if the signature was made with a certificate from a non-expired chain; it is up to the application to handle this correctly according to local policy.
strCRLId	Certificate Revocation List (CRL) Name – stored internally in the HSM – where the digital certificate will be verified. NULL can be passed to indicate that no CRL is available for verification.
baSignedPIXEnvelope	Signed XML.

Returns: true if the signature is valid, and false if it is invalid.

Exceptions

TacException

◆ verifyPixDict() [1/2]

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

Verifies the signature of a digitally signed XML document in XMLDSig format, following the DICT standard defined in the SPI (Instant Payment System).

Parameters

strChainId	Name of the PKCS#7 chain (stored internally in the HSM) of the certificate used in the signature. The chain must be complete, from the root CA to the certificate used in the signature. This formatting is necessary because the XML message from Pix does not contain the certificate used in the signature. Optionally, only the X.509 certificate used to sign can be passed instead of the complete chain. As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object that contains several chains. It is important to note that in the case of an HSM PKCS#7 object containing multiple chains, the presence of an expired certificate in any of the chains will generate a valid signature return code with an expired certificate (non-zero code) in the verification, even if the signature was made with a certificate from a non-expired chain; it is up to the application to handle this correctly according to local policy.
strCRLId	Certificate Revocation List (CRL) Name – stored internally in the HSM – where the digital certificate will be verified. NULL can be passed to indicate that no CRL is available for verification.
nFlags	Reserved for future use (must be 0).
baSignedDictEnvelope	Signed XML.

Returns: true if the signature is valid, and false if it is invalid.

Exceptions

TacException

◆ verifyPixDict() [2/2]

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

Verifies the signature of a digitally signed XML document in XMLDSig format, following the DICT standard defined in the SPI (Instant Payment System).

Parameters

strChainId	Name of the PKCS#7 chain (stored internally in the HSM) of the certificate used in the signature. The chain must be complete, from the root CA to the certificate used in the signature. This formatting is necessary because the XML message from Pix does not contain the certificate used in the signature. Optionally, only the X.509 certificate used to sign can be passed instead of the complete chain. As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object that contains several chains. It is important to note that in the case of an HSM PKCS#7 object containing multiple chains, the presence of an expired certificate in any of the chains will generate a valid signature return code with an expired certificate (non-zero code) in the verification, even if the signature was made with a certificate from a non-expired chain; it is up to the application to handle this correctly according to local policy.
strCRLId	Certificate Revocation List (CRL) Name – stored internally in the HSM – where the digital certificate will be verified. NULL can be passed to indicate that no CRL is available for verification.
baSignedDictEnvelope	Signed XML.

Returns: true if the signature is valid, and false if it is invalid.

Exceptions

TacException

◆ signPixJWS() [1/2]

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

Makes a JWS RFC 7515 signature following the PIX standard defined in the SPI (Instant Payment System).

Parameters

strKeyId Name of the private key used for signing. As defined in the PIX

baHeader

JWS Header for signature. At least the header parameter alg must be provided. Accepted values for alg.

Value	Meaning
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 JWS payload for signing.

Returns: Signed JWS.

Exceptions

TacException Throws an exception in case of signature errors.

Notes: Uses the Compact Serialization format described in Section-3.1 of RFC 7515.

◆ signPixJWS() [2/2]

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

Makes a JWS RFC 7515 signature following the PIX standard defined in the SPI (Instant Payment System).

Parameters

strKeyId Name of the private key used for signing. As defined in the PIX

strHeader

JWS Header for signature. At least the header parameter alg must be provided. Accepted values for alg.

Value	Meaning
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 JWS payload for signing.

Returns: Signed JWS.

Exceptions

TacException Throws an exception in case of signature errors.

Notes: Uses the Compact Serialization format described in Section-3.1 of RFC 7515.

◆ checkPixJWS() [1/4]

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

Validates an RFC 7515 signed JWS following the PIX standard defined in the SPI (Instant Payment System).

Parameters

strChainId	Name of the PKCS#7 chain (stored internally in the HSM) of the certificate used in the signature. The chain must be complete, from the root CA to the certificate used in the signature. This formatting is necessary because the XML message from Pix does not contain the certificate used in the signature. Optionally, only the X.509 certificate used to sign can be passed instead of the complete chain. As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object that contains several chains. It is important to note that in the case of an HSM PKCS#7 object containing multiple chains, the presence of an expired certificate in any of the chains will generate a valid signature return code with an expired certificate (non-zero code) in the verification, even if the signature was made with a certificate from a non-expired chain; it is up to the application to handle this correctly according to local policy.
strCRLId	Certificate Revocation List (CRL) Name – stored internally in the HSM – where the digital certificate will be verified. NULL can be passed to indicate that no CRL is available for verification.
baJWS	Signed JWS.
nFlags	Verification options. This value must be 0.

Returns: JwsComponents class that will contain the return code, the Header and the Payload of the signed message.

Exceptions

TacException

◆ checkPIXJWS() [2/4]

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

Validates an RFC 7515 signed JWS following the PIX standard defined in the SPI (Instant Payment System).

Parameters

strChainId	Name of the PKCS#7 chain (stored internally in the HSM) of the certificate used in the signature. The chain must be complete, from the root CA to the certificate used in the signature. This formatting is necessary because the XML message from Pix does not contain the certificate used in the signature. Optionally, only the X.509 certificate used to sign can be passed instead of the complete chain. As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object that contains several chains. It is important to note that in the case of an HSM PKCS#7 object containing multiple chains, the presence of an expired certificate in any of the chains will generate a valid signature return code with an expired certificate (non-zero code) in the verification, even if the signature was made with a certificate from a non-expired chain; it is up to the application to handle this correctly according to local policy.
strCRLId	Certificate Revocation List (CRL) Name – stored internally in the HSM – where the digital certificate will be verified. NULL can be passed to indicate that no CRL is available for verification.
strJWS	Signed JWS.
nFlags	Verification options. This value must be 0.

Returns: JwsComponents class that will contain the return code, the Header and the Payload of the signed message.

Exceptions

TacException

◆ checkPIXJWS() [3/4]

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

Validates an RFC 7515 signed JWS following the PIX standard defined in the SPI (Instant Payment System).

Parameters

strChainId	Name of the PKCS#7 chain (stored internally in the HSM) of the certificate used in the signature. The chain must be complete, from the root CA to the certificate used in the signature. This formatting is necessary because the XML message from Pix does not contain the certificate used in the signature. Optionally, only the X.509 certificate used to sign can be passed instead of the complete chain. As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object that contains several chains. It is important to note that in the case of an HSM PKCS#7 object containing multiple chains, the presence of an expired certificate in any of the chains will generate a valid signature return code with an expired certificate (non-zero code) in the verification, even if the signature was made with a certificate from a non-expired chain; it is up to the application to handle this correctly according to local policy.
strCRLId	Certificate Revocation List (CRL) Name – stored internally in the HSM – where the digital certificate will be verified. NULL can be passed to indicate that no CRL is available for verification.
baJWS	Signed JWS.

Returns: Returns true if the check is performed successfully.

Exceptions

TacException

◆ checkPIXJWS() [4/4]

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

Validates an RFC 7515 signed JWS following the PIX standard defined in the SPI (Instant Payment System).

Parameters

strChainId	Name of the PKCS#7 chain (stored internally in the HSM) of the certificate used in the signature. The chain must be complete, from the root CA to the certificate used in the signature. This formatting is necessary because the XML message from Pix does not contain the certificate used in the signature. Optionally, only the X.509 certificate used to sign can be passed instead of the complete chain. As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object that contains several chains. It is important to note that in the case of an HSM PKCS#7 object containing multiple chains, the presence of an expired certificate in any of the chains will generate a valid signature return code with an expired certificate (non-zero code) in the verification, even if the signature was made with a certificate from a non-expired chain; it is up to the application to handle this correctly according to local policy.
strCRLId	Certificate Revocation List (CRL) Name – stored internally in the HSM – where the digital certificate will be verified. NULL can be passed to indicate that no CRL is available for verification.
strJWS	Signed JWS.

Returns: Returns true if the check is performed successfully.

Exceptions

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

It makes a secure HTTP POST request following the PIX standard defined in SPI (Instant Payment System).

Uses the basic initial HTTP header.

Note: Configure timeout settings. Refer to the Best Practices section for more details.

Parameters

strKeyId	Name of the private key used for tunnel establishment. Corresponds to a CPIC certificate.
strCertId	Name of the certificate used for tunnel establishment. This is the PSP Digital Certificate registered with SPI for connection, also known as CPIC or CERTPIC.
strPIXCertChainId	Name of the PKCS#7 string used to check the PIX server (ICOM or DICT). As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object containing several strings.
strURL	URL of the server PIX (ICOM or DICT).
straRequestHeaderList	Lines containing the customized HTTP headers that will be used in the request. Can be passed null if you want to use the default header without changes. This option will overwrite the default headers if they overlap. To remove a header, pass the name of the header without a value (e.g. `Accept:`). To include a header without content, use `;` instead of `:` (e.g. `Accept;`). Do NOT use CRLF terminators in headers. Passing these terminators may cause unwanted behavior. Formatting will be done internally. This option cannot be used to change the first line of the request (e.g. POST, PUT, GET, DELETE), which is not a header. The corresponding API, described in this manual, must be used. The default initial header includes Host, User-Agent and Content-Length.
baRequestData	Data sent in the request.
nTimeOut	Operation timeout in milliseconds. Can be set to 0 for no timeout.
bUseGzip	Performs automatic gzip compression of request data. Automatically includes the necessary headers (Content-Encoding and Accept-Encoding).
bVerifyHostName	Verifies the certificate against the hostname.

Returns: Request response.

Exceptions

TacException Throws an exception in case of signature errors.

Notes: It executes a secure request following the PIX standard defined in the SPI in the documents: "Annex IV - Security Manual", "Technical and business specifications of the Brazilian instant payment ecosystem" and "Annex III - Communication Interfaces Manual" defined in the SPI.
The negotiated tunnel is TLS version 1.2 with mutual authentication, using the HTTP protocol version 1.1 with a minimum Cipher Suite of ECDHE-RSA-AES-128-GCM-SHA256.

This API will automatically decompress a response that comes compressed in the gzip standard. If you choose to compress the sending data, the API caller must do so in gzip format.

This request uses the following headers by default.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", where 0.0.0.0 is the version of the HSM client library used.

Certificate validation with the host name is done by checking that the Common Name field or Subject Alternate Name field of the certificate matches the host name of the URL passed as a parameter.

When making an HTTP request, 2 operations are performed, one to use the HSM objects (private key, certificate and chain, used for tunnel authentication) and the other to open the HTTP session with the HTTP server.
To optimize resources, the session with the HTTP server is kept open and cached; likewise, the session with the HSM is cached by default (the HSM session can optionally be set not to be cached).
The HTTP session is associated with the session opened with the HSM, which means that to reuse an HTTP session you must use the same HSM session that was previously used to open the HTTP session.
The HTTP session is physically closed when the session with the HSM is physically closed.
The HSM session and the HTTP session have thread-session affinity and cannot be used simultaneously by several threads.

Long Polling is adjusted by setting the HTTP operation timeout (POST/GET/DELETE) according to the HTTP server settings.

◆ postPix() [2/2]

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

It makes a secure HTTP POST request following the PIX standard defined in SPI (Instant Payment System).

Note: Configure timeout settings. Refer to the Best Practices section for more details.

Parameters

strKeyId Name of the private key used for tunnel establishment. Corresponds to a CPIC certificate.

strCertId Name of the certificate used for tunnel establishment. This is the PSP Digital Certificate registered with SPI for connection, also known as CPIC or CERTPIC.

strPIXCertChainId Name of the PKCS#7 string used to check the PIX server (ICOM or DICT). As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object containing several strings.

strURL URL of the server PIX (ICOM or DICT).

straRequestHeaderList Lines containing the customized HTTP headers that will be used in the request. Can be passed null if you want to use the default header without changes.
This option will overwrite the default headers if they overlap.
To remove a header, pass the name of the header without a value (e.g. Accept:).
To include a header without content, use ; instead of : (e.g. Accept;).
Do NOT use CRLF terminators in headers. Passing these terminators may cause unwanted behavior. Formatting will be done internally.
This option cannot be used to change the first line of the request (e.g. POST, PUT, GET, DELETE), which is not a header. The corresponding API, described in this manual, must be used.
The default initial header includes Host, User-Agent, Accept, Accept-Encoding, Content-Type, Expect and Content-Length.

baRequestData Data sent in the request.

nTimeOut Operation timeout in milliseconds. Can be set to 0 for no timeout.

nParam

Value	Meaning
0	Default option. Does not verify the certificate against the hostname.
TacNDJavaLib.PIX_VERIFY_HOST_NAME	Verifies the certificate against the hostname.
TacNDJavaLib.PIX_BASIC_HTTP_HEADER	Uses the basic initial HTTP header. Includes Host, User-Agent, and Content-Length.
TacNDJavaLib.PIX_GZIP	Performs automatic gzip compression of request data. Automatically includes the necessary headers (Content-Encoding and Accept-Encoding).

Returns: Request response.

Exceptions

TacException Throws an exception in case of signature errors.

Notes: It executes a secure request following the PIX standard defined in the SPI in the documents: "Annex IV - Security Manual", "Technical and business specifications of the Brazilian instant payment ecosystem" and "Annex III - Communication Interfaces Manual" defined in the SPI.
The negotiated tunnel is TLS version 1.2 with mutual authentication, using the HTTP protocol version 1.1 with a minimum Cipher Suite of ECDHE-RSA-AES-128-GCM-SHA256.

This API will automatically decompress a response that comes compressed in the gzip standard. If you choose to compress the sending data, the API caller must do so in gzip format.

This request uses the following headers by default.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", where 0.0.0.0 is the version of the HSM client library used.

Certificate validation with the host name is done by checking that the Common Name field or Subject Alternate Name field of the certificate matches the host name of the URL passed as a parameter.

When making an HTTP request, 2 operations are performed, one to use the HSM objects (private key, certificate and chain, used for tunnel authentication) and the other to open the HTTP session with the HTTP server.
To optimize resources, the session with the HTTP server is kept open and cached; likewise, the session with the HSM is cached by default (the HSM session can optionally be set not to be cached).
The HTTP session is associated with the session opened with the HSM, which means that to reuse an HTTP session you must use the same HSM session that was previously used to open the HTTP session.
The HTTP session is physically closed when the session with the HSM is physically closed.
The HSM session and the HTTP session have thread-session affinity and cannot be used simultaneously by several threads.

Long Polling is adjusted by setting the HTTP operation timeout (POST/GET/DELETE) according to the HTTP server settings.

◆ 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

It makes a secure HTTP PUT request following the PIX standard defined in the SPI (Instant Payment System).

Uses the basic initial HTTP header.

Note: Configure timeout settings. Refer to the Best Practices section for more details.

Parameters

strKeyId	Name of the private key used for tunnel establishment. Corresponds to a CPIC certificate.
strCertId	Name of the certificate used for tunnel establishment. This is the PSP Digital Certificate registered with SPI for connection, also known as CPIC or CERTPIC.
strPIXCertChainId	Name of the PKCS#7 string used to check the PIX server (ICOM or DICT). As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object containing several strings.
strURL	URL of the server PIX (ICOM or DICT).
straRequestHeaderList	Lines containing the customized HTTP headers that will be used in the request. Can be passed null if you want to use the default header without changes. This option will overwrite the default headers if they overlap. To remove a header, pass the name of the header without a value (e.g. `Accept:`). To include a header without content, use `;` instead of `:` (e.g. `Accept;`). Do NOT use CRLF terminators in headers. Passing these terminators may cause unwanted behavior. Formatting will be done internally. This option cannot be used to change the first line of the request (e.g. POST, PUT, GET, DELETE), which is not a header. The corresponding API, described in this manual, must be used. The default initial header includes Host, User-Agent and Content-Length.
baRequestData	Data sent in the request.
nTimeOut	Operation timeout in milliseconds. Can be set to 0 for no timeout.
bUseGzip	Performs automatic gzip compression of request data. Automatically includes the necessary headers (Content-Encoding and Accept-Encoding).
bVerifyHostName	Verifies the certificate against the hostname.

Returns: Request response.

Exceptions

TacException Throws an exception in case of signature errors.

Notes: It executes a secure request following the PIX standard defined in the SPI in the documents: "Annex IV - Security Manual", "Technical and business specifications of the Brazilian instant payment ecosystem" and "Annex III - Communication Interfaces Manual" defined in the SPI.
The negotiated tunnel is TLS version 1.2 with mutual authentication, using the HTTP protocol version 1.1 with a minimum Cipher Suite of ECDHE-RSA-AES-128-GCM-SHA256.

This API will automatically decompress a response that comes compressed in the gzip standard. If you choose to compress the sending data, the API caller must do so in gzip format.

This request uses the following headers by default.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", where 0.0.0.0 is the version of the HSM client library used.

Certificate validation with the host name is done by checking that the Common Name field or Subject Alternate Name field of the certificate matches the host name of the URL passed as a parameter.

When making an HTTP request, 2 operations are performed, one to use the HSM objects (private key, certificate and chain, used for tunnel authentication) and the other to open the HTTP session with the HTTP server.
To optimize resources, the session with the HTTP server is kept open and cached; likewise, the session with the HSM is cached by default (the HSM session can optionally be set not to be cached).
The HTTP session is associated with the session opened with the HSM, which means that to reuse an HTTP session you must use the same HSM session that was previously used to open the HTTP session.
The HTTP session is physically closed when the session with the HSM is physically closed.
The HSM session and the HTTP session have thread-session affinity and cannot be used simultaneously by several threads.

Long Polling is adjusted by setting the HTTP operation timeout (POST/GET/DELETE) according to the HTTP server settings.

◆ putPix() [2/2]

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

It makes a secure HTTP PUT request following the PIX standard defined in the SPI (Instant Payment System).

Note: Configure timeout settings. Refer to the Best Practices section for more details.

Parameters

strKeyId Name of the private key used for tunnel establishment. Corresponds to a CPIC certificate.

strCertId Name of the certificate used for tunnel establishment. This is the PSP Digital Certificate registered with SPI for connection, also known as CPIC or CERTPIC.

strPIXCertChainId Name of the PKCS#7 string used to check the PIX server (ICOM or DICT). As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object containing several strings.

strURL URL of the server PIX (ICOM or DICT).

straRequestHeaderList Lines containing the customized HTTP headers that will be used in the request. Can be passed null if you want to use the default header without changes.
This option will overwrite the default headers if they overlap.
To remove a header, pass the name of the header without a value (e.g. Accept:).
To include a header with no content, use ; instead of : (e.g. Accept;).
Do NOT use CRLF terminators in headers. Passing these terminators may cause unwanted behavior. Formatting will be done internally.
This option cannot be used to change the first line of the request (e.g. POST, PUT, GET, DELETE), which is not a header. The corresponding API, described in this manual, must be used.
The default initial header includes Host, User-Agent, Accept, Accept-Encoding, Expect and Content-Length.

baRequestData Data sent in the request.

nTimeOut Operation timeout in milliseconds. Can be set to 0 for no timeout.

nParam

Value	Meaning
0	Default option. Does not verify the certificate against the hostname.
TacNDJavaLib.PIX_VERIFY_HOST_NAME	Verifies the certificate against the hostname.
TacNDJavaLib.PIX_BASIC_HTTP_HEADER	Uses the basic initial HTTP header. Includes Host, User-Agent, and Content-Length.
TacNDJavaLib.PIX_GZIP	Performs automatic gzip compression of request data. Automatically includes the necessary headers (Content-Encoding and Accept-Encoding).

Returns: Request response.

Exceptions

TacException Throws an exception in case of signature errors.

Notes: It executes a secure request following the PIX standard defined in the SPI in the documents: "Annex IV - Security Manual", "Technical and business specifications of the Brazilian instant payment ecosystem" and "Annex III - Communication Interfaces Manual" defined in the SPI.
The negotiated tunnel is TLS version 1.2 with mutual authentication, using the HTTP protocol version 1.1 with a minimum Cipher Suite of ECDHE-RSA-AES-128-GCM-SHA256.

This API will automatically decompress a response that comes compressed in the gzip standard. If you choose to compress the sending data, the API caller must do so in gzip format.

This request uses the following headers by default.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", where 0.0.0.0 is the version of the HSM client library used.

Certificate validation with the host name is done by checking that the Common Name field or Subject Alternate Name field of the certificate matches the host name of the URL passed as a parameter.

When making an HTTP request, 2 operations are performed, one to use the HSM objects (private key, certificate and chain, used for tunnel authentication) and the other to open the HTTP session with the HTTP server.
To optimize resources, the session with the HTTP server is kept open and cached; likewise, the session with the HSM is cached by default (the HSM session can optionally be set not to be cached).
The HTTP session is associated with the session opened with the HSM, which means that to reuse an HTTP session you must use the same HSM session that was previously used to open the HTTP session.
The HTTP session is physically closed when the session with the HSM is physically closed.
The HSM session and the HTTP session have thread-session affinity and cannot be used simultaneously by several threads.

Long Polling is adjusted by setting the HTTP operation timeout (POST/GET/DELETE) according to the HTTP server settings.

◆ getPix() [1/2]

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

It makes a secure HTTP GET request following the PIX standard defined in the SPI (Instant Payment System).

Uses the basic initial HTTP header.

Note: Configure timeout settings. Refer to the Best Practices section for more details.

Parameters

strKeyId	Name of the private key used for tunnel establishment. Corresponds to a CPIC certificate.
strCertId	Name of the certificate used for tunnel establishment. This is the PSP Digital Certificate registered with SPI for connection, also known as CPIC or CERTPIC.
strPIXCertChainId	Name of the PKCS#7 string used to check the PIX server (ICOM or DICT). As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object containing several strings.
strURL	URL of the server PIX (ICOM or DICT).
straRequestHeaderList	Lines containing the customized HTTP headers that will be used in the request. Can be passed null if you want to use the default header without changes. This option will overwrite the default headers if they overlap. To remove a header, pass the name of the header without a value (e.g. `Accept:`). To include a header with no content, use `;` instead of `:` (e.g. `Accept;`). Do NOT use CRLF terminators in headers. Passing these terminators may cause unwanted behavior. Formatting will be done internally. This option cannot be used to change the first line of the request (e.g. POST, PUT, GET, DELETE), which is not a header. The corresponding API, described in this manual, must be used. The default initial header includes Host, User-Agent, Accept, Accept-Encoding.
nTimeOut	Operation timeout in milliseconds. Can be set to 0 for no timeout.
bUseGzip	Includes the Accept-Encoding: gzip header if the basic header is enabled.
bVerifyHostName	Verifies the certificate against the hostname.

Returns: Request response.

Exceptions

TacException Throws an exception in case of signature errors.

Notes: It executes a secure request following the PIX standard defined in the SPI in the documents: "Annex IV - Security Manual", "Technical and business specifications of the Brazilian instant payment ecosystem" and "Annex III - Communication Interfaces Manual" defined in the SPI.
The negotiated tunnel is TLS version 1.2 with mutual authentication, using the HTTP protocol version 1.1 with a minimum Cipher Suite of ECDHE-RSA-AES-128-GCM-SHA256.

This API will automatically decompress a response that comes compressed in the gzip standard. If you choose to compress the sending data, the API caller must do so in gzip format.

This request uses the following headers by default.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", where 0.0.0.0 is the version of the HSM client library used.

Certificate validation with the host name is done by checking that the Common Name field or Subject Alternate Name field of the certificate matches the host name of the URL passed as a parameter.

When making an HTTP request, 2 operations are performed, one to use the HSM objects (private key, certificate and chain, used for tunnel authentication) and the other to open the HTTP session with the HTTP server.
To optimize resources, the session with the HTTP server is kept open and cached; likewise, the session with the HSM is cached by default (the HSM session can optionally be set not to be cached).
The HTTP session is associated with the session opened with the HSM, which means that to reuse an HTTP session you must use the same HSM session that was previously used to open the HTTP session.
The HTTP session is physically closed when the session with the HSM is physically closed.
The HSM session and the HTTP session have thread-session affinity and cannot be used simultaneously by several threads.

Long Polling is adjusted by setting the HTTP operation timeout (POST/GET/DELETE) according to the HTTP server settings.

◆ getPix() [2/2]

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

It makes a secure HTTP GET request following the PIX standard defined in the SPI (Instant Payment System).

Note: Configure timeout settings. Refer to the Best Practices section for more details.

Parameters

strKeyId Name of the private key used for tunnel establishment. Corresponds to a CPIC certificate.

strCertId Name of the certificate used for tunnel establishment. This is the PSP Digital Certificate registered with SPI for connection, also known as CPIC or CERTPIC.

strPIXCertChainId Name of the PKCS#7 string used to check the PIX server (ICOM or DICT). As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object containing several strings.

strURL URL of the server PIX (ICOM or DICT).

straRequestHeaderList Lines containing the customized HTTP headers that will be used in the request. Can be passed null if you want to use the default header without changes.
This option will overwrite the default headers if they overlap.
To remove a header, pass the name of the header without a value (e.g. Accept:).
To include a header with no content, use ; instead of : (e.g. Accept;).
Do NOT use CRLF terminators in headers. Passing these terminators may cause unwanted behavior. Formatting will be done internally.
This option cannot be used to change the first line of the request (e.g. POST, PUT, GET, DELETE), which is not a header. The corresponding API, described in this manual, must be used.
The default initial header includes Host, User-Agent, Accept, Accept-Encoding.

nTimeOut Operation timeout in milliseconds. Can be set to 0 for no timeout.

nParam

Value	Meaning
0	Default option. Does not verify the certificate against the hostname.
TacNDJavaLib.PIX_VERIFY_HOST_NAME	Verifies the certificate against the hostname.
TacNDJavaLib.PIX_BASIC_HTTP_HEADER	Uses the basic initial HTTP header. Includes Host and User-Agent.
TacNDJavaLib.PIX_GZIP	Includes the Accept-Encoding: gzip header if the basic header is enabled.

Returns: Request response.

Exceptions

TacException Throws an exception in case of signature errors.

Notes: It executes a secure request following the PIX standard defined in the SPI in the documents: "Annex IV - Security Manual", "Technical and business specifications of the Brazilian instant payment ecosystem" and "Annex III - Communication Interfaces Manual" defined in the SPI.
The negotiated tunnel is TLS version 1.2 with mutual authentication, using the HTTP protocol version 1.1 with a minimum Cipher Suite of ECDHE-RSA-AES-128-GCM-SHA256.

This API will automatically decompress a response that comes compressed in the gzip standard. If you choose to compress the sending data, the API caller must do so in gzip format.

This request uses the following headers by default.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", where 0.0.0.0 is the version of the HSM client library used.

Certificate validation with the host name is done by checking that the Common Name field or Subject Alternate Name field of the certificate matches the host name of the URL passed as a parameter.

When making an HTTP request, 2 operations are performed, one to use the HSM objects (private key, certificate and chain, used for tunnel authentication) and the other to open the HTTP session with the HTTP server.
To optimize resources, the session with the HTTP server is kept open and cached; likewise, the session with the HSM is cached by default (the HSM session can optionally be set not to be cached).
The HTTP session is associated with the session opened with the HSM, which means that to reuse an HTTP session you must use the same HSM session that was previously used to open the HTTP session.
The HTTP session is physically closed when the session with the HSM is physically closed.
The HSM session and the HTTP session have thread-session affinity and cannot be used simultaneously by several threads.

Long Polling is adjusted by setting the HTTP operation timeout (POST/GET/DELETE) according to the HTTP server settings.

◆ deletePix() [1/2]

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

It makes a secure HTTP DELETE request following the PIX standard defined in SPI (Instant Payment System).

Uses the basic initial HTTP header.

Note: Configure timeout settings. Refer to the Best Practices section for more details.

Parameters

strKeyId	Name of the private key used for tunnel establishment. Corresponds to a CPIC certificate.
strCertId	Name of the certificate used for tunnel establishment. This is the PSP Digital Certificate registered with SPI for connection, also known as CPIC or CERTPIC.
strPIXCertChainId	Name of the PKCS#7 string used to check the PIX server (ICOM or DICT). As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object containing several strings.
strURL	URL of the server PIX (ICOM or DICT).
straRequestHeaderList	Lines containing the customized HTTP headers that will be used in the request. Can be passed null if you want to use the default header without changes. This option will overwrite the default headers if they overlap. To remove a header, pass the name of the header without a value (e.g. `Accept:`). To include a header without content, use `;` instead of `:` (e.g. `Accept;`). Do NOT use CRLF terminators in headers. Passing these terminators may cause unwanted behavior. Formatting will be done internally. This option cannot be used to change the first line of the request (e.g. POST, PUT, GET, DELETE), which is not a header. The corresponding API, described in this manual, must be used. The default initial header includes Host and User-Agent.
nTimeOut	Operation timeout in milliseconds. Can be set to 0 for no timeout.
bUseGzip	Includes the Accept-Encoding: gzip header if the basic header is enabled.
bVerifyHostName	Verifies the certificate against the hostname.

Returns: Request response.

Exceptions

TacException Throws an exception in case of signature errors.

Notes: It executes a secure request following the PIX standard defined in the SPI in the documents: "Annex IV - Security Manual", "Technical and business specifications of the Brazilian instant payment ecosystem" and "Annex III - Communication Interfaces Manual" defined in the SPI.
The negotiated tunnel is TLS version 1.2 with mutual authentication, using the HTTP protocol version 1.1 with a minimum Cipher Suite of ECDHE-RSA-AES-128-GCM-SHA256.

This API will automatically decompress a response that comes compressed in the gzip standard. If you choose to compress the sending data, the API caller must do so in gzip format.

This request uses the following headers by default.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", where 0.0.0.0 is the version of the HSM client library used.

Certificate validation with the host name is done by checking that the Common Name field or Subject Alternate Name field of the certificate matches the host name of the URL passed as a parameter.

When making an HTTP request, 2 operations are performed, one to use the HSM objects (private key, certificate and chain, used for tunnel authentication) and the other to open the HTTP session with the HTTP server.
To optimize resources, the session with the HTTP server is kept open and cached; likewise, the session with the HSM is cached by default (the HSM session can optionally be set not to be cached).
The HTTP session is associated with the session opened with the HSM, which means that to reuse an HTTP session you must use the same HSM session that was previously used to open the HTTP session.
The HTTP session is physically closed when the session with the HSM is physically closed.
The HSM session and the HTTP session have thread-session affinity and cannot be used simultaneously by several threads.

Long Polling is adjusted by setting the HTTP operation timeout (POST/GET/DELETE) according to the HTTP server settings.

◆ deletePix() [2/2]

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

It makes a secure HTTP DELETE request following the PIX standard defined in SPI (Instant Payment System).

Note: Configure timeout settings. Refer to the Best Practices section for more details.

Parameters

strKeyId Name of the private key used for tunnel establishment. Corresponds to a CPIC certificate.

strCertId Name of the certificate used for tunnel establishment. This is the PSP Digital Certificate registered with SPI for connection, also known as CPIC or CERTPIC.

strPIXCertChainId Name of the PKCS#7 string used to check the PIX server (ICOM or DICT). As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object containing several strings.

strURL URL of the server PIX (ICOM or DICT).

straRequestHeaderList Lines containing the customized HTTP headers that will be used in the request. Can be passed null if you want to use the default header without changes.
This option will overwrite the default headers if they overlap.
To remove a header, pass the name of the header without a value (e.g. Accept:).
To include a header with no content, use ; instead of : (e.g. Accept;).
Do NOT use CRLF terminators in headers. Passing these terminators may cause unwanted behavior. Formatting will be done internally.
This option cannot be used to change the first line of the request (e.g. POST, PUT, GET, DELETE), which is not a header. The corresponding API, described in this manual, must be used.
The default initial header includes Host, User-Agent, Accept, Accept-Encoding.

nTimeOut Operation timeout in milliseconds. Can be set to 0 for no timeout.

nParam

Value	Meaning
0	Default option. Does not verify the certificate against the hostname.
TacNDJavaLib.PIX_VERIFY_HOST_NAME	Verifies the certificate against the hostname.
TacNDJavaLib.PIX_BASIC_HTTP_HEADER	Uses the basic initial HTTP header. Includes Host and User-Agent.
TacNDJavaLib.PIX_GZIP	Includes the Accept-Encoding: gzip header if the basic header is enabled.

Returns: Request response.

Exceptions

TacException Throws an exception in case of signature errors.

Notes: It executes a secure request following the PIX standard defined in the SPI in the documents: "Annex IV - Security Manual", "Technical and business specifications of the Brazilian instant payment ecosystem" and "Annex III - Communication Interfaces Manual" defined in the SPI.
The negotiated tunnel is TLS version 1.2 with mutual authentication, using the HTTP protocol version 1.1 with a minimum Cipher Suite of ECDHE-RSA-AES-128-GCM-SHA256.

This API will automatically decompress a response that comes compressed in the gzip standard. If you choose to compress the sending data, the API caller must do so in gzip format.

This request uses the following headers by default.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", where 0.0.0.0 is the version of the HSM client library used.

Certificate validation with the host name is done by checking that the Common Name field or Subject Alternate Name field of the certificate matches the host name of the URL passed as a parameter.

When making an HTTP request, 2 operations are performed, one to use the HSM objects (private key, certificate and chain, used for tunnel authentication) and the other to open the HTTP session with the HTTP server.
To optimize resources, the session with the HTTP server is kept open and cached; likewise, the session with the HSM is cached by default (the HSM session can optionally be set not to be cached).
The HTTP session is associated with the session opened with the HSM, which means that to reuse an HTTP session you must use the same HSM session that was previously used to open the HTTP session.
The HTTP session is physically closed when the session with the HSM is physically closed.
The HSM session and the HTTP session have thread-session affinity and cannot be used simultaneously by several threads.

Long Polling is adjusted by setting the HTTP operation timeout (POST/GET/DELETE) according to the HTTP server settings.

◆ getPixHTTPReqDetails()

PIXHTTPReqDetails getPIXHTTPReqDetails ( ) throws TacException

Retrieves the details of the last PIX HTTP request (POST, GET...) made in this session.

This operation must be called immediately after calling the PIX request API. It must be called using the same session. Do not perform any other operations between these calls.

Returns: Details of the last PIX HTTP request for this session.

Exceptions

TacException Throws an exception in case of signature errors.

◆ getPixHTTPReqCode()

long getPIXHTTPReqCode ( ) throws TacException

Retrieves the return code of the last PIX HTTP request (POST, GET...) made in this session.

This operation must be called immediately after calling the PIX request API. It must be called using the same session. Do not perform any other operations between these calls.

Returns: HTTP response code.

Exceptions

TacException Throws an exception on error.