API E-commerce Cielo

Overview

The purpose of this documentation is to guide the developer on how to integrate with API E-commerce Cielo, describing the features, methods to be used, listing information to be sent and received, and providing examples.

We recommend intermediate knowledge in web programming language, HTTP/HTTPS requests and JSON file manipulation are required to successfully deploy the E-commerce Cielo solution.

In this guide, you will find information on all operations available on API REST of API E-commerce Cielo. These operations must be performed using your credentials (Merchant ID and Merchant Key) in the respective environment endpoints

  SandBox Production
Requests https://apisandbox.cieloecommerce.cielo.com.br https://api.cieloecommerce.cielo.com.br/
Queries https://apiquerysandbox.cieloecommerce.cielo.com.br https://apiquery.cieloecommerce.cielo.com.br/

To perform an operation, combine the base URL of the environment with the URL of the desired operation and send it using the HTTP verb as described in the operation.

Download the tutorial to learn how to generate your MerchantId and MerchantKey credentials on Cielo portal.

Solution features

The API E-commerce Cielo solution of the E-commerce Cielo platform was developed with REST technology, which is market standard and also independent of the technology used by our customers. In this way, it is possible to integrate using the most varied programming languages.

To get examples in these languages, see our conversion tutorial Postman Tutorial

Among other features, the attributes that stand out most in the Cielo e-commerce platform:

Architecture

The model employed for the integration is quite simple since there are two URLs (endpoints):

To execute an operation:

  1. Combine the base URL of the environment with the URL of the desired operation. Eg.: https://api.cieloecommerce.cielo.com.br/1/sales/
  2. Send the request to the URL using the adequate HTTP method.
Method Description
POST The POST HTTP method is used in the creation of features or in sending information that will be processed. For example, creation of a transaction.
PUT ThePUT HTTP method is used to update an already existing feature. For example, capture or cancelation of a previously authorized transaction.
GET The GET HTTP method is used for querying already existing features. For example, transaction query.

All operations require the access credentials MerchantId and MerchantKey, which must be sent in the header (header) of the request.
Each request sent will return an HTTP Status Code, indicating whether it was carried out successfully or not.

Glossary

To facilitate understanding, we have listed below a short glossary with the main terms related to e-commerce and also to card and acquiring market:

Terms Description
Authentication Process to ensure that the shopper is actually who they claim to be (lawful carrier), usually occurs at the issuing bank using a digital token or card with security keys.
Authorization Process to check whether a purchase can or not be made with a card. At this point, several verifications are done with the card and the carrier (e.g., timely payments, card locks, etc.). It is also at this point that the card limit is checked with the transaction value.
Cancellation Process to cancel a purchase made with a card.
Capture Process that confirms an authorization that was previously made. It is only after the capture that the card carrier will be able to view it on their bank statement or invoice.
Shopper It is the one who makes the purchase at the virtual store.
Issuer (or issuing bank) It is the financial institution that issues the credit card, debit card or voucher.
Commercial establishment or CE Entity that responds by the virtual store.
Payment Gateway Company responsible for technical integration and transaction processing.
Carrier It is the person who carries the card at the time of sale.
TID (Transaction Identifier) Code consisting of 20 characters that identifies a Cielo e-commerce transaction.

Products and Supported Brands

The current version of Cielo Webservice supports the following issuers and products:

Issuer Demand credit Installment credit Store Debit Voucher International
Visa Yes Yes Yes No Yes
Master Card Yes Yes Yes No Yes
American Express Yes Yes No No Yes
Elo Yes Yes Yes No Yes
Diners Club Yes Yes No No Yes
Discover Yes No No No Yes
JCB Yes Yes No No Yes
Aura Yes Yes No No Yes
Hipercard Yes Yes No No No

Cielo Support

If you have any questions, feel free to contact us through our e-mail: cieloecommerce@cielo.com.br

Extended Validation Certificate

What is the SSL Certificate?

The SSL Certificate for web servers confirms the authenticity and integrity of the website data, giving customers of virtual stores the guarantee that they are actually accessing the website they want, not a fraudulent 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:

EV Internet Explorer Certificate

Firefox:

EV Firefox Certificate

Google Chrome:

EV Google Chrome Certificate

What is EV SSL Certificate?

The EV Certificate ensures a higher level of security for virtual stores customers.

It is a more trustworthy certificate and when HTTPS is accessed the address bar will turn green, showing more reliability for users.

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

You just have to install the following 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.

Installation tutorial

Installation on the Virtual Store Server

For the the step-by-step of the EV Certificate installation, you must contact your server vendor support.

Client Access to Virtual Store

Usually, the browser automatically updates the Certificate. If it does not and the client reaches out, the following steps must be informed:

Step 1:

Save these files below into a new folder, or into a folder that can be easily accessed, as it will be used later:

Step 2:

On Internet Explorer, click on Tools and go to Internet Options:

Install IE

On Firefox, click on Open Menu and go to Advanced > Options:

Install FF

On Google Chrome, click on Control Google Chrome and go to Settings > Show advanced settings… > Change Proxy Settings… > Content > Certificates:

Install GC

Step 3:

On Internet Explorer, under Certificates, click on *Import…:

Install IE

On Firefox, go on View Certificates, click on Import…:

Install FF

On Chrome, go on Manage Certificates…, click on Import:

Install GC

Step 4:

On Internet Explorer and Chrome, under Certificate Import Wizard, click on Next:

Install IE and GC

Install IE and GC

On Firefox, under Servers, click on Import…:

Install FF

Step 5:

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

Install IE and GC

Install IE and GC

Step 6:

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

Install IE and GC

Step 7:

Click on Finish.

Install IE and GC

Step 8:

Click on Ok to complete the import.

Install IE and GC

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

Install IE and GC

Step 9:

Repeat the same procedure for the 3 sent files.

Sandbox and Tools

About Sandbox

To facilitate testing during integration, Cielo offers a Sandbox environment that allows simuation of the API messages. The Sandbox environment is programmed to give you responses for every feature available on API E-commerce Cielo

INFORMATION URL
Access credentials MerchantId and MerchantKey obtained after creating your testing account on Sandbox Registration
Requests URL https://apisandbox.cieloecommerce.cielo.com.br
Queries URL https://apiquerysandbox.cieloecommerce.cielo.com.br

Perks of using Sandbox

Integration Tool

You can use Postman to test your integration, using the API E-commerce Cielo collection.

Collection

Importation link: https://www.postman.com/collections/7313fe78130211f5f009

Environment Endpoints
Sandbox Request: https://apisandbox.cieloecommerce.cielo.com.br
Query: https://apiquerysandbox.cieloecommerce.cielo.com.br/
Production Request: https://api.cieloecommerce.cielo.com.br/
Query: https://apiquery.cieloecommerce.cielo.com.br/

Environment

Download the Environment Production and Sandbox file and replace MerchantID and MerchantKeys with your store’s information.

Credit card in sandbox

With this payment method it is possible to simulate the flows of:

To make better use of a simulated payment, you can create a fake card number using a generator online or choosing random numbers. For either option, the first 15 digits can be random, but the last one should correspond to the transaction status you want to test.

The Security Code (CVV) and expiration date information may be random, keeping the format - CVV (3 digits) and Validity (MM/YYYY).

Final card digit Transaction Status Return Code Return Message
XXXX.XXXX.XXXX.XXX0
XXXX.XXXX.XXXX.XXX1
XXXX.XXXX.XXXX.XXX4
Authorized 4/6 Operation performed successfully
XXXX.XXXX.XXXX.XXX2 Not Authorized 05 Not Authorized
XXXX.XXXX.XXXX.XXX3 Not Authorized 57 Expired Card
XXXX.XXXX.XXXX.XXX5 Not Authorized 78 Blocked Card
XXXX.XXXX.XXXX.XXX6 Not Authorized 99 Time Out
XXXX.XXXX.XXXX.XXX7 Not Authorized 77 Canceled Card
XXXX.XXXX.XXXX.XXX8 Not Authorized 70 Problems with the Credit Card
XXXX.XXXX.XXXX.XXX9 Random Authorization 4 a 99 Operation Successful / Time Out

The test card 4024.0071.5376.3191, for example, would simulated a successful transaction.

To check the return codes in Production, check API Codes.

Debit card in sandbox

With this payment method, it is possible to simulate the flows of:

The debit transaction needs to be authenticated:

Option Status
Authenticated Authorized
Not Authenticated Denied
Do not use the URL Not Finished

Online Transfer: The same behavior of debit card in Sandbox is valid for debit card.

Other payment methods in sandbox

Other payment methods do not have cards or specific simulated data, as in the case of credit cards. Below we specify any existing differences:

Payment Method Orientations for Sandbox
Boleto To send a boleto transaction in the Sandbox environment you should put the Provider as Simulado.
There is no bank validation. The boleto behaves as a boleto without registration.
Alelo Use the same values from the request at the Production environment for Alelo Cards.
QR Code Use the same values from the resquest at the Production environment for QR Code. There is no bank conciliation.
Carnê Use the same values from the request at the Production environmnet for Carnê Transaction.
Electronic Transfer The Provider used should be “Simulado”.
The redirecting URL for the bank environment will be a screen for you to choose the status of the authentication.

Renova Fácil in Sandbox

To simulate a transaction with return for a new card, updated by our service Renova Fácil, follow the instructions below.

In the authorization request, besides the fields already mentioned for the used method of payment, you need the send the following:

Consulta BIN - Sandbox

A card’s BIN code is the first six digits of the card number. At the Consulta BIN simulation in the Sandbox environment, each one of the six digits will determine a simulated result.

It is possible to test different card numbers and observe the expected return according to the different options.

A card’s BIN code should return the card brand, the type of card, the nationality, if it is a corporate card, the return of the BIN analysis and the card issuer. To know more, read the Consulta BIN section of this guide.

Digit Meaning Return
1st digit Brand. If it’s ‘3’ it returns “AMEX
If it’s ‘5’ it returns “MASTERCARD
If it’s ‘6’ it returns “DISCOVER
Every other number returns “VISA”.
2nd digit Type of card If it’s ‘3’ it returns “Débito
If it’s ‘5’ it returns “Crédito
If it’s ‘7’ it returns “Crédito” and it returns the Prepaid field as “true
Any other number returns “Múltiplo”.
3rd digit Card nationality If it’s ‘1’ it returns “true” (national card)
Every other number other than ‘1’ returns “false” (international card).
4th digit If it’s a corporate card If it’s ‘1’ it returns “true” (it is a corporate card)
Every other number other than ‘1’ returns “false” (not a corporate card).
5th digit Analysis return If it’s ‘2’ it returns “01 - Bandeira não suportada
If it’s ‘3’ it returns “02 - Voucher - Não suportado na consulta de bins
Every other number returns “00 - Analise autorizada
6th digit Issuing bank If it’s ‘1’ it returns “104” and “Caixa
If it’s ‘2’ it returns “001” and “Banco do Brasil
Every other number returns “237” e “Bradesco

Example

A card with the number 4110110012341234 will return the following data:

Consulta BIN Sandbox

Request

curl
--request GET https://apiquerysandbox.cieloecommerce.cielo.com.br/1/cardBin/411011
--header "Content-Type: application/json"
--data-binary
--verbose

Response

{
  "Status": "00",
  "Provider": "VISA",
  "CardType": "Multiplo",
  "ForeignCard": false,
  "CorporateCard": false,
  "Issuer": "Banco do Brasil",
  "IssuerCode": "001"
}
curl
{
    "Status": "00",
    "Provider": "VISA",
    "CardType": "Multiplo",
    "ForeignCard": false,
    "CorporateCard": false,
    "Issuer": "Banco do Brasil",
    "IssuerCode": "001"
}
--verbose

Payment Methods

Credit and Debit Cards

Credit Cards

To enjoy all the features available in our API, it is important that you first understand the concepts around processing a credit card transaction.

Concept Description
Authentication The authentication process makes it possible to effective a sale, which will pass through the authentication process of the card issuing bank, then providing more security for the sale and transferring the risk of fraud to the bank.
Authorization The authorization (or pre-authorization) is the main operation in the eCommerce, because through it, the sale can be finished. Pre-authorization only sensitizes the customer’s limit, but still does not generate charge for the consumer.
Capture When making a pre-authorization, it is necessary to confirm it, so that the charge is effected to the card carrier. It is through this operation a pre-authorization is effected, and it can be executed normally within 5 days after the pre-authorization date.
Cancellation The cancellation is necessary when, for some reason, a sale will not be effected anymore.

Creating a credit card transaction

To create a credit card transaction, you need to send a request using the POST method, as shown. This example covers all the possible fields you can send; check which fields are required in the request properties table.

The transaction capture can be authomatic or posterior. For an authomatic capure, send the Payment.Capture field in the request as “true”. For a posterior capture, send the field as “false” and then do the capture request.

Warning: It is not possible to carry out a transaction with its value (Amount) as 0. To verify if a card is valid, use Zero Auth.

Mastercard credit card transactions with stored credentials: the Mastercard brand requires the Transaction Initiator Indicator for credit and debit card transactions using stored card data. The goal is to indicate if the transaction was initiated by the cardholder or by the merchant. In this scenario, the node InitiatedTransactionIndicator must be sent with the parameters Category and SubCategory for Mastercard transactions, within the Payment node. Please check the complete list of categories in the Category parameter description and the subcategories tables in Transaction Indicator Tables.

Please refer to Credit card with authentication to create an authenticated credit card transaction.

Request
{
  "MerchantOrderId": "2014111701",
  "Customer": {
    "Name": "Comprador crédito completo",
    "Email": "compradorteste@teste.com",
    "Birthdate": "1991-01-02",
    "Address": {
      "Street": "Rua Teste",
      "Number": "123",
      "Complement": "AP 123",
      "ZipCode": "12345987",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BRA"
    },
    "DeliveryAddress": {
      "Street": "Rua Teste",
      "Number": "123",
      "Complement": "AP 123",
      "ZipCode": "12345987",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BRA"
    },
    "Billing": {
      "Street": "Rua Neturno",
      "Number": "12345",
      "Complement": "Sala 123",
      "Neighborhood": "Centro",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BR",
      "ZipCode": "20080123"
    }
  },
  "Payment": {
    "Currency": "BRL",
    "Country": "BRA",
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": "ByMerchant",
    "Capture": true,
    "Authenticate": "false",
    "Recurrent": "false",
    "SoftDescriptor": "123456789ABCD",
    "CreditCard": {
      "CardNumber": "1234123412341231",
      "Holder": "Teste Holder",
      "ExpirationDate": "12/2030",
      "SecurityCode": "123",
      "SaveCard": "false",
      "Brand": "Visa",
      "CardOnFile": {
        "Usage": "Used",
        "Reason": "Unscheduled"
      }
    },
      "InitiatedTransactionIndicator": {
          "Category": "C1",
          "Subcategory": "Standingorder"
    },    
    "IsCryptoCurrencyNegotiation": true,
    "Type": "CreditCard",
    "Amount": 15700,
    "AirlineData": {
      "TicketNumber": "AR988983"
    }
  }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
   "MerchantOrderId":"2014111701",
   "Customer":{
      "Name":"Comprador crédito completo",
      "Identity":"11225468954",
      "IdentityType":"CPF",
      "Email":"compradorteste@teste.com",
      "Birthdate":"1991-01-02",
      "Address":{
         "Street":"Rua Teste",
         "Number":"123",
         "Complement":"AP 123",
         "ZipCode":"12345987",
         "City":"Rio de Janeiro",
         "State":"RJ",
         "Country":"BRA"
      },
        "DeliveryAddress": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "Billing": {
            "Street": "Rua Neturno",
            "Number": "12345",
            "Complement": "Sala 123",
            "Neighborhood": "Centro",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BR",
            "ZipCode": "20080123"
  },
   },
   "Payment":{
     "ServiceTaxAmount":0,
     "Installments":1,
     "Interest":"ByMerchant",
     "Capture":true,
     "Authenticate":false,
     "Recurrent":"false",
     "SoftDescriptor":"123456789ABCD",
     "CreditCard":{
         "CardNumber":"4551870000000183",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"123",
         "SaveCard":"false",
         "Brand":"Visa",
         "CardOnFile":{
            "Usage": "Used",
            "Reason":"Unscheduled"
         }
     },
      "InitiatedTransactionIndicator": {
          "Category": "C1",
          "Subcategory": "Standingorder"
    },     
     "IsCryptoCurrencyNegotiation": true,
     "Type":"CreditCard",
     "Amount":15700,
     "AirlineData":{
         "TicketNumber":"AR988983"
     }
   }
}
--verbose
Property Type Size Required Description
MerchantId GUID 36 Yes Store identifier in Cielo.
MerchantKey text 40 Yes Public Key for Double Authentication in Cielo.
Content-Type header 40 Yes application/json (required).
RequestId GUID 36 No Request identifier, used when the merchant uses different servers for each GET/POST/PUT.
MerchantOrderId text 50 Yes Order ID number.
Customer.Name text 255 No Customer’s name.
Customer.Status text 255 No The customer’s registration status on the store. (NEW / EXISTING).
Customer.Identity text 14 No Customer’s RG, CPF or CNPJ.
Customer.IdentityType text 255 No Customer’s type of identification (CPF/CNPJ).
Customer.Email text 255 No Customer’s e-mail.
Customer.Birthdate date 10 No Customer’s birth date (AAAA/MM/DD).
Customer.Address.Street text 255 No Customer’s address.
Customer.Address.Number text 15 No Customer’s address number.
Customer.Address.Complement text 50 No Customer’s address complement.
Customer.Address.ZipCode text 9 No Customer’s Zip Code.
Customer.Address.City text 50 No Customer’s address’ city.
Customer.Address.State text 2 No Customer’s address’ state.
Customer.Address.Country text 35 No Customer’s address’ country.
Customer.DeliveryAddress.Street text 255 No Customer’s delivery address.
Customer.Address.Number text 15 No Customer’s delivery address number.
Customer.DeliveryAddress.Complement text 50 No Customer’s delivery address complement.
Customer.DeliveryAddress.ZipCode text 9 No Customer’s delivery address Zip Code.
Customer.DeliveryAddress.City text 50 No Customer’s delivery address city.
Customer.DeliveryAddress.State text 2 No Customer’s delivery address state.
Customer.DeliveryAddress.Country text 35 No Customer’s delivery address country.
Customer.Billing.Street string 24 No Customer’s billing address.
Customer.Billing.Number string 5 No Customer’s billing address number.
Customer.Billing.Complement string 14 No Customer’s billing address complement.
Customer.Billing.Neighborhood string 15 No Customer’s billing address neighborhood.
Customer.Billing.City string 20 No Customer’s billing address city.
Customer.Billing.State string 2 No Customer’s billing address state.
Customer.Billing.Country string 2 No Customer’s billing address country. More information at ISO 2-Digit Alpha Country Code
Customer.Billing.ZipCode string 9 No Customer’s billing address Zip Code.
Payment.Type text 100 Yes Type of the payment method.
Payment.Amount number 15 Yes Order Amount (to be sent in cents).
Payment.Currency text 3 No Currency in which the payment will be made (BRL).
Payment.Country text 3 No Country in which the payment will be made.
Payment.Provider text 15 Defines the behavior for the payment method/NOT REQUIRED FOR CREDIT.
Payment.ServiceTaxAmount number 15 No Appliable only to airline companies. Order amounth that will be destined to service tax. PS.: This amount is not added to the authorization amount.
Payment.SoftDescriptor text 13 No The store’s name that will be on the shopper’s bank invoice. Does not allow special characters.
Payment.Installments number 2 Yes Number of installments. If the transaction is a recurrence, the number of installments will be 1. For installment transactions, the number of installments will be greater than 1.
Payment.Interest text 10 No Type of installments - Store (ByMerchant) or Card (ByIssuer).
Payment.Capture boolean No (Default false) Boolean that identifies if the authorization should be done by Authomatic capture (true) or posterior capture (false).
Payment.Authenticate boolean No (Default false) Defines if the shopper will be directed to the issuing bank for a card authetication.
Payment.Recurrent boolean - Conditional Indicates if the transaction is recurring (“true”) or not (“false”). The value “true” won’t originate a new recurrence, it will only allow a transaction without the need to send the security code. Authenticate should be “false” if Recurrent is “true”. Find out more about Recurring Payments.
Payment.IsCryptocurrencyNegotiation boolean - No (default false) Should be send as “true” if the transaction is to sell or buy criptocurrency.
Payment.AirlineData.TicketNumber alphanumeric 13 No Inform the number of the main airline ticket of the transaction.
Payment.CreditCard.CardNumber text 19 Yes Shopper’s card number.
Payment.CreditCard.Holder text 25 No Name of the shopper that’s printed on the card. Does not accept special characters.
Payment.CreditCard.ExpirationDate text 7 Yes Expiration date printed on the card. Example: MM/AAAA.
Payment.CreditCard.SecurityCode text 4 No Security code printed on the back of the card.
Payment.CreditCard.SaveCard boolean No (Default false) Boolean that identifies if the card will be saved to generate a CardToken. Find out more about Tokenization of Cards.
Payment.CreditCard.Brand text 10 Yes Card brand. Possible values: Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard / Hiper.
Payment.CreditCard.CardOnFile.Usage text - No First if the card was stored and it’s your first use.
Used if the card was stored and has been used for another transaction before. Find out more about Card On File.
Payment.CreditCard.CardOnFile.Reason text - Conditional Indicates the motive for card storage, if the “Usage” field is “Used”.
Recurring - Programmed recurring transaction (e.g. Subscriptions). If it is a recurring transaction, use Payment.Recurrent = true (merchant recurrence) or Recurrent.Payment = true (scheduled recurrence).
Unscheduled - Recurring transaction with no fixed date (e.g. service apps)
Installments - Installments through recurring transactions. Get more information on the topic Card On File
Payment.InitiatedTransactionIndicator.Category string 2 Conditional. Required only for Mastercard. Transaction Initiator Indicator category. Valid only for Mastercard.
Possible values:
- “C1”: transaction initiated by the cardholder;
- “M1”: recurring payment or installment initiated by the merchant
- “M2”: transaction initiated by the merchant.
Payment.InitiatedTransactionIndicator.Subcategory string - Conditional. Required only for Mastercard. Transaction Initiator Indicator subcategory. Valid only for Mastercard. Please refer to the Transaction Initiator Indicator tables for the full list.
Response
{
  "MerchantOrderId": "2014111706",
  "Customer": {
    "Name": "Comprador crédito completo",
    "Identity": "11225468954",
    "IdentityType": "CPF",
    "Email": "compradorteste@teste.com",
    "Birthdate": "1991-01-02",
    "Address": {
      "Street": "Rua Teste",
      "Number": "123",
      "Complement": "AP 123",
      "ZipCode": "12345987",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BRA"
    },
    "DeliveryAddress": {
      "Street": "Rua Teste",
      "Number": "123",
      "Complement": "AP 123",
      "ZipCode": "12345987",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BRA"
    },
    "Billing": {
      "Street": "Rua Neturno",
      "Number": "12345",
      "Complement": "Sala 123",
      "Neighborhood": "Centro",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BR",
      "ZipCode": "20080123"
    }
  },
  "Payment": {
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": "ByMerchant",
    "Capture": true,
    "Authenticate": false,
    "CreditCard": {
      "CardNumber": "455187******0183",
      "Holder": "Teste Holder",
      "ExpirationDate": "12/2030",
      "SaveCard": false,
      "Brand": "Visa",
      "PaymentAccountReference": "92745135160550440006111072222",
      "CardOnFile": {
        "Usage": "Used",
        "Reason": "Unscheduled"
      }
    },
      "InitiatedTransactionIndicator": {
          "Category": "C1",
          "Subcategory": "Standingorder"
    },    
    "IsCryptoCurrencyNegotiation": true,
    "TryAutomaticCancellation": true,
    "ProofOfSale": "674532",
    "Tid": "0305020554239",
    "AuthorizationCode": "123456",
    "SoftDescriptor": "123456789ABCD",
    "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
    "Type": "CreditCard",
    "Amount": 15700,
    "CapturedAmount": 15700,
    "Country": "BRA",
    "AirlineData": {
      "TicketNumber": "AR988983"
    },
    "ExtraDataCollection": [],
    "Status": 2,
    "ReturnCode": "6",
    "ReturnMessage": "Operation Successful",
    "MerchantAdviceCode": "1",
    "Links": [
      {
        "Method": "GET",
        "Rel": "self",
        "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
      },
      {
        "Method": "PUT",
        "Rel": "void",
        "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
      }
    ]
  }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2014111706",
    "Customer": {
        "Name": "Comprador crédito completo",
        "Identity":"11225468954",
        "IdentityType":"CPF",
        "Email": "compradorteste@teste.com",
        "Birthdate": "1991-01-02",
        "Address": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "DeliveryAddress": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "Billing": {
            "Street": "Rua Neturno",
            "Number": "12345",
            "Complement": "Sala 123",
            "Neighborhood": "Centro",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BR",
            "ZipCode": "20080123"
  },
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": true,
        "Authenticate": false,
        "CreditCard": {
            "CardNumber": "455187******0183",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa",
            "PaymentAccountReference":"92745135160550440006111072222",
         "CardOnFile":{
            "Usage": "Used",
            "Reason":"Unscheduled"
         }
        },
        "InitiatedTransactionIndicator": {
          "Category": "C1",
          "Subcategory": "Standingorder"
    },        
        "IsCryptoCurrencyNegotiation": true,
        "TryAutomaticCancellation":true,
        "ProofOfSale": "674532",
        "Tid": "0305020554239",
        "AuthorizationCode": "123456",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "CreditCard",
        "Amount": 15700,
        "CapturedAmount": 15700,
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 2,
        "ReturnCode": "6",
        "ReturnMessage": "Operation Successful",
        "MerchantAdviceCode":"1",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
Property Description Type Size Format
ProofOfSale Authorization number, identical to NSU. text 6 Alphanumeric text
Tid Transaction Id on the acquirer. text 20 Alphanumeric text
AuthorizationCode Authorization code. text 6 Alphanumeric text
SoftDescriptor Text that will be printed on the carrier’s bank invoice. Does not allow special characters. text 13 Alphanumeric text
PaymentId Payment ID number, needed for future operations like Consulting, Capture and Cancellation. GUID 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ECI Eletronic Commerce Indicator. Indicates how safe a transaction is. text 2 Examples: 7
Status Transaction status. Check out the complete Transactional status codes table. byte 2
ReturnCode Acquiring return code. text 32 Alphanumeric text
ReturnMessage Acquiring return message. text 512 Alphanumeric text
Payment.MerchantAdviceCode Card brand’s return code that defines the period for transaction submission retry. Valid only for Mastercard. See more at Mastercard retry program text 2 Number
TryAutomaticCancellation In case of error during authorization (status “Not Finished - 0”), the response will include the “tryautomaticcancellation” field as “true”. In this case, the transaction will be automatically queried, and if it has been authorized successfully, it will be canceled automatically. This feature must be enabled for establishment. To enable, please contact our technical support. boolean - true ou false
Payment.CreditCard.PaymentAccountReference PAR (payment account reference) is the number that associates different tokens to the same card. It will be returned by the Master and Visa brands and passed on to Cielo e-commerce customers. If the card brand doesn’t send the information the field will not be returned. alphanumeric 29

Debit cards

This payment method is automatically released along to the Cielo’s affiliation.

Every debit transaction should be authenticated by demand of the issuing banks and card brands, to ensure better safety.

To authenticate a debit transaction, we use the EMV 3DS 2.0 protocol; this protocol is a script integrated to your e-commerce that verifies the identity of the shopper while keeping a positive shopping experience and reducing the risk of fraud.

To integrate the authentication method, check the 3DS 2.0 documentation.

Debit without authentication: or “debit without password”, can only be done when the e-commerce has the issuing bank’s authorization to dismiss the authentication. In case you have that permission, send the field Authenticate as “false” in the standard request for debit card.

Creating a debit transaction

To sell with a debit card, you should request using the POST method. The example below shows the minimum necessary fields that should be sent for the authorization.

Mastercard debit transactions with stored credentials: Mastercard requires the submission of the Transaction Initiator Indicator for credit and debit card purchases that use a card’s stored data. The objective is to indicate whether the transaction was initiated by the shopper (Cardholder-Initiated Transaction - CIT) or by the e-commerce (Merchant-Initiated Transaction - MIT). In this scenario, it is mandatory to send the InitiatedTransactionIndicator node with the Category and SubCategory parameters for Mastercard transactions, within the Payment node. Check out the list of categories in the Category parameter description and the full table of subcategories in Mastercard Transaction Initiator.

Attention: It is not possible to carry out a transaction with an amount (Amount) 0. To check the validity of a card, use Zero Auth.

In the standard debit transaction (with authentication), send Authenticate = “true”.

Request
{
  "MerchantOrderId": "2014121201",
  "Customer": {
    "Name": "Comprador Cartão de débito"
  },
  "Payment": {
    "Type": "DebitCard",
    "Authenticate": true,
    "Amount": 15700,
    "DebitCard": {
      "CardNumber": "5551870000000181",
      "Holder": "Teste Holder",
      "ExpirationDate": "12/2030",
      "SecurityCode": "123",
      "Brand": "Master"
    },
    "ExternalAuthentication": {
      "Cavv": "AAABB2gHA1B5EFNjWQcDAAAAAAB=",
      "Xid": "Uk5ZanBHcWw2RjRCbEN5dGtiMTB=",
      "Eci": "5",
      "Version": "2",
      "ReferenceID": "a24a5d87-b1a1-4aef-a37b-2f30b91274e6"
    },
  }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
   "MerchantOrderId":"2014121201",
   "Customer":{
      "Name":"Comprador Cartão de débito"
   },
   "Payment":{
      "Type":"DebitCard",
      "Authenticate":true,
      "Amount":15700,
      "DebitCard":{
         "CardNumber":"5551870000000181",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"123",
         "Brand":"Master"
      },
      "ExternalAuthentication":{
         "Cavv":"AAABB2gHA1B5EFNjWQcDAAAAAAB=",
         "Xid":"Uk5ZanBHcWw2RjRCbEN5dGtiMTB=",
         "Eci":"5",
         "Version":"2",
         "ReferenceID":"a24a5d87-b1a1-4aef-a37b-2f30b91274e6"
      },      
   }
}
--verbose
Property Description Type Size Required
MerchantId Store identifier in API E-commerce Cielo. Guid 36 Yes
MerchantKey Public Key for Double Authentication in API E-commerce Cielo. Text 40 Yes
RequestId Request Identifier, used when the merchant uses different servers for each GET/POST/PUT. Guid 36 No
MerchantOrderId Order Identifier field at the e-commerce. Text 50 Yes
Customer.Name Shopper’s name. Text 255 No
Customer.Status Shopper registration status in store (NEW / EXISTING) - Used for fraud analysis Text 255 No
Payment.Type Type of the payment method. Text 100 Yes
Payment.Amount Order amount (to be sent in cents). Number 15 Yes
Payment.Authenticate Defines if the shopper will be directed to the issuing bank for the authentication of the card. Boolean Yes
Payment.ReturnUrl URL to where the user will be redirected after payment. Text 1024 Yes
Payment.IsCryptocurrencyNegotiation Should be send as “true” if the transaction is to sell or buy criptocurrency. Boolean - No (default false)
Payment.DebitCard.CardNumber Customer’s card number. Text 19 Yes
Payment.DebitCard.Holder Customer’s name printed on the card. Text 25 No
Payment.DebitCard.ExpirationDate Expiration date printed on the card. Text 7 Yes
Payment.DebitCard.SecurityCode Security code printed on the back of the card. Text 4 No
Payment.DebitCard.Brand Card brand. Text 10 Yes
Payment.InitiatedTransactionIndicator.Category Transaction start indicator category. Valid only for Mastercard brand.
Possible values:
- “C1”: transaction initiated by the cardholder;
- “M1”: recurring or installment transaction initiated by the store;
- “M2” : transaction initiated by the e-commerce.
string 2 Conditional. Required only for Mastercard.
Payment.InitiatedTransactionIndicator.Subcategory Indicator subcategory. Valid only for Mastercard brand.
Possible values:
If InitiatedTransactionIndicator.Category = “C1” or “M1”
CredentialsOnFile
StandingOrder
Subscription
Installment
If InitiatedTransactionIndicator.Category = “M2”
PartialShipment
RelatedOrDelayedCharge
NoShow
Resubmission
See the table with the description of subcategories in Mastercard transaction start indicator.
string - Conditional. Required only for Mastercard.
Payment.ExternalAuthentication.Eci E-Commerce Indicator returned on the authentication process. Number 1 Yes
Payment.ExternalAuthentication.ReferenceId RequestID returned on the authentication process. GUID 36 Yes
Response
{
  "MerchantOrderId": "2014121201",
  "Customer": {
    "Name": "Comprador Cartão de débito"
  },
  "Payment": {
    "DebitCard": {
      "CardNumber": "555187******0181",
      "Holder": "Teste Holder",
      "ExpirationDate": "12/2030",
      "SaveCard": false,
      "Brand": "Master",
      "PaymentAccountReference": "IC722LCXBROSHBPIBK7B44MBXO5HF"
    },
    "Provider": "Simulado",
    "AuthorizationCode": "635288",
    "Tid": "0826104754051",
    "ProofOfSale": "132471",
    "Authenticate": true,
    "ExternalAuthentication": {
      "Cavv": "AAABB2gHA1B5EFNjWQcDAAAAAAB=",
      "Xid": "Uk5ZanBHcWw2RjRCbEN5dGtiMTB=",
      "Eci": "5",
      "Version": "2",
      "ReferenceId": "a24a5d87-b1a1-4aef-a37b-2f30b91274e6"
    },    
    "Recurrent": false,
    "Amount": 15700,
    "ReceivedDate": "2022-08-26 10:47:53",
    "CapturedAmount": 15700,
    "CapturedDate": "2022-08-26 10:47:54",
    "Status": 2,
    "IsSplitted": false,
    "ReturnMessage": "Operation Successful",
    "ReturnCode": "6",
    "PaymentId": "21c9a3e7-23c2-420b-b12d-b514ef271c85",
    "Type": "DebitCard",
    "Currency": "BRL",
    "Country": "BRA",
    "Links": [
      {
        "Method": "GET",
        "Rel": "self",
        "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/21c9a3e7-23c2-420b-b12d-b514ef271c85"
      }
    ]
  }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2014121201",
    "Customer": {
        "Name": "Comprador Cartão de débito"
    },
    "Payment": {
        "DebitCard": {
            "CardNumber": "555187******0181",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Master",
            "PaymentAccountReference": "IC722LCXBROSHBPIBK7B44MBXO5HF"
        },
        "Provider": "Simulado",
        "AuthorizationCode": "635288",
        "Tid": "0826104754051",
        "ProofOfSale": "132471",
        "Authenticate": true,
        "ExternalAuthentication": {
            "Cavv": "AAABB2gHA1B5EFNjWQcDAAAAAAB=",
            "Xid": "Uk5ZanBHcWw2RjRCbEN5dGtiMTB=",
            "Eci": "5",
            "Version": "2",
            "ReferenceId": "a24a5d87-b1a1-4aef-a37b-2f30b91274e6"
        },        
        "Recurrent": false,
        "Amount": 15700,
        "ReceivedDate": "2022-08-26 10:47:53",
        "CapturedAmount": 15700,
        "CapturedDate": "2022-08-26 10:47:54",
        "Status": 2,
        "IsSplitted": false,
        "ReturnMessage": "Operation Successful",
        "ReturnCode": "6",
        "PaymentId": "21c9a3e7-23c2-420b-b12d-b514ef271c85",
        "Type": "DebitCard",
        "Currency": "BRL",
        "Country": "BRA",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/21c9a3e7-23c2-420b-b12d-b514ef271c85"
            }
        ]
    }
}
Property Description Type Size Format
AuthenticationUrl URL to where the e-commerce should redirect the shopper for the debit flow. Text 56 Authentication URL
Tid Transaction Id at the acquirer. Text 20 Alphanumeric text
PaymentId Payment ID number, needed for future operations like Queries, Capture and Cancellation. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ReturnUrl Return URL for the store. URL where the store will be redirected after the flow. Text 1024 http://www.urlecommerce.com.br
Status Transaction Status. Check out the Transactional Status codes table Byte 0
ReturnCode Acquirer return code. Text 32 Alphanumeric text
Payment.MerchantAdviceCode Card brand’s return code that defines the period for transaction submission retry.Valid only for Mastercard. See more at Mastercard Retry Program. Text 2 Number
Payment.DebitCard.PaymentAccountReference PAR (payment account reference) is the number that associates different tokens to the same card. It will be returned by the Master and Visa brands and passed on to Cielo e-commerce customers. If the card brand doesn’t send the information the field will not be returned. Alphanumeric 29 -

3D Secure Authentication

Cielo offers 3DS 2.0, a transaction authenticating protocol. Authentication is optional for credit cards transactions and required for debit cards transaction, as determined by issuing banks and card brands.

To integrate the authentication to your transactions:

  1. Integrate the 3DS 2.0 script to your payment page, as instructed on the 3DS guide;
  2. In the credit or debit transaction request, send the aditional node ExternalAuthentication, as the following examples.

Credit card with authentication

Request
{
  "MerchantOrderId": "2014111701",
  "Customer": {
    "Name": "Comprador crédito completo",
    "Email": "compradorteste@teste.com",
    "Birthdate": "1991-01-02",
    "Address": {
      "Street": "Rua Teste",
      "Number": "123",
      "Complement": "AP 123",
      "ZipCode": "12345987",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BRA"
    },
    "DeliveryAddress": {
      "Street": "Rua Teste",
      "Number": "123",
      "Complement": "AP 123",
      "ZipCode": "12345987",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BRA"
    },
    "Billing": {
      "Street": "Rua Neturno",
      "Number": "12345",
      "Complement": "Sala 123",
      "Neighborhood": "Centro",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BR",
      "ZipCode": "20080123"
    }
  },
  "Payment": {
    "Currency": "BRL",
    "Country": "BRA",
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": "ByMerchant",
    "Capture": true,
    "Authenticate": "false",
    "Recurrent": "false",
    "SoftDescriptor": "123456789ABCD",
    "CreditCard": {
      "CardNumber": "1234123412341231",
      "Holder": "Teste Holder",
      "ExpirationDate": "12/2030",
      "SecurityCode": "123",
      "SaveCard": "false",
      "Brand": "Visa",
      "CardOnFile": {
        "Usage": "Used",
        "Reason": "Unscheduled"
      }
    },
    "IsCryptoCurrencyNegotiation": true,
    "Type": "CreditCard",
    "Amount": 15700,
    "AirlineData": {
      "TicketNumber": "AR988983"
    }
  }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
   "MerchantOrderId":"2014111701",
   "Customer":{
      "Name":"Comprador crédito completo",
      "Identity":"11225468954",
      "IdentityType":"CPF",
      "Email":"compradorteste@teste.com",
      "Birthdate":"1991-01-02",
      "Address":{
         "Street":"Rua Teste",
         "Number":"123",
         "Complement":"AP 123",
         "ZipCode":"12345987",
         "City":"Rio de Janeiro",
         "State":"RJ",
         "Country":"BRA"
      },
        "DeliveryAddress": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "Billing": {
            "Street": "Rua Neturno",
            "Number": "12345",
            "Complement": "Sala 123",
            "Neighborhood": "Centro",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BR",
            "ZipCode": "20080123"
  },
   },
   "Payment":{
     "ServiceTaxAmount":0,
     "Installments":1,
     "Interest":"ByMerchant",
     "Capture":true,
     "Authenticate":false,
     "Recurrent":"false",
     "SoftDescriptor":"123456789ABCD",
     "CreditCard":{
         "CardNumber":"4551870000000183",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"123",
         "SaveCard":"false",
         "Brand":"Visa",
         "CardOnFile":{
            "Usage": "Used",
            "Reason":"Unscheduled"
         }
     },
     "IsCryptoCurrencyNegotiation": true,
     "Type":"CreditCard",
     "Amount":15700,
     "AirlineData":{
         "TicketNumber":"AR988983"
     }
   }
}
--verbose
Propriedade Tipo Tamanho Obrigatório Descrição
MerchantId GUID 36 Yes Store identifier at Cielo.
MerchantKey text 40 Yes Public key for double authentication at Cielo.
Content-Type header 40 Yes application/json (required).
RequestId GUID 36 No Request Identifier, used when the merchant uses different servers for each GET/POST/PUT.
MerchantOrderId text 50 Yes Order ID number.
Customer.Name text 255 No Customer’s name
Customer.Status text 255 No The customer’s registration status on the store. (NEW / EXISTING)
Customer.Identity text 14 No Customer’s RG, CPF or CNPJ.
Customer.IdentityType text 255 No Customer’s type of identification (CPF/CNPJ).
Customer.Email text 255 No Customer’s e-mail
Customer.Birthdate date 10 No Customer’s birth date (AAAA/MM/DD).
Customer.Address.Street text 255 No Customer’s address.
Customer.Address.Number text 15 No Customer’s address number.
Customer.Address.Complement text 50 No Customer’s address complement.
Customer.Address.ZipCode text 9 No Customer’s Zip Code
Customer.Address.City text 50 No Customer’s address’ city.
Customer.Address.State text 2 No Customer’s address’ state.
Customer.Address.Country text 35 No Customer’s address’ country.
Customer.DeliveryAddress.Street text 255 No Customer’s delivery address.
Customer.Address.Number text 15 No Customer’s delivery address number.
Customer.DeliveryAddress.Complement text 50 No Customer’s delivery address complement.
Customer.DeliveryAddress.ZipCode text 9 No Customer’s delivery address Zip Code.
Customer.DeliveryAddress.City text 50 No Customer’s delivery address city.
Customer.DeliveryAddress.State text 2 No Customer’s delivery address state.
Customer.DeliveryAddress.Country text 35 No Customer’s delivery address country.
Payment.Type text 100 Yes Type of the payment method.
Payment.Amount number 15 Yes Order Amount (to be sent in cents).
Payment.Currency text 3 No Currency in which the payment will be made (BRL).
Payment.Country text 3 No Country in which the payment will be made.
Payment.Provider text 15 Defines the behavior for the payment method/NÃO OBRIGATÓRIO PARA CRÉDITO.
Payment.ServiceTaxAmount number 15 No Appliable only to airline companies. Order amount that will be destined to service tax. PS.: This amount is not added to the authorization amount.
Payment.SoftDescriptor text 13 No The store’s name that will be on the shopper’s bank invoice. Does not allow special characters.
Payment.Installments number 2 Yes Number of installments. If the transaction is a recurrence, the number of installments will be 1. For installment transactions, the number of installments will be greater than 1.
Payment.Interest text 10 No Type of installments - e-commerce (ByMerchant) or card (ByIssuer).
Payment.Capture boolean No (Default false) Boolean that identifies if the authorization should be done by authomatic capture (“true”) or posterior capture (“false”).
Payment.Authenticate Boolean No (Default false) Defines if the shopper will be directed to the issuing bank for card authetication.
Payment.Recurrent boolean - Conditional Indicates if the transaction is recurring (“true”) or not (“false”). The value “true” won’t originate a new recurrence, it will only allow a transaction without the need to send the security code. Authenticate should be “false” if Recurrent is “true”. Find out more about Recurring Payments.
Payment.IsCryptocurrencyNegotiation boolean - No (default false) Should be send as “true” if the transaction is to sell or buy criptocurrency.
Payment.AirlineData.TicketNumber alphanumeric 13 No Inform the number of the main airline ticket of the transaction.
CreditCard.CardNumber text 19 Yes Shopper’s card number.
CreditCard.Holder text 25 No Name of the shopper printed on the card. Does not accept special characters.
CreditCard.ExpirationDate text 7 Yes Expiration date printed on the card. E.g. MM/AAAA.
CreditCard.SecurityCode text 4 No Security code printed on the back of the card.
CreditCard.SaveCard boolean No (Default false) Boolean that identifies if the card will be saved to generate a CardToken. Find out more about Tokenization of Cards.
CreditCard.Brand text 10 Yes Card brand. Possible values: Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard / Hiper.
CreditCard.CardOnFile.Usage text - No First if the card was stored and it’s its first use.
Used if the card was stored and has been used for another transaction before.
CreditCard.CardOnFile.Reason text - Conditional Indicates the motive for card storage, if the “Usage” field is “Used”.
Recurring - Programmed recurring transaction (e.g. Subscriptions). If it is a recurring transaction, use Payment.Recurrent = true (merchant recurrence) or Recurrent.Payment = true (scheduled recurrence).
Unscheduled - Recurring transaction with no fixed date (e.g. service apps)
Installments - Installments through recurring transactions.
Response
{
  "MerchantOrderId": "2014111706",
  "Customer": {
    "Name": "Comprador crédito completo",
    "Identity": "11225468954",
    "IdentityType": "CPF",
    "Email": "compradorteste@teste.com",
    "Birthdate": "1991-01-02",
    "Address": {
      "Street": "Rua Teste",
      "Number": "123",
      "Complement": "AP 123",
      "ZipCode": "12345987",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BRA"
    },
    "DeliveryAddress": {
      "Street": "Rua Teste",
      "Number": "123",
      "Complement": "AP 123",
      "ZipCode": "12345987",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BRA"
    },
    "Billing": {
      "Street": "Rua Neturno",
      "Number": "12345",
      "Complement": "Sala 123",
      "Neighborhood": "Centro",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BR",
      "ZipCode": "20080123"
    }
  },
  "Payment": {
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": "ByMerchant",
    "Capture": true,
    "Authenticate": false,
    "CreditCard": {
      "CardNumber": "455187******0183",
      "Holder": "Teste Holder",
      "ExpirationDate": "12/2030",
      "SaveCard": false,
      "Brand": "Visa",
      "PaymentAccountReference": "92745135160550440006111072222",
      "CardOnFile": {
        "Usage": "Used",
        "Reason": "Unscheduled"
      }
    },
    "IsCryptoCurrencyNegotiation": true,
    "TryAutomaticCancellation": true,
    "ProofOfSale": "674532",
    "Tid": "0305020554239",
    "AuthorizationCode": "123456",
    "SoftDescriptor": "123456789ABCD",
    "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
    "Type": "CreditCard",
    "Amount": 15700,
    "CapturedAmount": 15700,
    "Country": "BRA",
    "AirlineData": {
      "TicketNumber": "AR988983"
    },
    "ExtraDataCollection": [],
    "Status": 2,
    "ReturnCode": "6",
    "ReturnMessage": "Operation Successful",
    "MerchantAdviceCode": "1",
    "Links": [
      {
        "Method": "GET",
        "Rel": "self",
        "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
      },
      {
        "Method": "PUT",
        "Rel": "void",
        "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
      }
    ]
  }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2014111706",
    "Customer": {
        "Name": "Comprador crédito completo",
        "Identity":"11225468954",
        "IdentityType":"CPF",
        "Email": "compradorteste@teste.com",
        "Birthdate": "1991-01-02",
        "Address": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "DeliveryAddress": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "Billing": {
            "Street": "Rua Neturno",
            "Number": "12345",
            "Complement": "Sala 123",
            "Neighborhood": "Centro",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BR",
            "ZipCode": "20080123"
  },
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": true,
        "Authenticate": false,
        "CreditCard": {
            "CardNumber": "455187******0183",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa",
            "PaymentAccountReference":"92745135160550440006111072222",
         "CardOnFile":{
            "Usage": "Used",
            "Reason":"Unscheduled"
         }
        },
        "IsCryptoCurrencyNegotiation": true,
        "TryAutomaticCancellation":true,
        "ProofOfSale": "674532",
        "Tid": "0305020554239",
        "AuthorizationCode": "123456",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "CreditCard",
        "Amount": 15700,
        "CapturedAmount": 15700,
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 2,
        "ReturnCode": "6",
        "ReturnMessage": "Operation Successful",
        "MerchantAdviceCode":"1",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
Property Description Type Size Format
ProofOfSale Authorization number, identical to the NSU. text 6 Alphanumeric text
Tid Transaction Id on the acquirer. text 20 Alphanumeric text
AuthorizationCode Authorization code. text 6 Alphanumeric text
SoftDescriptor Text that will be printed on the carrier’s bank invoice. Does not allow special characters. text 13 Alphanumeric text
PaymentId Payment ID number, needed for future operations like Queries, Capture and Cancellation. GUID 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ECI Eletronic Commerce Indicator. Indicates how safe a transaction is. text 2 E.g. 7
Status Transaction status. Check out the complete Transactional status codes table. byte 2
ReturnCode Acquirer return code. text 32 Alphanumeric text
ReturnMessage Acquirer return message. Text 512 Alphanumeric text
MerchantAdviceCode Card brand’s return code that defines the period for transaction submission retry. Valid only for Mastercard. See more at Mastercard retry program text 2 Number
TryAutomaticCancellation In case of error during authorization (status “Not Finished - 0”), the response will include the “tryautomaticcancellation” field as “true”. In this case, the transaction will be automatically queried, and if it has been authorized successfully, it will be canceled automatically. This feature must be enabled for establishment. To enable, please contact our technical support. boolean - true or false
CreditCard.PaymentAccountReference PAR (payment account reference) is the number that associates different tokens to the same card. It will be returned by the Master and Visa brands and passed on to Cielo e-commerce customers. If the card brand doesn’t send the information the field will not be returned. alphanumeric 29

Debit card with authentication

The debit transaction with authentication is the standard for this payment method. Follow the integration steps at the 3DS guide and send the request as shown in Creating a debit transaction.

External MPI

The Merchant plug-in, known as MPI, is a service that allows you to make the call for authentication, integrated and certified with card brands for 3DS authentication processing. Cielo offers the merchant the 3DS integration through the Internal MPI or the External MPI.

Mastercard Transaction Initiator

The following tables apply to Mastercard credit and debit transactions with stored credentials. The objective is to identify whether the transaction was initiated by the cardholder or by the merchant:

The transaction initiator indicator must be sent in the node Payment.InitiatedTransactionIndicator, within parameters Category and Subcategory. Please refer to the following request example and tables for more information:

Request

   "Payment":{
     (...)
    "InitiatedTransactionIndicator": {
        "Category": "C1",
        "Subcategory": "Standingorder"
    },
    (...)
   }
   "Payment":{
     (...)
    "InitiatedTransactionIndicator": {
        "Category": "C1",
        "Subcategory": "Standingorder"
    },
    (...)
   }

For the full request example see Creating a credit card transaction or Creating a debit transaction.

Property Type Size Required Description
Payment.InitiatedTransactionIndicator.Category string 2 Conditional. Required only for Mastercard. Transaction Initiator Indicator category. Valid only for Mastercard.
Possible values:
- “C1”: transaction initiated by the cardholder;
- “M1”: recurring payment or installment initiated by the merchant
- “M2”: transaction initiated by the merchant.
Payment.InitiatedTransactionIndicator.Subcategory string - Conditional. Required only for Mastercard. Transaction Initiator Indicator subcategory. Valid only for Mastercard. Please refer to the Transaction Initiator Indicator tables for the full list.

Response

The response will be the default response for the credit or debit transaction, returning the node Payment.InitiatedTransactionIndicator as sent in the request.

Mastercard transaction initiator tables

CIT and MIT categories

The categories (C1, M1 or M2) must be sent in parameter Payment.InitiatedTransactionIndicator.Category.

Category Transaction initiator Description
C1 Cardholder-initiated transaction (CIT). The transaction is initiated by the cardholder. The cardholder provides card data and agrees with the merchant storing payment credentials or makes a purchase using previously stored payment credentials. The subcategory will indicate the reason for the purchase or for storing card data.
M1 Merchant-initiated transaction (MIT). The merchant has stored the payment credentials in the past (tokenized and with cardholder consent) and is authorized to initiate one or more transactions in the future for recurrent payments or installments.
M2 Merchant-initiated transaction (MIT). The merchant has stored the payment credentials in the past (tokenized and with cardholder consent) and is authorized to initiate one or more transactions in the future in order to charge for partial deliveries, related/delayed expenses, no-show fees and retry/resubmission.
CIT and MIT subcategories

The subcategories must be sent in parameter Payment.InitiatedTransactionIndicator.Subcategory.

Initiator category Initiator subcategory Meaning Example
C1 CredentialsOnFile Cardholder-initiated transaction in which the cardholder provides card data and agrees with the merchant storing payment credentials or makes a purchase using previously stored payment credentials. The cardholder initiates the purchase and the merchant is authorized to save card data for future purchases initiated by the cardholder, such as one-click-buy.
C1 StandingOrder Cardholder-initiated transaction in which the cardholder provides card data and agrees with the merchant storing payment credentials for future payments of fixed amount and variable frequency. Initial transaction to store card data for utility bills monthly payments.
C1 Subscription Cardholder-initiated transaction in which the cardholder provides card data and agrees with the merchant storing payment credentials for recurrent payments of fixed amount and frequency. Initial transaction to store card data for a monthly subscription (e.g .newspapers and magazines).
C1 Installment Cardholder-initiated transaction in which the cardholder initiates the first installment and authorizes the merchant to save card data for the next installments. Initial transaction to store card data for installment buying
M1 CredentialsOnFile Merchant-initiated unscheduled transaction of fixed or variable amount. When the cardholder agrees with transactions for toll charges when the balance in their account is below a certain amount (auto-recharge).
M1 StandingOrder Merchant-initiated transaction of variable amount and fixed frequency. Utility bills monthy payments.
M1 Subscription Merchant-initiated transaction of fixed amount and fixed frequency. Monthly subscription or fixed monthly service payment.
M1 Installment Merchant-initiated transaction of known amount and defined period. If a shopper buys a TV for $600 and chooses to pay in three $200 installments; in this situation, the first transaction is initiated by the cardholder and the following two transactions are initiated by the merchant.
M2 PartialShipment Merchant-initiated transaction when the order will be delivered in more than one shipping. Partial shipment may occur when the amount of purchased goods in the e-commerce is not available for shipping in the time of purchase. Each shipping is a separate transaction.
M2 RelatedOrDelayedCharge Merchant-initiated transaction for additional expenses, i.e., additional charges after providing initial services and processing the payment. A hotel minibar fridge charges after cardholder check-out.
M2 NoShow Merchant-initiated transaction for no-show charges according to the merchant cancellation policy. The cancellation of a reservation by the cardholder without adequate prior notice to the merchant.
M2 Resubmission Merchant-initiated transaction for retrying previously denied transactions. The previous attempt to submit a transaction was denied, but the issuer response does not prohibit the merchant to retry, such as insufficient funds/response above credit limit.

Important: Card data is stored in encrypted format.

Pix

For Pix, the transmission for the payment order and the availability of funds for the receiver happens in real time, 24 hours a day and without the need of intermediaries. It is a payment method that allows fast and low cost transactions.

Get to know the cycle of a Pix transaction:

SEQUENCE RESPONSIBLE DESCRIPTION TRANSACTION STATUS
1 E-commerce Generating the QR code. 12 - Pending
2 Shopper Paying through the QR code. 2 - Paid
3 E-commerce Getting notified of the payment confirmation. 2 - Paid
4 E-commerce Consulting the transaction status. 2 - Paid
5 E-commerce Releasing the order. 2 - Paid
6 E-commerce If it’s necessary, requesting the Pix transaction refund (similar to a card refund). 2 - Paid
7 E-commerce Getting notified of the payment refund. 11 - Refunded
8 E-commerce Consulting the transaction status. 11 - Refunded

WARNING:

  • To enable Pix for the sandbox environment, get in touch with our E-commerce support e-mail: cieloecommerce@cielo.com.br;
  • Before using Pix in production, certify that Pix is allowed in your account. To confirm, you just have to access Cielo portal in the logged in area go to Meu Cadastro > Autorizações > PIX Geração do QR Code Pix

Creating a transaction with Pix QR Code

To generate a Pix QR code through the API E-commerce Cielo, simply perform the integration according to the following specification.

The required field Payment.Type should be sent as “Pix”. In the response, the Pix QR Code image code base64 will be returned and you should make it available to the shopper.

Check the transactional flow for generating a Pix QR Code:

Geração do QR Code Pix

The shopper then scans the QR code through one of the apps enabled for Pix and makes the payment. At this stage there is no participation from the e-commerce or the Cielo E-commerce API, as shown in the flow:

Pagamento Pix

See the request and response examples for generating Pix QR Code:

Request

{
  "MerchantOrderId": "2020102601",
  "Customer": {
    "Name": "Nome do Pagador",
    "Identity": "12345678909",
    "IdentityType": "CPF"
  },
  "Payment": {
    "Type": "Pix",
    "Amount": 100
  }
}
--request POST "https://(...)/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
   "MerchantOrderId":"2020102601",
   "Customer":{
      "Name":"Nome do Pagador",
      "Identity":"CPF",
      "IdentityType":"12345678909"
   },
   "Payment":{
      "Type":"Pix",
      "Amount":100
   }
}
--verbose
PROPERTY DESCRIPTION TYPE SIZE REQUIRED
MerchantOrderId Order Id number. text 50 Yes
Customer.Name Shopper name. text 255 Yes
Customer.Identity Shopper’s ID number (CPF/CNPJ) text 14 Yes
Customer.IdentityType Shopper’s type of ID (CPF or CNPJ). text 255 Yes
Payment.Type Payment type. In this case, “Pix”. text - Yes
Payment.Amount Payment value amount in cents. number 15 Yes

Response

{
   "MerchantOrderId":"2020102601",
   "Customer":{
      "Name":"Nome do Pagador"
   },
   "Payment":{
      (...)
      "Paymentid":"1997be4d-694a-472e-98f0-e7f4b4c8f1e7",
      "Type":"Pix",
      "AcquirerTransactionId":"86c200c7-7cdf-4375-92dd-1f62dfa846ad",
         "ProofOfSale":"123456",
      "QrcodeBase64Image":"rfhviy64ak+zse18cwcmtg==[...]",
      "QrCodeString":"00020101021226880014br.gov.bcb.pix2566qrcodes-h.cielo.com.br/pix-qr/d05b1a34-ec52-4201-ba1e-d3cc2a43162552040000530398654041.005802BR5918Merchant Teste HML6009Sao Paulo62120508000101296304031C",
      "Amount":100,
      "ReceivedDate":"2020-10-15 18:53:20",
      "Status":12,
      "ReturnCode":"0",
      "ReturnMessage":"Pix gerado com sucesso",
      (...)
   }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
   "MerchantOrderId":"2020102601",
   "Customer":{
      "Name":"Nome do Pagador"
   },
   "Payment":{
      (...)
      "PaymentId":"1997be4d-694a-472e-98f0-e7f4b4c8f1e7",
      "Type":"Pix",
      "AcquirerTransactionId":"86c200c7-7cdf-4375-92dd-1f62dfa846ad",
         "ProofOfSale":"123456",
      "QrcodeBase64Image":"rfhviy64ak+zse18cwcmtg==[...]",
      "QrCodeString":"00020101021226880014br.gov.bcb.pix2566qrcodes-h.cielo.com.br/pix-qr/d05b1a34-ec52-4201-ba1e-d3cc2a43162552040000530398654041.005802BR5918Merchant Teste HML6009Sao Paulo62120508000101296304031C",
      "Amount":100,
      "ReceivedDate":"2020-10-15 18:53:20",
      "Status":12,
      "ReturnCode":"0",
      "ReturnMessage":"Pix gerado com sucesso",
      (...)
   }
}
--verbose
PROPERTY DESCRIPTION TYPE SIZE FORMAT
Payment.PaymentId Payment ID number. GUID 40 Text
Payment.AcquirerTransactionId Transaction Id for the provider of the payment methods. GUID 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Payment.ProofOfSale NSU Pix. text 20 Alphanumeric Text
Payment.QrcodeBase64Image Base64 code for the QR Code image. text - Text
Payment.QrCodeString Codified text for the shopper to copy and paste in the internet banking field for mobile payments. The availability of this code is the merchant’s responsibility. We recommend displaying a button that, when clicked, the shopper copies the code. text Variable Alphanumeric Text
Payment.Status Transaction status. In case of success, the inital status is “12” (Pending). See the transaction status list. number - 12
Payment.ReturnCode Code returned by the provider of the payment method. text 32 0
Payment.ReturnMessage Message returned by the provider of the payment method. text 512 “Pix successfully generated”

Requesting Pix refund

If your store needs to cancel a pix transaction, it’s possible to ask for a refund. It’s important to point out that the refund is not immediate and it needs to be approved by the Pix provider. When it is approved, your store will get notified.

Warning:

  • The refund will only happen if there are funds available;
  • The deadline for cancellation is 90 days, as specified by BACEN.

Request

--request PUT "https://(...)/sales/{PaymentId}/void?Amount=xxx"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--verbose
PROPERTY DESCRIPTION TYPE SIZE REQUIRED
MerchantId Store identifier in Cielo. GUID 36 Yes
MerchantKey Public key for double authentication at Cielo. text 40 Yes
RequestId Request Identifier, used when the merchant uses different servers for each GET/POST/PUT. GUID 36 No
PaymentId Payment ID number. GUID 36 Yes
Amount Amount to be cancelled/refunded in cents. Check if the acquirer supports cancellations or refunds. number 15 No

Response

{
  "Status": 12,
  "ReasonCode": 0,
  "ReasonMessage": "Successful",
  "ReturnCode": "0",
  "ReturnMessage": "Reembolso solicitado com sucesso",
  "Links": [
    {
      "Method": "GET",
      "Rel": "self",
      "Href": "https://(...)/sales/{PaymentId}"
    }
  ]
}
{
   "Status": 12,
   "ReasonCode": 0,
   "ReasonMessage": "Successful",
   "ReturnCode": "0",
   "ReturnMessage": "Reembolso solicitado com sucesso",
   "Links": [
      {
         "Method": "GET",
         "Rel": "self",
         "Href": "https://(...)/sales/{PaymentId}"
      }
   ]
}
PROPERTY DESCRIPTION TYPE SIZE FORMAT
Status Transaction status. byte 2 E.g., “1”
ReasonCode Indicates success or error in the requested operation. See more at API Error Codes. text 32 Alphanumeric text
ReasonMessage Corresponding messa ge for the ReasonCode. Saiba mais em Códigos de Erros da API. text 512 Alphanumeric text

Boleto

To make a Boleto transaction, you first need to hire this service at the bank. Then, configure the boleto payment method according to the guidelines in the Boletos guide.

Note: Banco do Brasil boletos do not have the automatic conciliation service.

Request

{
  "MerchantOrderId": "2014111706",
  "Customer": {
    "Name": "Comprador Teste Boleto",
    "Identity": "1234567890",
    "Address": {
      "Street": "Avenida Marechal Câmara",
      "Number": "160",
      "Complement": "Sala 934",
      "ZipCode": "22750012",
      "District": "Centro",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BRA"
    },
    "Billing": {
      "Street": "Avenida Marechal Câmara",
      "Number": "160",
      "Complement": "Sala 934",
      "Neighborhood": "Centro",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BR",
      "ZipCode": "22750012"
    }
  },
  "Payment": {
    "Type": "Boleto",
    "Amount": 15700,
    "Provider": "Bradesco2",
    "Address": "Rua Teste",
    "BoletoNumber": "123",
    "Assignor": "Empresa Teste",
    "Demonstrative": "Desmonstrative Teste",
    "ExpirationDate": "2020-12-31",
    "Identification": "11884926754",
    "Instructions": "Aceitar somente até a data de vencimento, após essa data juros de 1% dia."
  }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId":"2014111706",
    "Customer":
    {
        "Name":"Comprador Teste Boleto",
        "Identity": "1234567890",
        "Address":
        {
          "Street": "Avenida Marechal Câmara",
          "Number": "160",
          "Complement": "Sala 934",
          "ZipCode" : "22750012",
          "District": "Centro",
          "City": "Rio de Janeiro",
          "State" : "RJ",
          "Country": "BRA"
        },
        "Billing": {
           "Street": "Avenida Marechal Câmara",
           "Number": "160",
           "Complement": "Sala 934",
           "Neighborhood": "Centro",
           "City": "Rio de Janeiro",
           "State": "RJ",
           "Country": "BR",
           "ZipCode": "22750012"
  },
    },
    "Payment":
    {
        "Type":"Boleto",
        "Amount":15700,
        "Provider":"Bradesco2",
        "Address": "Rua Teste",
        "BoletoNumber": "123",
        "Assignor": "Empresa Teste",
        "Demonstrative": "Desmonstrative Teste",
        "ExpirationDate": "2020-12-31",
        "Identification": "11884926754",
        "Instructions": "Aceitar somente até a data de vencimento, após essa data juros de 1% dia."
    }
}
--verbose
Property Description Type Size Required
MerchantId Store identifier in API E-commerce Cielo GUID 36 Yes
MerchantKey Public key for double authentication in API E-commerce Cielo text 40 Yes
RequestId Request Identifier, used when the merchant uses different servers for each GET/POST/PUT GUID 36 No
MerchantOrderId Order ID number. text Bradesco: 27
Banco do Brasil: 50
Yes
Customer.Name Shopper’s name. text Bradesco: 34
Banco do Brasil: 60
No
Customer.Status Shopper registration status in store(NEW / EXISTING) - Used by fraud analysis text 255 No
Customer.Address.ZipCode Shopper’s address zip code. text 9 Yes
Customer.Address.Country Shopper’s address country. text 35 No
Customer.Address.State Shopper’s address state. text 2 Yes
Customer.Address.City Shopper’s address city. text Bradesco: 50
Banco do Brasil: 18
Yes
Customer.Address.District Shopper’s neighborhood. text 50 Yes
Customer.Address.Street Shopper’s address. text 255 Yes
Customer.Address.Number Shopper’s address number. text 15 Yes
Customer.Billing.Street Shopper’s billing address. string 24 No
Customer.Billing.Number Shopper’s billing address number. string 5 No
Customer.Billing.Complement Shopper’s billing address complement. string 14 No
Customer.Billing.Neighborhood Shopper’s billing address neighborhood. string 15 No
Customer.Billing.City Shopper’s billing address city. string 20 No
Customer.Billing.State Shopper’s billing address state. string 2 No
Customer.Billing.Country Shopper’s billing address country. More information at ISO 2-Digit Alpha Country Code string 2 No
Customer.Billing.ZipCode Shopper’s billing address Zip Code. string 9 No
Payment.Type Type of the payment method. text 100 Yes
Payment.Amount Order Amount (to be sent in cents). number 15 Yes
Payment.Provider Defines behavior of the payment method. Possible values: “Bradesco2” or “BancoDoBrasil2” - see Additional Rules text 15 Yes
Payment.Adress Transferor’s address. text 255 No
Payment.BoletoNumber Boleto number sent by the merchant. Used to count issued bank slips (“OurNumber”). number Bradesco: 11
Banco do Brasil: 9
No
Payment.Assignor Transferor’s name. text 200 No
Payment.Demonstrative Demonstration text. text 450 No
Payment.ExpirationDate Boleto expiration date. date 10 No
Payment.Identification Identification document of the Transferor. text 14 No
Payment.Instructions Boleto instructions. text 450 No

Response

For the boleto transaction response, API E-commerce Cielo will send the boleto URL and the bar code, which the e-commerce should display to the shopper.

{
  "MerchantOrderId": "2014111706",
  "Customer": {
    "Name": "Comprador Boleto Completo",
    "Address": {
      "Street": "Av Marechal Camara",
      "Number": "160",
      "ZipCode": "22750012",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BRA",
      "District": "Centro"
    },
    "Billing": {
      "Street": "Avenida Marechal Câmara",
      "Number": "160",
      "Complement": "Sala 934",
      "Neighborhood": "Centro",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BR",
      "ZipCode": "22750012"
    }
  },
  "Payment": {
    "Instructions": "Aceitar somente até a data de vencimento, após essa data juros de 1% dia.",
    "ExpirationDate": "2015-01-05",
    "Url": "https://apisandbox.cieloecommerce.cielo.com.br/post/pagador/reenvia.asp/a5f3181d-c2e2-4df9-a5b4-d8f6edf6bd51",
    "Number": "123-2",
    "BarCodeNumber": "00096629900000157000494250000000012300656560",
    "DigitableLine": "00090.49420 50000.000013 23006.565602 6 62990000015700",
    "Assignor": "Empresa Teste",
    "Address": "Rua Teste",
    "Identification": "11884926754",
    "PaymentId": "a5f3181d-c2e2-4df9-a5b4-d8f6edf6bd51",
    "Type": "Boleto",
    "Amount": 15700,
    "Currency": "BRL",
    "Country": "BRA",
    "Provider": "Bradesco2",
    "ExtraDataCollection": [],
    "Status": 1,
    "Links": [
      {
        "Method": "GET",
        "Rel": "self",
        "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
      }
    ]
  }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2014111706",
    "Customer":
    {
        "Name": "Comprador Boleto Completo",
        "Address":
        {
        "Street": "Av Marechal Camara",
        "Number": "160",
        "ZipCode": "22750012",
        "City": "Rio de Janeiro",
        "State": "RJ",
        "Country": "BRA",
        "District": "Centro"
        },
      "Billing": {
         "Street": "Avenida Marechal Câmara",
         "Number": "160",
         "Complement": "Sala 934",
         "Neighborhood": "Centro",
         "City": "Rio de Janeiro",
         "State": "RJ",
         "Country": "BR",
         "ZipCode": "22750012"
    },
    "Payment":
    {
        "Instructions": "Aceitar somente até a data de vencimento, após essa data juros de 1% dia.",
        "ExpirationDate": "2015-01-05",
        "Url": "https://apisandbox.cieloecommerce.cielo.com.br/post/pagador/reenvia.asp/a5f3181d-c2e2-4df9-a5b4-d8f6edf6bd51",
        "Number": "123-2",
        "BarCodeNumber": "00096629900000157000494250000000012300656560",
        "DigitableLine": "00090.49420 50000.000013 23006.565602 6 62990000015700",
        "Assignor": "Empresa Teste",
        "Address": "Rua Teste",
        "Identification": "11884926754",
        "PaymentId": "a5f3181d-c2e2-4df9-a5b4-d8f6edf6bd51",
        "Type": "Boleto",
        "Amount": 15700,
        "Currency": "BRL",
        "Country": "BRA",
        "Provider": "Bradesco2",
        "ExtraDataCollection": [],
        "Status": 1,
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            }
        ]
    }
}
Property Description Type Size Format
PaymentId Payment identification number, necessary for future operations such as Queries, Capture and Cancellation. GUID 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Instructions Boleto instructions. text 450 e.g.: Accept only until the due date, after that date interest of 1% per day.
ExpirationDate Expiration date. text 10 2014-12-25
Url Generated Boleto URL. string 256 e.g.:https://…/pagador/reenvia.asp/8464a692-b4bd-41e7-8003-1611a2b8ef2d
Number “NossoNumero” generated. text 50 e.g.: 1000000012-8
BarCodeNumber Barcode numerical representation. text 44 e.g.: 00091628800000157000494250100000001200656560
DigitableLine Digitable line. text 256 e.g.: 00090.49420 50100.000004 12006.565605 1 62880000015700
Assignor Transferor’s name. text 256 e.g.: Test Store
Address Transferor’s address. text 256 e.g.: 160 Test Avenue
Identification Identification document of the Transferor. text 14 CPF or CNPJ of the Transferor without the special characters (., /, -)
Status Transaction Status. View the full Transactional Status table byte 1

Additional Rules

Number of characters per field and Provider:

Bradesco

Property Notes Size
Provider N/a Bradesco2
MerchantOrderId Only letters, numbers, and characters like “_” and “$”. 27
Payment.BoletoNumber The value is validated by the bank. 11
Customer.Name The API Cielo truncates automatically. 34
Customer.Address.Street The value is validated by API Cielo. 70
Customer.Address.Number The value is validated by API Cielo. 10
Customer.Address.Complement The value is validated by API Cielo. 20
Customer.Address.District The value is validated by API Cielo. 50
Customer.Address.City The value is validated by API Cielo. 50
Payment.Instructions N/a 255
Payment.Demonstrative N/a 255

Banco do Brasil

Property Notes Size
Provider BancoDoBrasil2 BancoDoBrasil2
MerchantOrderId Not sent to the bank. 50
Payment.BoletoNumber When sent above 9 positions, the API Cielo truncates automatically, considering the last 9 digits. 9
Customer.Name Valid characters:
Letters from A to Z - CAPITAL LETTERS
Special characters: hyphen (-) and apostrophe (‘)
When used, it can not contain spaces between letters;
Correct examples: D’EL-REI, D’ALCORTIVO, SANT’ANA.
Incorrect examples: D’EL - REI; at most one blank space between words.
60
Customer.Address.Street Valid characters:
Letters from A to Z - CAPITAL LETTERS
Special characters: hyphen (-) and apostrophe (‘)
When used, it can not contain spaces between letters;
Correct examples: D’EL-REI, D’ALCORTIVO, SANT’ANA.
Incorrect examples: D’EL - REI; at most one blank space between words.
The fields Customer.Address.Street; Customer.Address.Number; Customer.Address.Complement; Customer.Address.District should total 60 characters at maximum.
Customer.Address.Number Valid characters:
Letters from A to Z - CAPITAL LETTERS
Special characters: hyphen (-) and apostrophe (‘)
When used, it can not contain spaces between letters;
Correct examples: D’EL-REI, D’ALCORTIVO, SANT’ANA.
Incorrect examples: D’EL - REI; at most one blank space between words.
The fields Customer.Address.Street; Customer.Address.Number; Customer.Address.Complement; Customer.Address.District should total 60 characters at maximum.
Customer.Address.Complement Valid characters:
Letters from A to Z - CAPITAL LETTERS
Special characters: hyphen (-) and apostrophe (‘)
When used, it can not contain spaces between letters;
Correct examples: D’EL-REI, D’ALCORTIVO, SANT’ANA.
Incorrect examples: D’EL - REI; at most one blank space between words.
The fields Customer.Address.Street; Customer.Address.Number; Customer.Address.Complement; Customer.Address.District should total 60 characters at maximum.
Customer.Address.District Valid characters:
Letters from A to Z - CAPITAL LETTERS
Special characters: hyphen (-) and apostrophe (‘)
When used, it can not contain spaces between letters;
Correct examples: D’EL-REI, D’ALCORTIVO, SANT’ANA.
Incorrect examples: D’EL - REI; at most one blank space between words.
The fields Customer.Address.Street; Customer.Address.Number; Customer.Address.Complement; Customer.Address.District should total 60 characters at maximum.
Customer.Address.City Valid characters:
Letters from A to Z - CAPITAL LETTERS
Special characters: hyphen (-) and apostrophe (‘)
When used, it can not contain spaces between letters;
Correct examples: D’EL-REI, D’ALCORTIVO, SANT’ANA.
Incorrect examples: D’EL - REI; at most one blank space between words.
18
Payment.Instructions N/a 255

E-wallet

What are e-wallets?

E-wallets, or digital wallets, are repositories of cards and payment data for online consumers. E-wallets allow a consumer to register their payment details in the wallet, making the purchasing process more convenient and secure.

To use e-wallets in the API E-commerce Cielo, the merchant must have the e-wallets integrated into their checkout.

Contact the provider of your choice for further information on how to hire the service.

Available e-wallets

API E-commerce Cielo supports the following digital wallets:

E-wallet Integration

Please refer to the E-Wallets documentation to get details about integrating this payment method to your checkout page.

See below the representation of a standard transactional flow after the integration of an e-wallet:

Fluxo E-wallets EN

QR Code

Credit card via QR Code in Sandbox

To test a successful authorization scenario via QR Code, use the card 4551.8700.0000.0183.

The card verification code and expiration date can be random, but they should follow this format:

Generating a QR Code via API

To create a transaction that will use a credit card, you need to send a request using the POST method to the Payment resource, as the example shows. This example includes the minimum necessary fields to be sent for the authorization.

Payment Facilitators (or submerchants) must send the parameters within node PaymentFacilitator as required by Banco Central do Brasil and card brands. If the node PaymentFacilitator is not sent, the card brand may apply penalties to the submerchant.

Request

{
  "MerchantOrderId": "2019010101",
  "Customer": {
    "Name": "QRCode Test"
  },
  "Payment": {
    "Type": "qrcode",
    "Amount": 100,
    "Installments": 1,
    "Capture": false,
    "Modality": "Credit"
    "QrCode": {
    "MerchantName": "Loja Teste"
    },
    "PaymentFacilitator": {     
        "EstablishmentCode": "12345",
        "SubEstablishment": {
            "EstablishmentCode": "2000130733",
            "Mcc": "8999",
            "Address": "Av Marechal Camara 160",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "CountryCode": "76",
            "PostalCode": "20020080",
            "CompanyName": "Lojinha01",
            "Identity": "90501654000191",
            "PhoneNumber": "24999399555"
      }
    }
  }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
  "MerchantOrderId": "2019010101",
  "Customer": {
    "Name": "QRCode Test"
  },
  "Payment": {
    "Type": "qrcode",
    "Amount": 100,
    "Installments": 1,
    "Capture": false,
    "Modality": "Credit"
    "QrCode": {
    "MerchantName": "Loja Teste"
    },
    "PaymentFacilitator": {     
        "EstablishmentCode": "12345",
        "SubEstablishment": {
            "EstablishmentCode": "2000130733",
            "Mcc": "8999",
            "Address": "Av Marechal Camara 160",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "CountryCode": "76",
            "PostalCode": "20020080",
            "CompanyName": "Lojinha01",
            "Identity": "90501654000191",
            "PhoneNumber": "24999399555"
      }
    }
  }
}
--verbose
PROPERTY TYPE SIZE REQUIRED DESCRIPTION
MerchantId GUID 36 Yes Store identifier in Cielo.
MerchantKey text 40 Yes Public key for double authentication in Cielo.
Content-Type header 40 Yes application/json (required).
RequestId GUID 36 No Request Identifier, used when the merchant uses different servers for each GET/POST/PUT.
MerchantOrderId text 50 Yes Order ID number.
Customer.Name text 255 No Shopper’s name
Payment.Type text 100 Yes Type of payment method. Send qrcode for a QR Code transaction.
Payment.Amount number 15 Yes Order amount (to be sent in cents).
Payment.Installments number 2 Yes Number of installments. If the transaction is a recurrence, the number of installments will be 1. For installment transactions, the number of installments will be greater than 1.
Payment.Capture boolean - No Send as true for the capture to be authomatic.
Payment.Modality text 10 No Indicates if the payment will be made with credit or debit. Possible values: “Credit” (standard) or “Debit”.
PaymentFacilitator.EstablishmentCode text* 11 Required for facilitators Facilitator’s establishment code. “Facilitator ID” (Registration of the facilitator with the card brands).
The code is different depending on the brand, varying even the size of the field:
MasterCard –06 digits
Visa –08 digits
ELO –from 04 to 05 digits
Hipercard –06 digits
For other brands, like Amex and JCB, the field can be filled in by “0” zeros.
PaymentFacilitator.SubEstablishment.EstablishmentCode text* 15 Required for facilitators Submerchant establishment code. “Sub-Merchant ID” (Registration of sub-accredited with the facilitator)
PaymentFacilitator.SubEstablishment.Identity text* 14 Required for facilitators Submerchant CNPJ or CPF
PaymentFacilitator.SubEstablishment.Mcc text* 4 Required for facilitators Submerchant MCC.
PaymentFacilitator.SubEstablishment.Address text* 22 Required for facilitators Submerchant address.
PaymentFacilitator.SubEstablishment.City text* 13 Required for facilitators Submerchant city.
PaymentFacilitator.SubEstablishment.State text* 2 Required for facilitators Submerchant state.
PaymentFacilitator.SubEstablishment.PostalCode text* 9 Required for facilitators Submerchant Postcode.
PaymentFacilitator.SubEstablishment.CountryCode text* 3 Required for facilitators Submerchant country code based on ISO 3166.
Ex: Brazil’s ISO 3166 code is 076. Complete list online
PaymentFacilitator.SubEstablishment.PhoneNumber text* 13 Required for facilitators Submerchant Phone Number.

*Avoid using accents as they are considered two characters.

Response

{
  "MerchantOrderId": "2019010101",
  "Customer": {
    "Name": "QRCode Test"
  },
  "Payment": {
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": 0,
    "Capture": false,
    "Authenticate": false,
    "Recurrent": false,
    "Provider": "Cielo",
    "Amount": 100,
    "ReceivedDate": "2019-01-02 10:14:29",
    "Status": 12,
    "IsSplitted": false,
    "QrCode": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51AAAQ1klEQVR42u3de6hlVR(...)",
    "PaymentFacilitator": {     
        "EstablishmentCode": "12345",
        "SubEstablishment": {
            "EstablishmentCode": "2000130733",
            "Mcc": "8999",
            "Address": "Av Marechal Camara 160",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "CountryCode": "76",
            "PostalCode": "20020080",
            "CompanyName": "Lojinha01",
            "Identity": "90501654000191",
            "PhoneNumber": "24999399555"
      }
    },
    "ReturnMessage": "QRCode gerado com sucesso",
    "PaymentId": "5d7e8fd3-70b6-4a88-9660-e064d72fdcdd",
    "Type": "qrcode",
    "Currency": "BRL",
    "Country": "BRA",
    "Links": [
      {
        "Method": "GET",
        "Rel": "self",
        "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/5d7e8fd3-70b6-4a88-9660-e064d72fdcdd"
      }
    ]
  }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2019010101",
    "Customer": {
        "Name": "QRCode Test"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": 0,
        "Capture": false,
        "Authenticate": false,
        "Recurrent": false,
        "Provider": "Cielo",
        "Amount": 100,
        "ReceivedDate": "2019-01-02 10:14:29",
        "Status": 12,
        "IsSplitted": false,
        "QrCodeBase64Image": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51AAAQ1klEQVR42u3de6hlVR(...)",
        "PaymentFacilitator": {     
            "EstablishmentCode": "12345",
            "SubEstablishment": {
                "EstablishmentCode": "2000130733",
                "Mcc": "8999",
                "Address": "Av Marechal Camara 160",
                "City": "Rio de Janeiro",
                "State": "RJ",
                "CountryCode": "76",
                "PostalCode": "20020080",
                "CompanyName": "Lojinha01",
                "Identity": "90501654000191",
                "PhoneNumber": "24999399555"
      }
    },
        "ReturnMessage": "QRCode gerado com sucesso",
        "PaymentId": "5d7e8fd3-70b6-4a88-9660-e064d72fdcdd",
        "Type": "qrcode",
        "Currency": "BRL",
        "Country": "BRA",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/5d7e8fd3-70b6-4a88-9660-e064d72fdcdd"
            }
        ]
    }
}
PROPERTY DESCRIPTION TYPE SIZE FORMAT
QrCodeBase64Image QR Code codified in base 64. The image can be shown on the page using a HTML code like this:
<img src="data:image/png;base64, image_code_in_base_64">
text variable Alphanumeric text
PaymentId Payment identification number, necessary for future operations such as Queries, Capture and Cancellation. GUID 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Status Transaction status. For QR code transactions, the initial status is 12 (Pending). View the full Transactional Status table byte 2
ReturnCode Acquirer return code. text 32 Alphanumeric text
ReturnMessage Acquirer return message. text 512 Alphanumeric text

Carnê

Carnê is a debit transaction used to pay an account.

Carnê is a payment method available for MasterCard, Visa and Elo.

This payment method can be used by merchants who issue their own carnês and Private Label card invoices. It allows the separation of sales related to product purchases and payment for services, making it easier to report values to Tax Authorities.

As in any other debit transaction on our E-commerce, the carnê transactions need to be authenticated via the 3DS 2.0 protocol. Find more information about the authentication protocol on the 3DS 2.0 guide.

Request

{
  "MerchantOrderId": "2014111704",
  "Customer": {
    "Name": "Comprador Carnet simples"
  },
  "Payment": {
    "Provider": "CieloSandbox",
    "Authenticate": true,
    "Installments": 1,
    "Amount": 100,
    "Type": "DebitCard",
    "SoftDescriptor": "123456789ABCD",
    "DebitCard": {
      "ExpirationDate": "05/2024",
      "CardNumber": "1234567891234567",
      "Holder": "Test Holder",
      "Brand": "Visa",
      "SecurityCode": "123",
      "CardOnFile": {
        "Reason": "Unscheduled",
        "Usage": "first"
      }
    },
    "ExternalAuthentication": {
      "Eci": "05",
      "Cavv": "AAABAWFlmQAAAABjRWWZEEFgFz+=",
      "Xid": "blNhMmtMUWg4RDFoV2JaM1RRbjA="
    },
    "iscarnetransaction": true
  }
}
Property Type Size Required Description
Payment.IsCarneTransaction boolean No (default false) Must be sent with a value of “true” in the case of a Carnê service payment transaction.

Specific Implementations

Quasi cash

Quasi Cash transactions are refer to purchases of currencies in online gaming, lottery tickets and more. Only a few MCCs (Merchant Category Codes) can process this type of transaction. Contact the Cielo team to know if your business fits in this category.

All E-commerce customers who transact Quasi Cash must use the request for a debit and/or credit transaction (depending on the type of payment chosen) and additionally forward the QuasiCash tag as per the following example:

"Payment":{
   "Currency":"BRL",
   "Country":"BRA",
   "ServiceTaxAmount":0,
   "Installments":1,
   "Interest":"ByMerchant",
   "Capture":true,
   "Authenticate":false,
   "SoftDescriptor":"123456789ABCD",
   "QuasiCash":true,
   "Type":"CreditCard",
   "Amount":15700,
   "CreditCard":{
      "CardNumber":"1234123412341231",
      "Holder":"Teste Holder",
      "ExpirationDate":"12/2030",
      "SecurityCode":"123",
      "SaveCard":"false",
      "Brand":"Visa",
      "CardOnFile":{
         "Usage":"Used",
         "Reason":"Unscheduled"
   }
Property Description Value Format Size Required
QuasiCash Identifies a Quasi Cash transaction. “true” ou “false” boolean - No

Payment Facilitators

All E-Commerce customers who are Payment Facilitators, as required by the Card Networks and Central Bank must submit new fields in transactional messaging. Cielo will send the information to the Card Networks through transactional messaging at the time of authorization.

The new fields are contained within the Payment Facilitator node. In addition to the fields of this new node, facilitators will also have to send the SoftDescriptor field of the Payment node.

  • Warning: If the card brands identify that the required data wasn’t sent in the transactional messaging, they will fine Cielo and these fines will be forwarded to the Facilitator responsible for sending the data.
  • As of April 15, 2023, Visa updated the rules for marketplace and every merchant who acts as Payment Facilitators and has clients (submerchants) who operate as foreigner marketplace must send the foreigner retail indicator to avoid charges from Visa. The specific parameter is Payment.PaymentFacilitator.SubEstablishment.CountryCode, which indicates the country code.

Request

{
  "MerchantOrderId": "2222222222",
  "Customer": {
    "Name": "Comprador Teste",
    "Identity": "11225468954",
    "IdentityType": "CPF",
    "Email": "compradorteste@teste.com",
    "Birthdate": "1991-01-02",
    "Address": {
      "Street": "Rua Teste",
      "Number": "123",
      "Complement": "AP 123",
      "ZipCode": "12345987",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BRA"
    },
    "DeliveryAddress": {
      "Street": "Rua Teste",
      "Number": "123",
      "Complement": "AP 123",
      "ZipCode": "12345987",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BRA"
    }
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 157000,
    "Currency": "BRL",
    "Country": "BRA",
    "Provider": "Cielo",
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": "ByMerchant",
    "Capture": false,
    "Authenticate": false,
    "Recurrent": false,
    "SoftDescriptor": "123456789ABCD",
    "CreditCard": {
      "CardNumber": "4024007197692931",
      "Holder": "Teste Holder",
      "ExpirationDate": "12/2021",
      "SecurityCode": "123",
      "SaveCard": "false",
      "Brand": "Visa"
    },
    "PaymentFacilitator": {
      "EstablishmentCode": "1234",
      "SubEstablishment": {
        "EstablishmentCode": "1234",
        "Identity": "11111111000100",
        "Mcc": "1234",
        "Address": "Alameda Grajau, 512",
        "City": "Barueri",
        "State": "SP",
        "CountryCode": "076",
        "PostalCode": "06455914",
        "PhoneNumber": "1155855585"
      }
    }
  }
}
Property Type Size Required Description
PaymentFacilitator.EstablishmentCode text* 11 Required for facilitators Facilitator’s establishment code. “Facilitator ID” (Registration of the facilitator with the card brands).
The code is different depending on the brand, varying even the size of the field:
MasterCard –06 digits
Visa –08 digits
ELO –from 04 to 05 digits
Hipercard –06 digits
For other brands, like Amex and JCB, the field can be filled in by “0” zeros.
PaymentFacilitator.SubEstablishment.EstablishmentCode text* 15 Required for facilitators Sub Merchant establishment code. “Sub-Merchant ID” (Registration of sub-accredited with the facilitator)
PaymentFacilitator.SubEstablishment.Identity text* 14 Required for facilitators CNPJ or CPF of the sub-merchant.
PaymentFacilitator.SubEstablishment.Mcc text* 4 Required for facilitators MCC do sub Merchant.
PaymentFacilitator.SubEstablishment.Address text* 22 Required for facilitators Sub Merchant Address.
PaymentFacilitator.SubEstablishment.City text* 13 Required for facilitators City of the sub Merchant.
PaymentFacilitator.SubEstablishment.State text* 2 Required for facilitators State do sub Merchant.
PaymentFacilitator.SubEstablishment.PostalCode text* 9 Required for facilitators Sub Merchant Postcode.
PaymentFacilitator.SubEstablishment.CountryCode text* 3 Required for facilitators Sub-merchant country code based on ISO 3166.
Ex: Brazil’s ISO 3166 code is 076. Complete list online
PaymentFacilitator.SubEstablishment.PhoneNumber text* 13 Required for facilitators Sub Merchant Phone Number.
Payment.Softdescriptor text* 13 Required for facilitators Text printed on buyer bank invoice. Must be completed according to the data of the sub Merchant.

*Avoid using accents as they are considered two characters.

Response

{
  "MerchantOrderId": "2014111701",
  "Customer": {
    "Name": "Comprador Teste",
    "Identity": "11225468954",
    "IdentityType": "CPF",
    "Email": "compradorteste@teste.com",
    "Birthdate": "1991-01-02",
    "Address": {
      "Street": "Rua Teste",
      "Number": "123",
      "Complement": "AP 123",
      "ZipCode": "12345987",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BRA"
    },
    "DeliveryAddress": {
      "Street": "Rua Teste",
      "Number": "123",
      "Complement": "AP 123",
      "ZipCode": "12345987",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BRA"
    }
  },
  "Payment": {
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": 0,
    "Capture": false,
    "Authenticate": false,
    "Recurrent": false,
    "CreditCard": {
      "CardNumber": "402400******2931",
      "Holder": "Teste Holder",
      "ExpirationDate": "12/2021",
      "SaveCard": false,
      "Brand": "Visa"
    },
    "Tid": "1223092935684",
    "ProofOfSale": "2935684",
    "AuthorizationCode": "065158",
    "SoftDescriptor": "123456789ABCD",
    "Provider": "Simulado",
    "IsQrCode": false,
    "PaymentFacilitator": {
      "EstablishmentCode": "1234",
      "SubEstablishment": {
        "EstablishmentCode": "1234",
        "Identity": "11111111000100",
        "Mcc": "1234",
        "Address": "Alameda Grajau, 512",
        "City": "Barueri",
        "State": "SP",
        "CountryCode": "076",
        "PostalCode": "06455914",
        "PhoneNumber": "1155855585"
      }
    },
    "Amount": 157000,
    "ReceivedDate": "2019-12-23 09:29:34",
    "Status": 1,
    "IsSplitted": false,
    "ReturnMessage": "Operation Successful",
    "ReturnCode": "4",
    "PaymentId": "365c3a0d-fd86-480b-9279-4ba3da21333c",
    "Type": "CreditCard",
    "Currency": "BRL",
    "Country": "BRA",
    "Links": [
      {
        "Method": "GET",
        "Rel": "self",
        "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/365c3a0d-fd86-480b-9279-4ba3da21333c"
      },
      {
        "Method": "PUT",
        "Rel": "capture",
        "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/365c3a0d-fd86-480b-9279-4ba3da21333c/capture"
      },
      {
        "Method": "PUT",
        "Rel": "void",
        "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/365c3a0d-fd86-480b-9279-4ba3da21333c/void"
      }
    ]
  }
}
Property Type Size Required Description
PaymentFacilitator.EstablishmentCode text* 11 Required for facilitators Facilitator’s establishment code. “Facilitator ID” (Registration of the facilitator with the card brands).
The code is different depending on the brand, varying even the size of the field:
MasterCard –06 digits
Visa –08 digits
ELO –from 04 to 05 digits
Hipercard –06 digits
For other brands, like Amex and JCB, the field can be filled in by “0” zeros.
PaymentFacilitator.SubEstablishment.EstablishmentCode text* 15 Required for facilitators Sub Merchant establishment code. “Sub-Merchant ID” (Registration of sub-accredited with the facilitator)
PaymentFacilitator.SubEstablishment.Identity text* 14 Required for facilitators CNPJ or CPF of the sub-merchant.
PaymentFacilitator.SubEstablishment.Mcc text* 4 Required for facilitators MCC do sub Merchant.
PaymentFacilitator.SubEstablishment.Address text* 22 Required for facilitators Sub Merchant Address.
PaymentFacilitator.SubEstablishment.City text* 13 Required for facilitators City of the sub Merchant.
PaymentFacilitator.SubEstablishment.State text* 2 Required for facilitators State do sub Merchant.
PaymentFacilitator.SubEstablishment.PostalCode text* 9 Required for facilitators Sub Merchant Postcode.
PaymentFacilitator.SubEstablishment.CountryCode text* 3 Required for facilitators Sub-merchant country code based on ISO 3166.
Ex: Brazil’s ISO 3166 code is 076. Complete list online
PaymentFacilitator.SubEstablishment.PhoneNumber text* 13 Required for facilitators Sub Merchant Phone Number.
Payment.Softdescriptor text* 13 Required for facilitators Text printed on buyer bank invoice. Must be completed according to the data of the sub Merchant.

*Avoid using accents as they are considered two characters.

CBPS Transactions

Entities that operate as CBPS (in Portuguese, Bill Payment Service for Consumers) are companies that offer consolidated bill payment services to the cardholder. CBPS Marking is a Visa-specific option and provides more visibility and accuracy in transactions.

Establishments that operate with this service must be registered with Visa and to operate as such, they must send some additional information through messenger, which is required by the brand. See below:

Request

{
  "merchantorderid": "123456ABCD1234",
  "customer": {
    "name": "João das Contas accept",
    "mobile": "5521923455678"
  },
  "payment": {
    "type": "CreditCard",
    "amount": 100,
    "installments": 1,
    "IsCustomerBillPaymentService": true,
    "capture": false,
    "authenticate": false,
    "recurrent": false,
    "provider": "CieloSandbox",
    "creditcard": {
      "cardnumber": "4532110000001234",
      "holder": "Teste Holder",
      "expirationdate": "12/2022",
      "securitycode": "123",
      "brand": "jcb",
      "savecard": true
    },
    "Wallet": {
      "AdditionalData": {
        "Mcc": "1234"
      }
    }
  }
}
Property Type Size Required Description
IsCustomerBillPaymentService boolean No True ou false. Indicates whether it’s a CBPS (Consumer Bill Payment Service) transaction
Wallet.AdditionalData.Mcc string (number) Yes, for CBPS transactions Establishment MCC (EC) allowed for CBPS transactions

SDWO Transactions

A SDWO (Staged Digital Wallet Operators) company offers e-wallet services, allowing the shopper to pay for a product or service through their own platform, with registered credit or debit cards or generating a QR Code.

To make transactions as a SDWO, the store needs to register it with the card brands. To do that, contact your commercial manager at Cielo for more information.

When the transactions at a SDWO e-commerce are made with a credit or debit card (not by QR Code), additional data is required so the card brands can identify this type of transaction. See the specifications below:

Besides the specific fields, for buying SDWO transactions it’s required for you to send the Soft Descriptor (Payment.SoftDescriptor) and the shopper’s CNPJ, if the shopper is a legal entity (fields Customer.Identity and Customer.IdentityType). See more details on the request fields table.

To run tests, you need to follow the Sandbox and tools.

To send the merchant’s MCC in the SDWO transaction, the market guidance is to use the ABECS (Brazilian Association of Credit Card and Services Companies) table, which makes the equivalence of CNAEs for MCCS across the industry. This table is constantly updated and is available online on the Abecs website at the following link: ABECS

Important: SDWO marking is only accepted for the following types and brands: Visa/Elo - credit and debit; Mastercard - credit only. Accepts foreign cards.

Request

{
  "MerchantOrderId": "2012345678",
  "Customer": {
    "Name": "Comprador Carteira",
    "Identity": "11225468954",
    "IdentityType": "CPF"
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 15700,
    "Installments": 1,
    "SoftDescriptor": "CARTEIRA*NOMELOJA",
    "CreditCard": {
      "CardNumber": "4532110000001234",
      "Brand": "Visa",
      "SecurityCode": "123"
    },
    "Wallet": {
      "PlatformOperator": "ABC",
      "AdditionalData": {
        "Mcc": "1234"
      }
    }
  }
}
Property Type Size Required Description
Wallet.PlatformOperator string (text) 3 Yes for SDWO transactions Acronym for the wallet that’s registered in Cielo (check with you commercial manager at Cielo)
Wallet.AdditionalData.Mcc string (number) 4 Yes for SDWO transactions Merchant’s MCC (for purchase transactions); E-wallet’s MCC (for credit supply transactions in the wallet, if applicable – in which the cash in markup also seen in this session is required)
Customer.Identity text 14 Yes for SDWO transactions Shopper’s CPF or CNPJ number
Customer.IdentityType text 255 Yes for SDWO transactions Shopper ID Type (CPF/CNPJ).
SoftDescriptor text 13 Yes for SDWO transactions Text that will be printed on the shopper’s bank invoice.
Does not allow special characters.
Needs to include Wallet name*merchant name.

Cash In Transactions

A Cash In transaction is when you add credit to a digital wallet. The merchants that operate this type of transaction should be registered as an E-Wallet with the card brands and should be registered with one of the following MCCs:

EC KEY MCC BRANDS
2000019700 8c08a0d0f00b73dedd2673a06fa725b0bd8edbf71c4c7dd0614bf408e4d16120 6051/6540/6538/4829 Mastercard
2000019700 8c08a0d0f00b73dedd2673a06fa725b0bd8edbf71c4c7dd0614bf408e4d16120 6051/6540 Visa
2000019853 8c08a0d0f00b73dedd2673a06fa725b0bd8edbf71c4c7dd0614bf408e4d16120 6051 Elo

In addition, you have to send some additional data in the transaction so that the brands can identify this type of transaction. See the specifications below:

In addition to the specific fields of this payment method, for Cash In transactions, it is also required to send the Soft Descriptor (Payment.SoftDescriptor) and the CPF or CNPJ of the shopper (Customer.Identity and Customer.IdentityType). In case of Cash In, the Soft Descriptor field should be filled in with name of e-wallet*name of shopper. See more details on the request fields table.

Important: Cash In booking is only accepted for the following types and brands: Visa/Mastercard credit only; Debit and credit link. Not accepted for foreign cards.

Request

{
  "MerchantOrderId": "2012345678",
  "Customer": {
    "Name": "Comprador Carteira",
    "Identity": "11225468954",
    "IdentityType": "CPF"
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 15700,
    "Installments": 1,
    "SoftDescriptor": "CARTEIRA*NOMEPORTADOR",
    "CreditCard": {
      "CardNumber": "4532110000001234",
      "Brand": "Visa",
      "SecurityCode": "123"
    },
    "Wallet": {
      "PlatformOperator": "ABC",
      "AdditionalData": {
        "CashIn": "true"
      }
    }
  }
}
Property Type Size Required Description
Wallet.PlatformOperator string (text) 3 Yes for Cash In transactions Acronym for the wallet that’s registered in Cielo (check with you commercial manager at Cielo)
Wallet.AdditionalData.CashIn string (text) Yes for Cash In transactions Enviar como “True” se for uma transação de Cash In  
Wallet.AdditionalData.Mcc string (number) 4 Yes for Cash In transactions MCC of the underlying merchant (for purchase transactions); MCC of the digital wallet (for credit supply transactions in the wallet, if applicable - in which it is necessary to mark cash in, also seen in this session)
Customer.Identity text 14 Yes for Cash In transactions Shopper’s CPF or CNPJ number.
Customer.IdentityType Text 255 Yes for Cash In transactions Shopper ID Type (CPF/CNPJ).
SoftDescriptor text 13 Yes for Cash In transactions Text that will be printed on the shopper’s bank invoice.
Does not allow special characters.
Needs to include Wallet name*merchant name.

Card tokenization

What is ** card tokenization**?

It is encryption that allows for secure credit card data storage. This data is transformed into an encrypted code called a “token”, which can be stored in a database. With the tokenization of cards, the merchant will be able to offer features like “1-click buy” and “Retry transaction sending”, always preserving the integrity and the confidentiality of the information.

Creating a tokenized card before authorization

To save a card without authorizing a transaction, simply make a tokenization request with the card data.

Request

{
  "CustomerName": "Comprador Teste Cielo",
  "CardNumber": "4532117080573700",
  "Holder": "Comprador T Cielo",
  "ExpirationDate": "12/2030",
  "Brand": "Visa"
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/card/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "CustomerName": "Comprador Teste Cielo",
    "CardNumber":"4532117080573700",
    "Holder":"Comprador T Cielo",
    "ExpirationDate":"12/2030",
    "Brand":"Visa"
}
--verbose
Property Type Size Required Description
Name Text 255 Yes Shopper’s name.
CardNumber Text 16 Yes Shopper’s Card Number.
Holder Text 25 Yes Shopper’s name printed on card.
ExpirationDate Text 7 Yes Expiry date printed on card.
Brand Text 10 Yes Card brand (Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover).

Response

{
  "CardToken": "db62dc71-d07b-4745-9969-42697b988ccb",
  "Links": {
    "Method": "GET",
    "Rel": "self",
    "Href": "https://apiquerydev.cieloecommerce.cielo.com.br/1/card/db62dc71-d07b-4745-9969-42697b988ccb"
  }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
  "CardToken": "db62dc71-d07b-4745-9969-42697b988ccb",
  "Links": {
    "Method": "GET",
    "Rel": "self",
    "Href": "https://apiquerydev.cieloecommerce.cielo.com.br/1/card/db62dc71-d07b-4745-9969-42697b988ccb"}
}
Property Description Type Size Format
Cardtoken Card identification token. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Creating a tokenized card during an authorization

To save a card as a token during a credit card transaction authorization, send the standard request for credit transaction and send the SaveCard field as “true”.

The response will return with the card token on the CardToken field.

Network tokenization

Some card brands offer a tokenization solution that tokenize and sotores card data in a network vault, in an encrypted form. Network tokenization is intended to improve the security and quality of card information transmitted, which leads to possible increases in the conversion of approval by issuing banks. See all the benefits:

How does it work?

The participating brands provide APIs for receiving and storing the card securely for acquirers, gateways and partners, with the creation of an exclusive token for that card at that merchant.

Cielo provides these services to clients in three ways:

Check below which parameters to send in the transaction request if the option chosen is external integration:

Request

{
  "MerchantOrderId": "2014111701",
  "Customer": {
    "Name": "Comprador Teste",
    "Email": "compradorteste@teste.com",
    "Birthdate": "1991-01-02",
    "Address": {
      "Street": "Rua Teste",
      "Number": "123",
      "Complement": "AP 123",
      "ZipCode": "12345987",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BRA"
    },
    "DeliveryAddress": {
      "Street": "Rua Teste",
      "Number": "123",
      "Complement": "AP 123",
      "ZipCode": "12345987",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BRA"
    }
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 15700,
    "Currency": "BRL",
    "Country": "BRA",
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": "ByMerchant",
    "Capture": true,
    "Authenticate": false,
    "SoftDescriptor": "123456789ABCD",
    "CreditCard": {
      "CardNumber": "1234123412341231",
      "Holder": "Teste Holder",
      "Cryptogram": "abcdefghijklmnopqrstuvw==",
      "ExpirationDate": "12/2030",
      "SecurityCode": "123",
      "SaveCard": "true",
      "Brand": "Visa"
    }
  }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
   "MerchantOrderId":"2014111701",
   "Customer":{
      "Name":"Comprador Teste",
      "Identity":"11225468954",
      "IdentityType":"CPF",
      "Email":"compradorteste@teste.com",
      "Birthdate":"1991-01-02",
      "Address":{
         "Street":"Rua Teste",
         "Number":"123",
         "Complement":"AP 123",
         "ZipCode":"12345987",
         "City":"Rio de Janeiro",
         "State":"RJ",
         "Country":"BRA"
      },
        "DeliveryAddress": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        }
   },
   "Payment":{
     "Type":"CreditCard",
     "Amount":15700,
     "ServiceTaxAmount":0,
     "Installments":1,
     "Interest":"ByMerchant",
     "Capture":true,
     "Authenticate":false,
     "SoftDescriptor":"123456789ABCD",
     "CreditCard":{
         "CardNumber":"4551870000000183",
         "Holder":"Teste Holder",
         "Cryptogram":"abcdefghijklmnopqrstuvw==",
         "ExpirationDate":"12/2030",
         "SecurityCode":"123",
         "SaveCard":"true",
         "Brand":"Visa"
     }
   }
}
--verbose
Property Type Size Required Description
Payment.CreditCard.CardNumber Text 19 Yes Token generated by the brand (DPAN). The indication that the CardNumber must be filled with the DPAN in case of brand tokenization.
Payment.CreditCard.Holder Text 25 No Shopper’s name printed on card.
Payment.CreditCard.Cryptogram Text 28 No Cryptogram generated by the card brand.
Payment.CreditCard.ExpirationDate Text 7 Yes Expiry date of token generated by brand.
Payment.CreditCard.SecurityCode Text 4 No Security code printed on back of card - See Annex.
Payment.CreditCard.SaveCard Boolean No (Default false) Boolean that identifies whether the card will be saved to generate the CardToken. Find out more about Tokenization of Cards.
Payment.CreditCard.Brand Text 10 Yes Card brand (Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard / Hiper).

Response

{
    "MerchantOrderId": "2014111706",
    "Customer": {
        "Name": "Comprador Teste",
        "Identity":"11225468954",
        "IdentityType":"CPF",
        "Email": "compradorteste@teste.com",
        "Birthdate": "1991-01-02",
        "Address": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "DeliveryAddress": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        }
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": true,
        "Authenticate": false,
        "CreditCard": {
            "CardNumber": "455187******0183",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": true,
            "CardToken": "d37bf475-307d-47be-b50a-8dcc38c5056c",
            "Brand": "Visa"
        },
        "ProofOfSale": "674532",
        "Tid": "0305020554239",
        "AuthorizationCode": "123456",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "CreditCard",
        "Amount": 15700,
        "CapturedAmount": 15700,
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 2,
        "ReturnCode": "6",
        "ReturnMessage": "Operation Successful",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            }
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2014111706",
    "Customer": {
        "Name": "Comprador Teste",
        "Identity":"11225468954",
        "IdentityType":"CPF",
        "Email": "compradorteste@teste.com",
        "Birthdate": "1991-01-02",
        "Address": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "DeliveryAddress": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        }
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": true,
        "Authenticate": false,
        "CreditCard": {
            "CardNumber": "455187******0183",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": true,
            "CardToken": "d37bf475-307d-47be-b50a-8dcc38c5056c"
            "Brand": "Visa"
        },
        "ProofOfSale": "674532",
        "Tid": "0305020554239",
        "AuthorizationCode": "123456",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "CreditCard",
        "Amount": 15700,
        "CapturedAmount": 15700,
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 2,
        "ReturnCode": "6",
        "ReturnMessage": "Operation Successful",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            }
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
Property Description Type Size Format
ProofOfSale Authorization number, identical to NSU. Text 6 Alphanumeric text
Tid Transaction Id on the acquirer. Text 20 Alphanumeric text
AuthorizationCode Authorization code. Text 6 Alphanumeric text
SoftDescriptor Text that will be printed on the carrier’s bank invoice - Available only for VISA/MASTER - does not allow special characters Text 13 Alphanumeric text
PaymentId Payment ID number. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ECI Eletronic Commerce Indicator. Represents how secure a transaction is. Text 2 Examples: 7
Status Transaction Status. Byte 2
ReturnCode Return code from the Acquirer. Text 32 Alphanumeric text
ReturnMessage Return message from the Acquirer. Text 512 Alphanumeric text
Cardtoken Card identification token. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Creating a sale with Tokenized Card

To create a tokenized credit card sale, submit a credit transaction requisition with CardToken as the following example.

Request

{
  "MerchantOrderId": "2014111706",
  "Customer": {
    "Name": "Comprador Teste"
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 100,
    "Installments": 1,
    "SoftDescriptor": "123456789ABCD",
    "CreditCard": {
      "CardToken": "6e1bf77a-b28b-4660-b14f-455e2a1c95e9",
      "SecurityCode": "262",
      "Brand": "Visa"
    }
  }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
   "MerchantOrderId":"2014111706",
   "Customer":{
      "Name":"Comprador Teste"
   },
   "Payment":{
     "Type":"CreditCard",
     "Amount":100,
     "Installments":1,
     "SoftDescriptor":"123456789ABCD",
     "CreditCard":{
         "CardToken":"6e1bf77a-b28b-4660-b14f-455e2a1c95e9",
         "SecurityCode":"262",
         "Brand":"Visa"
     }
   }
}
--verbose
Property Description Type Size Required
CreditCard.CardToken Card identification token. Guid 36 Yes
CreditCard.SecurityCode Security code printed on back of card. Text 4 No
CreditCard.Brand Card brand. Text 10 Yes

Response

