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:
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:
- The store’s registration must be active with Cielo;
- A timeout needs to be defined in HTTP requests to Cielo. We recommend 30 seconds;
- The Root certificate of the certifying entity (CA) of our Web Service must be registered. See the section Extended Validation Certificate for more information.
- 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:
- The shopper chooses the products in the store integrated into Checkout Cielo and clicks on Buy;
- The merchant sends the checkout page creation request to the Cielo Checkout API;
- 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); - The store redirects the buyer to the URL returned by Cielo (checkout page). The screen shown is part of the Cielo secure payment environment;
- The shopper chooses the payment method, type of shipping and delivery address on the checkout page;
- 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);
- The merchant will be notified about the status of the transaction (if the store has configured a notification URL on the Cielo website);
- 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
andClientSecret
, see the Obtaining Credentials topic, below.
Obtaining credentials
To obtain the ClientId
and ClientSecret
credentials, follow the steps below:
- After receiving the establishment number (EC) with authorization for Checkout, access the Cielo website and login;
- Go to Ecommerce > Checkout > Configurações > Dados Cadastrais;
- 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;
- Click on Gerar Credenciais de Acesso às APIs;
- 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:
- Concatenate the
ClientId
andClientSecret
,**ClientId:ClientSecret**
; - Encode the result in Base64;
- 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. Theaccess_token
has a validity of 20 minutes (1200 seconds) and it is necessary to generate a new token every time the validity expires.
Extended Validation Certificate
What is SSL Certificate?
The SSL Certificate for web server offers authenticity and integrity of web site data, giving customers of virtual stores the guarantee that they are actually accessing the web site they want, not a fraudster web site.
Specialized companies are responsible for domain validating and, depending on the type of certificate, they are also responsible for the validation of the entity that owns the domain.
Internet Explorer
Firefox
Google Chrome
What is EV SSL Certificate?
The EV Certificate has been recently released on market and ensures a higher level of security for virtual stores customers.
It is a certificate of greater confidence and when https is accessed the address bar will turn green, giving more reliability for site visitors.
How to install the Extended Validation Certificate on the Store server?
Just install the following three files in the server Trustedstore. Cielo does not offer support to the installation of the Certificate. If you are unsure about how to install the EV Certificate, then you should contact your server vendor support.
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”:
In “Firefox”, click on “Open Menu” menu and go to “Advanced” and “Options”:
In “Chrome”, click on “Customize and Control Google Chrome” and go to “Settings” and “Show advanced settings … “Change Proxy Settings and “Content” and Certificates:
Step 3
In Internet Explorer, under “Certificates”, click on “Import”.
In Firefox, click on “View Certificates”, click on “Import”
In Chrome, click on “Manage Certificates”, click on “Import”
Step 4
In Internet Explorer and Chrome “Certificate Import Wizard”, click on “Next”.
In Firefox “Servers Tab”, click on “Import”
Step 5
In Chrome and Internet Explorer “Certificate Import Wizard”, click on “Search”, look for the folder where the files are and select the file “cieloecommerce.cielo.com.br.crt, click on “Open” and then “Next”.
Step 6
Select the desired option: add the Certificate in a default folder or search for the folder of your choice.
Step 7
Click on “Finish”.
Step 8
Click on “Ok” to complete the import.
The Certificate may be viewed in the default tab “Other People” or at the one chosen by the customer.
Step 9
Repeat the same procedure for the 3 sent files.
Integrating Checkout Cielo
This documentation describes all the features of the API Checkout Cielo integration, technical parameters and especially the examples of codes to facilitate their development.
There are two ways to achieve integration:
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 - Flowchart
After the card carrier (custumer) select their purchases and hit the “Buy” button of a shop already integrated with Checkout Cielo, the flow in this order:
- The Cielo API returns the CheckoutURL, which is the URL of the transactional screen assembled based on the data sent by the Merchant/Button.
- The store redirects the customer to the URL returned by Cielo. The screen shown is part of the Cielo safe payment environment.
- The carrier chooses: Means of payment , freight type and delivery address on the transactional screen
- 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.
- If the store has a notification URL, it will be notified about the status of the transaction.
- 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.
- The store processes the purchase order using the notification POST data and, if the transaction is authorized, releases the order.
NOTE: The Checkout Cielo does not notify buyers about purchasing status, only the merchant does. This is because it allows the merchant to decide when and how to inform their customers about the delivery deadline and shipping process
Checkout Cielo test mode
Checkout Cielo test mode is a tool that allows to test the integration of your web site with the platform. With the test mode, you can perform transactions as you evolve with integration, and you can simulate scenarios to test different means of payment.
Activating test mode
The test mode can be activated in the Settings tab, where there is a checkbox that, when checked, enable the Checkout Cielo test mode. The test mode will only start when the selection is saved.
When the option is saved, a red stripe appears at the top of the screen. It will be displayed on all the screens of the Backoffice Cielo Checkout and on the Checkout Cielo transaction screen.
This stripe indicates that your Checkout Cielo store is now operating in a test environment, i.e. any transaction performed in that mode will be considered as a test.
Backoffice | Transacional |
---|---|
![]() |
![]() |
How to transact in Test Mode
Performing transactions in test mode occurs normally. Transaction information is sent via POST or API, using the parameters as described in the Integration by API topic, however, the payment means to be used are simulated media.
To perform test transactions with different payment means, follow these rules:
A - Transactions with Credit cards:
To test credit cards it is necessary for two important data to be defined, the authorization status of the card and the return of the fraud analysis.
Credit Card Authorization Status
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 |
- Example: Unauthorized Status.
- Customer name: Maria Pereira
D - Test Transactions
All transactions performed in test mode will be displayed as normal transactions in the Checkout Cielo Orders tab, however, they will be marked as test transactions and will not be accounted for in conjunction with transactions performed outside of the test environment.
These transactions will have the test symbol differentiating them from their other transactions. They can be captured or canceled using the same procedures of the actual transactions.
SDKs and POSTMAN
Checkout Cielo has a unique test POSTMAN collection with all the parameters and options described in this manual. Just access our Tutorial for information on using the tool.
In postman it is possible to create examples of its integration in:
- PHP
- RUBY
- C#
- JAVA
- PYTHON
- SHELL
Integration by API
This type of integration must be used whenever there is a “shopping cart” to be sent, i.e. in case the customer browses the web site and choose 1 or more products to add to a cart and then finalize the sale.
If you do not have a shopping cart implemented, see the Checkout Cielo Integration via Button section.
Below, it is demonstrated how the purchase flow occurs in the integration via API:
Creating the Cart
In integration via API, the transactional screen is “assembled” with bases in sent data that form a Shopping cart. These data are separated into the following “main nodes”:
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:
- Response - Transactional screen - It is the Response returned with data to send the buyer to the transactional screen
- Response - Transaction Finished - Contains data on the result of the transaction, after the buyer clicks “Finish” on the transaction screen. It is returned only via Notification
Transaction Result/Status: To get the transaction status return, it is necessary to set a NOTIFICATION URL. See the notification session for more information..
Response - Transactional screen
There are only two response options in API integration: Success / Error
Success: In case of success, the response will be the content of the Request plus the Link that directs the transactional screen
SUCCESS
{
"Settings": {
"CheckoutUrl": "https://cieloecommerce.cielo.com.br/transacional/order/index?id=123",
"Profile": "CheckoutCielo",
"Version": 1
}
}
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”
- Types of “Freight”
Types of “Discount”
Checkout Cielo allows the merchant to apply specific discounts for both cart and payment means. The discounts available at Checkout Cielo are:
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 |
---|---|
![]() |
![]() |
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 |
---|
![]() |
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 |
![]() |
Free |
![]() |
WithoutShippingPickUp |
![]() |
WithoutShipping |
![]() |
Post office |
![]() |
NOTE: The options for multiple freights in the category Post office
should be selected within the Backoffice Cielo.
The nodes that compound the freight information below:
- Shipping - Base node. It is equired on integration via API. It defines the types of freight to be used
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:
- Shipping with Volume - Uses the post office API, but requires the store to send the dimensions of the package to be shipped with the goods
- Freight without Volume - Uses the Post Office API, but only considers cart weight as the basis for calculating the delivery.
To use volumetric freight, just send the Shipping.Measures
node, following the integration rules via API REST.
Shipping.Measures
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 | It is an HTML code that when pasted into a website, will direct the buyer to the transactional screen - Ideal for use in hotSites or Marketing E-mail |
![]() |
QRCODE | Code interpretable by Smartphones and Tablets - Ideal for use in Printed Marketing or Digital |
http://bit.ly/2tRkSxZ |
LINK | is a shareable link, ideal for use in Social networks or Messengers Mobile |
This integration model is used to:
- Associate a direct quick purchase to a product as a promotion on a homepage by jumping the cart step.
- Send an e-mail marketing, or a charge via e-mail.
- Add the button (HTML) for the product/service to be purchased/paid.
- Perform payments sending by mobile applications
- Whenever you want to provide a quick sale.
To use this feature, it is necessary to register the product you want to sell, their information, and then just copy the source code generated for this button. The inclusion of products is done within the Backoffice Cielo Checkout, in the Products/Register Product menu.
Button Features
Each button has a unique code that only allows to buy that particular product in the conditions of price and registered freight. Therefore, a fraudster can not change any of this information when submitting to the purchase, because Checkout Cielo will collect all the product data in the register of the Backoffice Cielo Checkout, and will be worth the register data.
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:
Creating the Button
To use this feature, it is necessary to register the product you want to sell, their information, and then just copy the source code generated for this button. The inclusion of products is done within the Backoffice Cielo Checkout, in the Products/Register Product menu.
Registration Screen:
Registered Button:
Below the list of items that must be registered for the button creation:
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 AND LINK - The link and the QRCODE has the same behavior as the button, leading to the same transactional screen.
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.
- Link - is a shortened url that can be sent via social networks. Very practical for access via computers!
- QR Code - is an image that when read by a device with QR code reader (an APP on the cell phone for example), takes the buyer to the payment screen. Great for printed advertising!
- Button - is an Image embedded in HTML code to use in a web site. Very good if you own a web site, but does not want to deal with creating carts or payment streams. Put on your web site and that’s all, the button takes the buyers to the payments screen
The LQB is available when you register a cart in Checkout Cielo’s backoffice. Just follow the path below:
Merchant access on Cielo web site > Online Sales > Checkout Cielo > ABA: Products >. Register products
That’s it! After registering you already have a LQB waiting to be used!
Here’s an example of use:
- Link + Recurrence:
The PagBras company holds a birthday party with their employees every month, watered by soft drinks and snacks, provided by the company itself, which they say are very good!
One day the employees decided to carry out a “crowdfunding” and contribute monthly to make the variety of snacks and drinks bigger, so they could do theme parties such as Christmas, for example.
What did they do? Being an attuned company that did not want to use a little box every month to collect the monthly contribution, one of the employees created a recurrence via LQB, and in a company Facebook group, posted the payments link.
Today, employees contribute monthly without having to remember to pay, once the Checkout Cielo Recurrence performs a new billing transaction every month!
Payment methods flow
Credit card
Checkout Cielo allows the use of Credit Cards of the main national and international issuers. This means of payment is automatically released with Cielo affiliation, and can be used initially with the Checkout integration.
Credit card transactions will be included in the Backoffice Cielo Checkout as PENDING, AUTHORIZED, PAID, DECLINED, EXPIRED OR CHARGEBACK depending on the result of the authorization with the Bank.
Credit Card Order of Status:
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:
You can view the anti-fraud status by going to the purchase detail in the Orders tab and clicking on (+)
Debit card
Checkout Cielo allows the use of MasterCard and Visa Debit cards. This means of payment is automatically released with Cielo affiliation and can be used initially with the Checkout integration.
Supported Banks:
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
- Pending - Original status. The transaction is occurring, awaiting response from the bank to send the buyer to the authentication environment
- Not finished - Intermediate status. At this point Checkout Cielo expects the Bank to confirm the status of the authentication and transaction. If the buyer leaves the bank environment, the status does not change.
- Paid - Buyer successfully completed debit card payment.
- Not authorized - The Buyer did not present an account balance to finalize the transaction.
NOTE: The Cancell option within the backoffice, will modify the status of the PAID/NOT PAID transaction to CANCELED, but will have no effect on the banking movement. It will be up to the merchant to return the value to the buyer
Pix
What is Pix?
Pix is a Brazilian instant payment method, created by Banco Central (BC), in which resources are transferred between accounts in a few seconds, at any time or day (including holidays and weekends).
In addition to increasing the speed of payments, Pix in Cielo offers several benefits:
- Improves the sales conversion rate;
- Increases security in transactions;
- It is integrated with Checkout Cielo, versatile and easy.
How to use Pix in Checkout Cielo?
You must enable the Pix payment method in your registration on the Cielo portal and in your store settings. In API integration, it is not necessary to send additional parameters.
Enabling Pix on the Cielo portal
To use Pix, your registration must be enabled with the Pix payment method. To confirm the qualification, access the Cielo portal and click on Meu Cadastro > Autorizações > Pix.
If Pix is not enabled in your registration, the accession screen will be displayed if your establishment (EC) is eligible; after completing the Pix accession process, it will be possible to use Pix at Checkout Cielo.
Enabling Pix in merchant settings
Also make sure Pix is enabled in your store settings. To do so, go to E-commerce > Checkout Cielo > Acessar > Configurações > Configurações da Loja. Scrolling down the page will show the means of payment available in your registration:
Once this is done, your e-commerce can now receive transactions with Pix at Checkout Cielo.
Bank slip
Checkout Cielo allows the use of Bradesco (Wallet 26 and SPS) and Banco do Brasil Bank slips (Wallet 17). This means of payment must be registered by Cielo Support to be made available in Backoffice Checkout.
Supported Banks:
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
- Pending - Original status. The transaction is occurring, awaiting response from the bank to send the buyer to the authentication environment
- Not Finished - Intermediate status. At this point, the Checkout Cielo expects the Bank to confirm the status of the authentication and transaction. If the buyer leaves the bank environment, the status does not change.
- Paid - Buyer successfully completed debit card payment.
- Not Authorized - The Buyer did not present an account balance to finalize the transaction.
NOTE: The Cancel option within the backoffice, will modify the status of the PAID/NOT PAID transaction to CANCELED, but will have no effect on the banking movement. It will be up to the merchant to return the value to the buyer
Online Debit
Checkout Cielo allows the use of Online Debit (Transfer between bank accounts) for buyers who have accounts at Bradesco and Banco do Brasil banks. This means of payment is released via registration with Support Cielo.
Upon accessing the transaction screen, the buyer will obtain by the payment via Online debit, and will be redirected to the banking environment for Authentication and Authorization.
Online debit transactions will be included in the Backoffice Cielo Checkout as PENDING, PAID, UNAUTHORIZED or NOT FINISHED, depending on the result of the authorization with the Bank.
Online debit - Order of Status
- Pending - Original status. The transaction is occurring, awaiting response from the bank to send the buyer to the authentication environment
- Not Finished - Intermediate status. At this point, the Checkout Cielo expects the Bank to confirm the status of the authentication and transaction. If the buyer leaves the bank environment, the status does not change.
- Paid - Buyer successfully completed debit payment.
- Not Authorized - The Buyer did not present an account balance to finalize the transaction.
NOTE: The Cancel option within the backoffice, will modify the status of the PAID/NOT PAID transaction to CANCELED, but will have no effect on the banking movement. It will be up to the merchant to return the value to the buyer
Payment Notifications
The process of transactional notification in Checkout Cielo occurs via the inclusion of an URL to where will be directed the data of the transactions performed on the platform. Note that Checkout only notifies when a transaction is considered completed i.e. the buyer has filled in all the payment screen data and clicked “Finish”.
Types of notification
Checkout Cielo has two types of notifications that the merchant can use according to their needs:
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:
- Must be static URLs
- Must have less than 255 characters
- Special characters are not supported
Setting up URLs
- Just access within the Backoffice the Settings Tabs
- At Store Settings, go to the Payments session
- Register the URLs and choose the type of Notification you want
Notification: POST
Notification via POST is based on sending a POST HTTP
when a transaction is performed. It is performed in two steps:
NOTIFICATION POST
- Occurs when the transaction is finalized. This POST has all the order data, including the initial STATUS of the transaction.STATUS CHANGE POST
- Occurs when a transaction has its STATUS changed - e.g.: “Authorized” > > > “Paid”
This flow is used by stores that do not yet perform transactions via API.
Below the Flow of a POST Notification
Return expected to send notification: HttpStatus = 200 (OK)
- Post received and processed successfully
IMPORTANT If the registered Notification URL
returns any error/is unavailable, *3 retries, with an interval of 1 hour between each POST will be performed.
If the POST is not received, it is possible to resend it manually, just access the order in question by the Backoffice and click on the Sending icon:
See description of notification items in the session “NOTIFICATION POST content”
Notification: JSON
Notification via JSON is a more secure and flexible method for the merchant to conduct a query in Chekcout Cielo.
This notification mode is based on a POST JSON
, where the merchant receives credentials so that a query (GET
) can be performed with the Checkout Cielo database.
It is performed in two steps:
NOTIFICATION POST
- Occurs when the transaction is finalized. It has the necessary Credentials transactional queries.TRANSACTIONAL QUERY
- With the query credentials, the merchant searches for sale data with Checkout Cielo
In JSON Notification, there is no difference between the Notification POST
and Status Change
. Whenever something occurs in the transaction, the merchant will receive a Notification POST
Below the Flow of a JSON Notification (Transaction Creation + Status Change)
JSON NOTIFICATION POST content:
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 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:
- Installment via backoffice - is the default installment method of Checkout. Each issuer has a installment configuration up to 12x. The Value of the Cart (Products + Freight) is equally divided by the number of parcels.
- Installment via API - The Merchant limits the number of installments to be displayed in the backoffice
NOTE: Checkout is limited to 12x installments, even if your Cielo affiliation supports higher values. If the value presented in your backoffice is lower than 12, contact Cielo Support and check the configuration of your Affiliation.
Installment via backoffice
In this mode, the merchant controls the maximum limit of installments that the store will perform by Backoffice Checkout. The installments Value is defined by accessing the Settings tab and changing the session Payments
NOTE: The Check Box must be marked for the payment means to be displayed on the transactional screen.
Features
- Available in Checkout Cielo integrations via API or Button;
- The total value of the items in the cart is summed and divided by the amount of installments of the merchant;
- The value of the purchase is always the same regardless of the number of parcels chosen by the buyer (There is no Interest charge);
- The value of the freight is added to the value of the installment;
- The “in cash” option is always available to the buyer.
- All transactions will have the same installment options.
Installment via API
In this option, the merchant can configure the amount of parcels per sale, specified via API request at the time of sending the transaction. Checkout calculates the installments by considering total value and limit of installments sent via API.
WARNING: In this installment option, the number of installments desired should be lower than the amount that is registered in the backoffice Checkout.
Features
- The merchant sends the maximum number of installments he wants to display to the buyer.
- The value of the freight is added to the value of the installment.
The Installment via API is performed by sending the MaxNumberOfInstallments
field inside the Payment node. This will force Checkout to recalculate the installment value.
Below is an example of the Node
"Payment": {
"MaxNumberOfInstallments": 3
}
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:
- Schools
- Gyms
- Publishers
- Hosting services
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
.
- Interval – repeat pattern and time interval between each transaction. This time interval between transactions can be: Monthly, Bimonthly, Quarterly, Biannual and Annual.
- Closing date – Date that the recurrence process no longer occurs.
"Payment": {
"RecurrentPayment": {
"Interval": "Monthly",
"EndDate": "2018-12-31"
}
Payment.RecurrentPayment
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:
WARNING: If a button is used after the registered “End Date”, the transaction will present an error displaying Oppss on the transaction screen. The Date can be edited in the editing screen of the button within “Product Details”
Retry of Recurrences
If one of the recurrence transactions is not authorized, Checkout Cielo performs the retry automatically, sending a new transaction, considering:
- Time interval between attempts: 4 days
- Number of retries: 4 (four), one per day, for 4 consecutive days from the day following the unauthorized original transaction.
NOTE: This process aims to maintain a positive response to the authorization process, preventing the merchant from losing the sale. The Retry Process generates duplicate orders within the Backoffice because the original order, the one declined, will be displayed in the Orders list, along with the new authorized transaction
WARNING:The retry rule can not be modified by the merchant.
Querying transactions
Recurrence transactions are available in Backoffice Checkout Cielo like the other sales of your store in the “ORDERS” tab (see image below).
The first transaction of the recurrence is a normal transaction, following the rules and preferences defined by the merchant in the Backoffice.
WARNING: The value and charge date of the recurring transactions will always be the same as the initial transaction. Scheduling starts automatically from the date the first transaction is authorized.
This screen shows the date that the 1st recurrence transaction was authorized and should be captured manually. The other recurrence transactions will always be captured automatically, regardless of whether the first transaction was captured or canceled. If the Customer has configured Automatic Capture, the recurrence capture will also be automatic.
WARNING: Only the 1st transaction is subjected to anti-fraud analysis
Recurrence Edition
Checkout Cielo allows the merchant to modify 3 recurrence data:
- Activation - A recurrence can be enabled or disabled. e.g.: Suspension of a signature for a period of 3 months; Just set the Recurrence as inactive.
- Interval - It is possible to modify the execution interval.
- Occurrence day - It is possible to modify the execution date of the recurring transaction.
The update is done exclusively via Backoffice Cielo.
Card Brands Retry Program
When a shopper tries to make a card purchase on e-commerce, the transaction may be denied due to several reasons. The next attempts to complete the transaction using the same card are called retrying.
How retrying works
The denied transactions were classified as irreversible (never retry) and reversible (retry allowed).
Th card brands determine if they will charge a fee for retrying and how many retry attemps are allowed before applying charges. The merchants who do not follow the card brand rules will be penalized by charging fees for exceeded transactions.
Please refer to Card Brands Retry Program manual to see each card brand rules.
ABECS return codes
The Brazilian Association of Credit Card and Services Companies (ABECS) establishes as of July 15, 2020, the standardization of the return codes for denied sales authorizations for both the in store and and e-commerce payment solutions of the Brazilian market.
Please refer to ABECS Return Codes table to get the complete list of return codes.
Cielo Support
After reading this manual, if any doubts remain (technical or not), Cielo provides technical support 24 hours a day, 7 days a week in languages (Portuguese and English), in the following contacts:
- +55 4002-5472 – Capitals and Metropolitan Regions
- +55 0800 570 8472 – Other Locations
- +55 11 2860-1348 – International Option 5 – E-commerce support;
- E-mail: cieloecommerce@cielo.com.br