Códigos de retorno transacionais

Na integração com Split de Pagamento (via API E-commerce Cielo ou Gateway de Pagamento), os códigos de retorno transacionais são divididos em dois níveis:

• Nível HTTP (validação da requisição)
• Nível de negócio (processamento da transação)

Entender essa separação é essencial para interpretar corretamente os retornos e tratar cada cenário.

Code e Message

Os campos Code e Message são retornados quando ocorre erro na requisição HTTP, normalmente com status 4xx (ex.: 400, 401, 403).

Esses erros indicam que a requisição não foi processada, devido a problemas como:

• Campos obrigatórios ausentes;

• Formato inválido;

• Dados inconsistentes.

• Code: código do erro

• Message: descrição do erro

[
  {
    "Code": "123",
    "Message": "Invalid request format"
  }
]

ℹ️

Atenção

Utilize Code e Message para corrigir a requisição antes de reenviá-la. Esses erros ocorrem antes do processamento da operação.

ReturnCode e ReturnMessage (API E-commerce Cielo)

Em integrações Split via API E-commerce Cielo, os campos ReturnCode e ReturnMessage indicam o resultado da operação no nível de negócio.

Eles são retornados quando a requisição foi aceita (HTTP 200 ou 201), mas o resultado precisa ser interpretado.

• ReturnCode: código do resultado
• ReturnMessage: descrição do resultado

[
  {
    "ReturnCode": "00",
    "ReturnMessage": "Operation Successful"
  }
]

Quando são retornados

• Criação de transações
• Captura
• Cancelamento

Como interpretar

• Sucesso:

  • 00 → operação aprovada

• Sucesso com observação / fluxo intermediário:

  • 4, 6 → variam conforme operação (ex.: captura parcial, transação em análise)

• Falha ou recusa:

  • Depende do código retornado (ex.: cartão recusado, saldo insuficiente, etc.)

ℹ️

Importante

Sempre valide o resultado final utilizando o Payment.Status em conjunto com o ReturnCode.

ProviderReturnCode e ProviderReturnMessage (Gateway de Pagamento)

Em integrações Split via Gateway de Pagamento, a API pode retornar também:

• ProviderReturnCode
• ProviderReturnMessage

Esses campos representam o retorno do provedor do meio de pagamento, como:

• Adquirente
• Banco emissor
• Outros participantes da transação

{
  "ProviderReturnCode": "51",
  "ProviderReturnMessage": "Insufficient funds"
}

Características

• Podem ser equivalentes aos valores de ReturnCode e ReturnMessage;
• Representam uma camada externa ao Gateway;
• São úteis principalmente para depuração.

ℹ️

Importante

Para adquirentes diferentes da Cielo, consulte a documentação da própria adquirente para interpretar esses códigos corretamente.

Resumo

ℹ️

Os códigos retornados são dinâmicos e dependem do fluxo percorrido por cada solicitação. A interpretação deve considerar o contexto da operação e o meio de pagamento utilizado.

A seguir veja a tabela dos códigos de retorno transacionais: