This manual will guide the developer in integrating with the Checkout Cielo API. By integrating the Checkout API, you will be able to:

• Configure your store and customize your payment page;
• Create a payment page via API;
• Query, capture and cancel transactions via API;
• Receive payment notifications.

Not a developer? You can use Checkout via the Cielo website or the Cielo Gestão app. Find out more in this tutorial.

About Checkout Cielo

Checkout Cielo is recommended for websites with shopping carts, that is, when the consumer browses the website and chooses one or more products to purchase. When finalizing the purchase, the consumer is redirected to a secure Cielo online payment page.

Checkout Cielo is a solution that brings together several payment processing services and generates a payments page that provides a high level of trust, following PCI security standards.

The great advantage of Checkout Cielo is the range of services aggregated in a secure transactional screen with only one technical integration via the API REST.

Checkout has the following features:

Payment methods accepted at Cielo Checkout

The current version of Checkout Cielo supports the following payment methods and card brands:

Note: Checkout Cielo maximum limit of installments is 12 installments.

Prerequisites for integration

Checkout Cielo has a list of basic requirements for the integration process to be successful. Here are the points that must be ready before integration:

1. The store’s registration must be active with Cielo;
2. A timeout needs to be defined in HTTP requests to Cielo. We recommend 30 seconds;
3. The Root certificate of the certifying entity (CA) of our Web Service must be registered. See the section Extended Validation Certificate for more information.
4. We recommend using the Chrome and Edge browsers for the web and Safari, Chrome and Samsung Internet for mobile, always in their most up-to-date versions.

API Checkout Cielo flow

In the API Checkout Cielo, the merchant sends a request to create the checkout screen and the API returns a URL to access the checkout page, called CheckoutUrl. Check out more details about how the API works in the following flow:

1. The shopper chooses the products in the store integrated into Checkout Cielo and clicks on Buy;
2. The merchant sends the checkout page creation request to the Cielo Checkout API;
3. The API Checkout Cielo returns the CheckoutUrl, which is the URL of the checkout page created based on the data sent by the merchant (such as shopper, product, delivery data and others);
4. The store redirects the buyer to the URL returned by Cielo (checkout page). The screen shown is part of the Cielo secure payment environment;
5. The shopper chooses the payment method, type of shipping and delivery address on the checkout page;
6. Checkout Cielo redirects the shopper to the Return URL chosen by the merchant (if the merchant has configured a Return URL on the Cielo website);
7. The merchant will be notified about the status of the transaction (if the store has configured a notification URL on the Cielo website);
8. The store processes the purchase order using the notification data and, if the transaction is authorized, releases the order.

Important: Cielo Checkout does not notify shoppers about the status of their purchase. Cielo Checkout only notifies the merchant when there is a change in the payment status, thus allowing the merchant to decide when and how to inform its shopper about the delivery time and shipping process. To receive notifications, you must configure at least one type of notification URL in Merchant Settings.

Endpoints

The endpoints for integration with Cielo Checkout are presented in the following table:

Important: The Checkout API does not have a sandbox, but you can create test checkout pages by activating Test Mode on the Cielo website.

Cielo OAUTH Authentication

Cielo OAUTH is an authentication process for Cielo APIs related to e-commerce. Cielo OAUTH uses the OAUTH2 protocol for security. In it, it is necessary to first obtain an access token using your credentials and then send it to the Transactional Control API.

Authentication is only required for query, capture and cancellation operations.

To use Cielo OAUTH, the following credentials are required:

To generate the ClientID and ClientSecret, see the Obtaining Credentials topic, below.

Obtaining credentials

To obtain the ClientId and ClientSecret credentials, follow the steps below:

1. After receiving the establishment number (EC) with authorization for Checkout, access the Cielo website and login;
2. Go to Ecommerce > Checkout > Configurações > Dados Cadastrais;
3. In the Contato técnico section, fill in the contact details of the person responsible for receiving the store’s keys. ATTENTION: only enter the details of the person who can actually have access to your store’s keys, which are confidential information for each establishment;
4. Click on Gerar Credenciais de Acesso às APIs;
5. The technical contact will receive an email with credentials.

Obtaining the access token

To gain access to Cielo services that use Cielo Oauth, you will need to obtain an access token, following the steps below:

1. Concatenate the ClientId and ClientSecret, **ClientId:ClientSecret**;
2. Encode the result in Base64;
3. Send the token creation request using the HTTP POST method.

Example of Concatenation

Request

The request must be sent only in the header.

x-www-form-urlencoded
--header "Authorization: Basic {base64}"  
--header "Content-Type: application/x-www-form-urlencoded"  
grant_type=client_credentials

Response

The response will return the access_token, which must be used in Transactional Control API requests, for query, capture and cancellation operations.

{
  "access_token":
    "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjbGllbnRfbmFtZSI6Ik1ldUNoZWNrb3V0IE1hc3RlciBLZXkiLCJjbGllbnRfaWQiOiJjODlmZGasdasdasdmUyLTRlNzctODA2YS02ZDc1Y2QzOTdkYWMiLCJzY29wZXMiOiJ7XCJTY29wZVwiOlwiQ2hlY2tvdXRBcGlcIixcIkNsYWltc1wiOltdfSIsInJvbGUiOiJasdasdasd291dEFwaSIsImlzc47I6Imh0dHBzOi8vYXV0aGhvbasdasdnJhc3BhZy5jb20uYnIiLCJhdWQiOiJVVlF4Y1VBMmNTSjFma1EzSVVFbk9pSTNkbTl0ZmasdsadQjVKVVV1UVdnPSIsImV4cCI6MTQ5Nzk5NjY3NywibmJmIjoxNDk3OTEwMjc3fQ.ozj4xnH9PA3dji-ARPSbI7Nakn9dw5I8w6myBRkF-uA",
  "token_type": "bearer",
  "expires_in": 1199
}

