Webservice integration 1.5

The purpose of this documentation is to orientate the developer about how integrate with Cielo Webservice, describing its functionalities, the methods to be used, list information to be sent and received and provide examples.

The integration mechanism with Cielo E-commerce is Yesple, so that are necessary only an intermediate knowledge in programming language for Web, HTTP/HTTP requisitions and handling XML archive to implant Cielo E-commerce solution with success.

Importantly to use this platform, the website must comply with safety rules or use the PCI certification. For questions about web security, please send email to: Segurança Web.

After conclude the registration and receive the instructions, you need to develop the integration using this documentation as a guide. Once the integration is completed, it’s necessary to fill the homologation form fully and then send it to Cielo E-commerce Web Support that will inform the secure key to the establishment.

Finally, after the development, to start the operation on production environment, first, it’s necessary start the homologation at Cielo.

Cielo Support

After reading this documentation, if you still have questions (technical or not), you can check Cielo technical support 24 hours per day, 7 days of week, in Portuguese and English, in the following contacts:

• +55 4002-9700 – Capitals and Metropolitan regions
• +55 0800-570-1700 – Others localities
• +55 11 2860-1348 – International
  • Option 1: Technical support
  • Option 2: E-commerce credential
• Email: cieloecommerce@cielo.com.br

Glossary

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

• Authentication: process to ensure that the buyer is really who says (authentic holder), generally it happens at the issuing bank using the digital token or security key card.
• Authorization: process to verify if a purchase can be realized or not with a card. In this moment several verification are done with the card and the holder (Funds availability, blocked account, blockades, etc), It’s also in this moment that the card limit is cross-checked with the transaction value.
• Cancellation: process to cancel the purchase that has been realized with card.
• Capture: process to confirm the authorization that has been realized previously. Only after the capture, the cardholder can check this in his bank statement or invoice.
• Key access: it’s a specific secure code for each store, created by Cielo, and used to realized an authentication and communication in all messages exchanged with Cielo. It’s also known as production key and data key.
• Buyer: who effectives the purchase at online store.
• Emitter (or Issuing Bank): it’s the financial institution that issues credit card, debt or voucher.
• Commercial establishment or EC: entity that responses for online store.
• Payment gateway: company responsible for technical integration and for processing transactions.
• Credential number: it’s an identifier number that the retailer receives after registered at Cielo.
• Holder: it’s the person who carries the card in the moment of purchase.
• Security Code: international program of MasterCard to allow the buyer authentication in the moment of purchase in e-commerce environment.
• TID (Transaction Identifier): a code composed by 20 characters that identifies only Cielo E-commerce transactions.
• Transaction: it’s the purchase order to cardholder at Cielo.
• VBV (Verified by Visa): International Program at Visa that allows the buyer authentication in the moment of purchase in e-commerce environment.

Products and Card Issuers supported

The current version of Cielo Webservice has support to the following products and card issuers:

Extended Validation Certificate

What is SSL Certificate?

The Extended Validation Certificate for web server offers authenticity and integrity of data from a web site, provides customers of virtual stores the guarantee that they are actually accessing the site they want, and not a fraudster site.

Specialized companies are responsible for making domain validation and depending on the type of certificate, also the owner of the domain entity.

What is EV SSL Certificate?

The EV Certificate was released in the market recently and ensures a higher level of security for customers of online stores.

It is a certificate of greater confidence and when https is accessed, the address bar turns green, giving more reliability to site visitors.

Internet Explorer:

Firefox

Google Chrome

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

Just install the following three files in the server Trustedstore. Cielo does not offer support to the installation of the Certificate. If you are unsure about how to install the EV Certificate, then you should contact your server vendor support.

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

Step by Step Installation

INSTALLATION ON THE SERVER OF ONLINE STORE

To install the EV Certificate you shall contact your server vendor support.

CUSTOMER ACCESS TO ONLINE STORE

Normally, the browser makes a Certificate update automatically, in case of failure and client contacted you to inform it, follow the steps:

1st STEP:

Save the files below into a new folder, or recall easily to be used later:

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

2nd STEP:

In the “Internet Explorer”, click on “Tools” menu and access the “Internet Options”:

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

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

3rd STEP:

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

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

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

4th STEP:

In Internet Explorer and in Chrome, “Certificate import wizard”, click “Next”

In Firefox “Abba servers,” click “Import”

5th STEP:

In Chrome and Internet Explorer “Certificate Import Assistent”, click “Browse”, find the folder where the files are and select the file “ecommerce.cielo.com.br.crt, click” Open “and then” Advance”.

6th STEP:

Select the desired option: add the certificate in a default folder or browse to the folder of your choice.

7th STEP:

Click “Finish”.

8th STEP:

Click “Ok” to complete the import.

The certificate can be viewed in the default tab “Others” or chosen by the customer.

9th STEP:

Repeat the same procedure for the 3 uploaded files.

Questions:

If you have questions at any stage or other technical information, contact the Support Web Cielo e-Commerce in the following channels:

• Email: cieloecommerce@cielo.com.br
• Metropolitan region: 4002-9700
• Other Cities: 0800 570 1700

Hours: 24 hours a day, 7 days a week.

Overview

In this documentation we will be present an overview of Cielo E-commerce and the technical mechanism of Webservice integration format (named in the previous version as “Buy Page Loja”).

To more information about integration at Checkout Cielo format (named in the previous versions as Buy Page Cielo or Integrated Solution) access: https://www.cielo.com.br/ecommerce.

For all purchase orders, the purpose is convert it in a sale. A sale using a card can be characterized as an authorized and captured transaction.

Solutions characteristics:

The Webservice solution at Cielo E-commerce platform has been developed based on XML technology, a market pattern and independent of technologies used by our customers. In this way, it’s possible to integrate it by using the various programing languages, like: ASP, ASP.NEt, Java, PHP, Ruby, Python, etc.

Among others characteristics, the most highlighted attributes of Cielo E-commerce platform are:

• No proprietary application: it’s not necessary to install application at online store environment in any case.
• Yesplicity: the protocol used is purely HTTP, without necessity of using SOAP.
• Registering facility: the customer’s credential information (affiliation number and access key) transits in common fields of XML, without necessity of special attributes, as SOAP Header.
• Security: the information exchange always happens between the Store Server and Cielo, in other words, without the buyer’s browser.

Consideration about integration

• All the Web Service requests at Cielo must contain a retailer’s link authentication, composed by credential number and access key.
• The store registration must be active on Cielo.
• You must define appropriate deadline ton HTTP requests to Cielo, we recommend 30 seconds.
• The Root certificate of certifier entity (CA) of our Web Service must be registered on Truststore that will be used. Because our certifier has a wider market acceptance, probably this is already registered on Truststore of own operational system.
• We make available the ecommerce.xsd archive on integration kit to make easier the validation format restriction, size field, types and data domains.
• In all messages of data/hour you have to follow the format: yyyy=MM=ddTHH24:mm:ss. Example: 2011-12-21T11:32:45.
• The monetary value is always handled as intire values, without representation of decimals place, in such case the last two digits are considered as “centavos”. Example: R$ 1.286,87 is represented as 128687; R$ 1,00 is represented as 100.

Architecture

The integration is realized through the available services as Web Services. The model employed is quite Yesple: there is an unique URL (endpoint) that receives the POSTs via HTTPs and, depending of XML format sent, a specific operation is realized.

The Web Service request is summarized for:

• The message in XML format, defined according to the functionality.
• The destiny (testing environment or production).
• The return on XML format, can be: <transacao/>, <retorno-token> or <erro/>.

POST /servicos/ecommwsec.do HTTP/1.1
Host: ecommerce.cielo.com.br
Content-Type: application/x-www-form-urlencoded
Content-Length: length
mensagem=<?xml version="1.0" encoding="ISO-8859-1"?><requisicao-captura id="3e22bdd0-2017-4756-80b7-35a532e6c973" versao="1.2.1"><tid>10069930690101012005</tid><dados-ec><numero>1006993069</numero><chave>25fbb99741c739dd84d7b06ec78c9bac718838630f30b112d033ce2e621b34f3</chave></dados-ec><valor>3880</valor></requisicao-captura>

Transaction

The main element on Cielo E-commerce is the transaction, created from a HTTP request to Cielo Webservice. The unique identification of Cielo transactions is done through TID field, that is present at message’s return of authorization. This field is essential to realize inquires, captures and cancellations.

From transaction creation, it can assume the following status:

The transition of status can be realized through the message exchange between the store and Cielo, or automatically, for example, when an authorized transaction capture deadline expires.

Mandatory Updates

Payment Facilitators

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

The new fields are contained within the <subcredenciador> tag. In addition to the fields in this new node, facilitators will also have to send the <soft-descriptor> tag. Below is an example of sending and reply.

Request

<requisicao-transacao id="1abd5a36-fba5-4a92-9341-7c9e9d44aa1a" versao="1.3.0">
    <dados-ec>
        <numero>2000000001</numero>
        <chave>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</chave>
        <subcredenciador>
            <numero>12345678901</numero>
            <sub-ec>
                <numero>2000130733</numero>
                <mcc>5542</mcc>
                <endereco>Alameda Xingu, 512</endereco>
                <cidade>Barueri</cidade>
                <estado>SP</estado>
                <codigo-postal>06537085</codigo-postal>
                <telefone>11978962345</telefone>
                <documento>53976428000130</documento>
                <codigo-pais>076</codigo-pais>
            </sub-ec>
        </subcredenciador>
    </dados-ec>
    <dados-portador>
        <numero>518605152xxxxxx5923</numero>
        <validade>aaaamm</validade>
        <indicador>1</indicador>
        <codigo-seguranca>xxx</codigo-seguranca>
        <nome-portador>Jose Luis</nome-portador>
        <token/>
    </dados-portador>
    <dados-pedido>
        <numero>54583</numero>
        <valor>10000</valor>
        <moeda>986</moeda>
        <data-hora>2016-02-16T13:45:05</data-hora>
        <descricao>Compra Online</descricao>
        <idioma>PT</idioma>
        <soft-descriptor>lojinha</soft-descriptor>
    </dados-pedido>
    <forma-pagamento>
        <bandeira>mastercard</bandeira>
        <produto>1</produto>
        <parcelas>1</parcelas>
    </forma-pagamento>
    <url-retorno>http://www.cielo.com.br</url-retorno>
    <autorizar>3</autorizar>
    <capturar>true</capturar>
    <gerar-token>false</gerar-token>
</requisicao-transacao>

Response

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<transacao id="1abd5a36-fba5-4a92-9341-7c9e9d44aa1a" versao="1.3.0" xmlns="http://ecommerce.cbmp.com.br">
    <tid>2000153601009A0OCH1E</tid>
    <pan>qM5R3jZDvsXFU7KUAM5fmzKg7dA7ZaG2/gc2rFeFMW0=</pan>
    <dados-pedido>
        <numero>54583</numero>
        <valor>10000</valor>
        <moeda>986</moeda>
        <data-hora>2016-02-16T13:45:05</data-hora>
        <descricao>Compra Online</descricao>
        <idioma>PT</idioma>
    </dados-pedido>
    <forma-pagamento>
        <bandeira>mastercard</bandeira>
        <produto>1</produto>
        <parcelas>1</parcelas>
    </forma-pagamento>
    <status>6</status>
    <autenticacao>
        <codigo>6</codigo>
        <mensagem>Transacao sem autenticacao</mensagem>
        <data-hora>2020-01-10T15:32:45.843-03:00</data-hora>
        <valor>10000</valor>
        <eci>0</eci>
    </autenticacao>
    <autorizacao>
        <codigo>6</codigo>
        <mensagem>Transacao autorizada</mensagem>
        <data-hora>2020-01-10T15:32:45.844-03:00</data-hora>
        <valor>10000</valor>
        <lr>00</lr>
        <arp>192379</arp>
        <nsu>094004</nsu>
    </autorizacao>
    <captura>
        <codigo>6</codigo>
        <mensagem>Transacao capturada com sucesso</mensagem>
        <data-hora>2020-01-10T15:32:45.844-03:00</data-hora>
        <valor>10000</valor>
    </captura>
</transacao>

CBPS Transactions

Today, consumers often need to log in to several billing sites to pay their bills, many of which do not accept card payments. Suppliers of the Account Payment Service for Consumers (CBPS) simplify the process by allowing consumers to make all bill payments with a card and in a single channel. Generally, CBPS providers offer a mobile application or electronic commerce for the bearer to manage and make payments.

Visa requests that providers of this type of service start to inform which transactions are CBPS as of Oct20. This information must be sent in the transactional message in the field “payment-account” according to the XML below.

Request

<requisicao-transacao id="1abd5a36-fba5-4a92-9341-7c9e9d44aa1a" versao="1.3.0">
    <dados-ec>
        <numero>2000000001</numero>
        <chave>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</chave>
        <subcredenciador>
            <numero>12345678901</numero>
            <sub-ec>
                <numero>2000130733</numero>
                <mcc>5542</mcc>
                <endereco>Alameda Xingu, 512</endereco>
                <cidade>Barueri</cidade>
                <estado>SP</estado>
                <codigo-postal>06537085</codigo-postal>
                <telefone>11978962345</telefone>
                <documento>53976428000130</documento>
                <codigo-pais>076</codigo-pais>
            </sub-ec>
        </subcredenciador>
    </dados-ec>
    <dados-portador>
        <numero>518605152xxxxxx5923</numero>
        <validade>aaaamm</validade>
        <indicador>1</indicador>
        <codigo-seguranca>xxx</codigo-seguranca>
        <nome-portador>Jose Luis</nome-portador>
        <token/>
    </dados-portador>
    <dados-pedido>
        <numero>54583</numero>
        <valor>10000</valor>
        <moeda>986</moeda>
        <data-hora>2016-02-16T13:45:05</data-hora>
        <descricao>Compra Online</descricao>
        <idioma>PT</idioma>
        <soft-descriptor>lojinha</soft-descriptor>
        <pagamento-conta>true</pagamento-conta>
    </dados-pedido>
    <forma-pagamento>
        <bandeira>mastercard</bandeira>
        <produto>1</produto>
        <parcelas>1</parcelas>
    </forma-pagamento>
    <url-retorno>http://www.cielo.com.br</url-retorno>
    <autorizar>3</autorizar>
    <capturar>true</capturar>
    <gerar-token>false</gerar-token>
</requisicao-transacao>

Creating transactions

Every transaction on Cielo E-commerce starts through a POST (HTTPS) to Webservice at Cielo with a XML message <requisicao-transacao>, which group of TAGS defines a transaction configuration:

