manual do desenvolvedor 1.5.8.1

e-commerce Manual do desenvolvedor Verso 1.5.9

207

e-commerce

Manual do Desenvolvedor

1


1 2 3 4 5 6 7 8 9

Qual o objetivo? .................................................................................................................. 3 Quais so os conhecimentos necessrios?............................................................................ 3 O que preciso para realizar vendas atravs da Cielo? ......................................................... 3 Termos utilizados no manual ................................................................................................. 3 Como funciona a venda ......................................................................................................... 4 Caractersticas da soluo ..................................................................................................... 5 Arquitetura de integrao ....................................................................................................... 6 Loja de exemplo .................................................................................................................... 7 Integrao da loja virtual ........................................................................................................ 7 9.1 Versionamento e Compatibilidade................................................................................... 8 9.2 Regras e procedimentos de integrao ........................................................................... 8 9.3 Tipos de retorno ............................................................................................................. 9 9.4 A venda e a transao .................................................................................................. 12 9.5 Nvel de segurana da transao .................................................................................. 12 9.6 Requisio Cielo ........................................................................................................ 13 9.7 Criao ......................................................................................................................... 14 9.8 Autenticao................................................................................................................. 16 9.9 Autorizao .................................................................................................................. 16 9.10 Captura ........................................................................................................................ 18 9.11 Cancelamento .............................................................................................................. 19 9.12 Consulta via TID ........................................................................................................... 20 9.13 Autorizao Direta ........................................................................................................ 21 10 Catlogo de Erros ................................................................................................................ 25 11 Redirecionamento Cielo .................................................................................................... 27 12 Dados para teste ................................................................................................................. 27 13 Ambientes ........................................................................................................................... 27 14 Homologao ...................................................................................................................... 28 15 Suporte e-commerce Cielo (atendimento bilingue, 24 x 7).................................................... 29 16 Regras para leitura do carto na prpria loja ........................................................................ 29 17 Apndice ............................................................................................................................. 30

2


1

Qual o objetivo?

Guiar o desenvolvedor da loja virtual na integrao com a soluo de comrcio eletrnico da Cielo, de modo a disponibilizar ao lojista a possibilidade de venda com os cartes de crdito e de dbito. 2 Quais so os conhecimentos necessrios?

Conhecimentos mnimos sobre o uso de requisies HTTP e tratamento de XML. 3 O que preciso para realizar vendas atravs da Cielo? Ser uma loja afiliada. Veja como em http://www.cielo.com.br > Afiliao > Afiliao ecommerce Integrar a loja virtual com nossa soluo de comrcio eletrnico Homologar essa integrao

4

Termos utilizados no manual Autenticao Processo para assegurar que o comprador realmente aquele quem diz ser (portador legtimo) Autorizao Processo para verificar se uma compra pode ou no ser realizada num carto. Verifica-se limite, se o carto est ativo, se o portador est adimplente, etc. Cancelamento Processo para cancelar uma compra no carto. Captura Processo para confirmar uma autorizao. aps ela que o portador recebe um dbito na fatura de seu carto.

3


Chave de acesso Chave de autenticao da loja usada na chamada aos Web Services da Cielo. Comprador aquele que efetua compra na loja virtual. Emissor Ou banco emissor. a entidade que emite o carto. Estabelecimento comercial ou EC Entidade que responde pela loja virtual Nmero de afiliao um identificador que o lojista recebe aps ter-se afiliado a Cielo. Portador o mesmo que comprador. aquele que tem o porte de um carto. TID Identificador nico da transao Transao o pedido de compra do portador na Cielo.

5

Como funciona a venda

O comprador, aps ter preenchido o seu carrinho de compras: Opta pelo pagamento com Carto de Crdito Escolhe a modalidade (Dbito ou Crdito) Define o nmero de parcelas (se crdito) Informa os dados do carto (nmero, data de validade e cdigo de segurana) A partir da inicia-se o processo de autenticao. O comprador redirecionado ao banco emissor. Aps autenticar-se, ele retorna ao ambiente da Cielo e ento a transao finalizada com a autorizao. Posteriormente, o fluxo retorna loja virtual que apresenta o fechamento do pedido de acordo com o resultado da etapa anterior.

4


Esse fluxo pode variar de acordo com: Local do fornecimento dos dados do carto: pode ser na prpria loja ou na Cielo (recomendado). Veja Regras para leitura do carto na prpria loja. A existncia de autenticao no banco emissor. Quando inexistente, a transao prossegue direto autorizao A configurao da transao: a autorizao logo aps a autenticao facultativa.

6

Caractersticas da soluo Ausncia de aplicativos proprietrios: no necessrio instalar aplicativos no ambiente da loja virtual Flexibilidade no armazenamento das credenciais (nmero de afiliao e chave de acesso) da loja Segurana na transferncia de informaes: elas so sempre transferidas diretamente do servidor da loja para o servidor da Cielo, ou seja, sem o browser do comprador. Multiplataforma: a integrao realizada via Web Services

5


7

Arquitetura de integrao

