Integration Manual E-commerce Cielo

Redirecionando para https://docs.cielo.com.br/ecommerce-cielo-en/docs/ ...

The documentation for API Cielo E-commerce is now on a new portal

Access the new E-commerce developers portal at docs.cielo.com.br.

Warning: The content on this page is being discontinued and will not receive updates after 09/16/2024. Please visit the new documentation at docs.cielo.br.

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 E-commerce Cielo. These operations must be performed using your credentials (MerchantId and MerchantKey) in the respective environment endpoints

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:

• No proprietary apps: it is not necessary to install applications in the virtual shop environment.
• Simplicity: the only protocol used is HTTPS.
• Easy testing: the Cielo platform offers a publicly accessible Sandbox environment, which allows the developer to create a test account without the need for accreditation, making it easier and faster to start integration.
• Credentials: the handling of the customers’s credentials (affiliation number and access key) traffics in the header of the HTTP request of the message.
• Safety: the information exchange always takes place between the Store Server and Cielo Server, without the shopper’s browser.
• Multiplatform: the integration is performed through Web Service REST.

Architecture

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

• Requests URL: for operations that cause side effects - such as authorization, capture and cancellation of transactions
• Queries URL: for operations that do not cause side effects, such as transaction searching.

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.

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:

Products and Supported Brands

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

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:

Firefox:

Google Chrome:

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.

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

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:

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

Step 2:

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

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

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

Step 3:

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

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

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

Step 4:

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

On Firefox, under Servers, click on Import…:

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.

Step 6:

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

Step 7:

Click on Finish.

Step 8:

Click on Ok to complete the import.

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

Step 9:

Repeat the same procedure for the 3 sent files.

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

Perks of using Sandbox

• No affiliation is required to use Sandbox Cielo.
• Just access the Sandbox Registration to create an account.

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

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:

• Authorization;
• Capture;
• Cancellation;
• Consultation.

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

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:

• Authorization;
• Cancellation;
• Consultation.
  

The debit transaction needs to be authenticated:

• Authentication via 3DS 2.0: learn to simulate the authentication 3DS 2.0 in Sandbox in the 3DS documentation
• Authentication URL: it’s being discontinued. In this type of authentication, the debit card transactional flow works by getting an Authentication URL from the transaction response. On the authentication screen, the chosen option defines the status of the transaction.
  

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:

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:

• In the field CreditCard.CardNumber: send a card with 3 as the final digit, which simulates an expired card.
• In the field CreditCard.ExpirationDate: send an expiration date that has passed.
• Send the field Payment.Recurrent as true, to mark the transaction as recurring.

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.

Example

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

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.

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",
      "Tip":false,
      "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",
      "Tip":false,
      "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

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,
      "Tip":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,
        "Tip":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"
            }
        ]
    }
}

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,
      "Tip":false,
      "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,
       "Tip":false,
       "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

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,
      "Tip":false,
      "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,
        "Tip":false,
        "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"
            }
        ]
    }
}

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

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"
            }
        ]
    }
}

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.

• Internal MPI: it is a service already integrated to 3DS Cielo, there is no need to integrate or hire.

• External MPI: used when your e-commerce hires a MPI solution, without Cielo’s participation. No matter the 3DS version hired, follow the Authorization with Authentication guide.

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:

• Cardholder-Initiated Transaction (CIT): the transaction is initiated by the cardholder, who provides their payment credentials and allows them to be stored.
• Merchant-Initiated Transaction (MIT): the transaction is initiated by the merchant, after an agreement in which the cardholder authorizes the merchant to save and use the account data to initiate one or more transactions in the future (such as recurrent payments or installments, and charges commonly applied by the tourism and hospitality sector).
  
  

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.

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.

CIT and MIT subcategories

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

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.

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

To enable Pix for the sandbox environment, get in touch with our E-commerce support e-mail: cieloecommerce@cielo.com.br;

Get to know the cycle of a Pix transaction:

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:

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:

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

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

Requesting Pix refund

If your store needs to cancel a pix transaction, it is possible to ask for a refund. It is 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 via Notification Post.

• The shopper must require to the store (merchant) the partial or total refund, through the store’s support channels;
  
• The merchant agrees with the refund and identifies the original Pix payment.

When to ask for a Pix refund?

Some example scenarios for requesting a Pix refund are product return, charge errors, and product not available in stock.

Who should request a Pix refund via API E-commerce Cielo

The store (seller who received the Pix transaction amount) should request the Pix refund for API E-commerce Cielo, in agreement with the shopper. Important: Be aware of time limits (regulated by Banco Central do Brasil).

How to ask for a Pix refund?

Via API E-commerce Cielo or App Cielo Gestão.

Pix refund rules

• Refund will be effective only if the merchant has a positive balance;
• For transfers, sales and other Pix transactions, the time limit for refund is 90 days, according to Banco Central do Brasil;
• Clients that opt for automatic transfer will not have a positive balance in the payments account, therefore the refund will not be possible. The expected return is “Merchant with insufficient funds for refund” (“Lojista com saldo insuficiente para devolução”).

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

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}"
      }
   ]
}

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

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}"
            }
        ]
    }
}

Additional Rules

Number of characters per field and Provider:

Bradesco

Banco do Brasil

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:

• Apple Pay
• Google Pay
• Samsung Pay

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:

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:

• Code with 3 digits;
• Date in the MM/YYYY 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

*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"
            }
        ]
    }
}

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

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"
   }