<?xml version="1.0" encoding="ISO-8859-1"?>
<requisicao-transacao id="a97ab62a-7956-41ea-b03f-c2e9f612c293" versao="1.2.1">
  <dados-ec>
    <numero>1006993069</numero>
    <chave>25fbb997438630f30b112d033ce2e621b34f3</chave>
  </dados-ec>
  <dados-portador>
    <numero>4012001038443335</numero>
    <validade>201508</validade>
    <indicador>1</indicador>
    <codigo-seguranca>973</codigo-seguranca>
    <token/>
  </dados-portador>
  <dados-pedido>
    <numero>178148599</numero>
    <valor>1000</valor>
    <moeda>986</moeda>
    <data-hora>2011-12-07T11:43:37</data-hora>
    <descricao>[origem:10.50.54.156]</descricao>
    <idioma>PT</idioma>
    <taxa-embarque/>
    <soft-descriptor/>
    <numero-bilhete>123456</numero-bilhete>
  </dados-pedido>
  <forma-pagamento>
    <bandeira>visa</bandeira>
    <produto>A</produto>
    <parcelas>1</parcelas>
  </forma-pagamento>
  <url-retorno>http://localhost/lojaexemplo/retorno.jsp</url-retorno>
  <autorizar>1</autorizar>
  <capturar>false</capturar>
  <campo-livre>Informações extras</campo-livre>
  <bin>455187</bin>
  <gerar-token>false</gerar-token>
  <avs>
  <![CDATA[
    <dados-avs>
      <endereco>Rua Teste AVS</endereco>
      <complemento>Casa</complemento>
      <numero>123</numero>
      <bairro>Vila AVS</bairro>
      <cep>12345-123</cep>
      <cpf>11111111111</cpf>
    </dados-avs>
  ]]>
  </avs>
</requisicao-transacao>

ROOT Node

dados-ec

dados-portador

dados-pedido

forma-pagamento

Integration flux and redirection

After creating a transaction, the browsing flux can be directed to Cielo environment, if the retailer requests the authentication on XML message.

In this situation, the retailer’ system will obtain the amount of TAG of XML returned to realize a redirection on customer browser and continues the process. The redirecting must be realized in “Full Screen” mode. In the other words, there is no more support to the pop up window. This way, from a checkout screen must be realized a redirecting to URL returned at transaction’s creation.

After the authentication process, the flux is returned to the retailer through the present information on TAG, sent in the first request to Cielo.

The diagram below makes easier the view of complete flux of browsing:

In the other hand, when there is no authentication, doesn’t exist the context exchange or redirections and the integration is more Yesple:

Return types

There are three types of return that can be created on WebService response:

1. <transacao>
2. <retorno-token>
3. <erro>

To operations related to a transaction (consults, authorization, capture and cancellation) in case of success the response is always a XML of type <transacao>. In case of an exclusive request to create a token, the response expected is <retorno-token>.

The next example shows the more reduced way of a message of return such . Basically, it’s composed by order data and data from transaction’s configuration.

<?xml version="1.0" encoding="ISO-8859-1"?>
<transacao versao="1.6.2" id="af32f93c-5e9c-4f44-9478-ccc5aca9319e" xmlns="http://ecommerce.cbmp.com.br">
    <tid>100699306908642F1001</tid>
    <pan>uv9yI5tkhX9jpuCt+dfrtoSVM4U3gIjvrcwMBfZcadE=</pan>
    <dados-pedido>
        <numero>2132385784</numero>
        <valor>1000</valor>
        <moeda>986</moeda>
        <data-hora>2013-02-18T16:51:30.852-03:00</data-hora>
        <descricao>[origem:0:0:0:0:0:0:0:1]</descricao>
        <idioma>PT</idioma>
        <taxa-embarque>0</taxa-embarque>
    </dados-pedido>
    <forma-pagamento>
        <bandeira>visa</bandeira>
        <produto>1</produto>
        <parcelas>1</parcelas>
    </forma-pagamento>
    <status>4</status>
    <autenticacao>
        <codigo>4</codigo>
        <mensagem>Transacao sem autenticacao</mensagem>
        <data-hora>2013-02-18T16:51:31.158-03:00</data-hora>
        <valor>1000</valor>
        <eci>7</eci>
    </autenticacao>
    <autorizacao>
        <codigo>4</codigo>
        <mensagem>Transação autorizada</mensagem>
        <data-hora>2013-02-18T16:51:31.460-03:00</data-hora>
        <valor>1000</valor>
        <lr>00</lr>
        <arp>123456</arp>
        <nsu>549935</nsu>
        <par>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</par>
    </autorizacao>
</transacao>

The more important information are:

• TID: it’s the link between purchase order of online store and Cielo’s transaction.
• URL de autenticação: indicates the page that starts the authentication (when requested).
• Status: it’s the base information to store control the transaction.

The table below details TAGS from basic-XML of return, identified by source node <transacao>:

Finally, there is another type of return which is employed every time a request can’t be executed, because it’s invalid or for some failure in its process. In this scenario, root node of XML response is like this <erro>.