A integrao realizada atravs de servios disponibilizados como Web Services. O modelo empregado simples: para cada servio, um tipo de mensagem e um destino (endpoint) em comum. Veja:public Transacao criarTransacao(Pedido pedido) throws FalhaComunicaoException { Mensagem mensagem = new MensagemNovaTransacao (loja, pedido); Requisicao requisicao = new Requisicao(mensagem); return requisicao.enviarPara(destino); } public Transacao capturar(Transacao transacao, long valor) throws FalhaComunicaoException { Mensagem mensagem = new MensagemCaptura(loja, transacao, valor); Requisicao requisicao = new Requisicao(mensagem); return requisicao.enviarPara(destino); }

As funcionalidades so orientadas por transao. E destinam-se a controlar o seu ciclo de vida atravs da Criao Autenticao Autorizao Captura ou confirmao (valor total ou parcial) Cancelamento Consulta A combinao dessas funcionalidades d vida a uma transao. A meta a captura, a venda realizada. Da concepo at esse objetivo h transies de status:

6


A transio de status que promove Autenticada possui caractersticas distintas dos outros. Ela no executada por um servio de fato, pois envolve interao do comprador. Em outras palavras, ela no baseada no modelo requisio-resposta. Na autenticao ocorrem mudanas de fluxos (telas) que no esto mais restritas apenas loja virtual: h interao com o banco emissor e a Cielo.

8

Loja de exemplo

Nela possvel verificar o comportamento de todas as funcionalidades. Instale-a conforme o Guia da Loja Exemplo ou acesse http://200.183.118.76:8080/lojaexemplo.

9

Integrao da loja virtual

A integrao apresentada conforme o ciclo almejado de uma transao, isto , desde sua criao at a captura. Mas antes disso so apresentados alguns conceitos e regras. imperativo que o lojista j tenha resposta para as seguintes perguntas: Que tipo de autorizao automtica ser empregado? So 4 tipos disponveis: o Somente autenticar a transao o Enviar para autorizao somente transao autenticada o Enviar para autorizao transao autenticada e no-autenticada (sujeita ainda s regras de autorizao automtica) o Autorizar Direto Ser utilizada captura automtica? Os dados do carto sero lidos no prprio ambiente ou na Cielo? Que tipo de parcelamento ser utilizado: parcelado loja ou parcelado administradora? As respostas a esses questionamentos sero utilizadas nos prximos passos.

7


9.1

Versionamento e Compatibilidade

Atualmente h trs verses de mensagens suportadas. A mais recente (e recomendada para uso), a 1.1.1, detalhada nesse manual. de grande valia que, o lojista numa nova integrao ou manuteno evolutiva, atualize para a verso mais recente e dessa forma usufruir das novas funcionalidades. As principais mudanas que sero apresentadas, desde a verso anterior do manual (1.5.6): Suporte as bandeiras Diners e Discover Possibilidade de solicitar uma autorizao direta em apenas um nico passo Possibilidade de consultar transao via nmero do pedido Retorno do nmero de sequncia da autorizao (NSU)NOVO

Os detalhes dessas alteraes esto identificados com a marca

.

Foi mantida total compatibilidade com as verses anterioriores: 1.0.0 e 1.1.0. Obviamente, o lojista optando por essas verses, no ter acesso s novas funcionalidades. 9.2 Regras e procedimentos de integrao Toda e qualquer requisio obrigatoriamente deve conter o nmero de afiliao e chave de acesso O cadastro da loja deve estar ativo junto Cielo O ambiente a ser utilizado para o desenvolvimento da integrao o de Teste, inclusive com o nmero de afiliao e chave de acesso empregado na loja exemplo (veja o tpico Ambientes). Para homologao da soluo junto Cielo deve ser usado o ambiente de produo. Maiores informaes em Homologao. Deve ser definido um timeout adequado nas requisies HTTP O certificado Root da entidade certificadora de nosso site deve estar cadastrado na Trust Store a ser utilizada. Como nossa certificadora de ampla aceitao no mercado muitssimo provvel que ela j esteja registrada na Trust Store do prprio sistema operacional. Caso necessrio consulte o apndice Como saber qual o certificado a Cielo utiliza As restries de formato, tamanho, tipo e domnio esto compiladas no arquivo ecommerce.xsd. De todo modo, em cada etapa tambm exibida uma tabela com essas informaes O uso de frame no recomendado. Porm, caso seja a escolha, o tamanho mnimo deve ser de 430x570 pixels

8


9.3

Tipos de retorno

De forma resumida, uma requisio pode ser executada com sucesso ou com erro. Dessa forma, h apenas dois tipos de retorno possveis ou dois tipos de mensagens XML: A primeira mensagem uma representao do status da transao. Basicamente composta por dados do pedido e dados de configurao da transao. As informaes mais importantes so: O TID A URL de autenticao e O status 10069930690004381001 633834383369859337 100 986 2009-07-17T14:38:56 visa 1 1 https://ecommerce.cbmp.com.br/web/index.cbmp?id=c7cf30ab476c96d778 0

