Tratamento de erros do Pix Automático

Esta página apresenta apenas os retornos específicos do Pix Automático. Consulte também todos os tipos de códigos de retorno da API em Códigos da API .

A API retorna os códigos HTTP conforme a especificação em Status HTTP . Quando a API retorna o código HTTP 201 (Created) ou 200 (Ok), verifique também os códigos complementares no corpo da resposta:

ReasonCode e ReasonMessage dentro do objeto RecurrentPayment: indicam o resultado da criação da recorrência por Pix Automático;

{ (...)
"RecurrentPayment": {
            "RecurrenceType": "SelfManagedConsent",
            "RetryPolicy": "Allowed_3R_7D",
            "Plan": "Convenio",
            "ReasonCode": 3,
            "ReasonMessage": "OPERACAO INVALIDA. VERIFIQUE OS DADOS ENVIADOS",
            "StartDate": "2025-12-01",
            "EndDate": "2030-12-31",
            "Interval": 1,
            "AuthorizeNow": false
	}
}

{ (...)
"RecurrentPayment": {
            "RecurrenceType": "SelfManagedConsent",
            "RetryPolicy": "Allowed_3R_7D",
            "Plan": "Convenio",
            "ReasonCode": 0,
            "ReasonMessage": "OPERACAO REALIZADA COM SUCESSO",
            "StartDate": "2025-12-01",
            "EndDate": "2030-12-31",
            "Interval": 1,
            "AuthorizeNow": false
	}
}

ReturnCode e ReturnMessage dentro do objeto Payment : indicam o resultado da criação da transação de Pix.

{
    (...),
    "Payment": {
        "RecurrentPayment": {
(...)
        },
        "Amount": 0,
        "ReceivedDate": "2025-11-11 09:18:36",
        "Provider": "Cielo2",
        "Status": 0,
        "ReturnMessage": "OPERACAO INVALIDA. VERIFIQUE OS DADOS ENVIADOS",
        "ReturnCode": "3",
        "PaymentId": "3729f703-5e52-4h9c-9af3-4a24c26fb9c9",
        "Type": "Pix",
        "Currency": "BRL",
        "Country": "BRA",
        "Links": [
            {
(...)
            }
        ]
    },
(...)
}

{
    (...),
    "Payment": {
        "RecurrentPayment": {
(...)
        },
        "Amount": 0,
        "ReceivedDate": "2025-11-11 09:18:36",
        "Provider": "Cielo2",
        "Status": 12,
        "ReturnMessage": "QR Code PIX gerado com sucesso.",
        "ReturnCode": "0",
        "PaymentId": "3729f703-5e52-4h9c-9af3-4a24c26fb9c9",
        "Type": "Pix",
        "Currency": "BRL",
        "Country": "BRA",
        "Links": [
            {
(...)
            }
        ]
    },
(...)
}

Criação de QR Code para as jornadas 2 e 3

Para as jornadas 2 e 3, que correspondem à criação do QR Code de Pix Automático sem e com pagamento imediato, a API pode retornar o ReasonCode = 3 e ReasonMessage = "Operação inválida. Verifique os dados enviados" dentro do objeto RecurrentPayment:

Os principais motivos para esse erro são:

O campo OrderDescription está em formato inválido;
O nome do comprador (CustomerName) contém caracteres especiais ou excede o limite de caracteres;
O parâmetro do documento (Customer.Identity) está inválido, com máscara (pontos, traços) ou com o dígito verificador incorreto. Para sandbox, use um gerador de CPF mockado;
O parâmetro tipo de documento (Customer.IdentityType) está inválido. Os valores possíveis são "CPF" ou "CNPJ";
O parâmetro que identifica o tip de integração (Payment.Provider) está em formato inválido (o correto é "Cielo2");
A data de início da recorrência StartDate é anterior à data atual ou está em formato incorreto;
O parâmetro EndDate é anterior à data de início (StartDate) ou está em formato inválido;
O parâmetro Interval está em formato inválido;
O valor (Payment.Amount, RecurrentPayment.Amount ou RecurrentPayment.MinimumAmount) está em formato inválido. Envie o valor em centavos de real;
O valor do pagamento imediato (Payment.Amount) na jornada 3 não foi enviado;
O parâmetro tipo de recorrência RecurrenceType está em formato inválido;
O parâmetro RetryPolice está em formato inválido.

Envio de cobrança ou retentativa

Para as operação de cobrança por Pix Automático ou retentativa, os principais erros que a API pode retornar são o ReasonCode = 3 e ReasonMessage = "Operação inválida. Verifique os dados enviados" dentro do objeto RecurrentPayment:

O campo OrderDescription está em formato inválido;
O nome do comprador (CustomerName) contém caracteres especiais ou excede o limite de caracteres;
O parâmetro do documento (Customer.Identity) está inválido, com máscara (pontos, traços) ou com o dígito verificador incorreto. Para sandbox, use um gerador de CPF mockado;
O parâmetro tipo de documento (Customer.IdentityType) está inválido. Os valores possíveis são "CPF" ou "CNPJ";
O parâmetro que identifica o tip de integração (Payment.Provider) está em formato inválido (o correto é "Cielo2");
O valor (Payment.Amount) está em formato inválido. Envie o valor em centavos de real;
O parâmetro tipo de recorrência RecurrenceType está em formato inválido;
A data de cobrança ExpirationDate é anterior à data de início da recorrência ou está em formato inválido;
O identificador da recorrência (RecurrenceId) não foi encontrado;
O usuário pagador não tem saldo disponível;
Apenas para retentativa: o identificador do primeiro pagamento negado (PaymentId) não existe, não foi informado corretamente ou está em formato inválido;

Cancelar recorrência de Pix Automático

Para erros do cancelamento, consulte os códigos retornados pela API e os códigos de erro do Pix .

Um dos erros possíveis é informar um RecurrenceId não existente. Nesse caso, a API irá retornar o erro HTTP 400 acompanhado de Code e Message, conforme exemplo:

[
    {
        "Code": 313,
        "Message": "Recurrent Payment not found"
    }
]

Indisponibilidade do Pix

Se houver alguma indisponibilidade do serviço Pix no Banco Central do Brasil, seja por manutenção, falha ou por estar fora da janela de funcionamento, a API irá retornar o seguinte ReturnCode e ReturnMessage:

"Payment": {
    (...)
    "ReturnCode": "99",
    "ReturnMessage": "FALHA NA OPERACAO"
}