{
  "MerchantOrderId": "2014111706",
  "Customer": {
    "Name": "Comprador Teste"
  },
  "Payment": {
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": "ByMerchant",
    "Capture": false,
    "Authenticate": false,
    "CreditCard": {
      "SaveCard": false,
      "CardToken": "6e1bf77a-b28b-4660-b14f-455e2a1c95e9",
      "Brand": "Visa"
    },
    "ProofOfSale": "5036294",
    "Tid": "0310025036294",
    "AuthorizationCode": "319285",
    "SoftDescriptor": "123456789ABCD",
    "PaymentId": "c3ec8ec4-1ed5-4f8d-afc3-19b18e5962a8",
    "Type": "CreditCard",
    "Amount": 100,
    "Currency": "BRL",
    "Country": "BRA",
    "ExtraDataCollection": [],
    "Status": 1,
    "Links": [
      {
        "Method": "GET",
        "Rel": "self",
        "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
      },
      {
        "Method": "PUT",
        "Rel": "capture",
        "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
      },
      {
        "Method": "PUT",
        "Rel": "void",
        "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
      }
    ]
  }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
        {
    "MerchantOrderId": "2014111706",
    "Customer": {
        "Name": "Comprador Teste"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": false,
        "Authenticate": false,
        "CreditCard": {
            "SaveCard": false,
            "CardToken": "6e1bf77a-b28b-4660-b14f-455e2a1c95e9",
            "Brand": "Visa"
        },
        "ProofOfSale": "5036294",
        "Tid": "0310025036294",
        "AuthorizationCode": "319285",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId": "c3ec8ec4-1ed5-4f8d-afc3-19b18e5962a8",
        "Type": "CreditCard",
        "Amount": 100,
        "Currency": "BRL",
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 1,
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            },
            {
                "Method": "PUT",
                "Rel": "capture",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
Property Description Type Size Format
ProofOfSale Authorization number, identical to NSU. Text 6 Alphanumeric text
Tid Transaction Id on the acquirer. Text 20 Alphanumeric text
AuthorizationCode Authorization code. Text 6 Alphanumeric text
SoftDescriptor Text that will be printed on the carrier’s bank invoice - Available only for VISA/MASTER - does not allow special characters Text 13 Alphanumeric text
PaymentId Order Identifier Field. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ECI Eletronic Commerce Indicator. Represents how secure a transaction is. Text 2 Examples: 7
Status Transaction Status. Byte 2
ReturnCode Return code of Acquiring. Text 32 Alphanumeric text
ReturnMessage Return message of Acquiring. Text 512 Alphanumeric texto

Card On File

What’s Card On File?

Card on File (COF) transactions are used by merchants to send financial and non financial (card validation) transactions with stored credentials.

Most of these transactions do not contain CVV as PCI rules prevent the establishment from storing this information. However, it is important to consider that a merchant may have validated the CVV in a previous transaction, such as the first Card On File transaction.

Examples of segments that use this type of modality are streaming services, education services, gyms and subscriptions, among others.

Why use Card On File?

Card On File allows for greater flexibility in online purchases, since it does not ask the cardholder to send all the data again (including the CVV); it is also possible to notice a better sales conversion rate since in the process for using the COF initiated by the merchant, necessarily, there is already a previous transaction initiated by the cardholder that already assists in the authorization of the transaction by the issuer.

Supported brands

Card On File supports the following brands:

For Card On File transactions with the Mastercard brand it is required to send the indicator node in the request (Payment.InitiatedTransactionIndicator), to inform whether the transaction was initiated by the shopper or by the store. Find out more at Mastercard Transaction Initiator Indicator.

Request

See an example of a Card on File credit transaction request.

{  
   "MerchantOrderId":"2014111701",
   "Customer":{  
      "Name":"Comprador crédito completo",
      "Email":"compradorteste@teste.com",
      "Birthdate":"1991-01-02"
   },
   "Payment":{  
     "Type":"CreditCard",
     "Amount":15700,
     "Currency":"BRL",
     "Country":"BRA",
     "Installments":1,
     "Interest":"ByMerchant",
     "Capture":true,
     "Authenticate":"false",
     "Recurrent":"true",
     "SoftDescriptor":"123456789ABCD",
     "CreditCard":{  
         "CardNumber":"1234123412341231",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"123",
         "SaveCard":"false",
         "Brand":"Visa",
         "CardOnFile":{
            "Usage": "First",
            "Reason":"Recurring"
         }
     }
   }
}
PROPERTY TYPE SIZE REQUIRED DESCRIPTION
MerchantOrderId Text 50 Yes Order ID number.
Customer.Name Text 255 No Customer’s name.
Customer.Status Text 255 No The customer’s registration status on the store. (NEW / EXISTING)
Customer.Email Text 255 No Customer’s email
Customer.Birthdate Date 10 No Customer’s birthdate (AAAA/MM/DD).
Payment.Type Text 100 Yes Type of the Payment Method.
Payment.Amount Number 15 Yes Order Amount (to be sent in cents).
Payment.Currency Text 3 No Currency in which the payment will be made (BRL).
Payment.Country Text 3 No Country in which the payment will be made.
Payment.SoftDescriptor Text 13 No The store’s name that will be on the shopper’s bank invoice. Does not allow special characters.
Payment.Installments Number 2 Yes Number of installments. If the transaction is a recurrence, the number of installments will be 1. For installment transactions, the number of installments will be greater than 1.
Payment.Interest Text 10 No Type of installments - Store (ByMerchant) or Card (ByIssuer).
Payment.Capture Boolean No (Default false) Boolean that identifies if the authorization should be done by authomatic capture (true) or posterior capture (false).
Payment.Recurrent Boolean - Conditional Indicates if the transaction is recurring (“true”) or not (“false”). The value “true” won’t originate a new recurrence, it will only allow a transaction without the need to send the security code. Authenticate should be “false” if Recurrent is “true”. Find out more about Recurring Payments.
CreditCard.CardNumber Text 19 Yes Shopper’s card number.
CreditCard.Holder Text 25 No Name of the shopper that’s printed on the card. Does not accept special characters.
CreditCard.ExpirationDate Text 7 Yes Expiration date printed on the card. Example: MM/AAAA.
CreditCard.SecurityCode Text 4 No Security code printed on the back of the card.
CreditCard.SaveCard Boolean No (Default false) Boolean that identifies if the card will be saved to generate a CardToken. Find out more about Tokenization of Cards.
CreditCard.Brand Text 10 Yes Card brand. Possible values: Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard / Hiper.
CreditCard.CardOnFile.Usage Text - No “First” if the card was stored and it’s your first use. “Used” if the card was stored and has been used for another transaction before.
CreditCard.CardOnFile.Reason Text - Conditional Indicates the motive for card storage, if the CardOnFile.Usage field is “Used”.
Recurring: programmed recurring transaction (e.g. Subscriptions). If it is a recurring transaction, use Payment.Recurrent = true (merchant recurrence) or Recurrent.Payment = true (scheduled recurrence).
Unscheduled: recurring transaction with no fixed date (e.g. service apps).
Installments: installments through recurring transactions.

Response

{
    "MerchantOrderId": "2014111701",
    "Customer": {
        "Name": "Comprador crédito completo",
        "Email": "compradorteste@teste.com",
        "Birthdate": "1991-01-02"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": 0,
        "Capture": true,
        "Authenticate": false,
        "Recurrent": true,
        "CreditCard": {
            "CardNumber": "123412******1231",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa",
            "CardOnFile": {
                "Usage": "First",
                "Reason": "Recurring"
            },
            "PaymentAccountReference": "JZHOZJHNZH87KQXM3G60B9I21GVZN"
        },
        "Tid": "0928084922246",
        "ProofOfSale": "652515",
        "AuthorizationCode": "927181",
        "SoftDescriptor": "123456789ABCD",
        "Provider": "Simulado",
        "IsQrCode": false,
        "DynamicCurrencyConversion": false,
        "Amount": 15700,
        "ReceivedDate": "2022-09-28 08:49:22",
        "CapturedAmount": 15700,
        "CapturedDate": "2022-09-28 08:49:22",
        "Status": 2,
        "IsSplitted": false,
        "ReturnMessage": "Operation Successful",
        "ReturnCode": "6",
        "PaymentId": "91bad53a-9198-4738-a280-f51dddc34988",
        "Type": "CreditCard",
        "Currency": "BRL",
        "Country": "BRA",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/91bad53a-9198-4738-a280-f51dddc34988"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/91bad53a-9198-4738-a280-f51dddc34988/void"
            }
        ]
    }
}
PROPERTY DESCRIPTION TYPE SIZE FORMAT
ProofOfSale Authorization number, identical to NSU. Text 6 Alphanumeric text
Tid Transaction Id on the acquirer. Text 20 Alphanumeric text
AuthorizationCode Authorization code. Text 6 Alphanumeric text
SoftDescriptor Text that will be printed on the carrier’s bank invoice. Does not allow special characters. Text 13 Alphanumeric text
PaymentId Payment ID number, needed for future operations like Consulting, Capture and Cancellation. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ECI Eletronic Commerce Indicator. Indicates how safe a transaction is. Text 2 Example: 7
Status Transaction status. Byte 2
ReturnCode Acquiring return code. Text 32 Alphanumeric text
ReturnMessage Acquiring return message. Text 512 Alphanumeric text
Payment.MerchantAdviceCode Card brand’s return code that defines the period for transaction submission retry. Valid only for Mastercard. Text 2 Numeric
CreditCard.PaymentAccountReference PAR (payment account reference) is the number that associates different tokens to the same card. It will be returned by the Master and Visa brands and passed on to Cielo e-commerce customers. If the card brand doesn’t send the information the field will not be returned. If it is a debit transaction, include inside the DebitCard node. Alphanumeric 29

Recurring Payments

Recurring payments are credit card transactions that repeat themselves after a certain period of time.

This type of payment is usually used for streaming services, education services, gyms and subscriptions, where the shopper wants to be automatically charged but doesn’t want to re-enter the card details.

Types of recurrences

API E-commerce Cielo works with two types of Recurrences:

Merchant Recurrence

In this format, the merchant is responsible for creating intelligence to:

Intelligence Description
Save transaction data The merchant will need to store the transaction and payment data.
Create transactional repetition The merchant must sent a new transaction whenever it needs an authorization.
Procedure for declined transaction If one of the transactions is declined, it will be up to the store to “retry” a new authorization.

In all instances, the scheduled recurrence is a default transaction for Cielo, its only difference being the need to send an additional parameter that defines it as Merchant Recurrence:
>
> Parameter: Payment.Recurrent= True

Flow recorrência própria

Merchant Recurrence example

This is an example of how API E-commerce Cielo allows the use of external recurrence systems in your transactions.

Merchant recurrence is a configuration of the API E-commerce Cielo that allows a merchant to use an internal recurrence system specific to their business needs.

In this model, the merchant’s system is responsible for defining the period, the transactional data, and, when necessary, sending us the recurrence transaction.

Merchant Recurence + Tokenized Card

A gym called Cleverfit has a specific billing system, where the client is charged every fifteen days, but never on weekends.

As a highly customized model, CleverFit has its own recurrence system, using the API E-commerce Cielo via two mechanisms:

  1. Merchant Recurrence - CleverFit sends the transaction data as a normal sale, but the API identifies it as a recurrence and applies differential authorization rules to the order.
  2. Tokenized Card - CleverFit keeps cards stored in a tokenized form at Cielo, according to security rules, avoiding storing card data in their system.

CleverFit sends the transaction every fifteen days to the API E-commerce Cielo, using the tokens saved in the API itself and opting for Merchant Recurrence, which changes the authorization rules to suit its billing model.

Scheduled Recurrence

In this model, Cielo is responsible for the intelligence necessary to perform a recurrence automatically.

The Scheduled Recurrence allows the merchant to create a base transaction that, when sent to the API E-commerce Cielo, will be saved and executed following the rules defined by the merchant.

To learn more about configuring a scheduled recurrence, access Backoffice API Cielo.

In this model, the API performs and allows:

Advantages Description
Saves transactional data Save transaction data, thus creating a model of what the next recurrences will look like.
Automates the recurrence Without the need for merchant action, the API creates future transactions according to the store’s definitions.
Allows updating of data If necessary, the API allows modifications in the transaction information (such as shopper data) or recurrence cycle (such as billing date).

The Scheduled Recurrence has two request flows; the difference is in the AuthorizeNow parameter.

When the first transaction must be authorized at the time of scheduling, please send AuthorizeNow as “true”.

Flow da primeira transação na hora do agendamento

*If Post Notification was enabled by the merchant.

When the first transaction must be authorized after scheduling, send AuthorizeNow as “false”; in this case, also send the StartDate parameter.

Flow da transação posterior ao agendamento

*To schedule the transaction needs the RecurrentPayment node, the transaction date and the AuthorizeNow field as “false”.
**If Post Notification was enabled by the merchant.

See the example of the snippet with the RecurrentPayment node, which must be inserted in a credit transaction.

"RecurrentPayment":
{
       "AuthorizeNow":"False",
       "StartDate":"2019-06-01"
       "EndDate":"2019-12-01",
       "Interval":"SemiAnnual"
}

Where can we define the data as:

Parameters Description
AuthorizeNow Defines the time a recurrence will be created. If it is sent as True, it is created at the time of authorization, if sent as false False, the recurrence will be suspended until the date chosen to be initiated.
StartDate Defines the date on which the Scheduled Recurrence transaction will be authorized.
EndDate Defines the date the Scheduled Recurrence will end. If it is not sent, the Recurrence will be executed until it is canceled by the merchant.
Interval Recurrence interval.
Monthly Bimonthly Quarterly SemiAnnual Annual

When a transaction is sent to the API E-commerce Cielo with the Scheduled Recurrence node (RecurrentPayment), the recurrence process becomes effective when the transaction is considered AUTHORIZED. From that point on, the transaction will occur within the interval defined by the merchant.

Important features of Scheduled Recurrence:

Information Description
Creation The first transaction is called “Scheduling Transaction”, all subsequent transactions will be copies of the first transaction. It does not need to be captured for the recurrence to be created, it just needs to be AUTHORIZED
Capture Scheduled Recurrence transactions do not need to be captured. After the first transaction, all recurrence transactions are automatically captured by the API.
Identification Scheduled Recurrence transactions generate two types of identification:
PaymentId: Identifies a transaction. It is the same identifier as the other transactions in the API
RecurrentPaymentId: Identifies recurrence order. A RecurrentPaymentID has many PaymentId’s linked to it. This is the variable used to Cancel a Scheduled Recurrence.
Consulting To consult, just use one of two types of identification:
PaymentId: Used to consult A TRANSACTION WITHIN THE RECURRENCE
RecurrentPaymentId: Used to consult THE RECURRENCE.
Canceling A Scheduled Recurrence can be canceled in two ways:
Merchant: When the merchant requests the canceling of the recurrence. You can’t cancel transactions already finalized before the recurrence cancelation order.
By invalid card: If the API identifies that a saved card is invalid (e.g.: Expired) the recurrence will be canceled and will not be repeated until the merchant updates the payment method.
NOTE: Canceling transactions within the recurrence does not end the scheduling of future transactions. Only the Cancellation using the RecurrentPaymentID ends future schedules.

RecurrentPaymentID Structure

Estrutura do RecurrentPaymentID

Scheduled Recurrence example

This is an example of how to use API E-commerce Cielo recurrences to increase your sales:

Recurrence is the process of saving a transaction and repeating it at a predefined time interval. Ideal for subscription model.

Cielo’ Scheduled Recurrence has the following characteristics:

Monthly and annual recurrence

Musicfy offers an online subscription service where their customers pay to be able to access a music library and listen to them via streaming.

To capture as many customers as possible, they offer two payment methods:

How do they bill their customers monthly or yearly?

Musicfy uses API E-commerce Cielo’s Scheduled Recurrence.

When creating a transaction, Musicfy informs the client that the order in question will be repeated monthly or annually and that there is no end date for the billing.

What are the advantages of using scheduled recurrence for MusicFy?

  1. Practicality: The monthly charge is automatic, so MusicFy does not have to worry about building a billing system.

  2. Usability: The subscription value can be updated without having to redo the transaction. A month can be canceled or the recurrence can have a delay (the 30-day free model) with only one setting.

  3. Safety: MusicFy does not need to store sensitive card and shopper data.

  4. Conversion: Cielo’s Scheduled Recurrence has an automatic retry system. If one of the transactions is denied, it will be retried up to four times, seeking to achieve authorization.

Creating Recurrences

Marking a recurrence is important for the security of a recurring transaction, so that it is not denied due to suspected fraud. Therefore:

Creating a Merchant Recurrence

To create a recurring sale in which recurrence and interval process will be performed by the store itself, just make a POST as in the example.

The request follows the structure of a standard credit transaction, but the Payment.Recurrent parameter must be true; otherwise, the transaction will be denied.

Request

{
  "MerchantOrderId": "2014113245231706",
  "Customer": {
    "Name": "Comprador rec propria"
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 1500,
    "Installments": 1,
    "SoftDescriptor": "123456789ABCD",
    "Recurrent": true,
    "CreditCard": {
      "CardNumber": "1234123412341231",
      "Holder": "Teste Holder",
      "ExpirationDate": "12/2030",
      "SecurityCode": "262",
      "SaveCard": "false",
      "Brand": "Visa"
    }
  }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
    {
   "MerchantOrderId":"2014113245231706",
   "Customer":{
      "Name":"Comprador rec propria"
   },
   "Payment":{
     "Type":"CreditCard",
     "Amount":1500,
     "Installments":1,
     "SoftDescriptor":"123456789ABCD",
     "Recurrent": true,
     "CreditCard":{
         "CardNumber":"1234123412341231",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"262",
         "SaveCard":"false",
         "Brand":"Visa"
     }
   }
}
--verbose
Property Description Type Size Required
MerchantId Merchant identifier in API E-commerce Cielo. Guid 6 Yes
MerchantKey Public Key for Double Authentication in API E-commerce Cielo. Text 40 Yes
RequestId Request identifier, used when the merchant uses different servers for each GET/POST/PUT. Guid 36 No
MerchantOrderId Order ID number. Text 50 Yes
Customer.Name Shopper’s name. Text 255 Yes
Payment.Type Type of the Payment Method. Text 100 Yes
Payment.Amount Order Amount (to be sent in cents). Number 15 Yes
Payment.Installments Number of installments. As this is a recurrence, the number of installments will be 1. Number 2 Yes
Payment.SoftDescriptor Text that will be printed on the shopper’s bank invoice - Available only for VISA/MASTER - does not allow special characters Text 13 No
Payment.Recurrent Indicates an unscheduled recurrence transaction. Boolean 5 Yes
CreditCard.CardNumber Shopper’s Card Number. Text 19 Yes
CreditCard.Holder Shopper’s name printed on card. Text 25 No
CreditCard.ExpirationDate Expiration date printed on card. Text 7 Yes
CreditCard.SecurityCode Security code printed on back of card. Text 4 No
CreditCard.Brand Card brand. Text 10 Yes

Response

{
    "MerchantOrderId": "2014113245231706",
    "Customer": {
        "Name": "Comprador rec propria"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": false,
        "Authenticate": false,
        "Recurrent": true,
        "CreditCard": {
            "CardNumber": "123412******1231",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa"
        },
        "ProofOfSale": "3827556",
        "Tid": "0504043827555",
        "AuthorizationCode": "149867",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId": "737a8d9a-88fe-4f74-931f-acf81149f4a0",
        "Type": "CreditCard",
        "Amount": 1500,
        "Currency": "BRL",
        "Country": "BRA",
        "Provider": "Simulado",
        "ExtraDataCollection": [],
        "Status": 1,
        "ReturnCode": "4",
        "ReturnMessage": "Operation Successful",
        "Link": {
                "Method": "GET",
                "Rel": "recurrentPayment",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}"
            },
            "AuthorizeNow": true
        },
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            },
            {
                "Method": "PUT",
                "Rel": "capture",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2014113245231706",
    "Customer": {
        "Name": "Comprador rec propria"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": false,
        "Authenticate": false,
        "Recurrent": true,
        "CreditCard": {
            "CardNumber": "123412******1231",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa"
        },
        "ProofOfSale": "3827556",
        "Tid": "0504043827555",
        "AuthorizationCode": "149867",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId": "737a8d9a-88fe-4f74-931f-acf81149f4a0",
        "Type": "CreditCard",
        "Amount": 1500,
        "Currency": "BRL",
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 1,
        "ReturnCode": "4",
        "ReturnMessage": "Operation Successful",
        "Link": {
                "Method": "GET",
                "Rel": "recurrentPayment",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}"
            },
            "AuthorizeNow": true
        },
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            },
            {
                "Method": "PUT",
                "Rel": "capture",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
Property Description Type Size Required
MerchantId Store identifier in API E-commerce Cielo. Guid 6 Yes
MerchantKey Public Key for Double Authentication in API E-commerce Cielo. Text 40 Yes
RequestId Request identifier, used when the merchant uses different servers for each GET/POST/PUT. Guid 36 No
MerchantOrderId Order ID number. Text 50 Yes
Customer.Name Shopper’s name. Text 255 No
Payment.Type Type of the Payment Method. Text 100 Yes
Payment.Amount Order Amount (to be sent in cents). Number 15 Yes
Payment.Installments Number of installments. As this is a recurrence, the number of installments will be 1. Number 2 Yes
Payment.SoftDescriptor Text that will be printed on the carrier’s bank invoice - Available only for VISA/MASTER - does not allow special characters Text 13 No
Payment.Recurrent Indicates an unscheduled recurrence transaction. Boolean 5 Yes
CreditCard.CardNumber Shopper’s Card Number. Text 19 Yes
CreditCard.Holder Shopper’s name printed on card. Text 25 No
CreditCard.ExpirationDate Expiration date printed on card. Text 7 Yes
CreditCard.SecurityCode Security code printed on back of card. Text 4 No
CreditCard.Brand Card brand. Text 10 Yes

Creating a Scheduled Recurrence

To create a recurring sale in which the first recurrence is authorized with the credit card payment method, just make a POST as in the example.

Request

{
  "MerchantOrderId": "2014113245231706",
  "Customer": {
    "Name": "Comprador rec programada"
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 1500,
    "Installments": 1,
    "SoftDescriptor": "123456789ABCD",
    "RecurrentPayment": {
      "AuthorizeNow": "true",
      "EndDate": "2019-12-01",
      "Interval": "SemiAnnual"
    },
    "CreditCard": {
      "CardNumber": "1234123412341231",
      "Holder": "Teste Holder",
      "ExpirationDate": "12/2030",
      "SecurityCode": "262",
      "SaveCard": "false",
      "Brand": "Visa"
    }
  }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
    {
   "MerchantOrderId":"2014113245231706",
   "Customer":{
      "Name":"Comprador rec programada"
   },
   "Payment":{
     "Type":"CreditCard",
     "Amount":1500,
     "Installments":1,
     "SoftDescriptor":"123456789ABCD",
     "RecurrentPayment":{
       "AuthorizeNow":"true",
       "EndDate":"2019-12-01",
       "Interval":"SemiAnnual"
     },
     "CreditCard":{
         "CardNumber":"1234123412341231",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"262",
         "SaveCard":"false",
         "Brand":"Visa"
     }
   }
}
--verbose
Property Description Type Size Required
MerchantId Store identifier in API E-commerce Cielo. Guid 6 Yes
MerchantKey Public Key for Double Authentication in API E-commerce Cielo. Text 40 Yes
RequestId Request identifier, used when the merchant uses different servers for each GET/POST/PUT. Guid 36 No
MerchantOrderId Order ID number. Text 50 Yes
Customer.Name Shopper’s name. Text 255 Yes
Payment.Type Type of the Payment Method. Text 100 Yes
Payment.Amount Order Amount (to be sent in cents). Number 15 Yes
Payment.Installments Number of installments. As this is a recurrence, the number of installments will be 1. Number 2 Yes
Payment.SoftDescriptor Text that will be printed on the carrier’s bank invoice - Available only for VISA/MASTER - does not allow special characters Text 13 No
Payment.RecurrentPayment.EndDate End date for recurrence. Text 10 No
Payment.RecurrentPayment.Interval Recurrence interval.
Monthly (Default) Bimonthly Quarterly SemiAnnual Annual
Text 10 No
Payment.RecurrentPayment.AuthorizeNow Boolean to know if the first recurrence is going to be Authorized or not. Boolean Yes
CreditCard.CardNumber Shopper’s Card Number. Text 19 Yes
CreditCard.Holder Shopper’s name printed on card. Text 25 No
CreditCard.ExpirationDate Expiration date printed on card. Text 7 Yes
CreditCard.SecurityCode Security code printed on back of card. Text 4 No
CreditCard.Brand Card brand. Text 10 Yes

Response

{
  "MerchantOrderId": "2014113245231706",
  "Customer": {
    "Name": "Comprador rec programada"
  },
  "Payment": {
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": "ByMerchant",
    "Capture": false,
    "Authenticate": false,
    "Recurrent": false,
    "CreditCard": {
      "CardNumber": "123412******1231",
      "Holder": "Teste Holder",
      "ExpirationDate": "12/2030",
      "SaveCard": false,
      "Brand": "Visa"
    },
    "ProofOfSale": "3827556",
    "Tid": "0504043827555",
    "AuthorizationCode": "149867",
    "SoftDescriptor": "123456789ABCD",
    "PaymentId": "737a8d9a-88fe-4f74-931f-acf81149f4a0",
    "Type": "CreditCard",
    "Amount": 1500,
    "Currency": "BRL",
    "Country": "BRA",
    "Provider": "Simulado",
    "ExtraDataCollection": [],
    "Status": 1,
    "ReturnCode": "4",
    "ReturnMessage": "Operation Successful",
    "RecurrentPayment": {
      "RecurrentPaymentId": "61e5bd30-ec11-44b3-ba0a-56fbbc8274c5",
      "NextRecurrency": "2015-11-04",
      "EndDate": "2019-12-01",
      "Interval": "SemiAnnual",
      "Link": {
        "Method": "GET",
        "Rel": "recurrentPayment",
        "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}"
      },
      "AuthorizeNow": true
    },
    "Links": [
      {
        "Method": "GET",
        "Rel": "self",
        "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
      },
      {
        "Method": "PUT",
        "Rel": "capture",
        "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
      },
      {
        "Method": "PUT",
        "Rel": "void",
        "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
      }
    ]
  }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2014113245231706",
    "Customer": {
        "Name": "Comprador rec programada"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": false,
        "Authenticate": false,
        "Recurrent": false,
        "CreditCard": {
            "CardNumber": "123412******1231",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa"
        },
        "ProofOfSale": "3827556",
        "Tid": "0504043827555",
        "AuthorizationCode": "149867",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId": "737a8d9a-88fe-4f74-931f-acf81149f4a0",
        "Type": "CreditCard",
        "Amount": 1500,
        "Currency": "BRL",
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 1,
        "ReturnCode": "4",
        "ReturnMessage": "Operation Successful",
        "RecurrentPayment": {
            "RecurrentPaymentId": "61e5bd30-ec11-44b3-ba0a-56fbbc8274c5",
            "NextRecurrency": "2015-11-04",
            "EndDate": "2019-12-01",
            "Interval": "SemiAnnual",
            "Link": {
                "Method": "GET",
                "Rel": "recurrentPayment",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}"
            },
            "AuthorizeNow": true
        },
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            },
            {
                "Method": "PUT",
                "Rel": "capture",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
Property Description Type Size Format
RecurrentPaymentId Next recurrence Identifier field. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
NextRecurrency Date of next recurrence. Text 7 12/2030 (MM/YYYY)
EndDate End date of recurrence. Text 7 12/2030 (MM/YYYY)
Interval Interval between recurrences. Text 10 MonthlyBimonthly Quarterly SemiAnnual Annual
AuthorizeNow Boolean to know if the first recurrence is about to be Authorized or not. Boolean true ou false

Scheduling a Scheduled Recurrence

To create a recurring sale in which the first recurrence will not be authorized on the same date with the credit card payment method, just make a POST as in the example.

Before setting up a scheduled recurrence, use Zero Auth to validate the card. This way, you can guarantee that you are scheduling a recurrence with a valid card.

Unlike the previous recurrence, this example does not authorize immediately, it schedules a future authorization. To schedule the first transaction in the series of recurrences, send the AuthorizeNow parameter as “false” and add the StartDate parameter.

Request

{
  "MerchantOrderId": "2014113245231706",
  "Customer": {
    "Name": "Comprador rec programada"
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 1500,
    "Installments": 1,
    "SoftDescriptor": "123456789ABCD",
    "RecurrentPayment": {
      "AuthorizeNow": "false",
      "EndDate": "2019-12-01",
      "Interval": "SemiAnnual",
      "StartDate": "2015-06-01"
    },
    "CreditCard": {
      "CardNumber": "1234123412341231",
      "Holder": "Teste Holder",
      "ExpirationDate": "12/2030",
      "SecurityCode": "262",
      "SaveCard": "false",
      "Brand": "Visa"
    }
  }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
   "MerchantOrderId":"2014113245231706",
   "Customer":{
      "Name":"Comprador rec programada"
   },
   "Payment":{
     "Type":"CreditCard",
     "Amount":1500,
     "Installments":1,
     "SoftDescriptor":"123456789ABCD",
     "RecurrentPayment":{
       "AuthorizeNow":"false",
       "EndDate":"2019-12-01",
       "Interval":"SemiAnnual",
       "StartDate":"2015-06-01"
     },
     "CreditCard":{
         "CardNumber":"1234123412341231",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"262",
         "SaveCard":"false",
         "Brand":"Visa"
     }
   }
}
--verbose
Property Description Type Size Required
MerchantId Store identifier in API E-commerce. Guid 36 Yes
MerchantKey Public Key for Double Authentication in API E-commerce Cielo. Text 40 Yes
RequestId Request identifier, used when the merchant uses different servers for each GET/POST/PUT. Guid 36 No
RecurrentPaymentId Recurrence identification number. Text 50 Yes
Customer.Name Shopper’s name. Text 255 No
Customer.Status Shopper registration status in store (NEW / EXISTING) - Used by fraud analysis Text 255 No
Customer.Email Shopper’s e-mail. Text 255 No
Customer.Birthdate Shopper’s date of birth (AAAA/MM/DD). Date 10 No
Customer.Identity Shopper’s RG, CPF or CNPJ number. Text 14 No
Customer.Address.Street Shopper’s address. Text 255 No
Customer.Address.Number Shopper’s address number. Text 15 No
Customer.Address.Complement Shopper’s address complement. Text 50 No
Customer.Address.ZipCode Shopper’s address zip code. Text 9 No
Customer.Address.City Shopper’s address city. Text 50 No
Customer.Address.State Shopper’s address state. Text 2 No
Customer.Address.Country Shopper’s address country. Text 35 No
Customer.Address.District Shopper’s neighborhood. Text 50 No
Customer.DeliveryAddress.Street Shopper’s address. Text 255 No
Customer.DeliveryAddress.Number Shopper’s address number. Text 15 No
Customer.DeliveryAddress.Complement Shopper’s address complement. Text 50 No
Customer.DeliveryAddress.ZipCode Shopper’s address zip code. Text 9 No
Customer.DeliveryAddress.City Shopper’s address city. Text 50 No
Customer.DeliveryAddress.State Shopper’s address state. Text 2 No
Customer.DeliveryAddress.Country Shopper’s address country. Text 35 No
Customer.DeliveryAddress.District Shopper’s neighborhood. Text 50 No

Response

{
  "MerchantOrderId": "2014113245231706",
  "Customer": {
    "Name": "Comprador rec programada"
  },
  "Payment": {
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": "ByMerchant",
    "Capture": false,
    "Authenticate": false,
    "Recurrent": false,
    "CreditCard": {
      "CardNumber": "123412******1231",
      "Holder": "Teste Holder",
      "ExpirationDate": "12/2030",
      "SaveCard": false,
      "Brand": "Visa"
    },
    "SoftDescriptor": "123456789ABCD",
    "Type": "CreditCard",
    "Amount": 1500,
    "Currency": "BRL",
    "Country": "BRA",
    "ExtraDataCollection": [],
    "Status": 20,
    "RecurrentPayment": {
      "RecurrentPaymentId": "0d2ff85e-594c-47b9-ad27-bb645a103db4",
      "NextRecurrency": "2015-06-01",
      "StartDate": "2015-06-01",
      "EndDate": "2019-12-01",
      "Interval": "SemiAnnual",
      "Link": {
        "Method": "GET",
        "Rel": "recurrentPayment",
        "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{PaymentId}"
      },
      "AuthorizeNow": false
    }
  }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2014113245231706",
    "Customer": {
        "Name": "Comprador rec programada"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": false,
        "Authenticate": false,
        "Recurrent": false,
        "CreditCard": {
            "CardNumber": "123412******1231",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa"
        },
        "SoftDescriptor":"123456789ABCD",
        "Type": "CreditCard",
        "Amount": 1500,
        "Currency": "BRL",
        "Country": "BRA",
        "Provider": "Simulado",
        "ExtraDataCollection": [],
        "Status": 20,
        "RecurrentPayment": {
            "RecurrentPaymentId": "0d2ff85e-594c-47b9-ad27-bb645a103db4",
            "NextRecurrency": "2015-06-01",
            "StartDate": "2015-06-01",
            "EndDate": "2019-12-01",
            "Interval": "SemiAnnual",
            "Link": {
                "Method": "GET",
                "Rel": "recurrentPayment",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{PaymentId}"
            },
            "AuthorizeNow": false
        }
    }
}
Property Description Type Size Format
RecurrentPaymentId Next recurrence Identifier field. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
NextRecurrency Date of next recurrence. Text 7 12/2030 (MM/YYYY)
StartDate Start date of recurrence. Text 7 12/2030 (MM/YYYY)
EndDate End date of recurrence. Text 7 12/2030 (MM/YYYY)
Interval Interval between recurrences. Text 10 MonthlyBimonthly Quarterly SemiAnnual Annual
AuthorizeNow Boolean to know if the first recurrence is about to be Authorized or not. Boolean true ou false

Issuer transaction Id

The issuer transaction Id is an authentication code for recurrent or stored credential transactions returned in the authorization or card validation response (Zero Auth).

Identificador Bandeira

  1. The merchant sends request for first transaction authorization or card validation (ZeroAuth);
  2. Cielo E-Commerce API requests authorization for acquirer, card brand, and issuer;
  3. The card brand authorizes transaction or validates card and returns IssuerTransactionId;
  4. Cielo E-Commerce API returns IssuerTransactionId to the merchant;
  5. In the next requests, the merchant sends IssuerTransactionId obtained from the first or following transactions.

Why sending the issuer transaction Id?

The issuer transaction Id is important to improve authorization rates, because when the current transaction is related to the previous one, the issuer is able to identify that there has already been a previous transaction initiated by the cardholder.

The issuer transaction Id returned in the last transaction must be informed in the next requests.

Supported card brands:

Response example

The IssuerTransactionId is returned:

Note: The IssuerTransactionId value may be different in each response for an authorization or card validation.

Please refer to the default request examples in Creating a credit card transaction or Validating a card with Zero Auth.

See below a response example for a credit card transaction returning the IssuerTransactionId:

{  
   "MerchantOrderId":"2014111701",
   "Payment":{  
     "Type":"CreditCard",
     "Amount":15700,
     "Capture":true,
     "Recurrent":"true",
     "IssuerTransactionId": "580027442382078",
     "Installments" 1,
     "CreditCard":{  
         "CardNumber":"1234123412341231",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SaveCard":"false",
         "Brand":"Visa",
         "CardOnFile":{
            "Usage": "Used",
            "Reason":"Recurring"
         }
     }
   }
}
PROPRIERTY TYPE SIZE REQUIRED DESCRIPTION
MerchantOrderId text 50 Yes Order Id number.
Payment.Type text 100 Yes Type of the payment method.
Payment.Amount number 15 Sim Order Amount (to be sent in cents).
Payment.Installments number 2 Sim Number of installments. If the transaction is a recurrence, the number of installments will be 1. For installment transactions, the number of installments will be greater than 1.
Payment.Capture boolean No (Default false) Boolean that identifies if the authorization should be done by Authomatic capture (“true”) or posterior capture(“false”).
Payment.IssuerTransactionId text - Conditional Issuer authentication identifier for recurring credit and debit transactions. This field must be sent in subsequent transactions of the first transaction in the self-recurrence model. In the programmed recurrence model, Cielo will be responsible for sending the field in subsequent transactions.
Payment.Recurrent boolean - No Indicates if the transaction is recurring (“true”) or not (“false”). The value “true” won’t originate a new recurrence, it will only allow a transaction without the need to send the security code. Authenticate should be “false” if Recurrent is “true”. Find out more about Recurring Payments.
Payment.CreditCard.CardNumber text 19 Yes Shopper’s card number.
Payment.CreditCard.Holder text 25 No Name of the shopper that’s printed on the card. Does not accept special characters.
Payment.CreditCard.ExpirationDate text 7 Yes Expiration date printed on the card. Example: MM/AAAA.
Payment.CreditCard.SecurityCode text 4 No Security code printed on the back of the card.
Payment.CreditCard.SaveCard boolean No (Default false) Boolean that identifies if the card will be saved to generate a CardToken. Find out more about Tokenization of Cards.
Payment.CreditCard.Brand text 10 Yes Card brand. Possible values: Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard / Hiper.
Payment.CreditCard.CardOnFile.Usage text - No First if the card was stored and it’s your first use.
Used if the card was stored and has been used for another transaction before. Find out more about Card On File.
Payment.CreditCard.CardOnFile.Reason text - Conditional Indicates the motive for card storage, if the “Usage” field is “Used”.
Recurring - Programmed recurring transaction (e.g. Subscriptions). If it is a recurring transaction, use Payment.Recurrent = true (merchant recurrence) or Recurrent.Payment = true (scheduled recurrence).
Unscheduled - Recurring transaction with no fixed date (e.g. service apps)
Installments - Installments through recurring transactions. Get more information on the topic Card On File

Modifying Recurrences

Modifying shopper data

To change the shopper’s data for the recurrent transactions, just do a PUT as in the example.

Request

{
  "Name": "Customer",
  "Email": "customer@teste.com",
  "Birthdate": "1999-12-12",
  "Identity": "22658954236",
  "IdentityType": "CPF",
  "Address": {
    "Street": "Rua Teste",
    "Number": "174",
    "Complement": "AP 201",
    "ZipCode": "21241140",
    "City": "Rio de Janeiro",
    "State": "RJ",
    "Country": "BRA"
  },
  "DeliveryAddress": {
    "Street": "Outra Rua Teste",
    "Number": "123",
    "Complement": "AP 111",
    "ZipCode": "21241111",
    "City": "Qualquer Lugar",
    "State": "QL",
    "Country": "BRA",
    "District": "Teste"
  }
}
curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}/Customer"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
      "Name":"Customer",
      "Email":"customer@teste.com",
      "Birthdate":"1999-12-12",
      "Identity":"22658954236",
      "IdentityType":"CPF",
      "Address":{
         "Street":"Rua Teste",
         "Number":"174",
         "Complement":"AP 201",
         "ZipCode":"21241140",
         "City":"Rio de Janeiro",
         "State":"RJ",
         "Country":"BRA"
      },
      "DeliveryAddress":{
         "Street":"Outra Rua Teste",
         "Number":"123",
         "Complement":"AP 111",
         "ZipCode":"21241111",
         "City":"Qualquer Lugar",
         "State":"QL",
         "Country":"BRA",
        "District":"Teste"
      }
   }
--verbose
Property Description Type Size Required
MerchantId Store identifier in API E-commerce Cielo. Guid 36 Yes
MerchantKey Public Key for Double Authentication in API E-commerce Cielo. Text 40 Yes
RequestId Request Identifier, used when the merchant uses different servers for each GET/POST/PUT. Guid 36 No
RecurrentPaymentId Recurrence identification number. Text 50 Yes
Customer.Name Shopper’s name. Text 255 No
Customer.Status Shopper registration status in store (NEW / EXISTING) - Used by fraud analysis Text 255 No
Customer.Email Shopper’s e-mail. Text 255 No
Customer.Birthdate Shopper’s date of birth (AAAA/MM/DD). Date 10 No
Customer.Identity Shopper’s RG, CPF or CNPJ number. Text 14 No
Customer.IdentityType Text 255 No Type of shopper ID document (CFP/CNPJ).
Customer.Address.Street Shopper’s address. Text 255 No
Customer.Address.Number Shopper’s address number. Text 15 No
Customer.Address.Complement Shopper’s address complement. Text 50 No
Customer.Address.ZipCode Shopper’s address zip code. Text 9 No
Customer.Address.City Shopper’s address city. Text 50 No
Customer.Address.State Shopper’s address state. Text 2 No
Customer.Address.Country Shopper’s address country. Text 35 No
Customer.Address.District Shopper’s neighborhood. Text 50 No
Customer.DeliveryAddress.Street Shopper’s address. Text 255 No
Customer.DeliveryAddress.Number Shopper’s address number. Text 15 No
Customer.DeliveryAddress.Complement Shopper’s address complement. Text 50 No
Customer.DeliveryAddress.ZipCode Shopper’s address zip code. Text 9 No
Customer.DeliveryAddress.City Shopper’s address city. Text 50 No
Customer.DeliveryAddress.State Shopper’s address state. Text 2 No
Customer.DeliveryAddress.Country Shopper’s address country. Text 35 No
Customer.DeliveryAddress.District Shopper’s neighborhood. Text 50 No

Response


HTTP Status 200

See HTTP Status Code for the list with all HTTP status codes possibly returned by the API.

Modifying end date of Recurrence

To change the end date of the Recurrence, just do a PUT as in the example.

Request

"2021-01-09"
curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}/EndDate"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
"2021-01-09"
--verbose
Property Description Type Size Required
MerchantId Store identifier in API E-commerce Cielo. Guid 36 Yes
MerchantKey Public Key for Double Authentication in API E-commerce Cielo. Text 40 Yes
RequestId Request Identifier, used when the merchant uses different servers for each GET/POST/PUT. Guid 36 No
RecurrentPaymentId Recurrence identification number. Text 50 Yes
EndDate End date for recurrence. Text 10 Yes

Response

HTTP Status 200

See HTTP Status Code for the list with all HTTP status codes possibly returned by the API.

Modifying Recurrence interval

To change the Recurrence Interval, just do a PUT as in the example.

Request

6
curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}/Interval"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
6
--verbose
Property Description Type Size Request
MerchantId Store identifier in API E-commerce Cielo. Guid 36 Yes
MerchantKey Public Key for Double Authentication in API E-commerce Cielo. Text 40 Yes
RequestId Request Identifier, used when the merchant uses different servers for each GET/POST/PUT. Guid 36 No
RecurrentPaymentId Recurrence identification number. Text 50 Yes
Interval Recurrence interval. MonthlyBimonthly Quarterly SemiAnnual Annual Number 2 Yes

Response

HTTP Status 200

See HTTP Status Code for the list with all HTTP status codes possibly returned by the API.

Modify day of Recurrence

To modify the day of recurrence, just do a PUT as in the example.

When changing the day of recurrence, consider the following rules for executing the update in the API:

  1. If the new day entered is after the current day, we will update the day of the recurrence with effect on the next recurrence. Ex.: Today is May 5 and the next recurrence is May 25. When updated to the 10th, the next recurrence date will be the on May 10.

  2. If the new day entered is before the current day, we will update the day of the recurrence, but this will only take effect after the next recurrence is successfully executed. Ex.: Today is May 5 and the next recurrence is May 25. When updated to the 3rd, the date of the next recurrence will remain on May 25. After its execution, the next recurrence will be scheduled for June 3.

  3. If the new day entered is before the current day, but the next recurrence is in another month, we will update the day of the recurrence with effect on the next recurrence. Ex.: Today is May 5 and the next recurrence is September 25. When updated to the 3rd, the date of the next recurrence will be September 3.

Request

16
curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}/RecurrencyDay"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
16
--verbose
Property Description Type Size Required
MerchantId Store identifier in API E-commerce Cielo. Guid 36 Yes
MerchantKey Public Key for Double Authentication in API E-commerce Cielo. Text 40 Yes
RequestId Request Identifier, used when the merchant uses different servers for each GET/POST/PUT. Guid 36 No
RecurrentPaymentId Recurrence identification number. Text 50 Yes
RecurrencyDay Recurrence day. Number 2 Yes

Response

HTTP Status 200

See HTTP Status Code for the list with all HTTP status codes possibly returned by the API.

Modifying the Recurrence value

To modify the value of the recurrence, just do a PUT as in the example.

Request

156
curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}/Amount"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
156
--verbose
Property Description Type Size Required
MerchantId Store identifier in API E-commerce Cielo. Guid 36 Yes
MerchantKey Public Key for Double Authentication in API E-commerce Cielo. Text 40 Yes
RequestId Request Identifier, used when the merchant uses different servers for each GET/POST/PUT. Guid 36 No
RecurrentPaymentId Recurrence identification number. Text 50 Yes
Payment.Amount Order Value in cents; 156 equals R$ 1,56. Number 15 Yes

Response

HTTP Status 200

See HTTP Status Code for the list with all HTTP status codes possibly returned by the API.

Modifying date of next payment

To change the date of the next payment, just do a PUT as in the example.

Request

"2016-06-15"
curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}/NextPaymentDate"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
"2016-06-15"
--verbose
Property Description Type Size Required
MerchantId Store identifier in API E-commerce Cielo. Guid 36 Yes
MerchantKey Public Key for Double Authentication in API E-commerce Cielo. Text 40 Yes
RequestId Request Identifier, used when the merchant uses different servers for each GET/POST/PUT. Guid 36 No
RecurrentPaymentId Recurrence identification number. Text 50 Yes
NextPaymentDate Payment date of the next recurrence. Text 10 Yes

Response

HTTP Status 200

See HTTP Status Code for the list with all HTTP status codes possibly returned by the API.

Modifying Recurrence payment data

To change the payment data of the recurrence, just do a PUT as in the example.

Request

{
  "Type": "CreditCard",
  "Amount": "123",
  "Installments": 3,
  "Country": "USA",
  "Currency": "BRL",
  "SoftDescriptor": "123456789ABCD",
  "CreditCard": {
    "Brand": "Master",
    "Holder": "Teset card",
    "CardNumber": "1234123412341232",
    "ExpirationDate": "12/2030"
  }
}
curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}/Payment"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
   "Type":"CreditCard",
   "Amount":"123",
   "Installments":3,
   "Country":"USA",
   "Currency":"BRL",
   "SoftDescriptor":"123456789ABCD",
   "CreditCard":{
      "Brand":"Master",
      "Holder":"Teset card",
      "CardNumber":"1234123412341232",
      "ExpirationDate":"12/2030"
   }
}
--verbose
Property Description Type Size Required
MerchantId Store identifier in API E-commerce Cielo. Guid 36 Yes
MerchantKey Public Key for Double Authentication in API E-commerce Cielo. Text 40 Yes
RequestId Request Identifier, used when the merchant uses different servers for each GET/POST/PUT. Guid 36 No
RecurrentPaymentId Recurrence identification number. Text 50 Yes
Payment.Type Type of the Payment Method. Text 100 Yes
Payment.Amount Order Amount (to be sent in cents). Number 15 Yes
Payment.Installments Number of installments. As this is a recurrence, the number of installments will be 1. Number 2 Yes
Payment.SoftDescriptor Text that will be printed on the carrier’s bank invoice - Available only for VISA/MASTER - does not allow special characters Text 13 No
CreditCard.CardNumber Shopper’s Card Number. Text 16 Yes
CreditCard.Holder Shopper’s name printed on card. Text 25 No
CreditCard.ExpirationDate Expiry date printed on card. Text 7 Yes
CreditCard.SecurityCode Security code printed on back of card Text 4 No
CreditCard.Brand Card brand. Text 10 Yes

Response

HTTP Status 200

See HTTP Status Code for the list with all HTTP status codes possibly returned by the API.

Disabling a Recurrent Order

To disable a recurrent order, just do a PUT as in the example.

Request

curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}/Deactivate"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
--verbose
Property Description Type Size Required
MerchantId Store identifier in API E-commerce Cielo. Guid 36 Yes
MerchantKey Public Key for Double Authentication in API E-commerce Cielo. Text 40 Yes
RequestId Request Identifier, used when the merchant uses different servers for each GET/POST/PUT. Guid 36 No
RecurrentPaymentId Recurrence identification number. Text 50 Yes

Response

HTTP Status 200

See HTTP Status Code for the list with all HTTP status codes possibly returned by the API.

Rehabilitating a Recurrent Order

To rehabilitate a recurring order, just do a PUT as in the example.

Request

curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}/Reactivate"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
--verbose
Property Description Type Size Required
MerchantId Store identifier in API E-commerce Cielo. Guid 36 Yes
MerchantKey Public Key for Double Authentication in API E-commerce Cielo. Text 40 Yes
RequestId Request Identifier, used when the merchant uses different servers for each GET/POST/PUT. Guid 36 No
RecurrentPaymentId Recurrence identification number. Text 50 Yes

Response

HTTP Status 200

See HTTP Status Code for the list with all HTTP status codes possibly returned by the API.

Retries

What is a retry?

Retrying is resubmitting a rejected transaction to obtain approval. To retry, it is important that the denied transaction response code is considered by the brand as reversible.

What is the impact of retrying on my business?

Retrying can bring a positive result and convert sales that were initially denied. However, excessive retries can harm the establishment in the eyes of issuers and brands, reducing the establishment’s approval rate and/or generating a fine for retrying when not permitted.

When to retry?

It is allowed to retry when the response code is reversible. The retry strategy must also take into account the response code for each brand.

Examples:

Therefore, pay attention to the transaction response to develop a good retry strategy. See other response codes and their characteristics in Return Codes ABECS.

Excessive unapproved attempts may result in fines. Read more at Programa de Retentativa das Bandeiras.

Is it possible to configure automatic retries?

For Scheduled Recurrence, it is possible to leave up to four retries enabled automatically. See how to set it up in Backoffice API Cielo.

Renova Fácil

Renova Fácil is a service developed by Cielo together with issuers. The objective of the service is to increase the conversion rate of recurring transactions with credit cards.

Using this functionality allows the automatic replacement of a credit card that has been replaced by the issuing bank for some reason (expiry date, exchange, etc.). This way, when a recurrent transaction is submitted to the API and Cielo identifies that the card sent has been replaced, authorization will be denied and the API will return the new card data in the NewCard node. When you receive the new card details, you will need to send a new authorization request with the new card details..

Below is an example of a response to a credit transaction with the node NewCard.

Request

{
  "MerchantOrderId": "2014113245231706",
  "Customer": {
    "Name": "Comprador Renova facil"
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 1500,
    "Installments": 1,
    "SoftDescriptor": "123456789ABCD",
    "RecurrentPayment": {
      "AuthorizeNow": "true",
      "EndDate": "2019-12-01",
      "Interval": "SemiAnnual"
    },
    "CreditCard": {
      "CardNumber": "1234123412341231",
      "Holder": "Teste Holder",
      "ExpirationDate": "12/2030",
      "SecurityCode": "262",
      "SaveCard": "false",
      "Brand": "Visa"
    }
  }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
    {
   "MerchantOrderId":"2014113245231706",
   "Customer":{
      "Name":"Comprador Renova facil"
   },
   "Payment":{
     "Type":"CreditCard",
     "Amount":1500,
     "Installments":1,
     "SoftDescriptor":"123456789ABCD",
     "RecurrentPayment":{
       "AuthorizeNow":"true",
       "EndDate":"2019-12-01",
       "Interval":"SemiAnnual"
     },
     "CreditCard":{
         "CardNumber":"1234123412341231",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"262",
         "SaveCard":"false",
         "Brand":"Visa"
     }
   }
}
--verbose
Property Description Type Size Required
MerchantId Store identifier in API E-commerce Cielo. Guid 6 Yes
MerchantKey Public Key for Double Authentication in API E-commerce Cielo. Text 40 Yes
RequestId Request Identifier, used when the merchant uses different servers for each GET/POST/PUT Guid 36 No
MerchantOrderId Order ID number. Text 50 Yes
Customer.Name Shopper’s name. Text 255 No
Customer.Status Shopper’s registration status in store (NEW / EXISTING) - Used by fraud analysis Text 255 No
Payment.Type Type of the Payment Method. Text 100 Yes
Payment.Amount Order Amount (to be sent in cents). Number 15 Yes
Payment.Installments Number of installments. If the transaction is a recurrence, the number of installments will be 1. For installment transactions, the number of installments will be greater than 1. Number 2 Yes
Payment.SoftDescriptor Text that will be printed on the shopper’s bank invoice - Available only for VISA/MASTER - does not allow special characters Text 13 No
Payment.RecurrentPayment.EndDate End date for recurrence. Text 10 No
Payment.RecurrentPayment.Interval Recurrence interval.
Monthly (Default) Bimonthly Quarterly SemiAnnual Annual
Text 10 No
Payment.RecurrentPayment.AuthorizeNow Boolean to know if the first recurrence is about to be Authorized or not. Boolean Yes
CreditCard.CardNumber Shopper’s Card Number. Text 19 Yes
CreditCard.Holder Shopper’s name printed on card. Text 25 No
CreditCard.ExpirationDate Expiry date printed on card. Text 7 Yes
CreditCard.SecurityCode Security code printed on back of card. Text 4 No
CreditCard.Brand Card brand. Text 10 Yes

Response

{
  "MerchantOrderId": "2014113245231706",
  "Customer": {
    "Name": "Comprador  Renova facil"
  },
  "Payment": {
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": 0,
    "Capture": false,
    "Authenticate": false,
    "Recurrent": false,
    "CreditCard": {
      "CardNumber": "123412******1231",
      "Holder": "Teste Holder",
      "ExpirationDate": "12/2030",
      "SaveCard": false,
      "Brand": "Visa"
    },
    "Tid": "10447480685P4611AQ9B",
    "ProofOfSale": "087001",
    "SoftDescriptor": "123456789ABCD",
    "Provider": "Cielo",
    "Eci": "0",
    "NewCard": {
      "CardNumber": "40000000000000000",
      "ExpirationDate": "10/2020",
      "SaveCard": false,
      "Brand": "Visa"
    },
    "VelocityAnalysis": {
      "Id": "94f06657-c715-45d2-a563-63f7dbb19e08",
      "ResultMessage": "Accept",
      "Score": 0
    },
    "PaymentId": "94f06657-c715-45d2-a563-63f7dbb19e08",
    "Type": "CreditCard",
    "Amount": 1500,
    "ReceivedDate": "2016-12-26 14:14:21",
    "Currency": "BRL",
    "Country": "BRA",
    "ReturnCode": "KA",
    "ReturnMessage": "Autorizacao negada",
    "Status": 3,
    "RecurrentPayment": {
      "ReasonCode": 7,
      "ReasonMessage": "Declined",
      "EndDate": "2019-12-01",
      "Interval": 6,
      "AuthorizeNow": true
    },
    "Links": [
      {
        "Method": "GET",
        "Rel": "self",
        "Href": "https://apiquery.cieloecommerce.cielo.com.br/1/sales/94f06657-c715-45d2-a563-63f7dbb19e08"
      }
    ]
  }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
  "MerchantOrderId": "2014113245231706",
  "Customer": {
    "Name": "Comprador  Renova facil"
  },
  "Payment": {
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": 0,
    "Capture": false,
    "Authenticate": false,
    "Recurrent": false,
    "CreditCard": {
      "CardNumber": "123412******1231",
      "Holder": "Teste Holder",
      "ExpirationDate": "12/2030",
      "SaveCard": false,
      "Brand": "Visa"
    },
    "Tid": "10447480685P4611AQ9B",
    "ProofOfSale": "087001",
    "SoftDescriptor": "123456789ABCD",
    "Provider": "Cielo",
    "Eci": "0",
 "NewCard": {
       "CardNumber": "40000000000000000",
       "ExpirationDate": "10/2020",
       "SaveCard": false,
        "Brand": "Visa"
    },
    "VelocityAnalysis": {
      "Id": "94f06657-c715-45d2-a563-63f7dbb19e08",
      "ResultMessage": "Accept",
      "Score": 0
    },
    "PaymentId": "94f06657-c715-45d2-a563-63f7dbb19e08",
    "Type": "CreditCard",
    "Amount": 1500,
    "ReceivedDate": "2016-12-26 14:14:21",
    "Currency": "BRL",
    "Country": "BRA",
    "ReturnCode": "KA",
    "ReturnMessage": "Autorizacao negada",
    "Status": 3,
    "RecurrentPayment": {
      "ReasonCode": 7,
      "ReasonMessage": "Declined",
      "EndDate": "2019-12-01",
      "Interval": 6,
      "AuthorizeNow": true
    },
    "Links": [
      {
        "Method": "GET",
        "Rel": "self",
        "Href": "https://apiquery.cieloecommerce.cielo.com.br/1/sales/94f06657-c715-45d2-a563-63f7dbb19e08"
      }
    ]
  }
}
Property Description Type Size Format
RecurrentPaymentId Next recurrence Identifier field. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
NextRecurrency Date of next recurrence. Text 7 12/2030 (MM/YYYY)
EndDate End date of recurrence. Text 7 12/2030 (MM/YYYY)
Interval Interval between recurrences. Text 10 MonthlyBimonthly Quarterly SemiAnnual Annual
AuthorizeNow Boolean to know if the first recurrence is about to be Authorized or not. Boolean true ou false
Property Description Type Size Required
NewCard.CardNumber Shopper’s new card number. Text 16 Yes
NewCard.ExpirationDate New expiry date of the card. Text 7 Yes
NewCard.Brand Card brand. Text 10 Yes
NewCard.SaveCard Identifies whether the card generated Cardtoken during the transaction. Find out more about Tokenization of Cards Boolean Yes

Card Brands and Issuers Enabled

Card Brands and Issuers that are already with Renova Fácil enabled:

Issuers VISA MASTER ELO
BRADESCO Yes Yes Yes
BANCO DO BRASIL Yes
SANTANDER Yes
CITI Yes
BANCO PAN Yes

Queries, Capture and Cancellation

Getting details on transactions

Searching for a transaction via PaymentId

To get details on a sale via PaymentId, follow the request example below.

Request

curl
--request GET "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
--verbose
Property Description Type Size Required
MerchantId Store identifier in API E-commerce Cielo. Guid 36 Yes
MerchantKey Public Key for Double Authentication in API E-commerce Cielo. Text 40 Yes
RequestId Request Identifier, used when the merchant uses different servers for each GET/POST/PUT. Guid 36 No
PaymentId Payment identification number. Text 36 Yes

Response

}
"MerchantOrderId": "2014111706",
"AcquirerOrderId": "202202231037440D1BD0",
"Customer": {
    "Name": "Comprador Teste",
    "Address": {}
},
"Payment": {
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": "ByMerchant",
    "Capture": false,
    "Authenticate": false,
    "CreditCard": {
        "CardNumber": "455187******0183",
        "Holder": "Teste Holder",
        "ExpirationDate": "12/2030",
        "SaveCard": false,
        "Brand": "Visa",
        "PaymentAccountReference":"92745135160550440006111072222"
    },
    "ProofOfSale": "674532",
    "Tid": "0223103744208",
    "AuthorizationCode": "123456",
    "Chargebacks": [
        {
            "Amount": 10000,
            "CaseNumber": "123456",
            "Date": "2022-06-04",
            "ReasonCode": "104",
            "ReasonMessage": "Outras Fraudes - Cartao Ausente",
            "Status": "Received",
            "RawData": "Client did not participate and did not authorize transaction"
        }
    ],
    "FraudAlert": {
        "Date": "2022-05-20",
        "ReasonMessage": "Uso Ind Numeração",
        "IncomingChargeback": false
    },
    "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
    "Type": "CreditCard",
    "Amount": 10000,
    "ReceivedDate": "2022-07-29 17:16:21",
    "CapturedAmount": 9000,
    "CapturedDate": "2022-07-29 17:16:22",
    "VoidedAmount": 1000,
    "VoidedDate": "2022-05-15 16:25:38",
    "Currency": "BRL",
    "Country": "BRA",
    "ExtraDataCollection": [],
    "Status": 1,
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
        },
        {
            "Method": "PUT",
            "Rel": "capture",
            "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
        },
        {
            "Method": "PUT",
            "Rel": "void",
            "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
        }
    ]
}
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2014111706",
    "AcquirerOrderId": "202202231037440D1BD0",
    "Customer": {
        "Name": "Comprador Teste",
        "Address": {}
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": false,
        "Authenticate": false,
        "CreditCard": {
            "CardNumber": "455187******0183",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa",
            "PaymentAccountReference":"92745135160550440006111072222"
        },
        "ProofOfSale": "674532",
        "Tid": "0223103744208",
        "AuthorizationCode": "123456",
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "CreditCard",
        "Amount": 10000,
        "ReceivedDate": "2022-07-29 17:16:21",
        "CapturedAmount": 9000,
        "CapturedDate": "2022-07-29 17:16:22",
        "VoidedAmount": 1000,
        "VoidedDate": "2022-05-15 16:25:38",
        "Currency": "BRL",
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 1,
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            },
            {
                "Method": "PUT",
                "Rel": "capture",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
Property Description Type Size Format
MerchantOrderId Order identification number. Text 50 Text alphanumeric
AcquirerOrderId Transaction Id sent to the authorizer if the MerchantOrderId is longer than 20 characters or has symbols. Text 50 Text alphanumeric
AuthorizationCode Authorization code. Text 6 Text alphanumeric
PaymentId Order Identifier Field. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Status Transaction Status. Byte 2 -
Customer.Name Shopper name. Text 255 -
Customer.Status Shopper registration status in the store (NEW / EXISTING). Text 255 -
Payment.ProofOfSale Authorization number, identical to NSU. Text 6 Text alphanumeric
Payment.Tid Transaction Id in the payment method provider. Text 40 Text alphanumeric
Payment.Type Type of payment method. Text 100 -
Payment.Amount Order Amount (to be shipped in cents). Number 15 -
Payment.ReceivedDate Date when the transaction was received. Text 19 AAAA-MM-DD HH:mm:SS
Payment.CapturedAmount Captured value. Number 15 10000
Payment.CapturedDate Capture date. Text 19 AAAA-MM-DD HH:mm:SS
Payment.VoidedAmount Canceled/refunded amount, in cents. Number 15 10000
Payment.VoidedDate Date of cancellation/chargeback. Text 19 AAAA-MM-DD HH:mm:SS
Payment.Provider Defines behavior of the means of payment (see files attached)/NOT MANDATORY FOR CREDIT. Text 15 -
Payment.EndToEndId Identification number for a Pix transaction. Text 50 Text alphanumeric
CreditCard.CardNumber Shopper’s Card Number Text 19 -
CreditCard.Holder Shopper’s name printed on card Text 25 -
CreditCard.ExpirationDate Expiration date printed on card. Text 7 -
CreditCard.SecurityCode Security code printed on the back of the card. Text 4 -
CreditCard.Brand Card brand. Text 10 -
CreditCard.PaymentAccountReference PAR (Payment Account Reference) is the number that associates different tokens to the same card. It will be returned by the Master and Visa brands and passed on to E-commerce Cielo customers. If the brand does not send the information, the field will not be returned. Number 29 -

Searching for a transaction via TId

To get details on transaction using the TId number, follow the request example..

Request

curl
--request GET "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/acquirerTid/{TID}"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
--verbose
Property Description Type Size Required
MerchantId Store identifier in API E-commerce Cielo. Guid 36 Yes
MerchantKey Public Key for Double Authentication in API E-commerce Cielo. Text 40 Yes
RequestId Request Identifier, used when the merchant uses different servers for each GET/POST/PUT. Guid 36 No
AcquirerOrderId Transaction Id sent to the authorizer if the MerchantOrderId is longer than 20 characters or has symbols. Text 50 Yes
TId Payment identification number at the acquirer. Text 36 Sim

Response

}
"MerchantOrderId": "2014111706",
"AcquirerOrderId": "202202231037440D1BD0",
"Customer": {
    "Name": "Comprador Teste",
    "Address": {}
},
"Payment": {
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": "ByMerchant",
    "Capture": false,
    "Authenticate": false,
    "CreditCard": {
        "CardNumber": "455187******0183",
        "Holder": "Teste Holder",
        "ExpirationDate": "12/2030",
        "SaveCard": false,
        "Brand": "Visa",
        "PaymentAccountReference":"92745135160550440006111072222"
    },
    "ProofOfSale": "674532",
    "Tid": "0223103744208",
    "AuthorizationCode": "123456",
    "Chargebacks": [
        {
            "Amount": 10000,
            "CaseNumber": "123456",
            "Date": "2022-06-04",
            "ReasonCode": "104",
            "ReasonMessage": "Outras Fraudes - Cartao Ausente",
            "Status": "Received",
            "RawData": "Client did not participate and did not authorize transaction"
        }
    ],
    "FraudAlert": {
        "Date": "2022-05-20",
        "ReasonMessage": "Uso Ind Numeração",
        "IncomingChargeback": false
    },
    "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
    "Type": "CreditCard",
    "Amount": 10000,
    "ReceivedDate": "2022-07-29 17:16:21",
    "CapturedAmount": 9000,
    "CapturedDate": "2022-07-29 17:16:22",
    "VoidedAmount": 1000,
    "VoidedDate": "2022-05-15 16:25:38",
    "Currency": "BRL",
    "Country": "BRA",
    "ExtraDataCollection": [],
    "Status": 1,
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
        },
        {
            "Method": "PUT",
            "Rel": "capture",
            "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
        },
        {
            "Method": "PUT",
            "Rel": "void",
            "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
        }
    ]
}
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2014111706",
    "AcquirerOrderId": "202202231037440D1BD0",
    "Customer": {
        "Name": "Comprador Teste",
        "Address": {}
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": false,
        "Authenticate": false,
        "CreditCard": {
            "CardNumber": "455187******0183",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa",
            "PaymentAccountReference":"92745135160550440006111072222"
        },
        "ProofOfSale": "674532",
        "Tid": "0223103744208",
        "AuthorizationCode": "123456",
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "CreditCard",
        "Amount": 10000,
        "ReceivedDate": "2022-07-29 17:16:21",
        "CapturedAmount": 9000,
        "CapturedDate": "2022-07-29 17:16:22",
        "VoidedAmount": 1000,
        "VoidedDate": "2022-05-15 16:25:38",
        "Currency": "BRL",
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 1,
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            },
            {
                "Method": "PUT",
                "Rel": "capture",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
Property Description Type Size Format
MerchantOrderId Order identification number. Text 50 Alphanumeric
AcquirerOrderId Transaction Id sent to the authorizer if the MerchantOrderId is longer than 20 characters or has symbols. Text 50 Alphanumeric
AuthorizationCode Authorization code. Text 6 Alphanumeric
PaymentId Order Identifier Field. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Status Transaction Status. Byte 2 -
Customer.Name Shopper name. Text 255 -
Customer.Status Shopper registration status in the store (NEW / EXISTING). Text 255 -
Payment.ProofOfSale Authorization number, identical to NSU. Text 6 Alphanumeric
Payment.Tid Transaction Id in the payment method provider. Text 40 Alphanumeric
Payment.Type Type of payment method. Text 100 -
Payment.Amount Order Amount (to be shipped in cents). Number 15 -
Payment.ReceivedDate Date when the transaction was received. Text 19 AAAA-MM-DD HH:mm:SS
Payment.CapturedAmount Captured value. Number 15 10000
Payment.CapturedDate Capture date. Text 19 AAAA-MM-DD HH:mm:SS
Payment.VoidedAmount Canceled/refunded amount, in cents. Number 15 10000
Payment.VoidedDate Date of cancellation/chargeback. Text 19 AAAA-MM-DD HH:mm:SS
Payment.Provider Defines behavior of the means of payment (see files attached)/NOT MANDATORY FOR CREDIT. Text 15 -
Payment.EndToEndId Identification number for a Pix transaction. Text 50 Text alphanumeric
CreditCard.CardNumber Shopper’s Card Number Text 19 -
CreditCard.Holder Shopper’s name printed on card Text 25 -
CreditCard.ExpirationDate Expiration date printed on card. Text 7 -
CreditCard.SecurityCode Security code printed on the back of the card. Text 4 -
CreditCard.Brand Card brand. Text 10 -
CreditCard.PaymentAccountReference PAR (Payment Account Reference) is the number that associates different tokens to the same card. It will be returned by the Master and Visa brands and passed on to E-commerce Cielo customers. If the brand does not send the information, the field will not be returned. Number 29 -

Searhing for a transaction via MerchandOrderID

For some merchants, the MerchantOrderId may have multiple transactions. The query for MerchantOrderId returns the PaymentId of all transactions associated with a MerchantOrderId.

Considering this, it is possible to query details of each transaction by searching with PaymentId

Request

curls
--request GET " https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales?merchantOrderId={merchantOrderId}"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
--verbose
Property Description Type Size Required
MerchantId Store identifier in API E-commerce Cielo. Guid 36 Yes
MerchantKey Public Key for Double Authentication in API E-commerce Cielo. Text 40 Yes
RequestId Request Identifier, used when the merchant uses different servers for each GET/POST/PUT Guid 36 No
MerchantOrderId Order Identifier Field at the Store. Text 36 Yes

Response

{
  "Payment": [
    {
      "PaymentId": "5fb4d606-bb63-4423-a683-c966e15399e8",
      "ReceveidDate": "2015-04-06T10:13:39.42"
    },
    {
      "PaymentId": "6c1d45c3-a95f-49c1-a626-1e9373feecc2",
      "ReceveidDate": "2014-12-19T20:23:28.847"
    }
  ]
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "Payment": [
        {
            "PaymentId": "5fb4d606-bb63-4423-a683-c966e15399e8",
            "ReceveidDate": "2015-04-06T10:13:39.42"
        },
        {
            "PaymentId": "6c1d45c3-a95f-49c1-a626-1e9373feecc2",
            "ReceveidDate": "2014-12-19T20:23:28.847"
        }
    ]
}
Property Description Type Size Format
PaymentId Order Identifier Field. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Searching for recurrence information

The Recurrence query provides data on the scheduling and on the process of repeating transactions. The Recurrence query does not return data about the transactions themselves.

For information about each transaction, search via PaymentId

Request

curl
--request GET "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
--verbose
Property Description Type Size Required
MerchantId Store identifier in API E-commerce Cielo. Guid 36 Yes
MerchantKey Public Key for Double Authentication in API E-commerce Cielo. Text 40 Yes
RequestId Request Identifier, used when the merchant uses different servers for each GET/POST/PUT Guid 36 No
RecurrentPaymentId Recurrence Identifier Field. Text 36 Yes

Response

{
  "Customer": {
    "Name": "Fulano da Silva"
  },
  "RecurrentPayment": {
    "RecurrentPaymentId": "c30f5c78-fca2-459c-9f3c-9c4b41b09048",
    "NextRecurrency": "2017-06-07",
    "StartDate": "2017-04-07",
    "EndDate": "2017-02-27",
    "Interval": "Bimonthly",
    "Amount": 15000,
    "Country": "BRA",
    "CreateDate": "2017-04-07T00:00:00",
    "Currency": "BRL",
    "CurrentRecurrencyTry": 1,
    "Provider": "Simulado",
    "RecurrencyDay": 7,
    "SuccessfulRecurrences": 0,
    "Links": [
      {
        "Method": "GET",
        "Rel": "self",
        "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/c30f5c78-fca2-459c-9f3c-9c4b41b09048"
      }
    ],
    "RecurrentTransactions": [
      {
        "PaymentId": "f70948a8-f1dd-4b93-a4ad-90428bcbdb84",
        "PaymentNumber": 0,
        "TryNumber": 1
      }
    ],
    "Status": 1
  }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "Customer": {
        "Name": "Fulano da Silva"
    },
    "RecurrentPayment": {
        "RecurrentPaymentId": "c30f5c78-fca2-459c-9f3c-9c4b41b09048",
        "NextRecurrency": "2017-06-07",
        "StartDate": "2017-04-07",
        "EndDate": "2017-02-27",
        "Interval": "Bimonthly",
        "Amount": 15000,
        "Country": "BRA",
        "CreateDate": "2017-04-07T00:00:00",
        "Currency": "BRL",
        "CurrentRecurrencyTry": 1,
        "Provider": "Simulado",
        "RecurrencyDay": 7,
        "SuccessfulRecurrences": 0,
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/c30f5c78-fca2-459c-9f3c-9c4b41b09048"
            }
        ],
        "RecurrentTransactions": [
            {
                "PaymentId": "f70948a8-f1dd-4b93-a4ad-90428bcbdb84",
                "PaymentNumber": 0,
                "TryNumber": 1
            }
        ],
        "Status": 1
    }
}
Property Description Type Size Format
RecurrentPaymentId Next recurrence Identifier field. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
NextRecurrency Date of next recurrence. Text 7 12/2030 (MM/YYYY)
StartDate Start date of recurrence. Text 7 12/2030 (MM/YYYY)
EndDate End date of recurrence. Text 7 12/2030 (MM/YYYY)
Interval Interval between recurrences. Text 10 MonthlyBimonthly Quarterly SemiAnnual Annual
CurrentRecurrencyTry Indicates the number of attempts of the current recurrence Number 1 1
OrderNumber Order identification at the store Text 50 2017051101
Status Recurrent order status Number 1
1 - Active
2 - Finished
3- Deactivated by the Merchant
4 - Disabled by number of retries
5 - Disabled by expired credit card
RecurrencyDay Recurrence day Number 2 22
SuccessfulRecurrences Successful amount of recurrence Number 2 5
RecurrentTransactions.RecurrentPaymentId Recurrence Id Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
RecurrentTransactions.TransactionId Payment ID of the transaction generated on recurrence Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
RecurrentTransactions.PaymentNumber Number of Recurrence. The first one is zero Number 2 3
RecurrentTransactions.TryNumber Number of current attempt at the specific recurrence Number 2 1