O TID o elo de ligao entre o pedido de compra da loja e a transao na Cielo. A URL aponta pgina que d incio a autenticao. O status a informao base para a loja controlar a transao. Seus possveis valores so:Status Nome 0 1 2 3 4 5 6 8 9 10 Criada Em andamento Autenticada No autenticada Autorizada ou pendente de captura No autorizada Capturada No capturada Cancelada Em Autenticao

9


Abaixo todos os dados que compem ou podem compor um retorno, mas antes disso algumas consideraes gerais: AN ou alfanumrico: campo que aceita caracteres e nmeros N: campo que aceita apenas nmeros R: campo requerido ou mandatrio O: campo opcional C: campo requerido de acordo com uma condio Root: n-raiz da mensagem XML Formato para data-hora: sempre que referenciado, o formato adotado aaaa-mmddTHH24:mm:ss. Exemplos: 2009-09-21T11:32:45, 2009-12-31T23:50:00 Formato para valor monetrio: sempre um valor inteiro, sendo que os dois ltimos dgitos so considerados como os centavos. Exemplo 1.286,87 representado como 128687; 1,00 representado como 100.

10


Agora sim a mensagem de retorno:

Root Campo tid dados-pedido forma-pagamento status autenticacao autenticacao.codigo autenticacao.mensagem autenticacao.data-hora autenticacao.valor autenticacao.eci autorizacao autorizacao.codigo autorizacao.mensagem autorizacao.data-hora autorizacao.valor autorizacao.lr autorizacao.arp autorizacao.nsu captura captura.codigo captura.mensagem captura.data-hora captura.valor cancelamento cancelamento.codigo cancelamento.mensagem cancelamento.data-hora cancelamento.valor pan url-autenticacaoNOVO

Formato Tamanho AN Descrio

1..40 Identificador.

Idntico ao n enviado pela loja na criao da transao. Idntico ao n enviado pela loja na criao da transao. N N AN AN N N N AN AN N N AN AN N AN AN N N AN AN N AN AN 1..2 Status. 1..2 Cdigo do processamento. 1..100 Detalhe do processamento. Data hora do processamento. Valor do processamento sem pontuao. Os 1..12 dois ltimos dgitos so os centavos. 2 Nvel de segurana. 1..2 Cdigo do processamento. 1..100 Detalhe do processamento. 19 Data hora do processamento Valor do processamento sem pontuao. Os 1..12 dois ltimos dgitos so os centavos. Retorno da autorizao. Quando negada, o 2 motivo da negao. Cdigo da autorizao caso a transao 6 tenha sido autorizada com sucesso. 6 Nmero de sequncia da autorizao. N com dados da captura caso tenha passado por essa etapa. 1..2 Cdigo do processamento. 1..100 Detalhe do processamento. Data hora do processamento. Valor do processamento sem pontuao. Os 1..12 dois ltimos dgitos so os centavos. 1..2 Cdigo do processamento. 1..100 Detalhe do processamento. Data hora do processamento. Valor do processamento sem pontuao. Os 1..12 dois ltimos dgitos so os centavos. 1..40 Hash do nmero do carto do portador. 1..256 URL de redirecionamento Cielo. 19 19 19 N com dados da autenticao caso tenha passado por essa etapa.

N com dados da autorizao caso tenha passado por essa etapa.

N com dados do cancelamento caso tenha passado por essa etapa.

O outro tipo de retorno empregado quando uma requisio no pde ser executada, ou por ser invlida ou por ter ocorrido falha no seu processamento. Quando invlida, ela classificada em erros sintticos e semnticos. Erros sintticos so todos aqueles em que a mensagem XML no respeita as regras definidas no arquivo ecommerce.xsd. Por exemplo: letra num campo numrico; ausncia de um campo obrigatrio, etc.

11


J os semnticos esto presentes em requisies que solicitam operaes no suportadas. Por exemplo: capturar uma transao no autorizada; cancelar uma transao aps o prazo ter vencido; solicitar uma captura com valor invlido, etc. Em ambos os casos, a resposta enviada atravs de uma mensagem que contm um cdigo e uma mensagem descritiva. Veja o exemplo abaixo e o Catlogo de Erros para maiores informaes. 032 Valor de captura invlido

9.4

A venda e a transao

Para todo pedido de compra, a meta efetiv-la em uma venda. E numa venda com carto, isso pode ser traduzido em uma transao autorizada. Lembre-se que: Uma transao capturada uma transao autorizada. Dessa forma, o pedido de compra pode ser convertido em uma venda Toda transao autorizada somente gera crdito para o lojista se for capturada

9.5

Nvel de segurana da transao

Toda transao possui um indicador, chamado ECI (Eletronic Commerce Indicator), que diz quo segura uma transao . Seus valores variam de acordo com o resultado da autenticao:Resultado da Autenticao Portador autenticado com sucesso Portador no realizou autenticao, pois o Emissor no forneceu mecanismos de autenticao Portador no se autenticou com sucesso A loja optou por autorizar sem passar pela autenticao Visa 5 6 7 7 Mastercard 2 1 0 0 Diners, Discover e Elo n/a n/a n/a 7

H um campo chamado eci, dentro do n na mensagem que armazena esse dado. Esse indicador importante, pois ele quem dita as regras de Chargeback.

