Integração Webservice 1.5

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

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

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

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

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

Suporte Cielo

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

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

Glossário

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

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

Produtos e Bandeiras suportadas

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

Certificado Extended Validation

O que é Certificado SSL?

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

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

Internet Explorer:

Firefox

Google Chrome

O que é Certificado EV SSL?

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

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

Como instalar o Certificado Extended Validation no servidor da Loja?

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

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

Passo a Passo para a Instalação

Instalação no Servidor da Loja Virtual

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

Acesso do Cliente à Loja Virtual

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

1o Passo:

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

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

2o Passo:

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

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

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

3o Passo:

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

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

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

4o Passo:

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

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

5o Passo:

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

6o Passo:

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

7o Passo:

Clique em “Concluir”.

8o Passo:

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

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

9o Passo:

Repita o mesmo procedimento para os 3 arquivos enviados.

Dúvidas

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

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

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

Visão Geral

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

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

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

Características da solução

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

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

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

Considerações sobre a integração

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

Arquitetura

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

A chamada ao Web Service é resumida por:

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

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

Transação

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

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

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

Atualizações Mandatórias

Facilitadores de Pagamento

Todos os clientes de E-Commerce que são Facilitadores de Pagamento, por obrigatoriedade das bandeiras e do Banco Central deverão enviar novos campos na mensageria transacional. A Cielo transmitirá as informações para as bandeiras por meio da mensageria transacional no momento da autorização.

Os novos campos estão contidos dentro da tag <subcredenciador>. Além dos campos deste novo nó, os facilitadores terão também de enviar obrigatoriamente a tag <soft-descriptor>. Segue abaixo exemplo do envio e da resposta.

Requisição

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

Resposta

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<transacao id="a97ab62a-7956-41ea-b03f-c2e9f612c293" versao="1.2.1" xmlns=http://ecommerce.cbmp.com.br>
    <tid>10069930691VE920A57C</tid>
    <pan>LtEYby/oCSWVqxTgWTU8T3Lq642xUUiNI+Ue38kiQK0=</pan>
    <dados-pedido>
        <numero>178148599</numero>
        <valor>1000</valor>
        <moeda>986</moeda>
        <data-hora>2011-12-07T11:43:37</data-hora>
        <descricao>[origem:10.50.54.156]</descricao>
        <idioma>PT</idioma>
        <criptomoeda>true</criptomoeda>
    </dados-pedido>
    <forma-pagamento>
        <bandeira>visa</bandeira>
        <produto>1</produto>
        <parcelas>1</parcelas>
    </forma-pagamento>
    <status>4</status>
    <autenticacao>
        <codigo>4</codigo>
        <mensagem>Transacao sem autenticacao</mensagem>
        <data-hora>2022-06-29T14:31:37.769-03:00</data-hora>
        <valor>1000</valor>
        <eci>7</eci>
    </autenticacao>
    <autorizacao>
        <codigo>4</codigo>
        <mensagem>Transacao autorizada</mensagem>
        <data-hora>2022-06-29T14:31:37.769-03:00</data-hora>
        <valor>1000</valor>
        <lr>00</lr>
        <arp>163940</arp>
        <nsu>687251</nsu>
    </autorizacao>
</transacao>

Transações CBPS

Entidades que operam como CBPS (em português, Serviço de Pagamento de Contas para Consumidores) são empresas que oferecem serviços consolidados de pagamento de contas ao portador de cartão. A Marcação de CBPS é uma opção específica para a bandeira Visa e fornece mais visibilidade e precisão nas transações.

Os estabelecimentos que operam com esse serviço devem ser registrados junto a Visa e para operar como tal, devem enviar algumas informações adicionais através da mensageria, que são exigidas pela bandeira. Veja abaixo:

Requisição

<?xml version="1.0"?>
<requisicao-transacao id="1abd5a36-fba5-4a92-9341-7c9e9d44aa1a" versao="1.3.0">
    <dados-ec>
        <numero>2000019700</numero>
        <chave>8c08a0d0f00b73dedd2673a06fa725b0bd8edbf71c4c7dd0614bf408e4d16120</chave>
        <mcc-dinamico>4900</mcc-dinamico>
    </dados-ec>
    <dados-portador>
        <numero>4084359300407900</numero>
        <validade>202405</validade>
        <indicador>1</indicador>
        <codigo-seguranca>123</codigo-seguranca>
        <nome-portador>Teste Cashin</nome-portador>
        <token/>
    </dados-portador>
    <dados-pedido>
        <numero>12345</numero>
        <valor>1000</valor>
        <moeda>986</moeda>
        <data-hora>2021-11-26T10:00:05</data-hora>
        <descricao>Compra Online</descricao>
        <idioma>PT</idioma>
        <soft-descriptor>CART*LOJA</soft-descriptor>
<pagamento-conta>true</pagamento-conta>
    </dados-pedido>
    <forma-pagamento>
        <bandeira>Visa</bandeira>
        <produto>1</produto>
        <parcelas>1</parcelas>
    </forma-pagamento>
    <url-retorno>http://www.cielo.com.br</url-retorno>
    <autorizar>3</autorizar>
    <capturar>true</capturar>
    <gerar-token>false</gerar-token>
</requisicao-transacao>

MCC’s permitidos para CBPS:

Quasi cash

Transações Quasi Cash são aquelas transações referentes a compras de fichas para jogos online, compras de bilhete de lotéricas ou relacionados. Apenas alguns MCCs (Códigos de categoria de atuação) que podem processar transações desse modelo. Consulte o time Cielo para entender se o seu negócio entra nesse modelo.

Todos os clientes de E-commerce que transacionarem quasi cash, devem usar a requisição de uma transação de débito e/ou crédito (dependendo do tipo de pagamento escolhido) e encaminhar adicionalmente a tag quase-cash conforme exemplo a seguir:

Requisição

<?xml version="1.0"?>
<requisicao-transacao id="1abd5a36-fba5-4a92-9341-7c9e9d44aa1a" versao="1.3.0">
    <dados-ec>
        <numero>2000019700</numero>
        <chave>8c08a0d0f00b73dedd2673a06fa725b0bd8edbf71c4c7dd0614bf408e4d16120</chave>
    </dados-ec>
    <dados-portador>
        <numero>4084359300407900</numero>
        <validade>202405</validade>
        <indicador>1</indicador>
        <codigo-seguranca>123</codigo-seguranca>
        <nome-portador>TESTE</nome-portador>
        <token/>
    </dados-portador>
    <dados-pedido>
        <numero>79346</numero>
        <valor>35000</valor>
        <moeda>986</moeda>
        <data-hora>2016-02-16T13:45:05</data-hora>
        <descricao>Compra Online</descricao>
        <idioma>PT</idioma>
        <soft-descriptor>soft teste</soft-descriptor>
        <quasi-cash>true</quasi-cash>
    </dados-pedido>
    <forma-pagamento>
        <bandeira>visa</bandeira>
        <produto>1</produto>
        <parcelas>1</parcelas>
    </forma-pagamento>
    <url-retorno>http://www.cielo.com.br</url-retorno>
    <autorizar>3</autorizar>
    <capturar>false</capturar>
    <gerar-token>false</gerar-token>
   </requisicao-transacao>

Transações SDWO

Se categoriza como uma SDWO (Staged Digital Wallet Operators) uma empresa que oferece serviços de carteira digital/wallet, ou seja, que permite que o portador pague a aquisição de um produto ou serviço por meio de sua própria plataforma, seja com cadastro de cartões de crédito ou debito, ou geração de QR code.

Para transacionar como SDWO, o estabelecimento precisa se registrar junto as bandeiras. Para isso, procure seu gestor comercial Cielo para mais informações.

No caso de transações de ecommerce de uma SDWO com cartão de crédito ou débito (não originadas por um QR Code), é necessário que a carteira mande alguns dados adicionais na transação, para que as bandeiras possam identificar e diferenciar esse tipo de transação. Veja abaixo as especificações:

Além dos campos específicos dessa modalidade, para transações SDWO também é obrigatório o envio do Soft Descriptor (campo dados-pedido.soft-descriptor) e CPF/CNPJ do portador (campo dados-portador.cnpj-cpf-portador). Confira mais detalhes desses campos na tabela de propriedades da requisição.

Para efetuar testes, é necessário apenas seguir as orientações do menu Testes e Homologação

Para enviar o MCC do varejista na transação de SDWO, a orientação do mercado é utilizar a tabela da ABECS (Associação Brasileira das Empresas de cartões de crédito e Serviços) que realiza o de-para de CNAEs para os MCCS de toda a indústria. Essa tabela é atualizada constantemente e está disponível online no site da Abecs no seguinte link:ABECS

Importante: A marcação de SDWO é apenas aceita para as seguintes modalidades e bandeiras: Visa/Elo- crédito e débito; Mastercard - apenas crédito. Aceita cartões estrangeiros.

Requisição

<?xml version="1.0"?>
<requisicao-transacao id="1abd5a36-fba5-4a92-9341-7c9e9d44aa1a" versao="1.3.0">
    <dados-ec>
        <numero>xxxxxxxxxx</numero>
        <chave>xxxxxxxxxxxxxxxxxxxxxxxxx</chave>
        <mcc-dinamico>xxxx</mcc-dinamico>
    </dados-ec>
    <dados-portador>
        <numero>xxxxxxxxxxxxxx</numero>
        <validade>******</validade>
        <indicador>1</indicador>
        <codigo-seguranca>***</codigo-seguranca>
        <nome-portador>NOME DO PORTADOR</nome-portador>
        <cnpj-cpf-portador>12345678901</cnpj-cpf-portador>
        <token/>
        <carteira>
           <tipo>MASTERPASS</tipo>
        </carteira>
    </dados-portador>
    <dados-pedido>
        <numero>xxxxx</numero>
        <valor>1000</valor>
        <moeda>986</moeda>
        <data-hora>2021-11-26T10:00:05</data-hora>
        <descricao>Compra Online</descricao>
        <idioma>PT</idioma>
        <soft-descriptor>CART*LOJAABCDE</soft-descriptor>
    </dados-pedido>
    <forma-pagamento>
        <bandeira>mastercard</bandeira>
        <produto>1</produto>
        <parcelas>1</parcelas>
    </forma-pagamento>
    <url-retorno>http://www.cielo.com.br</url-retorno>
    <autorizar>3</autorizar>
    <capturar>true</capturar>
    <gerar-token>false</gerar-token>
</requisicao-transacao>

Transações Cash In

Uma transação do tipo Cash In é uma operação de adição de créditos em uma carteira digital. Os estabelecimentos que operam com esse tipo de transação devem ser registrados como carteira digital junto as bandeiras e devem estar cadastrados com um dos seguintes MCCs (Códigos de categoria do estabelecimento): 6540/6051 Master ou VISA, a bandeira ELO só opera com o MCC 6540.

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

Além disso, precisam enviar alguns dados adicionais na transação, para que as bandeiras possam identificar e diferenciar esse tipo de transação. Veja abaixo as especificações:

Além dos campos específicos dessa modalidade, para transações Cash in também é obrigatório o envio do Soft Descriptor (campo dados-pedido.soft-descriptor) e CPF/CNPJ do portador (campo dados-portador.cnpj-cpf-portador). No caso de Cash In, o campo do soft descriptor precisa ser preenchido com nome da carteira*nome do portador. Confira mais detalhes desses campos na tabela de propriedades da requisição.

Importante: A marcação de Cash In é apenas aceita para as seguintes modalidades e bandeiras: Visa/Mastercard só crédito; Elo débito e crédito. Não é aceita para cartão estrangeiro.

Requisição

<?xml version="1.0"?>
<requisicao-transacao id="1abd5a36-fba5-4a92-9341-7c9e9d44aa1a" versao="1.3.0">
    <dados-ec>
        <numero>xxxxxxxxxx</numero>
        <chave>xxxxxxxxxxxxxxxxxxxxxxxxx</chave>
    </dados-ec>
    <dados-portador>
        <numero>xxxxxxxxxxxxxx</numero>
        <validade>******</validade>
        <indicador>1</indicador>
        <codigo-seguranca>***</codigo-seguranca>
        <nome-portador>NOME DO PORTADOR</nome-portador>
        <cnpj-cpf-portador>12345678901</cnpj-cpf-portador>
        <token/>
        <carteira>
           <tipo>MASTERPASS</tipo>
        </carteira>
    </dados-portador>
    <dados-pedido>
        <numero>xxxxx</numero>
        <valor>1000</valor>
        <moeda>986</moeda>
        <data-hora>2021-11-26T10:00:05</data-hora>
        <descricao>Compra Online</descricao>
        <idioma>PT</idioma>
        <soft-descriptor>CARTEIRA*NOMEPORTADOR</soft-descriptor>
    </dados-pedido>
    <forma-pagamento>
        <bandeira>mastercard</bandeira>
        <produto>1</produto>
        <parcelas>1</parcelas>
    </forma-pagamento>
    <url-retorno>http://www.cielo.com.br</url-retorno>
    <autorizar>3</autorizar>
    <capturar>true</capturar>
    <gerar-token>false</gerar-token>
    <cash-in>true</cash-in>
</requisicao-transacao>

Criando transações

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

