Skip to main content

Troubleshooting

This section provides guidance on resolving common issues related to Pix Cash-in and QR Codes.

Cash-in Payment Not Found​

If a payment is queried and is not found on our side, the following must be verified on the payer's side:

  • Ensure that the transaction was indeed successfully debited from the payer's account.
  • Ensure that the transaction was successfully forwarded to the SPI (Sistema de Pagamentos Instantâneos).
  • Confirm that the transaction was not reversed or undone (desfazimento) on the payer's side.

If all these conditions are met and the payment is still not found, please contact our support team.

QRCode Troubleshooting​

This section describes common errors when using QRCode endpoints, their possible causes, and how to resolve them.

QRCode processing is asynchronous and may return false positives, so a 200 status at some point does not guarantee success.

Common errors​

1. POST /pix/qrcode/static - Missing or empty body​

Example​
{
  "title": "Please refer to the errors property for additional details.",
  "code": "UNPROCESSABLE_ENTITY",
  "errors": [
    "Corpo da requisição inválido ou malformado"
  ]
}
Cause​

The request did not include a body, even an empty one {}.

Solution​

Ensure to send a valid JSON body, even if empty.

Example with curl:

curl -X POST https://apisandbox.delbank.com.br/baas/api/v2/pix/qrcode/static \
  -H "x-delbank-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{}"

2. GET /pix/qrcode/static/:transactionIdentifier - Invalid or missing ID​

Example​
{
  "title": "Not Found",
  "status": 404
}
Cause​

The transactionIdentifier does not belong to the account, is incorrect, or was not provided in the request.

Solution​

Verify that the transactionIdentifier is correct and belongs to your account. Ensure it is included in the URL path.

3. PATCH /pix/qrcode/static/:transactionIdentifier/cancel - QR Code not found​

Example​
{
  "title": "Please refer to the errors property for additional details.",
  "code": "QR_CODE_NOT_FOUND",
  "errors": [
    "QR Code não encontrado"
  ]
}
Cause​

The transactionIdentifier does not belong to the account, is incorrect, or was not provided in the request.

Solution​

Check that the transactionIdentifier is valid and associated with your account. Ensure it is included in the URL path.

4. POST /pix/qrcode/dynamic - Incomplete address object​

Example​
{
  "title": "Please refer to the errors property for additional details.",
  "code": "UNPROCESSABLE_ENTITY",
  "errors": [
    "Address: Os campos 'cityName', 'zipCode', 'state' devem ser informados"
  ]
}
Cause​

The address object is incomplete; required fields like 'cityName', 'zipCode', 'state' are missing.

Solution​

Provide all required fields in the address object: cityName, zipCode, state, uf, street.

5. POST /pix/qrcode/dynamic - Incomplete payer object​

Example​
{
  "title": "Please refer to the errors property for additional details.",
  "code": "UNPROCESSABLE_ENTITY",
  "errors": [
    "Payer: Os campos 'name' e 'document' devem ser informados"
  ]
}
Cause​

The payer object is incomplete; required fields like 'name' and 'document' are missing.

Solution​

Include all required fields in the payer object: name, document, validate (optional).

6. POST /pix/qrcode/dynamic - Invalid formatResponse value​

Example​
{
  "title": "Please refer to the errors property for additional details.",
  "code": "INVALID_ARGUMENT",
  "errors": [
    "formatResponse: Valores aceitos: [ONLY_PAYLOAD, PAYLOAD_AND_QRCODE]"
  ]
}
Cause​

The formatResponse field contains an invalid value.

Solution​

Use only accepted values: ONLY_PAYLOAD or PAYLOAD_AND_QRCODE.

7. POST /pix/qrcode/dynamic - additionalInfos missing value​

Example​
{
  "title": "Please refer to the errors property for additional details.",
  "code": "UNPROCESSABLE_ENTITY",
  "errors": [
    "Corpo da requisição inválido ou malformado"
  ]
}
Cause​

In additionalInfos array, an object has "name": "Split" but is missing the "value" attribute.

Solution​

Ensure each additionalInfos object has both "name" and "value" fields.

8. POST /pix/qrcode/dynamic - additionalInfos missing name​

Example​
{
  "title": "Please refer to the errors property for additional details.",
  "code": "INVALID_ARGUMENT",
  "errors": [
    "additionalInfos[0].name: não deve estar em branco"
  ]
}
Cause​

In additionalInfos array, an object has "value": "Teste" but is missing the "name" attribute.

Solution​

Provide the "name" field for each additionalInfos object.

9. POST /pix/qrcode/due-date - taxes without dueDate​

Example​
{
  "title": "Please refer to the errors property for additional details.",
  "code": "INVALID_ARGUMENT",
  "errors": [
    "taxes: só deve ser informado se dueDate também for informado",
    "dueDate: não deve ser nulo"
  ]
}
Cause​

Taxes were provided without specifying dueDate.

Solution​

Include dueDate when providing taxes.

10. POST /pix/qrcode/due-date - Missing dueDate​

Example​
{
  "title": "Please refer to the errors property for additional details.",
  "code": "INVALID_ARGUMENT",
  "errors": [
    "dueDate: não deve ser nulo"
  ]
}
Cause​

The dueDate field is missing.

Solution​

Provide the dueDate field in the request.

Diagnostic Checklist​

Before opening a support ticket, please verify:

  • Correct API Key and headers
  • Valid JSON body with all required fields
  • TransactionIdentifier is correct and belongs to your account
  • Asynchronous processing may cause delays

Useful Information for Support​

If you need to open a support ticket, please provide:

  • Endpoint used
  • Request body (if applicable)
  • Timestamp of the request
  • Account ID
  • API Key (partial)
  • The returned error log