Guia de Implementação
Versão 3.0
CIELO Ecommerce
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 comercio@locaweb.com.br Atendimento: http://atendimento.locaweb.com.br/
2010
CIELO Ecommerce
Página 1 de 21
Guia de Implementação
Versão 3.0
CIELO Ecommerce 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
2010
CIELO Ecommerce
Página 2 de 21
Guia de Implementação
Versão 3.0
CIELO Ecommerce 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) suporteweb@cielo.com.br
2010
CIELO Ecommerce
Página 3 de 21
Guia de Implementação
Versão 3.0
CIELO Ecommerce 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 .
2010
CIELO Ecommerce
Página 4 de 21
Guia de Implementação
Versão 3.0
CIELO Ecommerce 3. Registro da transação Os parâmetros que deverão ser passados via POST são: Parâmetro
Formato
Tamanho
Obrigatório
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.
AlfaNum
2
N
Idioma do pedido. Utilizar: PT (português), EN (inglês) ou ES (espanhol)
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
idioma
valor
Descrição
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ãoautenticada), 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
2010
CIELO Ecommerce
Página 5 de 21
Guia de Implementação
Versão 3.0
CIELO Ecommerce 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 tid status
url-autenticacao
Formato
Tamanho
Descrição
AlfaNum
40
Código de identificação da transação.
Num
2
Status da transação. Ver item 10. Possíveis status de transação.
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
idioma
AlfaNum
2
Idioma do pedido.
Breve descrição 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> <urlautenticacao>https://qasecommerce.cielo.com.br/web/index.cbmp?id=d75b93d1edbc1a84fcf71 6ba727c4c5c</url-autenticacao> </transacao>
2010
CIELO Ecommerce
Página 6 de 21
Guia de Implementação
Versão 3.0
CIELO Ecommerce Caso ocorra algum erro no processo, serão retornados os parâmetros: Parâmetro codigo mensagem
Formato
Tamanho
Descrição
Num
-
Código do erro. Ver item 12. Possíveis retornos de erro.
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.
2010
CIELO Ecommerce
Página 7 de 21
Guia de Implementação
Versão 3.0
CIELO Ecommerce 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: Parâmetro
Formato
Tamanho
Obrigatório
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: 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.
AlfaNum
2
N
Idioma do pedido. Utilizar: PT (português), EN (inglês) ou ES (espanhol)
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
campo_livre
AlfaNum
128
N
Campo livre.
idioma
valor
2010
CIELO Ecommerce
Descrição
Página 8 de 21
Guia de Implementação
Versão 3.0
CIELO Ecommerce 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: Parâmetro
Formato
Tamanho
tid
AlfaNum
40
Código de identificação da transação.
pan
AlfaNum
40
Hash do número do cartão do portador.
Num
2
Status da transação. Ver item 10. Possíveis status de transação.
AlfaNum
256
URL de redirecionamento a Cielo para processamento da transação.
status
url-autenticacao
Descriçã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
idioma
AlfaNum
2
Idioma do pedido.
Breve descrição do pedido.
Forma de Pagamento (forma-pagamento) bandeira
AlfaNum
-
Bandeira.
produto
Num
1
Forma de pagamento.
parcelas
Num
3
Número de parcelas.
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.
Num
2
Código do processamento.
mensagem
AlfaNum
100
Detalhe do processamento.
data-hora
AlfaNum
19
Data hora do processamento.
Num
12
Valor do processamento sem pontuação.
Autenticação (autenticacao) codigo
Autorização (autorizacao) codigo
valor
2010
CIELO Ecommerce
Página 9 de 21
Guia de Implementação
Versão 3.0
CIELO Ecommerce lr arp
Num
2
Retorno da autorização.
AlfaNum
6
Código da autorização caso a transação tenha sido autorizada com sucesso.
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>10017348980401251001</tid> <pan>34353531383730303030303030313833</pan> <dados-pedido> <numero>5</numero> <valor>100</valor> <moeda>986</moeda> <data-hora>2010-04-27T18:34:10.427-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>9</status> <autenticacao> <codigo>9</codigo> <mensagem>Transacao sem autenticacao</mensagem> <data-hora>2010-04-27T18:35:00.454-03:00</data-hora> <valor>100</valor> <eci>7</eci> </autenticacao> <autorizacao> <codigo>9</codigo> <mensagem>Transação autorizada</mensagem> <data-hora>2010-04-27T18:35:00.502-03:00</data-hora> <valor>100</valor> <lr>00</lr> <arp>183501</arp> </autorizacao> <urlautenticacao>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: Parâmetro codigo mensagem
Formato
Tamanho
Descrição
Num
-
Código do erro. Ver item 12. Possíveis retornos de erro.
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>
2010
CIELO Ecommerce
Página 10 de 21
Guia de Implementação
Versão 3.0
CIELO Ecommerce 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: 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: Autorizacao
ambiente
AlfaNum
-
S
Define o tipo de ambiente. Utilizar: TESTE ou PRODUCAO
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: Parâmetro
Formato
Tamanho
tid
AlfaNum
40
Código de identificação da transação.
pan
AlfaNum
40
Hash do número do cartão do portador.
Num
2
Status da transação. Ver item 10. Possíveis status de transação.
AlfaNum
256
URL de redirecionamento a Cielo para processamento da transação.
status
url-autenticacao
Descriçã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
idioma
AlfaNum
2
Idioma do pedido.
-
Bandeira.
Breve descrição do pedido.
Forma de Pagamento (forma-pagamento) bandeira
2010
AlfaNum
CIELO Ecommerce
Página 11 de 21
Guia de Implementação
Versão 3.0
CIELO Ecommerce produto
Num
1
Forma de pagamento.
parcelas
Num
3
Número de parcelas.
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.
lr
Num
2
Retorno da autorização.
AlfaNum
6
Código da autorização caso a transação tenha sido autorizada com sucesso.
Autorização (autorizacao) codigo
arp
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>10017348980401251001</tid> <pan>34353531383730303030303030313833</pan> <dados-pedido> <numero>5</numero> <valor>100</valor> <moeda>986</moeda> <data-hora>2010-04-27T18:34:10.427-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>9</status> <autorizacao> <codigo>9</codigo> <mensagem>Transação autorizada</mensagem> <data-hora>2010-04-27T18:35:00.502-03:00</data-hora> <valor>100</valor> <lr>00</lr> <arp>183501</arp> </autorizacao> <urlautenticacao>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: Parâmetro codigo mensagem
Formato
Tamanho
Descrição
Num
-
Código do erro. Ver item 12. Possíveis retornos de erro.
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>
2010
CIELO Ecommerce
Página 12 de 21
Guia de Implementação
Versão 3.0
CIELO Ecommerce 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: 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: Consulta
ambiente
AlfaNum
-
S
Define o tipo de ambiente. Utilizar: TESTE ou PRODUCAO
tid
AlfaNum
40
S
Código de identificação da transação.
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: Parâmetro
Formato
Tamanho
tid
AlfaNum
40
Código de identificação da transação.
pan
AlfaNum
40
Hash do número do cartão do portador.
Num
2
Status da transação. Ver item 10. Possíveis status de transação.
AlfaNum
256
URL de redirecionamento a Cielo para processamento da transação.
status
url-autenticacao
Descriçã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
idioma
AlfaNum
2
Idioma do pedido.
-
Bandeira.
Breve descrição do pedido.
Forma de Pagamento (forma-pagamento) bandeira
2010
AlfaNum
CIELO Ecommerce
Página 13 de 21
Guia de Implementação
Versão 3.0
CIELO Ecommerce produto
Num
1
Forma de pagamento.
parcelas
Num
3
Número de parcelas.
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.
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.
lr
Num
2
Retorno da autorização.
AlfaNum
6
Código da autorização caso a transação tenha sido autorizada com sucesso.
Num
2
Código do processamento.
mensagem
AlfaNum
100
Detalhe do processamento.
data-hora
AlfaNum
19
Data hora do processamento.
Num
12
Valor do processamento sem pontuação.
Num
2
Código do processamento.
mensagem
AlfaNum
100
Detalhe do processamento.
data-hora
AlfaNum
19
Data hora do processamento.
Num
12
Valor do processamento sem pontuação.
Autenticação (autenticacao) codigo
Autorização (autorizacao) codigo
arp
Captura (captura) codigo
valor
Cancelamento (cancelamento) codigo
valor
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>10017348980401251001</tid> <pan>34353531383730303030303030313833</pan> <dados-pedido> <numero>5</numero> <valor>100</valor> <moeda>986</moeda> <data-hora>2010-04-27T18:34:10.427-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>
2010
CIELO Ecommerce
Página 14 de 21
Guia de Implementação
Versão 3.0
CIELO Ecommerce </forma-pagamento> <status>9</status> <autenticacao> <codigo>9</codigo> <mensagem>Transacao sem autenticacao</mensagem> <data-hora>2010-04-27T18:35:00.454-03:00</data-hora> <valor>100</valor> <eci>7</eci> </autenticacao> <autorizacao> <codigo>9</codigo> <mensagem>Transação autorizada</mensagem> <data-hora>2010-04-27T18:35:00.502-03:00</data-hora> <valor>100</valor> <lr>00</lr> <arp>183501</arp> </autorizacao> <captura> <codigo>9</codigo> <mensagem>Transacao capturada com sucesso</mensagem> <data-hora>2010-04-27T18:36:09.025-03:00</data-hora> <valor>100</valor> </captura> <cancelamento> <codigo>9</codigo> <mensagem>Transacao cancelada com sucesso</mensagem> <data-hora>2010-04-27T18:37:54.591-03:00</data-hora> <valor>100</valor> </cancelamento> <urlautenticacao>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: Parâmetro codigo mensagem
Formato
Tamanho
Descrição
Num
-
Código do erro. Ver item 12. Possíveis retornos de erro.
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>
2010
CIELO Ecommerce
Página 15 de 21
Guia de Implementação
Versão 3.0
CIELO Ecommerce 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: Parâmetro
Formato
Tamanho
Obrigatório
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: Captura
ambiente
AlfaNum
-
S
Define o tipo de ambiente. Utilizar: TESTE ou PRODUCAO
tid
AlfaNum
40
S
Código de identificação da transação.
Num
12
N
Valor da transação que será capturado. Utilizar: 100 para R$ 1,00
AlfaNum
128
N
Campo livre.
valor campo_livre
Descrição
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: Parâmetro
Formato
Tamanho
tid
AlfaNum
40
Código de identificação da transação.
pan
AlfaNum
40
Hash do número do cartão do portador.
Num
2
Status da transação. Ver item 10. Possíveis status de transação.
AlfaNum
256
URL de redirecionamento a Cielo para processamento da transação.
status
url-autenticacao
Descriçã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.
AlfaNum
19
Data e hora do pedido.
data-hora
2010
CIELO Ecommerce
Página 16 de 21
Guia de Implementação
Versão 3.0
CIELO Ecommerce 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.
Num
2
Código do processamento.
mensagem
AlfaNum
100
Detalhe do processamento.
data-hora
AlfaNum
19
Data hora do processamento.
Num
12
Valor do processamento sem pontuação.
Captura (captura) codigo
valor
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>10017348980401251001</tid> <pan>34353531383730303030303030313833</pan> <dados-pedido> <numero>5</numero> <valor>100</valor> <moeda>986</moeda> <data-hora>2010-04-27T18:34:10.427-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>9</status> <captura> <codigo>9</codigo> <mensagem>Transacao capturada com sucesso</mensagem> <data-hora>2010-04-27T18:36:09.025-03:00</data-hora> <valor>100</valor> </captura> <urlautenticacao>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: Parâmetro codigo mensagem
Formato
Tamanho
Descrição
Num
-
Código do erro. Ver item 12. Possíveis retornos de erro.
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>
2010
CIELO Ecommerce
Página 17 de 21
Guia de Implementação
Versão 3.0
CIELO Ecommerce 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: 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: Cancelamento
ambiente
AlfaNum
-
S
Define o tipo de ambiente. Utilizar: TESTE ou PRODUCAO
tid
AlfaNum
40
S
Código de identificação da transação.
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: Parâmetro
Formato
Tamanho
tid
AlfaNum
40
Código de identificação da transação.
pan
AlfaNum
40
Hash do número do cartão do portador.
Num
2
Status da transação. Ver item 10. Possíveis status de transação.
AlfaNum
256
URL de redirecionamento a Cielo para processamento da transação.
status
url-autenticacao
Descriçã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
idioma
AlfaNum
2
2010
Breve descrição do pedido. Idioma do pedido.
CIELO Ecommerce
Página 18 de 21
Guia de Implementação
Versão 3.0
CIELO Ecommerce Forma de Pagamento (forma-pagamento) bandeira
AlfaNum
-
Bandeira.
produto
Num
1
Forma de pagamento.
parcelas
Num
3
Número de parcelas.
Num
2
Código do processamento.
mensagem
AlfaNum
100
Detalhe do processamento.
data-hora
AlfaNum
19
Data hora do processamento.
Num
12
Valor do processamento sem pontuação.
Cancelamento (cancelamento) codigo
valor
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>10017348980401251001</tid> <pan>34353531383730303030303030313833</pan> <dados-pedido> <numero>5</numero> <valor>100</valor> <moeda>986</moeda> <data-hora>2010-04-27T18:34:10.427-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>9</status> <cancelamento> <codigo>9</codigo> <mensagem>Transacao cancelada com sucesso</mensagem> <data-hora>2010-04-27T18:37:54.591-03:00</data-hora> <valor>100</valor> </cancelamento> <urlautenticacao>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: Parâmetro codigo mensagem
Formato
Tamanho
Descrição
Num
-
Código do erro. Ver item 12. Possíveis retornos de erro.
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>
2010
CIELO Ecommerce
Página 19 de 21
Guia de Implementação
Versão 3.0
CIELO Ecommerce 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
2010
CIELO Ecommerce
Página 20 de 21
Guia de Implementação
Versão 3.0
CIELO Ecommerce 12. Possíveis retornos de erro Código
2010
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
CIELO Ecommerce
Página 21 de 21