Trying to pay a Pix QR Code in Sandbox without a registered key = 404 error

Context

When using the endpoint:

POST 

/v3/pix/qrCodes/pay

in the Sandbox environment, a 404 Not Found error may occur when attempting to pay a Pix QR Code generated from a charge created through the interface, without a Pix key registered on the account.

This error occurs because, in the testing environment, the Pix QR Code payload is not registered when the account does not have a valid Pix key — or when the charge was created using the Bradesco Pix integration (which does not generate the payload in Sandbox).

Important note

Although the 404 error is technically correct (the payload truly does not exist in Sandbox), we understand that this may cause confusion for developers integrating with the API, since:

The endpoint being used is valid;
The payload was correctly extracted from the charge;
The expectation is that the QR Code should work for testing purposes.

Example scenario that generates the error

The flow below usually results in a 404 Not Found error in Sandbox:

Account without a Pix key
        ↓
Create charge through the interface
        ↓
Generate Pix QR Code
        ↓
Copy payload
        ↓
Send to /v3/pix/qrCodes/pay
        ↓
404 Error

Request example:

{
  "qrCode": {
    "payload": "payloadObtainedFromTheCharge"
  },
  "value": 50
}

In this scenario, the error occurs because the QR Code payload was not registered in the Sandbox environment.

How to avoid the error

To ensure the test works in the homologation environment (Sandbox), it is necessary to register a Pix key on the account and generate a new charge with a QR Code associated with that key.

See the call to make a QR Code payment here.

Recommended homologation flow

To avoid this behavior:

Register a Pix key in the Sandbox account.
Generate a new Pix charge after registering the key.
Obtain the payload from the generated QR Code.
Execute the payment again using the endpoint.
Validate the creation of the Pix charge and the payment processing.

Simplified flow:

Register Pix key
        ↓
Create Pix charge
        ↓
Obtain payload
        ↓
Pay QR Code
        ↓
Process payment