Códigos de retorno de negócio da API (Provider e Reason)

Para saber se uma venda foi autorizada e/ou paga, confira o Payment.Status, e o ProviderReturnCode e ProviderReturnMessage.

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

Veja nesta seção:

Códigos de retorno do provedor: ProviderReturnCode e ProviderReturnMessage;
Códigos de motivo: ReasonCode e ReasonMessage.

Códigos de retorno do provedor: `ProviderReturnCode` e `ProviderReturnMessage`

O ProviderReturnCode e ProviderReturnMessage fornecem o resultado da operação do ponto de vista do negócio, retornado pelo provedor/adquirente, e são apresentados no corpo da resposta para as seguintes operações:

Criação de transações;
Captura;
Cancelamento;
Devolução de Pix;
Conversão de moedas;
Criação de pagamento com boleto.

⚠️
Os valores de ProviderReturnCode e ProviderReturnMessage apresentados a seguir são os retornados quando o provedor/adquirente da transação é a Cielo.
Caso o estabelecimento utilize outra adquirente integrada ao Gateway, os códigos e mensagens serão os definidos por ela — consulte a documentação da adquirente utilizada para a lista completa.

Os principais ProviderReturnCode de sucesso (para adquirente Cielo) são:

00: transação autorizada;
4: transação autorizada (apta a ser capturada);
6: transação capturada.

ℹ️
Valide o sucesso da venda pela combinação do ProviderReturnCode com o Payment.Status.

Alguns exemplos de ProviderReturnCode de transações negadas (adquirente Cielo) são:

51: o portador do cartão não tem saldo suficiente para a compra;
54: cartão vencido;
78: cartão novo sem desbloqueio.

Como interpretar o `ProviderReturnCode`

Quando uma transação é negada, o ProviderReturnCode é a base para determinar o fluxo de decisão. É importante que o estabelecimento analise se o retorno é reversível ou irreversível e decida por submeter ou não a transação para uma nova tentativa de autorização.

Analise o tipo de retorno para:

Determinar se a transação pode ser enviada novamente para o mesmo cartão;
Criar mensagens na página de pagamento ou enviar mensagem ao comprador orientando a usar outro cartão ou outro meio de pagamento.

ℹ️
Atenção para autorizações negadas de cartão de crédito ou débito:
Quando a transação é reversível:

Envie a transação novamente para autorização (retentativa);

Respeite o limite de retentativas da bandeira para aquele código e evite penalidades.

Quando a transação é irreversível:

Oriente o comprador a tentar outro cartão ou meio de pagamento.

Cenários comuns de `ProviderReturnCode` por meio de pagamento

A tabela a seguir exemplifica os principais cenários por meio de pagamento, com o seu Status e ProviderReturnCode correspondentes (valores para adquirente Cielo):

Cenário	`Payment.Status`	Exemplo* de `ProviderReturnCode`	Exemplo* `ProviderReturnMessage`
Crédito - autorizado	1	00 ou 4	Transação autorizada
Crédito - capturado (pago)	2	6 ou 00	Transação capturada com sucesso
Crédito - negado	3	Diversos (ver tabela Abecs)	Autorização negada
Crédito - abortado	13	—	Não retorna `ProviderReturnCode`/`ProviderReturnMessage`
Crédito - não finalizado	0	001 ou BP171	XML inválido or Rejected by fraud risk
Crédito - recorrência agendada	20	4	Operation Successful
Débito - pago	2	00 ou 6	Transação capturada com sucesso
Débito - não autorizado	3	Diversos (ver tabela Abecs)	Autorização negada
Pix - gerado com sucesso	12	0	Pix gerado com sucesso
Pix - pago	2	0	Sucesso
Pix - não finalizado	0	422	Error on merchantResponse integration
Pix - devolvido	11	0	Devolução solicitada com sucesso
Boleto - criado	1	0	REGISTRO EFETUADO COM SUCESSO
Boleto pago	2	--	--
Cancelamento aprovado	10	9	Transação desfeita ou Transação cancelada com sucesso
Estorno aprovado	11	9	Transação desfeita

*Os valores de ProviderReturnCode e ProviderReturnMessage apresentados na tabela são exemplos de retornos comuns para cada cenário quando o provedor/adquirente é a Cielo. Se o estabelecimento utiliza outra adquirente, consulte a documentação dessa adquirente.