The returned token (access_token) must be used in every query, capture and cancellation request as an authorization key. The access_token has a validity of 20 minutes (1200 seconds) and it is necessary to generate a new token every time the validity expires.

Extended Validation Certificate

What is SSL Certificate?

The SSL Certificate for web server offers authenticity and integrity of web site data, giving customers of virtual stores the guarantee that they are actually accessing the web site they want, not a fraudster web site.

Specialized companies are responsible for domain validating and, depending on the type of certificate, they are also responsible for the validation of the entity that owns the domain.

Internet Explorer

Firefox

Google Chrome

What is EV SSL Certificate?

The EV Certificate has been recently released on market and ensures a higher level of security for virtual stores customers.

It is a certificate of greater confidence and when https is accessed the address bar will turn green, giving more reliability for site visitors.

How to install the Extended Validation Certificate on the Store server?

Just install the following three files in the server Trustedstore. Cielo does not offer support to the installation of the Certificate. If you are unsure about how to install the EV Certificate, then you should contact your server vendor support.

• Root Certificate
• Intermediate certificate
• E-Commerce Cielo certificate

Step-by-Step for Installation

Installation on the Virtual Store Server

The step-by-step of the EV Certificate installation must contact your server vendor support.

Client Access to Virtual Store

Normally, the browser automatically updates the Certificate. If it does not and the client contacts, the following steps must be informed:

Step 1

Save the three files below into a new folder, or into a folder that can be easily remembered, as it will be used later:

• Root Certificate
• Intermediate certificate
• E-Commerce Cielo certificate

Step 2

In “Internet Explorer”, click on “Tools” menu and go to “Internet Options”:

In “Firefox”, click on “Open Menu” menu and go to “Advanced” and “Options”:

In “Chrome”, click on “Customize and Control Google Chrome” and go to “Settings” and “Show advanced settings … “Change Proxy Settings and “Content” and Certificates:

Step 3

In Internet Explorer, under “Certificates”, click on “Import”.

In Firefox, click on “View Certificates”, click on “Import”

In Chrome, click on “Manage Certificates”, click on “Import”

Step 4

In Internet Explorer and Chrome “Certificate Import Wizard”, click on “Next”.

In Firefox “Servers Tab”, click on “Import”

Step 5

In Chrome and Internet Explorer “Certificate Import Wizard”, click on “Search”, look for the folder where the files are and select the file “cieloecommerce.cielo.com.br.crt, click on “Open” and then “Next”.

Step 6

Select the desired option: add the Certificate in a default folder or search for the folder of your choice.

Step 7

Click on “Finish”.

Step 8

Click on “Ok” to complete the import.

The Certificate may be viewed in the default tab “Other People” or at the one chosen by the customer.

Step 9

Repeat the same procedure for the 3 sent files.

Integrating Checkout Cielo

This documentation describes all the features of the API Checkout Cielo integration, technical parameters and especially the examples of codes to facilitate their development.

There are two ways to achieve integration:

Integration flow

During the integration with Checkout Cielo, a sequence of information exchange and redirects will be executed so that a transaction is created and executed. See the flow below:

Checkout Cielo integration flow - Sequential diagram

Checkout Cielo integration flow - Flowchart

After the card carrier (custumer) select their purchases and hit the “Buy” button of a shop already integrated with Checkout Cielo, the flow in this order:

1. The Cielo API returns the CheckoutURL, which is the URL of the transactional screen assembled based on the data sent by the Merchant/Button.
2. The store redirects the customer to the URL returned by Cielo. The screen shown is part of the Cielo safe payment environment.
3. The carrier chooses: Means of payment , freight type and delivery address on the transactional screen
4. Checkout Cielo redirects the customer to the Return URL chosen by the store, configured in Backoffice Checkout Cielo or sent by the integration via API.
5. If the store has a notification URL, it will be notified about the status of the transaction.
6. The store notifies the customer that the process has been completed and that he will receive more information about the purchase and payment by e-mail.
7. The store processes the purchase order using the notification POST data and, if the transaction is authorized, releases the order.

NOTE: The Checkout Cielo does not notify buyers about purchasing status, only the merchant does. This is because it allows the merchant to decide when and how to inform their customers about the delivery deadline and shipping process

Checkout Cielo test mode

Checkout Cielo test mode is a tool that allows to test the integration of your web site with the platform. With the test mode, you can perform transactions as you evolve with integration, and you can simulate scenarios to test different means of payment.

Activating test mode

The test mode can be activated in the Settings tab, where there is a checkbox that, when checked, enable the Checkout Cielo test mode. The test mode will only start when the selection is saved.

When the option is saved, a red stripe appears at the top of the screen. It will be displayed on all the screens of the Backoffice Cielo Checkout and on the Checkout Cielo transaction screen.

