API business return codes (Provider and Reason)

To find out whether a sale was authorized and/or paid, check the Payment.Status, and the ProviderReturnCode and ProviderReturnMessage.

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

See in this section:

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

Provider return codes: `ProviderReturnCode` and `ProviderReturnMessage`

The ProviderReturnCode and ProviderReturnMessage provide the result of the operation from a business standpoint, returned by the provider/acquirer, and are shown in the response body for the following operations:

Transaction creation;
Capture;
Void;
Pix refund;
Currency conversion;
Boleto payment creation.

⚠️
The ProviderReturnCode and ProviderReturnMessage values shown below are the ones returned when the transaction's provider/acquirer is Cielo.
If the merchant uses another acquirer integrated with the Gateway, the codes and messages will be the ones defined by that acquirer — check the documentation of the acquirer used for the full list.

The main successful ProviderReturnCode values (for the Cielo acquirer) are:

00: transaction authorized;
4: transaction authorized (ready to be captured);
6: transaction captured.

ℹ️
Validate the success of the sale by combining the ProviderReturnCode with the Payment.Status.

Some examples of ProviderReturnCode for denied transactions (Cielo acquirer) are:

51: the cardholder doesn't have enough balance for the purchase;
54: expired card;
78: new card not yet unlocked.

How to interpret the `ProviderReturnCode`

When a transaction is denied, the ProviderReturnCode is the basis for determining the decision flow. It's important for the merchant to analyze whether the return is reversible or irreversible and decide whether to resubmit the transaction for a new authorization attempt.

Analyze the return type to:

Determine whether the transaction can be sent again for the same card;
Create messages on the payment page or send a message to the shopper suggesting they use another card or another payment method.

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

Send the transaction again for authorization (retry);

Respect the card brand's retry limit for that code to avoid penalties.

When the transaction is irreversible:

Suggest the shopper try another card or payment method.

Common `ProviderReturnCode` scenarios by payment method

The following table shows the main scenarios by payment method, with the corresponding Status and ProviderReturnCode (values for the Cielo acquirer):

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

*The ProviderReturnCode and ProviderReturnMessage values shown in the table are examples of common returns for each scenario when the provider/acquirer is Cielo. If the merchant uses another acquirer, check that acquirer's documentation.

`ProviderReturnCode` and `ProviderReturnMessage` table (Cielo acquirer)

ProviderReturnCode and ProviderReturnMessage show the same values as Code and Message, but are returned in different situations:

The ProviderReturnCode and ProviderReturnMessage values are returned in successful HTTP operations (200 or 201);
The Code and Message values are returned in HTTP error operations (e.g., 400).

⚠️
The table below lists the codes and messages specific to the Cielo acquirer.
If the merchant uses another acquirer integrated with the Gateway, the ProviderReturnCode/ProviderReturnMessage codes and messages will be different — check the documentation of the acquirer used.

See the full table:

Provider Return Code	Provider Return Message	Description
0	Internal error	The submitted data exceeds the field size limit.
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 exist	The submitted field exceeds the size limit 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 submitted MerchantId is not a GUID.
115	The provided MerchantId was not found	The MerchantID doesn't exist or belongs to another environment (e.g., Sandbox).
116	The provided MerchantId is blocked	Blocked merchant, contact hantID doesn't exist or belongs to another environment (e.g., Sandbox).
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	The `Payment` node was not sent.
120	Request IP not allowed. Check your IP White List	IP blocked for security reasons.
121	Customer is required	The `Customer` node was not sent.
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	The credit card number is required.
128	Card Number length exceeded	Card number exceeds 16 digits.
129	Affiliation not found	Payment method not linked to the merchant, or invalid Provider.
130	Could not get Credit Card
131	MerchantKey is required	The submitted field is empty or invalid.
132	MerchantKey is invalid	The submitted MerchantKey is not valid.
133	Provider is not supported for this Payment Type	The submitted Provider doesn't exist.
134	FingerPrint length exceeded	The submitted data exceeds the field size limit.
135	MerchantDefinedFieldValue length exceeded	The submitted data exceeds the field size limit.
136	ItemDataName length exceeded	The submitted data exceeds the field size limit.
137	ItemDataSKU length exceeded	The submitted data exceeds the field size limit.
138	PassengerDataName length exceeded	The submitted data exceeds the field size limit.
139	PassengerDataStatus length exceeded	The submitted data exceeds the field size limit.
140	PassengerDataEmail length exceeded	The submitted data exceeds the field size limit.
141	PassengerDataPhone length exceeded	The submitted data exceeds the field size limit.
142	TravelDataRoute length exceeded	The submitted data exceeds the field size limit.
143	TravelDataJourneyType length exceeded	The submitted data exceeds the field size limit.
144	TravelLegDataDestination length exceeded	The submitted data exceeds the field size limit.
145	TravelLegDataOrigin length exceeded	The submitted data exceeds the field size limit.
146	SecurityCode length exceeded	The submitted data exceeds the field size limit.
147	Address Street length exceeded	The submitted data exceeds the field size limit.
148	Address Number length exceeded	The submitted data exceeds the field size limit.
149	Address Complement length exceeded	The submitted data exceeds the field size limit.
150	Address ZipCode length exceeded	The submitted data exceeds the field size limit.
151	Address City length exceeded	The submitted data exceeds the field size limit.
152	Address State length exceeded	The submitted data exceeds the field size limit.
153	Address Country length exceeded	The submitted data exceeds the field size limit.
154	Address District length exceeded	The submitted data exceeds the field size limit.
155	Customer Name length exceeded	The submitted data exceeds the field size limit.
156	Customer Identity length exceeded	The submitted data exceeds the field size limit.
157	Customer IdentityType length exceeded	The submitted data exceeds the field size limit.
158	Customer Email length exceeded	The submitted data exceeds the field size limit.
159	ExtraData Name length exceeded	The submitted data exceeds the field size limit.
160	ExtraData Value length exceeded	The submitted data exceeds the field size limit.
161	Boleto Instructions length exceeded	The submitted data exceeds the field size limit.
162	Boleto Demostrative length exceeded	The submitted data exceeds the field size limit.
163	Return Url is required	The return URL is invalid - Pagination or extensions (e.g., PHP) aren't accepted in the return URL.
166	AuthorizeNow is required
167	Antifraud not configured	Antifraude not linked to the merchant's registration.
168	Recurrent Payment not found	Recurrence not found.
169	Recurrent Payment is not active	The recurrence isn't active. Execution stopped.
170	Cartão Protegido not configured	Cartão Protegido not linked to the merchant's registration.
171	Affiliation data not sent
172	Credential Code is required	Failed to validate the submitted credentials.
173	Payment method is not enabled	Payment method not linked to the merchant's registration.
174	Card Number is required	The submitted field is empty or invalid.
175	EAN is required	The submitted field is empty or invalid.
176	Payment Currency is not supported	The submitted field is empty or invalid.
177	Card Number is invalid	The submitted field is empty or invalid.
178	EAN is invalid	The submitted field is empty or invalid.
179	The max number of installments allowed for recurring payment is 1	The submitted field is empty or invalid.
180	The provided Card PaymentToken was not found	Cartão Protegido token not found.
181	The MerchantIdJustClick is not configured	Cartão Protegido token blocked.
182	Brand is required	Card brand not sent.
183	Invalid customer bithdate	Invalid or future birth date.
184	Request could not be empty	Request format error. Check the submitted code.
185	Brand is not supported by selected provider	Card brand not supported by the Gateway de Pagamento API.
186	The selected provider does not support the options provided (Capture, Authenticate, Recurrent or Installments)	The payment method doesn't support the submitted command.
187	ExtraData Collection contains one or more duplicated names
188	Avs with CPF invalid
189	Avs with length of street exceeded	The submitted data exceeds the field size limit.
190	Avs with length of number exceeded	The submitted data exceeds the field size limit.
190	Avs with length of complement exceeded	The submitted data exceeds the field size limit.
191	Avs with length of district exceeded	The submitted data exceeds the field size limit.
192	Avs with zip code invalid	The submitted ZIP code is invalid.
193	Split Amount must be greater than zero	The amount for the SPLIT must be greater than 0.
194	Split Establishment is Required	SPLIT not enabled for the merchant's registration.
195	PlatformId is required	Platform validators not sent.
196	DeliveryAddress is required	Required field not sent.
197	Street is required	Required field not sent.
198	Number is required	Required field not sent.
199	ZipCode is required	Required field not sent.
200	City is required	Required field not sent.
201	State is required	Required field not sent.
202	District is required	Required field not sent.
203	Cart item name is required	Required field not sent.
204	Cart item quantity is required	Required field not sent.
205	Cart item type is required	Required field not sent.
206	Cart item name length exceeded	The submitted data exceeds the field size limit.
207	Cart item description length exceeded	The submitted data exceeds the field size limit.
208	Cart item sku length exceeded	The submitted data exceeds the field size limit.
209	Shipping addressee sku length exceeded	The submitted data exceeds the field size limit.
210	Shipping data cannot be null	Required field not sent.
213	Credit Card Number is invalid	The submitted credit card is invalid.
214	Credit Card Holder Must Have Only Letters	The cardholder name must not contain special characters.
215	Agency is required in Boleto Credential	Required field not sent.
216	Customer IP address is invalid	IP blocked for security reasons.
220	Service tax can not be sent with 1 installment	`ServiceTaxAmount` requires more than 1 installment.
228	Customer Anddress Country is required	The submitted field is empty or invalid
233	Service tax not supported for the given brand	`ServiceTaxAmount` not supported by the card brand.
298	Split payment facilitator data not found.	The submitted `MerchantId` doesn't exist in the database for the selected environment (Production or Sandbox).
300	MerchantId was not found
301	Request IP is not allowed
302	Sent MerchantOrderId is duplicated	The order was duplicated.
303	Sent OrderId does not exist
304	Customer Identity is required
306	Merchant is blocked
307	Transaction not found	Transaction not found or doesn't exist in the environment.
308	Transaction not available to capture	The transaction cannot be captured - contact x not supported for the given brand b Check whether the submitted amount is lower than the total transaction amount or whether it's available for capture.
309	Transaction not available to void	The transaction cannot be voided - contact r>
310	Payment method does not support this operation	The submitted command isn't supported by the payment method.
311	Refund is not enabled for this merchant	Voiding after 24 hours isn't enabled for the merchant.
312	Transaction not available to refund	The transaction doesn't allow voiding after 24 hours.
313	Recurrent Payment not found	Recurring transaction not found or unavailable in the environment.
314	Invalid Integration
315	Cannot change NextRecurrency with pending payment
316	Cannot set NextRecurrency to past date	You can't change the recurrence date to a past date.
317	Invalid Recurrency Day
318	No transaction found
319	Smart Recurrency is not enabled	Recurrence not linked to the merchant's registration.
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 not linked to the merchant's registration.
323	Bin Query is not enabled	Consulta BIN not linked to the merchant's registration.
841	Status nao permite capturar	Retry limit reached. Generate a new transaction to capture.
902	Erro no tratamento da resposta do pagamento	One-time processing error. Try again.

Reason codes: `ReasonCode` and `ReasonMessage`

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

The ReasonCode indicates the code, while the ReasonMessage provides the description corresponding to the code. The main operations that return ReasonCode and ReasonMessage are:

Capture;
Void;
Currency conversion;
Boleto payment creation.

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

Provider return codes: ProviderReturnCode and ProviderReturnMessage

How to interpret the ProviderReturnCode

Warning for denied credit or debit card authorizations:

Common ProviderReturnCode scenarios by payment method

ProviderReturnCode and ProviderReturnMessage table (Cielo acquirer)

Reason codes: ReasonCode and ReasonMessage

Reason Code and Reason Message table

Provider return codes: `ProviderReturnCode` and `ProviderReturnMessage`

How to interpret the `ProviderReturnCode`

Common `ProviderReturnCode` scenarios by payment method

`ProviderReturnCode` and `ProviderReturnMessage` table (Cielo acquirer)

Reason codes: `ReasonCode` and `ReasonMessage`