Tabela de `ProviderReturnCode` e `ProviderReturnMessage` (adquirente Cielo)

ProviderReturnCode e ProviderReturnMessage apresentam os mesmos valores de Code e Message, mas retornam em situações diferentes:

Os valores ProviderReturnCode e ProviderReturnMessage são retornados em operações HTTP de sucesso (200 ou 201);
Os valores Code e Message são retornados em operações HTTP de erro (ex.: 400).

⚠️
A tabela abaixo lista os códigos e mensagens específicos da adquirente Cielo.
Se o estabelecimento utiliza outra adquirente integrada ao Gateway, os códigos e mensagens de ProviderReturnCode/ProviderReturnMessage serão diferentes — consulte a documentação da adquirente utilizada.

Confira a tabela completa:

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.
220	Service tax can not be sent with 1 installment	`ServiceTaxAmount` precisa de parcelamento superior a 1.
228	Customer Anddress Country is required	Campo enviado está vazio ou inválido
233	Service tax not supported for the given brand	`ServiceTaxAmount` não suportado pela bandeira do cartão.
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.
841	Status nao permite capturar	Limite de tentativas atingido. Gere uma nova transação para capturar.
902	Erro no tratamento da resposta do pagamento	Erro pontual no processamento. Tente novamente.

Códigos de motivo `ReasonCode` e `ReasonMessage`

O ReasonCode e ReasonMessage podem indicar sucesso ou erro, e estão 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.

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.

Tabela de Reason Code e Reason Message

Reason Code	Reason Message
00	Successful
01	AffiliationNotFound
02	IssuficientFunds
03	CouldNotGetCreditCard
04	ConnectionWithAcquirerFailed
05	InvalidTransactionType
06	InvalidPaymentPlan
07	Denied
08	Scheduled
09	Waiting
10	Authenticated
11	NotAuthenticated
12	ProblemsWithCreditCard
13	CardCanceled
14	BlockedCreditCard
15	CardExpired
16	AbortedByFraud
17	CouldNotAntifraud
18	TryAgain
19	InvalidAmount
20	ProblemsWithIssuer
21	InvalidCardNumber
22	TimeOut
23	CartaoProtegidoIsNotEnabled
24	PaymentMethodIsNotEnabled
25	CouldNotFindPaymentToken
26	MerchantIdJustClickNotFound
27	BrandNotSupported
28	CardOptionsNotSupported
29	WalletKeyIsInvalid
30	MerchantWalletConfigurationNotFound
31	BoletoRequiredDataNotSupported
32	ConnectionWithAntifraudFailed
33	AbortedByCardVerification
34	ProblemsWithAcquirer
35	ValidationError
36	AcquirerTransactionNotFound
37	SplitTransactionalError
38	MerchantSplitConfigurationNotFound
39	SplitSoftDescriptorIsRequired
40	SplitFraudAnalysisIsRequired
41	SplitAntifraudMerchantConfigurationNotFound
42	ProviderNotFound
43	PaymentSettingsNotFound
44	SubAcquirerMerchantConfigurationNotFound
45	AbortedBySubAcquirer
98	InvalidRequest
99	InternalError
100	CieloPayCardHolderIsNotActive
101	CieloPayStrongValidationIsInvalid
102	CieloPayExpireDateDoesNotMatch
103	CieloPayCardHolderApiError
104	SplitPaymentFacilitatorDataNotFound

Códigos de retorno do provedor: ProviderReturnCode e ProviderReturnMessage

Como interpretar o ProviderReturnCode

Atenção para autorizações negadas de cartão de crédito ou débito:

Cenários comuns de ProviderReturnCode por meio de pagamento

Tabela de ProviderReturnCode e ProviderReturnMessage (adquirente Cielo)

Códigos de motivo ReasonCode e ReasonMessage

Tabela de Reason Code e Reason Message

Códigos de retorno do provedor: `ProviderReturnCode` e `ProviderReturnMessage`

Como interpretar o `ProviderReturnCode`

Cenários comuns de `ProviderReturnCode` por meio de pagamento

Tabela de `ProviderReturnCode` e `ProviderReturnMessage` (adquirente Cielo)

Códigos de motivo `ReasonCode` e `ReasonMessage`