12


9.6

Requisio Cielo

A chamada a um Web Service resumida por Uma mensagem, definida de acordo com a funcionalidade Um destino, ambiente de teste ou de produo E um retorno, uma mensagem XML: ou Veja o exemplo abaixo: um HTTP Post com o parmetro mensagem.POST /servicos/ecommwsec.do HTTP/1.1 Host: ecommerce.cbmp.com.br Content-Type: application/x-www-form-urlencoded Content-Length: length mensagem=10069930690101012005100699306925fbb99741c739dd84d7b06ec78c9bac718838630f30b112d033ce2e621b34f33880

13


9.7

Criao

Uma transao criada a partir do envio de uma requisio contendo as seguintes informaes:N raiz Campo dados-ec.numero dados-ec.chave dados-portador dados-portador.numero dados-portador.validade

Formato N AN n/a N N Obrigatrio? Tamanho Descrio R 1..20 Nmero de afiliao da loja com a Cielo. R 1..100 Chave de acesso da loja atribuda pela Cielo. O n/a N com dados do carto. R 16 Nmero do carto. R Validade do carto no formato aaaamm. 6 Exemplos: 201212 (dez 2012). Indicador do cdigo de segurana: 0 (no informado), 1 (informado), 2 (ilegvel), 9 1 (inexistente). 3..4 Obrigatrio se indicador = 1. 0..50 Opcional. Nome impresso no carto. n/a N com dados do pedido. Nmero do pedido da loja. Recomenda-se que 1..20 seja um valor nico por pedido. 1..12 Valor do pedido. Cdigo numrico da moeda na ISO 4217. Para o 3 Real, o cdigo 986. 19 Data hora do pedido. 0..1024 Descrio do pedido. Idioma do pedido: PT (portugus), EN (ingls) ou ES (espanhol). Com base nessa informao definida a lngua a ser utilizada nas telas da Cielo. 2 Caso no preenchido, assume-se PT. n/a N com a forma de pagamento. Bandeira: visa, mastercard, diners, discover ou NOVO n/a elo (em minsculo) Cdigo do produto: 1 (Crdito Vista), 2 (Parcelado loja), 3 (Parcelado administradora), A 1 (Dbito). Nmero de parcelas. Para crdito vista ou 1..3 dbito, utilizar 1. URL da pgina de retorno. para essa tela que o fluxo ser retornado ao fim da autenticao e/ou 1..1024 autorizao. Indicador de autorizao automtica: 0 (no autorizar) 1 (autorizar somente se autenticada) 2 (autorizar autenticada e noautenticada) 3 (autorizar sem passar por autenticao vlido somente para crdito) Para Diners, Discover e Elo, o valor ser sempre 1 3. [true|false]. Define se a transao ser n/a automaticamente capturada caso seja autorizada. 0..128 Campo livre. 6 Seis primeiros nmeros do carto.

dados-portador.indicador dados-portador.codigo-seguranca dados-portador.nome-portador dados-pedido dados-pedido.numero dados-pedido.valor dados-pedido.moeda dados-pedido.data-hora dados-pedido.descricao

N N AN n/a AN N N AN AN

R C O R R R R R O

dados-pedido.idioma forma-pagamento forma-pagamento.bandeira

AN n/a AN

O R R

forma-pagamento.produto forma-pagamento.parcelas

AN N

R R

url-retorno

AN

R

autorizar capturar campo-livre bin

N A AN N

R R O O

14


9.7.1

Regras O envio ou no-envio dos dados do carto deve ser condizente com o cadastro da loja junto Cielo A forma de pagamento (modalidade e nmero de parcelas) deve tambm ser condizente com o cadastro

9.7.2

Exemplo

1001734898 e84827130b9837473681c2787007da5914d6359947015a5cdb2b8843db0fa832 285813768 100 986 2010-07-14T13:56:12 PT visa 1 1 http://minha.loja.com/pedido/285813768 2 false

9.7.3

Retorno

Os dados da transao recm criada so retornados no XML sendo que as informaes mais importantes nessa etapa so: o TID, o status igual a criada e a URL de autenticao. Por outro lado, caso a requisio seja invlida, retorna-se a mensagem . Revisite tpico Tipos de retorno caso necessrio.

15


9.8

Autenticao

A autenticao no executada via Web Service. No efetuada somente com troca de mensagens entre loja virtual e Cielo. Ela requer interao com o comprador. Interao tal que iniciada no ambiente da Cielo a partir do momento que a loja redireciona o browser do usurio. Essa transferncia de fluxo possui um destino, o qual especificado pela URL retornada aps a criao da transao. Ela pautada por algumas regras. Consulte Redirecionamento Cielo para maiores detalhes. Ou navegue pela loja exemplo para tornar mais claro esse entendimento. Aps o redirecionamento o portador fornece os dados do carto no site de e-commerce da Cielo e ento a autenticao de fato iniciada. Lembre-se: ela corre sempre no site do emissor. Para isso um segundo redirecionamento efetuado: da Cielo para o banco.

