Códigos de Erros da API

A API do Gateway de Pagamento pode ter dois tipos principais de códigos retornados nas operações, os códigos de motivo da resposta (ReasonCode) e os códigos de retorno do provedor do meio de pagamento (ProviderReturnCode).

Códigos de motivo da resposta

São apresentados nos campos ReasonCode e ReasonMessage, e indicam se a operação desejada foi bem sucedida ou não, informando o motivo.

O ReasonCode e ReasonMessage estão mais associados aos fluxos operacionais internos da Cielo e/ou entre a Cielo e a bandeira/emissor que ocorrem depois que a API E-commerce recebe a requisição (status HTTP 200 ou 201).

O ReasonCode indica o código, enquanto o ReasonMessage traz a descrição correspondente ao código. As principais operações que retornam ReasonCode e ReasonMessage são:

Captura;
Cancelamento;
Conversão de moedas;
Criação de pagamento com boleto.

Confira a tabela de ReasonCode e ReasonMessage.

ProviderReturnCode e ProviderReturnCode

A API do Gateway de Pagamento pode retornar o campo ProviderReturnCode acompanhado de sua respectiva mensagem correspondente em ProviderReturnCode. Esse retorno representa a resposta do provedor do meio de pagamento e é comum, por exemplo, em transações de cartão de crédito com conversão de moedas. Apesar da nomenclatura, os valores costumam ser equivalentes aos códigos do ReturnCode e ReturnMessage.

Confira a tabela completa de ProviderReturnCode e ProviderReturnMessage.

ℹ️
Importante
Os códigos retornados são dinâmicos e dependem do fluxo percorrido por cada solicitação.

Códigos de retorno padrão

Para as operações que envolvem a criação de uma transação de qualquer meio de pagamento, o código de resposta mais comum é o ReturnCode, que vem acompanhado da sua mensagem explicativa em ReturnMessage.

[
  {
    "ReturnCode": 126,
    "ReturnMessage": "Credit Card Expiration Date is invalid"
  }
]

Além disso, os retornos da Abecs (Associação Brasileira das Empresas de Cartões de Crédito e Serviços) também são apresentados em ReturnCode e ReturnMessage, e são essenciais para determinar se uma transação é elegível à retentativa.

o ReturnCode e ReturnMessage podem retornar também nas operações de captura, cancelamento, conversão de moedas e boleto.

Confira a tabela completa de ReturnCode e ReturnMessage.

Confira a tabela da Abecs.

Tabela de Erros da API

Provider Return Code	Provider Return Message	Descrição
0	Internal error	Dado enviado excede o tamanho do campo.
100	RequestId is required	Campo enviado está vazio ou inválido.
101	MerchantId is required	Campo enviado está vazio ou inválido.
102	Payment Type is required	Campo enviado está vazio ou inválido.
103	Payment Type can only contain letters	Caracteres especiais não permitidos.
104	Customer Identity is required	Campo enviado está vazio ou inválido.
105	Customer Name is required	Campo enviado está vazio ou inválido.
106	Transaction ID is required	Campo enviado está vazio ou inválido.
107	OrderId is invalid or does not exist	Campo enviado excede o tamanho ou contém caracteres especiais.
108	Amount must be greater or equal to zero	Valor da transação deve ser maior que "0".
109	Payment Currency is required	Campo enviado está vazio ou inválido.
110	Invalid Payment Currency	Campo enviado está vazio ou inválido.
111	Payment Country is required	Campo enviado está vazio ou inválido.
112	Invalid Payment Country	Campo enviado está vazio ou inválido.
113	Invalid Payment Code	Campo enviado está vazio ou inválido.
114	The provided MerchantId is not in correct format	O MerchantId enviado não é um GUID.
115	The provided MerchantId was not found	O MerchantID não existe ou pertence a outro ambiente. (Ex.: Sandbox).
116	The provided MerchantId is blocked	Loja bloqueada, entre em contato com o suporte e-commerce.
117	Credit Card Holder is required	Campo enviado está vazio ou inválido.
118	Credit Card Number is required	Campo enviado está vazio ou inválido.
119	At least one Payment is required	Nó `Payment` não enviado.
120	Request IP not allowed. Check your IP White List	IP bloqueado por questões de segurança.
121	Customer is required	Nó `Customer` não enviado.
122	MerchantOrderId is required	Campo enviado está vazio ou inválido.
123	Installments must be greater or equal to one	Número de parcelas deve ser superior a 1.
124	Credit Card is Required	Campo enviado está vazio ou inválido.
125	Credit Card Expiration Date is required	Campo enviado está vazio ou inválido.
126	Credit Card Expiration Date is invalid	Campo enviado está vazio ou inválido.
127	You must provide CreditCard Number	Número do cartão de crédito é obrigatório.
128	Card Number length exceeded	Número do cartão superior a 16 dígitos.
129	Affiliation not found	Meio de pagamento não vinculado à loja ou Provider inválido.
130	Could not get Credit Card
131	MerchantKey is required	Campo enviado está vazio ou inválido.
132	MerchantKey is invalid	O Merchantkey enviado não é válido.
133	Provider is not supported for this Payment Type	Provider enviado não existe.
134	FingerPrint length exceeded	Dado enviado excede o tamanho do campo.
135	MerchantDefinedFieldValue length exceeded	Dado enviado excede o tamanho do campo.
136	ItemDataName length exceeded	Dado enviado excede o tamanho do campo.
137	ItemDataSKU length exceeded	Dado enviado excede o tamanho do campo.
138	PassengerDataName length exceeded	Dado enviado excede o tamanho do campo.
139	PassengerDataStatus length exceeded	Dado enviado excede o tamanho do campo.
140	PassengerDataEmail length exceeded	Dado enviado excede o tamanho do campo.
141	PassengerDataPhone length exceeded	Dado enviado excede o tamanho do campo.
142	TravelDataRoute length exceeded	Dado enviado excede o tamanho do campo.
143	TravelDataJourneyType length exceeded	Dado enviado excede o tamanho do campo.
144	TravelLegDataDestination length exceeded	Dado enviado excede o tamanho do campo.
145	TravelLegDataOrigin length exceeded	Dado enviado excede o tamanho do campo.
146	SecurityCode length exceeded	Dado enviado excede o tamanho do campo.
147	Address Street length exceeded	Dado enviado excede o tamanho do campo.
148	Address Number length exceeded	Dado enviado excede o tamanho do campo.
149	Address Complement length exceeded	Dado enviado excede o tamanho do campo.
150	Address ZipCode length exceeded	Dado enviado excede o tamanho do campo.
151	Address City length exceeded	Dado enviado excede o tamanho do campo.
152	Address State length exceeded	Dado enviado excede o tamanho do campo.
153	Address Country length exceeded	Dado enviado excede o tamanho do campo.
154	Address District length exceeded	Dado enviado excede o tamanho do campo.
155	Customer Name length exceeded	Dado enviado excede o tamanho do campo.
156	Customer Identity length exceeded	Dado enviado excede o tamanho do campo.
157	Customer IdentityType length exceeded	Dado enviado excede o tamanho do campo.
158	Customer Email length exceeded	Dado enviado excede o tamanho do campo.
159	ExtraData Name length exceeded	Dado enviado excede o tamanho do campo.
160	ExtraData Value length exceeded	Dado enviado excede o tamanho do campo.
161	Boleto Instructions length exceeded	Dado enviado excede o tamanho do campo.
162	Boleto Demostrative length exceeded	Dado enviado excede o tamanho do campo.
163	Return Url is required	URL de retorno não é valida - Não são aceitas paginação ou extensões (EX.: PHP) na URL de retorno.
166	AuthorizeNow is required
167	Antifraud not configured	Antifraude não vinculado ao cadastro do lojista.
168	Recurrent Payment not found	Recorrência não encontrada.
169	Recurrent Payment is not active	Recorrência não está ativa. Execução paralizada.
170	Cartão Protegido not configured	Cartão protegido não vinculado ao cadastro do lojista.
171	Affiliation data not sent	Falha no processamento do pedido, entre em contato com o suporte e-commerce.
172	Credential Code is required	Falha na validação das credenciadas enviadas.
173	Payment method is not enabled	Meio de pagamento não vinculado ao cadastro do lojista.
174	Card Number is required	Campo enviado está vazio ou inválido.
175	EAN is required	Campo enviado está vazio ou inválido.
176	Payment Currency is not supported	Campo enviado está vazio ou inválido.
177	Card Number is invalid	Campo enviado está vazio ou inválido.
178	EAN is invalid	Campo enviado está vazio ou inválido.
179	The max number of installments allowed for recurring payment is 1	Campo enviado está vazio ou inválido.
180	The provided Card PaymentToken was not found	Token do cartão protegido não encontrado.
181	The MerchantIdJustClick is not configured	Token do cartão protegido bloqueado.
182	Brand is required	Bandeira do cartão não enviado.
183	Invalid customer bithdate	Data de nascimento inválida ou futura.
184	Request could not be empty	Falha no formato da requisição. Verifique o código enviado.
185	Brand is not supported by selected provider	Bandeira não suportada pela API Gateway de Pagamento.
186	The selected provider does not support the options provided (Capture, Authenticate, Recurrent or Installments)	Meio de pagamento não suporta o comando enviado.
187	ExtraData Collection contains one or more duplicated names
188	Avs with CPF invalid
189	Avs with length of street exceeded	Dado enviado excede o tamanho do campo.
190	Avs with length of number exceeded	Dado enviado excede o tamanho do campo.
190	Avs with length of complement exceeded	Dado enviado excede o tamanho do campo.
191	Avs with length of district exceeded	Dado enviado excede o tamanho do campo.
192	Avs with zip code invalid	CEP enviado é inválido.
193	Split Amount must be greater than zero	Valor para realização do SPLIT deve ser superior a 0.
194	Split Establishment is Required	SPLIT não habilitado para o cadastro da loja.
195	PlatformId is required	Validados de plataformas não enviado.
196	DeliveryAddress is required	Campo obrigatório não enviado.
197	Street is required	Campo obrigatório não enviado.
198	Number is required	Campo obrigatório não enviado.
199	ZipCode is required	Campo obrigatório não enviado.
200	City is required	Campo obrigatório não enviado.
201	State is required	Campo obrigatório não enviado.
202	District is required	Campo obrigatório não enviado.
203	Cart item name is required	Campo obrigatório não enviado.
204	Cart item quantity is required	Campo obrigatório não enviado.
205	Cart item type is required	Campo obrigatório não enviado.
206	Cart item name length exceeded	Dado enviado excede o tamanho do campo.
207	Cart item description length exceeded	Dado enviado excede o tamanho do campo.
208	Cart item sku length exceeded	Dado enviado excede o tamanho do campo.
209	Shipping addressee sku length exceeded	Dado enviado excede o tamanho do campo.
210	Shipping data cannot be null	Campo obrigatório não enviado.
213	Credit Card Number is invalid	Cartão de crédito enviado é invalido.
214	Credit Card Holder Must Have Only Letters	Portador do cartão não deve conter caracteres especiais.
215	Agency is required in Boleto Credential	Campo obrigatório não enviado.
216	Customer IP address is invalid	IP bloqueado por questões de segurança.
228	Customer Anddress Country is required	Campo enviado está vazio ou inválido
298	Split payment facilitator data not found.	O `MerchantId` informado não existe na base de dados do ambiente selecionado (Produção ou Sandbox)
300	MerchantId was not found
301	Request IP is not allowed
302	Sent MerchantOrderId is duplicated	Houve duplicidade do pedido.
303	Sent OrderId does not exist
304	Customer Identity is required
306	Merchant is blocked
307	Transaction not found	Transação não encontrada ou não existente no ambiente.
308	Transaction not available to capture	Transação não pode ser capturada - Entre em contato com o suporte e-commerce. Verificar se o valor informado é inferior ao valor total da transação ou se está disponível para captura
309	Transaction not available to void	Transação não pode ser cancelada - Entre em contato com o suporte e-commerce.
310	Payment method does not support this operation	Comando enviado não suportado pelo meio de pagamento.
311	Refund is not enabled for this merchant	Cancelamento após 24 horas não liberado para o lojista.
312	Transaction not available to refund	Transação não permite cancelamento após 24 horas.
313	Recurrent Payment not found	Transação recorrente não encontrada ou não disponivel no ambiente.
314	Invalid Integration
315	Cannot change NextRecurrency with pending payment
316	Cannot set NextRecurrency to past date	Não é permitido alterar a data da recorrência para uma data passada.
317	Invalid Recurrency Day
318	No transaction found
319	Smart Recurrency is not enabled	Recorrência não vinculada ao cadastro do lojista.
320	Cannot Update Affiliation because this recurrency has no affiliation saved
321	Cannot Set EndDate to before next recurrency
322	Zero Dollar Auth is not enabled	Zero Dollar não vinculado ao cadastro do lojista.
323	Bin Query is not enabled	Consulta de Bins não vinculada ao cadastro do lojista.

Outros códigos de erro

Os códigos a seguir são retornados em caso de falha na comunicação entre API e adquirente (timeout) ou por alguma falha na integração.

Quando ocorre falha na comunicação com a adquirente é possível que a transação tenha sido aprovada. Nesses casos, existe um processo interno chamado sonda, que efetua a consulta da transação na adquirente e atualiza o status em caso de divergência.

Para obter o resultado da sonda, a loja deve possuir cadastrada uma URL de mudança de status ou realizar a consulta via webservice ou API Rest.

Veja abaixo alguns códigos:

Código	Significado
BP171	Rejeitado por risco de fraude (Velocity)
BP335	Cancelado por erro transacional no Split de Pagamento
BP900	Falha na operação
BP901	Falha na operação
BP902	Espere pela resposta da operação anterior
BP903	Falha no cancelamento