This stripe indicates that your Checkout Cielo store is now operating in a test environment, i.e. any transaction performed in that mode will be considered as a test.

Backoffice	Transacional

How to transact in Test Mode

Performing transactions in test mode occurs normally. Transaction information is sent via POST or API, using the parameters as described in the Integration by API topic, however, the payment means to be used are simulated media.

To perform test transactions with different payment means, follow these rules:

A - Transactions with Credit cards:

To test credit cards it is necessary for two important data to be defined, the authorization status of the card and the return of the fraud analysis.

Credit Card Authorization Status

Example: 540443424293010 7 = Authorized

B - Bank slip

Just carry out the purchase process normally with no change in procedure. The bank slip generated in test mode will always be a simulated bank slip.

C - Online debit

It is necessary to inform the status of online Debit transaction to be returned the desired status. This process occurs as in the credit card anti-fraud described above, with the change of the name of the buyer.

Debit Status

• Example: Unauthorized Status.
• Customer name: Maria Pereira

D - Test Transactions

All transactions performed in test mode will be displayed as normal transactions in the Checkout Cielo Orders tab, however, they will be marked as test transactions and will not be accounted for in conjunction with transactions performed outside of the test environment.

These transactions will have the test symbol differentiating them from their other transactions. They can be captured or canceled using the same procedures of the actual transactions.

SDKs and POSTMAN

Checkout Cielo has a unique test POSTMAN collection with all the parameters and options described in this manual. Just access our Tutorial for information on using the tool.

In postman it is possible to create examples of its integration in:

• PHP
• RUBY
• C#
• JAVA
• PYTHON
• SHELL

Integration by API

This type of integration must be used whenever there is a “shopping cart” to be sent, i.e. in case the customer browses the web site and choose 1 or more products to add to a cart and then finalize the sale.

If you do not have a shopping cart implemented, see the Checkout Cielo Integration via Button section.

Below, it is demonstrated how the purchase flow occurs in the integration via API:

Creating the Cart

In integration via API, the transactional screen is “assembled” with bases in sent data that form a Shopping cart. These data are separated into the following “main nodes”:

After sending cart data, Checkout will send a Response containing one LINK to the payment screen

IMPORTANT: A call to the API Checkout DOES NOT CREATE A TRANSACTION. The returned Link is just a “preorder” indicating that a transactional screen is ready to be used. The Transaction is created only when the buyer clicks on “FINALIZE”

Request

Endpoint is the URL to where requests with the cart data will be sent. All requests must be sent using the HTTP POST method, for the endpoint:

Example of a requisition

{
  "OrderNumber": "Pedido01",
  "SoftDescriptor": "Exemplo",
  "Cart": {
    "Discount": {
      "Type": "Percent",
      "Value": 0
    },
    "Items": [
      {
        "Name": "Produto01",
        "Description": "ProdutoExemplo01",
        "UnitPrice": 100,
        "Quantity": 1,
        "Type": "Asset",
        "Sku": "ABC001",
        "Weight": 500
      }
    ]
  },
  "Shipping": {
    "SourceZipCode": "20020080",
    "TargetZipCode": "21911130",
    "Type": "FixedAmount",
    "Services": [
      {
        "Name": "Motoboy",
        "Price": 1,
        "Deadline": 15,
        "Carrier": null
      },
      {
        "Name": "UPS Express",
        "Price": 1,
        "Deadline": 2,
        "Carrier": null
      }
    ],
    "Address": {
      "Street": "Rua Cambui",
      "Number": "92",
      "Complement": "Apto 201",
      "District": "Freguesia",
      "City": "Rio de Janeiro",
      "State": "RJ"
    }
  },
  "Payment": {
    "BoletoDiscount": 15,
    "DebitDiscount": 10,
    "Installments": null,
    "MaxNumberOfInstallments": null
  },
  "Customer": {
    "Identity": "84261300206",
    "FullName": "Test de Test",
    "Email": "test@cielo.com.br",
    "Phone": "21987654321"
  },
  "Options": {
    "AntifraudEnabled": true,
    "ReturnUrl": "http://www.cielo.com.br"
  },
  "Settings": null
}

Header

Header and Authentication - All requests sent to Cielo must be authenticated by the store. Authentication consists of sending MerchantId, which is the unique store identifier provided by Cielo after store affiliation. Store authentication should be done by sending the MerchantId HTTP header field, as shown below and beside:

Body - Detailed

Responses

Due to its sale flow being divided into two stages, the first being the creation of the transactional screen and the second being the finalization of the payment; The Checkout has two replies to a transaction:

• Response - Transactional screen - It is the Response returned with data to send the buyer to the transactional screen
• Response - Transaction Finished - Contains data on the result of the transaction, after the buyer clicks “Finish” on the transaction screen. It is returned only via Notification

Transaction Result/Status: To get the transaction status return, it is necessary to set a NOTIFICATION URL. See the notification session for more information..

Response - Transactional screen

There are only two response options in API integration: Success / Error

Success: In case of success, the response will be the content of the Request plus the Link that directs the transactional screen

SUCCESS

{
    "Settings": {
        "CheckoutUrl": "https://cieloecommerce.cielo.com.br/transacional/order/index?id=123",
        "Profile": "CheckoutCielo",
        "Version": 1
    }
}

Error: In case of error, the message below will be returned.

