Guia de Implementacao - CIELO Ecommerce

Guia de Implementação CIELO Ecommerce

Versão 3.0

2010 CIELO Ecommerce Página 1 de 21

Comércio Eletrônico

Locaweb

Autores:

Equipe Comércio Eletrônico Guia de Implementação

CIELO Ecommerce ________ __ Versão 3.0

http://www.locaweb.com.br [email protected] Atendimento: http://atendimento.locaweb.com.br/

http://atendimento.locaweb.com.br/


Versão 3.0


Sumário

1. Informações..................................................................................................................... 3

2. Fluxo básico com autorização e captura automáticas.................................................... 4

3. Registro da transação..................................................................................................... 5

3.1. Retorno XML do Registro da transação..................................................................... 6

4. Autorização direta da transação...................................................................................... 8

4.1. Retorno XML da Autorização Direta da transação..................................................... 9

5. Autorização da transação................................................................................................ 11

5.1. Retorno XML da Autorização da transação............................................................... 11

6. Consulta da transação.................................................................................................... 13

6.1. Retorno XML da Consulta da transação.................................................................... 13

7. Captura da transação...................................................................................................... 16

7.1. Retorno XML da Captura da transação...................................................................... 16

8. Cancelamento da transação........................................................................................... 18

8.1. Retorno XML do Cancelamento da transação........................................................... 18

9. Dados de teste................................................................................................................ 20

10. Possíveis status de transação....................................................................................... 20

11. Níveis de segurança da transação................................................................................ 20

12. Possíveis retornos de erro............................................................................................ 21


Versão 3.0


1. Informações