Notas 1. Somente o primeiro redirecionamento de responsabilidade da loja virtual. 2. O comprador redirecionado ao site do Banco Emissor somente se a autenticao estiver disponvel. Caso contrrio a transao prossegue autorizao (exceto se foi apenas solicitada autenticao) 3. At o momento (julho de 2011), no h mecanismos de autenticao para a bandeira Elo, Diners e Discover. A tecnologia empregada para autenticao de escolha do emissor. Pode ser carto de bingo, token, e-cpf entre outras. Entretanto o objetivo sempre o mesmo: assegurar que o comprador o portador legtimo. Essa verificao retornada Cielo e o retorno dos fluxos tem incio.

9.9

Autorizao

Com base na resposta de autenticao, autenticada ou no-autenticada, e nas escolhas efetuadas na criao da transao, a autorizao a prxima etapa. Nesse cenrio ela cunhada de autorizao automtica. Embora essa escolha caiba a loja virtual, em conjunto so consideradas outras regras:

16


Se o portador no se autenticou com sucesso, ela no executada Se o portador autenticou-se com sucesso, ela pode ser executada Se o emissor no forneceu mecanismos de autenticao, ela pode ser executada Se a resposta do emissor no pde ser validada, ela no executada Nota: nessa etapa que o saldo disponvel do carto do comprador sensibilizado caso a transao tenha sido autorizada. A outra face da autorizao aquela que pode ser efetuada num momento diferente da autenticao. O servio disponvel para isso chamado de autorizao posterior e o dados necessrios so:

N raiz Campo dados-ec.numero dados-ec.chave tid

Formato N AN AN Obrigatoriedade R R R Tamanho 1..20 1..100 1..40 Descrio Nmero de afiliao da loja com a Cielo Chave de acesso da loja atribuda pela Cielo Identificador da transao

9.9.1

Regras No aceito pedido de autorizao caso a autenticao tenha sido negada. No caso de falha, a solicitao de autorizao recusada (somente para a Visa). A solicitao de autorizao posterior pode ser efetuada em at 90 dias contados a partir da data da transao

9.9.2

Exemplo

10017348980059172008 1001734898 e84827130b9837473681c2787007da5914d6359947015a5cdb2b8843db0fa832

9.9.3

Retorno

Aps a execuo de uma autorizao, o status pode ser autorizada, no-autorizada ou capturada (caso tenha-se optado por captura automtica). Dentro da mensagem h um n especfico com os detalhes desse processamento, chamado de . Revisite o tpico Tipos de retorno caso necessrio.

17


9.10 Captura Uma transao autorizada somente gera crdito para o estabelecimento comercial caso ela seja capturada. Por isso, todo pedido de compra que o lojista queira efetivar, deve ter a transao capturada. Para venda na modalidade de Crdito, essa confirmao pode ocorrer Logo aps a autorizao (valor total) Ou num momento posterior (valor total ou parcial) Essa definio feita atravs do parmetro capturar (consulte o tpico Criao). J na modalidade de Dbito no existe essa abertura: toda transao de dbito autorizada automaticamente capturada. O servio disponvel para uma captura posterior requer os seguintes dados:

N raiz Campo dados-ec.numero dados-ec.chave tid valor anexo

Formato N AN AN N AN Obrigatoriedade R R R O O Tamanho Descrio

1..20 Nmero de afiliao da loja com a Cielo 1..100 Chave de acesso da loja atribuda pela Cielo 1..40 Identificador da transao. Valor da captura. Caso no fornecido, o valor 1..12 atribudo o valor da autorizao. 1..1024 Informao adicional para detalhamento da captura.

9.10.1 Regras Por padro, o prazo mximo para captura de 5 dias aps a data de autorizao. Exemplo: se a data de autorizao 21/09, o prazo mximo as 0 hs do dia 27/09 O valor da captura deve ser menor (captura parcial) ou igual (captura total) ao valor autorizado Somente transaes autorizadas podem ser capturadas Em caso de falha na captura, outras tentativas podero ser realizadas 9.10.2 Exemplo 10017348980048592047 1001734898 e84827130b9837473681c2787007da5914d6359947015a5cdb2b8843db0fa832

18


9.10.3 Retorno Respeitadas as regras, o retorno do pedido de captura uma mensagem com o status capturada e mais um n adicional chamado com os detalhes do processamento. Revisite o tpico Tipos de retorno caso necessrio. Por outro lado, caso alguma regra no tenha sido respeitada, o retorno uma mensagem contendo o motivo da rejeio.

9.11 Cancelamento empregado quando o lojista decide no efetivar um pedido de compra, seja por insuficincia de estoque, desistncia da compra, entre outros motivos. Seu uso faz-se necessrio principalmente se a transao estiver capturada, caso contrrio haver dbito na fatura do cliente para um pedido de compra no efetivado. Nota: se a transao estiver apenas autorizada e a loja queira cancel-la, o pedido de cancelamento no de fato necessrio: vencido o prazo de captura, ela cancelada automaticamente. Os dados necessrios ao cancelamento so:


Formato N AN AN Obrigatoriedade R R R Tamanho 1..20 1..100 1..40 Descrio Nmero de afiliao da loja com a Cielo Chave de acesso da loja atribuda pela Cielo Identificador da transao.

