Integração Webservice 1.5

Para novas integrações, veja API Cielo E-commerce

O objetivo desta documentação é orientar o desenvolvedor sobre como integrar com a solução Webservice da Cielo, descrevendo as funcionalidades, os métodos a serem utilizados, listando informações a serem enviadas e recebidas, e provendo exemplos.

O mecanismo de integração com o Cielo eCommerce é simples, de modo que apenas conhecimentos intermediários em linguagem de programação para Web, requisições HTTP/HTTPS e manipulação de arquivos XML, são necessários para implantar a solução Cielo eCommerce com sucesso. É importante destacar para utilizar essa plataforma, o website deve estar em confirmidade com regras de segurança ou utilizar a certificação PCI. Para dúvidas sobre segurança web, favor encaminhar email para: Segurança Web.

Após a conclusão do credenciamento e recebimento das instruções é preciso desenvolver a integração utilizando como guia este manual. Assim que a integração estiver concluída, é necessário preencher completamente o formulário de homologação e enviá-lo para o Suporte Web do Cielo eCommerce que informará ao estabelecimento a chave de segurança.

Por fim, após o término do desenvolvimento, é preciso dar início à homologação junto à Cielo para iniciar a operação no ambiente de produção.

Suporte Cielo

Após a leitura deste manual, caso ainda persistam dúvidas (técnicas ou não), a Cielo disponibiliza o suporte técnico 24 horas por dia, 7 dias por semana em idiomas (Português e Inglês), nos seguintes contatos:

• +55 4002-9700 – Capitais e Regiões Metropolitanas
• +55 0800-570-1700 – Demais Localidades
• +55 11 2860-1348 – Internacionais
  • Opção 1 – Suporte técnico;
  • Opção 2 – Credenciamento eCommerce.
• Email: cieloeCommerce@cielo.com.br

Glossário

Para facilitar o entendimento, listamos abaixo um pequeno glossário com os principais termos relacionados ao eCommerce, ao mercado de cartões e adquirencia:

• Autenticação: processo para assegurar que o comprador é realmente aquele quem diz ser (portador legítimo), geralmente ocorre no banco emissor com uso de um token digital ou cartão com chaves de segurança.
• Autorização: processo para verificar se uma compra pode ou não ser realizada com um cartão. Nesse momento, são feitas diversas verificações com o cartão e com o portador (ex.: adimplência, bloqueios, etc.) É também neste momento que o limite do cartão é sensibilizado com o valor da transação.
• Cancelamento: processo para cancelar uma compra realizada com cartão.
• Captura: processo que confirma uma autorização que foi realizada previamente. Somente após a captura, é que o portador do cartão poderá visualizá-la em seu extrato ou fatura.
• Chave de acesso: é um código de segurança específico de cada loja, gerado pela Cielo, usada para realizar a autenticação e comunicação em todas as mensagens trocadas com a Cielo. Também conhecido como chave de produção e key data.
• Comprador: é o aquele que efetua compra na loja virtual.
• Emissor (ou banco emissor): É a instituição financeira que emite o cartão de crédito, débito ou voucher.
• Estabelecimento comercial ou EC: Entidade que responde pela loja virtual.
• Gateway de pagamentos: Empresa responsável pelo integração técnica e processamento das transações.
• Número de credenciamento: é um número identificador que o lojista recebe após seu credenciamento junto à Cielo.
• Portador: é a pessoa que tem o porte do cartão no momento da venda.
• SecureCode: programa internacional da Mastercard para possibilitar a autenticação do comprador no momento de uma compra em ambiente eCommerce.
• TID (Transaction Identifier): código composto por 20 caracteres que identificada unicamente uma transação Cielo eCommerce.
• Transação: é o pedido de compra do portador do cartão na Cielo.
• VBV (Verified by Visa): Programa internacional da Visa que possibilita a autenticação do comprador no momento de uma compra em ambiente eCommerce.

Produtos e Bandeiras suportadas

A versão atual do Webservice Cielo possui suporte às seguintes bandeiras e produtos:

Certificado Extended Validation

O que é Certificado SSL?

O Certificado SSL para servidor web oferece autenticidade e integridade dos dados de um web site, proporcionando aos clientes das lojas virtuais a garantia de que estão realmente acessando o site que desejam, e não uma um site fraudador.

Empresas especializadas são responsáveis por fazer a validação do domínio e, dependendo do tipo de certificado, também da entidade detentora do domínio.

Internet Explorer:

Firefox

Google Chrome

O que é Certificado EV SSL?

O Certificado EV foi lançado no mercado recentemente e garante um nível de segurança maior para os clientes das lojas virtuais.

Trata-se de um certificado de maior confiança e quando o https for acessado a barra de endereço ficará verde, dando mais confiabilidade aos visitantes do site.

Como instalar o Certificado Extended Validation no servidor da Loja?

Basta instalar os três arquivos a seguir na Trustedstore do servidor. A Cielo não oferece suporte para a instalação do Certificado. Caso não esteja seguro sobre como realizar a instalação do Certificado EV, então você deverá ser contatado o suporte do fornecedor do seu servidor.

• Certificado Raiz
• Certificado Intermediária 1
• Certificado Intermediária 2
• Certificado E-Commerce Cielo

Passo a Passo para a Instalação

Instalação no Servidor da Loja Virtual

O passo a passo para a instalação do Certificado EV deverá ser contatado o suporte do fornecedor do seu servidor.

Acesso do Cliente à Loja Virtual

Normalmente, o browser faz a atualização do Certificado automaticamente, caso não o faça e o cliente entre em contato deverá ser informado os seguintes passos:

1o Passo:

Salvar os arquivos abaixo em uma pasta nova, ou que relembre facilmente, pois será utilizada posteriormente:

• Certificado Raiz
• Certificado Intermediária 1
• Certificado Intermediária 2
• Certificado E-Commerce Cielo

2o Passo:

No “Internet Explorer”, clique no menu “Ferramentas” e acesse as “Opções da Internet”:

No “Firefox”, clique no menu “Abrir Menu” e acesse “Avançado” e “Opções”:

No “Chrome”, clique no “Personalizar e Controlar o Google Chrome” e acesse “Configurações” e “Mostrar configurações avançadas… “Alterar Configurações de Proxy e “Conteúdo” e Certificados:

3o Passo:

No Internet Explorer, em “Certificados”, clique em “Importar”.

No Firefox clique em “Ver Certificados”, clique em “Importar”

No Chrome clique em “Gerenciar Certificados”, clique em “Importar”

4o Passo:

No Internet Explorer e Chrome “Assistente para Importação de Certificados”, clique em “Avançar”.

No Firefox “Aba Servidores ”, clique em “Importar”

5o Passo:

No Chrome e Internet Explorer “Assistente para Importação de Certificados”, clique em “Procurar”, procure a pasta onde estão os arquivos e selecione o arquivo “ecommerce.cielo.com.br.crt, clique em “Abrir” e em seguida “Avançar”.

6o Passo:

Selecionar a opção desejada: adicionar o Certificado em uma pasta padrão ou procurar a pasta de sua escolha.

7o Passo:

Clique em “Concluir”.

8o Passo:

Clique em “Ok” para concluir a importação.

O Certificado poderá ser visualizado na aba padrão “Outras Pessoas” ou na escolhida pelo cliente.

9o Passo:

Repita o mesmo procedimento para os 3 arquivos enviados.

Dúvidas

Em caso de dúvidas em qualquer etapa ou outras informações técnicas, entre em contato com o Suporte Web do Cielo e-Commerce nos seguintes canais:

• Email: cieloeCommerce@cielo.com.br
• Capitais: 4002-9700
• Demais Cidades: 0800 570 1700

Horário de atendimento: 24h por dia, 7 dias por semana.

Visão Geral

Neste manual será apresentado uma visão geral do Cielo eCommerce e o mecanismo tecnológico no formato de integração Webservice (chamado nas versões anteriores de Buy Page Loja).

Para informações sobre a integração no formato do Checkout Cielo (chamado nas versões anteriores de Buy Page Cielo ou Solução Integrada) acesse: https://www.cielo.com.br/eCommerce.

Para todo pedido de compra, a meta é efetivá-la em uma venda. Uma venda com cartão pode ser caracterizado em uma transação autorizada e capturada.

Características da solução

A solução Webservice da plataforma Cielo eCommerce foi desenvolvida com tecnologia XML, que é padrão de mercado e independe da tecnologia utilizada por nossos clientes. Dessa forma, é possível integrar-se utilizando as mais variadas linguagens de programação, tais como: ASP, ASP. Net, Java, PHP, Ruby, Python, etc.

Entre outras características, os atributos que mais se destacam na plataforma Cielo eCommerce:

• Ausência de aplicativos proprietários: não é necessário instalar aplicativos no ambiente da loja virtual em nenhuma hipótese.
• Simplicidade: o protocolo utilizado é puramente o HTTPS, sem necessidade do uso de SOAP.
• Facilidade de credenciamento: o tratamento das credenciais do cliente (número de afiliação e chave de acesso) trafega na mensagem, em campos comuns do XML, sem necessidade de atributos especiais, como por exemplo, SOAP Header.
• Segurança: a troca de informações se dá sempre entre o Servidor da Loja e da Cielo, ou seja, sem o browser do comprador.
• Multiplataforma: a integração é realizada através de Web Service, em um único Endpoint.

Considerações sobre a integração

• Todas as requisições a Web Service da Cielo devem conter o nó de autenticação do lojista, composto pelo número de credenciamento e chave de acesso.
• O cadastro da loja deve estar ativo junto à Cielo.
• Deve-se definir um timeout adequado nas requisições HTTP à Cielo; recomendamos 30 segundos.
• O certificado Root da entidade certificadora (CA) de nosso Web Service deve estar cadastrado na Truststore a ser utilizada. Como nossa certificadora é de ampla aceitação no mercado, é provável que ela já esteja registrada na Truststore do próprio sistema operacional.
• Disponibilizamos no kit de integração o arquivo eCommerce.xsd para facilitar a validação das restrições de formato, tamanho dos campos, tipos e domínios de dados.
• Em todas as mensagens a data/hora deverá seguir o formato: aaaa-MM-ddTHH24:mm:ss. Exemplo: 2011-12-21T11:32:45.
• Os valores monetários são sempre tratados como valores inteiros, sem representação das casas decimais, sendo que os dois últimos dígitos são considerados como os centavos. Exemplo: R$ 1.286,87 é representado como 128687; R$ 1,00 é representado como 100.

Arquitetura

A integração é realizada através de serviços disponibilizados como Web Services. O modelo empregado é bastante simples: há uma única URL (endpoint) que recebe os POSTs via HTTPs e, dependendo do formato do XML enviado, uma determinada operação é realizada.

A chamada ao Web Service é resumida por:

• A mensagem em formato XML, definida de acordo com a funcionalidade.
• O destino (ambiente de teste ou de produção).
• O retorno em formato XML, que pode ser: <transacao/>, <retorno-token> ou <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>

Transação

O elemento central do Cielo eCommerce é a transação, criada a partir de uma requisição HTTP ao Webservice da Cielo. A identificação única de uma transação na Cielo é feita através do campo TID, que está presente no retorno das mensagens de autorização. Esse campo é essencial para realizar consultas, capturas e cancelamentos.

A partir da criação de uma transação, ela pode assumir os seguintes status:

As transições de status podem ser realizadas através da troca de mensagens entre a loja e a Cielo, ou de forma automática, por exemplo, quando o prazo para a captura de transação autorizada expirar.

Criando transações

Todas as transações no Cielo eCommerce iniciam-se através de um POST (HTTPS) ao Web Service da Cielo com uma mensagem XML <requisicao-transacao>, cujo conjunto de TAGS determinam as configurações de uma transação.

<?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/>
  </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>

raiz

dados-ec

dados-portador

dados-pedido

forma-pagamento

Fluxos de integração e redirecionamentos

Após a transação ter sido criada, o fluxo de navegação pode ser direcionado ao ambiente da Cielo caso o lojista solicite a autenticação na mensagem XML.

Nessa situação, o sistema do lojista deve obter o valor da TAG do XML de retorno para realizar um redirect no browser do cliente e dar continuidade ao processo. O redirecionamento deve ser realizado em modo Full Screen. Ou seja, não há mais suporte a abertura de pop up. Dessa forma, a partir da tela de checkout deve ser realizado um redirecionamento à URL retornada na criação da transação.

Após o processo de autenticação, o fluxo é devolvido ao lojista através da informação presente na TAG , enviada na primeira requisição para a Cielo.

O diagrama abaixo facilita a visualização do fluxo completo de navegação:

Por outro lado, quando não há autenticação, não existe troca de contextos ou redirects, e a integração é mais simples:

Tipos de retorno

