Pular para conteúdo

Criando uma cobrança PIX

Você pode criar, consultar e simular pagamentos via Pix diretamente pelo SDK da AbacatePay.

1. Criando um Pix QR Code

Você pode criar um Pix QR Code informando o valor, dados do cliente e uma descrição opcional.

from abacatepay import AbacatePay

client = AbacatePay("<sua chave de API>")
ONE_MINUTE = 60

pix_qr = client.pixQrCode.create(
    amount=500_00,  # (1)
    description="Assinatura mensal",
    expires_in=ONE_MINUTE,  # (2)
    customer={  # (3)
        "name": "Maria Silva",
        "email": "maria@email.com",
        "cellphone": "(11) 90000-0000",
        "tax_id": "123.456.789-00"
    }
)

print(pix_qr.status)
  1. O valor é em centavos (ex: 500_00 = R$ 500,00).
  2. O campo expires_in é opcional (em segundos). Ex: 600 = 10 minutos.
  3. Você pode passar o cliente como dict ou CustomerMetadata.
Referência para o método create

Create a new Pix QR Code.

Parameters:

Name Type Description Default
amount int

The amount to be paid in cents.

 required
expires_in int

The expiration time in seconds. Defaults to None.

 required
description str

A description for the Pix QR Code. Defaults to None.

 required
customer CustomerMetadata | dict

Customer information. Defaults to None.

 required

Returns: PixQrCode: The created Pix QR Code object.

Source code in abacatepay/pixQrCode/client.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
def create(self, data: PixQrCodeIn | dict[str, Any], **kwargs: Any) -> PixQrCode:
    """
    Create a new Pix QR Code.

    Args:
        amount (int): The amount to be paid in cents.
        expires_in (int, optional): The expiration time in seconds.
            Defaults to None.
        description (str, optional): A description for the Pix QR Code.
            Defaults to None.
        customer (CustomerMetadata | dict, optional): Customer information.
            Defaults to None.
    Returns:
        PixQrCode: The created Pix QR Code object.
    """
    json_data = prepare_data(data or kwargs, PixQrCodeIn)
    logger.debug('Creating Pix QR Code: %s', json_data)

    response = self._request(
        f'{BASE_URL}/pixQrCode/create',
        method='POST',
        json=json_data,
    )
    logger.debug('Pix QR Code created successfully: %s', response.json())
    return PixQrCode.model_validate(response.json()['data'])
O objeto PixQrCode

Bases: BaseModel

A representation of a Pix QRCode.

Attributes:

Name Type Description
id str

Unique identifier of the Pix QRCode.
amount int

Amount to be paid.
status str

Information about the status of the Pix QRCode.
dev_mode bool

Environment in which the Pix QRCode was created.
brcode str

Copy-and-paste code of the Pix QRCode.
brcode_base64 str

Base64 image of the Pix QRCode.
platform_fee int

Platform fees.
created_at str

Creation date of the Pix QRCode.
updated_at str

Update date of the Pix QRCode.
expires_at str

Expiration date of the Pix QRCode.
Source code in abacatepay/pixQrCode/models.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
class PixQrCode(BaseModel):
    """
    A representation of a Pix QRCode.

    Attributes:
        id (str): Unique identifier of the Pix QRCode.
        amount (int): Amount to be paid.
        status (str): Information about the status of the Pix QRCode.
        dev_mode (bool): Environment in which the Pix QRCode was created.
        brcode (str): Copy-and-paste code of the Pix QRCode.
        brcode_base64 (str): Base64 image of the Pix QRCode.
        platform_fee (int): Platform fees.
        created_at (str): Creation date of the Pix QRCode.
        updated_at (str): Update date of the Pix QRCode.
        expires_at (str): Expiration date of the Pix QRCode.
    """

    id: str = Field(
        description='Unique identifier of the Pix QRCode.',
        examples=['pix_char_123456'],
    )
    amount: int = Field(description='Amount to be paid.', examples=[100])
    status: PIX_QR_CODE_STATUS = Field(
        description=(
            'Information about the status of the Pix QRCode.'
            'Options: PENDING, EXPIRED, CANCELLED, PAID, REFUNDED'
        ),
        examples=['PENDING'],
    )
    dev_mode: bool = Field(
        description='Environment in which the Pix QRCode was created.',
        examples=[True],
        validation_alias='devMode',
    )
    brcode: str = Field(
        description='Copy-and-paste code of the Pix QRCode.',
        examples=['00020101021226950014br.gov.bcb.pix'],
        validation_alias='brCode',
    )
    brcode_base64: str = Field(
        description='Base64 image of the Pix QRCode.',
        examples=['data:image/png;base64,iVBORw0KGgoAAA'],
        validation_alias='brCodeBase64',
    )
    platform_fee: int = Field(
        description='Platform fees.',
        examples=[80],
        validation_alias='platformFee',
    )
    created_at: str = Field(
        description='Creation date of the Pix QRCode.',
        examples=['2025-03-24T21:50:20.772Z'],
        validation_alias='createdAt',
    )
    updated_at: str = Field(
        description='Update date of the Pix QRCode.',
        examples=['2025-03-24T21:50:20.772Z'],
        validation_alias='updatedAt',
    )
    expires_at: str = Field(
        description='Expiration date of the Pix QRCode.',
        examples=['2025-03-25T21:50:20.772Z'],
        validation_alias='expiresAt',
    )

2. Consultando o status do Pix

Após criar um Pix QR Code, você pode acompanhar seu status (se foi pago, expirado, etc).

status = client.pixQrCode.check(pix_qr.id)
print(status.status)
# > "PAID" ou "PENDING" ou "EXPIRED"

3. Simulando um pagamento (ambiente de testes)

Se estiver usando o ambiente sandbox, você pode simular um pagamento:

simulado = client.pixQrCode.simulate(pix_qr.id)
print(simulado.status)
# > "PAID"

Você também pode enviar metadados para simular o pagamento:

pix_status = client.pixQrCode.simulate(
    id=pix_qr.id,
    metadata={"origin": "test-script"}
)
print(pix_status.status)
O objeto PixStatus

Bases: BaseModel

Represents the status of a Pix QRCode.

Attributes:

Name Type Description
status str

Information about the status of the Pix QRCode.
expires_at str

Expiration date of the Pix QRCode.
Source code in abacatepay/pixQrCode/models.py 
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
class PixStatus(BaseModel):
    """Represents the status of a Pix QRCode.

    Attributes:
        status (str): Information about the status of the Pix QRCode.
        expires_at (str): Expiration date of the Pix QRCode.
    """

    status: PIX_QR_CODE_STATUS = Field(
        description=(
            'Information about the status of the Pix QRCode. '
            'Options: PENDING, EXPIRED, CANCELLED, PAID, REFUNDED'
        ),
        examples=['PENDING'],
    )
    expires_at: str | None = Field(
        None,
        description='Expiration date of the Pix QRCode.',
        examples=['2025-03-25T21:50:20.772Z'],
    )

Pronto! Agora você já pode gerar e gerenciar pagamentos via Pix de forma prática com a AbacatePay 🚀