9.11.1 Regras Aplicvel somente para transao autorizada ou capturada Deve ser solicitado no mesmo dia da autorizao 9.11.2 Exemplo 10017348980054772008 1001734898 e84827130b9837473681c2787007da5914d6359947015a5cdb2b8843db0fa832

19


9.11.3 Retorno Respeitadas as regras, o retorno do pedido de cancelamento uma mensagem com o status cancelada e mais um n adicional chamado . Tal n contm detalhes desse processamento. Revisite o tpico Tipos de retorno caso necessrio. Por outro lado, caso alguma regra no tenha sido respeitada, o retorno uma mensagem contendo o motivo da rejeio.

9.12 Consulta via TID Funcionalidade de extrema importncia na integrao. atravs dela que a loja virtual obtm uma foto da transao. sempre utilizada aps a loja ter recebido o retorno do fluxo da Cielo. Os dados necessrios consulta so:


Formato Obrigatoriedade N AN AN R R R Tamanho Descrio 1..20 Nmero de afiliao da loja com a Cielo 1..100 Chave de acesso da loja atribuda pela Cielo 1..40 Identificador da transao.

9.12.1 Regras Somente transaes dos ltimos 180 dias esto disponveis para consulta 9.12.2 Exemplo 10017348980059031001 1001734898 e84827130b9837473681c2787007da5914d6359947015a5cdb2b8843db0fa832

9.12.3 Retorno O retorno uma mensagem . Revisite o tpico Tipos de retorno caso necessrio. Quando a requisio no pde ser atendida, ora por credencial invlida ou por falha de processamento, retorna-se uma mensagem .

20


9.13

Autorizao Direta

o pedido de autorizao sem autenticao. aquela na qual a loja virtual solicita os dados do carto em seu prprio ambiente. Logo o lojista deve estar atento s regras de segurana. Consulte Regras para leitura do carto na prpria loja. Essa funcionalidade muito prxima a Criao de uma transao (item 9.7). Baseia-se na mesma mensagem . Porm mais simples:N raiz Campo dados-ec.numero dados-ec.chave dados-portador dados-portador.numero dados-portador.validade

Formato N AN n/a N N Obrigatrio? Tamanho Descrio R 1..20 Nmero de afiliao da loja com a Cielo. R 1..100 Chave de acesso da loja atribuda pela Cielo. O n/a N com dados do carto. R 16 Nmero do carto. R Validade do carto no formato aaaamm. 6 Exemplos: 201212 (dez 2012). Indicador do cdigo de segurana: 0 (no informado), 1 (informado), 2 (ilegvel), 9 1 (inexistente). 3..4 Obrigatrio se indicador = 1. 0..50 Opcional. Nome impresso no carto. n/a N com dados do pedido. Nmero do pedido da loja. Recomenda-se que 1..20 seja um valor nico por pedido. 1..12 Valor do pedido. Cdigo numrico da moeda na ISO 4217. Para o 3 Real, o cdigo 986. 19 Data hora do pedido. 0..1024 Descrio do pedido. n/a N com a forma de pagamento. Bandeira: visa, mastercard, diners, discover ou NOVO n/a elo (em minsculo) Cdigo do produto: 1 (Crdito Vista), 2 1 (Parcelado loja), 3 (Parcelado administradora) Nmero de parcelas. Para crdito vista ou 1..3 dbito, utilizar 1. 1 Valor fixo. Deve ser sempre 3, Autorizar Direto. [true|false]. Define se a transao ser n/a automaticamente capturada caso seja autorizada.

dados-portador.indicador dados-portador.codigo-seguranca dados-portador.nome-portador dados-pedido dados-pedido.numero dados-pedido.valor dados-pedido.moeda dados-pedido.data-hora dados-pedido.descricao forma-pagamento forma-pagamento.bandeira forma-pagamento.produto forma-pagamento.parcelas autorizar capturar

N N AN n/a AN N N AN AN n/a AN AN N N A

R C O R R R R R O R R R R R R

21


9.13.1 Regras A loja virtual deve estar habilitada a enviar os dados do carto A forma de pagamento (modalidade e nmero de parcelas) deve ser condizente com o cadastro da loja A autorizao direta no se aplica s transaes de Dbito pois esse tipo requer autenticao O nvel de segurana da transao (ECI) definido como 7 (se Visa, Diners, Discover ou Elo) e 0 (se Mastercard) 9.13.2 Exemplo 1006993069 25fbb99741c739dd84d7b06ec78c9bac718838630f30b112d033ce2e621b34f3 4551870000000183 201501 1 585 1530561447 10000 986 2011-07-27T20:52:34 descricaoDoPedido PT visa 1 1 3 false

22


