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

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:

Feature Description
Payment page Checkout Cielo has its own transactional screen, with an optimized layout, shortening the steps to pay for your transactions.
Recurrence Cielo Checkout has Scheduled Recurrence. All the store needs to do is define that a transaction must be repeated, and Checkout will execute it again at the defined interval.
Fraud analysis Checkout provides fraud analysis of credit transactions without additional integration.
Various payment methods Checkout Cielo has a wide range of payment methods:
Credit cards
Debit card
Boleto Bradesco and Banco do Brasil
Pix Cielo, Bradesco and Banco do Brasil
Integration with Button and QR Code Without technical integration or programming, Checkout provides an integration that makes it possible to create a button to access the transactional screen. See more at Checkout Tutorial
Transactional reports Within the Cielo website, you can generate transactional reports that facilitate the administration of your sales:
Recurrence Report
Shoppers Report
Sales Statement
Sales Report
BIN Query BIN Query is a card data search service, whether credit or debit, which identifies the characteristics of the card based on the first digits: brand, type, nationality, whether it is a corporate card, issuer and whether it is a pre-paid card.

Payment methods accepted at Cielo Checkout

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

PAYMENT METHOD BRANDS AND PROVIDERS
Credit card Visa, Mastercard, American Express, Elo, Diners Club, Discover, JCB and Hipercard
Debit card Visa, Mastercard and Elo
Pix Cielo, Bradesco and Banco do Brasil
Registered boleto Bradesco and Banco do Brasil

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:

Fluxo Geral Checkout Inglês

  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:

API URL DESCRIPTION
API Checkout Cielo https://cieloecommerce.cielo.com.br/api/public/v1/orders/ Creation of the checkout page.
Cielo OAUTH2 Server https://cieloecommerce.cielo.com.br/api/public/v2/token Authentication for querying, capturing and canceling transactions (creating access_token).
Transactional Control API https://cieloecommerce.cielo.com.br/api/public/v2/ Querying, capturing and canceling transactions.

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:

PROPERTY DESCRIPTION TYPE
ClientId Key identifier provided by CIELO GUID
ClientSecret Key that validates the ClientID. Provided by Cielo along with ClientID string

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

Field Format
ClientId b521b6b2-b9b4-4a30-881d-3b63dece0006
ClientSecret 08Qkje79NwWRx5BdgNJsIkBuITt5cIVO
ClientId:ClientSecret b521b6b2-b9b4-4a30-881d-3b63dece0006:08Qkje79NwWRx5BdgNJsIkBuITt5cIVO
Base64 YjUyMWI2YjItYjliNC00YTMwLTg4MWQtM2I2M2RlY2UwMDA2OiAwOFFramU3OU53V1J4NUJkZ05Kc0lrQnVJVHQ1Y0lWTw

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
}
PROPERTY DESCRIPTION TYPE
Access_token Used to access API services string
Token_type It will always be of the bearer type text
Expires_in Token validity in seconds. Approximately 20 minutes. int

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

EV Internet Explorer Certificate

Firefox

EV Firefox Certificate

Google Chrome

EV Google Chrome Certificate

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.

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:

Step 2

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

Install IE

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

Install FF

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

Install GC

Step 3

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

Install IE

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

Install FF

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

Install GC

Step 4

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

Install IE and GC

Install IE and GC

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

Install FF

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”.

Install IE and GC

Install IE and GC

Step 6

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

Install IE and GC

Step 7

Click on “Finish”.

Install IE and GC

Step 8

Click on “Ok” to complete the import.

Install IE and GC

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

Install IE and GC

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:

Type Description
API An Integration via API allows the merchant to send the web site “Shopping cart” with all the data that he wants to display on the transactional screen.
In this type of integration the merchant has more control over how the order will be generated.
Botão / QR Code / Link Within the Checkout Cielo Backoffice, it is possible to register a product or group of products that will generate a Link capable of creating multiple payment screens. This template is used for payments by social networks, promotional campaigns or Sales via QR Code. In this category the merchant has less control over how the orders will be presented or generated on the transactional screen

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

Checkout Cielo integration flow - Flowchart Checkout Cielo integration flow

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.

Activating test mode

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
Red stripe - Backoffice Red stripe - 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

Transaction Status Cards for conducting tests Return Code Return message
Authorized 0000.0000.0000.0001 / 0000.0000.0000.0004 4 Operation performed successfully
Not Authorized 0000.0000.0000.0002 2 Not Authorized
Not Authorized 0000.0000.0000.0007 77 Canceled Card
Not Authorized 0000.0000.0000.0008 70 Problems with Credit Card
Not Authorized 0000.0000.0000.0005 78 Locked Card
Not Authorized 0000.0000.0000.0003 57 Expired Card
Not Authorized 0000.0000.0000.0006 99 Time Out

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

Customer last name Status
Paid Paid
Any name. Not authorized

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.

Test Transactions

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.

Test 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:

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:

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”:

Node Description
Cart Contains data of the products to be sold.
Shipping Contains data of the type of freight to be charged. Is influenced by the Cart node
Payment Contains information that influences the amount charged. Does not contain information about payment means
Customer Has buyer’s data. Not required in the integration, but required on the payments screen. We suggest it to be sent to expedite the purchase process
Options Controls Checkout optional features. Node not required

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

Field Type Required Size Description
MerchantId Guid Yes 36 Unique store identifier. Format: 00000000-0000-0000-0000-000000000000
Content-type Alphanumeric Yes n/a Type of message content to be sent. Use: “application/json”

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

Field Type Required Size Description Conditional
OrderNumber Alphanumeric Optional 64 Store order number.  
SoftDescriptor Alphanumeric Optional 13 Text displayed on buyer’s invoice. No special characters or spaces. e.g.: NOMEDALOJA123  
Cart.Discount.Type Alphanumeric Conditional 255 Discount type to be applied: Amount or Percent. Required in case of Cart.Discount.Value is greater than or equal to zero.
Cart.Discount.Value Numeric Condicional 18 Discount amount to be applied: Value or Percentage Required in case of Cart.Discount.Type is Amount or Percent.
Cart.Items.Name Alphanumeric Yes 128 Item name in cart.  
Cart.Items.Description Alphanumeric Optional 256 Item description in cart.  
Cart.Items.UnitPrice Numeric Yes 18 Unit price of the product in cents. e.g.: R$ 1,00 = 100  
Cart.Items.Quantity Numeric Yes 9 Item quantity in cart.  
Cart.Items.Type Alphanumeric Yes 255 Item type in cart:
Asset
Digital
Service
Payment
 
Cart.Items.Sku Alphanumeric Optional 32 Item Sku in cart.  
Cart.Items.Weight Numeric Conditional 9 Weight in grams of item in cart. Required in case of Shipping.Type is “Post office”.
Payment.BoletoDiscount Numeric Conditional 3 Discount, in percentage, for payments to be performed with bank slip.  
Payment.DebitDiscount Numeric Conditional 3 Discount, in percentage, for payments to be perfomed with online debit.  
FirstInstallmentDiscount Numeric Conditional 3 Discount, in percentage, for payments to be performed with credit card cash payment.  
MaxNumberOfInstallments Numeric Conditional 2 Sets maximum value of installments displayed in transactional, ignoring Backoffice setup  
Customer.Identity Numeric Conditional 14 buyer’s CPF or CNPJ. Not required in API, but mandatory in the transactional screen
Customer.FullName Alphanumeric Conditional 288 Buyer full name. Not required in API, but mandatory in the transactional screen
Customer.Email Alphanumeric Conditional 64 Buyer’s e-mail. Not required in API, but mandatory in the transactional screen
Customer.Phone Numeric Conditional 11 Buyer’s phone number. Not required in API, but mandatory in the transactional screen
Options.AntifraudEnabled Boolean Conditional n/a Enable or not the fraud analysis for the order: true or false.  
Options.ReturnUrl Strin Conditional 255 Sets to which url the buyer will be sent after completing the purchase. A fixed URL can be registered in Backoffice Checkout

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:

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
    }
}
Field Type Required Size Description
CheckoutUrl String Yes 255 Transactional screen URL. The Buyer must be directed to this environment to finalize the transaction
Profile String Yes 16 Merchant profile: “CheckoutCielo” fixed.
Version String Yes 1 Order creation service version (version: 1).

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

ERROR

{
  "message": "An error has occurred."
}
Field Type Required Size Description
Message String Yes 254 Error descriptive message

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”

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

Discount Application Description
Cart API When sent, it applies the discount on the entire cart, regardless of the means of payment
Bank slip API and Backoffice When sent, the discount is applied only if the Bank slip is the chosen payment means
Online Debit API and Backoffice When sent, the discount is applied only if the Online debit is the chosen payment means
Cash payment API When sent, the discount is applied when cash payment on Credit Card is the chosen payment means

Cart

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

{
  "Discount": {
    "Type": "Percent",
    "Value": 0
  }
}
Field Type Required Size Description Conditional
Cart.Discount.Type Alphanumeric Conditional 255 Discount type to be applied: Amount or Percent. Required in case of Cart.Discount.Value is greater than or equal to zero.
Cart.Discount.Value Numeric Conditional 18 Discount amount to be applied: Value or Percentage Required in case of Cart.Discount.Type is Amount or Percent.

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

Percentage Value
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
  }
}
Field Type Required Size Description
Payment.BoletoDiscount Numeric Conditional 3 Discount, in percentage, for payments to be performed with bank slip.
Payment.DebitDiscount Numeric Conditional 3 Discount, in percentage, for payments to be perfomed with online debit.
Payment.FirstInstallmentDiscount Numeric Conditional 3 Discount, in percent, for cash payments on credit card

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

Transactional screen
Means of payment

Types of “Freight”

Checkout Cielo has different types of freight.

Field Description
FixedAmount Fixed value sent by the merchant. Used if the Merchant has a delivery method of his own
Free Do not perform freight calculation and displays on the transactional screen “Free Shipping”
WithoutShippingPickUp Considered “Withdrawal at the store”
WithoutShipping No freight charge (applicable for digital products and services).
Post office Uses the post office API to perform the cost calculation. The value of the calculation will depend on the used contract (Chosen in the Backoffice of the checkout) and on the type of integration for calculation: Shipping with Volume or Shipping without Volume

Below, how each option is demonstrated on the transactional screen

Type of freight Transactional
FixedAmount FixedAmount
Free Free
WithoutShippingPickUp WithoutShippingPickUp
WithoutShipping WithoutShipping
Post office 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:

Field Type Required Size Description Conditional
Shipping.Type Alphanumeric Yes 255 Freight type:
Post office
FixedAmount
Free
WithoutShippingPickUp
WithoutShipping
 
Shipping.SourceZipCode Numeric Conditional 8 Shopping cart origin zip code. Obrigatório caso Shipping.Type for “Correios”.
Shipping.TargetZipCode Numeric Optional 8 Buyer’s delivery address zip code.  

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.

Field Type Required Size Description
Shipping.Address.Street Alphanumeric Yes 256 Street, avenue, lane, etc., from buyer’s delivery address.
Shipping.Address.Number Alphanumeric Yes 8 Buyer’s delivery address number.
Shipping.Address.Complement Alphanumeric Optional 14 Buyer’s delivery address complement.
Shipping.Address.District Alphanumeric Yes 64 Buyer’s delivery address neighborhood.
Shipping.Address.City Alphanumeric Yes 64 Buyer’s delivery address city.
Shipping.Address.State Alphanumeric Yes 2 Buyer’s delivery address state (UF).

Shipping.Services

Field Type Required Size Description
Shipping.Services.Name Alphanumeric Yes 128 Freight service name.
Shipping.Services.Price Numeric Yes 18 Price of freight service in cents. e.g.: R$ 1,00 = 100.
Shipping.Services.Deadline Numeric Conditional 9 Delivery time (in days).

The Post Office Freight can be calculated in 2 ways:

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

Shipping.Measures

Field Type Required Size Description Conditional
Shipping.Package Alphanumeric Required Integer Type of package:
BOX- Box
ROL - Cylinder or ENVELOPE
 
Shipping.Lenght Numeric Required Integer Package length  
Shipping.Height Numeric Conditional Integer Package height Required in case of Shipping.Package as BOX
Shipping.Width Numeric Conditional Integer Package width. Required in case of Shipping.Package as BOX or ENVELOPE
Shipping.Diameter Numeric Conditional Integer Package diameter. Required in case of Shipping.Package as ROL

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:

Type of freight Transactional
Transactional pre-screen It means that there was some wrong data in sending the transaction. Required data may be missing or in invalid format. Here the merchant will always receive an e-mail stating what went wrong
Transactional post-screen It means that there is some register impediment that limits the sale. Things like membership blocked, error in data saved in the register or even problems in the checkout itself

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 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 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:

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.

Feature Explanation
Specific Each generated button only suits for a particular product or group of products. The quantity and volume of products sold is defined in the Button register, and it is not possible to change the quantity in the transactional screen
Example: It will be necessary to create a button to sell 1 shirt. If the buyer desires 3 shirts, he will need to use the button 2X or The merchant should create a button with 2 shirts
Checkout Order Number The button does not allow the register of the Merchant’s order number. Since Cielo will trigger its own Checkout, a unique order number (a GUID) will be generated. The Merchant will receive this order number as a link to the performed sale
Creation of orders One button generates multiple independent orders, i.e. it is not possible to limit the number of orders generated by a button, QRCODE or created Link. Button is a method of calling the API Checkout. Each time it is triggered, a new request is performed to the API, thus creating a new order

Below, the payment flow via Button:

Button Checkout Cielo Integration Flow

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:

Button Registration

Registered Button:

Button Registration

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

Fields Description Minimum Size Maximum size Required
Product Type Indicate whether you are selling a Material, a Service or a Digital Good. For Digital goods, the Freight type option will not be displayed. n/a n/a Yes
SKU Product identification code 1 50 No
Title Product Title 1 50 Yes
Description Product description 1 255 Yes
Price Order total value in cents (e.g.: R$1,00 =100). 11 14 Yes
Freight Choose from one of the Freight options (Post Office, Fixed Freight, Free Shipping, Store Pickup, No Charge). n/a n/a Yes
Zip Code of Origin This field only appears for Post Office Freight type, must be filled with the Zip Code from where the goods will be shipped for freight calculation purposes. 9 9 Yes
Weight(kg) This field only appears for Post Office Freight type, must be filled with the product weight in kg for freight calculation purposes n/a n/a Yes
Cost of Freight This field only appears for Fixed Freight freight type, and must be filled with the amount that the merchant specifies for their products. n/a n/a Yes
Shipping method This field only appears for Product Type equal to Physical Material and Type of Freight equal to Fixed Freight. n/a n/a Yes
URL This field only appears for Product Type equal to Digital. n/a n/a Yes

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 Link
  http://bit.ly/2tRkSxZ

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.

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:

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:

Order Status Explanation
1 PENDING Original status. The transaction is occurring, awaiting response from the authorization process
2 AUTHORIZED / DECLINED Result of the authorization process.
AUTHORIZED - Credit was reserved for purchase
DECLINED - Card not authorized by the issuer to continue the transaction
3 PAID It occurs after capture. Indicates that the credit booked on the card will be deposited in the merchant’s account
N/A EXPIRED Occurs if the transaction is not captured within 15 days after authorization. In this situation the transaction is lost.
N/A CHARGEBACK Not automatic status. If the merchant is notified of ChargeBack, he can mark this transaction as lost.
This Status is only a markup, not affecting payment processes

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.

Anti-Fraud Status Substatus description
Low risk Low risk Low risk of being a fraudulent transaction
Medium Risk Medium Risk Medium risk of being a fraudulent transaction
High risk High risk High risk of being a fraudulent transaction
Not finished Not finished Could not complete the query
N/A Authenticated Transactions authenticated by the bank - They are not analyzable by AF
N/A AF Not hired Anti-fraud not allowed in merchant’s plan - They are not analyzable by AF
N/A AF Dispensed Anti-fraud dispensed via contract or lower than the minimum value of antifrade parameterized backoffice in the merchant
N/A Not applicable Non-analyzable means of payment such as debit cards, bank slip and online debit
N/A Recurrence transaction credit transaction is later than the scheduled transaction. Only Scheduling is analyzed
N/A Transaction declined Credit sale has been declined - They are not analyzable by AF

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

Risk analysis

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

Anti-fraud Status

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:

Mastercard Visa
Bradesco Bradesco
Banco do Brasil Banco do Brasil
Santander Santander
Itaú Itaú
CitiBank CitiBank
BRB N/A
Caixa N/A
BancooB N/A

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:

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.

Adesão Pix

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:

Adesão Pix

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:

Mastercard Visa
Bradesco Bradesco
Banco do Brasil Banco do Brasil
Santander Santander
Itaú Itaú
CitiBank CitiBank
BRB N/A
Caixa N/A
BancooB N/A

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

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:

Type Description
POST Notification where the merchant is passive. Two POST HTTP are triggered, one informing sales data and another the change of Transaction Status
JSON Notification where the merchant performs a query. One POST containing information for conducting a query (GET) the checkout transactions

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.

Type Description Note
Return URL Web page to where the buyer will be redirected at the end of the purchase.
No data is exchanged or sent to this URL.
This URL only takes the buyer, after completing the purchase, to a page set by the store.
If the Merchant wishes, he can configure this page to be sensitized by traffic, thus identifying that the transaction has been completed in Checkout Cielo
Can be sent via API - See “Integration via API”
Notification URL At the end of a transaction, an HTTP POST with all the sales data is sent to the Notification URL.
The notification POST is only sent at the time the transaction is finalized, regardless of whether the transaction status changed**
Used in the Notification via POST andJSON
Status Change URL When an order has its status changed, a HTTP post will be sent to the Status Change URL.
The status change POST does not contain cart data, only order identification data
Used only in Notification via POST

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:

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

URLS registration

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

N.POST Flow

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:

Resending of notification

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)

N.JSON Flow

JSON NOTIFICATION POST content:

Parameter Description Field Type
URL URL with the data needed to perform the transaction data search. String
MerchantId Store identifier at Checkout Cielo; in the Backoffice in the Setup/Register Data menu. Alphanumeric (GUID)
MerchantOrderNumber Store order number; if it is not sent, Checkout Cielo will generate a number, which will be viewed by the Customer. Alphanumeric

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 resending

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:

Parameter Description Field Type Maximum size
checkout_cielo_order_number Unique identifier generated by CHECKOUT CIELO Alphanumeric 32
amount Unit price of the product, in cents (e.g.: R$ 1,00 = 100) Numeric 10
order_number Order number sent by store Alphanumeric 32
created_date Date of order creation - dd/MM/yyyy HH:mm:ss Alphanumeric 20
customer_name Name of the customer. If sent, this value is already filled in the CHECKOUT CIELO screen Alphanumeric 289
customer_identity Customer identification (CPF or CNPJ) If sent, this value is already filled in the CHECKOUT CIELO screen Alphanumeric 14
customer_email Customer e-mail. If sent, this value is already filled in the CHECKOUT CIELO screen Alphanumeric 64
customer_phone Customer phone number. If sent, this value is already filled in the CHECKOUT CIELO screen Numeric 11
discount_amount Discount amount provided (sent only if there was a discount) Numeric 10
shipping_type Freight mode Numeric 1
shipping_name Freight name Alphanumeric 128
shipping_price Value of the freight service, in cents (e.g.: R$ 10,00 = 1000) Numeric 10
shipping_address_zipcode Delivery address zip code Numeric 8
shipping_address_district Delivery address neighborhood Text 64
shipping_address_city Delivery address city Alphanumeric 64
shipping_address_state Delivery address state Alphanumeric 64
shipping_address_line1 Delivery address Alphanumeric 256
shipping_address_line2 Delivery address complement Alphanumeric 14
shipping_address_number Delivery address number Numeric 8
payment_method_type Payment means type code Numeric 1
payment_method_brand Issuer (only for transactions with credit card payment means) Numeric 1
payment_method_bank Issuer bank (For Automatic Debit and Bank slip transactions) Numeric 1
payment_maskedcredicard Masked Card (Only for transactions with credit card payment means) Alphanumeric 20
payment_installments Number of installments Numeric 1
payment_antifrauderesult Status of Credit Card Transactions in Anti-Fraud Numeric 1
payment_boletonumber Number of bank slip generated String 1
payment_boletoexpirationdate Due date for transactions made with bank slip Numeric 10
payment_status Transaction status Numeric 1
tid TID Cielo generated at the time of transaction authorization Alphanumeric 20
test_transaction Indicates whether the transaction was generated with ‘Test Mode’ enabled Boolean 32

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.

Value Transaction status Means of Payment Description
1 Pending For all means of payment Indicates payment is still being processed; NOTE: Bank slip - Indicates that the bank slip did not have status changed by the merchant
2 Paid For all means of payment Transaction captured and money will be deposited into account.
3 Declined Credit Card only Transaction not authorized by the party responsible for the payment means
4 Expired Credit Cards and Bank slip Transaction no longer valid for capture - 15 days post Authorization
5 Canceled For credit cards Transaction was canceled by the merchant
6 Not Finished All means of payment Payment waiting Status - May indicate error or processing failure. Contact Cielo Support
7 Authorized Credit Card only Transaction authorized by the card issuer. Must be captured for money to be deposited into account
8 Chargeback Credit Card only Transaction canceled by the customer with the card issuer. Money will not be deposited into account.

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.

Value Anti-Fraud Status Substatus description
1 Low risk Low risk Low risk of being a fraudulent transaction
3 Medium Risk Medium Risk Medium risk of being a fraudulent transaction
2 High risk High risk High risk of being a fraudulent transaction
4 Not finished Not finished Could not end query
N/A N/A Authenticated Transactions authenticated by the bank - Not analyzable by AF
N/A N/A AF Not hired Anti-Fraud not enabled on the merchant’s plan - Not analyzable by AF
N/A N/A AF Dispensed Anti-fraud dispensed via contract or lower than the minimum value of anti-fraud parameterized backoffice in the merchant
N/A N/A Not applicable Non-analyzable payment means such as debit cards, bank slip and online debit
N/A N/A Recurrence transaction Credit transaction is after than the scheduled transaction. Only Scheduling is analyzed
N/A N/A Transaction declined Sale by credit was declined - Not analyzable by AF

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.

Value Description
1 Credit card
2 Bank slip
3 Online Debit
4 Debit card

Payment_method_brand

Value Description
1 Visa
2 Mastercad
3 AmericanExpress
4 Diners
5 Elo
6 Aura
7 JCB

Payment_method_bank

Value Description
1 Banco do Brasil
2 Bradesco

Shipping_type

Value Description
1 Post office
2 Fixed freight
3 Free shipping
4 Withdraw in store
5 No freight charge (digital services or products)

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:

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

Installments Selection

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

Features

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 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
}
Field Type Required Size Description
MaxNumberOfInstallments Numeric Conditional 2 Sets maximum value of installments displayed in transactional, ignoring Backoffice configuration

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:

Difference between recurrent and installment transactions:

Type Description
Installment This is a transaction divided into several months.
The total value of the sale compromises the limit of the buyer’s credit card regardless of the value of the initial installment.
The merchant receives the sale value in installments and does not take the plunge of one of the installments being declined.
e.g.: Sale of R$1.000,00 installment in 2x. Although the buyer pays only R$500.00 in the first installment, the amount of the credit limit consumed is the integral, that is, R$1,000.00. If the card limit is lower or the amount is not released, the R$1,000.00 transaction will be declined
Recurrent They are different transactions performed on the same card at previously scheduled times.
The first sale schedules future sales from a pre-defined time interval.
At each interval there will be a charge on the credit card.
The recurring payment blocks from the card limit only the value debited on the date of the first recurring sale and from the total value of the sale.
e.g.: Sale of R$1,000.00 on 01/15/2015, with monthly recurrence and final date on 06/01/2015. Every day of 15 there will be a new charge of R$1,000.00 on the buyer’s card, repeating until 05/15/2015, the last valid date before the end date.

Recurrence by API

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

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

Payment.RecurrentPayment

Field Type Required Size Description
Payment.RecurrentPayment.Interval Alphanumeric Yes 10 Interval between each recurrence transaction
Payment.RecurrentPayment.EndDate YYYY-MM-DD No 255 Date where the Recurrence will end; If not sent the recurrence ends only if canceled
Interval Description
Monthly Monthly
Bimonthly Bimonthly
Quarterly Quarterly
SemiAnnual SemiAnnual
Annual Annual

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:

Recurrence button

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:

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.

Querying transactions

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:

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: