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.

Get started

To start your integration with the API Cielo Checkout, you will need:

1. Request the establishment code for Checkout Cielo;
2. Define merchant settings (customization of the page, choice of payment methods and contract with the Post Office, if applicable);
3. Configure a notification and status change URL for your store;
4. Install the Extended Validation certificate;
5. Send the first request for payment page creation;
6. When there is a payment attempt at Checkout Cielo, you will receive a notification* with all data filled in on the payment page;
7. If the transaction changes status, you will receive a status change notification*;
8. To carry out tests, use Checkout Cielo Test Mode.

*If you have configured the notification URL.

Merchant Settings

Before setting up, you need to enable Cielo Checkout for your store.

Enabling the establishment number (EC) for Checkout

• If you are not yet a Cielo customer or if you only use the POS terminal, access the Cielo website to activate the establishment code (EC) for Checkout;
• If you are already a Cielo E-commerce customer, contact your commercial manager or Cielo Support.

Setting up your store

Access store settings on the Cielo website

Go to the Cielo website and log in. Access E-commerce > Checkout > Configurações > Configurações da loja.

1. Customize the appearance of the payment page

Insert the image of your store’s logo and choose a background color. Click on Salvar.

2. Configure the checkout email for the shopper

If you do not want your end customer to receive an order completion email after payment, disable this option. Then click on Salvar.

3. Define the desired payment methods

Select the payment methods you would like to make available to your customers. For credit cards, choose the maximum number of installments allowed. Then click Salvar.

The number of installments available for payment must be the same as that shown in your Cielo registration. Consult E-commerce Support if you have any questions.

Credit card

Checkout Cielo allows the use of credit cards from the main national and international brands. This payment method is automatically available with the Cielo affiliation and can initially be used with the Checkout integration.

Credit card transactions will be included in the Cielo Checkout Backoffice as PENDING, AUTHORIZED, PAID, DENIED, EXPIRED OR CHARGEBACK depending on the result of the authorization with the bank. See possible credit card transaction statuses in the Payment_status table.

Credit card transactions need to be captured automatically or manually - it depends on what you choose on step [5. Configure capture and Antifraude].

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

Debit card

Checkout Cielo allows the use of Mastercard, Visa and Elo debit cards. This payment method is automatically available with the Cielo affiliation and can initially be used with the Checkout integration.

Debit card transactions will be included on the Cielo website as Pago (paid), Não Autorizado (not authorized) or Não Finalizado (not finalized), depending on the result of authorization with the bank. See possible debit card transaction statuses in the Payment_status table.

Pix

The Pix payment method is available for CNPJ-type establishments through two providers, Cielo or Bradesco.

To enable Pix Bradesco, contact support.

Enabling Pix on the Cielo website

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

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

See possible Pix transaction statuses in the Payment_status table.

Boleto

Checkout Cielo allows the use of Boletos from Bradesco and Banco do Brasil. To make boleto available as a payment method, request authorization from E-commerce Support.

The number of installments chosen for payment must be the same as that shown in your Cielo registration. Consult E-commerce support if you have any questions.

Boleto transactions will be included on the Cielo website as Não Finalizado (not finalized) or Pago (paid). Unlike other payment methods, boleto does not have a status update. The store must access the Backoffice Cielo website and modify the boleto status manually.

See possible boleto transaction statuses in the Payment_status table.

QR Code Pay

The QR Code Pay Cielo allows payment through any digital wallet. When the shopper selects the QR Code Pay on the Checkout Cielo payment page and clicks Finalizar compra (finalize purchase), Checkout presents a QR Code to be scanned by the shopper using the digital wallet of their choice.

See possible QR Code Pau transaction statuses in the Payment_status table.

4. Configure your store’s return, notification, and status change URLs

You will need to fill in the return, notification and status change URLs. URLs must be created and defined by the store. Then click Salvar.

• Return URL: after completing payment, the shopper can be redirected to a web page defined by the store. No data is exchanged or sent to this URL and its configuration is optional;
• Notification URL: corresponds to the transaction completion notification. It is the URL through which your store will receive notification with all cart data when the transaction is completed;
• Status Change URL: corresponds to status change notification. It is the URL through which your store will receive the notification when an order has its status changed. The status change notification does not contain cart data, only order identification data.

5. Configure capture and Antifraude

A credit card transaction is sent to Cielo (acquirer) for authorization and will then be subjected to fraud analysis. Then, according to the fraud analysis result, the transaction can be captured automatically or manually.

When accessing your store settings, look for the Antifraude and automatic capture section. Select the desired option:

If the fraud analysis classifies the transaction as High Risk, it will be automatically canceled. Manual capture will not be possible.

Authorized credit transactions will be sent for fraud analysis. All transactions classified as high risk will be automatically cancelled, without exception.

On the Cielo website, the analysis will be presented in Detalhes do Pedido:

You can view the Antifraude status by accessing the purchase details, in the Pedidos tab and clicking +.

6. Configure Correios shipping options

If your store works with the delivery of physical products (those that require shipping) using Correios, enter your Correios login and password and select the desired services, such as Sedex and PAC types.

If your store works with digital materials, services or payments, that is, sales that do not require shipping, skip this step.

It is also possible to use other shipping services contracted by the store. In this case, submit the Shipping.Services node when creating the payment page. Find out more at Defining shipping.

Default settings

If you do not fill in the store settings, Checkout will consider the following pattern:

• The option to send an email to the shopper will be activated;
• The option to accept international cards will be activated;
• The minimum installment amount will be R$5.00;
• Credit and debit payment methods will have 12 installments enabled (if your Cielo registration allows it);
• The debit payment method will be enabled;
• The QR Code Crédito payment method will have one installment enabled;
• Boleto will not have a minimum value or defined discount (zero);
• The Always do Automatic Capture option will only be enabled for transactions that are not considered high risk;
• The Correios shipping login will be disabled.

Extended Validation Certificate

What is SSL Certificate?

The SSL Certificate for web server offers authenticity and integrity of website data, giving e-commerce customers the guarantee that they are actually accessing the website they want, not a fraudster website.

Specialized companies are responsible for validating the domain 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 e-commerce 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?

Simply install the following three files into the server’s Trustedstore. Cielo does not offer support for installing the Certificate. If you are not sure how to install the EV Certificate, you should contact your server supplier’s 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 done in contact with your server vendor support.

Client Access to Virtual Store

Usually, the browser automatically updates the Certificate. If it does not and the client calls for help, 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 located, 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.

Test Mode

Because it is a non-financial call, the Checkout API does not have a sandbox to test the creation of payment pages. Payment pages must be created by registrating on production. Enrollment can be done through the Cielo website or through a request from the establishment’s commercial manager.

Financial tests can be performed by activating test mode in your store settings.

Activating Test Mode

Test mode can be activated in the Configurações tab, by enabling the Modo Teste checkbox. Test mode will only start when the selection is saved.

After saving, a red stripe will be displayed at the top of the screen. It will be displayed on all Checkout screens.

This stripe indicates that your store is now operating in a test environment, that is, every transaction carried out in this mode will be considered a test.

Test transactions

All transactions carried out in test mode will be displayed as normal transactions in the Pedidos tab, however, they will be marked as test transactions and will not be counted together with transactions carried out outside the test environment.

These transactions will have the test symbol differentiating them from your other transactions. They can be captured or canceled using the same procedures as real transactions.

IMPORTANT:

• When releasing your store to make sales to your customers, make sure that Test Mode is disabled;
  
• Transactions carried out in Test Mode can be completed normally, but will not be deducted from the customer’s card and cannot be transferred to the standard sales environment.

How to make transactions in test mode

After activating test mode, transactions occur normally. The creation of the payment page can be done using the same parameters as the production environment, however, the payment methods to be used will be simulated means.

To carry out test transactions with different payment methods, follow the following rules:

Credit or debit card

To test credit or debit cards, it is necessary to use a card that follows the Luhn algorithm and which the final number corresponds to the desired card authorization status (see details in the table below).

Credit or debit card authorization status

Example: 5404434242930100 = Authorized

Boleto

To test boleto transactions, carry out the purchase process normally without any changes to the procedure. The boleto generated in test mode will always be a simulated boleto.

Creating the payment page

In integration via API, the payment page is created based on sent data that forms a shopping cart. This data is divided into the following main nodes:

After sending the cart data, Checkout will send a response containing a link to the payment page in the CheckoutUrl field.

Important: The payment page creation request does not create a transaction. The returned URL (CheckoutUrl) is just a “pre-order” indicating that the payment page is ready to be used. The transaction is only created when the shopper clicks Finalizar on the Checkout screen.

Request

Check out an example of a request to create a payment page on Checkout Cielo.

Parameters in the header

All requests sent to Cielo must be authenticated by the merchant. Authentication for creating the payment page consists of sending the MerchantId in the request header:

{
  "OrderNumber": "Pedido01",
  "SoftDescriptor": "Nomefantasia",
  "Cart": {
    "Discount": {
      "Type": "Percent",
      "Value": 00
    },
    "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,
    "Installments": null,
    "MaxNumberOfInstallments": null
  },
  "Customer": {
    "Identity": "84261300206",
    "FullName": "Test de Test",
    "Email": "test@cielo.com.br",
    "Phone": "21987654321"
  },
  "Settings": null
}

Parameters in the body

IMPORTANT: The order identification number (OrderNumber) does not change throughout the transactional flow but an additional number could be generated for the order and used during the transaction. This number will only be different in case of non-compliance with the acquirer’s rules or in case of order identification numbers (OrderNumber) being repeated in less than 24 hours.

For your order number to be sent in the transaction, follow the following formatting standards:

• Type of field: string;
• Minimum size: 1;
• Maximum size: 20;
• Allowed: letters (a-z, A-Z) and numbers (0-9);
• Not allowed: symbols and special characters, including blank spaces;
• Do not repeat the number in less than 24 (twenty-four) hours.

*Not required, but submission is recommended.

See more information about the Shipping node in Defining shipping.

Response

There are only two response options in API integration: success or error.

Important: The payment page creation request does not create a transaction, but rather the payment page URL (CheckoutUrl). The success or error response refers to the creation of the payment page and is not related to the transaction.

✅ Success: in case of success, the response will be the content of the request plus the link that leads to the transactional screen (CheckoutUrl), highlighted in the following example:

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

❌ Error: in case of error, the API returns the following message:

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

Creating payment in installments

Checkout Cielo allows merchants to carry out credit transactions in up to 12 installments.

Important: Checkout is limited to up to 12 installments, even if your Cielo membership supports higher amounts. If the value shown in Configurações da loja on the Cielo website is less than 12, contact Cielo Support and check your Affiliation configuration.

In this option, the merchant can configure the number of installments per sale. Checkout calculates installments considering the total value and limit of installments sent via API.

Attention: The number of desired installments must be less than the quantity registered in Configurações da loja (merchant settings) on the Cielo website.

Characteristics

• The merchant sends the maximum number of installments he wishes to display to the shopper;
• The shipping cost is added to the installment payment.

Installments via API are carried out by sending the MaxNumberOfInstallments field within the Payment node. This will force Checkout to recalculate the installment amount. Below is an example of the node:

"Payment": {
  "MaxNumberOfInstallments": 3
}

Applying discounts

Checkout Cielo allows the store to apply specific discounts to both the cart and payment methods. The discounts available at Checkout Cielo are:

Note: You can apply discounts via API or Cielo website. If a discount value is sent on the API, this will be the value considered, even if the Cielo website has another value registered.

Discount in cart

To send a discount on the cart, simply send the Discount node within the Cart node:

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

Discount by payment method

To send a discount on the invoice and/or credit card send the corresponding field within the Payment node:

• BoletoDiscount for boleto;
• FirstInstallmentDiscount for credit card in only one installment.

Example

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

Defining shipping

Cielo Checkout allows you to define five shipping options in the Shipping.Type parameter.

Note: Options for multiple shipping in the Post Office category must be selected within Configurações da loja (merchant settings) on the Cielo website.

Check out the nodes that form the shipping information below:

• Shipping: base node. It is mandatory for integration via API. It defines the types of freight to be used

• Shipping.Address: shipping address information. Not required in the API contract, but we suggest that this data be sent if it has already been collected within the store environment. If they have not been collected, the payment page will display address fields for the shopper to fill out.

*Not required, but submission is recommended

• Shipping.Services: used for fixed shipping, such as shipping services contracted by the store.

Calculation of Correios shipping

Shipping calculation is done using the Correios API and can be of two types:

• Shipping with volume: requires the merchant to inform the dimensions of the package that will be sent with the goods;
• Shipping without volume: only considers the weight of the cart as the calculation basis for delivery.

To use shipping with volume, submit the Shipping.Measures node, following the integration rules via REST API.

• Shipping.Measures: indicates the package measurements.

To calculate shipping via the Correios, it is necessary to respect the measurements defined by the contract used by the merchant. For more information about the dimensions and weights allowed, we suggest that you validate the store contract in Termo de Condições de Prestação de Serviços de Encomendas Nacionais dos Correios (Term of Conditions for the Provision of National Correios Services)

Recurrence

Recurrence is an automatic scheduling process for credit transactions, that is, it is a transaction that will be repeated automatically, without the need for the shopper to access the transactional screen, in accordance with the rules defined at the time of scheduling.

If one of the transactions is not authorized, Checkout Cielo automatically retrys; for more details about automatic retry, see the Recurrence Retry section

Recurring transactions are ideal for business models that involve the concept of subscription, plan or monthly fee in their form of billing, such as:

• Schools;
• Gyms;
• Publishers;
• Hosting services.

The recurring transaction is not an installment transaction. The total value of the sale compromises the shopper’s credit card limit, regardless of the value of the initial installment.

Creating a recurring payment

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

• Interval: repetition pattern and time interval between each transaction. This time interval between transactions can be monthly, bimonthly, quarterly, semi-annual and annual;
• Closing date: date on which the recurrence process stops occurring.

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

Payment.RecurrentPayment

The shopper’s credit card data is stored securely at Cielo, allowing it to be reused in a recurring transaction. This data is not accessed by the retailer and this intelligence is controlled by Checkout Cielo.

Request

{
  "OrderNumber": "12344",
  "SoftDescriptor": "Name that will show up on the invoice",
  "Cart": {
    "Discount": {
      "Type": "Percent",
      "Value": 10
    },
    "Items": [
      {
        "Name": "Product name",
        "Description": "Product description",
        "UnitPrice": 100,
        "Quantity": 2,
        "Type": "Asset",
        "Sku": "Product Sku",
        "Weight": 200
      }
    ]
  },
  "Shipping": {
    "Type": "Correios",
    "SourceZipCode": "14400000",
    "TargetZipCode": "11000000",
    "Address": {
      "Street": "Delivery address",
      "Number": "123",
      "Complement": "",
      "District": "Delivery neighbourhood",
      "City": "Delivery city",
      "State": "SP"
    },
    "Services": [
      {
        "Name": "Shipping service",
        "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"
  }
}

Example: physical asset

If the product type is physical asset (Cart.Items.Type = “Asset”), the API requires the shipping type (Shipping.Type) to be sent.

If there is a recurrence node in the technical contract, it is required to send the type WithoutShipping, otherwise the following response will be presented:

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

Important: The recurrence is only created if the transaction is authorized. Regardless of capture or not, once authorized, the recurrence process begins.

Recurrence Retry

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

• Time interval between attempts: four days;
• Number of retries: four retries, one per day, for four calendar days from the day following the original unauthorized transaction.

Note: This process aims to obtain a positive response from the authorization process, preventing the retailer from losing the sale. The retry process generates duplicate orders within the Backoffice, as the original denied order will be displayed in the Orders list, along with the new authorized transaction.

Attention: The retry rule cannot be modified by the retailer.

It is possible to query and cancel recurring transactions on the Cielo website.

Changing recurrence data

To change recurrence data, access the Cielo website, where you can change:

• Activation: a recurrence can be activated or canceled;
• Interval: it is possible to modify the execution interval;
• Recurrence day: it is possible to modify the execution day of the recurring transaction.
  Access the Backoffice Checkout Cielo Tutorial for more information.

Transaction notifications

The transactional notification process occurs in two steps, which are transaction completion notification and status change notification.

*Notifications are sent to the URLs defined by the establishment in Merchant Settings and contain data on transactions carried out at Checkout.

It is worth noting that Checkout only carries out a notification when a transaction is considered complete, that is, the shopper has filled in all the details on the payment screen and clicked Finalizar (complete)

Example: The shopper accesses the payment link and chooses to pay via Pix. When you click Finalizar, Checkout generates the Pix key and sends the transaction completion notification to the merchant, which will have the “Pending” status. When the shopper makes the payment via Pix, the transaction will have the status “Paid” and Checkout will send a status change notification.

Characteristics of notifications

Notification URLs are webhooks that can receive a notification via POST or via JSON:

Notification format

In notifications supported by the Checkout API, the format sent is Form Data, broken down by the Content-Type header ‘x-www-form-urlencoded’.

Expected return

The store server must send the return HTTPStatus = 200 (OK) to the Checkout API, indicating that the notification was received and processed successfully.

IMPORTANT: If the registered URL returns an error or is unavailable, three new attempts will be made, with an interval of one hour between each POST.

If the notification is not received, it is possible to request a resend manually in Detalhes do pedido, by clicking on the arrow icon.

Transaction completion notification

It is the notification sent to the Notification URL and can be in POST or JSON format.

Notification via POST

Contains all transaction data, including merchant_order_number and checkout_cielo_order_number, which can be used for querying transactions

Example:

order_number: "40e00eefbf094763a147af713fa07ece",
amount: "5000",
checkout_cielo_order_number: "b9ab1956738d45cc88edf51d7d03b13e",
created_date: "02/02/2023 17:01:35", 
customer_name: "customer name", 
customer_phone: "2222222222", 
customer_identity: "12312312344", 
customer_email: "name@email.com.br", 
shipping_type: "5", 
shipping_price: "0", 
payment_method_type: "6", 
payment_installments: "1", 
payment_status: "1", 
test_transaction: "False", 
product_id: "0f48e580-d0a2-4e3b-a748-6704927f1725", 
product_type: "3", 
product_description: "123", 
nsu: "00339922"

See the description of transaction details in the Notification content section

Notification via JSON

Notification via JSON is a safer and more flexible method for making a query at Checkout Cielo. In this modality, the merchant receives the MerchantId and MerchantOrderNumber and a URL to perform a query (GET) against the Checkout Cielo database and access the details of the transaction.

Notification content via JSON

MerchantId: "799g0de8-89c3-5d17-c670-6b29d7f00175", 
MerchantOrderNumber: "1db9226geg8b54e6b2972e9b745b89c7", 
Url: "https://cieloecommerce.cielo.com.br/api/public/v1/orders/799g0de8-89c3-5d17-c670-6b29d7f00175 /1db9226geg8b54e6b2972e9b745b89c7"

*In other requests and responses it may be called OrderNumber.

The store server must send the return HTTP Status = 200 (OK) to the Checkout API, indicating that the notification was received and processed successfully.

Example of a URL query returned via JSON

Response

{
    "order_number": "1db9226geg8b54e6b2972e9b745b89c7",
    "amount": 101,
    "discount_amount": 0,
    "checkout_cielo_order_number": "65930e7460bd4a849502ed14d7be6c03",
    "created_date": "10-03-2023 14:38:56",
    "customer_name": "Test Test",
    "customer_phone": "11987654321",
    "customer_identity": "445556667",
    "customer_email": "shopper@email.com.br",
    "shipping_type": 1,
    "shipping_name": "Motoboy",
    "shipping_price": 1,
    "shipping_address_zipcode": "06455-030",
    "shipping_address_district": "Alphaville",
    "shipping_address_city": "Barueri",
    "shipping_address_state": "SP",
    "shipping_address_line1": "Alameda Xingu",
    "shipping_address_line2": "Apto 25",
    "shipping_address_number": "512",
    "payment_method_type": 1,
    "payment_method_brand": 1,
    "payment_maskedcreditcard": "482852******6856",
    "payment_installments": 1,
    "payment_status": 3,
    "tid": "10558590697J62OH9BPB",
    "test_transaction": "False"
}

See the description of the sale details in the Notification content section.

Notification content

Whether notifying via POST or via JSON, the content of the data returned is the same. All returned fields are described below, as well as their definitions and sizes:

|PARAMETER|DESCRIPTION|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 the store.
If not sent, Checkout Cielo will generate a number that will be viewed by the consumer| alphanumeric
For reconciliation purposes, the characters allowed are only a-z, A-Z, 0-9. Special characters and whitespace are not allowed.|32
For reconciliation purposes, the maximum length is 20 characters.| |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 scree| 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| |first_installment_discount|Discount, in percentage, for payments by credit card.| Whole number from 1 to 100|3| |shipping_type|Shipping mode|numeric|1| | shipping_name| Shipping name| alphanumeric | 128| | shipping_price| Value of the shipping 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 method type code | numeric| 1| | payment_method_brand|Card brand (only for transactions with credit card payment method)| numeric| 1| | payment_method_bank| Issuer bank (For Automatic Debit and Boleto 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 Antifraude| numeric| 1| | payment_boletonumber| Number of boleto generated| string| 1| | payment_boletoexpirationdate | Due date for transactions made with boleto| numeric| 10| | payment_status|Transaction status| numeric| 1| | tid| TransactionId Cielo generated at the time of transaction authorization | alphanumeric | 20| | test_transaction| Indicates whether the transaction was generated with 'Test Mode' enabled | boolean| 32| |product_id|Identifier of the Payment Button/Link that generated the transaction|alphanumeric|36| |product_type|Type of Button that generated the order (See ProductID table)|alphanumeric|32| |product_sku|Product identifier registered in the payment link|text|16| |product_max_number_of_installments|Number of installments released by retailers for the payment link|number|2| |product_expiration_date|Button/Payment Link expiration date|alphanumeric|12| |product_quantity|Number of transactions remaining until the link stops working|alphanumeric|2| |product_description|Description of the payment link registered by the merchant|text|256| |nsu|NSU - Unique sequential number of the transaction.|alphanumeric|6| |authorization_code`|Authorization code.|alphanumeric|8|

ProductID types

Payment_status

Checkout has its own status, different from the Cielo website or the Cielo E-commerce API. See the full list at Payment_status.

Note: For order queries, the payment.status field will be returned in text format, always in English (Transaction Status column).

Payment_antifrauderesult

Antifraud has the concept of Status and SubStatus, where the former represents the level of risk that a transaction has of being a fraud, and the latter, additional information about the transaction.

Payment_method_type

Checkout only allows one type of Boleto per establishment, so the notification does not return whether the provider used was Bradesco or Banco do Brasil, as only one of them will be active in the affiliation.

Note: For queries, the type is returned in the Payment.Type field and is filled with the literal value (Description).

Payment_method_brand

Represents the card brand.

In queries, the card brand is returned in the Payment.Brand field and is filled in with the literal value.

Payment_method_bank

Shipping_type

Status change notification

It is sent to the status change URL and contains the checkout_cielo_order_number, the new status and some transaction data.

To find out more details about the transaction, make a query using checkout_cielo_order_number.

The status change notification format is POST (form data).

checkout_cielo_order_number: "b918afea483d4c6c8615d8a8e19803c1",
amount: "134",
order_number: "024f77ac98cb493b86d8c818eb6e79cd",
payment_status: "3",
test_transaction: "False",
brand: "Visa",
nsu: "000001",
authorization_code: "01234567"

Querying, capturing and cancelling

Querying transactions

Transaction queries via API can be made up to 45 days after the sale has been made.

The query must be made using the Transactional Control API, sending the access_token as authentication.

Order inquiries can be made by:

• order_number:is the MerchantOrderNumber returned in the transaction completion notification;
• checkout_cielo_order_number: is returned in the transaction completion notification or in the status change notification.

By order_number

Querying transactions by order_number returns a list of transactions with the same order number; This occurs because Checkout does not prevent the store from duplicating order_numbers. The response will return checkout_cielo_order_number, which must be used when querying a specific transaction.

Request

To query a transaction by order_number, do a GET.

Parameter in query string

Response

[
    {
        "$id": "1",
        "checkoutOrderNumber": "a58995ce24fd4f1cb025701e95a51478",
        "createdDate": "2023-03-30T12:09:33.57",
        "links": [
            {
                "$id": "2",
                "method": "GET",
                "rel": "self",
                "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/a58995ce24fd4f1cb025701e95a51478"
            }
        ]
    },
    {
        "$id": "3",
        "checkoutOrderNumber": "438f3391860a4bedbae9a868180dda6e",
        "createdDate": "2023-03-30T12:05:41.317",
        "links": [
            {
                "$id": "4",
                "method": "GET",
                "rel": "self",
                "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/438f3391860a4bedbae9a868180dda6e"
            }
        ]
    }
]

By Checkout_Cielo_Order_Number

Request

To query a transaction using Checkout_Cielo_Order_Number, simply perform a GET.

Header: Authorization: Bearer {access_token}

Parameter in query string

Response

{ 
    "merchantId": "c89fdfbb-dbe2-4e77-806a-6d75cd397dac", 
    "orderNumber": "054f5b509f7149d6aec3b4023a6a2957", 
    "softDescriptor": "Pedido1234", 
    "cart": { 
        "items": [ 
            { 
                "name": "Pedido ABC", 
                "description": "50 canetas - R$30,00 | 10 cadernos - R$50,00 | 10 Borrachas - R$10,00", 
                "unitPrice": 9000, 
                "quantity": 1, 
                "type": "1" 
            } 
        ] 
    }, 
    "shipping": { 
        "type": "FixedAmount", 
        "services": [ 
            { 
              "name": "Entrega Rápida", 
                "price": 2000 
            } 
        ], 
        "address": { 
            "street": "Alameda Xingu", 
            "number": "512", 
            "complement": "21 andar", 
            "district": "Alphaville", 
            "city": "Barueri", 
            "state": "SP" 
        } 
    }, 
    "payment": { 
        "status": "Paid", 
        "tid": "10127355487AK2C3EOTB",
        "nsu": "149111",
        "authorizationCode": "294551",
        "numberOfPayments": 1,
        "createdDate": "2023-03-02T14:29:43.767",
        "finishedDate": "2023-03-02T14:29:46.117",
        "cardMaskedNumber": "123456******2007",
        "brand": "Visa",
        "type": "creditCard",
        "errorcode": "00",
        "antifraud": { 
            "antifraudeResult": 1,
            "description": "Risco Baixo" 
        } 
    }, 
    "customer": { 
        "identity": "12345678911", 
        "fullName": "Nome do comprador", 
        "email": "exemplo@email.com.br", 
        "phone": "11123456789" 
    }, 
    "links": [ 
        { 
            "method": "GET", 
            "rel": "self", 
            "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/054f5b509f7149d6aec3b4023a6a2957" 
        }, 
        { 
            "method": "PUT", 
            "rel": "void", 
            "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/054f5b509f7149d6aec3b4023a6a2957/void" 
        } 
    ] 
}

Capturing transactions

Capturing consists of confirming an authorization that was previously carried out and is an exclusive procedure for credit card transactions.

The capture takes place after authorization, so that the sale can be completed and the card will be charged. Only after capture will the cardholder be able to view it on their statement or invoice.

Request

To capture a credit card transaction via Checkout_Cielo_Order_Number, simply perform a PUT.

Header: Authorization: Bearer {access_token}

Total Capture

It is the capture of the total value of the transaction.

Partial Capture

It is the capture of part of the transaction value. It can only be performed once.

Note: Partial capture can only be performed once and is exclusive to credit cards.

Response

{
  "success": true,
  "status": 2,
  "returnCode": "6",
  "returnMessage": "Operation Successful",
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/a9d517d81fb24b98b2d16eae2744be96"
    },
    {
      "method": "PUT",
      "rel": "void",
      "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/a9d517d81fb24b98b2d16eae2744be96/void"
    }
  ]
}

Canceling transactions

To cancel a transaction using Checkout_Cielo_Order_Number, simply perform a PUT.

For cancellation requests for the same transaction, it is necessary to wait a period of 5 seconds between one request and another, so that the balance can be consulted, the amount reserved in the financial calendar and the balance raised, avoiding duplication of cancellation. This rule applies to total and/or partial cancellations.

To identify that cancellation requests are from the same transaction, we consider the EC number, cancellation authorization number, sale date, sale value and NSU.

Important: To make any cancellation request, the establishment must have a sufficient balance in the transaction/book.

Request

Header: Authorization: Bearer {access_token}

Full cancellation

It is the cancellation of the total value of the transaction.

Partial Cancellation

It is the cancellation of part of the transaction value. It can be done more than once, until the total amount is cancelled.

Attention: Partial cancellation can only be carried out after capture. Partial cancellation can be carried out numerous times until the total amount is cancelled.

Response

{
  "success": true,
  "status": 2,
  "returnCode": "6",
  "returnMessage": "Operation Successful",
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/a9d517d81fb24b98b2d16eae2744be96"
    },
    {
      "method": "PUT",
      "rel": "void",
      "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/a9d517d81fb24b98b2d16eae2744be96/void"
    }
  ]
}

Status and codes

Payment_status

Checkout has its own status, different from the Cielo website or the Cielo E-commerce API. See the complete list below.

Note: For order queries, the payment.status field will be returned in text format, always in English (Transaction Status column).

Card Brands Retry Program

When a person tries to make a purchase with a card in e-commerce, the transaction may be denied due to a series of factors. The following attempts to complete the transaction using the same card are what we call a retry.

How does ​​it work?

Denied transactions are classified as:

• Irreversible: when retrying is not allowed;
• Reversible: when retrying is permitted according to the rules of each card brand.

Retries may be charged by the brand and the number of times a transaction can be retried before being charged also varies depending on the brand.

To check the retry rules for each card brand, access the manual Card Brands Retry Program.

ABECS return codes

The Brazilian Association of Credit Card and Services Companies (ABECS) is responsible for standardizing the return code for denied sales authorizations for both physical and e-commerce payment solutions in the Brazilian market.

To see the complete list of return codes for denied transactions, access ABECS return codes.

Cielo Support

Cielo provides technical support 24 hours a day, 7 days a week in Portuguese and English, at the following contacts:

• Email: cieloecommerce@cielo.com.br
• +55 4002-5472 (capitals and metropolitan regions)
• +55 0800 570 8472 (other locations)
• +55 11 2860-1348 (international)
  • Option 5 (E-commerce Support)