Skip to content

Pix

The APIs of the Pix module are designed to use the functionalities of signing, verifying, sending and receiving HTTP requests Pix.

Network

The HSM does not directly access the Pix/DICT servers, but is positioned on the network for use by the PSP's internal servers.

---
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

Signature and Verification

The signature and verification APIs Pix are based on the ISO 20.022 standard, and the DICT APIs follow the XMLDSig format, both defined by SPI in the document "Annex IV - Security Manual".

The API functions for use with Pix and DICT signatures require the internal storage in the HSM of the digital certificates for digital signing and the complete chain of trust of the certificates for verification.

To write a digital certificate (or file) to the HSM, use the remote management console or the DWriteFile() API.

The digital certificate for signing must be encoded in ASN1 DER binary format and also comply with the X.509 standard. The file containing the chain of trust for digital signature verification must be encoded in PKCS#7 format (Public Key Cryptography Standard #7 – Cryptographic Message Syntax Standard).

The JWS signing and validation functions Pix follow RFC 7515 and the SPI documentation.

HTTP requests

The HTTP request APIs Pix provide secure HTTP communication with the Pix or DICT servers, using the keys and certificates protected by the HSM.

The standard secure communication functions Pix that follow the definitions described in the following 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.

Operation

The secure connection is made between the PSP server and the Pix/DICT server, the HSM is only used to use PSP objects and private keys.

Access to the HSM only occurs during the TLS handshake. After the tunnel is closed, communication is only maintained between the PSP server and the Pix/DICT server.

---
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<br>credenciais do PSP
    psp ->> psp: Autentica SPI
    psp ->> hsm: Requisita informações<br>de autenticação
    hsm ->> hsm: Gera assinatura<br>para autenticação TLS
    destroy hsm
    hsm ->> psp: Envia assinatura
    psp ->> spi: Envia dados<br>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<br>Pix/Dict
        spi ->> psp: Resposta
    end

Requests are made using a handle Pix, created by DPIXOpenHandle(). The handle stores the authentication credentials and the identifiers of the objects used in the handshake (private key, certificate, and peer chain), and is not tied to an HSM session: the session is opened only during the TLS handshake and released immediately afterward.

All HTTP methods pass through a single function, DPIXRequest(), which receives the method (POST, PUT, GET, or DELETE) in the request structure.

A handle can be created in two ways:

  • Standard: A handle is a lightweight reference with no connection of its own. Each request borrows a connection from the HTTP connection cache and returns it when finished. Multiple handles share the same connections, and the number of connections reflects the application's actual concurrency, not the number of open handles.
  • Exclusive (DN_PIX_NO_CACHE): The handle maintains its own HTTP connection until it is closed and is not cached. Use this when the application requires a one-to-one correspondence between the handle and the connection—that is, when the number of open connections to the peer needs to be predictable and controlled by the application itself.
---
title: Handles Pix e conexões HTTP
---

%%{ init: { 'flowchart': { 'curve': 'basis' } } }%%
flowchart LR
    cache[("Cache de<br>conexões HTTP")]
    spi["SPI (Pix/Dict)"]

    subgraph app [Aplicação]
      h1[Handle padrão]
      h2[Handle padrão]
      h3["Handle exclusivo<br>(DN_PIX_NO_CACHE)"]
    end

    h1 --> cache
    h2 --> cache
    cache --> spi
    h3 --> spi

The cache reuses the most recently used (MRU) idle connection among those that correspond to the same identity, the same objects, and the same destination, which keeps a small set of connections active and allows the rest to expire due to inactivity. See HTTP Connection Cache Pix.

In both modes, the handle follows the same usage contract as the HSM session handle: it can be used by multiple threads, but never simultaneously. To make parallel requests, open one handle per thread—in the default mode, this does not imply one connection per handle, since they all share the same cache.

JWS

The Pix module provides APIs to help use the dynamic QR Code Pix. APIs are available for signing and checking JWS (JSON Web Signature).

Trade Name

See the Modules topic for the current commercial name of the module; it will be used in presentations, marketing and promotional material, commercial proposals, and contracts.

License

See the Licenses and Modules topics for information on whether a specific license is required to use the module's APIs and what the name of this license is.

API Pix

Specific API documentation for the Pix module, with functions, classes and examples.