<?xml version="1.0" encoding="ISO-8859-1"?>
<requisicao-transacao id="a97ab62a-7956-41ea-b03f-c2e9f612c293" versao="1.2.1">
  <dados-ec>
    <numero>1006993069</numero>
    <chave>25fbb997438630f30b112d033ce2e621b34f3</chave>
  </dados-ec>
  <dados-portador>
    <numero>4084359300407900</numero>
    <validade>201508</validade>
    <indicador>1</indicador>
    <codigo-seguranca>973</codigo-seguranca>
    <token/>
  </dados-portador>
  <dados-pedido>
    <numero>178148599</numero>
    <valor>1000</valor>
    <moeda>986</moeda>
    <data-hora>2011-12-07T11:43:37</data-hora>
    <descricao>[origem:10.50.54.156]</descricao>
    <idioma>PT</idioma>
    <soft-descriptor/>
  </dados-pedido>
  <forma-pagamento>
    <bandeira>visa</bandeira>
    <produto>1</produto>
    <parcelas>1</parcelas>
  </forma-pagamento>
  <url-retorno>http://localhost/lojaexemplo/retorno.jsp</url-retorno>
  <autorizar>3</autorizar>
  <capturar>false</capturar>
  <gerar-token>false</gerar-token>
</requisicao-transacao>

raiz

dados-ec

dados-portador

dados-pedido

forma-pagamento

Fluxos de integração e redirecionamentos

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

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

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

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

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

Tipo de retorno

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

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

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

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

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

As informações mais importantes são:

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

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

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

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

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

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

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

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

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

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

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

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

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

Observações

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

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

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

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

<?xml version="1.0" encoding="ISO-8859-1"?>
<transacao versao="1.3.0" id="5e445904-963e-4fa1-95cd-55ef88c289cc" xmlns="http://ecommerce.cbmp.com.br">
    <tid>10069930690864281001</tid>
    <pan>uv9yI5tkhX9jpuCt+dfrtoSVM4U3gIjvrcwMBfZcadE=</pan>
    <dados-pedido>
        <numero>1739114311</numero>
        <valor>1000</valor>
        <moeda>986</moeda>
        <data-hora>2013-02-18T15:06:27.523-03:00</data-hora>
        <descricao>[origem:172.16.34.66]</descricao>
        <idioma>PT</idioma>
        <taxa-embarque>0</taxa-embarque>
    </dados-pedido>
    <forma-pagamento>
        <bandeira>visa</bandeira>
        <produto>1</produto>
        <parcelas>1</parcelas>
    </forma-pagamento>
    <status>6</status>
    <autenticacao>
        <codigo>6</codigo>
        <mensagem>Transacao sem autenticacao</mensagem>
        <data-hora>2013-02-18T15:06:28.013-03:00</data-hora>
        <valor>1000</valor>
        <eci>7</eci>
    </autenticacao>
    <autorizacao>
        <codigo>6</codigo>
        <mensagem>Transação autorizada</mensagem>
        <data-hora>2013-02-18T15:06:28.807-03:00</data-hora>
        <valor>1000</valor>
        <lr>00</lr>
        <arp>123456</arp>
        <nsu>549928</nsu>
    </autorizacao>
    <captura>
        <codigo>6</codigo>
        <mensagem>Transacao capturada com sucesso</mensagem>
        <data-hora>2013-02-18T15:08:23.031-03:00</data-hora>
        <valor>1000</valor>
    </captura>
</transacao>

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

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

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

Consulta BIN

O Consulta Bin é um serviço de pesquisa de dados do cartão, seja ele de crédito ou débito, que retorna ao estabelecimento informações que permitem validar os dados preenchidos na tela de pagamento. O serviço retorna os seguintes dados sobre o cartão:

• Bandeira do cartão: Nome da Bandeira
• Tipo de cartão: Crédito, Débito ou Múltiplo (Crédito e Débito)
• Nacionalidade do cartão: Estrangeiro ou Nacional
• Cartão Corporativo: Se o cartão é ou não é corporativo
• Banco Emissor: Código e Nome
• Cartão pré-pago:: sim ou não

Essas informações permitem tomar ações no momento do pagamento para melhorar a conversão da loja.

Integração

Requisição

 
<?xml version="7.0" encoding="ISO-8859-1"?>
<requisicao-consulta-bin id="a387cb68-b33a-4113-b7c4-9b7dfde871ec" versao="2.2.0"
    xmlns="http://ecommerce.cbmp.com.br">
    <dados-ec>
        <numero>XXXXXXXXXX
        </numero>
        <chave>XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</chave
    </dados-ec>
    <bin>506708</bin>
</requisicao-consulta-bin>

Retorno

Exemplo XMl de retorno:

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<retorno-consulta-bin id="a387cb68-b33a-4113-b7c4-9b7dfde871ec" versao="2.2.0" xmlns="http://ecommerce.cbmp.com.br">
<bin>506708</bin>
<resultado>
<id>8d4d7aaf898bd43d1057f9627ae81003</id>
<status>00</status>
<dados-bin>
    <bandeira>ELO</bandeira>
    <produto>Crédito</produto>
    <emissor>Informação não disponivel</emissor>
    <cartao-estrangeiro>Não</cartao-estrangeiro>
    <cartao-corporativo>Não</cartao-corporativo>
    <codigo-emissor>950</codigo-emissor>
    <pre-pago>Sim</pre-pago>

