java-pix

en

Java library to build brazil's PIX Copy & Paste. Useful to build charges.

pt-br

Biblioteca java para construir PIX copia e cola. Útil para criar "cobranças" com dados predefinidos.

usage

Built with java 17

import

<dependency>
    <groupId>com.iskeru</groupId>
    <artifactId>java-pix</artifactId>
    <version>1.2.0</version>
</dependency>

Important: Most Brazilian banks require that the transaction id (txid) be present for the copied PIX code to be accepted when pasting in the banking app. Always set a txid in your PixTransaction when generating a Copy & Paste code.

Ex:

PixCopyAndPaste pix = PixCopyAndPaste.builder()
        .to(PixTarget.builder()
                .chavePix("minha-chave")
                .cidade("SAO PAULO")
                .nome("Person Person")
                .build())
        .transfer(PixTransaction.builder()
                .idTransacao("MEU_TXID_123")
                .valorTransacao(new BigDecimal("12.34"))
                .build())
        .build();

Atenção (pt-br): A maioria dos bancos exige que o identificador da transação (txid) esteja presente para que o código PIX Copia e Cola seja aceito ao colar no app. Sempre informe um txid em PixTransaction ao gerar o código.

code

Build simple copia e cola.

PIX Key / Chave PIX

PixCopyAndPaste pix = PixCopyAndPaste.builder()
        .to(PixTarget.builder()
                .chavePix("minha-chave")
                .cidade("SAO PAULO")
                .nome("Person Person")
                .build())
        .transfer(PixTransaction.builder().valorTransacao(new BigDecimal("12.34")).build())
        .build();

PIX phone number / telefone

// when key is a phone number, for instance: (11) 98181-1212
PixTarget.builder().chavePix("+5511981811212").build();

PIX E-mail

// when key is a e-mail
PixTarget.builder().chavePix("someone@gmail.com").build();

parse / validate

You can parse and validate a PIX Copy & Paste string generated by this library (or compatible ones).

String payload = "00020126330014BR.GOV.BCB.PIX0111minha-chave520400005303986540512.345802BR5913Person Person6009SAO PAULO62110507myidis16304E3BF";
PixCopyAndPaste parsed = PixCopyAndPasteParser.parse(payload);

// Access parsed models via getters
PixTarget target = parsed.to();
PixTransaction tx = parsed.transfer();

// A CRC field (63) is validated when present; an invalid CRC throws IllegalArgumentException.
// Payloads without CRC are accepted and parsed as well.

current limitations

• Only fields used by this project are parsed/validated: 00, 26 (00 GUI, 01 pix key), 52, 53, 54, 58, 59, 60, 62 (05 txid), and 63 (CRC).
• Unknown/new PIX fields are ignored during parsing.
• Merchant Account Info GUI is expected to be BR.GOV.BCB.PIX (lowercase br.gov.bcb.pix is also accepted). Other GUIs will be rejected.
• Amount (54) is required for parsing to succeed.