Estrutura geral dos códigos retornados pelo Gateway de Pagamento
O Gateway de Pagamento usa uma estrutura de múltiplos códigos de retorno para fornecer um resultado detalhado sobre cada requisição. É fundamental entender que o sucesso na comunicação HTTP (código 2xx) não garante o sucesso da transação (autorização, captura, etc.). É necessário verificar também os códigos no corpo (body) da resposta.
O fluxograma a seguir ilustra a estrutura geral de retornos da API, exibindo a diferença entre sucesso técnico (HTTP) e resultado da operação:
Se você está começando agora, use esta tabela como guia principal e consulte as seções específicas linkadas ao final da página para mais detalhes:
Resumo dos códigos do Gateway de Pagamento
A tabela a seguir apresenta um resumo geral sobre os códigos retornados pelo Gateway de Pagamento:
| Tipo de código | Onde retorna (parâmetro) | Quando retorna | Exemplos | Observação |
|---|---|---|---|---|
| Status HTTP | Cabeçalho da resposta | Retorna em toda resposta a uma requisição feita à API | 200 – OK 201 – Criada 401 – Unauthorized | 4xx/5xx indicam falha na requisição ou no servidor (a API recebeu a chamada, mas não conseguiu processá‑la); confira Code Message quando presentes.Os retornos 200 e 201 significam que o Gateway recebeu a requisição e deu uma resposta, mas é necessário verificar o ProviderReturnCode e ProviderReturnMessage para saber se é uma resposta positiva. |
| Erros da API | Code eMessage | Retorna quando há um erro HTTP | Informar um MerchantKey inválido irá retornar código HTTP 400 e o Code = 123 com Message igual à "MerchantKey is invalid". | Podem ser os mesmos valores retornados em ProviderReturnCode e ProviderReturnMessage ou ReasonCode e ReasonMessage |
| Status da transação | Payment.Status | Nas operações relacionadas à criação e/ou consulta de transações (depois de a transação ter sido criada, ou seja, deverá ter um 201 criado). - Criação de transação - Consulta de transação - Cancelamento de transação | Payment.Status = 2 indica que o pagamento foi confirmado. | -- |
| Código de retorno do provedor (adquirente) | ProviderReturnCode e ProviderReturnMessage | Em qualquer operação*, quando há um HTTP de sucesso. Representa o retorno do provedor/adquirente configurado no Gateway (ex.: Cielo, Pix, Conversor de Moedas). - Criação de transações - Cancelamento - Captura | Exemplo de sucesso: ProviderReturnCode = 00 e ProviderReturnMessage = Transacao autorizada Exemplo de erro: ProviderReturnCode = 51 e ProviderReturnMessage = Autorizacao negada | Quando o retorno HTTP é de sucesso (200 ou 201), ainda assim pode ter acontecido outro erro ou pendência, que deve ser verificado pelo ProviderReturnCode e ProviderReturnMessage. Atenção: os códigos específicos documentados aqui valem apenas quando o provedor/adquirente é a Cielo. Se o estabelecimento usa outra adquirente, consulte a documentação dessa adquirente para a lista de códigos correspondente. |
| Códigos de motivo do retorno | ReasonCode e ReasonMessage | -Captura; -Cancelamento; -Conversão de moedas; -Criação de pagamento com boleto. | Exemplo de sucesso: ReasonCode = 0 e ReasonMessage = Operation SuccessfulExemplo de erro: ReasonCode = 7 e ReasonMessage = Denied | Quando o retorno HTTP é de sucesso (200 ou 201), ainda assim pode ter acontecido outro erro ou pendência, que deve ser verificado pelo ReasonCode e ReasonMessage |
*A operação de consulta normalmente não retorna ProviderReturnCode ou ReasonCode e suas respectivas mensagens.
A API também pode retornar códigos relacionados a operações e funcionalidades específicas, como captura, cancelamento, transações de Pix, recorrentes ou com análise de fraude.
Exemplo da resposta de uma transação de cartão de crédito autorizada
A API retorna na resposta da transação de cartão de crédito todos os parâmetros enviados na requisição e também parâmetros exclusivos da resposta, como:
- Parâmetros relacionados à conciliação da transação, como o
Tid,SentOrderIdeProofOfSale; - Status da transação, no parâmetro
Payment.Status; Payment.ProviderReturnCodeePayment.ProviderReturnMessage, que representam os retornos do fluxo de autorização junto ao provedor/adquirente e indicam se a transação foi bem-sucedida ou não;Links, que indicam quais operações ainda podem ser executadas para essa transação, como captura, consulta e cancelamento.
{
"MerchantOrderId": "2017051001",
"Customer": {
"Name": "Aline de Souza",
"Identity": "12345678909",
"IdentityType": "CPF",
"Email": "[email protected]",
"Birthdate": "1990-01-01",
"IpAddress": "127.0.0.1"
},
"Payment": {
"ServiceTaxAmount": 0,
"Installments": 1,
"Interest": "ByMerchant",
"Capture": true,
"Authenticate": true,
"Recurrent": false,
"CreditCard": {
"CardNumber": "409168******7641",
"Holder": "Aline de Souza",
"ExpirationDate": "12/2035",
"SaveCard": false,
"Alias": "",
"Brand": "Visa",
"PaymentAccountReference": "DJL4R99SL2GQANTW0Q4FKCVWSI24W"
},
"ProofOfSale": "473618",
"AcquirerTransactionId": "0722040850557",
"AuthorizationCode": "997634",
"SoftDescriptor": "LojaTeste",
"SentOrderId": "2025072216085029F401",
"Eci": "5",
"ExternalAuthentication": {
"Cavv": "AAABB2gHA1B5EFNjWQcDAAAAAAB=",
"Xid": "Uk5ZanBHcWw2RjRCbEN5dGtiMTB=",
"Eci": "5",
"Version": "2.2.0",
"ReferenceId": "a24a5d87-b1a1-4aef-a37b-2f30b91274e6"
},
"Credentials": {
"Code": "9999999",
"Key": "D8888888",
"Password": "LOJA9999999",
"Signature": "001",
"Username": "#Braspag2018@NOMEDALOJA#"
},
"DoSplit": false,
"Tip": false,
"PaymentId": "d08a3e92-56d8-497c-a64a-a79819066fce",
"Type": "CreditCard",
"Amount": 10000,
"ReceivedDate": "2025-07-22 16:08:50",
"CapturedAmount": 10000,
"CapturedDate": "2025-07-22 16:08:50",
"Currency": "BRL",
"Country": "BRA",
"Provider": "Simulado",
"ExtraDataCollection": [
{
"Name": "NomeDoCampo",
"Value": "ValorDoCampo"
}
],
"ReasonCode": 0,
"ReasonMessage": "Successful",
"Status": 2,
"ProviderReturnCode": "6",
"ProviderReturnMessage": "Operation Successful",
"Links": [
{
"Method": "GET",
"Rel": "self",
"Href": "https://apiquerysandbox.braspag.com.br/v2/sales/d08a3e92-56d8-497c-a64a-a79819066fce"
},
{
"Method": "PUT",
"Rel": "void",
"Href": "https://apisandbox.braspag.com.br/v2/sales/d08a3e92-56d8-497c-a64a-a79819066fce/void"
}
]
}
}Próximas seções
Entenda os códigos HTTP retornados pela API e o que eles realmente indicam sobre o sucesso ou falha da comunicação com a Cielo.
Conheça os status transacionais que representam o ciclo de vida de um pagamento, da criação até a confirmação do pagamento, cancelamento ou estorno.
Consulte os códigos de retorno de negócio usados para identificar sucesso, negação ou pendência em operações de pagamento nos campos ProviderReturnCode e ProviderReturnMessage. Os códigos listados são específicos da adquirente Cielo; para outras adquirentes, consulte a documentação correspondente.
Saiba como identificar e tratar erros técnicos da API retornados em respostas HTTP de erro, nos campos Code e Message.
Consulte os códigos de retorno das bandeiras padronizados pela Abecs, e saiba como interpretá‑los nas respostas da API.
Entenda quando é permitido reenviar uma transação de cartão negada e como funcionam os programas de retentativas definidos pelas bandeiras.