Sobre o Checkout Cielo

O Checkout Cielo é uma solução que agrega vários serviços de processamento de pagamento, no qual o consumidor é direcionado para uma página de pagamento online segura da Cielo. A página de pagamentos Cielo proporciona um alto nível de confiança, seguindo as normas de segurança PCI.

O grande diferencial do Checkout Cielo é a gama de serviços agregados em uma tela transacional segura e com apenas uma integração técnica via API REST.

O Checkout possui as seguintes Funcionalidades:

O Checkout Cielo é uma funcionalidade indicada para:

• Sites com Carrinhos de compra: quando houver um “carrinho de compras” a ser enviado, ou seja, no caso do consumidor navegar pelo site e escolher 1 ou mais produtos a fim de finalizar a compra.
• Vendas via Redes sociais: Com a capacidade de gerar um link ou QR Code para levar o comprador a tela transacional, o Checkout é indicado para realizar vendas via redes sociais de modo simplificado, sem a necessidade de integração técnica.

Meios de pagamento do Checkout Cielo

A versão atual do Checkout Cielo possui suporte aos seguintes meios de pagamento:

Cartão de Crédito

OBS: Limite máximo de parcelas do Checkout Cielo é 12X.

Cartão de Débito

Boleto

Débito Online

Pré-requisitos para Integração

O Checkout Cielo possui uma lista de requisitos básicos para que o processo de integração seja bem sucedido. Abaixo listamos pontos que devem estar prontos antes da integração:

1. O cadastro da loja deve estar ativo junto à Cielo, possuindo ao menos um tipo de PLANO de pagamento atrelado a conta.

2. Deve-se definir um timeout adequado nas requisições HTTP à Cielo; recomendamos 30 segundos.

3. 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. Veja a seção Certificado Extended Validation para mais informações.

4. O Checkout funciona de forma eficiente apenas nos navegadores suportados:

OBS: Para que compradores e lojistas obtenham a melhor experiência do Checkout Cielo, recomendamos baixar a última versão dos navegadores mencionados acima.

Confira este site para visualizar as últimas versões dos navegadores.

Observação: navegadores antigos podem negar acesso ao Checkout Cielo e alguns recursos não funcionarão como desejado. Navegadores mais recentes também oferecem melhores recursos de encriptação e privacidade.

Se um recurso ainda não funcionar como esperado:

• Tente utilizar outro navegador como solução temporária para o problema.
• Se você utiliza o Internet Explorer, tente desativar o modo de compatibilidade.

Se você já tentou essas soluções, mas continua a ter problemas, entre em contato conosco pelo Suporte Cielo e forneça as seguintes informações:

• Uma explicação geral do problema.
• O navegador e a versão que estão sendo utilizados.
• O sistema operacional e a versão utilizada no computador.
• Uma captura de tela do problema.

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:

1º Passo

Salvar os três 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

2º 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:

3º 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”

4º Passo

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

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

5º 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 “cieloecommerce.cielo.com.br.crt, clique em “Abrir” e em seguida “Avançar”.

6º Passo

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

7º Passo

Clique em “Concluir”.

8º 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.

9º Passo

Repita o mesmo procedimento para os 3 arquivos enviados.

Integrando o Checkout Cielo

Nesta documentação estão descritas todas as funcionalidades da integração da API Checkout Cielo, os parâmetros técnicos e principalmente os códigos de exemplos para facilitar o seu desenvolvimento.

Existem duas maneiras de realizar a integração:

Fluxo de integração

Durante a integração com o Checkout Cielo, uma seguencia de troca de informações e redirecionamentos serão executados para que a uma transação seja criada e executada.

Veja o fluxo abaixo:

Fluxo de integração Checkout Cielo - Diagrama sequêncial

Fluxo de integração Checkout Cielo - Fluxograma

Após o portador do cartão (consumidor) selecionar suas compras e apertar o botão “Comprar” de uma loja já integrada ao Checkout Cielo, o fluxo nesta ordem:

1. A API da Cielo retorna o CheckoutURL, que é a URL da tela transacional montada com base nos dados enviados pelo Lojista/Botão.
2. A loja redireciona o cliente para a URL retornada pela Cielo. A tela apresentada é parte do Ambiente de pagamento seguro Cielo.
3. O portador escolhe: Meio de pagamento, tipo de frete e endereço de entrega na tela transacional
4. O Checkout Cielo redireciona o cliente para a URL de Retorno escolhida pela loja, configurada no Backoffice Checkout Cielo ou enviada pela integração via API.
5. Se a loja possui uma URL de notificação, ela será notificada sobre a situação da transação.
6. A loja avisa ao cliente que o processo foi concluído e que ele receberá mais informações sobre a compra e o pagamento por e-mail.e
7. A loja processa o pedido de compra utilizando os dados do POST de notificação e, se a transação estiver autorizada, libera o pedido.

OBS: O Checkout Cielo não notifica os compradores a respeito do status de compra, apenas ao lojista. Isso ocorre pois permite ao lojista decidir quando e como informar aos seus consumidores sobre o prazo de entrega e processo de envio

Modo de teste do Checkout Cielo

O modo de teste Checkout Cielo é uma ferramenta que permite testar a integração do seu site com a plataforma. Com o modo teste, você pode realizar transações a medida que evolui com a integração e consegue simular cenários para testar diferentes meios de pagamento.