</dados-bin>
      </resultado>
</retorno-consulta-bin>

Catálogo de códigos de resposta

Códigos de Autorização LR

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

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

Programa de Retentativa das Bandeiras

O que são retentativas?

Quando uma pessoa tenta fazer uma compra com cartão na sua loja, a transação pode ser negada devido a uma série de fatores. As tentativas seguintes de concluir a transação usando o mesmo cartão é o que chamamos de retentativa.

O que mudou?

Cada bandeira de cartão define os valores que serão cobrados por retentativa. A quantidade de vezes que uma transação pode ser retentada antes da cobrança também varia de acordo com a bandeira.

E no e-commerce?

As bandeiras de cartão definem regras diferentes para transações com cartão presente e não presente, como no caso das vendas feitas pela internet.

Qual o impacto para a loja?

Os e-commerces que não seguirem as regras serão penalizados com a cobrança de tarifas por transações excedidas, de acordo com o programa de cada bandeira.

Visando melhorar a experiência de compra, o mercado de meios de pagamento, em conjunto com a ABECS, promoveu a padronização nos códigos de respostas das transações recusadas feitas por cartão. As tentativas foram classificadas em dois tipos:

• ❌ Irreversível: nunca realizar retentativa
  
  Significa, por exemplo, que o cartão está cancelado para uso, foi perdido ou roubado, há uma fraude confirmada ou a transação não é permitida para aquele produto, indicando que não há circunstâncias nas quais o emissor concederia uma aprovação. Qualquer tentativa de autorização que, após uma recusa irreversível, não tenha alterado nenhum campo da mensageria, não obterá sucesso.
  
  
• ✅ Reversível: permitido realizar retentativa
  
  Significa que o emissor pode aprovar a transação, mas não pode fazê-lo agora, possivelmente devido a um problema do sistema (inoperante) ou falta de limite, suspeita de fraude ou excesso de número de tentativas de digitação da senha. São decisões de recusas temporárias tomadas pelo emissor que podem mudar com o tempo.

As bandeiras Visa, Mastercard, Elo e Hipercard ajustaram suas regras para limitar a quantidade de tentativas de autorização para uma transação negada. Essas mudanças preveem a cobrança de tarifas para o excesso de tentativas. Confira a seguir as regras de cada bandeira.

Mastercard

A bandeira Mastercard possui o programa Transaction Processing Excellence (TPE), que engloba duas categorias:

1. Excessive Attempts: monitora as retentativas de transações negadas nos ambientes de cartão presente e cartão não presente. Válido tanto para códigos de negadas reversíveis quanto irreversíveis.

2. Merchant Advice Code Transaction Excellence (MAC): monitora as retentativas de transações negadas, nos ambientes de cartão não presente e que são irreversíveis. Haverá cobrança somente nos MACs 03 e 21.

1. Excessive Attempts

São cobranças efetuadas quando o estabelecimento comercial excede as regras de retentativas de transações.

A bandeira também realiza o monitoramento para qualquer autorização de valor nominal, aprovada, com estorno subsequente para transações abaixo de 1 unidade de moeda inteira ou o equivalente a US$ 1.

O monitoramento é aplicado para as retentativas de transações de compras negadas e aprovadas, realizadas em ambiente de cartão presente e cartão não presente.

Tabela Excessive Attempts

• Serão consideradas como retentativas todas as transações de pagamento no mesmo cartão, e mesmo número de estabelecimento;
• A Mastercard prorrogou a data de vigência para o dia 01/02/2023 referente as novas regras do programa (Excessive Attempts) antes prevista para início do dia 01/11/2022. Confira as mudanças:

1. O excesso considerado no programa ocorrerá a partir da oitava retentativa dentro do mês de apuração; os valores cobrados sofreram alteração.
2. E a Mastercard também está introduzindo um limite de 35 tentativas negadas no mesmo cartão e mesmo número de estabelecimento por período contínuo de 30 dias. Mesmo se a loja não ultrapassar o limite de sete retentativas no período de 24h, mas ultrapassar a quantidade do limite mensal, a cobrança será aplicada.

Obs: A regra vigente do programa Excessive Attempts é válida até 31/01/2023 (tabela Excessive Attempts), permitindo apenas 10 tentativas de aprovar uma mesma transação (no mesmo cartão, e mesmo número de estabelecimento), e é permitido retentar após 24h.

2. Merchant Advice Code Transaction Excellence (MAC)

São cobranças efetuadas quando o estabelecimento comercial realiza retentativa de envio de autorização para códigos de respostas irreversíveis com um mesmo cartão valido para cartão não presente.

