API business return codes (Return, Provider, and Reason)

To determine whether a sale has been authorized and/or paid, check Payment.Status, ReturnCode, and ReturnMessage.

The returned codes are dynamic and depend on the flow followed by each request.

See this section:

Sale return codes: ReturnCode and ReturnMessage;
Provider return codes: ProviderReturnCode and ProviderReturnMessage;
Reason codes: ReasonCode and ReasonMessage.

Sale return codes: `ReturnCode` and `ReturnMessage`

ReturnCode and ReturnMessage provide the result of the operation from a business perspective and are returned in the response body for the following operations:

Transaction creation;
Capture;
Void.

The main success ReturnCode values are:

00: transaction authorized;
4: transaction authorized (eligible for capture);
6: transaction captured.

ℹ️
Validate the success of the sale by checking the combination of ReturnCode and Payment.Status.

Some examples of ReturnCode values for denied transactions are:

51: the cardholder does not have sufficient funds for the purchase;
54: expired card;
78: new card not activated.

How to interpret `ReturnCode`

When a transaction is denied, ReturnCode is the primary indicator used to determine the decision flow. It is important for the merchant to assess whether the response is reversible or irreversible and decide whether the transaction should be resubmitted for a new authorization attempt.

Analyze the return type to:

Determine whether the transaction can be submitted again using the same card;
Display messages on the payment page or send a message to the shopper advising them to use a different card or another payment method.

ℹ️
Warning for denied credit or debit card authorizations:
When the transaction is reversible:

Resubmit the transaction for authorization (retry);

Follow the card brand's retry limits for that specific code to avoid penalties.

When the transaction is irreversible:

Advise the shopper to use a different card or another payment method.

Common `ReturnCode` scenarios by payment method

The following table provides examples of the main scenarios for each payment method, along with their corresponding Status and ReturnCode:

Scenario	`Payment.Status`	`ReturnCode` example*	`ReturnMessage` example*
Credit - authorized	1	00 or 4	Transação autorizada (Transaction authorized)
Credit - captured (paid)	2	6 or 00	Transação capturada com sucesso (Transaction captured successfully)
Credit - denied	3	Various (see Abecs table)	Autorização negada (Authorization denied)
Credit - aborted	13	—	Does not return `ReturnCode`/`Message`
Credit - not finalized	0	001 or BP171	XML inválido (Invalid XML) ou Rejected by fraud risk
Credit - recurrence scheduled	20	4	Operation Successful
Debit - paid	2	00 or 6	Transação capturada com sucesso (Transaction captured successfully)
Debit - not authorized	3	Various (see Abecs table)	Autorização negada (Authorization denied)
Pix - successfully generated	12	0	Pix gerado com sucesso (Pix generated successfully)
Pix - paid	2	0	Sucesso (Success)
Pix - not finalized	0	422	Error on merchantResponse integration
Pix - refunded	11	0	Devolução solicitada com sucesso (Refund requested successfully)
Boleto - created	1	0	REGISTRO EFETUADO COM SUCESSO (REGISTRATION COMPLETED SUCCESSFULLY)
Boleto paid	2	--	--
Void approved	10	9	Transação desfeita (Transaction voided) or Transação cancelada com sucesso (Transaction successfully voided)
Refund approved	11	9	Transação desfeita (Transaction voided)

*The ReturnCode and ReturnMessage values shown in the table are examples of common responses for each scenario. See the ReturnCode and ReturnMessage Table for the complete list of possible values.

`ReturnCode` and `ReturnMessage` Table

ReturnCode and ReturnMessage are equivalent to Code and Message, but they are returned in different situations:

ReturnCode and ReturnMessage values are returned in successful HTTP operations (200 or 201);
Code and Message values are returned in HTTP error operations (for example, 400).

Check the complete table:

`ReturnCode` or `Code`	`ReturnMessage` or `Message`	Description
00	Internal error	Submitted data exceeds the field length
100	RequestId is required	The submitted field is empty or invalid.
101	MerchantId is required	The submitted field is empty or invalid.
102	Payment Type is required	The submitted field is empty or invalid.
103	Payment Type can only contain letters	Special characters are not allowed.
104	Customer Identity is required	The submitted field is empty or invalid.
105	Customer Name is required	The submitted field is empty or invalid.
106	Transaction ID is required	The submitted field is empty or invalid.
107	OrderId is invalid or does not exists	The submitted field exceeds the allowed length or contains special characters.
108	Amount must be greater or equal to zero	The transaction amount must be greater than "0".
109	Payment Currency is required	The submitted field is empty or invalid.
110	Invalid Payment Currency	The submitted field is empty or invalid.
111	Payment Country is required	The submitted field is empty or invalid.
112	Invalid Payment Country	The submitted field is empty or invalid.
113	Invalid Payment Code	The submitted field is empty or invalid.
114	The provided MerchantId is not in correct format	The provided MerchantId is not a GUID.
115	The provided MerchantId was not found	The MerchantID does not exist or belongs to a different environment (for example, Sandbox).
116	The provided MerchantId is blocked	Merchant is blocked. Check your merchant status on the Cielo website.
117	Credit Card Holder is required	The submitted field is empty or invalid.
118	Credit Card Number is required	The submitted field is empty or invalid.
119	At least one Payment is required	"Payment" node was not provided.
120	Request IP not allowed. Check your IP White List	IP address blocked for security reasons.
121	Customer is required	"Customer" node was not provided.
122	MerchantOrderId is required	The submitted field is empty or invalid.
123	Installments must be greater or equal to one	The number of installments must be greater than 1.
124	Credit Card is Required	The submitted field is empty or invalid.
125	Credit Card Expiration Date is required	The submitted field is empty or invalid.
126	Credit Card Expiration Date is invalid	The submitted field is empty or invalid.
127	You must provide CreditCard Number	Credit card number is required.
128	Card Number length exceeded	Credit card number exceeds 16 digits.
129	Affiliation not found	Payment method is not linked to the merchant, or the provider is invalid.
130	Could not get Credit Card	It may indicate that no card could be found for the provided card token, or that the query was interrupted.
131	MerchantKey is required	The submitted field is empty or invalid.
132	MerchantKey is invalid	The provided MerchantKey is not valid.
133	Provider is not supported for this Payment Type	The provided provider does not exist.
134	FingerPrint length exceeded	The provided data exceeds the field size limit.
135	MerchantDefinedFieldValue length exceeded	The provided data exceeds the field size limit.
136	ItemDataName length exceeded	The provided data exceeds the field size limit.
137	ItemDataSKU length exceeded	The provided data exceeds the field size limit.
138	PassengerDataName length exceeded	The provided data exceeds the field size limit.
139	PassengerDataStatus length exceeded	The provided data exceeds the field size limit.
140	PassengerDataEmail length exceeded	The provided data exceeds the field size limit.
141	PassengerDataPhone length exceeded	The provided data exceeds the field size limit.
142	TravelDataRoute length exceeded	The provided data exceeds the field size limit.
143	TravelDataJourneyType length exceeded	The provided data exceeds the field size limit.
144	TravelLegDataDestination length exceeded	The provided data exceeds the field size limit.
145	TravelLegDataOrigin length exceeded	The provided data exceeds the field size limit.
146	SecurityCode length exceeded	The provided data exceeds the field size limit.
147	Address Street length exceeded	The provided data exceeds the field size limit.
148	Address Number length exceeded	The provided data exceeds the field size limit.
149	Address Complement length exceeded	The provided data exceeds the field size limit.
150	Address ZipCode length exceeded	The provided data exceeds the field size limit.
151	Address City length exceeded	The provided data exceeds the field size limit.
152	Address State length exceeded	The provided data exceeds the field size limit.
153	Address Country length exceeded	The provided data exceeds the field size limit.
154	Address District length exceeded	The provided data exceeds the field size limit.
155	Customer Name length exceeded	The provided data exceeds the field size limit.
156	Customer Identity length exceeded	The provided data exceeds the field size limit.
157	Customer IdentityType length exceeded	The provided data exceeds the field size limit.
158	Customer Email length exceeded	The provided data exceeds the field size limit.
159	ExtraData Name length exceeded	The provided data exceeds the field size limit.
160	ExtraData Value length exceeded	The provided data exceeds the field size limit.
161	Boleto Instructions length exceeded	The provided data exceeds the field size limit.
162	Boleto Demostrative length exceeded	The provided data exceeds the field size limit.
163	Return Url is required	The return URL is not valid. Pagination or file extensions (for example, .PHP) are not allowed in the return URL.
166	AuthorizeNow is required	Required field not sent.
167	Antifraud not configured	Antifraude is not linked to the merchant registration.
168	Recurrent Payment not found	Recurrence not found.
169	Recurrent Payment is not active	Recurrence is not active. Execution has been halted.
170	Cartão Protegido not configured	The token is not linked to the merchant registration.
171	Affiliation data not sent	Order processing failed due to an affiliation error. Verify your credentials.
172	Credential Code is required	Credential validation failed.
173	Payment method is not enabled	The payment method is not linked to the merchant registration.
174	Card Number is required	The provided field is empty or invalid.
175	EAN is required	The provided field is empty or invalid.
176	Payment Currency is not supported	The provided field is empty or invalid.
177	Card Number is invalid	The provided field is empty or invalid.
178	EAN is invalid	The provided field is empty or invalid.
179	The max number of installments allowed for recurring payment is 1	The provided field is empty or invalid.
180	The provided Card PaymentToken was not found	Token not found.
181	The MerchantIdJustClick is not configured	Token is blocked.
182	Brand is required	Card brand was not provided.
183	Invalid customer bithdate	Invalid or future date of birth.
184	Request could not be empty	Request format error. Verify the submitted code.
185	Brand is not supported by selected provider	Card brand not supported by the API E-commerce Cielo.
186	The selected provider does not support the options provided (Capture, Authenticate, Recurrent or Installments)	The payment method does not support the requested operation.
187	ExtraData Collection contains one or more duplicated names
188	Avs with CPF invalid
189	Avs with length of street exceeded
190	Avs with length of number exceeded
191	Avs with length of district exceeded
192	Avs with zip code invalid
193	Split Amount must be greater than zero	The amount for a Split de Pagamento must be greater than 0.
194	Split Establishment is Required	The provided field is empty or invalid.
195	The PlataformId is required	The provided field is empty or invalid.
196	DeliveryAddress is required	The provided field is empty or invalid.
197	Street is required	The provided field is empty or invalid.
198	Number is required	The provided field is empty or invalid.
199	ZipCode is required	The provided field is empty or invalid.
200	City is required	The provided field is empty or invalid.
201	State is required	The provided field is empty or invalid.
202	District is required	The provided field is empty or invalid.
203	Cart item Name is required	The provided field is empty or invalid.
204	Cart item Quantity is required	The provided field is empty or invalid.
205	Cart item type is required	The provided field is empty or invalid.
206	Cart item name length exceeded	The provided data exceeds the field size limit.
207	Cart item description length exceeded	The provided data exceeds the field size limit.
208	Cart item sku length exceeded	The provided data exceeds the field size limit.
209	Shipping addressee sku length exceeded	The provided data exceeds the field size limit.
210	Shipping data cannot be null	Required field was not provided.
211	WalletKey is invalid	Invalid Visa Checkout data.
212	Merchant Wallet Configuration not found	The wallet is not enabled. See how to enable wallets on the Cielo website.
213	Credit Card Number is invalid	The provided credit card is invalid.
214	Credit Card Holder Must Have Only Letters	Must not contain special characters.
215	Agency is required in Boleto Credential	Required field was not provided.
216	Customer IP address is invalid	IP is blocked for security reasons.
220	Service tax can not be sent with 1 installment	`ServiceTaxAmount` requires installments greater than 1.
228	Customer Anddress Country is required	The provided field is empty or invalid.
233	Service tax not supported for the given brand.	`ServiceTaxAmount` is not supported by the card brand.
298	Split payment facilitator data not found	The provided `MerchantId` does not exist in the database of the selected environment (production or sandbox).
300	MerchantId was not found
301	Request IP is not allowed	The IP restriction service may be enabled, and the provided IP address is not configured. You can verify the IP addresses used by your merchant account on the Cielo website under E-commerce > Gestão API E-commerce > Gerenciamento de IPs. For more information, see the IP configuration documentation.
302	Sent MerchantOrderId is duplicated
303	Sent OrderId does not exist
304	Customer Identity is required	The provided field is empty or invalid.
306	Merchant is blocked	The merchant is blocked.
307	Transaction not found	Transaction not found or does not exist in the selected environment.
308	Transaction not available to capture	The transaction cannot be captured. We recommend querying the transactional status through the API. Capture can only be performed when the transaction status is 1. Each transaction can be captured only once, including in cases of partial capture. For more information, contact Cielo Support.
309	Transaction not available to void	The transaction cannot be voided. Please contact Cielo Support.
310	Payment method doest not support this operation	The requested operation is not supported by the selected payment method.
311	Refund is not enabled for this merchant	Voids after 24 hours are not authorized for the merchant.
312	Transaction not available to refund	The transaction does not allow voids after 24 hours.
313	Recurrent Payment not found	Recurrence is not enabled. Contact Cielo Support to have it enabled.
314	Invalid Integration
315	Cannot change NextRecurrency with pending payment	It is not allowed to change the recurrence date with a pending payment.
316	Cannot set NextRecurrency to past date	It is not allowed to change the recurrence date to a past date.
317	Invalid Recurrency Day
318	No transaction found
319	Smart recurrency is not enabled	The recurrence is not linked to the merchant registration.
320	Can not Update Affiliation Because this Recurrency not Affiliation saved
321	Can not set EndDate to before next recurrency
322	Zero Dollar Auth is not enabled	Zero Auth is not enabled. Contact Cielo Support to have it enabled.
323	Bin Query is not enabled	Consulta BIN is not enabled. Contact Cielo Support to have it enabled.
841	Status nao permite capturar	Attempt limit reached. Create a new transaction to perform the capture.