Capture

The capture is an exclusive procedure for credit card transactions. There are two types of capture:

When carrying out a capture, the merchant confirms that the amount authorized on the card may be charged by the financial institution issuing the card.

Important:

Partial or total capture

You can capture a partial amount or the total amount of the transaction.

Partial capture is the act of capturing a value less than the authorized value. This capture model can only occur once per transaction.

After capture, it is not possible to perform additional captures in the same order.

Request

*For partial capture, send the Amount field in the capture request with the value you want to capture; *For total capture, do not send the Amount field. The total value of the authorization will be considered.



https://api.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture

curl
--request PUT "https://api.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--verbose
Property Description Type Size Required
MerchantId Store identifier in API E-commerce Cielo. Guid 36 Yes
MerchantKey Public Key for Double Authentication in API E-commerce Cielo. Text 40 Yes
RequestId Request Identifier, used when the merchant uses different servers for each GET/POST/PUT Guid 36 No
PaymentId Order Identifier Field. Guid 36 Yes
Amount Order Amount (to be sent in cents). Number 15 No
ServiceTaxAmount Applicable to airlines companies only. Amount of the authorization value/amount that should be allocated to the service fee. Note: This value is not added to the authorization value. Number 15 No

Response

{
  "Status": 2,
  "Tid": "0719094510712",
  "ProofOfSale": "4510712",
  "AuthorizationCode": "693066",
  "ReturnCode": "6",
  "ReturnMessage": "Operation Successful",
  "Links": [
    {
      "Method": "GET",
      "Rel": "self",
      "Href": "https://api.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
    },
    {
      "Method": "PUT",
      "Rel": "void",
      "Href": "https://api.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
    }
  ]
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "Status": 2,
    "Tid": "0719094510712",
    "ProofOfSale": "4510712",
    "ReturnCode": "6",
    "ReturnMessage": "Operation Successful",
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "Href": "https://api.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
        },
        {
            "Method": "PUT",
            "Rel": "void",
            "Href": "https://api.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
        }
    ]
}
Property Description Type Size Format
Status Transaction Status. Byte 2
ProofOfSale Authorization number, identical to NSU. Text 6 Alphanumeric
Tid Transaction Id on the acquirer. Text 20 Alphanumeric
AuthorizationCode Authorization code. Text 6 Alphanumeric
ReturnCode Return code of acquirer. Text 32 Alphanumeric
ReturnMessage Return message of acquirer. Text 512 Alphanumeric

Canceling a transaction

Cancellation is a feature that allows the merchant to reverse a purchase order. Cancellation can occur due to insufficient stock or due to withdrawal of the purchase by the consumer, among other reasons.

In the API E-commerce Cielo it is possible to make the cancellation request for debit and credit cards.

For cancellation requests of the same transaction, it is necessary to wait a period of 5 seconds between one request and another, so that the balance inquiry, reserve the amount in the financial agenda and awareness of the balance can be carried out, thus avoiding duplicate cancellations. This rule applies to total and partial cancellations. To identify that cancellation requests are from the same transaction, we consider the EC number, cancellation authorization number, date of sale, sale amount, and NSU.

It is important to point out that, in order to make any cancellation request, it is necessary that the merchant has sufficient balance in the transaction and in the agenda.

Total cancellation

You can cancel a sale via PaymentId or MerchantOrderId (order number).

Request

Cancellation via PaymentId

ou

Cancellation via MerchantOrderId

The following example displays the cancellation request via PaymentId.

curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--verbose
Property Description Type Size Required
MerchantId Store identifier in API E-commerce Cielo Guid 36 Yes
MerchantKey Public Key for Double Authentication in API E-commerce Cielo. Text 40 Yes
RequestId Request Identifier, used when the merchant uses different servers for each GET/POST/PUT. Guid 36 No
PaymentId Payment ID number. Guid 36 Yes
Amount Order Amount (to be sent in cents). Number 15 No

Response

{
  "Status": 10,
  "Tid": "0719094510712",
  "ProofOfSale": "4510712",
  "AuthorizationCode": "693066",
  "ReturnCode": "9",
  "ReturnMessage": "Operation Successful",
  "Links": [
    {
      "Method": "GET",
      "Rel": "self",
      "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
    }
  ]
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "Status": 10,
    "Tid": "0719094510712",
    "ProofOfSale": "4510712",
    "AuthorizationCode": "693066",
    "ReturnCode": "9",
    "ReturnMessage": "Operation Successful",
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
        }
    ]
}
Property Description Type Size Format
Status Transaction Status. Byte 2
ProofOfSale Authorization number, identical to NSU. Text 6 Alphanumeric
Tid Transaction Id on the acquirer. Text 20 Alphanumeric
AuthorizationCode Authorization code. Text 6 Alphanumeric
ReturnCode Return code of acquirer. Text 32 Alphanumeric
ReturnMessage Return message of acquirer. Text 512 Alphanumeric

Partial cancellation

Partial cancellation is the act of canceling an amount less than the total amount that was authorized and captured. This cancellation model can occur numerous times, until the full amount of the transaction is canceled.

Partial cancellation is only available for captured transactions.

Request

curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void?amount=XXX"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--verbose
Property Description Type Size Required
MerchantId Store identifier in API E-commerce Cielo. Guid 36 Yes
MerchantKey Public Key for Double Authentication in API E-commerce Cielo. Text 40 Yes
RequestId Request Identifier, used when the merchant uses different servers for each GET/POST/PUT Guid 36 No
PaymentId Order Identifier Field. Guid 36 Yes
Amount Order Amount (to be sent in cents). Number 15 No

Response

{
  "Status": 2,
  "Tid": "0719094510712",
  "ProofOfSale": "4510712",
  "AuthorizationCode": "693066",
  "ReasonCode": 0,
  "ReasonMessage": "Successful",
  "ProviderReturnCode": "0",
  "ProviderReturnMessage": "Operation Successful",
  "ReturnCode": "0",
  "ReturnMessage": "Operation Successful",
  "Links": [
    {
      "Method": "GET",
      "Rel": "self",
      "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/4d7be764-0e81-4446-b31e-7eb56bf2c9a8"
    },
    {
      "Method": "PUT",
      "Rel": "void",
      "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/4d7be764-0e81-4446-b31e-7eb56bf2c9a8/void"
    }
  ]
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "Status": 2,
    "Tid": "0719094510712",
    "ProofOfSale": "4510712",
    "AuthorizationCode": "693066",
    "ReasonCode": 0,
    "ReasonMessage": "Successful",
    "ProviderReturnCode": "0",
    "ProviderReturnMessage": "Operation Successful",
    "ReturnCode": "0",
    "ReturnMessage": "Operation Successful",
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/4d7be764-0e81-4446-b31e-7eb56bf2c9a8"
        },
        {
            "Method": "PUT",
            "Rel": "void",
            "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/4d7be764-0e81-4446-b31e-7eb56bf2c9a8/void"
        }
    ]
}
Property Description Type Size Format
Status Transaction Status. Byte 2
ProofOfSale Authorization number, identical to NSU. Text 6 Alphanumeric
Tid Transaction Id on the acquirer. Text 20 Alphanumeric
AuthorizationCode Authorization code. Text 6 Alphanumeric
ReturnCode Return code of acquirer. Text 32 Alphanumeric
ReturnMessage Return message of acquirer. Text 512 Alphanumeric
ProviderReturnCode Provider return code. Text 32 Alphanumeric
ProviderReturnMessage Provider return message. Text 512 Alphanumeric
https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{paymentId}/void?amount={Valor}&serviceTaxAmount=xxx

Cancellation Return Codes

RETURN CODE DESCRIPTION
6 Partial cancellation request successfully approved
9 Total cancellation request successfully approved
72 Error: Insufficient merchant balance for sale cancellation
77 Error: Original sale not found for cancellation
100 Error: Payment method and/or flag do not allow cancellation
101 Error: Requested cancellation amount above the allowed cancellation deadline
102 Error: Requested cancellation above the original transaction amount
103 Cadastral Restriction. Cancellation not allowed. Contact the Cancellation Center
104 Cadastral Restriction. Cancellation not allowed. Contact the Cancellation Center
105 Cadastral Restriction. Cancellation not allowed. Contact the Cancellation Center
106 Cadastral Restriction. Cancellation not allowed. Contact the Cancellation Center
107 Cadastral Restriction. Cancellation not allowed. Contact the Cancellation Center
108 Error: Merchant Number (EC) not found. Please check the number sent
475 Processing failed. Please try again

Cancellation via Cielo website

It is possible to carry out both the total cancellation and the partial cancellation via the Cielo website.

Notification Post

Notification Post is a webhook that sends notifications about changes in transaction status or recurring order creation.

During your cielo registration, you must set up an endpoint for Cielo to send notifications and you can also configure the events for which you want to receive notifications.

Notified Events

Events that can be notified by payment method are:

Payment Method Events that can be notified
Credit Card Capture;
Cancellation;
Queries.
Debit Card Capture;
Queries.
Boleto Conciliation;
Manual cancellation
Electronic transfer Confirmed transers.

Notification also occurs at events related to Cielo Scheduled Recurrence:

Recurrence Events
Disabled when reaching maximum number of attempts (denied transactions)
Rehabilitation
Finalized / Completion date reached
Deactivation
Creation of the recurring order recurrence transaction.

Events are only notified when you request this type of notification from Cielo Support.

Notification Endpoint

You must report an endpoint (PAYMENT STATUS URL) to Cielo Support for the Notification Post to run.

Characteristics of Payment Status URL

Characteristics of Post notification

To increase security, you can register header return information for your endpoint. With this, your endpoint will only accept the notification if Cielo sends the header.

To set up the header information, please inform Cielo Support of the following:

You can register up to 3 types of return information in the header.

The merchant should return in response to the notification: HTTP Status Code 200 OK.

The content of the notification will consist of three fields:

Using this data you can identify the transaction via PaymentId or RecurrentPaymentId and the change that ocurred. After the notification, you can get more details about the transaction by Searching for a transaction via PaymentId or by Searching for recurrence information

Here’s an example of the Notification Post content:

{
  "RecurrentPaymentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "PaymentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "ChangeType": 2
}
curl
--header "key: value"
{
   "RecurrentPaymentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "PaymentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "ChangeType": 2
}
Property Description Type Size Required
RecurrentPaymentId Identifier representing the Recurring request (only applicable for ChangeType 2 or 4). GUID 36 No
PaymentId Payment identification number. GUID 36 Yes
ChangeType Specifies the type of notification. Number 1 Yes

ChangeType table

ChangeType Description
1 Payment status change.
2 Recurrence created.
3 Antifraude status change. Exclusive for customers integrated with Antifraude.
4 Recurring payment status change (eg automatic deactivation).
5 Cancellation denied.
7 Chargeback notification. Exclusive for customers integrated with Risk Notification API.
8 Fraud alert.

BIN Query

BIN Query is a card data search service, whether credit or debit, which identifies card characteristics based on the first digits and returns information that allows you to validate the data filled in on the checkout screen.

This information allows you to take actions at the time of payment to improve the store’s conversion rates.

Use Case

Based on the result of the BIN Query, you can develop functionalities in your checkout to improve usability for shoppers and, thus, help in the recovery of carts and in the best conversion of your store.

1. Avoid errors related to the brand or the type of card:

2. Offer online cart recovery

You can develop a flow at your checkout so that, if a card entered on the payment screen is multiple (credit and debit), your store can retain the card data and, if the credit transaction fails, automatically offer the shopper a debit transaction with the same card.

3. Warn about international or prepaid cards

The BIN query may indicate an attempt to use an international or prepaid card. If your store does not want to accept international or prepaid card payments, you can configure your checkout to inform the shopper that the store does not accept the card entered.

Integration

Request

A GET request must be sent containing the BIN to be checked:

Field Description
BIN It’s the first six or nine digits of the card.
https://apiquery.cieloecommerce.cielo.com.br/1/cardBin/420020

Response

{
    "Status": "00",
    "Provider": "MASTERCARD",
    "CardType": "Crédito",
    "ForeignCard": true,
    "CorporateCard": true,
    "Issuer": "Bradesco",
    "IssuerCode": "237"
    "Prepaid":true
}
Parameter Type Size Description
Status Text 2 BIN Check status response:
00 – Analysis authorized
01 – Brand not supported
02 – Card not supported for BIN Check
73 – Blocked Affiliation
Provider Text 255 Card Brand
CardType Text 20 Card Type:
Credit
Debit
Multiple
ForeignCard Boolean - If card was issued abroad (False/True)
CorporateCard Boolean - If card is coporate (False/True)
Issuer Text 255 Card issuer’s name
IssuerCode Text 255 Card issuer’s code
Prepaid Boolean True ou False Returns “True” if the card is prepaid.

NOTE: On testing environment (SANDBOX), the returned data is simulated, so they are not valid BIN Check results. Only fields and format must be considered. For real identification of the BIN Check, production environment must be used.

Zero Auth

Zero Auth is a Cielo tool that allows you to check whether a card is valid for making a purchase before the order is finalized. Zero Auth simulates an authorization without affecting the credit limit or alerting the cardholder about the test.

Zero Auth does not return the card available limit or card/cardholder characteristics. Zero Auth only simulates a Cielo authorization.

Zero Auth is the correct way to validate cards according to the recommendations of brands and banks. Before the creation of Zero Auth, stores used to create low-value transactions, such as one real or one dollar, and then cancel them; it is important to know that this practice is now penalized by the card brands.

Notice:

  • In the event of transactions with an amount different from zero and less than one dollar, followed by cancellation of the transaction, the brands will apply fees to Cielo, which will be passed on to the establishments that are non-compliant. Mastercard, for example, is charging a fee of R$0.21 per transaction.
  • Zero Auth transactions are subject to the rules established in Card Brands Retry Program. Fees may be charged due to excessive attempts. Please refer to Card Brands Retry Program for details.

Zero Auth validates open or tokenized cards (sending the CardToken created in the API E-commerce Cielo).

Supported brands

Zero Auth supports Visa, Master and Elo for both credit and debit cards.

If other brands are sent, there will be an error with the return “57-Invalid Brand”.

Integration

To perform a Zero Auth validation, the merchant must send a POST request to the API E-commerce Cielo, simulating a transaction.

Validating an open card requires a different technical contract than validating a tokenized card or an e-wallet. Check out each example request in the following topics:

Open card

You should send open card data: number, holder, expiration date, security code and brand, along with other parameters as seen below.

Request

{
    "CardNumber":"1234123412341231",
    "Holder":"Alexsander Rosa",
    "ExpirationDate":"12/2021",
    "SecurityCode":"123",
    "SaveCard":"false",
    "Brand":"Visa",
    "CardOnFile":{
       "Usage":"First",
       "Reason":"Recurring"
    }
}
Field Description Type Size Required
CardType Defines the type of card used:

CreditCard
DebitCard

If not sent, CreditCard is the default.
Text 255 Yes
CardNumber Card Number Text 16 Yes
Holder Cardholder’s name, printed on the card. Text 25 Yes
ExpirationDate Expiration date. Text 7 Yes
SecurityCode Card Security code. Text 4 Yes
SaveCard Defines if the card must be tokenized. Find out more about Tokenization of Cards. Boolean Yes
Brand Card brand:
Visa
Master
ELO
Text 10 Yes
CardToken Card Token in API E-commerce Cielo. GUID 36 Conditional
CardOnFile.Usage First if the credentials have been stored and they will be used for the first time.
Used if the credentials have been stored and they were previously used.
Text No
CardOnFile.Reason Indicates the purpose of storing cards, if the “Usage” field is “Used”.
Recurring - Scheduled recurring purchase (eg subscriptions). If it is a recurring transaction, use Payment.Recurrent = true (merchant recurrence) or Recurrent.Payment = true (scheduled recurrence).
Unscheduled - Recurring purchase without scheduling (eg service applications)
Installments - Installment through recurrence
.
Text Conditional

Tokenized card

If the card is tokenized, you should send the CardToken.

Request

{
  "CardToken":"23712c39-bb08-4030-86b3-490a223a8cc9",
  "SaveCard":"false",
  "Brand":"Visa"
}
Field Description Type Size Required
Brand Card Brand: Visa
Master
ELO
Text 10 not
CardToken Tokenized Card 3.0 GUID 36 yes

E-wallet

In order to validate an e-wallet with Zero Auth, the merchant is required to have one of the available e-wallets integrated.

Request

{
    "Card": {
       "CardType": "CreditCard",
       "CardNumber": "4532154371691902",
       "Holder": "Joao da Silva",
       "ExpirationDate": "MM/YYYY",
       "SecurityCode": "333",
       "Brand": "Visa",
       "CardOnFile": {
           "Usage": "First",
           "Reason": "Recurring"
       }
    },
    "Wallet": {
       "Type": "ApplePay",
       "Cavv": "AM1mbqehL24XAAa0J04CAoABFA==",
       "Eci": 7
    }
}
Field Description Type Contact Us Required
CardType Defines the type of card used:

CreditCard
DebitCard