9.13.3 Retorno O retorno uma mensagem , com o n preenchido com os detalhes da autorizao. O status pode ser autorizada, no-autorizada ou capturada. Se a requisio for invlida, retorna-se a mensagem . Revisite o tpico Tipos de retorno caso necessrio. Nota: na ocorrncia de erros durante a autorizao (um timeout, por exemplo), a loja virtual deve consultar quela transao (via Nmero do Pedido, veja item 9.13.4) antes de tentar submeter uma nova. Pois num caso como esse, h possibilidade da transao ter sido autorizada. Por isso muito importante que o nmero do pedido informado seja consistente (se possvel, um nmero para cada solicitao). 10069930690059201001 o6wY9v4JnD2aG7mVsFEDgg== 633912164370523780 100 986 2010-07-14T15:28:42 PT visa 1 1 5 6 Transao sem autenticao 2010-07-14T15:28:42 100 07 5 Carto invlido 2010-07-14T15:28:42 100 14 141516

23


9.13.4 Consulta via Nmero do Pedido Consulta de transao via nmero do pedido. Seu uso restrito para casos onde h ausncia do identificador da transao (TID), por conta de um timeout, por exemplo. So retornadas as mesmas informaes da consulta via TID. Os dados necessrios consulta so:

N raiz Campo numero-pedido dados-ec.numero dados-ec.chave

Formato Obrigatoriedade NA N AN R R R Tamanho Descrio 1..20 Nmero do Pedido associado Transao 1..20 Nmero de afiliao da loja com a Cielo 1..100 Chave de acesso da loja atribuda pela Cielo

9.13.5 Regras Somente transaes dos ltimos 180 dias esto disponveis para consulta Caso a loja virtual possua mais de uma transao para um mesmo nmero do pedido, retorna-se a transao mais recente apenas. 9.13.6 Exemplo 1401406040 1001734898 e84827130b9837473681c2787007da5914d6359947015a5cdb2b8843db0fa832

9.13.7 Retorno O retorno uma mensagem . Revisite o tpico Tipos de retorno caso necessrio. Quando a requisio no pde ser atendida, ora por credencial invlida ou por falha de processamento, retorna-se uma mensagem .

24


10

Catlogo de Erros

A seguir os erros que so comunicados atravs da mensagem XML :

Cdigo

Erro

Descrio A mensagem XML est fora do formato especificado pelo arquivo ecommerce.xsd Impossibilidade de autenticar uma requisio da loja virtual. No existe transao para o identificador informado A transao, com ou sem carto, est divergente com a permisso de envio dessa informao A transao est configurada com uma modalidade de pagamento no habilitada para a loja O nmero de parcelas solicitado ultrapassa o mximo permitido Flag de autorizao automtica incompatvel com a forma de pagamento solicitada A solicitao de Autorizao Direta est invlida A solicitao de Autorizao Direta est sem carto O TID fornecido est duplicado O cdigo de segurana do carto no foi enviado Uso incorreto do indicador de cdigo de segurana No permitido realizar autorizao para o status da transao No permitido realizar autorizao, pois o prazo est vencido O resultado da Autenticao da transao no permite a solicitao de Autorizao O status da transao no permite captura A captura no pode ser realizada, pois o prazo para captura est vencido O valor solicitado para captura no vlido

Ao Revisar as informaes enviadas na mensagem XML frente as especificaes Verificar se o nmero de afiliao e a chave esto corretos Rever a aplicao Rever se o cadastro da loja permite o envio do carto ou no Rever a modalidade de pagamento solicitada Rever a forma de pagamento Rever as regras de utilizao da flag Rever as regras de utilizao da Autorizao Direta Rever as regras de utilizao da Autorizao Direta Rever a aplicao Rever a aplicao Revisar as informaes de carto enviadas na mensagem XML Rever as regras de autorizao Rever as regras de autorizao Rever as regras de autorizao Rever as regras de captura Rever as regras de captura Rever as regras de captura Realizar nova tentativa. Persistindo, entrar em contato com o Suporte ecommerce e informar o TID da transao. Rever as regras de cancelamento Rever as regras de cancelamento Realizar nova tentativa. Persistindo, entrar em contato com o Suporte ecommerce e informar o TID da transao.

001 002 003 010 011 012 013 014 015 016 017 018 020 021 025 030 031 032

Mensagem invlida Credenciais invlidas Transao inexistente Inconsistncia no envio do carto Modalidade no habilitada Nmero de parcelas invlido Flag de autorizao automtica invlida Autorizao Direta invlida Autorizao Direta sem Carto Identificador, TID, invlido Cdigo de segurana ausente Indicador de cdigo de segurana inconsistente Status no permite autorizao Prazo de autorizao vencido Encaminhamento a autorizao no permitido Status invlido para captura Prazo de captura vencido Valor de captura invlido

033

Falha ao capturar Prazo de cancelamento vencido Status no permite cancelamento Falha ao cancelar

No foi possvel realizar a captura O cancelamento no pode ser realizado, pois o prazo est vencido O atual status da transao no permite cancelamento

040 041

042

No foi possvel realizar o cancelamento

25


Cdigo 097 098 099

Erro Sistema indisponvel Timeout Erro inesperado

Descrio Falha no sistema A aplicao no respondeu dentro de 25 segundos Falha no sistema

Ao Persistindo, entrar em contato com o Suporte e-commerce Persistindo, entrar em contato com o Suporte e-commerce Persistindo, entrar em contato com o Suporte e-commerce e informar o TID da transao