ERROR

{
  "message": "An error has occurred."
}

Important - Checkout Cielo has no numbered errors, just a generic message. See the section “Identifying Integration Errors” for more information.

Additional Features

In the following items, the behavior of some of the API integration features will be explained. These features have rules specific to use and are not available for integration via Button.

• Types of “Discount”
• Types of “Freight”

Types of “Discount”

Checkout Cielo allows the merchant to apply specific discounts for both cart and payment means. The discounts available at Checkout Cielo are:

Cart

To send a Discount on the Cart just send the node below inside the Cart node

{
  "Discount": {
    "Type": "Percent",
    "Value": 0
  }
}

Below, how the effect of the discount is displayed in the Cart:

Percentage	Value

Bank slip & Online Debit

To send a Discount on the Bank slip and Online debit just send inside the Payment node the fields below:

{
  "Payment": {
    "BoletoDiscount": 15,
    "DebitDiscount": 10,
    "FirstInstallmentDiscount": 90
  }
}

Below, how the effect of the discount is displayed in the Cart:

Transactional screen

Types of “Freight”

Checkout Cielo has different types of freight.

Below, how each option is demonstrated on the transactional screen

Type of freight	Transactional
FixedAmount
Free
WithoutShippingPickUp
WithoutShipping
Post office

NOTE: The options for multiple freights in the category Post office should be selected within the Backoffice Cielo.

The nodes that compound the freight information below:

• Shipping - Base node. It is equired on integration via API. It defines the types of freight to be used

Shipping.Address - Delivery address information. Not required in API contract, but mandatory on transactional screen. We suggest this data to be sent, if it has already been collected within the store environment.

Shipping.Services

The Post Office Freight can be calculated in 2 ways:

• Shipping with Volume - Uses the post office API, but requires the store to send the dimensions of the package to be shipped with the goods
• Freight without Volume - Uses the Post Office API, but only considers cart weight as the basis for calculating the delivery.

To use volumetric freight, just send the Shipping.Measures node, following the integration rules via API REST.

Shipping.Measures

To carry out the calculation of freight via Post Office, it is necessary to respect the measures defined by the contract used by the merchant. For more information on dimensions and weights allowed, we suggest that you validate the store agreement at the link below:

Limits and dimensions for post office deliveries

Identifying Integration Errors

Due to the Cielo checkout structure, where the buyer is redirected to a separate environment to complete the transaction, there are possibilities for errors and integration failures at different times of the payment flow. During integration it is important to There are two types of errors that may occur during the integration process with Checkout Cielo. They are:

If any errors occur after the transaction is completed, contact Cielo Support.

Integration by BUTTON

Integration via Button, QR CODE or LINK is a purchase method used whenever there is no “shopping cart” in your store. This type of integration is accomplished through the registration of a set of items to be sold on the backoffice of Checkout Cielo.

The generates one of the 3 different types of access methods to the same transactional screen:

Method	Name	Description
	Button	It is an HTML code that when pasted into a website, will direct the buyer to the transactional screen - Ideal for use in hotSites or Marketing E-mail
	QRCODE	Code interpretable by Smartphones and Tablets - Ideal for use in Printed Marketing or Digital
http://bit.ly/2tRkSxZ	LINK	is a shareable link, ideal for use in Social networks or Messengers Mobile

This integration model is used to:

• Associate a direct quick purchase to a product as a promotion on a homepage by jumping the cart step.
• Send an e-mail marketing, or a charge via e-mail.
• Add the button (HTML) for the product/service to be purchased/paid.
• Perform payments sending by mobile applications
• Whenever you want to provide a quick sale.

To use this feature, it is necessary to register the product you want to sell, their information, and then just copy the source code generated for this button. The inclusion of products is done within the Backoffice Cielo Checkout, in the Products/Register Product menu.

Button Features

Each button has a unique code that only allows to buy that particular product in the conditions of price and registered freight. Therefore, a fraudster can not change any of this information when submitting to the purchase, because Checkout Cielo will collect all the product data in the register of the Backoffice Cielo Checkout, and will be worth the register data.

Below, the payment flow via Button:

Creating the Button

To use this feature, it is necessary to register the product you want to sell, their information, and then just copy the source code generated for this button. The inclusion of products is done within the Backoffice Cielo Checkout, in the Products/Register Product menu.

Registration Screen:

Registered Button:

Below the list of items that must be registered for the button creation:

Example of Button

Below it is possible to see how the registration of a button generates the 3 methods to access the transactional screen.

Button - An HTML code like the one below will be created.:

<form method='post' action='https://cieloecommerce.cielo.com.br/transactional/Checkout/BuyNow' target='blank'><input type='hidden' name='id' value=00000000-0000-0000-000000000000/><input type='image' name='submit' alt='Comprar' src='https://cieloecommerce.cielo.com.br /BackOffice/Contentimages/botao_comprar_3.jpg' />
</form>

Example of a Functional Button:

• QR CODE AND LINK - The link and the QRCODE has the same behavior as the button, leading to the same transactional screen.

Adding the button to your HTML page you should copy the HTML code of the created button and put it in on the HTML code of your web site, as shown in the example below.

Each button has a unique code that only allows to buy that particular product in the conditions of price and registered freight. Therefore, a fraudster can not change any of this information when submitting the purchase, because Checkout Cielo will collect all product data in the register of the Backoffice Cielo Checkout, and the register data will be valid.