<?xml version="1.0" encoding="ISO-8859-1"?>
<erro xmlns="http://ecommerce.cbmp.com.br">
  <codigo>001</codigo>
  <messagem><![CDATA[O XML informado nao e valido:- string value '' does not match pattern for type of valor element in DadosPedido in namespace http://ecommerce.cbmp. com.br: '<xml-fragment/>]]>
  </mensagem>
</erro>

When the transaction is invalid, we can classify the error in two types:

• Syntatic error: it happens when a XML message doesn’t respect the rules defined by ecommerce.xsd archive. For example, a letter in numeric field, or an absence of a mandatory amount.
• Semantic error: it happens when a request asks an operation that is not supported for a specific transaction. For example, try to capture a transaction unauthorized, or even, cancel a transaction that is already cancelled.

Security level and authentication

Depending of card issuer, the transaction of Cielo E-commerce platform can be configured to be authenticated on card bank issuer (holder), in order to ensure the mayor level of security to the retailer.

The authentication isn’t done automatically between systems, so it’s necessary the customer interaction in the process, according the following explanation:

This happens always on the bank website (Internet Banking), using mechanisms and technologies independently from Cielo. In this way, it’s possible for bank use an electronic token and password meanwhile another uses the password cards or CPF [c]to authenticate a transaction.

As shown previously, the mechanic of redirection is obtained through a tag <url-autenticacao> that is returned by Cielo on XML in the moment of a request of authorization to Web Service.

The authentication is mandatory for debt transactions and optional for credit. Nowadays only Visa and MasterCard support this functionality and consequently, only these two card issuers have the debt product.

When there is authentication, the flux to execute an authorization happens in two steps, according to the diagram below:

1. finishOrder() - it happens when a cardholder finishes the order and starts the payment purchase.
2. createTransaction (authenticated) - the retailer system send a XML request <requisicao-transacao> requesting an authenticated transaction, in other words, the TAG will be 0,1 or 2. After this, Cielo will inform at XML returned a field with the address which the holder must be redirected for.
3. access (url-authentication) - the holder’s browser is redirected to Cielo environment. Thereby, the Cielo’s page is accessed, it automatically is directed to an issuer bank (3.1). This redirect is so fast that is practically imperceptible.
4. authenticate (token, cpf) - the holder will be on bank environment and will use some mechanism provided by his/her own issuer to realize the authentication of the transaction (generally token, “bingo card”/security card, cpf, electronic sign, etc).
5. resultAuthentication ()- the issuer bank redirects the flux to Cielo with the result of authentication. Then, the flux backs to normal, according to item “2.3 Architecture of integration”. 1.process () - Cielo system process the return of authentication and submit to authorization and, optionally, to automatic capture. 2. sendRedirect(url-return) - Cielo system send a redirection to customer browser to the address specificated on URL of return, provided on the first request (<requisicao-transacao>)
   1. access (url-return) - the holder’s browser access the URL on store environment, where we recommend that you have a consult request via TID to Cielo Web Service.

Notes

• Only on first redirection (1.2: send Redirect()) is Online Store responsability.
• The buyer is redirected on bank issuer only if the authentication is available. Otherwise, the transaction will progress to authorization automatically (excepting if the authentication has been just requested).

The prerequisites for a transaction to be certified are listed below:

• Bank and card issuer should be participating in the authentication program;
• The BIN card must be participant in authentication program;
• Setting the // is 0, 1 or 2.

Looking at the diagram of section Transaction, you can see that all transactions will pass through status “Authenticated” or “not authenticated”. Consequently, all receive the node <autenticacao> in the merchant response XML. Below the XML with the authentication node:

<?xml version="1.0" encoding="ISO-8859-1"?>
<transacao versao="1.3.0" id="5e445904-963e-4fa1-95cd-55ef88c289cc" xmlns="http://ecommerce.cbmp.com.br">
  <tid>1001734898073E931001</tid>
  <pan>IqVz7P9zaIgTYdU41HaW/OB/d7Idwttqwb2vaTt8MT0=</pan>
  <dados-pedido>
    <numero>1196683550</numero>
    <valor>1000</valor>
    <moeda>986</moeda>
    <data-hora>2011-12-08T10:44:24.244-02:00</data-hora>
    <descricao>[origem:10.50.54.156]</descricao>
    <idioma>PT</idioma>
    <taxa-embarque>1000</taxa-embarque>
  </dados-pedido>
  <forma-pagamento>
    <bandeira>visa</bandeira>
    <produto>1</produto>
    <parcelas>1</parcelas>
  </forma-pagamento>
  <status>2</status>
  <autenticacao>
    <codigo>2</codigo>
    <mensagem>Autenticada com sucesso</mensagem>
    <data-hora>2011-12-08T10:44:47.311-02:00</data-hora>
    <valor>1000</valor>
    <eci>5</eci>
  </autenticacao>
</transacao>

Just the “node” fields <autenticacao> are listed on the table below:

The ECI field (Eletronic Commerce Indicator) represents how safety is a transaction. This amount must be considered for the retailer to decide about transaction capture.

Reply Codes Catalog

Authorization Codes LR

Below are the response codes that account for 99% of the returns generated in the authorization process. The other existing codes are not listed as rarely occur or in specific cases. For these cases must be assumed that they are not likely to retry.

If you have a high amount of return codes that are not listed below, please contact the Cielo Web Support E-commerce.

Return codes (ABECS)

The Brazilian Association of Credit Card and Services Companies (ABECS) establishes as of July 15, 2020, the standardization of the return code of refused sales authorizations for both the physical payment and e-commerce solutions of the Brazilian market .

This normative measure seeks to bring benefits to the entire payment market, providing greater transparency in the understanding of the reason for the refusal of transactions, in addition to enabling greater assertiveness in the adoption of sales retentive strategies.

Cielo informs its customers that it’s prepared to process transactions following this new market standard, below is the table of codes standardized by ABECS.

Other return codes

Error Codes

The errors that may appear in the XML message through the TAG ‘’ are arranged as follows:

Table integration errors

Status of transactions

ECI

Operations and configurations

Creating an authorization of transaction

The request for an authorization is the main operation of Cielo E-commerce, because it’s through it, that a sale can be concreted and the sale process can be finished. The authorization has a sequence of configuration that can be customized, besides the functionalities that have value to customer and retailers.

Direct authorization

<?xml version="1.0" encoding="ISO-8859-1"?>
<requisicao-transacao id="a97ab62a-7956-41ea-b03f-c2e9f612c293" versao="1.2.1">
  <dados-ec>
    <numero>1006993069</numero>
    <chave>25fbb997438630f30b112d033ce2e621b34f3</chave>
  </dados-ec>
  <dados-portador>
    <numero>4012001038443335</numero>
    <validade>201508</validade>
    <indicador>1</indicador>
    <codigo-seguranca>973</codigo-seguranca>
  </dados-portador>
  <dados-pedido>
    <!-- ... -->
  </dados-pedido>
  <forma-pagamento>
    <bandeira>visa</bandeira>
    <produto>1</produto>
    <parcelas>1</parcelas>
  </forma-pagamento>
  <url-retorno>http://localhost/lojaexemplo/retorno.jsp</url-retorno>
  <autorizar>3</autorizar>
  <capturar>false</capturar>
</requisicao-transacao>

The direct authorization is characterized for being a transaction without authentication from holder, because it’s a retailer option (and risk), or because the card issuer or emitter don’t have support. The direct authorization can be done in two ways: traditional (with card data) or using a token.

Traditional

• Purpose - Submit a direct transaction using a credit card.
• Rules
  • The online store register must be enable to send card data.
  • Send a TAG with the value “3”.
  • Valid only for credit.
  • The retailer must pay attention on sending card rules.
  • In direct authorization, the security level of transaction (ECI) is defined as:
    • “7” for Visa, Diners, Discover, Elo and JCB.
    • “0” for Mastercard, Aura and Hipercard.

Recurrent authorization

<?xml version="1.0" encoding="ISO-8859-1"?>
<requisicao-transacao id="a97ab62a-7956-41ea-b03f-c2e9f612c293" versao="1.2.1">
  <dados-ec>
    <numero>1006993069</numero>
    <chave>25fbb997438630f30b112d033ce2e621b34f3</chave>
  </dados-ec>
  <dados-portador>
    <numero>4012001038443335</numero>
    <validade>201508</validade>
    <indicador>1</indicador>
    <codigo-seguranca>973</codigo-seguranca>
  </dados-portador>
  <dados-pedido>
    <!-- ... -->
  </dados-pedido>
  <forma-pagamento>
    <bandeira>visa</bandeira>
    <produto>1</produto>
    <parcelas>1</parcelas>
  </forma-pagamento>
  <url-retorno>http://localhost/lojaexemplo/retorno.jsp</url-retorno>
  <autorizar>4</autorizar>
  <capturar>false</capturar>
</requisicao-transacao>

The recurrent authorization must be done in two ways: sending a token previously registered, or using a card. The recurrent transaction is very Yesilar than traditional transaction, the changes consist on the rules that emitter and card issuer use to authorize or deny a transaction. Another difference is related to “Renova Fácil” (Easy Renew).

Recurrent authorization with card

• Purpose - Submit a recurrent transaction using a credit card.**
• Rules
  • Send a TAG ‘’ with value “4”.
  • Valid just for lump sum.

EASY RENEW (Renova Fácil):

<?xml version="1.0" encoding="ISO-8859-1"?>
<transacao xmlns="http://ecommerce.cbmp.com.br" versao="1.2.1" id="d35b67189442">
  <tid>10069930690362461001</tid>
  <pan>uv9yI5tkhX9jpuCt+dfrtoSVM4U3gIjvrcwMBfZcadE=</pan>
  <dados-pedido>
    <!-- ... -->
  </dados-pedido>
  <forma-pagamento>
    <!-- ... -->
  </forma-pagamento>
  <status>5</status>
  <!-- ... -->
  <autorizacao>
    <codigo>5</codigo>
    <mensagem>Autorização negada</mensagem>
    <data-hora>2011-12-09T10:58:45.847-02:00</data-hora>
    <valor>1000</valor>
    <lr>57</lr>
    <nsu>221766</nsu>
  </autorizacao>
  <dados-portador>
    <numero>4012001038443335</numero>
    <validade>201508</validade>
    <codigo-seguranca/>
  </dados-portador>
</transacao>

This functionality makes easier to identify a card which has been replaced for another at emitter bank. In this way, when a recurrent transaction is submitted to Web Service and Cielo identifies that the card used is outdated, the system will behave like that:

1. If the recurrent transaction has been send through a card, the authorization will be declined and it will returned the data of new card, according to the diagram below:

Authorization of a transaction previously created

<?xml version="1.0" encoding="ISO-8859-1"?>
<requisicao-autorizacao-tid id="0000000000" versao="1.2.0">
  <tid>1006993069990BCAA001</tid>
  <dados-ec>
    <numero>1006993069</numero>
    <chave>25fbb997438630f30b112d033ce2e621b34f3</chave>
  </dados-ec>
</requisicao-autorizacao-tid>

To the establishments that use the authentication process of authentication it’s possible to request an authorization of transaction that stopped after the execution of this process. The message to perform this operation is “requisicao-autorizacao-tid”, as described below:

Transaction with token

<?xml version="1.0" encoding="ISO-8859-1"?>
<requisicao-token id="8fc889c7-004f-42f1-963a-31aa26f75e5c" versao="1.2.1">
  <dados-ec>
    <numero>1006993069</numero>
    <chave>25fbb99741c739dd84d7b06ec78c9bac718838630f30b112d033ce2e621b34f3</chave>
  </dados-ec>
  <dados-portador>
    <numero>4012001038443335</numero>
    <validade>201508</validade>
    <nome-portador>FULANO DA SILVA</nome-portador>
  </dados-portador>
</requisicao-token>

• Purpose - Request the creation of a token associated to a credit card to help the transaction sending without card.
• Rules
  • The Token is unique to a specific [Card+Commercial Establishment]. So, a card can be “tokenized” in more than a store and each one will has different codes.
  • If more than one request has been sent with the same data, the token returned will be always the same.
  • The creation of token is independent of a transaction result (approved/declined).

Response

<?xml version="1.0" encoding="ISO-8859-1"?>
<retorno-token xmlns="http://ecommerce.cbmp.com.br" versao="1.2.1" id="57239017">
  <token>
    <dados-token>
      <codigo-token>TuS6LeBHWjqFFtE7S3zR052Jl/KUlD+tYJFpAdlA87E=</codigo-token>
      <status>1</status>
      <numero-cartao-truncado>455187******0183</numero-cartao-truncado>
    </dados-token>
  </token>
</retorno-token>

The return will be like: when a request has been concluded with success, or in case of failure .

Direct Authorization via TOKEN

<?xml version="1.0" encoding="ISO-8859-1"?>
<requisicao-transacao id="a97ab62a-7956-41ea-b03f-c2e9f612c293" versao="1.2.1">
  <dados-ec>
    <numero>1006993069</numero>
    <chave>25fbb997438630f30b112d033ce2e621b34f3</chave>
  </dados-ec>
  <dados-portador>
    <token>TuS6LeBHWjqFFtE7S3zR052Jl/KUlD+tYJFpAdlA87E=</token>
  </dados-portador>
  <dados-pedido>
    <!-- ... -->
  </dados-pedido>
  <forma-pagamento>
    <bandeira>visa</bandeira>
    <produto>1</produto>
    <parcelas>1</parcelas>
  </forma-pagamento>
  <url-retorno>http://localhost/lojaexemplo/retorno.jsp</url-retorno>
  <autorizar>3</autorizar>
  <capturar>true</capturar>
</requisicao-transacao>

• Purpose - To submit a direct transaction (without authentication) using a token previously registered.
• Rules
  • To send a TAG with the value “3”.
  • Token must be unlocked
  • Valid just for lump sum.

Recurrent Authorization with TOKEN

<?xml version="1.0" encoding="ISO-8859-1"?>
<requisicao-transacao id="a97ab62a-7956-41ea-b03f-c2e9f612c293" versao="1.2.1">
  <dados-ec>
    <numero>1006993069</numero>
    <chave>25fbb997438630f30b112d033ce2e621b34f3</chave>
  </dados-ec>
  <dados-portador>
    <token>TuS6LeBHWjqFFtE7S3zR052Jl/KUlD+tYJFpAdlA87E=</token>
  </dados-portador>
  <dados-pedido>
    <!-- ... -->
  </dados-pedido>
  <forma-pagamento>
    <bandeira>visa</bandeira>
    <produto>1</produto>
    <parcelas>1</parcelas>
  </forma-pagamento>
  <url-retorno>http://localhost/lojaexemplo/retorno.jsp</url-retorno>
  <autorizar>4</autorizar>
  <capturar>true</capturar>
</requisicao-transacao>

• Purpose - To submit a recurrent transaction using a token previously registered.** - Submeter uma transação recorrente com o uso de um token previamente cadastrado.
• Rules
  • To send a TAG with the value “4”.
  • Token must be unlocked.
  • Valid just for lump sum.

Easy Renew with TOKEN

<?xml version="1.0" encoding="ISO-8859-1"?>
<transacao xmlns="http://ecommerce.cbmp.com.br" versao="1.2.1" id="d35b67189442">
  <tid>10069930690362461001</tid>
  <pan>uv9yI5tkhX9jpuCt+dfrtoSVM4U3gIjvrcwMBfZcadE=</pan>
  <dados-pedido>
    <!-- ... -->
  </dados-pedido>
  <forma-pagamento>
    <!-- ... -->
  </forma-pagamento>
  <status>5</status>
  <!-- ... -->
  <autorizacao>
    <codigo>5</codigo>
    <mensagem>Autorização negada</mensagem>
    <data-hora>2011-12-09T10:58:45.847-02:00</data-hora>
    <valor>1000</valor>
    <lr>57</lr>
    <nsu>221766</nsu>
  </autorizacao>
  <token>
    <dados-token>
      <codigo-token>TuS6LeBHWjqFFtE7S3zR052Jl/KUlD+tYJFpAdlA87E=</codigo-token>
      <status>1</status>
      <numero-cartao-truncado>455187******0183</numero-cartao-truncado>
    </dados-token>
  </token>
</transacao>

This functionality makes easier to identify a card which has been replaced for another in emitter bank. So, when a recurrent transaction is submitted to Web Service and Cielo identifies a card in use outdated, the system will behave like that:

1. In case of recurrent transaction had been sent through a token, the authorization will be declined and a new token will return to be used, according to the diagram below:

Creating TOKEN

<?xml version="1.0" encoding="ISO-8859-1"?>
<requisicao-transacao id="a97ab62a-7956-41ea-b03f-c2e9f612c293" versao="1.2.0">
  <!-- ... -->
  <gerar-token>true</gerar-token>
</requisicao-transacao>

• Purpose - Beyond the specific message to creation of a token, described in a transaction with token, it’s possible to employ an authorization request to ask a creation of token, adding the information in the node of request of a transaction.
• Rules
  • In case of a card being submitted more than once for the same retailer, the Token created will be the same.

Card On File

The cardholder may allow his card data to be stored securely for future transactions at the Merchant.

Below are the situations to identify if it’s the first or subsequent transaction through the first transaction TAG:

• Situation 1: - THERE IS card date storage and IT’S first transaction.

<credencial-armazenada>
  <primeira-transacao>S</primeira-transacao>
</credencial-armazenada>

• Situation 2: - THERE IS card date storage and IT ISN’T first transaction.

<credencial-armazenada>
  <primeira-transacao>N</primeira-transacao>
</credencial-armazenada>

• Situation 3: - THERE ISN’T storage of card data, the establishment Yesply does not send this tag.

Request

<?xml version="1.0"?>
<requisicao-transacao id="1abd5a36-fba5-4a92-9341-7c9e9d44aa1a" versao="1.3.0">
  <dados-ec>
    <numero>2000019700</numero>
    <chave>65d156641f765861451c7c1270a4c09a617863b031b2e4b0c4a09cd390783c82</chave>
  </dados-ec>
  <dados-portador>
    <numero>4096031111110011</numero>
    <validade>201712</validade>
    <indicador>1</indicador>
    <codigo-seguranca>123</codigo-seguranca>
    <nome-portador>TESTE CUCUMBER</nome-portador>
  </dados-portador>
  <dados-pedido>
    <numero>77115</numero>
    <valor>315000</valor>
    <moeda>986</moeda>
    <data-hora>2016-02-16T13:45:05</data-hora>
    <descricao>Compra Online</descricao>
    <idioma>PT</idioma>
    <soft-descriptor>soft cucumber</soft-descriptor>
  </dados-pedido>
  <forma-pagamento>
    <bandeira>visa</bandeira>
    <produto>1</produto>
    <parcelas>1</parcelas>
  </forma-pagamento>
  <url-retorno>http://www.cielo.com.br</url-retorno>
  <autorizar>3</autorizar>
  <capturar>false</capturar>
  <credencial-armazenada>
    <primeira-transacao>S</primeira-transacao>
  </credencial-armazenada>
  <gerar-token>false</gerar-token>
</requisicao-transacao>

Response

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<transacao id="1abd5a36-fba5-4a92-9341-7c9e9d44aa1a" versao="1.3.0" xmlns="http://ecommerce.cbmp.com.br">
  <tid>20000197008CTDEP7DHC</tid>
  <pan>iwcdiV9SLhtb/dsQNXRHT426+tgjcLtMzchw5YggfP8=</pan>
  <dados-pedido>
    <numero>77115</numero>
    <valor>315000</valor>
    <moeda>986</moeda>
    <data-hora>2016-02-16T13:45:05</data-hora>
    <descricao>Compra Online</descricao>
    <idioma>PT</idioma>
  </dados-pedido>
  <forma-pagamento>
    <bandeira>elo</bandeira>
    <produto>A</produto>
    <parcelas>1</parcelas>
  </forma-pagamento>
  <status>6</status>
  <autenticacao>
    <codigo>6</codigo>
    <mensagem>Autenticada com sucesso</mensagem>
    <data-hora>2019-08-28T13:45:43.959-03:00</data-hora>
    <valor>315000</valor>
    <eci>5</eci>
  </autenticacao>
  <autorizacao>
    <codigo>6</codigo>
    <mensagem>Transacao autorizada</mensagem>
    <data-hora>2019-08-28T13:45:43.959-03:00</data-hora>
    <valor>315000</valor>
    <lr>00</lr>
    <arp>882114</arp>
    <nsu>248001</nsu>
  </autorizacao>
  <captura>
    <codigo>6</codigo>
    <mensagem>Transacao capturada com sucesso</mensagem>
    <data-hora>2019-08-28T13:45:43.959-03:00</data-hora>
    <valor>315000</valor>
  </captura>
</transacao>

Flag Tokenization

Customers who card tokenize along with the flags can send the information to Cielo in the transactional flow.

Request

<?xml version="1.0"?>
<requisicao-transacao id="1abd5a36-fba5-4a92-9341-7c9e9d44aa1a" versao="1.3.0">
    <dados-ec>
        <numero>2000019700</numero>
        <chave>65d156641f765861451c7c1270a4c09a617863b031b2e4b0c4a09cd390783c82</chave>
    </dados-ec>
    <dados-portador>
        <numero>4084359300407900</numero>
        <validade>201712</validade>
        <indicador>1</indicador>
        <codigo-seguranca>123</codigo-seguranca>
        <nome-portador>TESTE CUCUMBER</nome-portador>
        <token/>
        <carteira>
            <tipo>MERCHANT</tipo>
            <codigo-captura/>
            <cavv>A901234A5678A0123A567A90120=</cavv>
            <eci>4</eci>
        </carteira>
    </dados-portador>
    <dados-pedido>
        <numero>86785</numero>
        <valor>315000</valor>
        <moeda>986</moeda>
        <data-hora>2016-02-16T13:45:05</data-hora>
        <descricao>Compra Online</descricao>
        <idioma>PT</idioma>
        <soft-descriptor>soft cucumber</soft-descriptor>
    </dados-pedido>
    <forma-pagamento>
        <bandeira>visa</bandeira>
        <produto>1</produto>
        <parcelas>1</parcelas>
    </forma-pagamento>
    <url-retorno>http://www.cielo.com.br</url-retorno>
    <autorizar>3</autorizar>
    <capturar>false</capturar>
    <gerar-token>false</gerar-token>
    <avs>
        <![CDATA[<dados-avs><endereco>Rua Credito</endereco><complemento>Apto 504</complemento><numero>745</numero><bairro>Vila Cucumber</bairro><cep>13040-144</cep><cpf>30652698501</cpf></dados-avs>]]>
    </avs>
</requisicao-transacao>

Response

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<transacao id="1abd5a36-fba5-4a92-9341-7c9e9d44aa1a" versao="1.3.0" xmlns="http://ecommerce.cbmp.com.br">
    <tid>2000019700008C730BOC</tid>
    <pan>Ma7WOe2ciLGucTokmn5mX2mkpeVJGkqVTavqR42Pm5k=</pan>
    <dados-pedido>
        <numero>86785</numero>
        <valor>315000</valor>
        <moeda>986</moeda>
        <data-hora>2016-02-16T13:45:05</data-hora>
        <descricao>Compra Online</descricao>
        <idioma>PT</idioma>
    </dados-pedido>
    <forma-pagamento>
        <bandeira>visa</bandeira>
        <produto>1</produto>
        <parcelas>1</parcelas>
    </forma-pagamento>
    <status>4</status>
    <autenticacao>
        <codigo>4</codigo>
        <mensagem>Nao autenticada</mensagem>
        <data-hora>2020-01-09T11:28:39.732-03:00</data-hora>
        <valor>315000</valor>
        <eci>4</eci>
    </autenticacao>
    <autorizacao>
        <codigo>4</codigo>
        <mensagem>Transacao autorizada</mensagem>
        <data-hora>2020-01-09T11:28:39.732-03:00</data-hora>
        <valor>315000</valor>
        <lr>00</lr>
        <arp>144716</arp>
        <nsu>549201</nsu>
        <codigo-avs-cep>C</codigo-avs-cep>
        <mensagem-avs-cep>Confere</mensagem-avs-cep>
        <codigo-avs-end>C</codigo-avs-end>
        <mensagem-avs-end>Confere</mensagem-avs-end>
    </autorizacao>
</transacao>

Aggregated functionality

Authentication and transaction with debit card

<?xml version="1.0" encoding="ISO-8859-1"?>
<requisicao-transacao id="a97ab62a-7956-41ea-b03f-c2e9f612c293" versao="1.2.1">
  <!-- ... -->
  <forma-pagamento>
    <bandeira>visa</bandeira>
    <produto>A</produto>
    <parcelas>1</parcelas>
  </forma-pagamento>
  <!-- ... -->
  <autorizar>1</autorizar>
</requisicao-transacao>

The authenticated transaction will ensure an extra security for the retailer against Chargebacks, however, according to presented on chapter “2.5 - Authentication and security level”, neither all card issuers and emitters make this kind of service available.

The debit product mandatorily requires an authenticated transaction, otherwise, the transaction won’t be authorized.

• Purpose - Make eligible the transaction for authentication.
• Rules
  • To send a flag autorizar according to the domain below, to try:
    • 0 - Only authenticate a transaction
    • 1- Submit to authorization only if the transaction be authenticated.
    • 2- Submit to authorization if the transaction be authenticated or not.
  • For debit, send the product “A” at XML.
  • The request to authorization of a transaction that has been just authenticated can be done in until 90 days after the initial date.

Allows the retailer to send a text (Soft Descriptor)

<requisicao-transacao id="a97ab62a-7956-41ea-b03f-c2e9f612c293" versao="1.2.1">
  <!-- ... -->
  <dados-pedido>
    <numero>178148599</numero>
    <valor>1000</valor>
    <moeda>986</moeda>
    <data-hora>2011-12-07T11:43:37</data-hora>
    <descricao>[origem:10.50.54.156]</descricao>
    <idioma>PT</idioma>
    <soft-descriptor>soft-descriptor</soft-descriptor>
  </dados-pedido>
  <!-- ... -->
</requisicao-transacao>

• Purpose - Allows the retailer to send a text with until 13 characters that will be printed on holder invoice, next to store identification, respecting the card issuers length:
  • Visa: 25 characters
  • Mastercard: 11 characters
• Rules
  • Maximum size: 13 characters
  • Available only for Visa and Mastercard issuers.
  • Exclusive use of Yesple characters.

Automatic Capture

<?xml version="1.0" encoding="ISO-8859-1"?>
<requisicao-transacao id="a97ab62a-7956-41ea-b03f-c2e9f612c293" versao="1.2.1">
  <!-- ... -->
  <capturar>true</capturar>
  <!-- ... -->
</requisicao-transacao>

• Purpose - The automatic capture allows a request of authorization to be captured immediately after its approval. So it’s not necessary realize a <requisicao-captura>.
• Rules
  • Just approved authorizations can be captured automatically.

Boarding fee

<?xml version="1.0" encoding="ISO-8859-1"?>
<requisicao-transacao id="a97ab62a-7956-41ea-b03f-c2e9f612c293" versao="1.2.1">
  <!-- ... -->
  <dados-pedido>
    <numero>178148599</numero>
    <valor>10000</valor>
    <moeda>986</moeda>
    <data-hora>2011-12-07T11:43:37</data-hora>
    <descricao>[origem:10.50.54.156]</descricao>
    <idioma>PT</idioma>
    <soft-descriptor>softdescriptor</soft-descriptor>
    <taxa-embarque>1000</taxa-embarque>
  </dados-pedido>
  <!-- ... -->
</requisicao-transacao>

• Purpose: the boarding fee is the informative field that defines the total amount of transaction (informed on tag data-order//value) that must be destined to payment of Infraero tax.
  • The boarding fee is not accumulated to authorization value. For example, in a airplane ticket sale of R$ 200,00 with boarding fee of R$ 25,00 you have to send the field <valor>22500</valor> and <taxa-embarque>2500</taxa-embarque>.
• Rules
  • Available just for Visa and Mastercard issuers.
  • The boarding fee is not added to authorization value, in other words, it’s just informative.

AVS (Address Verification Service)

<?xml version="1.0" encoding="ISO-8859-1"?>
<requisicao-transacao id="a97ab62a-7956-41ea-b03f-c2e9f612c293" versao="1.2.1">
  <!-- ... -->
  <dados-pedido>
    <numero>178148599</numero>
    <valor>10000</valor>
    <moeda>986</moeda>
    <data-hora>2011-12-07T11:43:37</data-hora>
    <descricao>[origem:10.50.54.156]</descricao>
    <idioma>PT</idioma>
    <soft-descriptor>softdescriptor</soft-descriptor>
    <taxa-embarque>1000</taxa-embarque>
    <avs>
  <![CDATA[
      <dados-avs>
        <endereco>Rua Teste AVS</endereco>
        <complemento>Casa</complemento>
        <numero>123</numero>
        <bairro>Vila AVS</bairro>
        <cep>12345-123</cep>
        <cpf>11111111111</cpf>
      </dados-avs>
  ]]>
    </avs>
  </dados-pedido>
  <!-- ... -->
</requisicao-transacao>

• Purpose: AVS is a service to card transaction not presencial where is realized a register validation through numeric data of address informed by holder (shipping/delivery address on invoice) at online store, with register data of emitter.
  • AVS is a service that helps to reduce risks of lack of recognition at online shopping. It’s a establishment tool to analyze your sales, before decide for transaction capture and product shipping or service.
• Rules
  • Available just for Visa, Mastercard and Amex issuers.
  • Products allowed: only credit.
  • The consult returned to AVS is separated in two itens: CEP and address.
  • Each one can have the values following:
    • C- Check;
    • N- Not check;
    • U - unavailable
    • T - Temporarily unavailable
    • X - Service doesn’t supported by this card issuer
    • E - There are some error on data sent. Check if all fields were sent.
  • The node containing the XML of AVS must be encapsulated by “CDATA” term, to avoid problems with the parter of request.
  • All fields contained AVS node must be filled.
  • When some field is not relevant, the tag must be sent with NULL or N/A.
  • It’s necessary enable the option AVS on the register. To enable an option AVS on the register or consult the participant banks please, contact Cielo E-commerce Web Support..

Capture

An authorized transaction only creates the credit for a commercial establishment in case being captured. That’s why all sales that the retailer want effective must be necessary realize the capture (or confirmation).

For sales on Credit modality, this confirmation happens in two moments:

• Immediately after the authorization (total capture);
• After the authorization (total capture or partial).

In the first case, it’s not necessary to send a request to capture, because it’s done automatically by Cielo after the authorization of transaction. For this purpose, it’s necessary configure the request of transaction defining the value “true” for a TAG , according to section “Creating a transaction”.

In the second case, it’s necessary to do a “later capture”, through the new request to Cielo Webservice to confirm the transaction and receive the sale value.

Total and Partial Capture

<?xml version="1.0" encoding="ISO-8859-1"?>
<requisicao-captura id="0374f305-0e23-4aad-82a2-055788c8cf4d" versao="1.2.1">
  <tid>10069930690360EF1001</tid>
  <dados-ec>
    <numero>1006993069</numero>
    <chave>25fbb99741c739dd84d7b06ec78c9bac718838630f30b112d033ce2e621b34f3</chave>
  </dados-ec>
  <valor>10000</valor>
  <taxa-embarque>1000</taxa-embarque>
</requisicao-captura>

• Purpose: realize total and partial capture of a transaction previously authorized.
• Rules
  • Available only to transaction on the timeout maximum of capture.
  • In case of the amount doesn’t be informed, the system will assume the capture of total value.
  • The capture value must be lower or equal to authorization value.
  • In case of failure, new capture tries can be done.
  • In case of success, the status is chaged to “6 - Captured”.
  • Transaction with boarding fees:
    • On the request capture, the boarding fee indicates the total of amount that will be captured that must be destined to this purpose.
    • It’s mandatory in case of partial capture.
    • In case of total capture, the system will consider the value of boarding fee informed to request of authorization (<requisicao-transacao>).

Return

<?xml version="1.0" encoding="ISO-8859-1"?>
<transacao xmlns="http://ecommerce.cbmp.com.br" versao="1.2.1" id="0378c8cf4d">
  <tid>10069930690360EF1001</tid>
  <pan>uv9yI5tkhX9jpuCt+dfrtoSVM4U3gIjvrcwMBfZcadE=</pan>
  <!-- ... -->
  <captura>
    <codigo>6</codigo>
    <mensagem>Transacao capturada com sucesso</mensagem>
    <data-hora>2011-12-08T14:23:08.779-02:00</data-hora>
    <valor>900</valor>
    <taxa-embarque>900</taxa-embarque>
  </captura>
</transacao>

The field of node <captura> are detailed below:

Cancellation

The cancellation is used when the retailer decides for don’t effective a purchase order, because the stock is not enough, because the customer gave up, ot any other reason. Its usage is necessary especially if the transaction has been captured, because there will be a debit on holder’s invoice if it won’t be cancelled.

Total and Partial Cancellation

<?xml version="1.0" encoding="ISO-8859-1"?>
<requisicao-cancelamento id="13368079-dedc-4cdf-9140-84473faf83d4" versao="1.2.1">
  <tid>100699306903613D1001</tid>
  <dados-ec>
    <numero>1006993069</numero>
    <chave>25fbb99741c739dd84d7b06ec78c9bac718838630f30b112d033ce2e621b34f3
</chave>
  </dados-ec>
  <valor>200</valor>
</requisicao-cancelamento>

• Purpose: Realize the cancellation of total or partial value of a transaction.
• Rules
  • The total cancellation is valid for captured transaction, and also for authorized ones, the partial is valid just to the captured ones.
  • The cancellation timeout is until 120 current days to credit modality and D+0 to debt.
  • The total cancellation, when realized with success changes the transaction status to “9-Cancelled”, while the partial doesn’t change the transaction status, keeping it as “6-Captured”.
  • In case of XML version 1.6.1 (this version is only for cancellation), the status of partial cancellation will be different: If cancellation OK, the code of status will be 9. In case of error on partial cancellation, the code of status will be 6. This rules are only for partial cancellation
  • Do not use the version 1.6.1 to send transactions. This versions is only to cancellation.
  • If the TAG <valor> doesn’t be provided, the system will assume the total cancellation.
  • Partial cancellation is available for all flags supported in e-Commerce.
  • To debit modality, doesn’t exist the possibility of effective the partial cancellation.
  • Transaction with boarding fees:
    • Captured transactions with the same authorization value (in other words, total capture), have the same treatment for total and partial cancellation, because the boarding fee value is fully cancelled.

Return

<?xml version="1.0" encoding="ISO-8859-1"?>
<transacao xmlns="http://ecommerce.cbmp.com.br" versao="1.2.1" id="2c18f00a-3ff6-4c85-8865-a4fde599b2b2">
  <tid>100699306903613E1001</tid>
  <pan>uv9yI5tkhX9jpuCt+dfrtoSVM4U3gIjvrcwMBfZcadE=</pan>
  <!-- ... -->
  <cancelamentos>
    <cancelamento>
      <codigo>9</codigo>
      <mensagem>Transacao cancelada com sucesso</mensagem>
      <data-hora>2011-12-08T16:46:35.109-02:00</data-hora>
      <valor>1000</valor>
    </cancelamento>
  </cancelamentos>
</transacao>

Testing and homologation

Endpoint

The integrating tests must be realized before the homologation starts, during the development (codification) of solution. For this purpose, you must considered an enviroment like EndPoint to Webservice: https://sandbox1-5.hdevelo.com.br/sandsky/xml

Testing data

The data gross to realize the tests on this environment will be displayed on table below:

Testing key

To make easier the development we provided two key for tests, one for each modality of integration. Based on initial configurations done on your registration, choose the correct data to realize the tests:

After conclude the development, the Homologation step will ensure that the implementation was appropriate and the customer solution is ready to interact with production environment of Cielo. It’s always happens after the development has been finished and tested. It’s composed by the next steps:

1. Conclusion of Registration: at this stage, the customer must send an email to cieloecommerce@cielo.com.br, requesting a production key. The message will contain the next information, that will complete the registration:
   • Definitive URL of website (production environment).
   • Name of responsible company by the development of integration.
   • Name and technical email (responsible developer) by integration.
   • Credential number (at Cielo) of online store.
   • Legal name and fictitious name of online store.
   • User and password to perform testing purchases.
   • URL of store logo on GIF format and size of 112X25 pixels.

In response, Cielo will return the valid key on production environment. Therefore, the store will be enable to realize tests on this environment. It starts the second step. It’s important that the tests be realized to cover the next topics:

• Webservice interact: tests with the connection that you use.
• Visual integration: round trip of Cielo flow (an alternative flow must be considered).
• Correct payment modalities: tests with possible combination of payment.
• Payment methods: testing with the possible combination of payment.

At this moment, you have to consider the environment: https://ecommerce.cielo.com.br/servicos/ecommwsec.do

Production tests have to be done with card that belongs to the store or which holder authorized its usage, once in this environment exists a financial commitment about transaction realized.

At the end, a new request must be sent to cieloecommerce@cielo.com.br, to Cielo realize the homologation, indeed. The mass of tests will be executed to approve or deny the transactions.

The result “homologated” will be sent by e-mail. If there is any point that doesn’t allow the conclusion of homologation, the information will be also sent by e-mail requesting the corrections that are necessary.

Final considerations

Reading rules to store’s card

The reading of card data on own environment is controlled by rules defined by security program imposed by card issuers.

For Visa, this program is known as AIS (Account Information Security) PCI. To more information, access: https://www.cielo.com.br > Service > Security Service > AIS - Information Security Program or contact us.

For Mastercard, the security program is SDP (Site Data Protection) PCI. For more information, access: http://www.mastercard.com/us/sdp/index.html, or contact us.

Moreover, once requests are attended, at the credential (register) on e-commerce website, must be mentioned the option for reading the card from your own store.

Digital Certificate

In some environment is necessary extract the Digital Certificate that the Cielo E-commerce application uses to be installed on TrustStore of customer, specially in Java and PHP environments.

o obtain the certificate, please, open a browser and access: http://ecommerce.cielo.com.br; click on the icon that displays the information about the certificate:

Google Chrome:

Mozilla Firefox:

Internet Explorer:

Verified Program by Visa (Visa)

International Program of Visa allows the customer authentication at the purchase moment on e-commerce environment. Visit: http://www.verifiedbyvisa.com.br/ to more information.

Secure Code Program (Mastercard)

International Program of Mastercard allows the customer authentication at the purchase moment on e-commerce environment. Visit: http://www.verifiedbyvisa.com.br/ to more information.