Dentro desse programa de retentativas, há programas que se destinam especificamente ao cenário de “Não tente esta transação novamente”. Para esses casos, a Mastercard identifica as transações com os valores MAC 03 e MAC 21, por exemplo.

O programa MAC comporta alguns valores, porém somente os MACs 03 e 21 possuem uma cobrança específica. Os demais MACs não se enquadram nessa cobrança.

Os outros códigos MAC (01, 02, 04, 24, 25, 26, 27, 28, 29 e 30) não entram no programa de cobrança do MAC mas entram na cobrança do programa Excessive Attempts, caso exceda os limites.

Desde 14/10/2022 a Mastercard introduziu novos códigos MAC (24, 25, 26, 27, 28, 29 e 30) quando um emissor recusa uma transação com o código de resposta 51 (insuficiência de fundos) seguido de um dos MAC da tabela a seguir, para que o comerciante tome a melhor ação.

Tabela com toda relação de MACs

Além disso, alguns códigos de retorno deixarão de ser enviados:

• 04 (Cartão de Captura)
• 14 (Número de cartão inválido)
• 41 (Cartão Perdido)
• 43 (Cartão Roubado)
• 54 (Cartão Expirado)
• 57 (Transação Não Permitida)
• 62 (Cartão Restrito)
• 63 (Violação de Segurança)

Categorização de retornos Mastercard

A Mastercard poderá consolidar alguns códigos de respostas dos emissores, que muitas vezes não indicam ao comerciante se pode ou não retentar, em três códigos de uso exclusivo Mastercard:

• 79 (Ciclo de vida);
• 82 (Política);
• 83 (Fraude/ Segurança).

Os códigos originais serão substituídos pelo Merchant Advice Code (MAC), que acompanharão os códigos 79, 82 e 83 para determinar se a transação pode ou não ser retentada.

Por exemplo:

Programa de retentativas MAC 03 e MAC 21

Forma de apuração:

• Serão consideradas as transações de cartão não presente;
• São consideradas como retentativas todas as transações de pagamento no mesmo cartão e mesmo número de estabelecimento;
• São contabilizadas as retentativas no programa MAC com os valores MAC 03 e MAC 21;
• Valido para qualquer código de resposta;
• O excesso contabilizado no programa ocorrerá a partir da 1ª retentativa dentro do mês de apuração;
• O contador é zerado após o período de 30 dias;
• As retentativas podem ser cobradas nos MACs 03/21 e no Excessive Attempts caso ultrapasse o limite de cada programa;
• Atualmente é aplicado o valor de tarifa de R$1,25 e esse valor será alterado a partir de 01 de janeiro de 2023, como listado a seguir.

Tabela de valores:

Visa

O que é?

Um programa instituído pela bandeira Visa que gera cobranças quando o estabelecimento comercial excede as regras de retentativas.

• Válido para transações com cartão presente e cartão não presente;
• Códigos reversíveis: são permitidas até 15 tentativas de aprovar uma mesma transação (mesmo cartão, mesmo estabelecimento e valor) no período de 30 dias. Após os 30 dias iniciais (a contar da primeira tentativa), qualquer retentativa será cobrada;
• Códigos irreversíveis: é permitido apenas UMA tentativa de aprovar uma mesma transação (mesmo cartão, mesmo estabelecimento), na segunda tentativa será cobrado;
• Após uma transação ser aprovada, o contador é zerado.

Tarifas: Ao ultrapassar os limites de tentativas estabelecidos pela bandeira, haverá uma cobrança de tarifa para cada transação excedente.

• Doméstico: USD 0,10 + 13,83% de imposto;
• Estrangeiro: USD 0,25 + 13,83% de imposto

Regras de autorização já vigentes. A cobrança de tarifas é aplicada desde abril de 2021.

A Visa agrupou os códigos de retorno em quatro categorias:

• Categoria 1: emissor nunca aprovará

Para essa categoria, indica que o cartão foi cancelado ou nunca existiu ou que a negativa é resultado de uma restrição permanente ou condição de erro que impedirá uma aprovação futura.

• Categoria 2: emissor não pode aprovar neste momento

Indicam que a negativa é resultado de uma condição temporária tal como risco de crédito, controles de velocidade do emissor ou outras restrições do cartão que podem permitir uma retentativa da transação ser aprovada. Em alguns casos, a negativa requer uma ação do portador ou emissor para remover a restrição antes que uma aprovação possa ser obtida.

• Categoria 3: qualidade de dados/revisar dados

Quando um erro de dados é identificado pelo emissor essa transação é declinada como consequência. Os estabelecimentos devem revalidar dados de pagamentos antes de retentar. Estabelecimentos e Credenciadores devem monitorar estes códigos de negativas devido a exposição potencial a fraudes.

Atenção: A categoria 3 tem, além dos limites considerados na categoria 2, um limite diferente que é cumulativo. Um estabelecimento pode realizar até 10.000 transações em um período de 30 dias (neste caso considerando apenas o número do estabelecimento e códigos de negadas). Se ultrapassar o limite, todas as transações recusadas por categoria 3 serão tarifadas.

• Categoria 4: códigos de respostas genéricos

A categoria 4 inclui todos os outros códigos de resposta de recusa, muitos dos quais fornecem pouco ou nenhum valor para Adquirentes/Comerciantes como parte de sua estratégia de nova tentativa. O uso do emissor deve permanecer mínimo.

A maioria das condições de recusa tem códigos de resposta descritivos nas Categorias 1, 2 e 3 para indicar o motivo da recusa. No entanto, pode haver circunstâncias em que não haja valor de código de resposta para uma condição de declínio específica. Emissores pode usar outros valores de códigos de resposta definidos nas Especificações Técnicas VisaNet; no entanto, o uso deve permanecer mínimo.

Os emissores devem usar códigos de resposta que reflitam com mais precisão o motivo das recusas. Categorias 1 (o emissor nunca aprovar), 2 (o emissor não pode aprovar neste momento) e 3 (qualidade dos dados) devem ser usados, e os emissores devem limitar o uso de Categoria 4 (Código de Resposta Genérico) para transações onde nenhum outro valor se aplica. A taxa do Código de Resposta Genérico é cobrada para garantir que não mais do que a porcentagem aprovada regionalmente do total de recusas do emissor sejam categorizadas como Categoria 4. Os emissores que excederem o limite definido regionalmente receberão a Taxa de Código de Resposta Genérica por base de transação para cada declínio em excesso do limite definido.

Tabela com as regras e códigos de recusa:

Observação: O código de resposta 14 aparece nas categorias 1 e 3 porém a contabilização é a seguinte:

• Na categoria 1 o EC é tarifado a partir da 2ª tentativa para o (mesmo estabelecimento e mesmo cartão) não permitido retentar.

• Na categoria 3 compõe o grupo de códigos para contabilização das 10.001 transações, após o EC atingir 10.000 retentativas com o este grupo de códigos, qualquer transação será contabilizada independente do cartão.

Exemplo: Tivemos 10.000 transações negadas em um EC com os códigos de categoria 3, se a transação 10.001 for no código 14 ou em qualquer código do grupo de categoria 3 ele será tarifado independente do cartão.

Elo

O que é?

Trata-se de um programa instituído pela bandeira ELO que gera cobranças quando o estabelecimento comercial excede as regras de retentativas de transações com um mesmo cartão.

Formas de Apuração

• Retentativas: todas transações de pagamento no mesmo cartão, validade, valor e Merchant ID (MID) dentro de 30 dias;
• Códigos contabilizados: todos de negativas​;
• Excesso: a partir da 16ª retentativa no mês​*;
• Tarifa: R$ 0,80 (oitenta centavos) por retentativa, a partir da 16ª;
• Cobrança: a cobrança só será feita em casos de recorrência, sendo assim, o estabelecimento tem que estar no programa por pelo menos dois meses consecutivos;
• Contabilização do excesso: é baseada nos controles internos da Elo. 1º ao último dia corrido do mês.

Tabela de cobrança de retentativas para a bandeira Elo

A tabela a seguir exemplifica como será feita a cobrança pela bandeira:

Relação de códigos de recusa Elo:

Os códigos de respostas abaixo estão listados conforme manual de autorização da bandeira.

Hipercard

O que é?

Cobranças efetuadas quando um Estabelecimento Comercial excede as regras de retentativas de transações negadas com um mesmo cartão, mesma data ou período mensal, mesmo valor e mesmo número de Estabelecimento Comercial, conforme abaixo:

Regras:

1. Transações ASI: são transações Account Status Inquiry, ou seja, são as transações efetuadas para consultar o status de um cartão (verificar se está ativo). Para esse fim, não devem ser usadas transações financeiras e sim transações específicas;
2. Tentativas por dia: considerar para efeito do programa de Retentativas da Hipercard de 00h00 a 23h59;
3. Mês de referência: considerar para efeito do programa de Retentativas da Hipercard dia 01 a 30 ou 31 do mês em que ocorreu a transação. A cobrança será enviada após o fechamento do mês subsequente;
4. Os códigos de transações consideradas irreversíveis pelo emissor foram categorizados pela indústria de pagamentos e autorregulação da ABECS, por meio do Normativo 21 vigente. Veja os Códigos de retorno (ABECS);
5. Os códigos não citados no manual da ABECS são considerados como reversíveis.

