Testing Pix QR Code Payment

The Sandbox environment allows you to validate the complete Pix QR Code payment flow, enabling you to test integrations related to payment receipt without moving real funds.

This scenario is especially useful for validating Pix charge creation, payment processing, webhook delivery, and status updates performed by your application.

When to use

Use this flow when you need to:

• homologate Pix payments;
• validate Pix QR Code integrations;
• test Pix receipts in a controlled environment;
• validate webhooks related to Pix charges;
• verify your application's behavior after a payment has been settled.

Prerequisites

Before starting the tests, you must:

1. Have a Sandbox account.
2. Have a Sandbox API Key.
3. Create a static Pix QR Code in the Sandbox environment.
4. Use the Pix QR Code payment endpoint.

See also:

• Create a static QR Code
• Pay a QR Code

How the test works

The process consists of generating a static Pix QR Code and then using the returned payload to simulate the payment.

Simplified flow:

Create Pix QR Code
        ↓
Obtain payload
        ↓
Execute payment
        ↓
Create Pix charge
automatically
        ↓
Update status
        ↓
Validate integration

Important request fields

When using the Pix QR Code payment endpoint, some fields play a fundamental role:

📘

Important

The payload must be obtained from the Pix QR Code creation process in Sandbox.

The complete request parameters are documented in the official endpoint reference.

Request example

After creating a static Pix QR Code in Sandbox, use the payment endpoint by sending the returned payload.

POST /v3/pix/qrCodes/pay

See the complete reference for this endpoint

{
  "qrCode": {
    "payload": "00020126710014br.gov.bcb.pix01362ae3db4c-9f04-44de-9a39-adcc98a334c20209Churrasco520400005303986540550.005802BR5913John Doe6009Joinville62290525JHOND00000000465493ASA6304DB5E"
  },
  "value": 50
}

Expected behavior

When the payment is executed:

• a Pix charge will be created automatically;
• the payment will be processed in the Sandbox environment;
• Pix-related identifiers will be linked to the charge;
• your integration will be able to validate the events and updates resulting from the operation.

The automatically created charge will have the following fields:

• pixTransaction
• pixQrCodeId

filled with information related to the simulated transaction.

Differences between Sandbox and Production

For this reason, it is recommended to carefully validate the flows before going live in production.

Possible difficulties

If the payment is not processed as expected, check whether:

• the QR Code was created in the Sandbox environment;
• the payload used corresponds to the generated QR Code;
• authentication is being performed using a Sandbox API Key;
• the required request fields were sent correctly;
• the provided amount is compatible with the QR Code being used.

Best practices

📘

Recommended

• Always use the payload returned by the QR Code creation process.
• Validate the receipt of webhooks related to the Pix charge.
• Test both QR Code creation and payment during homologation.
• Do not use production data during testing.
• Monitor API responses to validate the expected integration behavior.

Operational impacts

Paying a Pix QR Code may automatically generate a Pix charge associated with the operation.

For this reason, integrations that perform:

• financial reconciliation;
• receipt management;
• charge-based automations;
• webhook processing;

must consider the automatic creation of this charge during testing and also in the production environment.

Proper homologation allows you to validate the entire Pix receipt journey before going live.