API Link de Pagamento Cielo

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

As documentações do Link de Pagamento 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.

Link de Pagamento Cielo

Sobre esta documentação

Este manual é um guia para desenvolvedores na integração com a API Link de Pagamento Cielo. Ao integrar a API do Link de Pagamento Cielo, você vai conseguir:

• Configurar a sua loja e personalizar seus links de pagamentos;
• Criar e editar links de pagamento via API;
• Receber notificações de pagamentos;
• Consultar pagamentos.

Você também pode usar o Link de Pagamento pelo site Cielo ou pelo app Cielo Gestão.

Sobre o Link de Pagamento Cielo

O Link de Pagamento permite que você envie um link de pagamento de um pedido para seus clientes pelas redes sociais ou pelo canal que preferir. Ao abrir o link de pagamento, a pessoa compradora vai ver uma página personalizada com o logo da sua loja e as opções de pagamento.

Você pode vender diferentes tipos de produtos:

• Material físico: qualquer produto físico que precise de entrega via frete, como roupas, eletrônicos, cosméticos, móveis etc;
• Digital: qualquer produto digital que não precise de entrega via frete, como mídia ou jogo online, softwares etc.;
• Serviço: qualquer serviço que não precise de entrega via frete, como serviços de manutenção e delivery ou consulta odontológica, entre outros;
• Pagamento: pagamentos únicos;
• Recorrência: vendas que se repetem dentro de uma determinada periodicidade, como mensalidade de academia ou aulas de idiomas.

Como criar um Link de Pagamento?

Você pode criar um Link de Pagamento pelo site Cielo, app Cielo Gestão ou pela API Link de Pagamento. Neste manual, vamos tratar da integração da API do Link de Pagamento.

Quem pode usar o Link de Pagamento?

Qualquer loja que deseje vender online pode criar um link de pagamento e compartilhar esse link pelas redes sociais. Você não precisa ter um e-commerce para usar o Link de Pagamento.

API do Link de Pagamento Cielo

A API do Link de Pagamento é uma API REST que permite criar, editar e consultar links de pagamentos. A principal vantagem da API é permitir que lojas possam criar links de pagamento (por botões ou QR Codes) através de seus próprios sistemas e compartilhar o Link de Pagamento com seus clientes, sem a necessidade de acessar o site Cielo.

A imagem a seguir representa o fluxo geral do funcionamento da API do Link de Pagamento:

1. A loja envia requisição de criação do link de pagamento para a API do Link de Pagamento;
2. A API do Link de Pagamento retorna a URL do link de pagamento e o ID do link;
3. A loja compartilha o link de pagamento com o comprador;
4. O comprador efetua o pagamento;
5. A Cielo (como adquirência) autoriza o pagamento e envia confirmação para o Link de Pagamento;
6. A API do Link de Pagamento envia a notificação de finalização da transação ou a notificação de mudança de status para a loja. Se desejar, a loja pode desenvolver um processo para disparo de e-mail de confirmação ao comprador (não disponível pela API do Link de Pagamento).

Meios de pagamento e bandeiras

No Link de Pagamento você pode vender seus produtos e serviços pelos principais meios de pagamento, como cartões de crédito e débito ou carteiras digitais.

Início Rápido

Para iniciar a sua integração com a API do Link de Pagamento, você vai precisar:

1. Solicitar o nº de estabelecimento (EC) para o Link de Pagamento
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. Obter as credenciais de acesso à API (ClientId e Client Secret);
5. Solicitar um token de acesso via API usando as credenciais;
6. Com o token, criar um link de pagamento;
7. Quando houver uma tentativa de pagamento no link, você receberá uma notificação** com todos os dados preenchidos no checkout;
8. Se a transação mudar de status, você receberá uma notificação** de mudança de status;
9. Para efetuar testes, use o Modo de Teste do Link de Pagamento.

*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 Link de Pagamento para a sua loja.

Habilitando o nº de estabelecimento (EC) para o Link de Pagamento

• 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 Link de Pagamento;
• 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 > Link de Pagamento > 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.

Atenção

• Para usar boleto, solicite a habilitação para o 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.

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 Link de Pagamento Cielo.

Para mais detalhes veja o tutorial Link de Pagamento e Checkout Cielo.

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: é 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: é 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), 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.

Configurações padrão

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

• A opção de envio de e-mail ao portador estará ligada;
• A opção de aceitar cartões internacionais estará ligada;
• 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 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.

Modo Teste

Sandbox

Por se tratar de uma chamada não financeira, a API do Link de Pagamento não possui um sandbox para testar a criação de links. Os links devem ser criados 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.

Suporte Cielo E-commerce

cieloecommerce@cielo.com.br

+55 11 4002-5472

0800 570 8472

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

Ativação do 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.

Quando a opção for salva, uma tarja vermelha será exibida na parte superior da tela. Ela será exibida em todas as telas do Link de Pagamento.

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 do link 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:

Transações com 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 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.

Endpoints

Os endpoints para integração com o Link de Pagamento são apresentados na tabela a seguir:

Importante: A API do Link de Pagamento não possui sandbox, mas você pode criar links de teste ativando o Modo Teste no site Cielo.

As transações criadas com o Modo Teste ativado podem ser consultadas pela API de Controle Transacional.

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 do Link de Pagamento.

Para utilizar o Cielo OAUTH são necessarias 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 para autenticação na API do Link de Pagamento, siga os passos a seguir:

1. Após receber o nº de estabelecimento (EC) com a habilitação para o Link de Pagamento, acesse o site Cielo e faça o login;
2. Vá para a aba Ecommerce > Link de Pagamento > 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. Você 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 do Link de Pagamento.

{
  "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 à API do Link de Pagamento 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.

Link de pagamento

Criar Link

Para criar um link de pagamento, envie um POST com os dados do produto ou serviço.

Requisição

Header: Authorization: Bearer {access_token}

{
  "OrderNumber": "123456",  
  "type": "Digital",
  "name": "Pedido",
  "description": "teste description",
  "price": "1000000",
  "weight": 2000000,
  "expirationDate": "2027-06-19 16:30:00",
  "maxNumberOfInstallments": "1",
  "quantity": 2,
  "sku": "teste",
  "shipping": {
    "type": "WithoutShipping",
    "name": "teste",
    "price": "1000000000"
  },
  "recurrent": {
    "interval": "Monthly",
    "endDate": "2024-02-06"
  },
  "softDescriptor": "Pedido1234"
}

Dados do produto

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.

Dentro de description você pode usar o caracter pipe | caso precise quebrar a linha ao apresentar a descrição na tela do link de pagamento.

Dados do Frete

Os dados que devem ser preenchidos com relação à frete estão no nó shipping.

Dados da Recorrência

O nó recurrent contém informações da recorrência do pagamento. Pode ser informado caso o tipo do produto (type) seja “Recurrent”.

Resposta

A resposta irá retornar o link de pagamento no campo shortUrl e o id do link, que pode ser usado para consultar, atualizar ou excluir o link.

“HTTP Status”: 201 – Created

{
  "id": "529aca91-2961-4976-8f7d-9e3f2fa8a0c9",
  "shortUrl": "http://bit.ly/2smqdhD",
  "OrderNumber": "123456",
  "type": "Asset",
  "name": "Pedido ABC",
  "description": "50 canetas - R$30,00 | 10 cadernos - R$50,00",
  "showDescription": false,
  "price": 8000,
  "weight": 4500,
  "shipping": {
    "type": "Correios",
    "originZipcode": "06455030"
  },
  "recurrent": {
    "interval": "Monthly",
    "endDate": "2024-02-06"
  },
  "softDescriptor": "Nome da Loja",
  "expirationDate": "2024-06-30T00:00:00",
  "maxNumberOfInstallments": 2,
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href":
        "https://cieloecommerce.cielo.com.br/Api/public/v1/product/529aca91-2961-4976-8f7d-9e3f2fa8a0c9"
    },
    {
      "method": "PUT",
      "rel": "update",
      "href":
        "https://cieloecommerce.cielo.com.br/Api/public/v1/product/529aca91-2961-4976-8f7d-9e3f2fa8a0c9"
    },
    {
      "method": "DELETE",
      "rel": "delete",
      "href":
        "https://cieloecommerce.cielo.com.br/Api/public/v1/product/529aca91-2961-4976-8f7d-9e3f2fa8a0c9"
    }
  ]
}

Os dados retornados na resposta contemplam todos os enviados na requisição e dados adicionais referentes a criação do link.

Consultar Link

Para consultar um link existente basta realizar um GET informando o id do link.

Importante: A resposta da consulta contém o link em si (shortUrl) e os mesmos dados retornados na criação do link.

O link ainda não é a transação. Uma transação só será iniciada quando o comprador fizer a tentativa de pagamento e pode ou não ser autorizada.

Para consultar uma transação, veja a seção Consulta de Transações.

Requisição

Header: Authorization: Bearer {access_token}

Resposta

HTTP Status: 200 – OK

{
  "id": "529aca91-2961-4976-8f7d-9e3f2fa8a0c9",
  "shortUrl": "http://bit.ly/2smqdhD",
  "OrderNumber": "123456",
  "type": "Asset",
  "name": "Pedido ABC",
  "description": "50 canetas - R$30,00 | 10 cadernos - R$50,00",
  "showDescription": false,
  "price": 8000,
  "weight": 4500,
  "shipping": {
    "type": "Correios",
    "originZipcode": "06455030"
  },
  "softDescriptor": "Pedido1234",
  "expirationDate": "2024-06-30 16:30:00",
  "maxNumberOfInstallments": 2,
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href":
        "https://cieloecommerce.cielo.com.br/Api/public/v1/products/529aca91-2961-4976-8f7d-9e3f2fa8a0c9"
    },
    {
      "method": "PUT",
      "rel": "update",
      "href":
        "https://cieloecommerce.cielo.com.br/Api/public/v1/products/529aca91-2961-4976-8f7d-9e3f2fa8a0c9"
    },
    {
      "method": "DELETE",
      "rel": "delete",
      "href":
        " https://cieloecommerce.cielo.com.br/Api/public/v1/products/529aca91-2961-4976-8f7d-9e3f2fa8a0c9"
    }
  ]
}

Atualizar Link

Para atualizar um link existente basta realizar uma chamada do tipo PUT informando o id do link.

Você pode atualizar um link para alterar a forma de pagamento, inserir um novo item no pedido, alterar a descrição do pedido ou alterar o tipo de recorrência, por exemplo.

Requisição

Header: Authorization: Bearer {access_token}

{
  "Type": "Asset",
  "name": "Pedido ABC",
  "description":
    "50 canetas - R$30,00 | 10 cadernos - R$50,00 | 10 Borrachas - R$10,00",
  "price": 9000,
  "expirationDate": "2024-06-30 16:30:00",
  "weight": 4700,
  "sku": "abc123456",  
  "shipping": {
    "type": "FixedAmount",
    "name": "Entrega Rápida",
    "price": 1000
  },
  "SoftDescriptor": "Pedido1234",
  "maxNumberOfInstallments": 2
}

Resposta

HTTP Status: 200 – OK

{
  "id": "529aca91-2961-4976-8f7d-9e3f2fa8a0c9",
  "shortUrl": "http://bit.ly/2smqdhD",
  "type": "Asset",
  "name": "Pedido ABC",
  "description":
    "50 canetas - R$30,00 | 10 cadernos - R$50,00 | 10 Borrachas - R$10,00",
  "showDescription": false,
  "sku": "abc123456",
  "price": 9000,
  "weight": 4700,
  "shipping": {
    "type": "FixedAmount",
    "name": "Entrega Rápida",
    "price": 1000
  },
  "softDescriptor": "Pedido1234",
  "expirationDate": "2024-06-30 16:30:00",
  "maxNumberOfInstallments": 2,
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href":
        "https://cieloecommerce.cielo.com.br/Api/public/v1/products/529aca91-2961-4976-8f7d-9e3f2fa8a0c9"
    },
    {
      "method": "PUT",
      "rel": "update",
      "href":
        "https://cieloecommerce.cielo.com.br/Api/public/v1/products/529aca91-2961-4976-8f7d-9e3f2fa8a0c9"
    },
    {
      "method": "DELETE",
      "rel": "delete",
      "href":
        "https://cieloecommerce.cielo.com.br/Api/public/v1/products/529aca91-2961-4976-8f7d-9e3f2fa8a0c9"
    }
  ]
}

Atenção: A resposta da consulta contém os mesmos dados retornados na criação do link.

Excluir Link

Para excluir um link existente basta realizar um DELETE informando o Id do link.

Requisição

Header: Authorization: Bearer {access_token}

Resposta

HTTP Status: 204 – No Content

Recorrência

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

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 um Link de Pagamento recorrente

Um Link de Pagamento recorrente 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 pode ser mensal, bimestral, trimestral, semestral e anual;
• Data de encerramento: data que o processo de recorrência deixa de ocorrer.

}, 

  "recurrent": { 

    "interval": "Monthly", 

    "endDate": "2024-02-06" 

  }, 

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 Link de Pagamento Cielo.

Requisição

{ 

  "OrderNumber": "123456",   

  "type": "Digital", 

  "name": "Pedido", 

  "description": "teste description", 

  "price": "1000000", 

  "weight": 2000000, 

  "expirationDate": "2027-06-19", 

  "maxNumberOfInstallments": "1", 

  "quantity": 2, 

  "sku": "teste", 

  "shipping": { 

    "type": "WithoutShipping", 

    "name": "teste", 

    "price": "1000000000" 

  }, 

  "recurrent": { 

    "interval": "Monthly", 

    "endDate": "2024-02-06" 

  }, 

  "softDescriptor": "Pedido1234" 

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 Link de PAgamento 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 Link de Pagamento (alteração integrada): siga os passos a seguir para enviar requisições de edição de recorrência de forma integrada pela API do Link de Pagamento.

Alteração Integrada

Para alterar dados de uma recorrêcia usando a API do Link de Pagamento 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âmetros 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 

}

Parâmetros no corpo (body)

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 Link de Pagamento.

Vale destacar que o Link de Pagamento 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 Link de Pagamento 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 Link de Pagamento 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 Link de Pagamento 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 Link de Pagamento, 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 Link de Pagamento Cielo. Nessa modalidade a loja recebe o MerchantId e o MerchantOrderNumber e uma URL para realizar uma consulta (GET) junto à base de dados do Link de Pagamento 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 Link de Pagamento, 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 Link de Pagamento 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).

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 Link de Pagamento 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 de transações

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

O controle dos pedidos oriundos de link de pagamento pode ser feito por meio da API de Controle Transacional. A consulta de pedidos pode ser feita de três formas distintas:

• Por order_number;
• Por checkout_cielo_order_number;
• Por id do link de pagamento.

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 Link de Pagamento 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.

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}

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" 
        } 
    ] 
}

Por Id do link de pagamento

Requisição

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

Header: Authorization: Bearer {access_token}

Resposta

{
   "$id": "1",
   "productId": "9487e3a9-f204-4188-96c5-a5a3013b2517",
   "createdDate": "2023-02-11T10:35:04.947",
   "orders": [
       {
           "$id": "2",
           "orderNumber": "b74df3e3c1ac49ccb7ad89fde2d787f7",
           "createdDate": "2023-02-11T10:37:23.447",
           "payment": {
               "$id": "3",
               "price": 11500,
               "numberOfPayments": 6,
               "createdDate": "2023-02-11T10:37:23.447",
               "status": "Denied"
           },
           "links": [
               {
                   "$id": "4",
                   "method": "GET",
                   "rel": "self",
                   "href": "https://cieloecommerce.cielo.com.br/api/public/v2/orders/b74df3e3c1ac49ccb7ad89fde2d787f7"
               }
           ]
       }
   ]
}

Para realizar o as consultas via API de Controle Transacional no Link de Pagamento Cielo é obrigatório que a loja tenha configurado um dos dois modelos de notificação:

• URL de Notificação da transação via POST ou
• URL de Notificação da transação via JSON.

É obrigatório ter fornecido uma URL de notificação de transação pois os dados para consulta da transação serão enviados no conteúdo da notificação.

O Checkout_Cielo_Order_Number é gerado apenas quando o pagamento é finalizado na tela transacional. Ele é enviado apenas pela URL de Notificação e não pela resposta da criação da tela transacional.

Status e Códigos

O Link de Pagamento possui status próprios, diferente do site Cielo ou da API Cielo E-commerce. Veja abaixo a lista completa.

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

Status do Antifraude