Use case

Here’s an example of how to use the link tool / Qr code / Payment button to boost your sales!

For ease of reading, let’s name these options as “LQB”.

First, let us explain the differences between these 3 options. They are 3 ways to access our payment screen without necessarily a technical integration with APIs etc.

• Link - is a shortened url that can be sent via social networks. Very practical for access via computers!
• QR Code - is an image that when read by a device with QR code reader (an APP on the cell phone for example), takes the buyer to the payment screen. Great for printed advertising!
• Button - is an Image embedded in HTML code to use in a web site. Very good if you own a web site, but does not want to deal with creating carts or payment streams. Put on your web site and that’s all, the button takes the buyers to the payments screen

The LQB is available when you register a cart in Checkout Cielo’s backoffice. Just follow the path below:

Merchant access on Cielo web site > Online Sales > Checkout Cielo > ABA: Products >. Register products

That’s it! After registering you already have a LQB waiting to be used!

Here’s an example of use:

• Link + Recurrence:

The PagBras company holds a birthday party with their employees every month, watered by soft drinks and snacks, provided by the company itself, which they say are very good!

One day the employees decided to carry out a “crowdfunding” and contribute monthly to make the variety of snacks and drinks bigger, so they could do theme parties such as Christmas, for example.

What did they do? Being an attuned company that did not want to use a little box every month to collect the monthly contribution, one of the employees created a recurrence via LQB, and in a company Facebook group, posted the payments link.

Today, employees contribute monthly without having to remember to pay, once the Checkout Cielo Recurrence performs a new billing transaction every month!

Payment methods flow

Credit card

Checkout Cielo allows the use of Credit Cards of the main national and international issuers. This means of payment is automatically released with Cielo affiliation, and can be used initially with the Checkout integration.

Credit card transactions will be included in the Backoffice Cielo Checkout as PENDING, AUTHORIZED, PAID, DECLINED, EXPIRED OR CHARGEBACK depending on the result of the authorization with the Bank.

Credit Card Order of Status:

Warning - International Cards: Checkout Cielo accepts cards issued outside Brazil, however these cards do not have the ability to pay installment sales. This is a limitation imposed by the issuing bank.

Warning - EXPIRED TRANSACTIONS: By default, Checkout Cielo stores have 15 days to capture the Credit transaction. If not captured, these transactions will be LOST.

Fraud Analysis

Credit transactions “AUTHORIZED” will be sent for analysis of the anti-fraud tool if the Options.AntifraudEnabled parameter is defined as TRUE. Anti-Fraud has the concept of Status and SubStatus, where the first represents the level of risk that a transaction has to be a fraud, and the second, additional information about the transaction. The analysis shall indicate a degree of *RISK**, specified by the Status, for the sale in question. This degree of risk is what should guide the merchant’s decision to capture or cancel the sale.

The analysis will be displayed in the “Order Details”, as below:

You can view the anti-fraud status by going to the purchase detail in the Orders tab and clicking on (+)

Debit card

Checkout Cielo allows the use of MasterCard and Visa Debit cards. This means of payment is automatically released with Cielo affiliation and can be used initially with the Checkout integration.

Supported Banks:

NOTE: Cards not belonging to these banks will have their authorizations declined.

Upon accessing the transaction screen, the buyer will obtain by the payment via Debit Card, and will be redirected to the banking environment for Authentication and Authorization.

Debit card transactions will be included in the Backoffice Cielo Checkout as PENDING, PAID, UNAUTHORIZED or NOT FINISHED, depending on the result of the authorization with the Bank.

Debit card - Order of Status

1. Pending - Original status. The transaction is occurring, awaiting response from the bank to send the buyer to the authentication environment
2. Not finished - Intermediate status. At this point Checkout Cielo expects the Bank to confirm the status of the authentication and transaction. If the buyer leaves the bank environment, the status does not change.
3. Paid - Buyer successfully completed debit card payment.
4. Not authorized - The Buyer did not present an account balance to finalize the transaction.

NOTE: The Cancell option within the backoffice, will modify the status of the PAID/NOT PAID transaction to CANCELED, but will have no effect on the banking movement. It will be up to the merchant to return the value to the buyer

Pix

What is Pix?

Pix is a Brazilian instant payment method, created by Banco Central (BC), in which resources are transferred between accounts in a few seconds, at any time or day (including holidays and weekends).

In addition to increasing the speed of payments, Pix in Cielo offers several benefits:

• Improves the sales conversion rate;
• Increases security in transactions;
• It is integrated with Checkout Cielo, versatile and easy.

How to use Pix in Checkout Cielo?

You must enable the Pix payment method in your registration on the Cielo portal and in your store settings. In API integration, it is not necessary to send additional parameters.

Enabling Pix on the Cielo portal

To use Pix, your registration must be enabled with the Pix payment method. To confirm the qualification, access the Cielo portal and click on Meu Cadastro > Autorizações > Pix.

If Pix is not enabled in your registration, the accession screen will be displayed if your establishment (EC) is eligible; after completing the Pix accession process, it will be possible to use Pix at Checkout Cielo.

Enabling Pix in merchant settings

Also make sure Pix is enabled in your store settings. To do so, go to E-commerce > Checkout Cielo > Acessar > Configurações > Configurações da Loja. Scrolling down the page will show the means of payment available in your registration:

