Testing Pix QR Code payment

Use the Sandbox to validate a Pix QR Code payment without moving real money.

In this flow, one Sandbox account generates the QR Code and another account, with an available balance, makes the payment.

When to use it

Use this flow to test:

• Pix QR Code payments;
• balance updates in the paying account;
• receipt of the amount in the destination account;
• processing of Pix transactions;
• Webhooks related to the operation;
• reconciliation between payment and receipt.

Before you start

You need to:

1. Have two Sandbox accounts:
   • a destination account, which will create the QR Code;
   • a paying account, which will make the payment.
2. Generate an API key for each account.
3. Have an available balance in the paying account.
4. Have a Pix key registered in the destination account.
5. Configure the Webhooks used by the integration.

If the paying account has no balance, see Add balance to your Sandbox account.

How it works

Destination Sandbox account
        ↓
Create Pix QR Code
        ↓
Get the payload
        ↓
Paying Sandbox account
        ↓
Pay the QR Code
        ↓
Validate balance, status, and Webhooks

1. Create the Pix QR Code

In the destination Sandbox account, use the static QR Code creation endpoint.

See the Create static QR Code endpoint.

Store the value returned in the payload field, as it will be used for the payment.

2. Pay the QR Code

In the paying Sandbox account, send the payload to the endpoint:

POST /v3/pix/qrCodes/pay

See the endpoint reference.

Request example

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

The main fields are:

See the reference for all filling rules.

3. Validate the result

After sending the request:

1. check the HTTP status and the response body;
2. store the transaction ID;
3. track the payment status;
4. validate the debit in the paying account;
5. validate the receipt in the destination account;
6. confirm the processing of the Webhooks.

Expected behavior

In the Sandbox:

• no real money is moved;
• no financial institution is contacted;
• the paying account's balance is updated;
• the destination account receives the simulated amount;
• the resources related to the Pix transaction become available for querying;
• the configured Webhooks can be used to validate processing.

If the receipt generates an automatic charge in the destination account, use the Pix-related fields to identify its origin.

If the payment is not created

Check that:

• the QR Code was created in the Sandbox;
• the payload was copied in full;
• the paying account has a balance;
• the destination account's Pix key is registered;
• the URL and the API key belong to the Sandbox;
• the amount provided is compatible with the QR Code;
• the required fields were sent correctly.

Differences between Sandbox and Production

A successful operation in the Sandbox does not guarantee that any payment will be completed in Production.

Validation checklist

Before considering the flow validated, confirm that your application:

• validates the balance before the payment;
• stores the transaction ID;
• tracks status changes;
• processes Webhooks idempotently;
• distinguishes the paying account from the receiving account;
• avoids duplicate payments;
• records logs and error messages;
• uses credentials that match the environment.

Next steps

• Create a static Pix QR Code
• Pay a Pix QR Code
• Add balance to the Sandbox account
• Test other features in the Sandbox