Provider return codes: `ProviderReturnCode` and `ProviderReturnMessage`

ProviderReturnCode and ProviderReturnMessage provide additional details for specific operations and can be useful for debugging. They represent the direct response returned by the provider (for example, the acquirer or bank), and their values are typically the same as those returned in ReturnCode and ReturnMessage.

Examples of operations that return ProviderReturnCode:

Pix refund;
Void;
Currency conversion;
Payment creation with boleto.

Reason codes: `ReasonCode` and `ReasonMessage`

ReasonCode and ReasonMessage can indicate either success or error conditions. They are associated with Cielo's internal operational flows and/or the interactions between Cielo and the card brand or issuer that occur after the API E-commerce Cielo receives the request.

ReasonCode indicates the code, while ReasonMessage provides the description associated with that code.

The main operations that return ReasonCode and ReasonMessage are:

Capture;
Void;
Currency conversion;
Payment creation with boleto.

Reason Code and Reason Message table

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

Sale return codes: ReturnCode and ReturnMessage

How to interpret ReturnCode

Warning for denied credit or debit card authorizations:

Common ReturnCode scenarios by payment method

ReturnCode and ReturnMessage Table

Provider return codes: ProviderReturnCode and ProviderReturnMessage

Reason codes: ReasonCode and ReasonMessage

Reason Code and Reason Message table

Sale return codes: `ReturnCode` and `ReturnMessage`

How to interpret `ReturnCode`

Common `ReturnCode` scenarios by payment method

`ReturnCode` and `ReturnMessage` Table

Provider return codes: `ProviderReturnCode` and `ProviderReturnMessage`

Reason codes: `ReasonCode` and `ReasonMessage`