Há três tipos de retorno que podem ser gerados na resposta do Web Service:

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

Para as operações relacionadas a uma transação (consultas, autorização, captura e cancelamento), a resposta, em caso de sucesso, é sempre um XML do tipo <transacao>. No caso de uma requisição exclusiva para criação de token, a resposta esperada é <retorno-token>.

O exemplo ao lado ilustra a forma mais reduzida de uma mensagem de retorno tipo <transacao>. Basicamente, ela é composta pelos dados do pedido e dados da configuração da transação.

<?xml version="1.0" encoding="ISO-8859-1"?>
<transacao versao="1.3.0" 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>
    </autorizacao>
</transacao>

As informações mais importantes são:

• TID: é o elo entre o pedido de compra da loja virtual e a transação na Cielo.
• URL de autenticação: aponta à página que dá início à autenticação (quando solicitada).
• Status: é a informação base para a loja controlar a transação.

A tabela abaixo detalha as TAGS do XML básico de retorno, identificado pelo nó raiz <transação>:

Por fim, há outro tipo de retorno que é empregado toda vez que uma requisição não pode ser executada, seja porque era inválida ou por ter ocorrido falha no seu processamento. Nesse cenário o nó raiz do XML de resposta é do tipo <erro>.

<?xml version="1.0" encoding="ISO-8859-1"?>
<erro xmlns="http://ecommerce.cbmp.com.br">
  <codigo>001</codigo>
  <mensagem><![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>

Quando a transação é inválida, podemos classificar os erros em dois tipos:

• Erros sintáticos: ocorrem quando a mensagem XML não respeita as regras definidas no arquivo eCommerce.xsd. Por exemplo, uma letra em um campo numérico, ou a ausência de um valor obrigatório;
• Erros semânticos: ocorrem quando uma requisição solicita uma operação não suportada para determinada transação. Por exemplo, tentar capturar uma transação não autorizada, ou ainda, cancelar uma transação já cancelada.

Autenticação e nível de segurança

Dependendo da bandeira escolhida, as transações na plataforma Cielo eCommerce podem ser configuradas para serem autenticadas no banco emissor do cartão (portador), a fim de garantir o nível maior de segurança ao lojista. A autenticação não é feita automaticamente entre sistemas, deste modo é necessário que o comprador interaja no processo, conforme será visto a seguir.

Ela acontece sempre no site do banco (Internet Banking), utilizando mecanismos e tecnologias independentes da Cielo. Dessa forma, é possível que o banco utilize token eletrônico e senha, enquanto outro utilize os cartões de senhas ou CPF para autenticar uma transação.

Conforme mostrado anteriormente, a mecânica do redirecionamento é obtida através da tag <url-autenticacao> que é retornada pela Cielo no XML no momento da solicitação de autorização ao Web Service.

A autenticação é obrigatória para transações de débito e opcional para o crédito. Atualmente somente Visa e MasterCard suportam essa funcionalidade e consequentemente, somente essas duas bandeiras possuem o produto débito.

Quando há autenticação, o fluxo de execução da autorização acaba sendo feito em duas etapas, conforme mostrado no diagrama abaixo:

1. fecharPedido() – acontece quando o portador do cartão finaliza o pedido e dá início ao pagamento da compra
2. criarTransacao(autenticada) – o sistema do lojista envia uma requisição XML <requisicao-transacao> solicitando uma transação autenticada, ou seja, a TAG será 0, 1 ou 2. Em seguida, a Cielo informará no XML de retorno o campo com o endereço que o portador deverá ser redirecionado.
3. acessar(url-atenticacao) – o browser do portador é redirecionado ao ambiente da Cielo. Assim que a página da Cielo é acessada, automaticamente ela já é direcionada para o banco emissor (3.1). Esse redirect é tão rápido que é praticamente imperceptível.
4. autenticar(token, cpf) – o portador estará no ambiente do banco e utilizará algum mecanismo provido pelo próprio emissor para realizar a autenticação da transação (geralmente token, cartão de bingo, cpf, assinatura eletrônica, etc).
5. resultadoAutenticacao() – o banco emissor redireciona o fluxo para a Cielo com o resultado da autenticação. A partir daí, o fluxo volta ao normal, conforme disposto no item “2.3 Arquitetura de integração”. 1.processar() – o sistema da Cielo processa o retorno da autenticação e submete á autorização e, opcionalmente, à captura automática. 2. enviarRedirect(url-retorno) – o sistema da Cielo envia um redirect ao browser do cliente para o endereço especificado na URL de retorno, fornecida na primeira requisição (<requisicao-transacao>)
   1. acessar(url-retorno) – o browser do portador acessar a URL no ambiente da loja, onde recomendamos que exista uma requisição de consulta via TID ao Web Service da Cielo.

Observações

• Somente o primeiro redirecionamento (1.2: enviarRedirect()) é de responsabilidade da loja virtual.
• O comprador é redirecionado ao site do Banco Emissor somente se a autenticação estiver disponível. Caso contrário, a transação prosseguirá à autorização automaticamente (exceto se foi apenas solicitada autenticação).

Os pré-requisitos para que uma transação seja autenticada estão relacionados abaixo:

• Banco e Bandeira devem ser participantes do programa de autenticação;
• O BIN do cartão deve ser participante do programa de autenticação;
• A configuração da // deve ser 0, 1 ou 2.

Observando o diagrama da seção Transação, é possível observar que todas as transações passarão pelo status “Autenticada” ou “Não autenticada”. Por consequência, todas receberão o nó <autenticacao> no XML de resposta ao lojista. Abaixo, o XML com o nó de autenticação:

<?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>10069930690864281001</tid>
    <pan>uv9yI5tkhX9jpuCt+dfrtoSVM4U3gIjvrcwMBfZcadE=</pan>
    <dados-pedido>
        <numero>1739114311</numero>
        <valor>1000</valor>
        <moeda>986</moeda>
        <data-hora>2013-02-18T15:06:27.523-03:00</data-hora>
        <descricao>[origem:172.16.34.66]</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>6</status>
    <autenticacao>
        <codigo>6</codigo>
        <mensagem>Transacao sem autenticacao</mensagem>
        <data-hora>2013-02-18T15:06:28.013-03:00</data-hora>
        <valor>1000</valor>
        <eci>7</eci>
    </autenticacao>
    <autorizacao>
        <codigo>6</codigo>
        <mensagem>Transação autorizada</mensagem>
        <data-hora>2013-02-18T15:06:28.807-03:00</data-hora>
        <valor>1000</valor>
        <lr>00</lr>
        <arp>123456</arp>
        <nsu>549928</nsu>
    </autorizacao>
    <captura>
        <codigo>6</codigo>
        <mensagem>Transacao capturada com sucesso</mensagem>
        <data-hora>2013-02-18T15:08:23.031-03:00</data-hora>
        <valor>1000</valor>
    </captura>
</transacao>

Os campos apenas do nó <autenticacao> estão listados na tabela abaixo:

O campo ECI (Eletronic Commerce Indicator) representa o quão segura é uma transação. Esse valor deve ser levado em consideração pelo lojista para decidir sobre a captura da transação.

A transação autenticada passa por uma validação do emissor e da bandeira, em momento de autorização, podendo refletir na alteração do ECI (Eletronic Commerce Indicator), que é utilizado para determinar quem será o responsável em caso de chargeback nas modalidades fraude.

Catálogo de códigos de resposta

Códigos de Autorização LR

A seguir estão os códigos de resposta que respondem por 99% dos retornos gerados no processo de autorização. Os demais códigos existentes não estão listados pois ocorrem raramente ou em casos específicos. Para estes casos deve-se assumir que eles não são passíveis de retentativa.

Caso tenha uma quantidade elevada de códigos de retorno que não está listado abaixo, entre em contato com o Suporte Web Cielo eCommerce.

Códigos de Erros

Os erros que podem ser apresentados na mensagem XML, através da TAG <erro>, estão dispostos a seguir:

Tabela de erros de integração

Status das transações

ECI

Operações e configurações

Criação da Transação de Autorização

A requisição de autorização é a principal operação do Cielo eCommerce, pois é através dela que uma venda pode ser concretizada e finalizar o processo de venda. A autorização possui uma série de configurações que podem ser customizadas, além de funcionalidades que agregam valor ao lojista e seus consumidores.

Autorização Direta

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

A autorização direta caracteriza-se por ser uma transação onde não há a autenticação do portador, seja por opção (e risco) do lojista, seja porque a bandeira ou emissor não tem suporte. A autorização direta pode ser feita de duas formas: tradicional (com os dados do cartão) ou através de um token.

Tradicional

• Objetivo - Submeter uma transação direta com o uso de um cartão de crédito.
• Regras
  • O cadastro da loja virtual deve estar habilitado para envio dos dados do cartão.
  • Enviar a TAG <autorizar> com o valor “3”.
  • Somente válido para Crédito.
  • O lojista deve estar atento às regras para envio do cartão.
  • Na autorização direta, o nível de segurança da transação (ECI) é definido como:
    • “7” para Visa, Diners, Discover, Elo e JCB.
    • “0” para Mastercard, Aura e Hipercard.

Autorização Recorrente

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

A autorização recorrente pode ser feita de duas formas: através do envio de um token previamente cadastrado, ou através de um cartão. A transação recorrente é praticamente igual à transação tradicional, as mudanças consistem nas regras que o emissor e a bandeira utilizam para autorizar ou negar uma transação. Outra diferença está relacionada ao Renova Fácil.

Autorização recorrente com Cartão

• Objetivo - Submeter uma transação recorrente com o uso de um cartão de crédito.
• Regras
  • Enviar a TAG <autorizar> com o valor “4”.
  • Somente válido para crédito à vista.

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>

Essa funcionalidade facilita a identificação de um cartão que tenha sido substituído por outro no banco emissor. Dessa forma, quando uma transação recorrente é submetida ao Web Service e a Cielo identifica que o cartão utilizado está desatualizado, o sistema terá o seguinte comportamento:

1. Caso a transação recorrente tenha sido enviada através de um cartão, sua autorização será negada e serão retornados os dados do novo cartão, conforme o diagrama abaixo:

Autorização de uma transação previamente gerada

<?xml version="1.0" encoding="ISO-8859-1"?>
<requisicao-autorizacao-tid id="a387cb68-b33a-4113-b7c4-9b7dfde871ec" versao="1.3.0">
    <tid>100699306908642E1001</tid>
    <dados-ec>
        <numero>1006993069</numero>
        <chave>25fbb99741c739dd84d7b06ec78c9bac718838630f30b112d033ce2e621b34f3</chave>
    </dados-ec>
</requisicao-autorizacao-tid>

Para os estabelecimentos utilizando o processo de autenticação, é possível solicitar a autorização das transações que pararam após a execução deste processo. A mensagem para performar tal operação é a “requisicao-autorizacao-tid” como descrita abaixo:

Transação com 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>

• Objetivo - Solicitar a criação de um token associada a um cartão de crédito, para viabilizar o envio de transações sem o cartão.
• Regras
  • O Token é único para um determinado [Cartão + Estabelecimento Comercial]. Dessa forma, um cartão pode estar “tokenizado” em mais de uma loja e em cada uma possuirá códigos diferentes.
  • Caso seja enviada mais de uma solicitação com os mesmos dados, o token retornado será sempre o mesmo.
  • A criação do token é independente do resultado da autorização (aprovada/negada).

Retorno

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

O retorno será do tipo quando a solicitação tenha sido concluída com sucesso, ou em caso de fracasso.

Autorização Direta 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>

• Objetico - Submeter uma transação direta (sem autenticação) com o uso de um token previamente cadastrado
• Regras
  • Enviar a TAG <autorizar> com o valor “3”.
  • O token deve estar desbloqueado.
  • Válido somente para crédito.

Autorização recorrente com 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>

• Objetivo - Submeter uma transação recorrente com o uso de um token previamente cadastrado.
• Regras
  • Enviar a TAG <autorizar> com o valor “4”.
  • O token deve estar desbloqueado.
  • Somente válido para crédito à vista.

Renova Fácil com 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>

Essa funcionalidade facilita a identificação de um cartão que tenha sido substituído por outro no banco emissor. Dessa forma, quando uma transação recorrente é submetida ao Web Service e a Cielo identifica que o cartão utilizado está desatualizado, o sistema terá o seguinte comportamento:

1. Caso a transação recorrente tenha sido enviada através de um token, sua autorização será negada e será retornado um novo token para ser utilizado, conforme o diagrama abaixo:

Geração de 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>

• Objetivo - Além da mensagem específica para criação de um token, descrita em Transação com Token, é possível aproveitar uma requisição de autorização para solicitar a geração do token, acrescentando a informação <gerar-token> no nó de requisição de transação.
• Regras
  • Caso um cartão seja submetido mais de uma vez pelo mesmo lojista, o Token gerado será sempre o mesmo.

Funcionalidades Agregadas

Autenticação e Transações com Cartões de Débito

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

A autenticação da transação garantirá uma segurança extra ao lojista contra Chargebacks, porém, conforme apresentando no capítulo “2.5 – Autenticação e nível de segurança”, nem todas as bandeiras e emissores disponibilizam esse tipo de serviço.

O produto débito obrigatoriamente exige uma transação autenticada, caso contrário, a transação não é autorizada.

• Objetivo - Tornar elegível uma transação para autenticação.
• Regras
  • Enviar a flag de acordo com o domínio abaixo, para tentar:
    • 0 – Somente autenticar a transação.
    • 1 – Submeter à autorização somente se a transação for autenticada.
    • 2 – Submeter à autorização se a transação for autenticada ou não.
  • Para débito, enviar o produto “A” no XML.
  • A solicitação da autorização de uma transação que foi somente autenticada pode ser feita em até 90 dias após a data inicial.

Permite que o lojista envie um texto (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>

• Objetivo - Permite que o lojista envie um texto de até 13 caracteres que será impresso na fatura do portador, ao lado da identificação da loja, respeitando o comprimento das bandeiras:
  • Visa: 25 caracteres
  • Mastercard: 22 caracteres
• Regras
  • Tamanho máximo: 13 caracteres.
  • Disponível apenas para as bandeiras Visa e MasterCard.
  • Uso exclusivo de caracteres simples.

Captura Automática

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

• Objetivo - A captura automática permite que uma requisição de autorização seja capturada imediatamente após sua aprovação. Dessa forma, não é preciso realizar uma <requisicao-captura>.
• Regras
  • Somente autorizações aprovadas serão capturadas automaticamente.

Taxa de embarque

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

• Objetivo A taxa de embarque é um campo informativo que define o montante do total da transação (informado na tag dados-pedido//valor) que deve ser destinado ao pagamento da taxa à Infraero.
  • O valor da taxa de embarque não é acumulado ao valor da autorização. Por exemplo, em uma venda de passagem aérea de R$ 200,00 com taxa de embarque de R$ 25,00 deve-se enviar o campo <valor>22500</valor> e <taxa-embarque>2500</taxa-embarque>.
• Regras
  • Disponível apenas para as bandeiras Visa e Mastercard.
  • O valor da taxa de embarque não é somado ao valor da autorização, ou seja, é apenas informativo.

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>
        <dados-avs>11111111111</dados-avs>
      </dados-avs>
  ]]>
    </avs>
  </dados-pedido>
  <!-- ... -->
</requisicao-transacao>

• Objetivo - O AVS é um serviço para transações de cartão não presente onde é realizada uma validação cadastral através do batimento dos dados numéricos do endereço informado pelo portador (endereço de entrega da fatura) na loja virtual, com os dados cadastrais do emissor.
  • O AVS é um serviço que auxilia na redução do risco de não reconhecimento de compras online. É uma ferramenta que o estabelecimento utilizará para a análise de suas vendas, antes de decidir pela captura da transação e a entrega do produto ou serviço.
• Regras
  • Disponível apenas para as bandeiras Visa, Mastercard e AmEx.
  • Produtos permitidos: somente crédito.
  • O retorno da consulta ao AVS é separado em dois itens: CEP e endereço.
  • Cada um deles pode ter os seguintes valores:
    • C – Confere;
    • N – Não confere;
    • I – Indisponível;
    • T – Temporariamente indisponível;
    • X – Serviço não suportado para esta Bandeira.
    • E - Dados enviados incorretos. Verificar se todos os campos foram enviados
  • O nó contendo o XML do AVS deve estar encapsulado pelo termo “CDATA”, para evitar problemas com o parser da requisição.
  • É necessário que todos os campos contidos no nó AVS sejam preenchidos.
  • Quando o campo não for aplicável (exemplo: complemento), a tag deve ser enviada preenchia com NULL ou N/A
  • Necessário habilitar a opção do AVS no cadastro. Para habilitar a opção AVS no cadastro ou consultar os bancos participantes, entre em contato com o Suporte Web Cielo eCommerce.

Consulta

A operação de consulta é essencial na integração, pois ela que garantirá a situação atual de uma transação. Ela deve ser executada ao término do processo de autorização, no momento em que a Loja Virtual recebe o fluxo de execução na URL informada na primeira requisição (através da TAG ). O E-commerce pode levar até 25 segundos para processar completamente uma transação.

Consulta por TID

• Objetivo - Realizar a consulta de uma transação através do TID informado.
• Regras
  • Somente transações dos últimos 365 dias estão disponíveis.
  • Não há mudança de status da transação.

Requisição

<?xml version="1.0" encoding="ISO-8859-1"?>
<requisicao-consulta id="6fcf758e-bc60-4d6a-acf4-496593a40441" versao="1.2.1">
  <tid>100699306903609A1001</tid>
  <dados-ec>
    <numero>1006993069</numero>
    <chave>25fbb99741c739dd84d7b06ec78c9bac718838630f30b112d033ce2e621b34f3
    </chave>
  </dados-ec>
</requisicao-consulta>

Consulta por Número do Pedido

• Objetivo - Realizar a consulta de uma transação através do número do pedido, fornecido pela loja no momento da requisição de transação.
• Regras:
  • Somente transações dos últimos 365 dias estão disponíveis.
  • Caso seja encontrada mais de uma transação para o mesmo número do pedido, a Cielo enviará a transação mais recente.
  • Não há mudança de status da transação.

Requisição

<?xml version="1.0" encoding="UTF-8"?>
<requisicao-consulta-chsec id="a51489b1-93d5-437f-bb4f-5b932fade248" versao="1.2.1">
  <numero-pedido>1663784368</numero-pedido>
  <dados-ec>
    <numero>1006993069</numero>
    <chave>25fbb99741c739dd84d7b06ec78c9bac718838630f30b112d033ce2e621b34f3
    </chave>
  </dados-ec>
</requisicao-consulta-chsec>

Captura

Uma transação autorizada somente gera o crédito para o estabelecimento comercial caso ela seja capturada. Por isso, toda venda que o lojista queira efetivar será preciso realizar a captura (ou confirmação) da transação.

Para vendas na modalidade de Crédito, essa confirmação pode ocorrer em dois momentos:

• Imediatamente após a autorização (captura total);
• Posterior à autorização (captura total ou parcial).

No primeiro caso, não é necessário enviar uma requisição de captura, pois ela é feita automaticamente pela Cielo após a autorização da transação. Para tanto, é preciso configurar a requisição de transação definindo-se o valor “true” para a TAG <capturar>, conforme visto na seção “Criando uma transação”.

Já no segundo caso, é preciso fazer uma “captura posterior”, através de uma nova requisição ao Webservice da Cielo para confirmar a transação e receber o valor da venda.

Captura Total e Parcial

<?xml version="1.0" encoding="ISO-8859-1"?>
<requisicao-captura id="adbc9961-8a39-452b-b7fd-15b44b464a97" versao="1.3.0">
    <tid>10069930690864281001</tid>
    <dados-ec>
        <numero>1006993069</numero>
        <chave>25fbb99741c739dd84d7b06ec78c9bac718838630f30b112d033ce2e621b34f3</chave>
    </dados-ec>
    <valor>1000</valor>
    <taxa-embarque>0</taxa-embarque>
</requisicao-captura>

• Objetivo - Realizar a captura total e parcial de uma transação previamente autorizada.
• Regras
  • Disponível somente para transações dentro do prazo máximo de captura.
  • Caso o valor não seja informado, o sistema assumirá a captura do valor total.
  • O valor da captura deve ser menor ou igual ao valor da autorização.
  • Em caso de falha, novas tentativas de captura poderão ser feitas.
  • Em caso de sucesso, o status é alterado para “6 – Capturada”.
  • Transações com Taxa de embarque:
    • Na requisição de captura, o valor da taxa de embarque indica o montante do total que será capturado que deve ser destinado a esse fim.
    • Obrigatório caso seja captura parcial.
    • Caso a captura seja total, o sistema irá considerar o valor da taxa de embarque informado no requisição de autorização (<requisicao-transacao>).

Retorno

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

Os campos do nó estão detalhados a seguir:

Cancelamento

O cancelamento é utilizado quando o lojista decide não efetivar um pedido de compra, seja por insuficiência de estoque, por desistência da compra pelo consumidor, ou qualquer outro motivo. Seu uso faz-se necessário principalmente se a transação estiver capturada, pois haverá débito na fatura do portador, caso ela não seja cancelada.

Cancelamento Total e Parcial

<?xml version="1.0" encoding="ISO-8859-1"?>
<requisicao-cancelamento id="39d36eb6-5ae9-4308-89a1-455d299460c0" versao="1.3.0">
    <tid>100699306908642E1001</tid>
    <dados-ec>
        <numero>1006993069</numero>
        <chave>25fbb99741c739dd84d7b06ec78c9bac718838630f30b112d033ce2e621b34f3</chave>
    </dados-ec>
    <valor>0</valor>
</requisicao-cancelamento>

• Objetivo - Realizar o cancelamento do valor total ou parcial de uma transação.
• Regras
  • O cancelamento total é válido tanto para transações capturadas, como autorizadas; o parcial é válido apenas para as capturadas.
  • O prazo de cancelamento é de até 300 dias para a modalidade crédito e D+0 para débito.
  • O cancelamento total, quando realizado com sucesso, altera o status da transação para “9 – Cancelada”, enquanto que o parcial não altera o status da transação, mantendo-a como “6 – Capturada”.
  • Em caso de cancelamento na versão 1.6.1 (esta versão é exclusiva para cancelamento), o status de cancelamento parcial será diferente, ou seja: se cancelado com sucesso, retorna status 9; caso ocorra um erro no cancelamento parcial, o código de status será 6. Estas regras aplicam-se apenas para o cancelamento parcial.
  • Caso a TAG <valor> não seja fornecida, o sistema assumirá um cancelamento total.
  • O cancelamento parcial está disponível para todas as bandeiras suportadas no e-Commerce.
  • Para a modalidade débito, não existe a possibilidade de efetuar cancelamento parcial.
  • Transações com Taxa de embarque:
    • Transações capturadas com o mesmo valor da autorização (ou seja, captura total) possuem o mesmo tratamento para cancelamentos parciais e totais, pois o valor da taxa de embarque é cancelado integralmente.

Retorno

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

Processamento em lote

O Processamento em Lote permite que sejam transmitidas em uma única chamada um conjunto com várias transações, essas transações serão processadas e disponibilizadas através de um arquivo de retorno no formato XML.

O que é o Processamento em Lote

O Processamento em Lote é baseado em um arquivo XML, o qual deve conter uma lista com as transações que compõem o lote, estas transações não devem exigir autenticação, pois será executada diretamente pela Cielo, após a geração do arquivo pelo Estabelecimento Comercial, deve ser enviado para Cielo utilizando o protocolo HTTPS.

Após o recebimento do arquivo, é feita uma pré-validação pela Cielo e o mesmo entra em uma fila para processamento, sendo que este processo é agendado para ser executado de hora em hora.

No momento da pré-validação arquivo poderá ser rejeitado, caso seja enviado em branco ou com formatação inválida.

Integração

Regras

Processamento em Lote deverá seguir as seguintes regras:

1 - O XML para processamento em lote está definido através do “ecm-lote.xsd” que possui dependência com o ecommerce.xsd. 2 - O arquivo deverá respeitar o limite de 20MB (aprox.: 27.000 transações). 3 - O processamento em lote suporta os mesmos tipos de operações do transacional online. Veja a tabela em anexo.

Os dados do Estabelecimento Comercial serão informados uma única vez dentro do lote, ou seja, o pacote de transações pertence exclusivamente ao Estabelecimento informado no arquivo. O lote a ser gerado deverá conter uma ou mais transações do mesmo tipo de operação, caso mais de um tipo seja enviado no lote, o arquivo será rejeitado.

4 - A nomenclatura do arquivo deverá respeitar a regra abaixo e conter a seguinte estrutura e tamanhos de campo:

Exemplo: ECOMM_1006993069_02_20121002_0000000086.xml

• a) Prefixo – obrigatoriamente deve iniciar com “ECOMM”;
• b) N.o Afiliação EC – número de afiliação do Estabelecimento Comercial, com a Cielo, deverá conter dez dígitos;
• c) Tipo de operação – deverá conter dois dígitos e para o código do tipo de operação vide tabela acima;
• d) Data de geração do arquivo – data em que o arquivo foi gerado, deve ser no formato yyyymmdd;
• e) Numero do lote – número do lote deverá ser sequencial e conter dez dígitos preenchidos com zeros à esquerda;
• f) Extensão do arquivo – deve ser XML obrigatoriamente.

