Integração API Checkout Cielo

Redirecionando para https://docs.cielo.com.br/link/docs/sobre-o-checkout-cielo ...

As documentações do Checkout Cielo estão em um novo portal

Acesse o novo portal de desenvolvedores E-commerce docs.cielo.com.br.

Atenção: O conteúdo desta página está sendo descontinuado e não receberá atualizações a partir de 14/08/2024. Visite a nova documentação em docs.cielo.br.

Este manual irá guiar o desenvolvedor na integração com a API do Checkout Cielo. Ao integrar a API do Checkout, você vai conseguir:

• Configurar a sua loja e personalizar sua página de pagamento;
• Criar uma página de pagamento via API;
• Consultar, capturar e cancelar transações via API;
• Receber notificações de pagamentos.

Não é desenvolvedor? Você pode usar o Checkout pelo site Cielo ou pelo app Cielo Gestão. Saiba mais neste tutorial.

Sobre o Checkout Cielo

O Checkout Cielo é indicado para sites com carrinhos de compra, ou seja, quando o consumidor navega pelo site e escolhe um ou mais produtos a fim de finalizar a compra. Ao clicar em Comprar, o consumidor é redirecionado para uma página de pagamento online segura da Cielo.

O Checkout Cielo é uma solução que agrega vários serviços de processamento de pagamento e gera uma página de pagamentos que 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 página de pagamento segura e com apenas uma integração técnica via API REST.

O Checkout possui as seguintes funcionalidades:

Meios de pagamento aceitos no Checkout Cielo

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

Observação: O limite máximo de parcelas do Checkout Cielo é 12 parcelas.

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. A seguir listamos pontos que devem estar prontos antes da integração:

1. O cadastro da loja deve estar ativo junto à Cielo;
2. É necessário 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. Veja a seção Certificado Extended Validation para mais informações;
4. Recomendamos o uso dos navegadores Chrome e Edge para web e Safari, Chrome e Samsung Internet para mobile, todos sempre em suas versões mais atualizadas.

Fluxo da API Checkout Cielo

Na API do Checkout Cielo, a loja envia uma requisição de criação da tela de checkout e a API retorna uma URL para acesso à página de pagamento, chamada CheckoutUrl. Confira mais detalhes sobre o funcionamento da API no fluxo a seguir:

1. A pessoa titular do cartão (comprador) escolhe os produtos na loja integrada ao Checkout Cielo e clica em Comprar;
2. A loja envia a requisição de criação da página de pagamento para a API Checkout Cielo;
3. A API Checkout Cielo retorna o CheckoutUrl, que é a URL da página de pagamento montada com base nos dados enviados pela loja (como dados do comprador, dos produtos, da entrega e outros);
4. A loja redireciona o comprador para a URL retornada pela Cielo (página de pagamento). A tela apresentada é parte do ambiente de pagamento seguro Cielo;
5. O comprador escolhe o meio de pagamento, tipo de frete e endereço de entrega na página de pagamento;
6. O Checkout Cielo redireciona o cliente para a URL de Retorno escolhida pela loja (caso a loja tenha configurado uma URL de Retorno no site Cielo);
7. A loja será notificada sobre a situação da transação (caso a loja tenha configurado uma URL de notificação no site Cielo);
8. A loja processa o pedido de compra utilizando os dados da notificação e, se a transação estiver autorizada, libera o pedido.

Importante: O Checkout Cielo não notifica os compradores a respeito do status da compra. O Checkout Cielo notifica apenas a loja quando há alguma alteração no status do pagamento, permitindo assim que a loja decida quando e como informar aos seus compradores sobre o prazo de entrega e processo de envio. Para receber notificações, é necessário configurar ao menos um tipo de URL de notificação nas Configurações da Loja.

Endpoints

Os endpoints para integração com o Checkout Cielo são apresentados na tabela a seguir:

Importante: A API do Checkout não possui sandbox, mas você pode criar páginas de pagamento de teste ativando o Modo Teste no site Cielo.

Autenticação Cielo OAUTH

O Cielo OAUTH é um processo de autenticação das APIs Cielo relacionadas ao e-commerce. O Cielo OAUTH utiliza como segurança o protocolo OAUTH2 , no qual é necessário primeiro obter um token de acesso utlizando suas credenciais e, posteriormente, enviá-lo à API de Controle Transacional.

A autenticação só é necessária para as operações de consulta, captura e cancelamento.

Para utilizar o Cielo OAUTH são necessárias as seguintes credenciais:

Para gerar o ClientID e o ClientSecret, consulte o tópico de Obtendo as Credenciais, a seguir.

Obtendo as credenciais

Para obter as credenciais ClientId e ClientSecret, siga os passos a seguir:

1. Após receber o nº de estabelecimento (EC) com a habilitação para o Checkout, acesse o site Cielo e faça o login;
2. Vá para a aba Ecommerce > Checkout > Configurações > Dados Cadastrais;
3. Na seção Contato técnico, preencha com os dados de contato da pessoa responsável por receber as chaves da sua loja. ATENÇÃO: apenas coloque os dados da pessoa que realmente pode ter acesso às chaves da sua loja, que são informações sigilosas de cada estabelecimento;
4. Clique em Gerar Credenciais de Acesso às APIs;
5. O contato técnico receberá um e-mail com as credenciais.

Obtendo o token de acesso

Para obter acesso a serviços Cielo que utilizam o Cielo Oauth, será necessário obter um token de acesso, conforme os passos abaixo:

1. Concatene o ClientId e o ClientSecret, **ClientId:ClientSecret**;
2. Codifique o resultado em Base64;
3. Envie a requisição de criação do token, utilizando o método HTTP POST.

Exemplo da Concatenação

Requisição

A requisição dever ser enviada apenas no header.

x-www-form-urlencoded
--header "Authorization: Basic {base64}"  
--header "Content-Type: application/x-www-form-urlencoded"  
grant_type=client_credentials

Resposta

A resposta retornará o access_token, que deverá ser usado nas requisições da API de Controle Transacional, para as operações de consulta, captura e cancelamento.

{
  "access_token":
    "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjbGllbnRfbmFtZSI6Ik1ldUNoZWNrb3V0IE1hc3RlciBLZXkiLCJjbGllbnRfaWQiOiJjODlmZGasdasdasdmUyLTRlNzctODA2YS02ZDc1Y2QzOTdkYWMiLCJzY29wZXMiOiJ7XCJTY29wZVwiOlwiQ2hlY2tvdXRBcGlcIixcIkNsYWltc1wiOltdfSIsInJvbGUiOiJasdasdasd291dEFwaSIsImlzc47I6Imh0dHBzOi8vYXV0aGhvbasdasdnJhc3BhZy5jb20uYnIiLCJhdWQiOiJVVlF4Y1VBMmNTSjFma1EzSVVFbk9pSTNkbTl0ZmasdsadQjVKVVV1UVdnPSIsImV4cCI6MTQ5Nzk5NjY3NywibmJmIjoxNDk3OTEwMjc3fQ.ozj4xnH9PA3dji-ARPSbI7Nakn9dw5I8w6myBRkF-uA",
  "token_type": "bearer",
  "expires_in": 1199
}

O token retornado (access_token) deverá ser utilizado em toda requisição de consulta, captura e cancelamento como uma chave de autorização. O access_token possui uma validade de 20 minutos (1200 segundos) e é necessário gerar um novo token toda vez que a validade expirar.

Início Rápido

Para iniciar a sua integração com a API do Checkout Cielo, você vai precisar:

1. Solicitar o nº de estabelecimento (EC) para o Checkout Cielo;
2. Definir as configurações da loja (personalização da página, escolha dos meios de pagamento e contrato com os Correios*, se houver);
3. Configurar uma URL de notificação e de mudança de status para a sua loja;
4. Instalar o certificado Extended Validation;
5. Enviar a primeira requisição de criação de página de pagamento;
6. Quando houver uma tentativa de pagamento no Checkout Cielo, você receberá uma notificação** com todos os dados preenchidos na página de pagamento;
7. Se a transação mudar de status, você receberá uma notificação** de mudança de status;
8. Para efetuar testes, use o Modo de Teste do Checkout Cielo.

*Indisponível por tempo indeterminado.

**Desde que tenha configurado a URL de notificação.

Configurações da loja

Antes das configurações, você precisa habilitar o Checkout Cielo para a sua loja.

Habilitando o nº de estabelecimento (EC) para o Checkout

• Se você ainda não é cliente Cielo ou se só usa a maquininha, acesse o site Cielo para habilitar nº do estabelecimento (EC) para o Checkout;
• Se você já é cliente Cielo E-commerce, entre em contato com seu gestor comercial ou com o Suporte Cielo.

Configurando a sua loja

Acesse as Configurações da loja no site Cielo

Vá para o site Cielo e faça login. Acesse E-commerce > Checkout > Configurações > Configurações da loja.

1. Personalize a aparência da página de pagamento

Insira a imagem do logo da sua loja e escolha uma cor de fundo. Clique em Salvar.

2. Configure o envio de e-mail de finalização para o comprador

Se não desejar que seu cliente final receba um e-mail de finalização do pedido após o pagamento, desabilite essa opção. Depois, clique em Salvar.

3. Defina os meios de pagamento desejados

Selecione os meios de pagamento que gostaria de disponibilizar aos seus clientes. Para cartão de crédito, escolha também a quantidade máxima de parcelas permitidas. Depois, clique em Salvar.

A quantidade de parcelas escolhida por meio de pagamento deve ser a mesma que consta em seu cadastro da Cielo. Consulte o Suporte E-commerce em caso de dúvidas.

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 da 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. Veja os possíveis status de transações de cartão de crédito na tabela Payment_status.

As transações de cartão de crédito precisam ser capturadas de forma automática ou manual - depende do que escolher no passo 5. Configure a captura e Antifraude.

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.

Cartão de débito

O Checkout Cielo permite a utilização de cartões de débito Mastercard, Visa e Elo. 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 débito serão incluídas no site Cielo como Pago, Não Autorizado ou Não Finalizado, dependendo do resultado da autorização junto ao banco.

Os status de cartão de débito são:

Pix

O meio de pagamento Pix está disponível para estabelecimentos do tipo CNPJ por meio de dois provedores, Cielo ou Bradesco.

Para habilitar o Pix Bradesco, entre em contato com o suporte.

Habilitando o Pix no portal Cielo

Para usar o Pix, o seu cadastro deve estar habilitado com o meio de pagamento Pix. Para confirmar a habilitação, acesse o portal Cielo e clique em Meu Cadastro > Autorizações > Pix.

Caso o Pix não esteja habilitado em seu cadastro, será apresentada a tela de adesão caso o seu estabelecimento (EC) seja elegível; após concluir o processo de adesão do Pix, já será possível usar o Pix no Checkout Cielo.

Boleto

O Checkout Cielo permite a utilização de boletos do Bradesco e Banco do Brasil. Para disponibilizar o boleto como meio de pagamento, solicite habilitação ao Suporte E-commerce.

A quantidade de parcelas escolhida por meio de pagamento deve ser a mesma que consta em seu cadastro da Cielo. Consulte o Suporte E-commerce em caso de dúvidas.

As transações de boleto serão incluídas no site Cielo como Não Finalizado ou Pago. Diferentemente de outros meios de pagamento, o boleto não possui atualização de status. A loja deverá acessar o Backoffice site Cielo e modificar o status do boleto manualmente.

Os status de boleto são:

QR Code Pay

O QR Code Pay Cielo permite o pagamento através de qualquer carteira digital. Quando o comprador seleciona o QR Code Pay na página de pagamento do Checkout Cielo e clica em Finalizar compra, o Checkout apresenta um QR Code para ser escaneado pelo comprador usando a carteira digital de sua preferência.

4. Configure as URLs de retorno, notificação e mudança de status da sua loja

Você deverá preencher as URLs de retorno, notificação e mudança de status. As URLs devem ser criadas e definidas pelo seu estabelecimento. Depois, clique em Salvar.

• URL de Retorno: após finalizar o pagamento, o comprador pode ser redirecionado para uma página definida web pela loja. Nenhum dado é trocado ou enviado para essa URL e sua configuração é opcional;
• URL de Notificação: corresponde à notificação de finalização da transação. É a URL pela qual a sua loja irá receber a notificação com todos os dados do carrinho quando a transação é finalizada;
• URL de Mudança de Status: corresponde à notificação de mudança de status. É a URL pela qual a sua loja irá receber a notificação quando um pedido tiver seu status alterado. A notificação de mudança de status não contém dados do carrinho, apenas dados de identificação do pedido.

5. Configure a captura e Antifraude

Uma transação de cartão de crédito é enviada para a autorização da Cielo (adquirente) e, em seguida, será submetida à análise de fraude. Em seguida, de acordo com o resultado da análise de fraude, a transação poderá ser capturada automaticamente ou manualmente.

Ao acessar as configurações da sua loja, procure a sessão Antifraude e captura automática. Selecione a opção desejada:

Se a análise de fraude classificar a transação como Alto Risco ela será cancelada automaticamente. Não será possível fazer a captura manual.

Análise de Fraude

Transações de crédito autorizadas serão enviadas para análise de fraude. Todas as transações classificadas como alto risco serão automaticamente canceladas, sem exceção.

Além dos status da tabela acima, é possível que o Antifraude retorne o status N/A. O status N/A pode retornar nas seguintes situações:

• Quando a transação é autenticada pelo banco - não é passível de análise pelo Antifraude;
• Quando o meio de pagamento não é passível de análise pelo Antifraude como cartões de débito, boleto e Pix;
• Quando é uma transação de crédito recorrente posterior a transação de agendamento. Somente o Agendamento é analisado;
• Quando a venda de cartão de crédito foi negada - não é passível de análise pelo Antifraude.

No site Cielo, a análise será apresentada em Detalhes do Pedido:

Você pode visualizar o status do Antifraude acessando os detalhes da compra, na aba Pedidos e clicando em +.

6. Configure as opções de frete dos Correios

Se a sua loja trabalha com a entrega de produtos físicos (aqueles que precisam de frete) usando os Correios, informe seu login e senha dos Correios e selecione os serviços desejados, como os tipos de Sedex e PAC.

Se a sua loja trabalha com materiais digitais, serviços ou pagamentos, ou seja, vendas que não precisam de frete, pule esta etapa.

Também é possível usar outros serviços de frete contratados pela loja. Nesse caso, envie o nó Shipping.Services na criação da página de pagamento. Saiba mais em Definindo o frete

Configurações padrão

Caso você não preencha as Configurações da Loja, o Checkout irá considerar o seguinte padrão:

• A opção de envio de e-mail ao portador estará ativada;
• A opção de aceitar cartões internacionais estará ativada;
• O valor mínimo da parcela será de R$5,00;
• Os meios de pagamento crédito e débito terão 12 parcelas habilitadas (se o seu cadastro Cielo permitir);
• O meio de pagamento débito estará habilitado;
• O meio de pagamento QR Code Crédito terá uma parcela habilitada;
• O boleto não terá valor mínimo ou desconto definido (zerado);
• A opção Sempre fazer Captura Automática só estará habilitada para transações que não são consideradas de alto risco;
• O login de frete dos Correios estará desabilitado.

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
• 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
• 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.

Modo Teste

Por se tratar de uma chamada não financeira, a API do Checkout não possui um sandbox para testar a criação de páginas de pagamento. As páginas de pagamento devem ser criadas a partir de um cadastro de produção. O credenciamento pode ser feito através do site Cielo ou por meio de uma solicitação do gestor comercial do estabelecimento.

Os testes financeiros podem ser executados a partir da ativação do modo teste nas configurações da sua loja.

Ativando o Modo Teste

O modo de teste pode ser ativado na aba Configurações, ao habilitar a caixa de seleção do Modo Teste. O modo teste somente se iniciará quando a seleção for salva.

Após salvar, uma tarja vermelha será exibida na parte superior da tela. Ela será exibida em todas as telas do Checkout.

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

Transações de teste

Todas as transações realizadas no modo de teste serão exibidas como transações normais na aba Pedidos, 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.

IMPORTANTE:

• Ao liberar sua loja para a realização de vendas para seus clientes, certifique-se de que o Modo Teste está desabilitado;
  
• As transações realizadas no Modo Teste poderão ser finalizadas normalmente, mas não serão descontadas do cartão do cliente e não poderão ser transferidas para o ambiente de venda padrão.

Como transacionar no modo teste

Após ativar o modo teste, a realização de transações ocorre de forma normal. A criação da página de pagamento pode ser feita usando os mesmos parâmetros do ambiente de produção, 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:

Cartão de crédito ou débito

Para testar cartões de crédito ou débito é necessário usar um cartão que siga o algoritmo de Luhn e cujo número final corresponda ao status desejado da autorização do cartão (veja detalhes na tabela a seguir).

Status da autorização do cartão de crédito ou débito

Exemplo: 5404434242930100 = Autorizado

Boleto

Para testar transações de boleto, realize o processo de compra normalmente sem nenhuma alteração no procedimento. O boleto gerado no modo de teste sempre será um boleto simulado.

Criando a página de pagamento

Na integração via API, a página de pagamento é 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á uma resposta contendo um link para a página de pagamento no campo CheckoutUrl.

Importante: A requisição de criação da página de pagamento não cria uma transação. A URL retornada (CheckoutUrl) é apenas uma “pré-ordem” indicando que a página de pagamento está pronta para ser utilizada. A transação é criada apenas quando o comprador clica em Finalizar na tela do Checkout.

Requisição

Confira um exemplo de requisição de criação da página de pagamento no Checkout Cielo.

Parâmetros no cabeçalho (header)

Todas as requisições enviadas para a Cielo deverão ser autenticadas pela loja. A autenticação para a criação da página de pagamento consiste no envio do MerchantId no header da requisição:

{
  "OrderNumber": "Pedido01",
  "SoftDescriptor": "Nomefantasia",
  "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,
    "Installments": null,
    "MaxNumberOfInstallments": null
  },
  "Customer": {
    "Identity": "84261300206",
    "FullName": "Test de Test",
    "Email": "test@cielo.com.br",
    "Phone": "21987654321"
  },
  "Settings": null
}

Parâmetros no corpo (body)

IMPORTANTE: O número de identificação do pedido (OrderNumber) não sofre alteração ao longo do fluxo transacional mas um número adicional pode ser gerado para o pedido e utilizado durante a transação. Esse número só será diferente em caso de adequação a regras da adquirente (que seguem abaixo) ou em caso de números de identificação do pedido (OrderNumber) repetidos em menos de 24 horas.

Para que o seu número de pedido seja enviado na transação até o extrato para fins de conciliação, siga os seguintes padrões de formatação:

• Campo: string;
• Tamanho mínimo: 1;
• Tamanho máximo: 20;
• Permitido: letras (a-z, A-Z) e números (0-9);
• Não permitido: símbolos e caracteres especiais, inclusive espaços em branco;
• Não repetir em menos de 24 (vinte e quatro) horas.

*Não é obrigatório, mas recomendamos enviar.

Veja mais informações sobre o nó Shipping em Definindo o frete.

Resposta

Existem apenas duas opções de resposta na integração da API: sucesso ou erro.

Importante: A requisição de criação da página de pagamento não cria uma transação, mas sim a URl da página de pagamento (CheckoutUrl). A resposta de sucesso ou erro se refere a criação da página de pagamento e não tem relação com a transação.

✅ Sucesso: em caso de sucesso, a resposta será o conteúdo da requisição mais o link que direciona a tela transacional (CheckoutUrl), detacada no exemplo a seguir:

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

❌ Erro: em caso de erro, a API retornará a seguinte mensagem:

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

Criando pagamento parcelado

O Checkout Cielo permite que o lojista realize transações de crédito parceladas em até 12 vezes.

Importante: O Checkout é limitado a parcelamentos em até 12 vezes, mesmo que sua afiliação Cielo suporte valores superiores. Caso o valor apresentado nas Configurações da loja no site Cielo seja menor que 12, entre em contato com o Suporte Cielo e verifique a configuração de sua Afiliação.

Nesta opção, a loja pode configurar a quantidade de parcelas por venda. O Checkout realiza o cálculo das parcelas considerando valor total e limite de parcelas enviadas via API.

Atenção: O número de parcelas desejadas deve ser inferior a quantidade que está cadastrada nas Configurações da loja no site Cielo.

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
}

Aplicando descontos

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

Observação: Você pode aplicar descontos via API ou site Cielo. Caso um valor de desconto seja enviado na API, esse será o valor considerado, mesmo que o site Cielo possua outro valor registrado.

Desconto no carrinho

Para enviar um desconto sobre o carrinho basta enviar o nó Discount dentro do nó Cart:

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

Desconto por meio de pagamento

Para enviar um desconto sobre o boleto e/ou cartão de crédito à vista envie dentro do nó Payment o campo correspondente:

• BoletoDiscount para boleto;
• FirstInstallmentDiscount para cartão de crédito à vista.

Exemplo

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

Definindo o frete

O Checkout Cielo permite definir cinco opções de frete no parâmetro Shipping.Type.

Observação: As opções para múltiplos fretes na categoria Correios devem ser selecionadas dentro das Configurações da Loja no site Cielo.

Confira 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 sugerimos que esses dados sejam enviados se já foram recolhidos dentro do ambiente da loja. Se não foram recolhidos, a página de pagamento exibirá os campos de endereço para preenchimento pelo comprador.

*Não é obrigatório, mas recomendamos enviar.

• Shipping.Services: usado para frete fixo, como serviços de frete contratados pela loja.

Cálculo do frete dos Correios

O cálculo do frete é feito pela API dos Correios e pode ser de dois tipos:

• Frete com volume: exige que a loja informe as dimensões do pacote que será enviado com as mercadorias;
• Frete sem volume: considera apenas o peso do carrinho como base de cálculo para a entrega.

Para usar o frete com volume, envie o nó Shipping.Measures, seguindo as regras de integração via API REST.

• Shipping.Measures: indica as medidas do pacote.

Para realizar o cálculo de frete via Correios é necessário respeitar as medidas definidas pelo contrato utilizado pelo lojista. Para mais informações sobre as dimensões e pesos permitidos, sugerimos que valide o contrato da loja em Termo de Condições de Prestação de Serviços de Encomendas Nacionais dos Correios

Recorrência

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.

Caso uma das transações não seja autorizada, o Checkout Cielo executa a retentativa automaticamente; para mais detalhes sobre a retentativa automática, veja a seção Retentativa de Recorrências.

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, como:

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

A transação recorrente é diferente de uma transação parcelada. Na transação recorrente, o limite do cartão do comprador é comprometido pelo valor da assinatura no período escolhido, ou seja, se for mensal, só será cobrado o valor da mensalidade no cartão do comprador.

• Assinatura de seguro no valor de R$ 100,00 e com cobrança mensal por um ano: será cobrado R$ 100,00 por mês.
  

Na transação parcelada, o valor total da venda afetará o limite do cartão de crédito do comprador:

• Venda de uma geladeira no valor de R$ 2000,00 parcelado em 10x de R$ 200,00: o valor total da compra (R$ 2000,00) – afetará o limite do cartão do comprador, mas na fatura será cobrado apenas R$ 200,00 por mês.

Criando pagamento recorrente

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 na 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.

Requisição

{
  "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 material físico (Cart.Items.Type = “Asset”), a API obriga o envio do tipo de frete (Shipping.Type).

Se no contrato técnico existir o nó da recorrência, é obrigatório enviar 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.

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: quatro dias;
• Quantidade de retentativas: quatro retentativas, uma por dia, por quatro dias corridos a partir do dia seguinte da transação original não autorizada.

Observação: Esse processo visa 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.

É possível consultar e cancelar transações recorrentes no site Cielo.

Alterando dados da Recorrência

O lojista pode alterar dados da recorrência gerada após a criação do pagamento. Confira quais dados é possível alterar:

• Intervalo: intervalo de execução;
• Dia da recorrência: dia de execução da transação recorrente;
• Data da próxima cobrança: data em que a próxima cobrança será realizada, seguindo a configuração de intervalo configurada e o dia da recorrência;
• Valor da recorrência: valor da cobrança recorrente no cartão do cliente;
• Data final da recorrência: data em que a recorrência é desativada.
  

Essas alteração podem ser feitas por dois canais. Confira abaixo quais são e as respectivas orientações:

• Site Cielo (alteração manual): Acesse o Tutorial do Backoffice Checkout Cielo para mais informações.
• API do Checkout (alteração integrada): siga os passos a seguir para enviar requisições de edição de recorrência de forma integrada pela API do Checkout Cielo.

Alteração Integrada

Para alterar dados de uma recorrêcia usando a API do Checkout Cielo, basta enviar uma requisição com as informações a serem alteradas. Confira um exemplo dessa requisição.

Requisição

Parâmetros no cabeçalho (header)

• Authorization: Bearer {access_token}
• Content-type: application/json

{ 
  "PagadorRecurrentPaymentId": "0207CE76-8144-48DC-8B17-876465BC3A6D", 
  "EndDate": "2030-12-31", 
  "Interval": 1, 
  "NextPaymentDate": "2024-12-31", 
  "Amount": "33333.33", 
  "Day": "31" 
} 

Parâmentros no corpo (body)

Resposta

HTTP Status: 200 - OK

{ 
" Recurrent Payment - {id} Updated Successfully" 
}

Consultando uma Recorrência

Para consultar os dados de uma recorrência e as transações ligadas a ela, é necessário usar o ID de recorrência enviado após a criação de uma recorrência.

A consulta deve ser feita enviando o access_token como autenticação.

Requisição

Parâmetros no cabeçalho (header)

• Authorization: Bearer {access_token}
• Content-type: application/json

Resposta

{ 

    "$id": "1", 

    "id": 202, 

    "pagadorRecurrentPaymentId": "0207ce76-8144-48dc-8b17-876465bc3a6d", 

    "recurrentPaymentStatus": 1, 

    "recurrentPaymentStatusEnum": 1, 

    "isRecurrentPaymentExpired": false, 

    "allowEdit": true, 

    "startDate": "2024-02-05T15:05:44.423", 

    "endDate": "2026-03-30T00:00:00", 

    "formatedEndDate": "30/03/2026", 

    "day": 10, 

    "items": [ 

        { 

            "$id": "2", 

            "name": "teste leo", 

            "quantity": 1, 

            "unitPrice": 1000, 

            "totalPrice": 1000, 

            "formattedUnitPrice": "R$ 10,00", 

            "formattedTotalPrice": "R$ 10,00" 

        } 

    ], 

    "item": { 

        "$ref": "2" 

    }, 

    "history": [ 

        { 

            "$id": "3", 

            "orderId": "c748ef42-d1e7-4db3-9633-8d057bf874b0", 

            "orderNumber": "8245e94dcf4c4de3906118e38f376822", 

            "merchantOrderNumber": "12345", 

            "createdDate": "2024-02-05T15:05:44.457", 

            "paymentStatus": 7, 

            "paymentStatusDescription": "Autorizado" 

        } 

    ], 

    "lastPaymentDate": "0001-01-01T00:00:00", 

    "nextPaymentDate": "2026-02-05T00:00:00", 

    "formatedNextPaymentDate": "05/02/2026", 

    "intervalDescription": "Mensal", 

    "recurrentPaymentStatusDescription": "Ativa", 

    "amount": 4000.0 

}

Desativando uma Recorrência

Para desativar uma recorrência, mande a seguinte requisição.

Requisição

Parâmetros no cabeçalho (header)

• Authorization: Bearer {access_token}
• Content-type: application/json

Não é necessário envio de nenhum parâmetro no corpo (body).

Notificações da transação

O processo de notificação transacional ocorre em duas etapas, que são a notificação de finalização da transação e a notificação de mudança de status.

*As notificações são enviadas para as URLs definidas pelo estabelecimento nas Configurações da Loja e contêm os dados das transações realizadas no Checkout.

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.

Exemplo: O comprador acessa o link de pagamento e escolhe pagar via Pix. Ao clicar em Finalizar, o Checkout gera a chave Pix e envia para a loja a notificação de finalização da transação, que estará com o status “Pendente”. Quando o comprador fizer o pagamento via Pix, a transação ficará com o status “Pago” e o Checkout enviará a notificação de mudança de status.

Características das notificações

As URLs para notificação são webhooks que podem receber uma notificação via POST ou via JSON:

Formato das notificações

Nas notificações suportadas pela API do Checkout o formato enviado é Form Data, discriminado pelo header Content-Type ‘x-www-form-urlencoded’.

Retorno esperado

O servidor da loja deve enviar o retorno HTTPStatus = 200 (OK) para a API do Checkout, indicando que a notificação foi recebida e processada com sucesso.

IMPORTANTE: Se a URL cadastrada retornar algum erro ou estiver indisponível, serão realizadas três novas tentativas, com intervalo de uma hora entre cada POST.

Caso a notificação não seja recebida, é possível solicitar o reenvio manualmente nos Detalhes do pedido, clicando no ícone da seta.

Notificação de finalização da transação

É a notificação enviada para a URL de Notificação e pode ser no formato POST ou JSON.

Notificação via POST

Contém todos os dados da transação, inclusive o merchant_order_number e o checkout_cielo_order_number, que poderão ser usados para a consulta de transações.

Exemplo:

FormData

order_number: "40e00eefbf094763a147af713fa07ece", 
amount: "5000", 
checkout_cielo_order_number: "b9ab1956738d45cc88edf51d7d03b13e", 
created_date: "02/02/2023 17:01:35",  
customer_name: "nome do cliente",  
customer_phone: "2222222222",  
customer_identity: "12312312344",  
customer_email: "nome@email.com.br",  
shipping_type: "5",  
shipping_price: "0",  
payment_method_type: "6",  
payment_method_brand: "2",  
payment_ maskedcreditcard: "550209******7201",  
payment_installments: "1",  
payment_antifraudresult: "1",  
payment_status: "1",  
tid: "28234896273NT8MFJBPE", 
test_transaction: "False",  
product_id: "0f48e580-d0a2-4e3b-a748-6704927f1725",  
product_type: "3",  
product_description: "123",  
nsu: "00339922" 
authorization_code: "913812" 
start_date: "29/04/2024 09:38:53" 
recurrent_status: "Ativa" 
interval: "Mensal" 
pagador_recurrent_payment_id: "9cfc236e-8600-4306-9c83-d409d1f86937" 

Veja a descrição dos detalhes da transação na sessão Conteúdo das notificações.

Notificação via JSON

A notificação via JSON é um método mais seguro e flexível para realizar uma consulta no Checkout Cielo. Nessa modalidade a loja recebe o MerchantId e o MerchantOrderNumber e uma URL para realizar uma consulta (GET) junto à base de dados do Checkout Cielo e acessar os detalhes da transação.

Conteúdo da notificação via JSON

MerchantId: "799g0de8-89c3-5d17-c670-6b29d7f00175", 
MerchantOrderNumber: "1db9226geg8b54e6b2972e9b745b89c7", 
Url: "https://cieloecommerce.cielo.com.br/api/public/v1/orders/799g0de8-89c3-5d17-c670-6b29d7f00175 /1db9226geg8b54e6b2972e9b745b89c7"

*Em outras requisições e respostas pode se chamar OrderNumber.

O servidor da loja deve enviar o retorno HTTP Status = 200 (OK) para a API do Checkout, indicando que a notificação foi recebida e processada com sucesso.

Exemplo de uma consulta à URL retornada via JSON

Resposta

{ 
    "order_number": "1db9226geg8b54e6b2972e9b745b89c7", 
    "amount": 101, 
    "discount_amount": 0, 
    "checkout_cielo_order_number": "65930e7460bd4a849502ed14d7be6c03", 
    "created_date": "10-03-2023 14:38:56", 
    "customer_name": "Test Test", 
    "customer_phone": "11987654321", 
    "customer_identity": "445556667", 
    "customer_email": "shopper@email.com.br", 
    "shipping_type": 1, 
    "shipping_name": "Motoboy", 
    "shipping_price": 1, 
    "shipping_address_zipcode": "06455-030", 
    "shipping_address_district": "Alphaville", 
    "shipping_address_city": "Barueri", 
    "shipping_address_state": "SP", 
    "shipping_address_line1": "Alameda Xingu", 
    "shipping_address_line2": "Apto 25", 
    "shipping_address_number": "512", 
    "payment_method_type": 1, 
    "payment_method_brand": 1, 
    "payment_maskedcreditcard": "482852******6856", 
    "payment_installments": 1, 
    "payment_status": 3, 
    "tid": "10558590697J62OH9BPB", 
    "test_transaction": "False" 
    "interval": "Monthly", 
    "recurrent_status": "Ativa", 
    "start_date": "20/02/2024", 
    "end_date": "04/10/2028", 
    "product_id": "adf8905e-68ef-4433-9692-9d63aa3d8f77", 
    "product_type": 5, 
    "nsu": "038002", 
    "authorization_code": "039186" 
} 

Veja a descrição dos detalhes da venda na sessão Conteúdo das notificações.

Conteúdo das notificações

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

Tipos de productID

Payment_status

O Checkout possui status próprios, diferente do site Cielo ou da API E-commerce Cielo. Veja a lista completa em Payment_status.

Observação: 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 por estabelecimento, sendo assim a notificação não retorna se o provedor usado foi Bradesco ou Banco do Brasil, pois apenas um deles estará ativo na afiliação.

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

Payment_method_brand

É a bandeira do cartão.

Nas Consultas, a bandeira do cartão é retornada no campo Payment.Brand e vem preenchida com o valor literal.

Payment_method_bank

Shipping_type

Notificação de mudança de status

É enviada para a URL de mudança de status e contém o checkout_cielo_order_number, o novo status e alguns dados da transação.

Para saber mais detalhes da transação, faça uma consulta usando o checkout_cielo_order_number.

O formato da notificação de mudança de status é POST (form data).

checkout_cielo_order_number: "b918afea483d4c6c8615d8a8e19803c1",
amount: "134",
order_number: "024f77ac98cb493b86d8c818eb6e79cd",
payment_status: "3",
test_transaction: "False",
brand: "Visa",
nsu: "000001",
authorization_code: "01234567"

Consulta, captura e cancelamento

Consultando transações

A consulta de transações via API pode ser feita até 45 dias após a venda ter sido realizada.

A consulta deve ser feita pela API de Controle Transacional, enviando o access_token como autenticação.

A consulta de pedidos pode ser feita por:

• order_number: é o MerchantOrderNumber retornado na notificação de finalização da transação;
• checkout_cielo_order_number: é retornado na notificação de finalização da transação ou na notificação de mudança de status.

Por order_number

A consulta de transações por order_number retorna uma lista de transações com o mesmo número de pedidos; isso ocorre pois o Checkout não impede a duplicação de order_numbers por parte da loja. A resposta retornará o checkout_cielo_order_number, que deverá ser usado na consulta de uma transação específica.

Requisição

Para consultar uma transação pelo order_number, faça um GET.

Parâmetro na query string

Resposta

[
    {
        "$id": "1",
        "checkoutOrderNumber": "a58995ce24fd4f1cb025701e95a51478",
        "createdDate": "2023-03-30T12:09:33.57",
        "links": [
            {
                "$id": "2",
                "method": "GET",
                "rel": "self",
                "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/a58995ce24fd4f1cb025701e95a51478"
            }
        ]
    },
    {
        "$id": "3",
        "checkoutOrderNumber": "438f3391860a4bedbae9a868180dda6e",
        "createdDate": "2023-03-30T12:05:41.317",
        "links": [
            {
                "$id": "4",
                "method": "GET",
                "rel": "self",
                "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/438f3391860a4bedbae9a868180dda6e"
            }
        ]
    }
]

Por Checkout_Cielo_Order_Number

Requisição

Para consultar uma transação pelo Checkout_Cielo_Order_Number, basta realizar um GET.

Header: Authorization: Bearer {access_token}

Parâmetro na query string

Resposta

{ 
    "merchantId": "c89fdfbb-dbe2-4e77-806a-6d75cd397dac", 
    "orderNumber": "054f5b509f7149d6aec3b4023a6a2957", 
    "softDescriptor": "Pedido1234", 
    "cart": { 
        "items": [ 
            { 
                "name": "Pedido ABC", 
                "description": "50 canetas - R$30,00 | 10 cadernos - R$50,00 | 10 Borrachas - R$10,00", 
                "unitPrice": 9000, 
                "quantity": 1, 
                "type": "1" 
            } 
        ] 
    }, 
    "shipping": { 
        "type": "FixedAmount", 
        "services": [ 
            { 
              "name": "Entrega Rápida", 
                "price": 2000 
            } 
        ], 
        "address": { 
            "street": "Alameda Xingu", 
            "number": "512", 
            "complement": "21 andar", 
            "district": "Alphaville", 
            "city": "Barueri", 
            "state": "SP" 
        } 
    }, 
    "payment": { 
        "status": "Paid", 
        "tid": "10127355487AK2C3EOTB",
        "nsu": "149111",
        "authorizationCode": "294551",
        "numberOfPayments": 1,
        "createdDate": "2023-03-02T14:29:43.767",
        "finishedDate": "2023-03-02T14:29:46.117",
        "cardMaskedNumber": "123456******2007",
        "brand": "Visa",
        "type": "creditCard",
        "errorcode": "00",
        "antifraud": { 
            "antifraudeResult": 1,
            "description": "Risco Baixo" 
        } 
    }, 
    "customer": { 
        "identity": "12345678911", 
        "fullName": "Nome do comprador", 
        "email": "exemplo@email.com.br", 
        "phone": "11123456789" 
    }, 
    "links": [ 
        { 
            "method": "GET", 
            "rel": "self", 
            "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/054f5b509f7149d6aec3b4023a6a2957" 
        }, 
        { 
            "method": "PUT", 
            "rel": "void", 
            "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/054f5b509f7149d6aec3b4023a6a2957/void" 
        } 
    ] 
}

Capturando transações

A captura consiste na confirmação de uma autorização que foi realizada previamente e é um procedimento exclusivo para transações de cartões de crédito.

A captura acontece após a autorização, para que a venda seja concretizada e a cobrança seja feita no cartão. Somente após a captura o portador do cartão poderá visualizá-la em seu extrato ou fatura.

Requisição

Para capturar uma transação de cartão de crédito pelo Checkout_Cielo_Order_Number, basta realizar um PUT.

Header: Authorization: Bearer {access_token}

Captura Total

É a captura do valor total da transação.

Captura Parcial

É a captura de parte do valor da transação. Só pode ser realizada uma vez.

Observação: A captura parcial pode ser realizada apenas uma vez e é exclusiva para cartão de crédito.

Resposta

{
  "success": true,
  "status": 2,
  "returnCode": "6",
  "returnMessage": "Operation Successful",
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/a9d517d81fb24b98b2d16eae2744be96"
    },
    {
      "method": "PUT",
      "rel": "void",
      "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/a9d517d81fb24b98b2d16eae2744be96/void"
    }
  ]
}

Cancelando transações

Para cancelar uma transação pelo Checkout_Cielo_Order_Number, basta realizar um PUT.

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 sensibilização do saldo, evitando 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: Para realizar qualquer solicitação de cancelamento, é necessário que o estabelecimento possua saldo suficiente na transação/em agenda.

Requisição

Header: Authorization: Bearer {access_token}

Cancelamento total

É o cancelamento do valor total da transação.

Camcelamento Parcial

É o cancelamento de parte do valor da transação. Pode ser realizado mais de uma vez, até que o valor total seja cancelado.

Atenção: O cancelamento parcial pode ser realizado apenas após a captura. O cancelamento parcial pode ser realizado inúmeras vezes até que o valor total seja cancelado.

Resposta

{
  "success": true,
  "status": 2,
  "returnCode": "6",
  "returnMessage": "Operation Successful",
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/a9d517d81fb24b98b2d16eae2744be96"
    },
    {
      "method": "PUT",
      "rel": "void",
      "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/a9d517d81fb24b98b2d16eae2744be96/void"
    }
  ]
}

Status e códigos

Payment_status

O Checkout possui status próprios, diferente do site Cielo ou da API E-commerce Cielo. Veja a seguir a lista completa.

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

Status da Recorrência

Veja a lista de possíveis respostas de status de uma Recorrência com o Checkout.

Programa de Retentativa das Bandeiras

Quando uma pessoa tenta fazer uma compra com cartão no e-commerce 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 são o que chamamos de retentativa.

Como funciona?

As transações negadas são classificadas como:

• Irreversíveis: quando a retentativa não é permitida;
• Reversíveis: quando a retentativa é permitida mediante as regras de cada bandeira.

As retentativas podem ser cobradas pela bandeira e a quantidade de vezes que uma transação pode ser retentada antes da cobrança também varia de acordo com a bandeira.

Para ver as regras de retentativa de cada bandeira, acesse o manual Programa de Retentativa das Bandeiras.

Códigos de retorno ABECS

A Associação Brasileira das Empresas de Cartão de Crédito e Serviços (ABECS) é responsável pela padronização do código de retorno das autorizações de vendas negadas tanto para as soluções pagamento do mundo físico quanto de e-commerce do mercado brasileiro.

Para ver a relação completa dos códigos de retorno das transações negadas, acesse a tabela Códigos de retorno ABECS.

Suporte Cielo

A Cielo disponibiliza o suporte técnico 24 horas por dia, 7 dias por semana em português e inglês, nos seguintes contatos:

• E-mail: cieloecommerce@cielo.com.br
• +55 4002-5472 (capitais e regiões metropolitanas)
• +55 0800 570 8472 (demais Localidades)
• +55 11 2860-1348 (internacionais)
  • Opção 5 (Suporte E-commerce)