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
- Simplified integration - Using a REST API, replacing the sending of XMLs to the payments authorization
- New payment ways - In addition to credit and debit cards, the Cielo e-Commerce API allows the retailer to perform the payment by Boletos and electronic transfer on Banco do Brasil and Bradesco.
- Scheduled recurrence - The Cielo e-Commerce API allows the retailer to create an automatic recurrence, without needing to store the card data. Just send the transaction and the execution interval
- Cards tokenization - The Cielo e-Commerce API allows the retailer to save clients’ cards, being that for recurrence transactions or creation of wallets. The retailer receives tokens that can be used to perform new transactions. Therefore, Cielo ensures the safety and easiness of access to the retailer’s own base of cards and payment data.
- Zero Auth - New feature that allows the retailer to test a card and verify if it finds itself fit to perform determined transaction - Availability subject to commercial approval.
- Bins Query - Feature that allows the validation of the card type (credit/debit) - Availability subject to commercial approval.
- Integration with the main Wallets - The Cielo e-Commerce API is already integrated with Visa Checkout and MasterPass, wallets with Visa and MasterCard flags, thus allowing the retailer to have access to a wider range of clients.
- Anti fraud - it’s made available on the Cielo e-Commerce API, a risk analysis of the credit cards transactions, thus elevating the retailer’s security and decreasing the chargeback risks.
3. What are the payment methods accepted on the Cielo e-Commerce API?
The Cielo e-Commerce API accepts the following payment methods:
- Credit Cards: Visa / Mastercard / American Express / ELO / Aura / Diners / Discovery / JCB
- Debit Cards: Visa Eletron / MasterCard
- Boletos: Banco do Brasil and Bradesco
- Electronic transfer (Online debit): Banco do Brasil and Bradesco
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: https://www.cielo.com.br/desenvolvedores
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 https://www.cielo.com.br/desenvolvedores for more information.
6. Can I perform a migration from 1.5 to Cielo e-Commerce API?
Cielo provides a Sandbox environment (https://bit.ly/2cHdrzr), 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: https://developercielo.github.io/Guia-de-migracao-1.5x3.0
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:
- Emitting bank
- Current account
- Assignor code
9. How can I get support from Cielo?
The support to the Cielo e-Commerce API integrated retailer is given by the following channels:
- +55 4002-9700 – Capitals and Metropolitan Regions
- +55 0800-570-1700 – Other locations
- +55 11 2860-1348 – International (Option 1 – Technical support/Option 2 – e-Commerce accreditation)
- E-mail: cieloeCommerce@cielo.com.br
10. Where can I follow my sales through the Cielo e-Commerce API?
Through the retailer area, on the website: https://minhaconta.cielo.com.br/wps/portal/est2/login
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:
- 1.5 - AFILIAÇÃO and CHAVE DE PRODUÇÃO are used. These credentials identify the store and destination account in which the amount of the transaction will be deposited according to the financial Cielo agenda. They must be send on the requisition body. Afiliação is the store’s register identification code on Cielo.
- New credentials are used: MerchantId and MerchantKey. These credentials are used to identify the store. In case they are not sent on the Header requisition, the transaction will be blocked by the API, returning “Error”. In an integration with the Cielo e-Commerce API, it is not possible to send 1.5 credentials. The API will deny requests.
- Chave de produção:
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.
- Sandbox: just access https://cadastrosandbox.cieloecommerce.cielo.com.br/ and register. Your credentials will be displayed after the registration.
- Production: it is required to contact the Cielo accreditation central and request your credentials. They are sent via e-mail. About the accreditation central, access: https://developercielo.github.io/Guia-de-migracao-1.5x3.0/#suporte-cielo
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:
- POST - The HTTP POST method is used on features creation or on sending of information that will be processed. For example, on the creation of a transaction.
- PUT - The HTTP PUT method is used to update an already existing feature. For example, capture or cancelling of a previously authorized transaction.
- GET - The HTTP GET method is used for querying already existing features. For example, transactions query.
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.
- C. Credit – Just use the Provider “Simulado” and send one of the cards included here: https://developercielo.github.io/Webservice-3.0/#sandbox
- Boleto - It will be generated an invalid boleto.
- C. Debit – You will be redirected to a screen where you’ll be able to select the operation result
- Online transfer – You will be redirected to a screen where you’ll be able to select the operation result
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
- For Visa, this program is known as AIS (Account Information Security) PCI. For more information, access: www.cielo.com.br > Serviços > Serviços de Segurança > AIS - Programa de Segurança da Informação, or contact us.
- For MasterCard, the security program is SDP (Site Data Protection) PCI. For more information, access: http://www.mastercard.com/us/sdp/index.html, or contact us.
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: https://developercielo.github.io/Webservice-3.0/#o-que-é-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: https://developercielo.github.io/Webservice-3.0/#consultando-vendas
23. The Cielo e-Commerce API has SDKs for what languages?
The API has SDKs for the following languages:
More information at: https://github.com/DeveloperCielo
24. Does the Cielo e-Commerce API accept payments with different currencies and international cards?
- Currencies: At the moment, Cielo e-Commerce API only accepts different transactions in Real (R$/BRL).
- International cards: Yes, the API accepts international cards, but the transactions are processed in Real (R$/BRL) and installment transactions are declined by the emitting card.
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:
- API: Every transaction sent through POST generates an URL where it’s possible to perform a GET, where order data will be returned. More information at: https://developercielo.github.io/Webservice-3.0/#criando-uma-transação-simples
- Cielo Portal: It is possible to extract reports and search for orders from the Cielo website. More information at: www.cielo.com.br
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:
- 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.
- 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:
- Anti fraud
- Zero Auth
- Bins Query
- Re attempt
2. What features are available in Sandbox?
Available features in Sandbox:
- Transactions with every payment method
- Cards tokenization
- Zero Auth
- Bins Query
Non-available features in Sandbox:
- Anti fraud
- Registered Boletos
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: https://developercielo.github.io/Webservice-3.0/#autorizando-a-primeira-recorrê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:
- Buyer data.
- Recurrence closure data.
- Recurrence’s installments number.
- Recurrence execution interval.
- Recurrence day.
- Recurrence Amount.
- Recurrence payment method data
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.
- Ex.: Today is 5th, and the next occurrence is on 25/05. When I update to the 10th, the next recurrence date will be on 10/05.
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.
- Ex.: Today is 5th, and the next recurrence is on 25/05. When I update to the 3rd, the next recurrence date will remain on 25/05, and after it is successfully executed, the next will be scheduled to 03/06.
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.
- Ex.: Today is the 5th, and the next recurrence is on 25/09. When I update to the 3rd, the next recurrence date will be on 03/09.
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:
- 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.
- 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
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: https://developercielo.github.io/Webservice-3.0/#criando-uma-venda-com-analise-de-fraude
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.
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:
- If the card is valid along with the issuing bank
- If the card has available limit
- If the card works in Brazil
- If the card number is correct
- If the CVV is valid
3.What does Zero Auth not do?
Zero Auth does not inform:
- Credit card limit
- Information about the holder
- Inform data about a specific card
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.
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.