Mensagens

Mensagem de Upload de Arquivo

<?xml version="1.0" encoding="UTF-8"?>
<retorno-upload-lote xmlns="http://ecommerce.cbmp.com.br ">
    <data-envio>2012-10-08T09:38:04.284-03:00</data-envio>
    <data-retorno>2012-10-09T09:38:04.284-03:00</data-retorno>
    <mensagem>Seu lote está válido para processamento. Favor aguardar o determinado para retorno.</mensagem>
</retorno-upload-lote>

Após a geração do arquivo, o Estabelecimento Comercial deverá efetuar o seu upload através do protocolo HTTPS, utilizando o método POST, na seguinte URL http://ecommerce.cbmp.com.br/lote/ecommwsecLoteUpload.do.

Após o envio, o Estabelecimento Comercial receberá o seguinte XML de retorno:

Mensagem de Solicitação de Download de Retorno

<?xml version="1.0" encoding="UTF-8"?>
<requisicao-download-retorno-lote versao="Versao da msg" id=“session id”>
   <dados-ec>
   <numero>1006993069 </numero>
   <chave>25fbb997438630f30b112d033ce2e621b34f3</chave>
   </dados-ec>
   <numero-lote>0000000086</numero-lote>
</requisicao-download-retorno-lote>

O Estabelecimento Comercial poderá solicitar o download do arquivo de retorno, após doze horas no mínimo, montando a seguinte mensagem:

A tabela abaixo detalha as TAGS do XML que podem ser enviadas na mensagem para definir as configurações da transação para o Processamento em Lote:

Ao receber esta mensagem, a plataforma Cielo eCommerce verificará se o lote está processado e o se o arquivo está gerado no outbox, com as validações positivas, o arquivo de retorno é devolvido para o Estabelecimento Comercial, caso contrário, será retornado um XML cuja mensagem informa em qual etapa o processo está pendente.

Caso o arquivo tenha sido gerado, porem não está no outbox, pode ter ocorrido limpeza do storage, neste caso, automaticamente, ocorre um evento que solicita a segunda via do arquivo. O Estabelecimento Comercial será informado através de uma mensagem XML retorno, que uma nova requisição deverá ser feita mais tarde, para que um novo arquivo seja gerado.

Anexo

Tipos de operações do transacional online

Códigos de resposta

Os erros que podem ser apresentados na mensagem XML, através da TAG , estão dispostos a seguir:

Arquivo ECM-LOTE.XSD

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns="http://ecommerce.cbmp.com.br"
    targetNamespace="http://ecommerce.cbmp.com.br"
    elementFormDefault="qualified">

    <xsd:include schemaLocation="ecm-ec.xsd"></xsd:include>


    <xsd:simpleType name="numeroLoteType">
        <xsd:restriction base="xsd:int">
            <xsd:minExclusive value="0"></xsd:minExclusive>

            <xsd:maxInclusive value="999999999"></xsd:maxInclusive>
        </xsd:restriction>
    </xsd:simpleType>



    <xsd:element name="requisicao-lote" type="RequisicaoLote"></xsd:element>

    <xsd:element name="retorno-lote" type="RetornoLote"></xsd:element>

    <xsd:complexType name="RequisicaoLote">
        <xsd:sequence>
            <xsd:element name="dados-ec" type="DadosEc"
                maxOccurs="1" minOccurs="1">
            </xsd:element>
            <xsd:element name="numero-lote" type="numeroLoteType"
                maxOccurs="1" minOccurs="1">
            </xsd:element>            
            <xsd:element name="tipo-operacao" minOccurs="1" maxOccurs="1">
                <xsd:annotation>
                    <xsd:documentation>
                        2: Autorização 3:Cancelamento 4:Captura 5:Tokenização 6:Consulta 7:ConsultaChSec 8:AutorizacaoTid
                    </xsd:documentation>
                </xsd:annotation>
                <xsd:simpleType>
                    <xsd:restriction base="xsd:string">
                        <xsd:pattern value="(2|3|4|5|6|7|8)"></xsd:pattern>                        
                    </xsd:restriction>
                </xsd:simpleType>
            </xsd:element>
            <xsd:element name="lista-requisicoes"
                type="ListaRequisicoesLote" maxOccurs="unbounded"
                minOccurs="1">
            </xsd:element>

        </xsd:sequence>
    </xsd:complexType>

    <xsd:complexType name="RetornoLote">
        <xsd:sequence>
            <xsd:element name="dados-ec" type="DadosEc"></xsd:element>
            <xsd:element name="numero-lote" type="numeroLoteType"></xsd:element>
            <xsd:element name="lista" type="ListaRetornoLote"></xsd:element>
        </xsd:sequence>
    </xsd:complexType>
    
    <xsd:complexType name="ListaRequisicoesLote">
        <xsd:sequence>
            <xsd:element name="requisicao-transacao"
                type="RequisicaoNovaTransacao" maxOccurs="unbounded"
                minOccurs="0">
            </xsd:element>
            <xsd:element name="requisicao-token" type="RequisicaoToken"
                maxOccurs="unbounded" minOccurs="0">
            </xsd:element>
            <xsd:element name="requisicao-consulta"
                type="RequisicaoConsulta" maxOccurs="unbounded" minOccurs="0">
            </xsd:element>
            <xsd:element name="requisicao-cancelamento"
                type="RequisicaoCancelamento" maxOccurs="unbounded"
                minOccurs="0">
            </xsd:element>
            <xsd:element name="requisicao-captura"
                type="RequisicaoCaptura" maxOccurs="unbounded" minOccurs="0">
            </xsd:element>

            <xsd:element name="requisicao-consulta-chsec"
                type="RequisicaoConsultaChSec" maxOccurs="unbounded"
                minOccurs="0">
            </xsd:element>
            <xsd:element name="requisicao-autorizacao-tid"
                type="RequisicaoAutorizacaoTid" maxOccurs="unbounded" minOccurs="0">
            </xsd:element>
        </xsd:sequence>
    </xsd:complexType>

    <xsd:complexType name="ListaRetornoLote">
        <xsd:sequence>
            <xsd:element name="transacao" type="Retorno" maxOccurs="unbounded" minOccurs="0"></xsd:element>
            <xsd:element name="retorno-token" type="RetornoToken" maxOccurs="unbounded" minOccurs="0"></xsd:element>
            <xsd:element name="erro" type="RequisicaoErro" maxOccurs="unbounded" minOccurs="0"></xsd:element>
        </xsd:sequence>
    </xsd:complexType>

    <xsd:complexType name="RequisicaoDownloadRetornoLote">
        <xsd:complexContent>
            <xsd:extension base="Mensagem">
                <xsd:sequence>
                    <xsd:element name="dados-ec" type="DadosEc" maxOccurs="1" minOccurs="1"></xsd:element>
                    <xsd:element name="numero-lote" type="numeroLoteType" maxOccurs="1" minOccurs="1"></xsd:element>
                </xsd:sequence>
            </xsd:extension>
        </xsd:complexContent>
    </xsd:complexType>

    <xsd:complexType name="RetornoDownloadLote">
        <xsd:sequence>
            <xsd:element name="erro" type="RequisicaoErro" maxOccurs="1"
                minOccurs="0">
            </xsd:element>
            <xsd:element name="arquivo" type="xsd:string" maxOccurs="1"
                minOccurs="0">
            </xsd:element>
            <xsd:element name="mensagem" type="xsd:string" maxOccurs="1" minOccurs="0"></xsd:element>
        </xsd:sequence>
    </xsd:complexType>

    <xsd:element name="requisicao-download-retorno-lote"
        type="RequisicaoDownloadRetornoLote">
    </xsd:element>

    <xsd:element name="retorno-download-lote"
        type="RetornoDownloadLote">
    </xsd:element>
    
    <xsd:complexType name="RetornoUploadLote">
        <xsd:sequence>
            <xsd:element name="data-envio" type="xsd:dateTime" maxOccurs="1" minOccurs="1"></xsd:element>
            <xsd:element name="data-retorno" type="xsd:dateTime" maxOccurs="1" minOccurs="1"></xsd:element>            
            <xsd:element name="mensagem" type="xsd:string" maxOccurs="1" minOccurs="1"></xsd:element>            
        </xsd:sequence>
    </xsd:complexType>

    <xsd:element name="retorno-upload-lote" type="RetornoUploadLote"></xsd:element>
</xsd:schema>

Testes e Homologação

Endpoint

Os testes de integração deverão ser realizados antes do início da homologação, durante o desenvolvimento (codificação) da solução. Para isso, deve-se considerar o seguinte ambiente como EndPoint do Webservice: https://qaseCommerce.cielo.com.br/servicos/ecommwsec.do

Dados para testes

A massa de dados para realizar os testes neste ambiente está disposta na tabela abaixo:

Chave de testes

Para facilitar o desenvolvimento disponibilizamos duas chaves para testes, uma para cada modalidade de integração. Com base nas configurações iniciais feitas durante o seu credenciamento, escolha os dados corretos para realizar os testes:

Após a conclusão do desenvolvimento, a etapa de Homologação garantirá que a implementação foi adequada e a solução do Cliente está apta para interagir no ambiente produtivo da Cielo. Ela sempre acontece depois que o desenvolvimento foi finalizado e testado. É composta pelas seguintes etapas:

1. Finalização do Cadastro: nesta etapa o Cliente deve enviar um email para cieloeCommerce@cielo.com.br, solicitando a Chave de Produção. A mensagem deve conter as seguintes informações, que irão completar o cadastro:
   • URL Definitiva do site (ambiente de produção).
   • Nome da empresa responsável pelo desenvolvimento da integração.
   • Nome e e-mail do técnico (desenvolvedor) responsável pela integração.
   • Número de credenciamento (junto à Cielo) da loja virtual.
   • Razão social e nome fantasia da loja virtual.
   • Um usuário e senha na loja virtual para efetuar compras de testes.
   • URL do logotipo da loja no formato GIF e tamanho de 112X25 pixels.

Em resposta, a Cielo retornará uma chave válida no ambiente de produção. Logo, a loja está habilitada a realizar seus testes nesse ambiente. Inicia-se a segunda etapa. É importante que testes sejam realizados para cobrir os seguintes tópicos:

• Interação com o Webservice: testes com a conexão utilizada.
• Integração visual: a ida e a volta do fluxo a Cielo (fluxos alternativos devem ser
• considerados).
• Aplicação correta da marca da bandeira.
• Modalidades de pagamento: testes com as combinações possíveis de pagamento.

Neste momento, deve-se considerar o ambiente: https://ecommerce.cielo.com.br/servicos/ecommwsec.do

Os testes em produção devem ser feitos com cartões de propriedade da Loja ou cujo portador tenha autorizado seu uso, uma vez que neste ambiente existe compromisso financeiro sobre as transações realizadas.

Ao término, uma nova solicitação deve ser enviada para cieloeCommerce@cielo.com.br, para que a Cielo realize a homologação de fato. Um conjunto de testes será executado aprovar e negar transações. O resultado “HOMOLOGADO” é enviado por e-mail. Caso haja algum ponto que não permite a conclusão da homologação, a informação será igualmente enviada por email solicitando as correções necessárias.

Considerações Finais

Regras para leitura do cartão na loja

A leitura dos dados do cartão no ambiente próprio é controlada por regras definidas pelo programa de segurança imposto pelas bandeiras de cartões.

Para a Visa, esse programa é o conhecido como AIS (Account Information Security) PCI. Para maiores informações acesse: https://www.cielo.com.br > Serviços > Serviços de Segurança > AIS – Programa de Segurança da Informação , ou entre em contato conosco.

Para a Mastercard o programa de segurança é o SDP (Site Data Protection) PCI. Para maiores informações acesse: http://www.mastercard.com/us/sdp/index.html, ou entre em contato conosco.

Ademais, atendidos os requisitos, no momento do credenciamento eCommerce deve ser mencionada a escolha por leitura do cartão na própria loja.

Certificado digital

Em alguns ambientes é preciso extrair o Certificado Digital que a aplicação do Cielo eCommerce utiliza para ser instalado na Trustedstore do cliente, especialmente em ambientes Java e PHP.

Para obter o certificado, abra um browser e acesse http://ecommerce.cielo.com.br e clique no ícone que exibe as informações sobre o certificado:

Google Chrome:

Mozilla Firefox:

Internet Explorer:

Programa Verified by Visa (Visa)

Programa internacional da Visa para possibilitar a autenticação do comprador no momento de uma compra em ambiente eCommerce. Visite http://www.verifiedbyvisa.com.br/ para maiores informações.

Programa Secure Code (Mastercard)

Programa internacional da Mastercard para possibilitar a autenticação do comprador no momento de uma compra em ambiente eCommerce. Visite http://www.mastercard.com/securecode para maiores informações.