Ativação do Modo de Teste

O modo de teste pode ser ativado na aba Configurações, onde existe um caixa de seleção, que quando marcada, habilitará o modo de teste do Checkout Cielo. O modo somente se iniciará quando a seleção for salva.

Quando a opção for salva, uma tarja vermelha será exibida na parte superior da tela. Ela será exibida em todas as telas do Backoffice Cielo Checkout e na tela transacional do Checkout Cielo.

Essa tarja indica que a sua loja Checkout Cielo está agora operando em ambiente de teste, ou seja, toda a transação realizada nesse modo será considerada como teste.

Backoffice	Transacional

Como transacionar no Modo de teste

A realização de transações no modo de teste ocorre de forma normal. As informações da transação são enviadas via POST ou API, utilizando os parâmetros como descrito no tópico Integração por API, entretanto, os meios de pagamentos a serem usados serão meios simulados.

Para realizar transações de teste com diferentes meios de pagamento, siga as seguintes regras:

A - Transações com Cartão de crédito:

Para testar cartões de crédito é necessário que dois dados importantes sejam definidos, o status da autorização do cartão e o retorno da analise de fraude.

Status da Autorização do Cartão de Crédito

Exemplo: 5404434242930100 = Autorizado

B - Boleto Bancário

Basta realizar o processo de compra normalmente sem nenhuma alteração no procedimento. O boleto gerado no modo de teste sempre será um boleto simulado.

C - Debito online

É necessário informa o status da transação de Debito online para que seja retornado o status desejado. Esse processo ocorre como no antifraude do cartão de crédito descrito acima, com a alteração do nome do comprador.

Status do Débito

• Exemplo: Status não Autorizado.
• Nome do Cliente: Maria Pereira

D - Transações de teste

Todas as transações realizadas no modo de teste serão exibidas como transações normais na aba Pedidos do Checkout Cielo, entretanto, elas serão marcadas como transações de teste e não serão contabilizadas em conjunto com as transações realizadas fora do ambiente de teste.

Essas transações terão o símbolo de teste as diferenciando de suas outras transações. Elas podem ser capturadas ou canceladas utilizando os mesmos procedimentos das transações reais.

SDKs e POSTMAN

O Checkout Cielo possui uma coleção POSTMAN de testes exclusiva com todos os parâmetros e opções descritas neste manual. Basta acessar nosso Tutorial para obter informações sobre a utilização da ferramenta.

No postman é possível criar exemplos de sua integração em:

• PHP
• RUBY
• C#
• JAVA
• PYTHON
• SHELL

Integração por API

Este tipo de integração deve ser usada sempre que houver um “carrinho de compras” a ser enviado, ou seja, no caso do consumidor navegar pelo site e escolher 1 ou mais produtos para adicionar a um carrinho e depois então finalizar a venda.

Se você não possui um carrinho de compras implementado, veja a seção de Integração via botão Checkout Cielo.

Abaixo, é demonstrado como o fluxo de compra ocorre na integração via API:

Criando o Carrinho

Na integração via API, a tela transacional é “montada” com bases em dados enviados que formam um Carrinho de compras. Esses dados são separados nos seguintes “nós principais”:

Após o envio dos dados do carrinho, o Checkout enviará um Response contendo um LINK para a tela de pagamento

IMPORTANTE: Uma chamada a API Checkout NÃO CRIA UMA TRANSAÇÃO. O Link retornado é apenas uma “pré-ordem” indicando que uma tela transacional está pronta para ser utilizada. A Transação é criada apenas quando o comprador clica em “FINALIZAR”

Request

Endpoint é a URL para onde as requisições com os dados do carrinho serão enviadas. Todas as requisições deverão ser enviadas utilizando o método HTTP POST, para o endpoint:

Produção https://cieloecommerce.cielo.com.br/api/public/v1/orders.

Exemplo de uma requisição

{  
   "OrderNumber":"Pedido01",
   "SoftDescriptor":"Exemplo",
   "Cart":{  
      "Discount":{  
         "Type":"Percent",
         "Value":00
      },
      "Items":[  
         {  
            "Name":"Produto01",
            "Description":"ProdutoExemplo01",
            "UnitPrice":100,
            "Quantity":1,
            "Type":"Asset",
            "Sku":"ABC001",
            "Weight":500
         },
        ]
   },
   "Shipping":{  
      "SourceZipCode":"20020080",
      "TargetZipCode":"21911130",
      "Type":"FixedAmount",
      "Services":[  
         {  
            "Name":"Motoboy",
            "Price":1,
            "Deadline":15,
            "Carrier":null
         },
         {  
            "Name":"UPS Express",
            "Price":1,
            "Deadline":2,
            "Carrier":null
         }
      ],
      "Address":{  
         "Street":"Rua Cambui",
         "Number":"92",
         "Complement":"Apto 201",
         "District":"Freguesia",
         "City":"Rio de Janeiro",
         "State":"RJ"
      }
   },
   "Payment":{  
      "BoletoDiscount":15,
      "DebitDiscount":10,
      "Installments":null,
      "MaxNumberOfInstallments": null
   },
   "Customer":{  
      "Identity":"84261300206",
      "FullName":"Test de Test",
      "Email":"test@cielo.com.br",
      "Phone":"21987654321"
   },
   "Settings":null
}

Header/Cabeçalho

Cabeçalho e Autenticação - Todas as requisições enviadas para a Cielo deverão ser autenticadas pela loja. A autenticação consiste no envio do MerchantId, que é o identificador único da loja fornecido pela Cielo após a afiliação da loja. A autenticação da loja deverá ser feita através do envio do campo de cabeçalho HTTP MerchantId, como ilustrado abaixo e ao lado:

Body - Detalhado

Responses

Devido ao seu fluxo de venda ser dividido em duas etapas, sendo a primeira, a criação da tela transacional e a segunda, a finalização do pagamento; O Checkout possui duas respostas para uma transação:

• Response - Tela transacional - É o Response retornado com dados para enviar o comprador para a tela transacional
• Response - Transação Finalizada - Contém dados sobre o resultado da transação, após o comprador clica em “Finalizar” na tela transacional. É retornado apenas via Notificação

Resultado/Status da transação: Para obter o retorno do status da transação, é necessário definir uma URL de NOTIFICAÇÃO. Veja a sessão de notificação para maiores informações.

Response - Tela transacional

Existem apenas duas opções de resposta na integração da API: Sucesso / Erro

Sucesso - Em caso de sucesso, o response será o conteúdo do Request mais o Link que direciona a tela transacional

{
    "Settings": {
        "CheckoutUrl": "https://cieloecommerce.cielo.com.br/transacional/order/index?id=123",
        "Profile": "CheckoutCielo",
        "Version": 1
    }
}

Erro - Em caso de erro, a mensagem abaixo será retornada.

{
    "message":"An error has occurred."
}

Importante - O Checkout Cielo não possui erros numerados, apenas uma mensagem genérica. Veja a sessão “Identificando erros de Integração” para maiores informações

Funcionalidades Adicionais

Nos itens a seguir, será explicado o comportamento de algumas das funcionalidades da integração via API. Essas funcionalidades possuem regras especificas para utilização e não estão disponíveis na integração via Botão.

• Tipos de “Desconto”
• Tipos de “Frete”

Tipos de “Desconto”

O Checkout Cielo permite que o lojista aplique descontos específicos tanto para o carrinho quanto para meios de pagamento. Os descontos disponíveis no Checkout Cielo são:

OBS: Descontos podem ser enviados na API ou definidos no Backoffice. Caso um Valor de desconto seja enviado na API, esse será o valor considerado, mesmo que o Backoffice possua outro valor registrado

Carrinho

Para enviar um Desconto sobre o Carrinho basta enviar o nó abaixo dentro do nó Cart

      {
       "Discount": {  
         "Type":"Percent",
         "Value":00
       },
      }

Abaixo, como o efeito do desconto são apresentados no Carrinho:

Percentual	Valor

Boleto & Débito Online

Para enviar um Desconto sobre o Boleto e Débito online basta enviar dentro do nó Payment os campos abaixo:

      {
      "Payment": {  
        "BoletoDiscount":15,
        "DebitDiscount":10,
        "FirstInstallmentDiscount":90
        },
      }

Abaixo, como o efeito do desconto são apresentados no Carrinho:

Tela transacional

Tipos de “Frete”

O Checkout cielo possui diferentes tipos de frete.

Abaixo, como cada opção é demonstrada na tela transacional

Tipo de frete	Transacional
FixedAmount
Free
WithoutShippingPickUp
WithoutShipping
Correios

OBS: As opções para múltiplos fretes na categoria Correios devem ser selecionadas dentro do Backoffice Cielo.

Os nós que formam as informações de frete abaixo:

• Shipping - Nó base. É obrigatório na integração via API. Ele define os tipos de frete a serem utilizados

Shipping.Address - Informações de endereço de entrega. Não obrigatório no contrato da API, mas obrigatório na tela transacional. Sugerimos que esses dados sejam enviados, se ja foram recolhidos dentro do ambiente da loja.

Shipping.Services

O Frete Correios pode ser calculado de 2 maneiras:

• Frete com Volume - Utiliza a API dos correios, mas exige que a loja envie as dimensões do pacote a ser enviado com as mercadorias
• Frete sem Volume - Utiliza a API dos correios, mas considera apenas o peso do carrinho como base de cálculo para a entrega.

Para utilizar o frete volumétrico, basta enviar o nó Shipping.Measures, seguindo as regras de integração via API REST.

Shipping.Measures

Para realizar o cálculo de frete via Correios é necessário respeitar as medidas definidas pelo contrato utilizado pelo lojista. Para maiores informações sobre as dimensões e pesos permitidos, sugerimos que valide o contrato da loja no link abaixo:

Limites e dimensões para entregas do correio

Identificando Erros de integração

Devido a estrutura do checkout Cielo, onde o comprador é redirecionado para um ambiente separado para completa a transação, existem possibilidades de erros e falhas de integração em diferentes momentos do fluxo de pagamento. Durante a integração é importante Há dois tipos de erro que poderão ocorrer durante o processo de integração com o Checkout Cielo. São eles:

Caso algum erro ocorra após a finalização da transação, entre em contato com o Suporte Cielo.

Integração por BOTÃO

Integração via Botão, QR CODE ou LINK é um método de compra usada sempre que não houver um “carrinho de compras” em sua loja. Esse tipo de integração é realizado via o cadastro de um conjunto de itens a ser vendido on backoffice do Checkout Cielo.

O botão gera um do 3 tipos diferentes de métodos de acesso a mesma tela transacional:

Método	Nome	Descrição
	Botão	É um código HTML que ao ser colado em um site, vai direcionar o comprador a tela transacional - Ideal para uso em hotSites ou E-mail Marketing
	QRCODE	Código interpretável por Smartphones e Tablets - Ideal para uso em Marketing impressos ou Digital
http://bit.ly/2tRkSxZ	LINK	é um link compartilhável, ideal para uso em Redes Sociais ou Messengers Mobile

Este modelo de integração é utilizado para:

• Associar uma compra rápida direta a um produto como uma promoção numa homepage pulando a etapa do carrinho.
• Enviar um e-mail marketing, ou uma cobrança via e-mail.
• Adicionar o botão (HTML) referente ao produto/serviço a ser comprado/pago.
• Realizar envio de pagamentos por aplicativos mobile
• Sempre que se deseja disponibilizar uma venda rápida.

Para utilizar este recurso, é necessário cadastrar o produto que se deseja vender, suas informações, e depois simplesmente copiar o código fonte gerado para este botão. A inclusão dos produtos é feita dentro do Backoffice Cielo Checkout, no menu de Produtos/Cadastrar Produto.

Características do Botão

Cada botão possui um código único que só permite comprar aquele determinado produto nas condições de preço e frete cadastrado. Portanto, um fraudador não consegue alterar nenhuma destas informações na hora de submeter à compra, pois o Checkout Cielo vai buscar todos os dados do produto no cadastro do Backoffice Cielo Checkout, e valerão os dados do cadastro.

Abaixo, o fluxo de pagamento via Botão:

Criando o Botão

Para utilizar este recurso, é necessário cadastrar o produto que se deseja vender, suas informações, e depois simplesmente copiar o código fonte gerado para este botão. A inclusão dos produtos é feita dentro do Backoffice Cielo Checkout, no menu de Produtos/Cadastrar Produto.

Tela de Cadastro:

Botão Cadastrado:

Abaixo a listagem de itens que devem ser cadastrados para a criação do botão:

Exemplo de Botão:

Abaixo é possível ver como o cadastro de um botão gera os 3 métodos de para acesso a tela transacional.

• Botão - Será criado um código HTML como o abaixo:

<form method='post' action='https://cieloecommerce.cielo.com.br/transactional/Checkout/BuyNow' target='blank'>
    <input type='hidden' name='id' value=00000000-0000-0000-000000000000/><input type='image' name='submit' alt='Comprar' src='https://cieloecommerce.cielo.com.br /BackOffice/Contenthttps://developercielo.github.io/images/botao_comprar_3.jpg' />
</form>

Exemplo de um botão Funcional:

• QR CODE E LINK - O link e o QRCODE tem o mesmo comportamento do botão, levando a mesma tela transacional.

Adicionando o botão na sua página, você deve copiar o código HTML do botão criado e inclui-lo no HTML de seu site, conforme o exemplo abaixo.

Cada botão possui um código único que só permite comprar aquele determinado produto nas condições de preço e frete cadastrado. Portanto, um fraudador não consegue alterar nenhuma destas informações na hora de submeter a compra, pois o Checkout Cielo vai buscar todos os dados do produto no cadastro do Backoffice Cielo Checkout, e valerão os dados do cadastro.

Fluxos Meios de pagamento

Cartão de Crédito

O Checkout Cielo permite a utilização de Cartões de Crédito das principais bandeiras nacionais e internacionais. Esse meio de pagamento é liberado automaticamente junto a afiliação de Cielo, podendo ser utilizado inicialmente com a integração Checkout.

Transações de cartão de crédito serão incluídas no Backoffice Cielo Checkout como PENDENTE, AUTORIZADO, PAGO, NEGADO, EXPIRADO OU CHARGEBACK dependendo do resultado da autorização junto ao Banco.

Cartão de Crédito Ordem de Status:

Atenção - Cartões Internacionais: O Checkout Cielo aceita cartões emitidos fora do Brasil, entretanto esses cartões não possuem a capacidade de pagar vendas parceladas. Essa é uma limitação imposta pelo banco emissor.

Atenção - TRANSAÇÕES EXPIRADAS: Por padrão, lojas Checkout Cielo possuem 15 dias para realizarem a captura da transação de Crédito. Se não capturadas, essas transações serão PERDIDAs.

Análise de Fraude

Transações de crédito “AUTORIZADAS” serão enviadas para análise da ferramenta de antifraude. Todas as transações classificadas como alto risco serão automaticamente canceladas, sem exceção. O Antifraude possui o conceito de Status e SubStatus, onde o primeiro representa o nível de risco que uma transação possui de ser uma fraude, e o segundo, uma informação adicional sobre a transação. A análise indicará um grau de RISCO, especificado pelo Status, para a venda em questão.

Esse grau de risco é o que deve guiar a decisão do lojista de capturar ou cancelar a venda.

A analise será apresentada no “Detalhes do Pedido”, como abaixo:

Você pode visualizar o status do antifraude acessando o detalhe da compra, na aba Pedidos e clicando no (+)

Cartão de Débito

O Checkout Cielo permite a utilização de Cartões de débito MasterCard e Visa. Esse meio de pagamento é liberado automaticamente junto a afiliação de Cielo, podendo ser utilizado inicialmente com a integração Checkout.

Bancos Suportados:

Ao acessar a tela transacional, o comprador obterá pelo pagamento via Cartão de débito, e será redirecionado ao ambiente bancário para Autenticação e Autorização.

Transações de cartão de débito serão incluídas no Backoffice Cielo Checkout como PENDENTE, PAGO, NÃO AUTORIZADO ou NÃO FINALIZADO, dependendo do resultado da autorização junto ao Banco.

Cartão de Débito - Ordem de Status

1. Pendente - Status original. A transação está ocorrendo, esperando resposta do banco para envio do comprador ao ambiente de autenticação
2. Não Finalizado - Status intermediário. Neste ponto o Checkout Cielo espera a confirmação do Banco sobre o status da autenticação e transação. Caso o comprador abandone o ambiente do banco, o status não se altera.
3. Pago - Comprador finalizou o pagamento com o cartão de débito com sucesso.
4. Não Autorizado - O Comprador não apresentava saldo em conta para finalizar a transação.

OBS: A opção Cancelar dentro do backoffice, vai modificar o status da transação de PAGO/NÃO PAGO para CANCELADO, mas não terá efeito sobre a movimentação bancaria. Caberá ao lojista retornar o valor ao comprador

Boleto

O Checkout Cielo permite a utilização de Boletos do Bradesco (Carteira 26 e SPS) e Banco do Brasil (Carteira 17). Esse meio de pagamento precisa ser cadastrado pelo Suporte Cielo para que seja disponibilizado no Backoffice Checkout.

Bancos Suportados:

Ao acessar a tela transacional, o comprador obterá pelo pagamento via Boleto.

Transações de boleto serão incluídas no Backoffice Cielo Checkout como NÃO FINALIZADO ou PAGO. Diferentemente de outros meios de pagamento, o boleto não possui atualização de Status. Caberá ao Lojista acessar o Backoffice e modificar o status do boleto manualmente.

Boleto - Ordem de Status

1. Não Finalizado - Status inicial. O Boleto é gerado, e ainda é valido. Como o Checkout não acessa o ambiente do banco para identificar o pagamento do boleto, esse status continuará efetivo até que o lojista entre no backoffice o atualize.
2. Pago - Comprador finalizou o pagamento com o cartão de débito com sucesso.

OBS: A opção Cancelar dentro do backoffice, vai modificar o status da transação de PAGO/NÃO FINALIZADO para CANCELADO, mas não terá efeito sobre a movimentação bancaria. Caberá ao lojista retornar o valor ao comprador

Débito Online

O Checkout Cielo permite a utilização de Débito Online (Transferência entre contas bancarias) para compradores que possuam contas nos bancos Bradesco e Banco do Brasil. Esse meio de pagamento é liberado via cadastro junto ao Suporte Cielo.

Ao acessar a tela transacional, o comprador obterá pelo pagamento via Débito online, e será redirecionado ao ambiente bancário para Autenticação e Autorização.

Transações de Débito online serão incluídos no Backoffice Cielo Checkout como PENDENTE, PAGO, NÃO AUTORIZADO ou NÃO FINALIZADO, dependendo do resultado da autorização junto ao Banco.

Débito online - Ordem de Status

• Pendente - Status original. A transação está ocorrendo, esperando resposta do banco para envio do comprador ao ambiente de autenticação
• Não Finalizado - Status intermediário. Neste ponto o Checkout Cielo espera a confirmação do Banco sobre o status da autenticação e transação. Caso o comprador abandone o ambiente do banco, o status não se altera.
• Pago - Comprador finalizou o pagamento do débito com sucesso.
• Não Autorizado - O Comprador não apresentava saldo em conta para finalizar a transação.

OBS: A opção Cancelar dentro do backoffice, vai modificar o status da transação de PAGO/NÃO PAGO para CANCELADO, mas não terá efeito sobre a movimentação bancaria. Caberá ao lojista retornar o valor ao comprador

Notificações de Pagamento

O processo de notificação transacional no Checkout Cielo ocorre via a inclusão de uma URL para onde serão direcionados dados das transações realizadas na plataforma. Vale destacar que o Checkout realiza a notificação somente quando uma transação é considerada finalizada ou seja, o comprador preencheu todos os dados da tela de pagamento e clicou em “Finalizar”.

Tipos de notificação

O Checkout Cielo possui dois tipos de notificações que o lojista pode utilizar de acordo com suas necessidades:

Para utilizar ambos os modelos, o lojista necessitará acessar o Backoffice cielo e configurar tanto a URL de NOTIFICAÇÃO quando a URL de MUDANÇA de STATUS.

Tipos de URL de Notificação

O Checkout possui 3 tipos de URL que podem impactar o processo de notificação.

OBS: Caso uma URL de retorno seja enviada vai API, ela terá prioridade sobre a URL cadastrada no Backoffice / Na integração Checkout Cielo via Botão, só é possível usar a opção de URL de retorno via backoffice.

Características das URLs

Todas as 3 URLs devem possuir as seguintes características:

• Devem ser URLs estáticas
• Devem possuir menos de 255 caracteres
• Caracteres especiais não são suportados

Configurando as URLs

1. Basta acessar dentro do Backoffice as Abas Configurações
2. Em Configurações da Loja, Vá a sessão de Pagamentos
3. Cadastre as URLS e escolhe o tipo de Notificação desejado

Notificação: POST

A notificação via POST é baseada no envio de um POST HTTP quando uma transação é realizada. Ela é realizada em duas etapas:

1. POST de NOTIFICAÇÃO - Ocorre quando a transação é finalizada. Esse POST possui todos os dados do pedido, incluindo o STATUS inicial da transação.
2. POST de MUDANÇA DE STATUS - Ocorre quando uma transação possui seu STATUS alterado - EX: “Autorizado” > > > “Pago”

Este fluxo é utilizado por lojas que ainda não realizam transações via API.

Abaixo o Fluxo de uma Notificação POST

Retorno aguardado para o envio da notificação: HttpStatus = 200 (OK) - Post recebido e processado com sucesso

IMPORTANTE Se a URL de Notificação cadastrada retornar algum erro/estiver indisponível, serão realizadas *3 novas tentativas, com intervalo de 1 hora entre cada POST.

Caso o POST não seja recebido, é possível reenvia-lo manualmente, basta acessar o pedido em questão pelo Backoffice e clicar no Ícone de envio:

Veja a descrição dos itens de notificação na sessão “Conteúdo do POST de NOTIFICAÇÃO”

Notificação: JSON

A notificação vai JSON é um método mais seguro e flexível para o lojista de realizar uma consulta no Chekcout Cielo. Essa modalidade de notificação é baseada em um POST JSON, onde o lojista recebe credenciais para que uma consulta (GET) possa ser realizado junto a base de dados Checkout Cielo.

Ela é realizada em duas etapas:

1. POST de NOTIFICAÇÃO - Ocorre quando a transação é finalizada. Possui as Credenciais necessárias consultas transacionais.
2. CONSULTA TRANSACIONAL - Com as credenciais de consulta, o lojista busca dados da venda junto ao Checkout Cielo

Na Notificação de JSON, não há diferença entre o POST de Notificação e Mudança de Status. Sempre que algo ocorrer na transação, o lojista receberá um POST de Notificação

Abaixo o Fluxo de uma Notificação JSON (Criação da transação + Mudança de status)

Conteúdo do POST de NOTIFICAÇÃO JSON:

Exemplo de uma consulta:

REQUEST

curl
--request GET https://cieloecommerce.cielo.com.br/api/public/v1/orders/{merchantId}/{merchantOrderNumber}"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
--verbose

RESPONSE

{
    "order_number": "Pedido01",
    "amount": 101,
    "discount_amount": 0,
    "checkout_cielo_order_number": "65930e7460bd4a849502ed14d7be6c03",
    "created_date": "12-09-2017 14:38:56",
    "customer_name": "Test Test",
    "customer_phone": "21987654321",
    "customer_identity": "84261300206",
    "customer_email": "test@cielo.com.br",
    "shipping_type": 1,
    "shipping_name": "Motoboy",
    "shipping_price": 1,
    "shipping_address_zipcode": "21911130",
    "shipping_address_district": "Freguesia",
    "shipping_address_city": "Rio de Janeiro",
    "shipping_address_state": "RJ",
    "shipping_address_line1": "Rua Cambui",
    "shipping_address_line2": "Apto 201",
    "shipping_address_number": "92",
    "payment_method_type": 1,
    "payment_method_brand": 1,
    "payment_maskedcreditcard": "471612******7044",
    "payment_installments": 1,
    "payment_status": 3,
    "tid": "10447480686J51OH8BPB",
    "test_transaction": "False"
}

Veja a descrição dos itens de notificação na sessão “Conteúdo do POST de NOTIFICAÇÃO”

Retorno aguardado para o envio da notificação: HttpStatus = 200 (OK) - Post recebido e processado com sucesso

IMPORTANTE Se a URL de Notificação cadastrada retornar algum erro/estiver indisponível, serão realizadas *3 novas tentativas, com intervalo de 1 hora entre cada POST.

Caso o POST não seja recebido, é possível reenvia-lo manualmente, basta acessar o pedido em questão pelo Backoffice e clicar no Ícone de envio:

Conteúdo da Notificação

Tanto na Notificação via POST HTTP ou POST JSON, o conteúdo dos dados retornados é o mesmo. Abaixo são descritos todos os campos retornados, assim como suas definições e tamanhos:

Conteúdo do POST de NOTIFICAÇÃO:

Tipos de productID

Payment_status

O Checkout possui um Status próprios, diferente do SITE CIELO ou da API Cielo ecommerce. Veja abaixo a lista completa.

Obs: Para consultas de pedido, o campo payment.status será retornado no formato texto, sempre em inglês (coluna Transaction Status).

Payment_antifrauderesult

O Antifraude possui o conceito de Status e SubStatus, onde o primeiro representa o nível de risco que uma transação possui de ser uma fraude, e o segundo, uma informação adicional sobre a transação.

Payment_method_type

O Checkout permite apenas um tipo de Boleto ou Débito Online por lojista, sendo assim não é retornado se o método usado foi Bradesco ou Banco do Brasil, pois apenas um deles estará ativado na afiliação.

OBS: Para consultas o Type é retornado no campo Payment.Type e vem preenchida com o valor literal (Description)

Payment_method_brand

OBS: Para consultas a Brand é retornado no campo Payment.Brand e vem preenchida com o valor literal.

Payment_method_bank

Shipping_type

Mudança de status

Parcelamentos do Checkout Cielo

Tipo de Parcelamento

O Checkout Cielo permite que o lojista realize transações de crédito parceladas em até 12 vezes. Existem dois métodos de parcelamento:

• Parcelamento via backoffice - é o método padrão de parcelamento do Checkout. Cada bandeira possui uma configuração de parcelamento até 12X. O Valor do Carrinho (Produtos + Frete) é dividido igualmente pelo número de parcelas.
• Parcelamento via API - O Lojista limita o número de parcelas a serem apresentadas no backoffice

OBS: O Checkout é limitado a parcelamentos de 12X, mesmo que sua afiliação Cielo suporte valores superiores. Caso o valor apresentando em seu backoffice seja menor que 12, entre em contato com o Suporte Cielo e verifique a configuração de sua Afiliação.

Parcelamento via backoffice

Neste modo, o lojista controla o limite máximo de parcelas que a loja realizará pelo Backoffice Checkout. O Valor das parcelas é definido acessando a aba Configurações e alterando a sessão Pagamentos

OBS: O Check Box deve estar marcado para que o meio de pagamento seja exibido na tela transacional.

Características

• Disponível nas integrações do Checkout Cielo via API ou Botão;
• O valor total dos itens do carrinho é somado e dividido pela quantidade de parcelas do lojista;
• O valor da compra é sempre o mesmo, independentemente da quantidade de parcelas escolhida pelo comprador (Não há cobrança de Juros);
• O valor do frete é somado ao valor do parcelamento;
• A opção “à vista” sempre está disponível ao comprador.
• Todas as transações possuirão as mesmas opções de parcelamento.

Parcelamento via API

Nesta opção, o lojista pode configurar a quantidade de parcelas por venda, especificado via request da API no momento de envio da transação. O Checkout realiza o cálculo das parcelas considerando valor total e limite parcelas enviadas via API.

ATENÇÃO: Nesta opção de parcelamento, o número de parcelas desejadas deve ser inferior a quantidade que está cadastrada no backoffice Checkout.

Características

• O lojista envia a quantidade máxima de parcelas que deseja exibir ao comprador.
• O valor do frete é somado ao valor do parcelamento.

O Parcelamento via API é realizado enviando o campo MaxNumberOfInstallments dentro do nó Payment. Isso forçará o Checkout a recalcular o valor do parcelamento. Abaixo, um exemplo do Nó

"Payment": {
  "MaxNumberOfInstallments": 3
}

Recorrência do Checkout Cielo

A Recorrência é um processo de agendamento automático de transações de crédito, ou seja, é uma transação que se repetirá automaticamente, sem a necessidade do comprador acessar a tela transacional, de acordo com as regras definidas no momento do agendamento.

Transações recorrentes são ideais para modelos de negócios que envolvam o conceito de assinatura, plano ou mensalidade na sua forma de cobrança. Alguns exemplos de negócios são:

• Escolas
• Academias
• Editoras
• Serviços de hospedagem

Diferença entre transações recorrentes e parceladas:

Recorrência por API

Uma transação de recorrência no Checkout Cielo possui duas configurações: Intervalo e Data de encerramento.

• Intervalo – padrão de repetição e intervalo de tempo entre cada transação. Esse intervalo temporal entre as transações podem ser: Mensal, Bimestral, Trimestral, Semestral e Anual.
• Data de encerramento – Data que o processo de recorrência deixa de ocorrer.

"Payment": {
        "RecurrentPayment": {
            "Interval": "Monthly",
            "EndDate": "2018-12-31"
        }

Payment.RecurrentPayment

Os dados do cartão de crédito do comprador ficam armazenados de forma segura dentro do Checkout Cielo, permitindo sua reutilização em uma transação recorrente. Esses dados não são acessados pelo lojista e essa inteligência é controlada pelo Checkout Cielo.

Exceto o objeto Payment que contém um novo elemento específico para a recorrência chamado RecurrentPayment, todos os outros objetos são iguais à integração com o Carrinho.

Request

{
    "OrderNumber": "12344",
    "SoftDescriptor": "Nome que aparecerá na fatura",
    "Cart": {
        "Discount": {
            "Type": "Percent",
            "Value": 10
        },
        "Items": [
            {
                "Name": "Nome do produto",
                "Description": "Descrição do produto",
                "UnitPrice": 100,
                "Quantity": 2,
                "Type": "Asset",
                "Sku": "Sku do item no carrinho",
                "Weight": 200
            }
        ]
    },
    "Shipping": {
        "Type": "Correios",
        "SourceZipCode": "14400000",
        "TargetZipCode": "11000000",
        "Address": {
            "Street": "Endereço de entrega",
            "Number": "123",
            "Complement": "",
            "District": "Bairro da entrega",
            "City": "Cidade de entrega",
            "State": "SP"
        },
        "Services": [
            {
                "Name": "Serviço de frete",
                "Price": 123,
                "Deadline": 15
            }
        ]
    },
    "Payment": {
        "BoletoDiscount": 0,
        "DebitDiscount": 0,
        "RecurrentPayment": {
            "Interval": "Monthly",
            "EndDate": "2015-12-31"
        }
    },
    "Customer": {
        "Identity": 11111111111,
        "FullName": "Fulano Comprador da Silva",
        "Email": "fulano@email.com",
        "Phone": "11999999999"
    },
}

Exemplo: Bem Físico

Se o tipo de produto for Bem Físico, a API obriga o envio do tipo de frete. Se no contrato técnico existir o nó da recorrência, fica obrigatório o tipo WithoutShipping, caso contrário, a seguinte resposta será apresentada:

{
    "message": "The request is invalid.",
    "modelState": {
        "[Shipping.Type]": [
            "[Shipping.Type] pedidos com recorrência devem possuir o Shipping.Type 'WithoutShipping'."
        ]
    }
}

IMPORTANTE: A Recorrência é criada apenas se a transação for AUTORIZADA. Independente de captura ou não, uma vez autorizada, o processo de recorrência se inicia.

Recorrência por Botão

Uma maneira de realizar a recorrência dentro do Checkout é criar um botão recorrente.

Basta cadastrar o produto, incluindo um intervalo de cobrança e uma data para encerramento (Opcional), como no exemplo abaixo:

ATENÇÃO: Caso um botão seja utilizado após a “Data final” cadastrada, a transação apresentará um erro exibindo Oppss na tela transacional. A Data pode ser editada na tela de edição do botão dentro de “Detalhes do Produto”

Retentativa de Recorrências

Caso uma das transações da recorrência não seja autorizada, o Checkout Cielo executa a retentativa automaticamente, o envio de uma nova transação, considerando:

• Intervalo de tempo entre as tentativas: 4 dias
• Quantidade de retentativas: 4 (quatro), uma por dia, por 4 dias corridos a partir do dia seguinte da transação original não autorizada.

OBS: Esse processo visa manter obter uma resposta positiva do processo de autorização, impedindo o lojista de perder a venda. O Processo de retentativa gera pedidos duplicados dentro do Backoffice, pois o pedido original, negado, será apresentado na lista de Pedidos, junto com a nova transação autorizada

ATENÇÃO: A regra da retentativa não pode ser modificada pelo lojista.

Consultando transações

As transações de Recorrência ficam disponíveis no Backoffice Checkout Cielo como as outras vendas de sua loja na aba “PEDIDOS” (veja imagem abaixo).

A primeira transação da recorrência é uma transação normal, seguindo as regras e preferências definidas pelo lojista no Backoffice.

ATENÇÃO: O valor e data de cobrança das transações recorrentes serão sempre os mesmos da transação inicial. O agendamento passa a funcionar automaticamente a partir da data em que a primeira transação for autorizada.

Esta tela mostra a data que a 1° transação da recorrência foi autorizada e deverá ser capturada manualmente. As demais transações da recorrência sempre serão capturadas automaticamente, independente se primeira transação foi capturada ou cancelada. Se o Cliente tiver configurado Captura automática, a captura da recorrência também será automática.

ATENÇÃO: Somente a 1° transação é submetida a análise do antifraude

Cancelamento de Recorrência no Checkout Cielo.

O cancelamento da recorrência ocorre dentro do Backoffice do Checkout Cielo, também na aba “PEDIDOS”. Basta:

1. Acessar uma transação de recorrência (marcada com o símbolo “Recorrente”)
2. Entrar em Detalhes (o símbolo de “+”)

Tela de detalhes da Recorrência

Na tela acima, há duas opções de Cancelamento pelos botões:

• Cancelar – Cancela a transação, sem efetuar o cancelamento das futuras transações de recorrência.
• Cancelar Recorrência - Cancela o agendamento de futuras transações, encerrando a recorrência. Não cancela a transação atual nem as que já ocorreram. Essas necessitam ser canceladas manualmente.

ATENÇÃO:

• A Recorrência ocorre somente para Cartões de crédito e para produtos tipo “SERVIÇO” e “BENS DIGITAIS”.
• A Recorrência é iniciada no momento da AUTORIZAÇAO, NÃO NA CAPTURA. Se a recorrência não tiver uma data para ser finalizada, ela se repetirá automaticamente até ser cancelada manualmente.
• Sua afiliação Cielo deve ser habilitada para transacionar sem CVV ou Em recorrência, do contrário, todas as transações recorrentes serão negadas.

Edição da Recorrência

O Checkout Cielo permite que o lojista modifique 3 dados da recorrência:

• Ativação - Uma recorrência pode ser ativada ou cancelada.
• Intervalo - É possivel modificar o intervalo de execução.
• Dia de ocorrência - É possivel modificar o dia de execução da transação recorrente.

A atualização é feita exclusivamente via o Backoffice Cielo. Acesso o Tutorial do Backoffice Checkout Cielo para mais informações.

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

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 E-commerce.
• Email: cieloecommerce@cielo.com.br