26


11

Redirecionamento Cielo

O redirecionamento do browser do comprador deve ser realizado em modo Full Screen. Ou seja, no h mais suporte a abertura de Pop Up. Dessa forma, partir da tela de checkout deve ser realizado um redirecionamento URL retornada na criao da transao. Esse redirecionamento pode ser atravs de um Http Redirect (como no cdigo da Loja Exemplo) ou atravs de um Javascript. Consulte o Guia da Loja Exemplo para maiores detalhes de implementao. 12 Dados para teste

As informaes abaixo podem ser usadas pelo desenvolvedor durante o desenvolvimento da integrao. Carto com autenticao: 4012001037141112 (visa) Carto sem autenticao: 4551870000000183 (visa), 5453010000066167 (mastercard), 6362970000457013 (elo), 36490102462661 (diners) e 6011020000245045 (discover). Data de validade: qualquer posterior ao corrente Cdigo de segurana: qualquer Valor do pedido: para simular transao autorizada, use qualquer valor em que os dois ltimos dgitos sejam zeros. Do contrrio, toda autorizao ser negada. Credenciais

Leitura do carto Loja Cielo

Nmero

Chave

1006993069 25fbb99741c739dd84d7b06ec78c9bac718838630f30b112d033ce2e621b34f3 1001734898 e84827130b9837473681c2787007da5914d6359947015a5cdb2b8843db0fa832

13

Ambientes

Ambiente Teste Produo

URL https://qasecommerce.cielo.com.br/servicos/ecommwsec.do https://ecommerce.cbmp.com.br/servicos/ecommwsec.do

27


14

Homologao

O objetivo dessa fase assegurar que a integrao esteja funcionando de maneira adequada. Ela iniciada aps o trmino da implementao. Aps a integrao da loja feita com o ambiente de Teste (da Cielo). composta pelas seguintes etapas: 1) Finalizao do cadastro junto Cielo e recebimento da chave de produo 2) Execuo de testes na loja virtual integrada ao ambiente de produo da Cielo 3) Homologao pela Cielo Na primeira etapa, o lojista solicita a chave de produo. Para tanto necessrio enviar para [email protected] as seguintes informaes (que iro completar o cadastro): URL definitiva do site (ambiente de produo) Nome da empresa responsvel pelo desenvolvimento da integrao Nome e e-mail do tcnico (desenvolvedor) responsvel pela integrao Nmero de afiliao (junto a Cielo) da loja virtual Razo social e nome fantasia da loja virtual URL do logotipo da loja, no formato GIF e tamanho de 112X25 pixels Usurio e senha na loja virtual para efetuar compras Em resposta, a Cielo retorna uma chave vlida no ambiente de produo. 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 tpicos: Interao com os Web Services: testes com todas as funcionalidades utilizadas Integrao visual: a ida e a volta do fluxo a Cielo (os fluxos alternativos devem ser considerados) Aplicao correta da marca da bandeira Modalidades de pagamento: testes com as combinaes possveis de pagamento Ao trmino, uma nova solicitao deve ser enviada para [email protected], para que a Cielo realize a homologao de fato. Um conjunto de testes ento executado. Para aprovar e negar transaes. O resultado, homologado ou no-homologado, enviado por e-mail.

28


15

Suporte e-commerce Cielo (atendimento bilingue, 24 x 7) 40029700 (opo:1- suporte tcnico e 2 - afiliao e-commerce) (Capitais e Regies Metropolitanas) 0800-570-1700 (opo:1- suporte tcnico e 2 - afiliao e-commerce) (Demais Localidades) [email protected]

16

Regras para leitura do carto na prpria loja

Para que seja possvel a solicitao das informaes do carto ao portador na prpria loja virtual, ela deve atender a um conjunto de regras definidas pelo programa de segurana da Bandeira do Carto de Crdito. Para a Visa, esse programa o AIS (Account Information Security) PCI. Para maiores informaes acesse: www.cielo.com.br > Servios > Servios de Segurana > AIS Programa de Segurana da Informao, ou entre em contato conosco. Para a Mastercard o programa de segurana o SDP (Site Data Protection) PCI. Para maiores informaes acesse: http://www.mastercard.com/us/sdp/index.html, ou entre em contato conosco. Ademais, atendidos os requisitos, no momento da afiliao e-commerce deve ser mencionada a escolha por leitura do carto na prpria loja.

29


17

Apndice Como saber qual o certificado a Cielo utiliza? Abra um browser, digite https://ecommerce.cbmp.com.br e clique no cone que exibe as informaes sobre o certificado.

Programa Verified by Visa (Visa) Programa internacional da Visa para possibilitar a autenticao do comprador no momento de uma compra em ambiente e-commerce. Visite www.verifiedbyvisa.com.br para maiores informaes. Programa Secure Code (Mastercard) Programa internacional da Mastercard para possibilitar a autenticao do comprador no momento de uma compra em ambiente e-commerce. Visite http://www.mastercard.com/securecode para maiores informaes.

30

manual do desenvolvedor 1.5.8.1

Documents