Demais bandeiras

• Códigos reversíveis: serão permitidas novas retentativas para o mesmo cliente e cartão. Não há limite e período pré-estabelecido;

Importante: antes de realizar uma nova tentativa, siga a orientação recebida na resposta da transação negada.

• Códigos Irreversíveis: não serão permitidas autorizações para o mesmo cartão ou estabelecimento, depois de receber 1ª resposta de recusa do emissor.

Códigos de retorno ABECS

Para acessar o programa de retentativa das bandeira acesse esse Link

A Associação Brasileira das Empresas de Cartão de Crédito e Serviços (ABECS) estabelece a partir do dia 15 de Julho de 2020 a padronização do código de retorno das autorizações de vendas recusadas tanto para as soluções pagamento do mundo físico e e-commerce do mercado brasileiro.

Essa medida normativa busca trazer benefícios para todo o mercado de pagamentos, proporcionando maior transparência no entendimento do motivo de recusa das transações, além de possibilitar maior assertividade na adoção de estratégias de retentativas de vendas.

A Cielo informa seus clientes que está preparada para processar as transações seguindo esse novo padrão do mercado, segue abaixo a tabela de códigos padronizados pela ABECS.

Outros códigos de retorno

Códigos de Erros

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

Tabela de erros de integração

Status das transações

ECI

Operações e configurações

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

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

Autorização Direta

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

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

Tradicional

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

Autorização Recorrente

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

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

Autorização recorrente com Cartão

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

Renova Fácil

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

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

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

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

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

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

Transação com Token

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

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

Retorno

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

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

Autorização Direta via Token

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

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

Autorização recorrente com Token

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

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

Renova Fácil com Token

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

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

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

Geração de Token

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

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

Credencial Armazenado - Card On File

O portador do cartão poderá permitir que os dados de seu cartão, sejam armazenados de forma segura, para transações futuras no Estabelecimento Comercial.

Abaixo seguem as situações para identificar se é a primeira transação ou subsequente, através da TAG primeira transação:

• Situação 1: - HÁ armazenamento de dados do cartão e É primeira transação.

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

• Situação 2: - HÁ armazenamento de dados do cartão e NÃO É primeira transação.

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

• Situação 3: - NÃO HÁ armazenamento de dados do cartão, o estabelecimento simplesmente não envia esta tag.

Requisição

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

Resposta

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

Tokenização de Bandeira

Clientes que fazem tokenização do cartão junto com as bandeiras poderão enviar as informações para a Cielo no fluxo transacional.

Requisição

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

Resposta

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

Funcionalidades Agregadas

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

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

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

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

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

Permite que o lojista envie um texto (Soft Descriptor)

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

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

Captura Automática

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

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

Taxa de embarque

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

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

AVS (Address Verification Service)

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

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

Consulta

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

Consulta por TID

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

Requisição

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

Consulta por Número do Pedido

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

Requisição

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

Captura

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

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

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

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

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

Captura Total e Parcial

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

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

Retorno

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

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

Cancelamento

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

Para as solicitações de cancelamento da mesma transação, é necessário aguardar um período de 5 segundos entre uma solicitação e outra, para que seja realizada a consulta de saldo, reserva do valor na agenda financeira e sensibilizado o saldo. Evitando assim duplicidade de cancelamento. Esta regra vale para cancelamentos totais e/ou parciais.

Para identificar que as solicitações de cancelamento são da mesma transação, consideramos o número do EC, número da autorização de cancelamento, data da venda, valor da venda e NSU.

Importante salientar que para realizar qualquer solicitação de cancelamento, é necessário que o estabelecimento possua saldo suficiente na transação/em agenda

Cancelamento Total e Parcial

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

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

Retorno

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

Processamento em lote

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

O que é o Processamento em Lote

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

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

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

Integração

Regras

Processamento em Lote deverá seguir as seguintes regras:

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

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

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

Exemplo: ECOMM_1006993069_02_20121002_0000000086.xml

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

Mensagens

Mensagem de Upload de Arquivo

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

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

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

Mensagem de Solicitação de Download de Retorno

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

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

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

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

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

Anexo

Tipos de operações do transacional online

Códigos de resposta

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

Arquivo ECM-LOTE.XSD

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

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


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

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



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

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

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

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

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

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

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

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

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

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

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

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

Testes e Homologação

Endpoint

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

Dados para testes

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

Chave de testes

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

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

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

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

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

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

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

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

Considerações Finais

Regras para leitura do cartão na loja

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

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

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

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

Certificado digital

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

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

Google Chrome:

Mozilla Firefox:

Internet Explorer:

Programa Verified by Visa (Visa)

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

Programa Secure Code (Mastercard)

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