O ambiente CIELO Ecommerce deve ser configurado inicialmente no nosso servidor de Comércio Eletrônico da Locaweb. Para configurá-lo, acesse o painel de controle do Gateway de Pagamentos (entre em http://painel.locaweb.com.br > Serviços Contratados > Gateway de Pagamentos > Acessar Painel do Gateway de Pagamentos). A solução CIELO Ecommerce funciona de forma síncrona, ou seja, na mesma conexão HTTP em que são postados os dados da transação é também retornado um arquivo XML com o resultado do processo. Para todas as operações, os dados da transação para o componente da Locaweb ( https://comercio.locaweb.com.br/comercio.comp) deverão ser enviados via POST. Uma transação pode ser processada de duas formas:

Com os dados do cartão sendo capturados em uma página da Cielo; Com os dados do cartão sendo capturados na página da loja e sendo postados ao sistema da

Cielo. Para uso do fluxo com os dados do cartão sendo capturados no site da loja, o estabelecimento deve atender a um conjunto de regras definidas pelo programa de segurança da bandeira do cartão de crédito. Para Visa, esse programa é o AIS (Account Information Security) da Visa. Para mais informações

acesse http://www.cielo.com.br “Serviços > Serviços de Segurança > AIS – Programa de Segurança da Informação” ou entre em contato com a CIELO através de seus canais de atendimento. 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 com a CIELO através de seus canais de atendimento. Os canais de atendimento da CIELO são:

4002-9700 (opção 1/2) (Capitais e regiões metropolitanas) 0800-570-1700 (opção 1/2) (Demais localidades) [email protected]

http://painel.locaweb.com.br/

https://comercio.locaweb.com.br/comercio.comp

http://www.cielo.com.br/

http://www.mastercard.com/us/sdp/index.html

mailto:[email protected]


Versão 3.0


2 . Fluxo básico com autorização e captura automáticas

O diagrama abaixo mostra a sequência de um fluxo básico com autorização e captura automáticas, com os dados do cartão sendo informados em uma página da Cielo .


Versão 3.0


3. Registro da transação

Os parâmetros que deverão ser passados via POST são:

Parâmetro Formato Tamanho Obrigatório Descrição

identificacao AlfaNum - S

Código de serviço do Gateway de Pagamentos junto à Locaweb (disponível em seu Painel de Controle da Locaweb – http://painel.locaweb.com.br/)

modulo AlfaNum - S Nome do módulo de pagamento utilizado. Utilizar: CIELO

operacao AlfaNum - S Define a ação que será executada. Utilizar: Registro

ambiente AlfaNum - S Define o ambiente a ser usado. Utilizar: TESTE ou PRODUCAO

bin_cartao Num 6 N Seis primeiros números do cartão.

idioma AlfaNum 2 N Idioma do pedido. Utilizar: PT (português), EN (inglês) ou ES (espanhol)

valor Num 12 S Valor total da transação sem pontuação – os últimos dois dígitos representam sempre os centavos. Utilizar: 100 para R$ 1,00

pedido AlfaNum 20 S Número do pedido para controle interno da sua loja.

descricao AlfaNum 1024 N Breve descrição do pedido.

bandeira AlfaNum - S Bandeira: visa ou mastercard (em minúsculo)

forma_pagamento Num 1 S Forma de pagamento. Utilizar: 1 (Crédito à Vista), 2 (Parcelado loja), 3 (Parcelado administradora), A (Débito)

parcelas Num 3 S Número de parcelas. Para transação à vista ou débito utilizar: 1

autorizar Num 1 S

Indicador de autorização automática. Utilizar: 0 (não autorizar), 1 (autorizar somente se autenticada), 2 (autorizar autenticada e não-autenticada), 3 (autorizar sem passar por autenticação – válido somente para crédito)

capturar AlfaNum - S Captura automática da transação caso seja autorizada. Utilizar: true ou false

campo_livre AlfaNum 128 N Campo livre.

Exemplo do registro da transação:

- ASP: registra_transacao.asp - PHP: registra_transacao.php


Versão 3.0


3.1. Retorno XML do Registro da transação

Após a postagem dos dados para registro da transação, será retornado um XML com o resultado do processo. Os seguintes parâmetros são retornados no XML:

Parâmetro Formato Tamanho Descrição

tid AlfaNum 40 Código de identificação da transação.

status Num 2 Status da transação. Ver item 10. Possíveis status de transação.

url-autenticacao AlfaNum 256 URL de redirecionamento a Cielo para processamento da transação.

Dados do Pedido (dados-pedido)

numero Num 20 Número do pedido para controle interno da loja.

valor Num 12 Valor total da transação.

moeda Num 3 Código numérico da moeda.

data-hora AlfaNum 19 Data e hora do pedido.

descricao AlfaNum 1024 Breve descrição do pedido.

idioma AlfaNum 2 Idioma do pedido.

Forma de Pagamento (forma-pagamento)

bandeira AlfaNum - Bandeira.

produto Num 1 Forma de pagamento.

parcelas Num 3 Número de parcelas.

Exemplo do XML retornado: <?xml version="1.0" encoding="iso-8859-1"?>

<transacao versao="1.0.0" id="1" xmlns="http://ecommerce.cbmp.com.br">

<tid>10017348980401201001</tid>

<dados-pedido>

<numero>1</numero>

<valor>100</valor>

<moeda>986</moeda>

<data-hora>2010-04-27T17:49:50.120-03:00</data-hora>

<descricao>Pedido de teste</descricao>

<idioma>PT</idioma>

</dados-pedido>

<forma-pagamento>

<bandeira>visa</bandeira>

<produto>1</produto>

<parcelas>1</parcelas>

</forma-pagamento>

<status>1</status>

<url-

autenticacao>https://qasecommerce.cielo.com.br/web/index.cbmp?id=d75b93d1edbc1a84fcf71

6ba727c4c5c</url-autenticacao>

</transacao>


Versão 3.0


Caso ocorra algum erro no processo, serão retornados os parâmetros:


codigo Num - Código do erro. Ver item 12. Possíveis retornos de erro.

mensagem AlfaNum - Descrição do erro.

Exemplo do XML retornado: <?xml version="1.0" encoding="ISO-8859-1"?>

<erro>

<codigo>999</codigo>

<mensagem>Valor nao deve conter ponto nem virgula. Formato 1000 para R$

10,00</mensagem>

</erro>

IMPORTANTE:

Nessa etapa a transação será SOMENTE registrada, mas é necessário que a loja faça o redirecionamento do comprador para a URL retornada no parâmetro url-autenticacao para que seja de

fato processada. Essa URL será de uma página da CIELO onde o comprador informará dos dados do seu cartão. Após o processamento da transação pelo comprador, ocorrerá o redirecionamento do mesmo da página da CIELO para a URL de retorno da loja. Essa URL de retorno é cadastrada em sua configuração CIELO Ecommerce no seu Painel de Gateway de Pagamentos da Locaweb (conforme explicado no item 1. Informações, deste guia de implementação).

No retorno da página da CIELO para a URL de retorno da sua loja, por questões de segurança, não será postado nenhum dado referente à transação. Dessa forma, é necessário que sua loja guarde o tid da transação, que foi recebido no XML de retorno no registro da transação, para efetuar a consulta

da transação para obter os dados da mesma. Como sugestão de implementação de como armanezar essa informação do tid, você pode usar

variáveis de sessão ou cookies. Os detalhes de como fazer a consulta da transação são explicados no item 6. Consulta da transação

deste guia de implementação.


Versão 3.0


4. Autorização direta da transação

A Autorização Direta da transação é uma operação em que os dados do cartão serão obtidos em uma interface do lojista para posterior postagem a CIELO. Neste modelo, não será exibida uma tela da CIELO durante o processo de compra. A utilização dessa operação SOMENTE será possível caso o seu relacionamento junto a CIELO permita esse tipo de transação. Mais informações entre em contato com seu representante comercial CIELO. Os parâmetros que deverão ser passados via POST são:





operacao AlfaNum - S Define a ação que será executada. Utilizar: Autorizacao-Direta

ambiente AlfaNum - S Define o tipo de ambiente. Utilizar: TESTE ou PRODUCAO

nome_portador_cartao AlfaNum 50 S Nome impresso no cartão.

numero_cartao Num 16 S Número do cartão.

validade_cartao Num 6 S Validade do cartão. Formato: AAAAMM

indicador_cartao Num 1 S

Indicador do código de segurança do cartão. Utilizar: 0 (não informado), 1 (informado), 2 (ilegível) e 9 (inexistente). Para Mastercard, deve ser sempre 1.

codigo_seguranca_cartao Num 3 N Código de segurança do cartão. Obrigatório se indicador do cartão for 1.

idioma AlfaNum 2 N Idioma do pedido. Utilizar: PT (português), EN (inglês) ou ES (espanhol)

valor Num 12 S Valor total da transação. Utilizar: 100 para R$ 1,00

pedido AlfaNum 20 S Número do pedido para controle interno da loja.

descricao AlfaNum 1024 N Breve descrição do pedido.

bandeira AlfaNum - S Bandeira: visa ou mastercard (em minúsculo)

forma_pagamento Num 1 S Forma de pagamento. Utilizar: 1 (Crédito à Vista), 2 (Parcelado loja), 3 (Parcelado administradora), A (Débito)

parcelas Num 3 S Número de parcelas. Para transação à vista ou débito utilizar: 1

capturar AlfaNum - S Captura automática da transação caso seja autorizada. Utilizar: true ou false



Versão 3.0


Exemplo do autorização direta da transação:

- ASP: autorizacao_direta_transacao.asp - PHP: autorizacao_direta_transacao.php 4.1. Retorno XML da Autorização Direta da transação

Após a postagem dos dados para autorização direta da transação, será retornado um XML com o resultado do processo. Os seguintes parâmetros são retornados no XML:



pan AlfaNum 40 Hash do número do cartão do portador.














Autenticação (autenticacao)

codigo Num 2 Código do processamento.

mensagem AlfaNum 100 Detalhe do processamento.

data-hora AlfaNum 19 Data hora do processamento.

valor Num 12 Valor do processamento sem pontuação.

eci Num 2 Nível de segurança da transação. Ver item 11. Níveis de segurança da transação.

Autorização (autorizacao)






Versão 3.0


lr Num 2 Retorno da autorização.

arp AlfaNum 6 Código da autorização caso a transação tenha sido autorizada com sucesso.



<tid>10017348980401251001</tid>

<pan>34353531383730303030303030313833</pan>

<dados-pedido>

<numero>5</numero>

<valor>100</valor>

<moeda>986</moeda>



<idioma>PT</idioma>

</dados-pedido>

<forma-pagamento>




</forma-pagamento>

<status>9</status>

<autenticacao>

<codigo>9</codigo>

<mensagem>Transacao sem autenticacao</mensagem>


<valor>100</valor>

<eci>7</eci>

</autenticacao>

<autorizacao>

<codigo>9</codigo>

<mensagem>Transação autorizada</mensagem>


<valor>100</valor>

<lr>00</lr>

<arp>183501</arp>

</autorizacao>

<url-

autenticacao>https://qasecommerce.cielo.com.br/web/index.cbmp?id=339986bdf7f744911638a

302b4fc4854</url-autenticacao>

</transacao>

Caso ocorra algum erro no processo serão retornados os parâmetros:





<erro>



10,00</mensagem>

</erro>


Versão 3.0


5. Autorização da transação

A Autorização da transação é uma operação que poderá ser feita inúmeras vezes. Este processo retornará todos os dados referentes à transação autorizada. Os parâmetros que deverão ser passados via POST são:





operacao AlfaNum - S Define a ação que será executada. Utilizar: Autorizacao


tid AlfaNum 40 S Código de identificação da transação.

Exemplo da autorização da transação:

- ASP: autorizacao_transacao.asp - PHP: autorizacao_transacao.php 5.1. Retorno XML da Autorização da transação

Após a postagem dos dados para autorização da transação será retornado um XML com o resultado do processo. Os seguintes parâmetros são retornados no XML:
















Versão 3.0













<tid>10017348980401251001</tid>

<pan>34353531383730303030303030313833</pan>

<dados-pedido>

<numero>5</numero>

<valor>100</valor>

<moeda>986</moeda>



<idioma>PT</idioma>

</dados-pedido>

<forma-pagamento>




</forma-pagamento>

<status>9</status>

<autorizacao>

<codigo>9</codigo>



<valor>100</valor>

<lr>00</lr>

<arp>183501</arp>

</autorizacao>

<url-



</transacao>






<erro>



10,00</mensagem>

</erro>


Versão 3.0


6. Consulta da transação

A Consulta é uma operação que poderá ser feita inúmeras vezes. Este processo retornará todos os dados referentes à transação consultada. Os parâmetros que deverão ser passados via POST são:





operacao AlfaNum - S Define a ação que será executada. Utilizar: Consulta



Exemplo da consulta da transação:

- ASP: consulta_transacao.asp - PHP: consulta_transacao.php 6.1. Retorno XML da Consulta da transação

Após a postagem dos dados para consulta da transação será retornado um XML com o resultado do processo. Os seguintes parâmetros são retornados no XML:
















Versão 3.0




Autenticação (autenticacao)





eci Num 2 Nível de segurança da transação. Ver item 11. Níveis de segurança da transação.








Captura (captura)





Cancelamento (cancelamento)







<tid>10017348980401251001</tid>

<pan>34353531383730303030303030313833</pan>

<dados-pedido>

<numero>5</numero>

<valor>100</valor>

<moeda>986</moeda>



<idioma>PT</idioma>

</dados-pedido>

<forma-pagamento>





Versão 3.0


</forma-pagamento>

<status>9</status>

<autenticacao>

<codigo>9</codigo>

<mensagem>Transacao sem autenticacao</mensagem>


<valor>100</valor>

<eci>7</eci>

</autenticacao>

<autorizacao>

<codigo>9</codigo>



<valor>100</valor>

<lr>00</lr>

<arp>183501</arp>

</autorizacao>

<captura>

<codigo>9</codigo>

<mensagem>Transacao capturada com sucesso</mensagem>


<valor>100</valor>

</captura>

<cancelamento>

<codigo>9</codigo>

<mensagem>Transacao cancelada com sucesso</mensagem>


<valor>100</valor>

</cancelamento>

<url-



</transacao>






<erro>



10,00</mensagem>

</erro>


Versão 3.0


7. Captura da transação

A Captura é uma operação necessária SOMENTE quando na transação o parâmetro “capturar” foi enviado com o valor “false” e tenha sido aprovada. Este procedimento libera a Visanet de emitir a cobrança para o emissor do cartão. A captura deve ser feita em até 5 dias (corridos) após a transação. Caso isso não ocorra, a transação será cancelada automaticamente pela operadora. Após a postagem dos dados para captura da transação será retornado um XML com o resultado do processo. Os parâmetros que deverão ser passados via POST são:





operacao AlfaNum - S Define a ação que será executada. Utilizar: Captura



valor Num 12 N Valor da transação que será capturado. Utilizar: 100 para R$ 1,00


Exemplo da captura da transação:

- ASP: captura_transacao.asp - PHP: captura_transacao.php 7.1. Retorno XML da Captura da transação

Após a postagem dos dados para captura da transação será retornado um XML com o resultado do processo. Os seguintes parâmetros são retornados no XML:












Versão 3.0








Captura (captura)







<tid>10017348980401251001</tid>

<pan>34353531383730303030303030313833</pan>

<dados-pedido>

<numero>5</numero>

<valor>100</valor>

<moeda>986</moeda>



<idioma>PT</idioma>

</dados-pedido>

<forma-pagamento>




</forma-pagamento>

<status>9</status>

<captura>

<codigo>9</codigo>

<mensagem>Transacao capturada com sucesso</mensagem>


<valor>100</valor>

</captura>

<url-



</transacao>






<erro>



10,00</mensagem>

</erro>


Versão 3.0


8. Cancelamento da transação

O Cancelamento é uma ação opcional para as transações aprovadas. Este procedimento notifica a Visanet para não emitir a cobrança ao emissor do cartão. O cancelamento deve ser feito em até 24 horas após a transação, passado esse prazo somente poderá ser feito junto à operadora. Após a postagem dos dados para cancelamento da transação, será retornado um XML com o resultado do processo. Os parâmetros que deverão ser passados via POST são:





operacao AlfaNum - S Define a ação que será executada. Utilizar: Cancelamento



Exemplo do cancelamento da transação:

- ASP: cancelamento_transacao.asp - PHP: cancelamento_transacao.php 8.1. Retorno XML do Cancelamento da transação

Após a postagem dos dados para cancelamento da transação, será retornado um XML com o resultado do processo. Os seguintes parâmetros são retornados no XML:














Versão 3.0






Cancelamento (cancelamento)







<tid>10017348980401251001</tid>

<pan>34353531383730303030303030313833</pan>

<dados-pedido>

<numero>5</numero>

<valor>100</valor>

<moeda>986</moeda>



<idioma>PT</idioma>

</dados-pedido>

<forma-pagamento>




</forma-pagamento>

<status>9</status>

<cancelamento>

<codigo>9</codigo>

<mensagem>Transacao cancelada com sucesso</mensagem>


<valor>100</valor>

</cancelamento>

<url-



</transacao>






<erro>



10,00</mensagem>

</erro>


Versão 3.0


9. Dados de teste

Para realizar seus testes, utilize os dados abaixo no ambiente de testes (estes dados funcionarão apenas neste ambiente): Dados para configuração de teste em seu Painel de Controle do Comércio Eletrônico:

Afiliação: 1001734898 Chave: e84827130b9837473681c2787007da5914d6359947015a5cdb2b8843db0fa832 Afiliação para autorização direta: 1006993069

Chave para autorização direta: 25fbb99741c739dd84d7b06ec78c9bac718838630f30b112d033ce2e621b34f3

Dados de cartão de teste:

Cartão com autenticação: 4012 0010 3714 1112 (visa) Cartão sem autenticação: 4551 8700 0000 0183 (visa), 5453 0100 0006 6167 (mastercard)

Data de validade: qualquer combinação posterior a data atual Código de segurança: qualquer combinação de 3 dígitos Valor do pedido: para simular transação autorizada, use qualquer valor em que os dois últimos

dígitos sejam zeros. Do contrário, toda autorização será negada.

IMPORTANTE: Para simular uma transação autorizada, é necessário que no valor da transação os

dois últimos dígitos seja 0. Do contrário, toda autorização será negada. 10. Possíveis status de transação

Código Erro

0 Criada

1 Em andamento

2 Autenticada

3 Não autenticada

4 Autorizada ou pendente de captura

5 Não autorizada

6 Capturada

8 Não capturada

9 Cancelada

10 Em autenticação

11. Níveis de segurança da transação

Resultado da autenticação Visa Mastercard

Portador autenticado com sucesso 5 2

Portador não realizou autenticação, pois o Emissor não forneceu mecanismos de autenticação

6 1

Portador não se autenticou com sucesso ou a loja optou por autorizar sem passar pela autenticação

7 0


Versão 3.0


12. Possíveis retornos de erro

Código Erro Descrição

001 Mensagem inválida A mensagem XML está fora do formato especificado pelo arquivo ecommerce.xsd

002 Credenciais inválidas Impossibilidade de autenticar uma requisição da loja virtual.

003 Transação inexistente Não existe transação para o identificador informado

010 Inconsistência no envio do cartão A transação, com ou sem cartão, está divergente com a permissão do envio dessa informação

011 Modalidade não habilitada A transação está configurada com uma modalidade de pagamento não habilitada para a loja

012 Número de parcelas inválido O número de parcelas solicitado ultrapassa o máximo permitido

020 Status não permite autorização Não é permitido realizar autorização para o status da transação

021 Prazo de autorização vencido Não é permitido realizar autorização, pois o prazo está vencido

022 EC não autorizado EC não possui permissão para realizar a autorização

030 Transação não autorizada para captura

A captura não pode ser realizada, pois a transação não está autorizada

031 Prazo de captura vencido A captura não pode ser realizada, pois o prazo para captura está vencido

032 Valor de captura inválido O valor solicitado para captura não é válido

033 Falha ao capturar Não foi possível realizar a captura

040 Prazo de cancelamento vencido O cancelamento não pode ser realizado, pois o prazo está vencido

041 Status não permite cancelamento O atual status da transação não permite cancelamento

042 Falha ao cancelar Não foi possível realizar o cancelamento

099 Erro inesperado Falha no sistema

Documents

Guia de Implementacao - CIELO Ecommerce