Once this is done, your e-commerce can now receive transactions with Pix at Checkout Cielo.

Bank slip

Checkout Cielo allows the use of Bradesco (Wallet 26 and SPS) and Banco do Brasil Bank slips (Wallet 17). This means of payment must be registered by Cielo Support to be made available in Backoffice Checkout.

Supported Banks:

NOTE: Cards not belonging to these banks will have their authorizations declined.

Upon accessing the transaction screen, the buyer will obtain by the payment via Debit Card, and will be redirected to the banking environment for Authentication and Authorization.

Debit card transactions will be included in the Backoffice Cielo Checkout as PENDING, PAID, UNAUTHORIZED or NOT FINISHED, depending on the result of the authorization with the Bank.

Debit card - Order of Status

1. Pending - Original status. The transaction is occurring, awaiting response from the bank to send the buyer to the authentication environment
2. Not Finished - Intermediate status. At this point, the Checkout Cielo expects the Bank to confirm the status of the authentication and transaction. If the buyer leaves the bank environment, the status does not change.
3. Paid - Buyer successfully completed debit card payment.
4. Not Authorized - The Buyer did not present an account balance to finalize the transaction.

NOTE: The Cancel option within the backoffice, will modify the status of the PAID/NOT PAID transaction to CANCELED, but will have no effect on the banking movement. It will be up to the merchant to return the value to the buyer

Online Debit

Checkout Cielo allows the use of Online Debit (Transfer between bank accounts) for buyers who have accounts at Bradesco and Banco do Brasil banks. This means of payment is released via registration with Support Cielo.

Upon accessing the transaction screen, the buyer will obtain by the payment via Online debit, and will be redirected to the banking environment for Authentication and Authorization.

Online debit transactions will be included in the Backoffice Cielo Checkout as PENDING, PAID, UNAUTHORIZED or NOT FINISHED, depending on the result of the authorization with the Bank.

Online debit - Order of Status

• Pending - Original status. The transaction is occurring, awaiting response from the bank to send the buyer to the authentication environment
• Not Finished - Intermediate status. At this point, the Checkout Cielo expects the Bank to confirm the status of the authentication and transaction. If the buyer leaves the bank environment, the status does not change.
• Paid - Buyer successfully completed debit payment.
• Not Authorized - The Buyer did not present an account balance to finalize the transaction.

NOTE: The Cancel option within the backoffice, will modify the status of the PAID/NOT PAID transaction to CANCELED, but will have no effect on the banking movement. It will be up to the merchant to return the value to the buyer

Payment Notifications

The process of transactional notification in Checkout Cielo occurs via the inclusion of an URL to where will be directed the data of the transactions performed on the platform. Note that Checkout only notifies when a transaction is considered completed i.e. the buyer has filled in all the payment screen data and clicked “Finish”.

Types of notification

Checkout Cielo has two types of notifications that the merchant can use according to their needs:

To use both models, the merchant will need to access Cielo Backoffice and configure both the NOTIFICATION URL and the STATUS CHANGE URL.

Notification URL Types

Checkout has 3 types of URLs that can impact the notification process.

NOTE: If a Return URL is sent to the API, it will have priority over the URL registered in the Backoffice / In the integration Cielo via Button, you can only use the return URL option via backoffice.

URL Features

All 3 URLs must have the following features:

• Must be static URLs
• Must have less than 255 characters
• Special characters are not supported

Setting up URLs

1. Just access within the Backoffice the Settings Tabs
2. At Store Settings, go to the Payments session
3. Register the URLs and choose the type of Notification you want

Notification: POST

Notification via POST is based on sending a POST HTTP when a transaction is performed. It is performed in two steps:

1. NOTIFICATION POST - Occurs when the transaction is finalized. This POST has all the order data, including the initial STATUS of the transaction.
2. STATUS CHANGE POST - Occurs when a transaction has its STATUS changed - e.g.: “Authorized” > > > “Paid”

This flow is used by stores that do not yet perform transactions via API.

Below the Flow of a POST Notification

Return expected to send notification: HttpStatus = 200 (OK) - Post received and processed successfully

IMPORTANT If the registered Notification URL returns any error/is unavailable, *3 retries, with an interval of 1 hour between each POST will be performed.

If the POST is not received, it is possible to resend it manually, just access the order in question by the Backoffice and click on the Sending icon:

See description of notification items in the session “NOTIFICATION POST content”

Notification: JSON

Notification via JSON is a more secure and flexible method for the merchant to conduct a query in Chekcout Cielo. This notification mode is based on a POST JSON, where the merchant receives credentials so that a query (GET) can be performed with the Checkout Cielo database.

It is performed in two steps:

1. NOTIFICATION POST - Occurs when the transaction is finalized. It has the necessary Credentials transactional queries.
2. TRANSACTIONAL QUERY - With the query credentials, the merchant searches for sale data with Checkout Cielo

In JSON Notification, there is no difference between the Notification POST and Status Change. Whenever something occurs in the transaction, the merchant will receive a Notification POST

Below the Flow of a JSON Notification (Transaction Creation + Status Change)

JSON NOTIFICATION POST content:

Example of a query:

REQUEST

--HEADER: MerchantID GET
https://cieloecommerce.cielo.com.br/api/public/v1/orders/{merchantId}/{merchantOrderNumber}

RESPONSE

{
  "order_number": "Pedido01",
  "amount": 101,
  "discount_amount": 0,
  "checkout_cielo_order_number": "65930e7460bd4a849502ed14d7be6c03",
  "created_date": "12/09/2017 14:38:56",
  "customer_name": "Test Test",
  "customer_phone": "21987654321",
  "customer_identity": "84261300206",
  "customer_email": "test@cielo.com.br",
  "shipping_type": 1,
  "shipping_name": "Motoboy",
  "shipping_price": 1,
  "shipping_address_zipcode": "21911130",
  "shipping_address_district": "Freguesia",
  "shipping_address_city": "Rio de Janeiro",
  "shipping_address_state": "RJ",
  "shipping_address_line1": "Rua Cambui",
  "shipping_address_line2": "Apto 201",
  "shipping_address_number": "92",
  "payment_method_type": 1,
  "payment_method_brand": 1,
  "payment_maskedcreditcard": "471612******7044",
  "payment_installments": 1,
  "payment_status": 3,
  "tid": "10447480686J51OH8BPB",
  "test_transaction": "False"
}

See description of notification items in the session “NOTIFICATION POST content”

Return expected to send notification: HttpStatus = 200 (OK) - Post received and processed successfully

IMPORTANT If the registered Notification URL returns any error/is unavailable, *3 new attempts, with an interval of 1 hour between each POST will be made.

If the POST is not received, it is possible to resend it manually, just access the order in question by the Backoffice and click on the Sending icon:

Notification Content

In either HTTP POST or JSON POST Notification, the content of the returned data is the same. Below are described all the returned fields, as well as their definitions and sizes:

NOTIFICATION POST content:

Payment_status

Checkout has a status of its own, different from the CIELO WEB SITE or the API Cielo e-Commerce. See below the complete list.

Payment_antifrauderesult

Antifraud has the concept of Status and SubStatus, where the first represents the level of risk that a transaction has to be a fraud, and the second, an additional information about the transaction.

Payment_method_type

Checkout allows only one type of Bank slip or Online Debit per merchant, so it is not returned if the method used is Bradesco or Banco do Brasil, since only one of them will be activated in the affiliation.

Payment_method_brand

Payment_method_bank

Shipping_type

Checkout Cielo installments

Type of Installment

Checkout Cielo allows the merchant to carry out credit transactions by installments up to 12 times. There are two methods of installment:

• Installment via backoffice - is the default installment method of Checkout. Each issuer has a installment configuration up to 12x. The Value of the Cart (Products + Freight) is equally divided by the number of parcels.
• Installment via API - The Merchant limits the number of installments to be displayed in the backoffice

NOTE: Checkout is limited to 12x installments, even if your Cielo affiliation supports higher values. If the value presented in your backoffice is lower than 12, contact Cielo Support and check the configuration of your Affiliation.

Installment via backoffice

In this mode, the merchant controls the maximum limit of installments that the store will perform by Backoffice Checkout. The installments Value is defined by accessing the Settings tab and changing the session Payments

NOTE: The Check Box must be marked for the payment means to be displayed on the transactional screen.

Features

• Available in Checkout Cielo integrations via API or Button;
• The total value of the items in the cart is summed and divided by the amount of installments of the merchant;
• The value of the purchase is always the same regardless of the number of parcels chosen by the buyer (There is no Interest charge);
• The value of the freight is added to the value of the installment;
• The “in cash” option is always available to the buyer.
• All transactions will have the same installment options.

Installment via API

In this option, the merchant can configure the amount of parcels per sale, specified via API request at the time of sending the transaction. Checkout calculates the installments by considering total value and limit of installments sent via API.

WARNING: In this installment option, the number of installments desired should be lower than the amount that is registered in the backoffice Checkout.

Features

• The merchant sends the maximum number of installments he wants to display to the buyer.
• The value of the freight is added to the value of the installment.

The Installment via API is performed by sending the MaxNumberOfInstallments field inside the Payment node. This will force Checkout to recalculate the installment value. Below is an example of the Node

"Payment": {
  "MaxNumberOfInstallments": 3
}

Checkout Cielo Recurrence

Recurrence is a process of automatic scheduling of credit transactions, that is, it is a transaction that will be repeated automatically, without the need of the buyer to access the transactional screen, according to the rules defined at the time of the scheduling.

Recurrent transactions are ideal for business models that involve the concept of subscription, plan or monthly fee in its form of charge. Some business examples are:

• Schools
• Gyms
• Publishers
• Hosting services

Difference between recurrent and installment transactions:

Recurrence by API

A recurring transaction in Checkout Cielo has two settings: Interval and Closing date.

• Interval – repeat pattern and time interval between each transaction. This time interval between transactions can be: Monthly, Bimonthly, Quarterly, Biannual and Annual.
• Closing date – Date that the recurrence process no longer occurs.

"Payment": {
        "RecurrentPayment": {
            "Interval": "Monthly",
            "EndDate": "2018-12-31"
        }

Payment.RecurrentPayment

The buyer’s credit card data is securely stored within Checkout Cielo, allowing it to be re-used in a recurring transaction. This data is not accessed by the merchant and this intelligence is controlled by Checkout Cielo.

Except the Payment object that contains a new element specific to the recurrence called RecurrentPayment, all other objects are equal to the integration with the Cart.

REQUEST

{
  "OrderNumber": "12344",
  "SoftDescriptor": "Nome que aparecerá na fatura",
  "Cart": {
    "Discount": {
      "Type": "Percent",
      "Value": 10
    },
    "Items": [
      {
        "Name": "Nome do produto",
        "Description": "Descrição do produto",
        "UnitPrice": 100,
        "Quantity": 2,
        "Type": "Asset",
        "Sku": "Sku do item no carrinho",
        "Weight": 200
      }
    ]
  },
  "Shipping": {
    "Type": "Correios",
    "SourceZipCode": "14400000",
    "TargetZipCode": "11000000",
    "Address": {
      "Street": "Endereço de entrega",
      "Number": "123",
      "Complement": "",
      "District": "Bairro da entrega",
      "City": "Cidade de entrega",
      "State": "SP"
    },
    "Services": [
      {
        "Name": "Serviço de frete",
        "Price": 123,
        "Deadline": 15
      }
    ]
  },
  "Payment": {
    "BoletoDiscount": 0,
    "DebitDiscount": 0,
    "RecurrentPayment": {
      "Interval": "Monthly",
      "EndDate": "2015-12-31"
    }
  },
  "Customer": {
    "Identity": 11111111111,
    "FullName": "Fulano Comprador da Silva",
    "Email": "fulano@email.com",
    "Phone": "11999999999"
  },
  "Options": {
    "AntifraudEnabled": false
  }
}

Example: Physical goods

If the product type is Physical Goods, the API requires the sending of the type of freight. If there is a recurrence node in the technical contract, the WithoutShipping type is mandatory, otherwise the following response will be displayed:

RESPONSE

{
  "message": "The request is invalid.",
  "modelState": {
    "[Shipping.Type]": [
      "[Shipping.Type] pedidos com recorrência devem possuir o Shipping.Type 'WithoutShipping'."
    ]
  }
}

IMPORTANT: The Recurrence is created only if the transaction is AUTHORIZED. Whether or not captured, once authorized, the recurrence process starts.

Recurrence by Button

One way to perform recurrence within Checkout is to create a recurring button.

Just register the product, including a billing interval and a closing date (Optional), as in the example below:

WARNING: If a button is used after the registered “End Date”, the transaction will present an error displaying Oppss on the transaction screen. The Date can be edited in the editing screen of the button within “Product Details”

Retry of Recurrences

If one of the recurrence transactions is not authorized, Checkout Cielo performs the retry automatically, sending a new transaction, considering:

• Time interval between attempts: 4 days
• Number of retries: 4 (four), one per day, for 4 consecutive days from the day following the unauthorized original transaction.

NOTE: This process aims to maintain a positive response to the authorization process, preventing the merchant from losing the sale. The Retry Process generates duplicate orders within the Backoffice because the original order, the one declined, will be displayed in the Orders list, along with the new authorized transaction

WARNING:The retry rule can not be modified by the merchant.

Querying transactions

Recurrence transactions are available in Backoffice Checkout Cielo like the other sales of your store in the “ORDERS” tab (see image below).

The first transaction of the recurrence is a normal transaction, following the rules and preferences defined by the merchant in the Backoffice.

WARNING: The value and charge date of the recurring transactions will always be the same as the initial transaction. Scheduling starts automatically from the date the first transaction is authorized.

This screen shows the date that the 1st recurrence transaction was authorized and should be captured manually. The other recurrence transactions will always be captured automatically, regardless of whether the first transaction was captured or canceled. If the Customer has configured Automatic Capture, the recurrence capture will also be automatic.

WARNING: Only the 1st transaction is subjected to anti-fraud analysis

Recurrence Edition

Checkout Cielo allows the merchant to modify 3 recurrence data:

• Activation - A recurrence can be enabled or disabled. e.g.: Suspension of a signature for a period of 3 months; Just set the Recurrence as inactive.
• Interval - It is possible to modify the execution interval.
• Occurrence day - It is possible to modify the execution date of the recurring transaction.

The update is done exclusively via Backoffice Cielo.

Card Brands Retry Program

When a shopper tries to make a card purchase on e-commerce, the transaction may be denied due to several reasons. The next attempts to complete the transaction using the same card are called retrying.

How retrying works

The denied transactions were classified as irreversible (never retry) and reversible (retry allowed).

Th card brands determine if they will charge a fee for retrying and how many retry attemps are allowed before applying charges. The merchants who do not follow the card brand rules will be penalized by charging fees for exceeded transactions.

Please refer to Card Brands Retry Program manual to see each card brand rules.

ABECS return codes

The Brazilian Association of Credit Card and Services Companies (ABECS) establishes as of July 15, 2020, the standardization of the return codes for denied sales authorizations for both the in store and and e-commerce payment solutions of the Brazilian market.

Please refer to ABECS Return Codes table to get the complete list of return codes.

Cielo Support

After reading this manual, if any doubts remain (technical or not), Cielo provides technical support 24 hours a day, 7 days a week in languages (Portuguese and English), in the following contacts:

• +55 4002-5472 – Capitals and Metropolitan Regions
• +55 0800 570 8472 – Other Locations
• +55 11 2860-1348 – International Option 5 – E-commerce support;
• E-mail: cieloecommerce@cielo.com.br