Business questions

1. What is the Cielo e-Commerce API?

The Cielo e-Commerce API is the evolution of the webservice 1.5 as a CIELO online transactional engine. It offers an API that allows the Cielo retailer to perform a modular and simplified integration. The Cielo e-Commerce API solution of the Cielo e-Commerce platform was developed with the technology REST, which is a market standard and does not depend on the technolgy used by our clients, therefore, it is possible to integrate yourself using the most varied programmming languages, such as: ASP, ASP .NET, Java, PHP, Ruby, Python, etc.

2. What’s the difference between Webservice 1.5 and the Cielo e-Commerce API?

The Cielo e-Commerce API offers new functionalities in addition to a simplified integration model

3. What are the payment methods accepted on the Cielo e-Commerce API?

The Cielo e-Commerce API accepts the following payment methods:

4. Can I maintain an integration 1.5 and a Cielo e-Commerce API at the same time?

It is not possible to maintain two simultaneous integrations of the webservice 1.5 and Cielo e-Commerce API When registering one of the integrations along with the Cielo e-Commerce, it will be required to chose between one of the platforms For more information, access:

5. I do not have an integration 1.5. Can I use the Cielo e-Commerce API?

Yes, the Cielo e-Commerce API integration does not depend on a previous webservice 1.5 integration. Just register along with Cielo, thus obtaining your credentials to transact Access for more information.

6. Can I perform a migration from 1.5 to Cielo e-Commerce API?

Cielo provides a Sandbox environment (, where the developer is able to start a learning process about the API integration.

After understanding the integration, it’s required to contact the Cielo e-Commerce support and request the creation of new access credentials to the production environment, thus It’ll be possible to start the integration in production.

For more information, access:

7. I have a 1.5. Is it necessary to perform a new homologation to use the Cielo e-Commerce API?

Yes, it is necessary to perform a new homologation to validate the transactional capacity of your website. To integrate yourself to the Cielo e-Commerce API in production, it will be required to request new credentials and start a new homologation.

8. How can I release other payment methods besides the credit card?

To release new payment methods, you’ll have to contact Cielo e-Commerce support and request the activation through the desired method. Only boletos require additional data:

9. How can I get support from Cielo?

The support to the Cielo e-Commerce API integrated retailer is given by the following channels:

10. Where can I follow my sales through the Cielo e-Commerce API?

Through the retailer area, on the website:

Technique questions / Integration

11. How does the Cielo e-Commerce API solution from Cielo work?

The Cielo e-Commerce API solution of the Cielo e-Commerce platform was developed with REST technology, The used model is quite simple: There are two URLs (endpoint): one specific to the operations that cause side effects – such as authorization, capture and transactions cancelling, and the other URL specific for operations that do not cause side effects, such as transaction search.

12. Are there changes from the credentials 1.5 to the Cielo e-Commerce API?

Yes, the credentials used in each platform are different:



Cielo e-Commerce API

13. How do I get the credentials for each environment?

There are two environments on the Cielo e-Commerce API: Sandbox and Production.

14. Is it required any proprietary software, such as DLLs, to perform the integration?

No. The absence of proprietary applications is one of the solution’s characteristics: It is not required to install applications on the store’s environment under any circumstances.

15. Do I have to make an affiliation before testing the integration?

It is not required an affiliation to use the Cielo Sandbox. Just access Sandbox registration and create a test account. By the end of the registration, you will get a MerchantId and a MerchantKey, That will have to be used to authenticate all the requisitions made to the API endpoints.

16. What kind of content is sent on the integration?

To simplify the Cielo e-Commerce API solution to the maximum, the integration is made through JSONs sending on a REST architecture. Each type of message must be sent to an identified feature through path and sent according the appropriate HTTP method:

17. How to test transactions with simulated payment methods?

To perform tests on the Cielo e-Commerce API, it is not required to use cards / real payment method. Each payment method (Credit, Debit, boleto and online transfer) has a simulated counterpart.

18. Is there any rule for card reading?

The reading of card data on the environment itself is controlled by rules defined by the security program imposed by the card flags

Additionally, when meeting the requirements, while on the e-Commerce accreditation the choice by card reading on the store itself must be mentioned.

19. Is it required to use any certificate to perform the connection to the Cielo e-Commerce API?

Yes, it is required to perform the installation of the SSL EV certificate. More information at:é-certificado-ev-ssl

20. Is it required any security protocol for the Cielo e-Commerce API usage?

It is mandatory the usage of TLS 1.2 on the communication with the API.

SSL, TLS 1.0 and 1.1 are not supported. Integrations using these protocols will not be able to perform transactions.

21. Is there any IP restriction to consume the API?

There are no IP restrictions or need of PROXY usage to integrate to the Cielo e-Commerce API.

22. How to query Sandbox transactions?

The Sandbox environment does not have a report area, this being required a query via API to visualize transactions in this environment. Check how to perform this query in our integration manual:

23. The Cielo e-Commerce API has SDKs for what languages?

The API has SDKs for the following languages:

More information at:

24. Does the Cielo e-Commerce API accept payments with different currencies and international cards?

Note: International cards can not perform installments.

25. Will I be able to consult information about my contract along with Cielo (Tax, amount deposit deadline)?

No, data about taxes and charging amounts are not subject to consultation through Cielo e-Commerce API These data will be available for consulting through the retailer area on Cielo website or via Cielo support.

26. Will I be able to perform advance payments through Cielo e-Commerce API?

No, Cielo e-Commerce API is only intended to the transaction authorization process and updating online orders data. Questions or issues regarding the financial agenda and receivables anticipation must be directed to Cielo support.

27. How will my integration be notified regarding the status changes?

Status changes will be notified through a POST HTTP directed to the notification URL that must registered by Cielo support.

28. How can I query data regarding my sales?

It will be possible to query through the API or via Cielo portal:

29. What is a transaction?

The central element of Cielo e-Commerce is the transaction, created from an HTTP requisition to the Cielo Webservice. The unique identification of a transaction on Cielo is made though the TID field, that is present on the authorization messages return. This field is essential to perform queries, captures and cancelling.

30. What is the deadline for an authorization to expire?

The deadline for the capture of a transaction is defined in your Cielo register and depends on your company line of business. In case a transaction is not captured within this limit, it ceases to be valid, not being able to captured anymore. The sale status will remain as authorized, but it won’t be subject to be changed.

31. Is it possible to perform a capture in a moment after the authorization?

An authorized transaction only generates the credit to the commercial establishment when captured. Therefore, every sale that the retailer wants to effect, It’ll be required for him to perform a transaction capture (or confirmation)

For Credit modality sales, this confirmation may occur in two moments:

  1. Immediately after the authorization (full capture) – it is not required to send a capture requisition, for it is made automatically by Cielo after the transaction authorization. Therefore, it is required to configure the transaction requisition defining the “true” amount to the TAG, as seen on the “Criando uma transação” section.
  2. Posteriorly to the authorization (total or partial capture) – As for the second situation, it is required to perform a “posterior capture”, trough a new requisition to the Cielo Webservice to confirm the transaction and receive the sale amount.

32. Is it possible to cancel a transaction?

The cancelling is used when the retailer decides not to effect the purchase order, being that for stock shortage, withdrawal of consumer purchase, or any other reason. Its use is mainly required if the the transaction is captured, for there will be debit on the holder invoice, in case it isn’t canceled.

If the transaction is only authorized and the store wants to cancel it, the cancelling request is not necessary, for after the capture deadline expires, the amount will not be charged of the buyer and the transaction will be invalidated.

33. What is the difference between the notifications for each payment method?

Every alteration on the order status will be notified via notification URL, that must be registered along with Cielo. Each payment method has different a status and it may vary depending on the returned information.

Example: Boletos have no return for the payment confirmation. The payment method conciliation must be done by the retailer.

Questions about features

1. What features have to be enabled by Cielo for the Cielo e-Commerce API usage in production?

By default, each retailer using the Cielo e-Commerce API must request Cielo Support the enabling of the following functionalities:

2. What features are available in Sandbox?

Available features in Sandbox:

Non-available features in Sandbox:


1. What is the Recurrence?

Recurrence is a feature for establishments that have to regularly charge for your products/services. Recurrence is the periodical transaction execution and pre-scheduled by the retailer or buyer. It is a feature highly used for the magazines signatures, tuition, software license, among others.

2. What are the Cielo e-Commerce API recurrence types?

The Cielo e-Commerce API provides two recurrence structures:

Intelligent Recurrence: The retailer sends a schedule transaction, with the payment and recurrence behavior data the API will replicate the transaction content and will execute it automatically, without the interference of the seller. In this method, there will be made available different features to model the charge according to the business model adopted. Every parameterization is configurable , such as: periodicity, start and end date, attempts quantity and interval.

Own recurrence: In this method, the retailer will have to automatize the transactions sending according to his/her need. The API only recognizes that it is a recurrence transaction, not requiring like the CVV, as mandatory. The entire recurrence periodic execution process becomes a retailer’s role.

3. When is a recurrence created?

In the smart recurrence case, the recurrence is created on the moment that the first transaction (scheduling transaction) is “authorized”, that is, even if the sale is not captured, future transactions will occur based on the scheduling data.

For own recurrence, the beginning of the recurrence and its scheduling is a retailer’s role.

4. Can I customize the recurrence interval?

Yes, it is possible to update the smart recurrence interval, but only for one of the scheduling options available.

5. How does the notification of new recurrences occur?

The smart recurrence transactions notification are the same sent to standard transactions. For more information about transactions notification, access:ência

6. Is it possible to update a recurrence data? If so, what data?

Yes, on the smart recurrence, it is possible to update a recurrence data via a PUT within the Cielo e-Commerce API. The data subject to modification are:

7. What are the rules to update the recurrence interval?

A.If the new informed day is after the current scheduling day, the recurrence day update will have effect on the next recurrence.

B.If the new informed day is before the current scheduling day, the recurrence day update will only have effect after the next recurrence is successfully executed.

C.If the new informed day is before the current scheduling day, but the next recurrence is on the next month, the recurrence day update will have effect on the next recurrence.

Tokenization/Protected card

1.What is the Cielo e-Commerce API tokenization/protected card?

It is the platform that allows the secure storage of sensitive credit card data. These data are transformed into an encrypted code called “token”, that will be able to be stored in database. With the platform, the store will be able to offer features like “One click buy” and “Transaction send Re attempt”, always preserving the information integrity and confidentiality.

2.When is it possible to tokenize a card?

It is possible to tokenize a card in 2 moments:

  1. On a transaction sending: When scheduling a recurrence or in a standard transaction, but indicate on the technical contract that you wish to save the card.
  2. Using a card saving contract available on the technical documentation.

3.Is it required being PCI to store the Tokens?

No, to store the tokens is not required being PCI certified.

4.Is it required to send the CVV to perform a transaction only with the token?

Yes, for a matter of security, the Cielo e-Commerce API demands the CVV sending in case a token is used to transact.


1.What is the authentication?

The Authentication is a payment flow where the buyer is directed to the card issuing bank for the buyer to be identified as the real holder on the buying moment.

2.Is the Authentication mandatory?

The authentication is only mandatory to debit card, being that an option for retailers that wish to authenticate credit cards.

3.Is the redirecting mandatory?

Yes, the authentication process requires the buyer to be directed to the bank environment.

4.Is it required to enable the authentication in my Cielo register?

Yes, it is required the retailer to contact the Cielo support and request that his/her Affiliation is fit to perform online authentications.

5.What card brands are able to perform the authentication?

Visa and Mastercard

Fraud Analysis

1.What is the Cielo fraud analysis?

It is a fraud prevention platform that provides a detailed risk analysis of the on-line purchases. Each transaction is submitted to more than 200 rules, besides the specific rules for each segment, and generate a risk recommendation in approximately two seconds. This process is totally transparent to the card holder. According to pre-established criteria, the request can be automatically accepted, refused or forwarded to manual analysis.

2.Is the fraud analysis mandatory?

No, the fraud analysis occurs as an addendum to the debit cards authorization process. It’s only required that the Anti fraud is enabled in your Cielo register. For more information on how to perform a fraud analysis, access:

3.In case there is a chargeback in an analyzed sale, will I be refunded?

No, the fraud analysis offered by Cielo only informs what data fled the buy/buyer activities standard, indicating what points present bigger evidences/risk to a supposed fraud. The accept decision of the transaction and its capture are the sole responsibility of the retailer. In case the chargeback is performed, Cielo does not take responsibility on refunding the retailer.

4.Can I use my own Anti fraud along with Cielo e-Commerce API?

No, the retailer can only use Cielo’s own anti fraud as a mean of analysis within the Cielo e-Commerce API.

Zero Auth

1.What is Zero Auth?

Zero Auth is a Cielo API card validation tool. The validation allows the retailer to know if the card is valid or not before sending the transaction to authorization, anticipating the reason of a probable non-authorization.

2.What does the Zero Auth do?

Zero auth simulates a Cielo authorization, validating data such as:

3.What does Zero Auth not do?

Zero Auth does not inform:

4.In what cards does Zero Auth work?

Only in MasterCard and Visa credit cards.

5.How to integrate to Zero Auth?

Zero Auth is a feature provided only to a few Cielo retailers. To know more about the integration mode, contact the Cielo e-Commerce Support.

Gateways Integration

1.I use a payment Gateway. Can I use the Cielo e-Commerce API?

Yes, but it is required that your Gateway is integrated to Cielo e-Commerce API and has your access credentials (MerchantKey and MerchantID)

2.How is the payment gateway able to integrate?

Using the same Cielo retailer standard integration, however the Gateway will need to have the retailer credentials to perform payment authorizations.