If not sent, CreditCard is the default.
Text 255 Yes
CardNumber Card Number Text 16 Yes
Holder Cardholder’s name, printed on the card. Text 25 Yes
ExpirationDate Expiration date. Text 7 Yes
SecurityCode Card Security code. Text 4 Yes
SaveCard Defines if the card must be tokenized. Find out more about Tokenization of Cards. Boolean Yes
Brand Card brand:
Visa
Master
ELO
Text 10 Yes
CardToken Card Token in API E-commerce Cielo. GUID 36 Conditional
CardOnFile.Usage First if the credentials have been stored and they will be used for the first time.
Used if the credentials have been stored and they were previously used.
Text No
CardOnFile.Reason Indicates the purpose of storing cards, if the “Usage” field is “Used”.
Recurring - Scheduled recurring purchase (eg subscriptions). If it is a recurring transaction, use Payment.Recurrent = true (merchant recurrence) or Recurrent.Payment = true (scheduled recurrence).
Unscheduled - Recurring purchase without scheduling (eg service applications)
Installments - Installment through recurrence
.
Text Conditional
Wallet.Type Wallet type: “ApplePay” / “SamsungPay” / “GooglePay”. Text 15 Yes
Wallet.Cavv Validation field returned by the e-wallet and used as authorization basis. Text 255 Yes
Wallet.Eci Electronic Commerce Indicator. Represents how secure a transaction is. The merchant should consider the ECI to decide whether or not to capture a transaction. Text 2 Yes

Response

The response always returns whether the card can currently be authorized. This information only means that the card is valid for transactioning, but does not indicate that a certain value will be authorized.

The fields returned in the response depend on the validation result. The following table presents all possible fields; after the table, check out the examples for each type of response.

If the response is negative, do not submit for authorization, submit only if the response code is positive.

Field Description Type Size
Valid Card Status:
True ** - Valid Card
**False
- Invalid Card
Boolean
ReturnCode Return code Text 2
ReturnMessage Return message Text 255
IssuerTransactionId Issuer authentication identifier for recurring credit transactions. This field must be sent in subsequent transactions of the first transaction in the self-recurrence model. In the programmed recurrence model, Cielo will be responsible for sending the field in subsequent transactions. Text 15

POSITIVE - Valid Card

{
  "Valid": true,
  "ReturnCode": "00",
  "ReturnMessage": "Transacao autorizada",
  "IssuerTransactionId": "580027442382078"
}

See Return codes to see the return codes descriptions. The return code 00 represents success in Zero Auth, the other codes are defined according to the next topics.

NEGATIVE - Invalid Card

{
       "Valid": false,
       "ReturnCode": "57",
       "ReturnMessage": "Autorizacao negada",
       "IssuerTransactionId": "580027442382078"
}

NEGATIVE - Invalid Card - Brand not Supported

  {    
      "Code": 57,     
      "Message": "Bandeira inválida"   
  }

NEGATIVE - Registration Restriction

  {    
      "Code": 389,     
      "Message": "Restrição Cadastral"   
  }

If there is an error in Zero Auth flow and it is not possible to validate the card, Zero Auth will return the following errors:

Silent Order Post

With Silent Order Post, payment data is securely transferred, maintaining full control over the checkout experience.

This method makes it possible to send the shopper’s payment data securely directly into our system. Payment fields are stored by Cielo, which is PCI DSS 3.2 certified.

It is ideal for merchants who require a high level of security without losing the identity of their page.

Characteristics

The PCI Data Security Standard (PCI DSS) is a global standard for card data security, and comprises a minimum set of requirements to protect cardholder data.

Authorization Flow

Below is how a standard authorization flow and an authorization flow with Silent Order Post.

Standard Authorization Flow

In the standard authorization flow, the online store receives payment data from the shopper and therefore needs to be PCI DSS compliant.

Authorization_Flow

Authorization Flow with Silent Order POST

With Silent Order Post, the virtual store server does not transfer card data openly.

Authorization_Flow_POST

  1. The store configures JavaScript on the checkout screen. At checkout, the script sends payment data directly to API E-commerce Cielo, without going through the store’s server;
  2. The API stores the card data for that purchase and creates an encrypted code (PaymentToken, valid only for one purchase) or stores the card data and creates an encrypted code for the card (CardToken, which can be used on other purchases);
  3. The store sends the script token to the server itself;
  4. The store, through its server, sends the authorization request with the token and the other mandatory fields for a transaction.

Integration

Step 1. Getting access tokens

In order to use Silent Order Post, you will need two tokens:

OAuth2 authentication token

Get the access_token from the Cielo authentication API (OAuth2). In case of success, the API will return an access_token that must be used in the next authentication layer of the tool.

To get the access_token in the OAuth 2.0 standard, send a request using the HTTP VERB POST to the URL of the table below, formed by the “base URL of the environment + endpoint”, according to the desired environment:

Environment base URL + endpoint Authorization
SANDBOX https://authsandbox.braspag.com.br/oauth2/token “Basic {base64}
PRODUCTION https://auth.braspag.com.br/oauth2/token “Basic {base64}

Note: The “{base64}” value for the “Basic” type authorization must be obtained as follows:

  1. Concatenate the “ClientId” and the “ClientSecret” (ClientId:ClientSecret);
  2. Encode the result of the concatenation in base64;
  3. Make a request to the authorization server using the generated alphanumeric code.

To obtain the “ClientID” and “ClientSecret”, send an email to cieloecommerce@cielo.com.br containing the MerchantId and informing that you want to obtain the “ClientID” and “ClientSecret” credentials for Silent Order Post.

Request

--request POST "https://authsandbox.braspag.com.br/oauth2/token"
--header "Authorization: Basic {base64}"
--header "Content-Type: application/x-www-form-urlencoded" 
--data-binary "grant_type=client_credentials"
Parameters Format Where to send
Authorization “Basic {base64} Header.
Content-Type “application/x-www-form-urlencoded” Header.
grant_type “client_credentials” Body.

Response

{
  "access_token": "faSYkjfiod8ddJxFTU3vti_ ... _xD0i0jqcw",
  "token_type": "bearer",
  "expires_in": 599
}
{
  "access_token": "faSYkjfiod8ddJxFTU3vti_ ... _xD0i0jqcw",
  "token_type": "bearer",
  "expires_in": 599
}
Response Properties Description
access_token The requested authentication token, that will be used in the next step.
token_type Indicates the token type value.
expires_in Access Token expiration, in seconds. When the token expires, you must request a new one.

Silent Order Post Authentication Token

After obtaining the OAuth2 authentication token, send a request using the HTTP VERB POST to the URL in the table below, depending on the desired environment:

Environment base URL + endpoint
Sandbox https://transactionsandbox.pagador.com.br/post/api/public/v2/accesstoken
Production https://transaction.pagador.com.br/post/api/public/v2/accesstoken

Request

--request POST "https://transactionsandbox.pagador.com.br/post/api/public/v2/accesstoken"
--header "Content-Type: application/json"
--header "MerchantId: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
--header "Authorization: Bearer faSYkjfiod8ddJxFTU3vti_ ... _xD0i0jqcw"
--data-binary
--verbose
Properties Description Type Size Required
MerchantId Merchant identifier at Pagador. GUID 36 Yes
Authorization Bearer [AccessToken OAuth2] Text 36 Yes

Response

In response, the store will receive a json (“HTTP 201 Created”) containing, among other information, the AccessToken from Silent Order Post.

{
    "MerchantId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "AccessToken": "MzA5YWIxNmQtYWIzZi00YmM2LWEwN2QtYTg2OTZjZjQxN2NkMDIzODk5MjI3Mg==",
    "Issued": "2021-05-05T08:50:04",
    "ExpiresIn": "2021-05-05T09:10:04"
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "AccessToken": "MzA5YWIxNmQtYWIzZi00YmM2LWEwN2QtYTg2OTZjZjQxN2NkMDIzODk5MjI3Mg==",
    "Issued": "2021-05-05T08:50:04",
    "ExpiresIn": "2021-05-05T09:10:04"
}
Properties Description Type Size Format
MerchantId Merchant identifier at aPI E-commerce Cielo. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AccessToken Access token (AccessToken from Silent Order Post). The AccessToken obtained will allow an authorization attempt to be made within 20 minutes. Text NjBhMjY1ODktNDk3YS00NGJkLWI5YTQtYmNmNTYxYzhlNjdiLTQwMzgxMjAzMQ==
Issued Token creation date and hour. Text AAAA-MM-DDTHH:MM:SS
ExpiresIn Token expiration date and hour. Text AAAA-MM-DDTHH:MM:SS

Step 2. Implementing the script

Download the script provided by Cielo, and attach the script to your checkout page. This script will allow Cielo to process all card information without the merchant’s intervention.

Download the script corresponding to the desired environment, sandbox or production:

Environment Script URL
SANDBOX https://transactionsandbox.pagador.com.br/post/scripts/silentorderpost-1.0.min.js
PRODUCTION https://transaction.cieloecommerce.cielo.com.br/post/scripts/silentorderpost-1.0.min.js

Then configure the form with the following classes:

Additionally, set the following parameters:

Script Parameters

Property Description
accessToken Access token obtained via Braspag’s authentication API (AccessToken SOP).
environment Type of environment: sandbox or production
language PT or EN or ES
enableTokenize “true” (saves the card directly to the Protected Card, returning a cardToken instead of a paymentToken) / “false” (otherwise).
cvvRequired “false” (sets CVV as not mandatory) / “true” (sets CVV as mandatory).

Example of setup to be performed by the virtual store on the checkout page:

Pagina Checkout

Script Response

The script provided by Cielo provides three events for handling and treatment by the establishment. They are:

When validating the inputs, the establishment will be able to use the entire validation layer on the card data carried out by Cielo and thus simplify the treatment in its checkout form. The messages returned in the validation result are available in Portuguese (default), English and Spanish.

Property Description Condition
PaymentToken Payment Token in GUID format (36)  
CardToken Permanent token to be used on a payment request on a GUID format (36). Only works if ‘enableTokenize’ is true.
  • The PaymentToken or CardToken will represent all the card data provided by the shopper. The token will be used by the establishment so that it does not need to treat and process card data on its server.
  • For security reasons, the PaymentToken can only be used for authorization in the API E-commerce Cielo. After processing the token, it will be invalidated.

Step 3. Authorization request with token

Request with PaymentToken

Send the authorization request with the PaymentToken in the CreditCard node (for credit card transaction) or in the DebitCard node (for debit card transaction).

},
    "Payment": {
    "Type": "CreditCard",
    "Amount": 1400,
    "Installments": 1,
        "CreditCard": {
        "PaymentToken": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "Brand": "MASTER"
        }
    }
}

To see the required fields for the request and the response, see standard requests for credit or debit.

For security reasons, the PaymentToken can only be used for authorization in the API E-commerce Cielo. The token will be processed and then invalidated.

Request with CardToken

Submit the authorization request with the CardToken in the CreditCard node (for credit card transaction) or in the DebitCard node (for debit card transaction).

{  
   "MerchantOrderId":"2014111706",
   "Customer":{  
      "Name":"Comprador Teste"
   },
   "Payment":{  
     "Type":"CreditCard",
     "Amount":100,
     "Installments":1,
     "SoftDescriptor":"123456789ABCD",
     "CreditCard":{  
         "CardToken":"6e1bf77a-b28b-4660-b14f-455e2a1c95e9",
         "SecurityCode":"262",
         "Brand":"Visa"
     }
   }
}

To see the required fields for the request and the response, see standard requests for credit or debit.

Legacy Authentication

We do not recommend this form of authentication as it will be discontinued.

STEP 1

a) The merchant must request a ticket (server to server) sending a POST to the following URL:

SANDBOX: https://transactionsandbox.pagador.com.br/post/api/public/v1/accesstoken?merchantid={mid_loja}

PRODUCTION: https://transaction.cieloecommerce.cielo.com.br/post/api/public/v1/accesstoken?merchantid={mid}

Example: https://transaction.cieloecommerce.cielo.com.br/post/api/public/v1/accesstoken?merchantid=00000000-0000-0000-0000-000000000000

Request

curl
--request POST "https://transaction.cieloecommerce.cielo.com.br/post/api/public/v1/accesstoken?merchantid=00000000-0000-0000-0000-000000000000"
--header "Content-Type: application/json"
--data-binary
--verbose
Property Description Type Size Required
mid_loja API store identifier Guid 36 Yes

Response

--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "AccessToken": "NjBhMjY1ODktNDk3YS00NGJkLWI5YTQtYmNmNTYxYzhlNjdiLTQwMzgxMjAzMQ==",
    "Issued": "2018-07-23T11:09:32",
    "ExpiresIn": "2018-07-23T11:29:32"
}
Property Description Type Size Format
MerchantId Store identifier in Cielo Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AccessToken Access token Text NjBhMjY1ODktNDk3YS00NGJkLWI5YTQtYmNmNTYxYzhlNjdiLTQwMzgxMjAzMQ==
Issued Date and time generation Text AAAA-MM-DDTHH:MM:SS
ExpiresIn Date and time of expiration Text AAAA-MM-DDTHH:MM:SS

b) To use this resource, for security reasons, Cielo will obligatorily request, at least, a valid IP of the establishment. Otherwise, the request will not be authorized (HTTP 401 NotAuthorized).

STEP 2

a) In response, the merchant will receive a JSON (HTTP 201 Created) containing, among other information, the ticket (AccessToken), such as:

Response Ticket

For security reasons, this ticket will allow the store to save only one card within a period already stipulated in the answer, through the ExpiresIn attribute (by default, 20 minutes). Whichever happens first will invalidate the ticket for future use.

Velocity

Velocity is a type of fraud prevention mechanism, which analyzes the frequency that certain data is used in a transaction and if this data is included in a list of behaviors subject to security actions.

Velocity is an ally in the evaluation of suspicious purchasing behavior, as the calculations are based on traceability elements.

For your transactions to be analyzed by Velocity, request the inclusion of this service to Cielo Support.

Velocity works by analyzing data sent in the standard integration of the API E-commerce Cielo. Thus, it is not necessary to include any additional nodes in the transaction creation request.

When Velocity is active, the transaction response will bring a specific node called Velocity, with the analysis details.

{
  "MerchantOrderId": "2017051202",
  "Customer": {
    "Name": "Nome do Comprador",
    "Identity": "12345678909",
    "IdentityType": "CPF",
    "Email": "comprador@cielo.com.br",
    "Address": {
      "Street": "Alameda Xingu",
      "Number": "512",
      "Complement": "27 andar",
      "ZipCode": "12345987",
      "City": "São Paulo",
      "State": "SP",
      "Country": "BRA"
    },
    "DeliveryAddress": {
      "Street": "Alameda Xingu",
      "Number": "512",
      "Complement": "27 andar",
      "ZipCode": "12345987",
      "City": "São Paulo",
      "State": "SP",
      "Country": "BRA"
    }
  },
  "Payment": {
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": "ByMerchant",
    "Capture": true,
    "Authenticate": false,
    "Recurrent": false,
    "CreditCard": {
      "CardNumber": "455187******0181",
      "Holder": "Nome do Portador",
      "ExpirationDate": "12/2027",
      "SaveCard": false,
      "Brand": "Undefined"
    },
    "VelocityAnalysis": {
      "Id": "2d5e0463-47be-4964-b8ac-622a16a2b6c4",
      "ResultMessage": "Reject",
      "Score": 100,
    },
    "PaymentId": "2d5e0463-47be-4964-b8ac-622a16a2b6c4",
    "Type": "CreditCard",
    "Amount": 10000,
    "Currency": "BRL",
    "Country": "BRA",
    "Provider": "Simulado",
    "ReasonCode": 16,
    "ReasonMessage": "AbortedByFraud",
    "Status": 0,
    "ProviderReturnCode": "BP171",
    "ProviderReturnMessage": "Rejected by fraud risk (velocity)",
    "Links": [
      {
        "Method": "GET",
        "Rel": "self",
        "Href": "https://apiquery.cieloecommerce.cielo.com.br/1/sales/2d5e0463-47be-4964-b8ac-622a16a2b6c4"
      }
    ]
  }
}
Property Description Type Size
VelocityAnalysis.Id Performed analysis identifier GUID 36
VelocityAnalysis.ResultMessage Accept ou Reject Text 25
VelocityAnalysis.Score 100 Number 10

API codes

About codes

API E-commerce Cielo has 4 types of returned codes that represent different moments of the transaction.

Below we explain them in the order in which they can occur:

Code Description
HTTP Status Code They are standard HTTP codes. It report if the information sent to the API is actually being successful in reaching our ENDPOINTs. If values other than 200 or 201 are appearing, there is some impediment with the comunication with the API
Returned at time of API request
API Errors These codes are responses to content validation of sent data. If they are being displayed, our API calls have been identified and are being validated. If this code is displayed, the request contains errors (EX: size/conditions/registration errors) that prevent the creation of the transaction
Returned at the time of the request to the API
Status After the transaction is created, these codes will be returned, informing how the transaction is at the moment (e.g. Authorized > Captured > Cancelled)
*Returned in the Status field *
Sales Return Formed by a Return code and a message, these codes indicate the reason for a certain Status within a transaction. They indicate, for example, if a transaction with status denied was not authorized due to a negative balance in the issuing bank.
Returned in the ReturnCode and ReturnMessage fields
Occurs only in Credit and Debit Cards

Note: In the old Webservice 1.5 Cielo, the ReturnCode was considered Transaction Status. In the API E-commerce Cielo, the Status field has its own codes, therefore, the field to be considered as the basis for identifying the status of a transaction.

HTTP Status Code

HTTP Status Code Descrição
200 OK (Capture/Void/Get)
201 OK (Authorization)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Resource Not Found
405 Method Not Allowed
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
400 Bad Request
404 Resource Not Found
500 Internal Server Error

See some example scenarios for when each HTTP code may return:

Successful responses

Client error responses

Server error responses

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.

The Merchant Advice Code (MAC) for Mastercard determines whether the transaction is reversible or not and which action the merchant can take to try to approve the transaction. Please refer to Merchant Advice Code Transaction Excellence (MAC) for further information.

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.

Transactional status

Code Status Means of payment Description
0 NotFinished All Waiting for status update
1 Authorized All Payment apt to be captured or defined as paid
2 PaymentConfirmed All Confirmed and finalized payment
3 Declined Credit and debit cards and e-wallets Payment declined by Authorizer
10 Voided All, except boleto Canceled payment
11 Refunded Credit and debit cards and e-wallets Payment canceled after 11:59 pm on the authorization day
12 Pending Credit and debit cards, e-wallets and pix Waiting for financial institution status
13 Aborted All Payment canceled due to processing failure
20 Scheduled Credit cards and e-wallets Scheduled recurrence

-

Payment method Description
ALL All
CC Credit Card
CD Debit Card
TF Electronic Transfer
BOL Bank slip

Integration errors

API Errors - These codes are responses to the content validation of the data sent at the time of the API request.
If an error code is displayed, the requisition contains errors (such as size, conditions or registration errors, etc.) that prevent the creation of the transaction

Example

[
    {
        "Code": 126,
        "Message": "Credit Card Expiration Date is invalid"
    }
]
Property Description
Code API error code. See the code list
Message Error description. See the code list

API Error Codes

Codes returned in case of error, identifying the reason for the error and its respective messages.

ReturnCode ReturnMessage Description
0 Internal error Sent data exceeds field size
100 RequestId is required Sent field is empty or invalid
101 MerchantId is required Sent field is empty or invalid
102 Payment Type is required Sent field is empty or invalid
103 Payment Type can only contain letters Special characters not allowed
104 Customer Identity is required Sent field is empty or invalid
105 Customer Name is required Sent field is empty or invalid
106 Transaction ID is required Sent field is empty or invalid
107 OrderId is invalid or does not exists Sent field exceeds size or contains special characters
108 Amount must be greater or equal to zero Transaction value must be greater than “0”
109 Payment Currency is required Sent field is empty or invalid
110 Invalid Payment Currency Sent field is empty or invalid
111 Payment Country is required Sent field is empty or invalid
112 Invalid Payment Country Sent field is empty or invalid
113 Invalid Payment Code Sent field is empty or invalid
114 The provided MerchantId is not in correct format The sent MerchantId is not a GUID
115 The provided MerchantId was not found MerchantID does not exist or belongs to another environment (e.g. Sandbox)
116 The provided MerchantId is blocked Locked store, contact Cielo support
117 Credit Card Holder is required Sent field is empty or invalid
118 Credit Card Number is required Sent field is empty or invalid
119 At least one Payment is required “Payment” node not sent
120 Request IP not allowed. Check your IP White List IP blocked for security reasons
121 Customer is required “Customer” node not sent
122 MerchantOrderId is required Sent field is empty or invalid
123 Installments must be greater or equal to one Number of installments must be greater than 1
124 Credit Card is Required Sent field is empty or invalid
125 Credit Card Expiration Date is required Sent field is empty or invalid
126 Credit Card Expiration Date is invalid Sent field is empty or invalid
127 You must provide CreditCard Number Credit card number is required
128 Card Number length exceeded Card number greater than 16 digits
129 Affiliation not found Payment means not linked to store or invalid Provider
130 Could not get Credit Card
131 MerchantKey is required Sent field is empty or invalid
132 MerchantKey is invalid Sent Merchantkey is not a valid one
133 Provider is not supported for this Payment Type Sent Provider does not exist
134 FingerPrint length exceeded Sent data exceeds field size
135 MerchantDefinedFieldValue length exceeded Sent data exceeds field size
136 ItemDataName length exceeded Sent data exceeds field size
137 ItemDataSKU length exceeded Sent data exceeds field size
138 PassengerDataName length exceeded Sent data exceeds field size
139 PassengerDataStatus length exceeded Sent data exceeds field size
140 PassengerDataEmail length exceeded Sent data exceeds field size
141 PassengerDataPhone length exceeded Sent data exceeds field size
142 TravelDataRoute length exceeded Sent data exceeds field size
143 TravelDataJourneyType length exceeded Sent data exceeds field size
144 TravelLegDataDestination length exceeded Sent data exceeds field size
145 TravelLegDataOrigin length exceeded Sent data exceeds field size
146 SecurityCode length exceeded Sent data exceeds field size
147 Address Street length exceeded Sent data exceeds field size
148 Address Number length exceeded Sent data exceeds field size
149 Address Complement length exceeded Sent data exceeds field size
150 Address ZipCode length exceeded Sent data exceeds field size
151 Address City length exceeded Sent data exceeds field size
152 Address State length exceeded Sent data exceeds field size
153 Address Country length exceeded Sent data exceeds field size
154 Address District length exceeded Sent data exceeds field size
155 Customer Name length exceeded Sent data exceeds field size
156 Customer Identity length exceeded Sent data exceeds field size
157 Customer IdentityType length exceeded Sent data exceeds field size
158 Customer Email length exceeded Sent data exceeds field size
159 ExtraData Name length exceeded Sent data exceeds field size
160 ExtraData Value length exceeded Sent data exceeds field size
161 Boleto Instructions length exceeded Sent data exceeds field size
162 Boleto Demostrative length exceeded Sent data exceeds field size
163 Return Url is required Return URL is not valid - No pagination or extensions are accepted (e.g. .PHP) in the return URL
166 AuthorizeNow is required
167 Antifraud not configured Antifraud not linked to the merchant’s registry
168 Recurrent Payment not found Recurrence not found
169 Recurrent Payment is not active Recurrence is not active. Paralyzed execution
170 Protected Card not configured Protected card not linked to merchant’s registry
171 Affiliation data not sent Order processing failed - Contact Cielo support
172 Credential Code is required Failed to validate the sent credentials
173 Payment method is not enabled Means of payment not linked to the merchant’s registry
174 Card Number is required Sent field is empty or invalid
175 EAN is required Sent field is empty or invalid
176 Payment Currency is not supported Sent field is empty or invalid
177 Card Number is invalid Sent field is empty or invalid
178 EAN is invalid Sent field is empty or invalid
179 The max number of installments allowed for recurring payment is 1 Sent field is empty or invalid
180 The provided Card PaymentToken was not found Protected Card Token not found
181 The MerchantIdJustClick is not configured Protected Card Token locked
182 Brand is required Card issuer not sent
183 Invalid customer bithdate Invalid or future date of birth
184 Request could not be empty Failure of the request format. Check the sent code
185 Brand is not supported by selected provider Card issuer not supported by API Cielo
186 The selected provider does not support the options provided (Capture, Authenticate, Recurrent or Installments) Payment means does not support the sent command
187 ExtraData Collection contains one or more duplicated names
188 Avs with CPF invalid  
189 Avs with length of street exceeded  
190 Avs with length of number exceeded  
191 Avs with length of district exceeded  
192 Avs with zip code invalid  
193 Split Amount must be greater than zero Value for SPLIT realization must be greater than 0
194 Split Establishment is Required SPLIT not enabled for store registration
195 The PlataformId is required Platforms validated not sent
196 DeliveryAddress is required Required field not sent
197 Street is required Required field not sent
198 Number is required Required field not sent
199 ZipCode is required Required field not sent
200 City is required Required field not sent
201 State is required Required field not sent
202 District is required Required field not sent
203 Cart item Name is required Required field not sent
204 Cart item Quantity is required Required field not sent
205 Cart item type is required Required field not sent
206 Cart item name length exceeded Sent data exceeds field size
207 Cart item description length exceeded Sent data exceeds field size
208 Cart item sku length exceeded Sent data exceeds field size
209 Shipping addressee sku length exceeded Sent data exceeds field size
210 Shipping data cannot be null Required field not sent
211 WalletKey is invalid Invalid Visa Checkout data
212 Merchant Wallet Configuration not found Sent Wallet data is not valid
213 Credit Card Number is invalid Sent credit card is invalid
214 Credit Card Holder Must Have Only Letters Card carrier must not contain special characters
215 Agency is required in Boleto Credential Required field not sent
216 Customer IP address is invalid IP blocked for security reasons
300 MerchantId was not found
301 Request IP is not allowed
302 Sent MerchantOrderId is duplicated
303 Sent OrderId does not exist
304 Customer Identity is required
306 Merchant is blocked
307 Transaction not found Transaction not found or does not exist in the environment.
308 Transaction not available to capture Transaction can not be captured - Contact Cielo support
309 Transaction not available to void Transaction can not be canceled - Contact Cielo support
310 Payment method doest not support this operation Sent command not supported by payment means
311 Refund is not enabled for this merchant Cancellation after 24 hours not released to the merchant
312 Transaction not available to refund Transaction does not allow cancellation after 24 hours
313 Recurrent Payment not found Recurrent transaction not found or not available in the environment
314 Invalid Integration
315 Cannot change NextRecurrency with pending payment
316 Cannot set NextRecurrency to past date It is not allowed to change the recurrence date to a past date
317 Invalid Recurrency Day
318 No transaction found
319 Smart recurrency is not enabled Recurrence not linked to the merchant’s registration
320 Can not Update Affiliation Because this Recurrency not Affiliation saved
321 Can not set EndDate to before next recurrency.
322 Zero Dollar Auth is not enabled Zero Dollar not linked to the merchant’s registration
323 Bin Query is not enabled Bins query not linked to the merchant’s registration

BP Errors

BP error codes may be returned in ReturnCode parameter; when the API returns BP errors, the transaction status is “0” - Not finished.

RESPONSE CODE DEFINITION DESCRIPTION ACTION RETRY ALLOWED?
BP 171 Rejected due to fraud risk (Velocity). It is related to Velocity rules. Try again after one hour. Yes
BP 900 Operation fail. Operation fail (request submission process). Try again. Sim
BP 901 Operation fail Authorization fail. Try again. Yes
BP 902 Wait for the response from previous operation. Capture fail. Try again. Yes
BP 903 Cancellation fail. Cancellation fail. Try again. Yes
BP 904 Query fail. Query fail. Try again. Yes

Reason Code and Reason Message

Reason Code Reason Message
0 Successful
1 AffiliationNotFound
2 IssuficientFunds
3 CouldNotGetCreditCard
4 ConnectionWithAcquirerFailed
5 InvalidTransactionType
6 InvalidPaymentPlan
7 Denied
8 Scheduled
9 Waiting
10 Authenticated
11 NotAuthenticated
12 ProblemsWithCreditCard
13 CardCanceled
14 BlockedCreditCard
15 CardExpired
16 AbortedByFraud
17 CouldNotAntifraud
18 TryAgain
19 InvalidAmount
20 ProblemsWithIssuer
21 InvalidCardNumber
22 TimeOut
23 CartaoProtegidoIsNotEnabled
24 PaymentMethodIsNotEnabled
98 InvalidRequest
99 InternalError

Error messages and codes - Pix

CODE EVENT MESSAGE DESCRIPTION/ACTION
422 Authorization Error on Merchant Integration Verify that the Pix is enabled in your registration
422 Authorization Error on bki service integration for charge Pix Banks Transaction Error, contact E-commerce Support
BP904 Authorization The json entered is not valid Contact E-commerce Support to assess the reason.
BP901 Authorization Operation failed Redo the payment, if it persists, contact e-commerce support
422 Cancellation Error on pix service integration for moneyback It is not possible to cancel the transaction, The return will only occur if there is a balance.
422 Cancellation Merchant bank for moneyback is not Cielo Pix Banco transaction does not allow cancellation operations