API E-commerce Cielo

Visão geral

O objetivo desta documentação é orientar sobre a integração da API E-commerce Cielo, descrevendo as funcionalidades e os métodos HTTP, listando informações a serem enviadas e recebidas e provendo exemplos.

Conhecimentos necessários: recomendamos conhecimentos intermediários em linguagem de programação para web, requisições HTTP/HTTPS e manipulação de arquivos JSON.

Para executar as operações da API E-commerce Cielo você deverá usar sua chave específica (MerchantId e MerchantKey) nos respectivos endpoints dos ambientes:

  Sandbox Produção
Transacional https://apisandbox.cieloecommerce.cielo.com.br https://api.cieloecommerce.cielo.com.br/
Consultas https://apiquerysandbox.cieloecommerce.cielo.com.br https://apiquery.cieloecommerce.cielo.com.br/

Para executar uma operação, combine a URL base do ambiente com a URL da operação desejada e envie utilizando o verbo HTTP conforme descrito na operação.

Faça o download do tutorial para saber como gerar seu MerchantId e MerchantKey no portal da Cielo.

Características da solução

A solução API e-commerce Cielo foi desenvolvida com a tecnologia REST, que é padrão de mercado e independe da tecnologia utilizada pelo seu e-commerce. Dessa forma, é possível integrar-se utilizando as mais variadas linguagens de programação.

Para obter exemplos dessas linguagens, veja nosso Tutorial de conversão Postman.

Entre outras características, os atributos que mais se destacam na plataforma API e-commerce Cielo:

Arquitetura da integração

O modelo empregado na integração das APIs é simples e se baseia na utilização de duas URLs:


Para executar uma operação:

  1. Combine a base da URL do ambiente com o endpoint da operação desejada. Ex.: https://api.braspag.com.br/v2/sales/.
  2. Envie a requisição para a URL utilizando o método HTTP adequado à operação.
Método HTTP Descrição
GET Retorna recursos já existentes, ex.: consulta de transações.
POST Cria um novo recurso, ex.: criação de uma transação.
PUT Atualiza um recurso existente, ex.: captura ou cancelamento de uma transação previamente autorizada.

Todas a operações requerem as credenciais de acesso MerchantId e MerchantKey, que devem ser enviadas no cabeçalho (header) da requisição.
Cada envio de requisição irá retornar um código de Status HTTP, indicando se ela foi realizada com sucesso ou não.

Glossário

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

Termo Descrição
Autenticação processo para assegurar que o comprador é realmente aquele quem diz ser (portador legítimo), geralmente ocorre no banco emissor com uso de um token digital ou cartão com chaves de segurança.
Autorização processo para verificar se uma compra pode ou não ser realizada com um cartão. Nesse momento, são feitas diversas verificações com o cartão e com o portador (ex.: adimplência, bloqueios, etc.) É também neste momento que o limite do cartão é sensibilizado com o valor da transação.
Cancelamento processo para cancelar uma compra realizada com cartão.
Captura processo que confirma uma autorização que foi realizada previamente. Somente após a captura, é que o portador do cartão poderá visualizá-la em seu extrato ou fatura.
Comprador É aquele que efetua compra na loja virtual.
Emissor (ou banco emissor) É a instituição financeira que emite o cartão de crédito, débito ou voucher.
Estabelecimento comercial ou EC É o número de dez posições que identifica o cadastro da loja na Cielo.
Gateway de pagamentos Empresa responsável pelo integração técnica e processamento das transações.
Portador É a pessoa que tem o porte do cartão no momento da venda.
TID (Transaction Identifier) código composto por 20 caracteres que identificada unicamente uma transação e-commerce Cielo.

Produtos e bandeiras suportadas

A versão atual da API e-commerce Cielo possui suporte às seguintes bandeiras e produtos:

Bandeira Crédito à vista Crédito parcelado Loja Débito Voucher Internacional
Visa Sim Sim Sim Não Sim
Master Card Sim Sim Sim Não Sim
American Express Sim Sim Não Não Sim
Elo Sim Sim Não Não Sim
Diners Club Sim Sim Não Não Sim
Discover Sim Não Não Não Sim
JCB Sim Sim Não Não Sim
Aura Sim Sim Não Não Sim
Hipercard Sim Sim Não Não Não

Suporte Cielo

Caso tenha dúvidas envie um e-mail para: cieloecommerce@cielo.com.br

Ou, se preferir, entre em contato com a gente pela Central de Atendimento:

Certificados e segurança

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:

Certificado EV Internet Explorer

Firefox

Certificado EV Firefox

Google Chrome

Certificado EV 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.

Passo a Passo para a Instalação

Instalação no Servidor da Loja Virtual

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

Acesso do Cliente à Loja Virtual

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

1o Passo:

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

2o Passo:

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

Instalar IE

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

Instalar FF

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:

Instalar GC

3o Passo:

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

Instalar IE

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

Instalar FF

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

Instalar GC

4o Passo:

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

Instalar IE e GC

Instalar IE e GC

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

Instalar FF

5o Passo:

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

Instalar IE e GC

Instalar IE e GC

6o Passo:

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

Instalar IE e GC

7o Passo:

Clique em “Concluir”.

Instalar IE e GC

8o Passo:

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

Instalar IE e GC

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

Instalar IE e GC

9o Passo:

Repita o mesmo procedimento para os 3 arquivos enviados.

Sandbox e Ferramentas

Sobre o Sandbox

Para facilitar os testes durante a integração, a Cielo oferece um ambiente Sandbox que permite simular as mensagerias da API. O ambiente Sandbox está programado com respostas preparadas para todas as funcionalidades previstas na API Cielo E-commerce.

INFORMAÇÃO URL
Credenciais de acesso MerchantId e MerchantKey obtidos após criação da conta de testes em Cadastro do Sandbox
Base da URL transacional https://apisandbox.cieloecommerce.cielo.com.br
Base da URL para consultas https://apiquerysandbox.cieloecommerce.cielo.com.br

Vantagens de utilizar o Sandbox

Ferramenta para Integração

Você pode usar o Postman para testar a sua integração, usando a collection da API e-commerce Cielo.

Collection

Link de importação: https://www.postman.com/collections/7313fe78130211f5f009

Ambiente Endpoints
Sandbox Envio de transação: https://apisandbox.cieloecommerce.cielo.com.br
Consulta transação: https://apiquerysandbox.cieloecommerce.cielo.com.br/
Produção Envio de transação: https://api.cieloecommerce.cielo.com.br/
Consulta transação: https://apiquery.cieloecommerce.cielo.com.br/

Environment

Faça download do arquivo Environment Produção e Sandbox e substitua os MerchantIDs e MerchantKeys pelos os da sua Loja.

Cartão de crédito - Sandbox

Com esse meio de pagamento é possível simular os fluxos de:

Para melhor aproveitar o meio de pagamento Simulado, você pode criar um número de cartão usando um gerador de cartões da internet ou escolhendo números aleatórios; para qualquer opção, os 15 primeiros dígitos do cartão podem ser aleatórios e o último dígito deve ser o número correspondente ao status da transação que deseja testar.

As informações de Cód.Segurança (CVV) e validade podem ser aleatórias, mantendo o CVV com 3 dígitos e a validade no formato MM/YYYY.



Final do Cartão Status da Transação Código de Retorno Mensagem de Retorno
XXXX.XXXX.XXXX.XXX0
XXXX.XXXX.XXXX.XXX1
XXXX.XXXX.XXXX.XXX4
Autorizado 4/6 Operação realizada com sucesso
XXXX.XXXX.XXXX.XXX2 Não Autorizado 05 Não Autorizada
XXXX.XXXX.XXXX.XXX3 Não Autorizado 57 Cartão Expirado
XXXX.XXXX.XXXX.XXX5 Não Autorizado 78 Cartão Bloqueado
XXXX.XXXX.XXXX.XXX6 Não Autorizado 99 Time Out
XXXX.XXXX.XXXX.XXX7 Não Autorizado 77 Cartão Cancelado
XXXX.XXXX.XXXX.XXX8 Não Autorizado 70 Problemas com o Cartão de Crédito
XXXX.XXXX.XXXX.XXX9 Autorização Aleatória 4 a 99 Operation Successful / Time Out

O cartão de teste 4024.0071.5376.3191, por exemplo, irá simular o status autorizado.


Para consultar os retornos em Produção, veja os Códigos da API.

Cartão de débito - Sandbox

Com esse meio de pagamento é possível simular os fluxos de:

Opção Status
Autenticado Autorizado
Não Autenticado Negado
Não usar a URL Não Finalizado

Outros meios de pagamento - Sandbox

Outros meios de pagamento não possuem cartões ou dados específicos simulados, como no caso do cartão de crédito. Abaixo especificamos qualquer diferença existente:

Meio de pagamento Orientações para Sandbox
Boleto Para enviar uma transação de boleto no ambiente sandbox você deve colocar o Provider como “Simulado”.
Não há validação bancária. O boleto se comporta como um boleto sem registro.
Alelo Use os mesmos valores da requisição do ambiente de produção para Cartões Alelo.
QR Code Use os mesmos valores da requisição do ambiente de produção para QR Code. Não tem a conciliação bancária.
Carnê Use os mesmos valores da requisição do ambiente de produção para Carnê.
Transferência eletrônica O Provider utilizado deve ser “Simulado”
A URL de redirecionamento para o ambiente do banco será uma tela para escolher o estado da autenticação.

Renova Fácil – Sandbox

Para simular uma transação com retorno de um novo cartão, atualizado pelo nosso serviço Renova Fácil, siga as orientações abaixo. Para saber mais como funciona a funcionalidade, acesse o menu “Recorrência” e depois “Renova Fácil”.

Na requisição de autorização, além dos campos já previstos para o meio de pagamento utilizado, é necessário enviar os seguintes:

Consulta BIN - Sandbox

O BIN de um cartão é composto pelos seis primeiros dígitos. Na simulação da Consulta BIN em ambiente sandbox, cada um dos seis primeiros dígitos vai reger um resultado simulado.

É possível montar uma numeração de cartão para teste e observar o retorno esperado de acordo com diferentes cenários.

O BIN de um cartão retorna a bandeira, o tipo, a nacionalidade, se o cartão é corporativo ou não, o retorno da análise de BIN e o emissor do cartão. Para saber mais, leia a seção Consulta BIN neste mesmo manual.

Dígito O que indica Retorno
1º dígito Bandeira. Se for ‘3’ retorna “AMEX
Se for ‘5’ retorna “MASTERCARD
Se for ‘6’ retorna “DISCOVER
Qualquer outro número retorna “VISA”.
2º dígito Tipo do cartão. Se for ‘3’ retorna “Débito
Se for ‘5’ retorna “Crédito
Se for ‘7’ retorna “Crédito” e retorna o campo Prepaidcomo “true
Qualquer outro número retorna”Múltiplo”.
3º dígito Nacionalidade do cartão. Se for ‘1’ retorna “true” (cartão nacional)
Qualquer número diferente de ‘1’ retorna “false” (cartão internacional).
4º dígito Se o cartão é corporativo ou não. Se for ‘1’ retorna “true” (é cartão corporativo)
Qualquer número diferente de ‘1’ retorna “false” (não é cartão corporativo).
5º dígito Retorno da análise. Se for ‘2’ retorna “01 - Bandeira não suportada
Se for ‘3’ retorna “02 - Voucher - Não suportado na consulta de bins
Qualquer outro número retorna “00 - Analise autorizada
6º dígito Banco emissor. Se for ‘1’ retorna “104” e “Caixa
Se for ‘2’ retorna “001” e “Banco do Brasil
Qualquer outro número retorna “237” e “Bradesco

Exemplo

O cartão com a numeração 4110110012341234 irá retornar os seguintes dados:

Consulta BIN Sandbox

Requisição

curl
--request GET https://apiquerysandbox.cieloecommerce.cielo.com.br/1/cardBin/411011
--header "Content-Type: application/json"
--data-binary
--verbose

Resposta

{
    "Status": "00",
    "Provider": "VISA",
    "CardType": "Multiplo",
    "ForeignCard": false,
    "CorporateCard": false,
    "Issuer": "Banco do Brasil",
    "IssuerCode": "001"
}
curl
{
    "Status": "00",
    "Provider": "VISA", 
    "CardType": "Multiplo",
    "ForeignCard": false,
    "CorporateCard": false,
    "Issuer": "Banco do Brasil",
    "IssuerCode": "001"
}
--verbose

Meios de Pagamento

Cartões de crédito e débito

Cartão de Crédito

Para que você possa disfrutar de todos os recursos disponíveis em nossa API, é importante que antes você conheça os conceitos envolvidos no processamento de uma transação de cartão de crédito.

Conceito Descrição
Autenticação É um processo de verificação do portador do cartão realizado pelo banco emissor para trazer mais segurança para a venda. Em caso de fraude em transação autenticada, o custo do chargeback é do emissor.
Autorização Etapa em que a Cielo faz a conexão com o sistema do banco emissor e da bandeira para aprovar uma transação de cartão. A pré-autorização apenas sensibiliza o limite do cliente, mas ainda não gera cobrança para o consumidor. Para efetivação da cobrança é necessária a ocorrência da captura.
Captura Após a autorização, para que a venda seja concretizada e a cobrança seja efetivada no cartão, ocorre o movimento de captura.
Cancelamento O cancelamento acontece quando o estabelecimento não quer mais prosseguir com uma transação. Esse movimento pode ser realizado tanto para transações autorizadas quanto para capturadas.

Criando uma transação de crédito

Para criar uma transação de cartão de crédito, envie uma requisição utilizando o método POST conforme o exemplo a seguir. Esse exemplo contempla todos os campos possíveis que você pode enviar; consulte quais campos são ou não obrigatórios na tabela de propriedades da requisição.

A captura da transação da crédito pode ser automática ou posterior. Para captura automática, envie o campo Payment.Capture na requisição como “true”. Para captura posterior, envie o campo como “false” e, posteriormente, faça a requisição de captura.

Saiba como realizar uma transação de crédito com autenticação em Autenticando uma Transação.

Requisição
{  
   "MerchantOrderId":"2014111701",
   "Customer":{  
      "Name":"Comprador crédito completo",
      "Email":"compradorteste@teste.com",
      "Birthdate":"1991-01-02",
      "Address":{  
         "Street":"Rua Teste",
         "Number":"123",
         "Complement":"AP 123",
         "ZipCode":"12345987",
         "City":"Rio de Janeiro",
         "State":"RJ",
         "Country":"BRA"
      },
        "DeliveryAddress": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "Billing": {
            "Street": "Rua Neturno",
            "Number": "12345",
            "Complement": "Sala 123",
            "Neighborhood": "Centro",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BR",
            "ZipCode": "20080123"
  },
   },
   "Payment":{  
     "Currency":"BRL",
     "Country":"BRA",
     "ServiceTaxAmount":0,
     "Installments":1,
     "Interest":"ByMerchant",
     "Capture":true,
     "Authenticate":"false",
     "Recurrent":"false",
     "SoftDescriptor":"123456789ABCD",
     "CreditCard":{  
         "CardNumber":"1234123412341231",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"123",
         "SaveCard":"false",
         "Brand":"Visa",
         "CardOnFile":{
            "Usage": "Used",
            "Reason":"Unscheduled"
         }
     },
     "IsCryptoCurrencyNegotiation": true,
     "Type":"CreditCard",
     "Amount":15700,
     "AirlineData":{
         "TicketNumber":"AR988983"
     }
   }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{  
   "MerchantOrderId":"2014111701",
   "Customer":{  
      "Name":"Comprador crédito completo",
      "Identity":"11225468954",
      "IdentityType":"CPF",
      "Email":"compradorteste@teste.com",
      "Birthdate":"1991-01-02",
      "Address":{  
         "Street":"Rua Teste",
         "Number":"123",
         "Complement":"AP 123",
         "ZipCode":"12345987",
         "City":"Rio de Janeiro",
         "State":"RJ",
         "Country":"BRA"
      },
        "DeliveryAddress": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "Billing": {
            "Street": "Rua Neturno",
            "Number": "12345",
            "Complement": "Sala 123",
            "Neighborhood": "Centro",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BR",
            "ZipCode": "20080123"
  },
   },
   "Payment":{  
     "ServiceTaxAmount":0,
     "Installments":1,
     "Interest":"ByMerchant",
     "Capture":true,
     "Authenticate":false,
     "Recurrent":"false",
     "SoftDescriptor":"123456789ABCD",
     "CreditCard":{  
         "CardNumber":"4551870000000183",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"123",
         "SaveCard":"false",
         "Brand":"Visa",
         "CardOnFile":{
            "Usage": "Used",
            "Reason":"Unscheduled"
         }
     },
     "IsCryptoCurrencyNegotiation": true,
     "Type":"CreditCard",
     "Amount":15700,
     "AirlineData":{
         "TicketNumber":"AR988983"
     }
   }
}
--verbose
Propriedade Tipo Tamanho Obrigatório Descrição
MerchantId Guid 36 Sim Identificador da loja na Cielo.
MerchantKey Texto 40 Sim Chave pública para autenticação dupla na Cielo.
Content-Type Header 40 Sim application/json (envio obrigatório).
RequestId Guid 36 Não Identificador da requisição, usado quando o lojista usa diferentes servidores para cada GET/POST/PUT.
MerchantOrderId Texto 50 Sim Número de identificação do pedido.
Customer.Name Texto 255 Não Nome do comprador.
Customer.Status Texto 255 Não Status de cadastro do comprador na loja (NEW / EXISTING)
Customer.Identity Texto 14 Não Número do RG, CPF ou CNPJ do comprador.
Customer.IdentityType Texto 255 Não Tipo de documento de identificação do comprador (CFP/CNPJ).
Customer.Email Texto 255 Não E-mail do comprador.
Customer.Birthdate Date 10 Não Data de nascimento do comprador.
Customer.Address.Street Texto 255 Não Endereço do comprador.
Customer.Address.Number Texto 15 Não Número do endereço do comprador.
Customer.Address.Complement Texto 50 Não Complemento do endereço do comprador
Customer.Address.ZipCode Texto 9 Não CEP do endereço do comprador.
Customer.Address.City Texto 50 Não Cidade do endereço do comprador.
Customer.Address.State Texto 2 Não Estado do endereço do comprador.
Customer.Address.Country Texto 35 Não País do endereço do comprador.
Customer.DeliveryAddress.Street Texto 255 Não Endereço do comprador.
Customer.Address.Number Texto 15 Não Número do endereço do comprador.
Customer.DeliveryAddress.Complement Texto 50 Não Complemento do endereço do comprador.
Customer.DeliveryAddress.ZipCode Texto 9 Não CEP do endereço do comprador.
Customer.DeliveryAddress.City Texto 50 Não Cidade do endereço do comprador.
Customer.DeliveryAddress.State Texto 2 Não Estado do endereço do comprador.
Customer.DeliveryAddress.Country Texto 35 Não País do endereço do comprador.
Customer.Billing.Street string 24 não Logradouro do endereço de cobrança.
Customer.Billing.Number string 5 não Número do endereço de cobrança.
Customer.Billing.Complement string 14 não Complemento do endereço de cobrança.
Customer.Billing.Neighborhood string 15 não Bairro do endereço de cobrança.
Customer.Billing.City string 20 não Cidade do endereço de cobrança.
Customer.Billing.State string 2 não Estado do endereço de cobrança.
Customer.Billing.Country string 2 não País do endereço de cobrança. Mais informações em ISO 2-Digit Alpha Country Code
Customer.Billing.ZipCode string 9 não Código postal do endereço de cobrança.
Payment.Type Texto 100 Sim Tipo do meio de pagamento.
Payment.Amount Número 15 Sim Valor do pedido (ser enviado em centavos).
Payment.Currency Texto 3 Não Moeda na qual o pagamento será feito (BRL).
Payment.Country Texto 3 Não País na qual o pagamento será feito.
Payment.Provider Texto 15 Define comportamento do meio de pagamento (ver Anexo)/NÃO OBRIGATÓRIO PARA CRÉDITO.
Payment.ServiceTaxAmount Número 15 Não Aplicável apenas para empresas aéreas. Montante do valor da autorização que deve ser destinado à taxa de serviço. Obs.: Esse valor não é adicionado ao valor da autorização.
Payment.SoftDescriptor Texto 13 Não O complemento do nome da loja que aparecerá na fatura do cartão. Não permite caracteres especiais.
Payment.Installments Número 2 Sim Número de Parcelas.
Payment.Interest Texto 10 Não Tipo de parcelamento - Loja (ByMerchant) ou Cartão (ByIssuer).
Payment.Capture Booleano Não (Default false) Booleano que identifica que a autorização deve ser com captura automática (“true”) ou captura posterior (“false”).
Payment.Authenticate Booleano Não (Default false) Define se o comprador será direcionado ao banco emissor para autenticação do cartão.
Payment.Recurrent Booleano - Não Indica se a transação é do tipo recorrente (“true”) ou não (“false”). O valor “true” não originará uma nova recorrência, apenas permitirá a realização de uma transação sem a necessidade de envio do CVV. Authenticate deve ser “false” quando Recurrent é “true”.
Payment.IsCryptocurrencyNegotiation Booleano - Não (default false) Deve ser enviado com valor “true” caso se trate de uma transação de compra ou venda de Criptomoeda.
Payment.AirlineData.TicketNumber alfanumérico 13 Não Informar o número do principal bilhete aéreo da transação.
CreditCard.CardNumber Texto 19 Sim Número do cartão do comprador.
CreditCard.Holder Texto 25 Não Nome do comprador impresso no cartão. Não aceita caracteres especiais ou acentuação.
CreditCard.ExpirationDate Texto 7 Sim Data de validade impressa no cartão. Ex. MM/AAAA.
CreditCard.SecurityCode Texto 4 Não Código de segurança impresso no verso do cartão.
CreditCard.SaveCard Booleano Não (Default false) Booleano que identifica se o cartão será salvo para gerar o CardToken.
CreditCard.Brand Texto 10 Sim Bandeira do cartão. Valores possíveis: Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard / Hiper.
CreditCard.CardOnFile.Usage Texto - Não First se o cartão foi armazenado e é seu primeiro uso.
Used se o cartão foi armazenado e ele já foi utilizado anteriormente em outra transação
CreditCard.CardOnFile.Reason Texto - Condicional Indica o propósito de armazenamento de cartões, caso o campo “Usage” for “Used”.
Recurring - Compra recorrente programada (ex. assinaturas)
Unscheduled - Compra recorrente sem agendamento (ex. aplicativos de serviços)
Installments - Parcelamento através da recorrência.
Resposta
{
    "MerchantOrderId": "2014111706",
    "Customer": {
        "Name": "Comprador crédito completo",
        "Identity":"11225468954",
        "IdentityType":"CPF",
        "Email": "compradorteste@teste.com",
        "Birthdate": "1991-01-02",
        "Address": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "DeliveryAddress": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "Billing": {
            "Street": "Rua Neturno",
            "Number": "12345",
            "Complement": "Sala 123",
            "Neighborhood": "Centro",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BR",
            "ZipCode": "20080123"
  },
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": true,
        "Authenticate": false,
        "CreditCard": {
            "CardNumber": "455187******0183",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa",
            "PaymentAccountReference":"92745135160550440006111072222",
         "CardOnFile":{
            "Usage": "Used",
            "Reason":"Unscheduled"
         }
        },
        "IsCryptoCurrencyNegotiation": true,
        "TryAutomaticCancellation":true,
        "ProofOfSale": "674532",
        "Tid": "0305020554239",
        "AuthorizationCode": "123456",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "CreditCard",
        "Amount": 15700,
        "CapturedAmount": 15700,
        "Country": "BRA",
        "AirlineData":{
            "TicketNumber": "AR988983"
        },
        "ExtraDataCollection": [],
        "Status": 2,
        "ReturnCode": "6",
        "ReturnMessage": "Operation Successful",
        "Payment.MerchantAdviceCode":"1",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2014111706",
    "Customer": {
        "Name": "Comprador crédito completo",
        "Identity":"11225468954",
        "IdentityType":"CPF",
        "Email": "compradorteste@teste.com",
        "Birthdate": "1991-01-02",
        "Address": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "DeliveryAddress": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "Billing": {
            "Street": "Rua Neturno",
            "Number": "12345",
            "Complement": "Sala 123",
            "Neighborhood": "Centro",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BR",
            "ZipCode": "20080123"
  },
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": true,
        "Authenticate": false,
        "CreditCard": {
            "CardNumber": "455187******0183",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa",
            "PaymentAccountReference":"92745135160550440006111072222",
         "CardOnFile":{
            "Usage": "Used",
            "Reason":"Unscheduled"
         }
        },
        "IsCryptoCurrencyNegotiation": true,
        "TryAutomaticCancellation":true,
        "ProofOfSale": "674532",
        "Tid": "0305020554239",
        "AuthorizationCode": "123456",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "CreditCard",
        "Amount": 15700,
        "CapturedAmount": 15700,
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 2,
        "ReturnCode": "6",
        "ReturnMessage": "Operation Successful",
        "Payment.MerchantAdviceCode":"1",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
Propriedade Descrição Tipo Tamanho Formato
ProofOfSale Número da autorização, identico ao NSU. Texto 6 Texto alfanumérico
Tid Id da transação na adquirente. Texto 20 Texto alfanumérico
AuthorizationCode Código de autorização. Texto 6 Texto alfanumérico
SoftDescriptor Texto impresso na fatura bancaria do portador. Não permite caracteres especiais. Texto 13 Texto alfanumérico
PaymentId Número de identificação do pagamento, necessário para futuras operações como Consulta, Captura e Cancelamento. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ECI Eletronic Commerce Indicator. Representa o quão segura é uma transação. Texto 2 Exemplos: 7
Status Status da Transação. Byte 2
ReturnCode Código de retorno da Adquirência. Texto 32 Texto alfanumérico
ReturnMessage Mensagem de retorno da Adquirência. Texto 512 Texto alfanumérico
Payment.MerchantAdviceCode Código de retorno da bandeira que define período para retentativa. Válido somente para bandeira Mastercard. Texto 2 Numérico
TryAutomaticCancellation Caso ocorra algum erro durante a autorização (status Não Finalizada - “0”), a resposta incluirá o campo “TryAutomaticCancellation” como true. Neste caso, a transação será consultada automaticamente, e caso tenha sido autorizada será cancelada automaticamente. Esta funcionalidade deverá estar habilitada para loja. Para habilitar, entre em contato com o nosso suporte técnico. Booleano - true ou false
CreditCard.PaymentAccountReference O PAR (Payment Account Reference) é o número que associa diferentes tokens a um mesmo cartão. Será retornado pelas bandeiras Master e Visa e repassado para os clientes do e-commerce Cielo. Caso a bandeira não envie a informação o campo não será retornado.Se for pra transação de débito, colocar o campo dentro do nó de DebitCard. Alfanumérico 29

Cartão de Débito

Esse meio de pagamento é liberado automaticamente junto a afiliação de Cielo.

Todas as transações de débito devem ser autenticadas por exigência dos bancos emissores e bandeiras, com o objetivo de promover maior segurança.

Para autenticar uma transação de débito, usamos o protocolo EMV 3DS 2.0; esse protocolo é um script integrado ao seu e-commerce que verifica a identidade do portador do cartão enquanto mantém uma boa experiência de compra ao consumidor e reduz o risco de fraude.

Para integrar o método de autenticação, consulte a documentação do 3DS 2.0.

Débito sem autenticação: ou “débito sem senha”, só pode ser realizada quando o e-commerce tem autorização do banco emissor para dispensa da autenticação. Caso você tenha essa permissão, envie o campo Authenticate como “false” na requisição padrão de cartão de débito.

Criando uma transação de débito

Para criar uma venda com cartão de débito, chame o método POST conforme o exemplo a seguir. O exemplo contempla o mínimo de campos necessários que devem ser enviados para a autorização.

Na transação de débito padrão (com autenticação), envie Authenticate = “true”.

Requisição
{
   "MerchantOrderId":"2014121201",
   "Customer":{
      "Name":"Comprador Cartão de débito"
   },
   "Payment":{
      "Type":"DebitCard",
      "Authenticate":true,
      "Amount":15700,
      "DebitCard":{
         "CardNumber":"5551870000000181",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"123",
         "Brand":"Master"
      },
      "ExternalAuthentication":{
         "Cavv":"AAABB2gHA1B5EFNjWQcDAAAAAAB=",
         "Xid":"Uk5ZanBHcWw2RjRCbEN5dGtiMTB=",
         "Eci":"5",
         "Version":"2",
         "ReferenceID":"a24a5d87-b1a1-4aef-a37b-2f30b91274e6"
      }
   }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
   "MerchantOrderId":"2014121201",
   "Customer":{
      "Name":"Comprador Cartão de débito"
   },
   "Payment":{
      "Type":"DebitCard",
      "Authenticate":true,
      "Amount":15700,
      "DebitCard":{
         "CardNumber":"5551870000000181",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"123",
         "Brand":"Master"
      },
      "ExternalAuthentication":{
         "Cavv":"AAABB2gHA1B5EFNjWQcDAAAAAAB=",
         "Xid":"Uk5ZanBHcWw2RjRCbEN5dGtiMTB=",
         "Eci":"5",
         "Version":"2",
         "ReferenceID":"a24a5d87-b1a1-4aef-a37b-2f30b91274e6"
      }
   }
}
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API Cielo eCommerce. Guid 36 Sim
MerchantKey Chave Publica para Autenticação Dupla na API Cielo eCommerce. Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
MerchantOrderId Numero de identificação do Pedido. Texto 50 Sim
Customer.Name Nome do Comprador. Texto 255 Não
Customer.Status Status de cadastro do comprador na loja (NEW / EXISTING) - Utilizado pela análise de fraude Texto 255 Não
Payment.Type Tipo do Meio de Pagamento. Texto 100 Sim
Payment.Amount Valor do Pedido (ser enviado em centavos). Número 15 Sim
Payment.Authenticate Define se o comprador será direcionado ao Banco emissor para autenticação do cartão Booleano Sim
Payment.ReturnUrl URI para onde o usuário será redirecionado após o fim do pagamento Texto 1024 Sim
Payment.IsCryptocurrencyNegotiation Deve ser enviado com valor “true” caso se trate de uma transação de compra ou venda de Criptomoeda Booleano - Não (default false)
DebitCard.CardNumber Número do Cartão do Comprador. Texto 19 Sim
DebitCard.Holder Nome do Comprador impresso no cartão. Texto 25 Não
DebitCard.ExpirationDate Data de validade impresso no cartão. Texto 7 Sim
DebitCard.SecurityCode Código de segurança impresso no verso do cartão. Texto 4 Não
DebitCard.Brand Bandeira do cartão. Texto 10 Sim
Payment.ExternalAuthentication.Eci E-Commerce Indicator retornado no processo de autenticação. Numérico 1 Sim
Payment.ExternalAuthentication.ReferenceId RequestID retornado no processo de autenticação. GUID 36 Sim
Resposta
{
    "MerchantOrderId": "2014121201",
    "Customer": {
        "Name": "Comprador Cartão de débito"
    },
    "Payment": {
        "DebitCard": {
            "CardNumber": "555187******0181",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Master",
            "PaymentAccountReference": "IC722LCXBROSHBPIBK7B44MBXO5HF"
        },
        "Provider": "Simulado",
        "AuthorizationCode": "635288",
        "Tid": "0826104754051",
        "ProofOfSale": "132471",
        "Authenticate": true,
        "ExternalAuthentication": {
            "Cavv": "AAABB2gHA1B5EFNjWQcDAAAAAAB=",
            "Xid": "Uk5ZanBHcWw2RjRCbEN5dGtiMTB=",
            "Eci": "5",
            "Version": "2",
            "ReferenceId": "a24a5d87-b1a1-4aef-a37b-2f30b91274e6"
        },
        "Recurrent": false,
        "Amount": 15700,
        "ReceivedDate": "2022-08-26 10:47:53",
        "CapturedAmount": 15700,
        "CapturedDate": "2022-08-26 10:47:54",
        "Status": 2,
        "IsSplitted": false,
        "ReturnMessage": "Operation Successful",
        "ReturnCode": "6",
        "PaymentId": "21c9a3e7-23c2-420b-b12d-b514ef271c85",
        "Type": "DebitCard",
        "Currency": "BRL",
        "Country": "BRA",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/21c9a3e7-23c2-420b-b12d-b514ef271c85"
            }
        ]
    }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2014121201",
    "Customer": {
        "Name": "Comprador Cartão de débito"
    },
    "Payment": {
        "DebitCard": {
            "CardNumber": "555187******0181",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Master",
            "PaymentAccountReference": "IC722LCXBROSHBPIBK7B44MBXO5HF"
        },
        "Provider": "Simulado",
        "AuthorizationCode": "635288",
        "Tid": "0826104754051",
        "ProofOfSale": "132471",
        "Authenticate": true,
        "ExternalAuthentication": {
            "Cavv": "AAABB2gHA1B5EFNjWQcDAAAAAAB=",
            "Xid": "Uk5ZanBHcWw2RjRCbEN5dGtiMTB=",
            "Eci": "5",
            "Version": "2",
            "ReferenceId": "a24a5d87-b1a1-4aef-a37b-2f30b91274e6"
        },
        "Recurrent": false,
        "Amount": 15700,
        "ReceivedDate": "2022-08-26 10:47:53",
        "CapturedAmount": 15700,
        "CapturedDate": "2022-08-26 10:47:54",
        "Status": 2,
        "IsSplitted": false,
        "ReturnMessage": "Operation Successful",
        "ReturnCode": "6",
        "PaymentId": "21c9a3e7-23c2-420b-b12d-b514ef271c85",
        "Type": "DebitCard",
        "Currency": "BRL",
        "Country": "BRA",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/21c9a3e7-23c2-420b-b12d-b514ef271c85"
            }
        ]
    }
}
Propriedade Descrição Tipo Tamanho Formato
AuthenticationUrl URL para qual o Lojista deve redirecionar o Cliente para o fluxo de Débito. Texto 56 Url de Autenticação
Tid Id da transação na adquirente. Texto 20 Texto alfanumérico
PaymentId Número de identificação do pagamento, necessário para futuras operações como Consulta, Captura e Cancelamento. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ReturnUrl Url de retorno do lojista. URL para onde o lojista vai ser redirecionado no final do fluxo. Texto 1024 http://www.urllogista.com.br
Status Status da Transação. Byte 0
ReturnCode Código de retorno da Adquirência. Texto 32 Texto alfanumérico
Payment.MerchantAdviceCode Código de retorno da bandeira que define período para retentativa. Válido somente para bandeira Mastercard. Texto 2 Numérico
DebitCard.PaymentAccountReference O PAR (Payment Account Reference) é o número que associa diferentes tokens a um mesmo cartão. Será retornado pelas bandeiras Master e Visa e repassado para os clientes do e-commerce Cielo. Caso a bandeira não envie a informação o campo não será retornado. Se for pra transação de crédito, colocar o campo dentro do nó de CreditCard Alfanumérico 29 -

Autenticando uma transação

A Cielo oferece o serviço do 3DS 2.0, um protocolo de autenticação de transações. A autenticação é opcional para transações de cartão de crédito, e obrigatória para cartão de débito, por determinação das bandeiras e emissores.

Para integrar a autenticação às suas transações:

  1. Integre o script do 3DS 2.0 na sua página de pagamento, conforme manual do 3DS;
  2. Na requisição das transações de crédito ou débito, envie o nó adicional ExternalAuthentication, conforme exemplos a seguir.

Cartão de crédito com autenticação

Requisição
{  
   "MerchantOrderId":"2014111701",
   "Customer":{  
      "Name":"Comprador crédito completo",
      "Email":"compradorteste@teste.com",
      "Birthdate":"1991-01-02",
      "Address":{  
         "Street":"Rua Teste",
         "Number":"123",
         "Complement":"AP 123",
         "ZipCode":"12345987",
         "City":"Rio de Janeiro",
         "State":"RJ",
         "Country":"BRA"
      },
        "DeliveryAddress": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "Billing": {
            "Street": "Rua Neturno",
            "Number": "12345",
            "Complement": "Sala 123",
            "Neighborhood": "Centro",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BR",
            "ZipCode": "20080123"
  },
   },
   "Payment":{  
     "Currency":"BRL",
     "Country":"BRA",
     "ServiceTaxAmount":0,
     "Installments":1,
     "Interest":"ByMerchant",
     "Capture":true,
     "Authenticate":"false",
     "Recurrent":"false",
     "SoftDescriptor":"123456789ABCD",
     "CreditCard":{  
         "CardNumber":"1234123412341231",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"123",
         "SaveCard":"false",
         "Brand":"Visa",
         "CardOnFile":{
            "Usage": "Used",
            "Reason":"Unscheduled"
         }
     },
     "IsCryptoCurrencyNegotiation": true,
     "Type":"CreditCard",
     "Amount":15700,
     "AirlineData":{
         "TicketNumber":"AR988983"
     }
   }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{  
   "MerchantOrderId":"2014111701",
   "Customer":{  
      "Name":"Comprador crédito completo",
      "Identity":"11225468954",
      "IdentityType":"CPF",
      "Email":"compradorteste@teste.com",
      "Birthdate":"1991-01-02",
      "Address":{  
         "Street":"Rua Teste",
         "Number":"123",
         "Complement":"AP 123",
         "ZipCode":"12345987",
         "City":"Rio de Janeiro",
         "State":"RJ",
         "Country":"BRA"
      },
        "DeliveryAddress": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "Billing": {
            "Street": "Rua Neturno",
            "Number": "12345",
            "Complement": "Sala 123",
            "Neighborhood": "Centro",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BR",
            "ZipCode": "20080123"
  },
   },
   "Payment":{  
     "ServiceTaxAmount":0,
     "Installments":1,
     "Interest":"ByMerchant",
     "Capture":true,
     "Authenticate":false,
     "Recurrent":"false",
     "SoftDescriptor":"123456789ABCD",
     "CreditCard":{  
         "CardNumber":"4551870000000183",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"123",
         "SaveCard":"false",
         "Brand":"Visa",
         "CardOnFile":{
            "Usage": "Used",
            "Reason":"Unscheduled"
         }
     },
     "IsCryptoCurrencyNegotiation": true,
     "Type":"CreditCard",
     "Amount":15700,
     "AirlineData":{
         "TicketNumber":"AR988983"
     }
   }
}
--verbose
Propriedade Tipo Tamanho Obrigatório Descrição
MerchantId Guid 36 Sim Identificador da loja na Cielo.
MerchantKey Texto 40 Sim Chave Publica para Autenticação Dupla na Cielo.
Content-Type Header 40 Sim application/json (obrigatório o envio deste).
RequestId Guid 36 Não Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT.
MerchantOrderId Texto 50 Sim Numero de identificação do Pedido.
Customer.Name Texto 255 Não Nome do Comprador.
Customer.Status Texto 255 Não Status de cadastro do comprador na loja (NEW / EXISTING)
Customer.Identity Texto 14 Não Número do RG, CPF ou CNPJ do Cliente.
Customer.IdentityType Texto 255 Não Tipo de documento de identificação do comprador (CFP/CNPJ).
Customer.Email Texto 255 Não Email do Comprador.
Customer.Birthdate Date 10 Não Data de nascimento do Comprador.
Customer.Address.Street Texto 255 Não Endereço do Comprador.
Customer.Address.Number Texto 15 Não Número do endereço do Comprador.
Customer.Address.Complement Texto 50 Não Complemento do endereço do Comprador.br
Customer.Address.ZipCode Texto 9 Não CEP do endereço do Comprador.
Customer.Address.City Texto 50 Não Cidade do endereço do Comprador.
Customer.Address.State Texto 2 Não Estado do endereço do Comprador.
Customer.Address.Country Texto 35 Não Pais do endereço do Comprador.
Customer.DeliveryAddress.Street Texto 255 Não Endereço do Comprador.
Customer.Address.Number Texto 15 Não Número do endereço do Comprador.
Customer.DeliveryAddress.Complement Texto 50 Não Complemento do endereço do Comprador.
Customer.DeliveryAddress.ZipCode Texto 9 Não CEP do endereço do Comprador.
Customer.DeliveryAddress.City Texto 50 Não Cidade do endereço do Comprador.
Customer.DeliveryAddress.State Texto 2 Não Estado do endereço do Comprador.
Customer.DeliveryAddress.Country Texto 35 Não País do endereço do Comprador.
Payment.Type Texto 100 Sim Tipo do Meio de Pagamento.
Payment.Amount Número 15 Sim Valor do Pedido (ser enviado em centavos).
Payment.Currency Texto 3 Não Moeda na qual o pagamento será feito (BRL).
Payment.Country Texto 3 Não Pais na qual o pagamento será feito.
Payment.Provider Texto 15 Define comportamento do meio de pagamento (ver Anexo)/NÃO OBRIGATÓRIO PARA CRÉDITO.
Payment.ServiceTaxAmount Número 15 Não Aplicável apenas para empresas aéreas. Montante do valor da autorização que deve ser destinado à taxa de serviço. Obs.: Esse valor não é adicionado ao valor da autorização.
Payment.SoftDescriptor Texto 13 Não O complemento do nome da loja que aparecerá na fatura do cartão. Não permite caracteres especiais.
Payment.Installments Número 2 Sim Número de Parcelas.
Payment.Interest Texto 10 Não Tipo de parcelamento - Loja (ByMerchant) ou Cartão (ByIssuer).
Payment.Capture Booleano Não (Default false) Booleano que identifica que a autorização deve ser com captura automática.
Payment.Authenticate Booleano Não (Default false) Define se o comprador será direcionado ao Banco emissor para autenticação do cartão
Payment.Recurrent Booleano - Não Indica se a transação é do tipo recorrente (“true”) ou não (“false”). O valor “true” não originará uma nova recorrência, apenas permitirá a realização de uma transação sem a necessidade de envio do CVV. Authenticate deve ser “false” quando Recurrent é “true”.
Payment.IsCryptocurrencyNegotiation Booleano - Não (default false) Deve ser enviado com valor “true” caso se trate de uma transação de compra ou venda de Criptomoeda
Payment.AirlineData.TicketNumber alfanumérico 13 Não Informar o número do principal bilhete aéreo da transação.
CreditCard.CardNumber Texto 19 Sim Número do Cartão do Comprador.
CreditCard.Holder Texto 25 Não Nome do Comprador impresso no cartão. Não aceita caracteres especiais ou acentuação.
CreditCard.ExpirationDate Texto 7 Sim Data de validade impressa no cartão. Ex. MM/AAAA.
CreditCard.SecurityCode Texto 4 Não Código de segurança impresso no verso do cartão.
CreditCard.SaveCard Booleano Não (Default false) Booleano que identifica se o cartão será salvo para gerar o CardToken.
CreditCard.Brand Texto 10 Sim Bandeira do cartão. Valores possíveis: Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard / Hiper.
CreditCard.CardOnFile.Usage Texto - Não First se o cartão foi armazenado e é seu primeiro uso.
Used se o cartão foi armazenado e ele já foi utilizado anteriormente em outra transação
CreditCard.CardOnFile.Reason Texto - Condicional Indica o propósito de armazenamento de cartões, caso o campo “Usage” for “Used”.
Recurring - Compra recorrente programada (ex. assinaturas)
Unscheduled - Compra recorrente sem agendamento (ex. aplicativos de serviços)
Installments - Parcelamento através da recorrência.
Resposta
{
    "MerchantOrderId": "2014111706",
    "Customer": {
        "Name": "Comprador crédito completo",
        "Identity":"11225468954",
        "IdentityType":"CPF",
        "Email": "compradorteste@teste.com",
        "Birthdate": "1991-01-02",
        "Address": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "DeliveryAddress": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "Billing": {
            "Street": "Rua Neturno",
            "Number": "12345",
            "Complement": "Sala 123",
            "Neighborhood": "Centro",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BR",
            "ZipCode": "20080123"
  },
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": true,
        "Authenticate": false,
        "CreditCard": {
            "CardNumber": "455187******0183",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa",
            "PaymentAccountReference":"92745135160550440006111072222",
         "CardOnFile":{
            "Usage": "Used",
            "Reason":"Unscheduled"
         }
        },
        "IsCryptoCurrencyNegotiation": true,
        "TryAutomaticCancellation":true,
        "ProofOfSale": "674532",
        "Tid": "0305020554239",
        "AuthorizationCode": "123456",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "CreditCard",
        "Amount": 15700,
        "CapturedAmount": 15700,
        "Country": "BRA",
        "AirlineData":{
            "TicketNumber": "AR988983"
        },
        "ExtraDataCollection": [],
        "Status": 2,
        "ReturnCode": "6",
        "ReturnMessage": "Operation Successful",
        "Payment.MerchantAdviceCode":"1",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2014111706",
    "Customer": {
        "Name": "Comprador crédito completo",
        "Identity":"11225468954",
        "IdentityType":"CPF",
        "Email": "compradorteste@teste.com",
        "Birthdate": "1991-01-02",
        "Address": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "DeliveryAddress": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "Billing": {
            "Street": "Rua Neturno",
            "Number": "12345",
            "Complement": "Sala 123",
            "Neighborhood": "Centro",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BR",
            "ZipCode": "20080123"
  },
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": true,
        "Authenticate": false,
        "CreditCard": {
            "CardNumber": "455187******0183",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa",
            "PaymentAccountReference":"92745135160550440006111072222",
         "CardOnFile":{
            "Usage": "Used",
            "Reason":"Unscheduled"
         }
        },
        "IsCryptoCurrencyNegotiation": true,
        "TryAutomaticCancellation":true,
        "ProofOfSale": "674532",
        "Tid": "0305020554239",
        "AuthorizationCode": "123456",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "CreditCard",
        "Amount": 15700,
        "CapturedAmount": 15700,
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 2,
        "ReturnCode": "6",
        "ReturnMessage": "Operation Successful",
        "Payment.MerchantAdviceCode":"1",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
Propriedade Descrição Tipo Tamanho Formato
ProofOfSale Número da autorização, identico ao NSU. Texto 6 Texto alfanumérico
Tid Id da transação na adquirente. Texto 20 Texto alfanumérico
AuthorizationCode Código de autorização. Texto 6 Texto alfanumérico
SoftDescriptor Texto impresso na fatura bancaria do portador. Não permite caracteres especiais. Texto 13 Texto alfanumérico
PaymentId Número de identificação do pagamento, necessário para futuras operações como Consulta, Captura e Cancelamento. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ECI Eletronic Commerce Indicator. Representa o quão segura é uma transação. Texto 2 Exemplos: 7
Status Status da Transação. Byte 2
ReturnCode Código de retorno da Adquirência. Texto 32 Texto alfanumérico
ReturnMessage Mensagem de retorno da Adquirência. Texto 512 Texto alfanumérico
Payment.MerchantAdviceCode Código de retorno da bandeira que define período para retentativa. Válido somente para bandeira Mastercard. Texto 2 Numérico
TryAutomaticCancellation Caso ocorra algum erro durante a autorização (status Não Finalizada - “0”), a resposta incluirá o campo “TryAutomaticCancellation” como true. Neste caso, a transação será consultada automaticamente, e caso tenha sido autorizada será cancelada automaticamente. Esta funcionalidade deverá estar habilitada para loja. Para habilitar, entre em contato com o nosso suporte técnico. Booleano - true ou false
CreditCard.PaymentAccountReference O PAR (Payment Account Reference) é o número que associa diferentes tokens a um mesmo cartão. Será retornado pelas bandeiras Master e Visa e repassado para os clientes do e-commerce Cielo. Caso a bandeira não envie a informação o campo não será retornado.Se for pra transação de débito, colocar o campo dentro do nó de DebitCard Alfanumérico 29

Cartão de débito com autenticação

A transação de débito com autenticação é o padrão para esse meio de pagamento. Siga os passos de integração do manual do 3DS e envie a requisição conforme apresentada em Criando uma Transação de Débito.

MPI Externo

O Merchant plug-in, conhecido por MPI, é um serviço que permite a realização da chamada de autenticação, integrado e certificado com bandeiras para processamento de autenticação de 3DS. A Cielo permite ao lojista a integração do 3DS através do MPI Interno ou do MPI Externo.

Cartões Alelo

Para criar uma venda que utilizará cartão de Alelo, é use a mesma requisição de uma venda de cartão de débito.

OBS: Em transações de Cartão ALELO, os seguintes parâmetros devem possuir configurações estáticas:

Requisição

{  
   "MerchantOrderId":"2014121201",
   "Customer":{  
      "Name":"Comprador Cartão de Alelo"
   },
   "Payment":{  
     "Type":"DebitCard",
     "Authenticate":false,
     "Amount":50,
     "ReturnUrl":"http://www.cielo.com.br",
     "DebitCard":{  
         "CardNumber":"5080540487508044",
         "Holder":"Comprador Cartão de Alelo",
         "ExpirationDate":"07/2029",
         "SecurityCode":"841",
         "brand": "Elo"
     }
   }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{  
   "MerchantOrderId":"2014121201",
   "Customer":{  
      "Name":"Comprador Cartão de Alelo"
   },
   "Payment":{  
     "Type":"DebitCard",
     "Authenticate":false,
     "Amount":50,
     "ReturnUrl":"http://www.cielo.com.br",
     "DebitCard":{  
         "CardNumber":"5080540487508044",
         "Holder":"Comprador Cartão de Alelo",
         "ExpirationDate":"07/2029",
         "SecurityCode":"841",
         "brand": "Elo"
     }
   }
}
 
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API Cielo eCommerce. Guid 36 Sim
MerchantKey Chave Pública para Autenticação Dupla na API Cielo eCommerce. Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
MerchantOrderId Número de identificação do Pedido. Texto 50 Sim
Customer.Name Nome do Comprador. Texto 255 Não
Payment.Authenticate Define se o comprador será direcionado ao Banco emissor para autenticação do cartão. Valor possível: “false” ou não enviar. Booleano Não (default =”false”)
Payment.Type Tipo do Meio de Pagamento Texto 100 Sim
Payment.Amount Valor do Pedido (ser enviado em centavos). Número 15 Sim
Payment.ReturnUrl URL de retorno do lojista. Texto 1024 Sim
Payment.ReturnUrl URL para onde o usuário será redirecionado após o fim do pagamento Texto 1024 Sim
DebitCard.CardNumber Número do cartão do comprador. Texto 19 Sim
DebitCard.Holder Nome do comprador impresso no cartão. Texto 25 Sim
DebitCard.ExpirationDate Data de validade impressa no cartão. Ex. MM/AAAA. Texto 7 Sim
DebitCard.SecurityCode Código de segurança impresso no verso do cartão. Texto 4 Sim
DebitCard.Brand Bandeira do cartão. Precisa ser enviada como “ELO”. Texto 10 Sim

Resposta

{
    "MerchantOrderId": "2014121201",
    "Customer": {
        "Name": "Comprador Cartão de Alelo"
    },
    "Payment": {
        "DebitCard": {
            "CardNumber": "508054******8044",
            "Holder": "Comprador Cartão de Alelo",
            "ExpirationDate": "07/2029",
            "SaveCard": false,
            "Brand": "Elo"
        },
        "Provider": "Cielo",
        "AuthorizationCode": "803247",
        "Eci": "7",
        "Tid": "107703563079N41O9DJB",
        "ProofOfSale": "770857",
        "Authenticate": false,
        "Recurrent": false,
        "Amount": 50,
        "ReceivedDate": "2018-01-30 15:00:24",
        "CapturedAmount": 50,
        "CapturedDate": "2018-01-30 15:00:25",
        "ReturnUrl": "http://www.cielo.com.br",
        "Status": 2,
        "IsSplitted": false,
        "ReturnMessage": "Transacao capturada com sucesso",
        "ReturnCode": "00",
        "PaymentId": "f8504766-4ae4-4a1f-811f-035964b6c4ee",
        "Type": "DebitCard",
        "Currency": "BRL",
        "Country": "BRA",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquery.cieloecommerce.cielo.com.br/1/sales/f8504766-4ae4-4a1f-811f-035964b6c4ee"
            }
        ]
    }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
{
    "MerchantOrderId": "2014121201",
    "Customer": {
        "Name": "Comprador Cartão de Alelo"
    },
    "Payment": {
        "DebitCard": {
            "CardNumber": "508054******8044",
            "Holder": "Comprador Cartão de Alelo",
            "ExpirationDate": "07/2029",
            "SaveCard": false,
            "Brand": "Elo"
        },
        "Provider": "Cielo",
        "AuthorizationCode": "803247",
        "Eci": "7",
        "Tid": "107703563079N41O9DJB",
        "ProofOfSale": "770857",
        "Authenticate": false,
        "Recurrent": false,
        "Amount": 50,
        "ReceivedDate": "2018-01-30 15:00:24",
        "CapturedAmount": 50,
        "CapturedDate": "2018-01-30 15:00:25",
        "ReturnUrl": "http://www.cielo.com.br",
        "Status": 2,
        "IsSplitted": false,
        "ReturnMessage": "Transacao capturada com sucesso",
        "ReturnCode": "00",
        "PaymentId": "f8504766-4ae4-4a1f-811f-035964b6c4ee",
        "Type": "DebitCard",
        "Currency": "BRL",
        "Country": "BRA",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquery.cieloecommerce.cielo.com.br/1/sales/f8504766-4ae4-4a1f-811f-035964b6c4ee"
            }
        ]
    }
}
Propriedade Descrição Tipo Tamanho Formato
Tid ID da transação na adquirente. Texto 20 Texto alfanumérico
PaymentId Campo Identificador do Pedido. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ReturnUrl URL de retorno do lojista. URL para onde o lojista vai ser redirecionado no final do fluxo. Texto 1024 http://www.urllogista.com.br
Status Status da Transação Byte 0
ReturnCode Código de retorno da Adquirência. Texto 32 Texto alfanumérico

Pix

No pix, a transmissão da ordem de pagamento e a disponibilidade de fundos para o recebedor ocorrem em tempo real, 24 horas por dia e sem a necessidade de intermediários. Sendo assim, é um meio que viabiliza pagamentos rápidos e com menores custos de transação.

Conheça o ciclo de vida de uma transação pix:

SEQUÊNCIA RESPONSÁVEL DESCRIÇÃO STATUS DA TRANSAÇÃO
1 Loja Geração do QR code. 12 - Pendente
2 Comprador Pagamento do QR code. 2 - Pago
3 Loja Recebimento da notificação de confirmação do pagamento. 2 - Pago
4 Loja Consulta ao status da transação. 2 - Pago
5 Loja Liberação do pedido. 2 - Pago
6 Loja Caso necessário, solicitação da devolução da transação Pix (semelhante ao estorno do cartão). 2 - Pago
7 Loja Recebimento da notificação de confirmação de devolução. 11 - Estornado
8 Loja Consulta ao status da transação. 11 - Estornado

ATENÇÃO:

  • Para habilitar o pix no ambiente sandbox entre em contato com nosso canal de suporte e-commerce pelo e-mail cieloecommerce@cielo.com.br;

  • Antes de usar o Pix em produção, certifique-se de que o pix está liberado em seu cadastro. Para confirmar basta acessar o portal Cielo na área logada em Meu Cadastro > Autorizações > PIX
    Geração do QR Code Pix

Criando uma transação com QR Code Pix

Para gerar um QR code Pix através da API Cielo E-commerce, basta realizar a integração conforme a especificação a seguir.

O campo obrigatório Payment.Type deve ser enviado como “Pix”. Na resposta da requisição será retornado o código base64 da imagem do QR code Pix, que você deverá disponibilizar ao comprador.

Confira a representação do fluxo transacional na geração do QR code pix:

Geração do QR Code Pix

O comprador então realiza a leitura do QR code através de um dos aplicativos habilitados para o pagamento pix e efetiva o pagamento. Nesta etapa não há participação da loja nem da API E-commerce Cielo, conforme demonstrado no fluxo:

Pagamento Pix

Veja exemplos de envio de requisição e resposta para a geração do QR code pix:

Requisição

{ 
   "MerchantOrderId":"2020102601",
   "Customer":{
      "Name":"Nome do Pagador",
      "Identity":"12345678909",
      "IdentityType":"CPF"
   },
   "Payment":{ 
      "Type":"Pix",
      "Amount":100
   }    
}
--request POST "https://(...)/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{ 
   "MerchantOrderId":"2020102601",
   "Customer":{
      "Name":"Nome do Pagador",
      "Identity":"CPF",
      "IdentityType":"12345678909"
   },
   "Payment":{ 
      "Type":"Pix",
      "Amount":100
   }    
}
--verbose
PROPRIEDADE DESCRIÇÃO TIPO TAMANHO OBRIGATÓRIO?
MerchantOrderId Número de identificação do pedido. Texto 50 Sim
Customer.Name Nome do pagador. Texto 255 Sim
Customer.Identity Número do CPF ou CNPJ do cliente. Texto 14 Sim
Customer.IdentityType Tipo de documento de identificação do comprador (CPF ou CNPJ). Texto 255 Sim
Payment.Type Tipo do meio de pagamento. Neste caso, “Pix”. Texto - Sim
Payment.Amount Valor do pedido, em centavos. Número 15 Sim

Resposta

{
   "MerchantOrderId":"2020102601",
   "Customer":{
      "Name":"Nome do Pagador"
   },
   "Payment":{
      (...)   
      "Paymentid":"1997be4d-694a-472e-98f0-e7f4b4c8f1e7",
      "Type":"Pix",
      "AcquirerTransactionId":"86c200c7-7cdf-4375-92dd-1f62dfa846ad",
         "ProofOfSale":"123456",
      "QrcodeBase64Image":"rfhviy64ak+zse18cwcmtg==[...]",
      "QrCodeString":"00020101021226880014br.gov.bcb.pix2566qrcodes-h.cielo.com.br/pix-qr/d05b1a34-ec52-4201-ba1e-d3cc2a43162552040000530398654041.005802BR5918Merchant Teste HML6009Sao Paulo62120508000101296304031C",
      "Amount":100,
      "ReceivedDate":"2020-10-15 18:53:20",
      "Status":12,
      "ReturnCode":"0",
      "ReturnMessage":"Pix gerado com sucesso",
      (...)
   }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
   "MerchantOrderId":"2020102601",
   "Customer":{
      "Name":"Nome do Pagador"
   },
   "Payment":{
      (...)
      "PaymentId":"1997be4d-694a-472e-98f0-e7f4b4c8f1e7",
      "Type":"Pix",
      "AcquirerTransactionId":"86c200c7-7cdf-4375-92dd-1f62dfa846ad",
         "ProofOfSale":"123456",
      "QrcodeBase64Image":"rfhviy64ak+zse18cwcmtg==[...]",
      "QrCodeString":"00020101021226880014br.gov.bcb.pix2566qrcodes-h.cielo.com.br/pix-qr/d05b1a34-ec52-4201-ba1e-d3cc2a43162552040000530398654041.005802BR5918Merchant Teste HML6009Sao Paulo62120508000101296304031C",
      "Amount":100,
      "ReceivedDate":"2020-10-15 18:53:20",
      "Status":12,
      "ReturnCode":"0",
      "ReturnMessage":"Pix gerado com sucesso",
      (...)
   }
}
--verbose
PROPRIEDADE DESCRIÇÃO TIPO TAMANHO FORMATO
Payment.PaymentId Campo identificador do pedido. GUID 40 Texto
Payment.AcquirerTransactionId Id da transação no provedor de meio de pagamento. GUID 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Payment.ProofOfSale NSU Pix. Texto 20 Texto alfanumérico
Payment.QrcodeBase64Image Código em base64 da imagem do QR code. Texto - Texto
Payment.QrCodeString Texto codificado para o comprador “copiar” e “colar” no campo do internet banking em pagamentos feitos no ambiente mobile. Texto Variável Texto alfanumérico
Payment.Status Status da transação. Em caso de sucesso, o status inicial é “12” (Pendente). Clique aqui para ver lista de status. Número - 12
Payment.ReturnCode Código retornado pelo provedor do meio de pagamento. Texto 32 0
Payment.ReturnMessage Mensagem retornada pelo provedor do meio de pagamento. Texto 512 “Pix gerado com sucesso”

Solicitando uma devolução pix

Caso a sua loja precise cancelar uma transferência pix, é possível realizar uma operação chamada de devolução. É importante ressaltar que a devolução não é uma operação instantânea, podendo ser acatada ou não pelo provedor pix. Quando uma devolução é acatada, uma notificação será enviada para a sua loja.

Importante:

  • A devolução ocorrerá somente se houver saldo;
  • O prazo para cancelamento é de 90 dias, conforme especificação do BACEN.

Requisição

--request PUT "https://(...)/sales/{PaymentId}/void?Amount=xxx"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API. GUID 36 Sim
MerchantKey Chave pública para autenticação dupla na API. Texto 40 Sim
RequestId Identificador do request definido pela loja, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT. GUID 36 Não
PaymentId Campo identificador do pedido. GUID 36 Sim
Amount Valor a ser cancelado/estornado, em centavos. Verifique se a adquirente contratada suporta a operação de cancelamento ou estorno. Número 15 Não

Resposta

{
   "Status": 12,
   "ReasonCode": 0,
   "ReasonMessage": "Successful",
   "ReturnCode": "0",
   "ReturnMessage": "Reembolso solicitado com sucesso",
   "Links": [
      {
         "Method": "GET",
         "Rel": "self",
         "Href": "https://(...)/sales/{PaymentId}"
      }
   ]
}
{
   "Status": 12,
   "ReasonCode": 0,
   "ReasonMessage": "Successful",
   "ReturnCode": "0",
   "ReturnMessage": "Reembolso solicitado com sucesso",
   "Links": [
      {
         "Method": "GET",
         "Rel": "self",
         "Href": "https://(...)/sales/{PaymentId}"
      }
   ]
}
Propriedade Descrição Tipo Tamanho Formato
Status Status da transação. Byte 2 Ex.: “1”
ReasonCode Código de retorno da adquirência. Texto 32 Texto alfanumérico
ReasonMessage Mensagem de retorno da adquirência. Texto 512 Texto alfanumérico

Boleto

Para transacionar por boleto, você precisa primeiro contratar esse serviço com o banco. Em seguida, configure o meio de pagamento boleto de acordo com as orientações do manual Boletos.

Observação: Os boletos do Banco do Brasil não possuem o serviço de conciliação automática.

Requisição

{  
    "MerchantOrderId":"2014111706",
    "Customer":
    {  
        "Name":"Comprador Teste Boleto",
        "Identity": "1234567890",
        "Address":
        {
          "Street": "Avenida Marechal Câmara",
          "Number": "160",    
          "Complement": "Sala 934",
          "ZipCode" : "22750012",
          "District": "Centro",
          "City": "Rio de Janeiro",
          "State" : "RJ",
          "Country": "BRA"
        },
        "Billing": {
           "Street": "Avenida Marechal Câmara",
           "Number": "160",
           "Complement": "Sala 934",
           "Neighborhood": "Centro",
           "City": "Rio de Janeiro",
           "State": "RJ",
           "Country": "BR",
           "ZipCode": "22750012"
  },
    },
    "Payment":
    {  
        "Type":"Boleto",
        "Amount":15700,
        "Provider":"Bradesco2",
        "Address": "Rua Teste",
        "BoletoNumber": "123",
        "Assignor": "Empresa Teste",
        "Demonstrative": "Desmonstrative Teste",
        "ExpirationDate": "2020-12-31",
        "Identification": "11884926754",
        "Instructions": "Aceitar somente até a data de vencimento, após essa data juros de 1% dia."
    }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{  
    "MerchantOrderId":"2014111706",
    "Customer":
    {  
        "Name":"Comprador Teste Boleto",
        "Identity": "1234567890",
        "Address":
        {
          "Street": "Avenida Marechal Câmara",
          "Number": "160",    
          "Complement": "Sala 934",
          "ZipCode" : "22750012",
          "District": "Centro",
          "City": "Rio de Janeiro",
          "State" : "RJ",
          "Country": "BRA"
        },
        "Billing": {
           "Street": "Avenida Marechal Câmara",
           "Number": "160",
           "Complement": "Sala 934",
           "Neighborhood": "Centro",
           "City": "Rio de Janeiro",
           "State": "RJ",
           "Country": "BR",
           "ZipCode": "22750012"
  },
    },
    "Payment":
    {  
        "Type":"Boleto",
        "Amount":15700,
        "Provider":"Bradesco2",
        "Address": "Rua Teste",
        "BoletoNumber": "123",
        "Assignor": "Empresa Teste",
        "Demonstrative": "Desmonstrative Teste",
        "ExpirationDate": "2020-12-31",
        "Identification": "11884926754",
        "Instructions": "Aceitar somente até a data de vencimento, após essa data juros de 1% dia."
    }
}
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API Cielo eCommerce. Guid 36 Sim
MerchantKey Chave Publica para Autenticação Dupla na API Cielo eCommerce. Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
MerchantOrderId Numero de identificação do Pedido. Texto Bradesco: 27
Banco do Brasil: 50
Sim
Customer.Name Nome do Comprador. Texto Bradesco: 34
Banco do Brasil: 60
Não
Customer.Status Status de cadastro do comprador na loja(NEW / EXISTING) - Utilizado pela análise de fraude Texto 255 Não
Customer.Address.ZipCode CEP do endereço do Comprador. Texto 9 Sim
Customer.Address.Country Pais do endereço do Comprador. Texto 35 Sim
Customer.Address.State Estado do endereço do Comprador. Texto 2 Sim
Customer.Address.City Cidade do endereço do Comprador. Texto Bradesco: 50
Banco do Brasil: 18
Sim
Customer.Address.District Bairro do Comprador. Texto 50 Sim
Customer.Address.Street Endereço do Comprador. Texto 255 Sim
Customer.Address.Number Número do endereço do Comprador. Texto 15 Sim
Customer.Billing.Street Logradouro do endereço de cobrança string 24 não
Customer.Billing.Number Número do endereço de cobrança string 5 não
Customer.Billing.Complement Complemento do endereço de cobrança string 14 não
Customer.Billing.Neighborhood Bairro do endereço de cobrança string 15 não
Customer.Billing.City Cidade do endereço de cobranças tring 20 não
Customer.Billing.State Estado do endereço de cobrança string 2 não
Customer.Billing.Country País do endereço de cobrança. Mais informações em ISO 2-Digit Alpha Country Code string 2 não
Customer.Billing.ZipCode Código postal do endereço de cobrança string 9 não
Payment.Type Tipo do Meio de Pagamento. Texto 100 Sim
Payment.Amount Valor do Pedido (ser enviado em centavos). Número 15 Sim
Payment.Provider Define comportamento do meio de pagamento (ver Anexo)/NÃO OBRIGATÓRIO PARA CRÉDITO. Valores possíveis: “Bradesco2” ou “BancoDoBrasil2” Texto 15 Sim
Payment.Address Endereço do Cedente. Texto 255 Não
Payment.BoletoNumber Número do Boleto enviado pelo lojista. Usado para contar boletos emitidos (“NossoNumero”). Número Bradesco: 11
Banco do Brasil: 9
Não
Payment.Assignor Nome do Cedente. Texto 200 Não
Payment.Demonstrative Texto de Demonstrativo. Texto 255 Não
Payment.ExpirationDate Data de expiração do Boleto. Ex. 2020-12-31 Date 10 Não
Payment.Identification Documento de identificação do Cedente. Texto 14 Não
Payment.Instructions Instruções do Boleto. Texto 255 Não

Resposta

Na resposta da transação de boleto, a API Cielo E-commerce vai enviar a URL do boleto e o código de barras, que o e-commerce deverá exibir para o comprador.

{
    "MerchantOrderId": "2014111706",
    "Customer":
    {
        "Name": "Comprador Boleto Completo",
        "Address":
        {
        "Street": "Av Marechal Camara",
        "Number": "160",
        "ZipCode": "22750012",
        "City": "Rio de Janeiro",
        "State": "RJ",
        "Country": "BRA",
        "District": "Centro"
        },
      "Billing": {
         "Street": "Avenida Marechal Câmara",
         "Number": "160",
         "Complement": "Sala 934",
         "Neighborhood": "Centro",
         "City": "Rio de Janeiro",
         "State": "RJ",
         "Country": "BR",
         "ZipCode": "22750012"
  },
    },
    "Payment":
    {
        "Instructions": "Aceitar somente até a data de vencimento, após essa data juros de 1% dia.",
        "ExpirationDate": "2015-01-05",
        "Url": "https://apisandbox.cieloecommerce.cielo.com.br/post/pagador/reenvia.asp/a5f3181d-c2e2-4df9-a5b4-d8f6edf6bd51",
        "Number": "123-2",
        "BarCodeNumber": "00096629900000157000494250000000012300656560",
        "DigitableLine": "00090.49420 50000.000013 23006.565602 6 62990000015700",
        "Assignor": "Empresa Teste",
        "Address": "Rua Teste",
        "Identification": "11884926754",
        "PaymentId": "a5f3181d-c2e2-4df9-a5b4-d8f6edf6bd51",
        "Type": "Boleto",
        "Amount": 15700,
        "Currency": "BRL",
        "Country": "BRA",
        "Provider": "Bradesco2",
        "ExtraDataCollection": [],
        "Status": 1,
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            }
        ]
    }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2014111706",
    "Customer":
    {
        "Name": "Comprador Boleto Completo",
        "Address":
        {
        "Street": "Av Marechal Camara",
        "Number": "160",
        "ZipCode": "22750012",
        "City": "Rio de Janeiro",
        "State": "RJ",
        "Country": "BRA",
        "District": "Centro"
        },
      "Billing": {
         "Street": "Avenida Marechal Câmara",
         "Number": "160",
         "Complement": "Sala 934",
         "Neighborhood": "Centro",
         "City": "Rio de Janeiro",
         "State": "RJ",
         "Country": "BR",
         "ZipCode": "22750012"
    },
    "Payment":
    {
        "Instructions": "Aceitar somente até a data de vencimento, após essa data juros de 1% dia.",
        "ExpirationDate": "2015-01-05",
        "Url": "https://apisandbox.cieloecommerce.cielo.com.br/post/pagador/reenvia.asp/a5f3181d-c2e2-4df9-a5b4-d8f6edf6bd51",
        "Number": "123-2",
        "BarCodeNumber": "00096629900000157000494250000000012300656560",
        "DigitableLine": "00090.49420 50000.000013 23006.565602 6 62990000015700",
        "Assignor": "Empresa Teste",
        "Address": "Rua Teste",
        "Identification": "11884926754",
        "PaymentId": "a5f3181d-c2e2-4df9-a5b4-d8f6edf6bd51",
        "Type": "Boleto",
        "Amount": 15700,
        "Currency": "BRL",
        "Country": "BRA",
        "Provider": "Bradesco2",
        "ExtraDataCollection": [],
        "Status": 1,
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            }
        ]
    }
}
Propriedade Descrição Tipo Tamanho Formato
PaymentId Número de identificação do pagamento, necessário para futuras operações como Consulta, Captura e Cancelamento. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Instructions Instruções do Boleto. Texto 255 Ex: Aceitar somente até a data de vencimento, após essa data juros de 1% dia.
ExpirationDate Data de expiração. Texto 10 2014-12-25
Url Url do Boleto gerado. string 256 Ex:https://…/pagador/reenvia.asp/8464a692-b4bd-41e7-8003-1611a2b8ef2d
Number “NossoNumero” gerado. Texto 50 Ex: 1000000012-8
BarCodeNumber Representação numérica do código de barras. Texto 44 Ex: 00091628800000157000494250100000001200656560
DigitableLine Linha digitável. Texto 256 Ex: 00090.49420 50100.000004 12006.565605 1 62880000015700
Assignor Nome do Cedente. Texto 256 Ex: Loja Teste
Address Endereço do Cedente. Texto 256 Ex: Av. Teste, 160
Identification Documento de identificação do Cedente. Texto 14 CPF ou CNPJ do Cedente sem os caracteres especiais (., /, -)
Status Status da Transação. Byte 1

Regras Adicionais

Quantidade de caracteres por campo e Provider:

Bradesco

Propriedade Observações Tamanho
Provider N/a Bradesco2
MerchantOrderId Apenas Letras, números e caracteres como “_” e “$”. 27
Payment.BoletoNumber O dado é validado pelo banco. 11
Customer.Name A API Cielo trunca automaticamente. 34
Customer.Address.Street O dado é validado pela API Cielo. 70
Customer.Address.Number O dado é validado pela API Cielo. 10
Customer.Address.Complement O dado é validado pela API Cielo. 20
Customer.Address.District O dado é validado pela API Cielo. 50
Customer.Address.City O dado é validado pela API Cielo. 50
Payment.Instructions N/a 255
Payment.Demonstrative N/a 255

Banco do Brasil

Propriedade Observações Tamanho
Provider N/a BancoDoBrasil2
MerchantOrderId Não é enviado ao banco. 50
Payment.BoletoNumber Quando enviado acima de 9 posições, a API Cielo trunca automaticamente, considerando os últimos 9 dígitos. 9
Customer.Name Caracteres válidos:
Letras de A a Z - MAIÚSCULAS
Caracteres especiais: hífen (-) e apóstrofo (‘)
Quando utilizados, não pode conter espaços entre as letras;
Exemplos corretos: D’EL-REI, D’ALCORTIVO, SANT’ANA.
Exemplos incorretos: D’EL - REI; até um espaço em branco entre palavras.
60
Customer.Address.Street Caracteres válidos:
Letras de A a Z - MAIÚSCULAS
Caracteres especiais: hífen (-) e apóstrofo (‘)
Quando utilizados, não pode conter espaços entre as letras;
Exemplos corretos: D’EL-REI, D’ALCORTIVO, SANT’ANA.
Exemplos incorretos: D’EL - REI; até um espaço em branco entre palavras
Os campos Customer.Address.Street; Customer.Address.Number; Customer.Address.Complement; Customer.Address.District devem totalizar até 60 caracteres.
Customer.Address.Number Caracteres válidos:
Letras de A a Z - MAIÚSCULAS
Caracteres especiais: hífen (-) e apóstrofo (‘)
Quando utilizados, não pode conter espaços entre as letras;
Exemplos corretos: D’EL-REI, D’ALCORTIVO, SANT’ANA.
Exemplos incorretos: D’EL - REI; até um espaço em branco entre palavras
Os campos Customer.Address.Street; Customer.Address.Number; Customer.Address.Complement; Customer.Address.District devem totalizar até 60 caracteres.
Customer.Address.Complement Caracteres válidos:
Letras de A a Z - MAIÚSCULAS
Caracteres especiais: hífen (-) e apóstrofo (‘)
Quando utilizados, não pode conter espaços entre as letras;
Exemplos corretos: D’EL-REI, D’ALCORTIVO, SANT’ANA.
Exemplos incorretos: D’EL - REI; até um espaço em branco entre palavras
Os campos Customer.Address.Street; Customer.Address.Number; Customer.Address.Complement; Customer.Address.District devem totalizar até 60 caracteres.
Customer.Address.District Caracteres válidos:
Letras de A a Z - MAIÚSCULAS
Caracteres especiais: hífen (-) e apóstrofo (‘)
Quando utilizados, não pode conter espaços entre as letras;
Exemplos corretos: D’EL-REI, D’ALCORTIVO, SANT’ANA.
Exemplos incorretos: D’EL - REI; até um espaço em branco entre palavras
Os campos Customer.Address.Street; Customer.Address.Number; Customer.Address.Complement; Customer.Address.District devem totalizar até 60 caracteres.
Customer.Address.City
Caracteres válidos:
Letras de A a Z - MAIÚSCULAS
Caracteres especiais: hífen (-) e apóstrofo (‘)
Quando utilizados, não pode conter espaços entre as letras;
Exemplos corretos: D’EL-REI, D’ALCORTIVO, SANT’ANA.
Exemplos incorretos: D’EL - REI; até um espaço em branco entre palavras.
18 caracteres
Payment.Instructions N/a 255

E-wallets

O que são e-wallets?

As e-wallets, ou carteiras digitais, são repositórios de cartões e dados de pagamentos para consumidores online. As e-wallets permitem que um consumidor realize o cadastro de seus dados de pagamento na carteira, tornando o processo de compra mais conveniente e seguro.

Para utilizar e-wallets na API Cielo E-commerce, o lojista deverá ter as e-wallets integradas em seu checkout.

Entre em contato com o provedor de sua preferência para maiores informações sobre como contratar o serviço.

E-wallets disponíveis

A API Cielo E-commerce possui suporte para as seguintes carteiras digitais:

Integração da E-Wallet

Consulte nosso manual E-Wallets e saiba mais detalhes sobre a integração desse meio de pagamento em seu checkout.

Com a e-wallet já totalmente integrada, o seu fluxo transacional de pagamento será o seguinte:

Fluxo E-wallets

QR Code

Cartão de crédito via QR Code - Sandbox

Para testar o cenário de autorização com sucesso via QRCode, utilize o cartão 4551.8700.0000.0183

As informações de Cód.Segurança (CVV) e validade podem ser aleatórias, mantendo o formato:

Gerando um QR Code via API

Para criar uma transação que utilizará cartão de crédito, é necessário enviar uma requisição utilizando o método POST para o recurso Payment, conforme o exemplo. Esse exemplo contempla o mínimo de campos necessários a serem enviados para a autorização.

Requisição

{  
   "MerchantOrderId":"2019010101",
   "Customer":{  
      "Name":"QRCode Test"
   },
   "Payment":{
     "Type":"qrcode",
     "Amount":100,
     "Installments":1,
     "Capture":false,
     "Modality": "Credit"
   }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{  
   "MerchantOrderId":"2019010101",
   "Customer":{  
      "Name":"QRCode Test"
   },
   "Payment":{
     "Type":"qrcode",
     "Amount":100,
     "Installments":1,
     "Capture":false,
     "Modality": "Credit"
   }
}
--verbose
Propriedade Tipo Tamanho Obrigatório Descrição
MerchantId Guid 36 Sim Identificador da loja na Cielo.
MerchantKey Texto 40 Sim Chave Publica para Autenticação Dupla na Cielo.
Content-Type Header 40 Sim application/json (obrigatório o envio deste).
RequestId Guid 36 Não Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT.
MerchantOrderId Texto 50 Sim Numero de identificação do Pedido.
Customer.Name Texto 255 Não Nome do Comprador.
Payment.Type Texto 100 Sim Tipo do Meio de Pagamento. Enviar qrcode para uma transação de QRCode.
Payment.Amount Número 15 Sim Valor do Pedido (ser enviado em centavos).
Payment.Installments Número 2 Sim Número de Parcelas.
Payment.Capture Booleano - Não Enviar true para uma trasação de captura automática.
Payment.Modality Texto 10 Não Indica se o pagamento será feito com crédito ou débito. Valores possíveis: “Credit” (padrão) ou “Debit”

Resposta

{
    "MerchantOrderId": "2019010101",
    "Customer": {
        "Name": "QRCode Test"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": 0,
        "Capture": false,
        "Authenticate": false,
        "Recurrent": false,
        "Provider": "Cielo",
        "Amount": 100,
        "ReceivedDate": "2019-01-02 10:14:29",
        "Status": 12,
        "IsSplitted": false,
        "QrCode": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51AAAQ1klEQVR42u3de6hlVR(...)",
        "ReturnMessage": "QRCode gerado com sucesso",
        "PaymentId": "5d7e8fd3-70b6-4a88-9660-e064d72fdcdd",
        "Type": "qrcode",
        "Currency": "BRL",
        "Country": "BRA",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/5d7e8fd3-70b6-4a88-9660-e064d72fdcdd"
            }
        ]
    }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2019010101",
    "Customer": {
        "Name": "QRCode Test"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": 0,
        "Capture": false,
        "Authenticate": false,
        "Recurrent": false,
        "Provider": "Cielo",
        "Amount": 100,
        "ReceivedDate": "2019-01-02 10:14:29",
        "Status": 12,
        "IsSplitted": false,
        "QrCodeBase64Image": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51AAAQ1klEQVR42u3de6hlVR(...)",
        "ReturnMessage": "QRCode gerado com sucesso",
        "PaymentId": "5d7e8fd3-70b6-4a88-9660-e064d72fdcdd",
        "Type": "qrcode",
        "Currency": "BRL",
        "Country": "BRA",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/5d7e8fd3-70b6-4a88-9660-e064d72fdcdd"
            }
        ]
    }
}
Propriedade Descrição Tipo Tamanho Formato
QrCodeBase64Image QRCode codificado na base 64. Por exemplo, a imagem poderá ser apresentada na página utilizando o código HTML como este:
<img src="data:image/png;base64, código_da_imagem_na_base_64">
Texto variável Texto alfanumérico
PaymentId Número de identificação do pagamento, necessário para futuras operações como Consulta, Captura e Cancelamento. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Status Status da Transação. No caso de uma transação de geração de QRCode de pagamento, o status inicial é 12 (Pending). Byte 2
ReturnCode Código de retorno da Adquirência. Texto 32 Texto alfanumérico
ReturnMessage Mensagem de retorno da Adquirência. Texto 512 Texto alfanumérico

Carnê

O carnê é uma transação de débito utilizada para efetuar o pagamento de uma conta.

O carnê é um meio de pagamento válido para as bandeiras MasterCard, Visa e Elo.

Essa modalidade pode ser utilizada por lojistas que emitem carnês próprios e faturas de cartões Private Label. O produto carnê permite a separação das vendas relacionadas à compra de produtos e pagamento de serviços, facilitando reporte de valores junto ao Fisco.

Como qualquer transação de débito no e-commerce, as transações de carnê precisam ser autenticadas via protocolo 3DS 2.0. Obtenha mais informações sobre o protocolo de autenticação no manual do 3DS 2.0.

Requisição

{
   "MerchantOrderId":"2014111704",
   "Customer":{
      "Name":"Comprador Carnet simples"
   },
   "Payment":{
      "Provider":"CieloSandbox",
      "Authenticate":true,
      "Installments":1,
      "Amount":100,
      "Type":"DebitCard",
      "SoftDescriptor":"123456789ABCD",
      "DebitCard":{
         "ExpirationDate":"05/2024",
         "CardNumber":"1234567891234567",
         "Holder":"Test Holder",
         "Brand":"Visa",
         "SecurityCode":"123",
         "CardOnFile":{
            "Reason":"Unscheduled",
            "Usage":"first"
         }
      },
      "ExternalAuthentication":{
         "Eci":"05",
         "Cavv":"AAABAWFlmQAAAABjRWWZEEFgFz+=",
         "Xid":"blNhMmtMUWg4RDFoV2JaM1RRbjA="
      },
      "iscarnetransaction":true
   }
}
Propriedade Tipo Tamanho Obrigatório Descrição
Payment.IsCarneTransaction Booleano Não (default false) Deve ser enviado com valor “true” caso se trate de uma transação de pagamento de serviço do tipo Carnê

Implementações específicas

Quasi cash

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

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

"Payment":{
   "Currency":"BRL",
   "Country":"BRA",
   "ServiceTaxAmount":0,
   "Installments":1,
   "Interest":"ByMerchant",
   "Capture":true,
   "Authenticate":false,
   "SoftDescriptor":"123456789ABCD",
   "QuasiCash":true,
   "Type":"CreditCard",
   "Amount":15700,
   "CreditCard":{
      "CardNumber":"1234123412341231",
      "Holder":"Teste Holder",
      "ExpirationDate":"12/2030",
      "SecurityCode":"123",
      "SaveCard":"false",
      "Brand":"Visa",
      "CardOnFile":{
         "Usage":"Used",
         "Reason":"Unscheduled"
   }    
Parâmetro Descrição Valor Formato Tamanho Obrigatório
QuasiCash Identifica uma transação de quase cash. “true” ou “false” Booleano - Não

Facilitadores de Pagamento

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

Os campos específicos estão contidos dentro do nó PaymentFacilitator. Além dos campos deste nó, os facilitadores também precisam enviar obrigatoriamente o campo SoftDescriptor do nó Payment. Veja a seguir o exemplo do envio e da resposta.

Atenção: As bandeiras, ao identificarem inconformidade devido ao não envio dos dados obrigatórios na mensageria transacional, aplicarão multas à Cielo as quais serão repassadas ao Facilitador responsável pelo envio dos dados transacionais.

Requisição

{
   "MerchantOrderId":"2222222222",
   "Customer":{
      "Name":"Comprador Teste",
      "Identity":"11225468954",
      "IdentityType":"CPF",
      "Email":"compradorteste@teste.com",
      "Birthdate":"1991-01-02",
      "Address":{
         "Street":"Rua Teste",
         "Number":"123",
         "Complement":"AP 123",
         "ZipCode":"12345987",
         "City":"Rio de Janeiro",
         "State":"RJ",
         "Country":"BRA"
      },
      "DeliveryAddress":{
         "Street":"Rua Teste",
         "Number":"123",
         "Complement":"AP 123",
         "ZipCode":"12345987",
         "City":"Rio de Janeiro",
         "State":"RJ",
         "Country":"BRA"
      }
   },
   "Payment":{
      "Type":"CreditCard",
      "Amount":157000,
      "Currency":"BRL",
      "Country":"BRA",
      "Provider":"Cielo",
      "ServiceTaxAmount":0,
      "Installments":1,
      "Interest":"ByMerchant",
      "Capture":false,
      "Authenticate":false,
      "Recurrent":false,
      "SoftDescriptor":"123456789ABCD",
      "CreditCard":{
         "CardNumber":"4024007197692931",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2021",
         "SecurityCode":"123",
         "SaveCard":"false",
         "Brand":"Visa"
      },
      "PaymentFacilitator":{
         "EstablishmentCode":"1234",
         "SubEstablishment":{
            "EstablishmentCode":"1234",
            "Identity":"11111111000100",
            "Mcc":"1234",
            "Address":"Alameda Grajau, 512",
            "City":"Barueri",
            "State":"SP",
            "CountryCode":"076",
            "PostalCode":"06455914",
            "PhoneNumber":"1155855585"
         }
      }
   }
}
Propriedade Tipo Tamanho Obrigatório Descrição
PaymentFacilitator.EstablishmentCode Texto* 11 Obrigatório para facilitadores Código do estabelecimento do Facilitador. “Facilitator ID” (Cadastro do facilitador com as bandeiras)
O código é diferente por bandeira, podendo variar inclusive o tamanho do campo:
Bandeira Mastercard –06 dígitos
Bandeira Visa –08 dígitos
Bandeira ELO –de 04 à 05 dígitos
Bandeira Hipercard –06 dígitos
Para demais bandeiras, como Amex e JCB, o campo pode ser preenchido com “0” zeros.
PaymentFacilitator.SubEstablishment.EstablishmentCode Texto* 15 Obrigatório para facilitadores Código do estabelecimento do sub Merchant. “Sub-Merchant ID” (Cadastro do subcredenciado com o facilitador)
PaymentFacilitator.SubEstablishment.Identity Texto* 14 Obrigatório para facilitadores CNPJ ou CPF do sub-merchant.
PaymentFacilitator.SubEstablishment.Mcc Texto* 4 Obrigatório para facilitadores MCC do sub Merchant.
PaymentFacilitator.SubEstablishment.Address Texto* 22 Obrigatório para facilitadores Endereço do sub Merchant.
PaymentFacilitator.SubEstablishment.City Texto* 13 Obrigatório para facilitadores Cidade do sub Merchant.
PaymentFacilitator.SubEstablishment.State Texto* 2 Obrigatório para facilitadores Estado do sub Merchant.
PaymentFacilitator.SubEstablishment.PostalCode Texto* 9 Obrigatório para facilitadores Código postal do sub Merchant.
PaymentFacilitator.SubEstablishment.CountryCode Texto* 3 Obrigatório para facilitadores Código país do sub-merchant com base no ISO 3166
Ex: código ISO 3166 do Brasil é o 076. Lista completa online.
PaymentFacilitator.SubEstablishment.PhoneNumber Texto* 13 Obrigatório para facilitadores Número de telefone do sub Merchant.
Payment.Softdescriptor Texto* 13 Obrigatório para facilitadores Texto impresso na fatura bancaria comprador. Deve ser preenchido de acordo com os dados do sub Merchant.

*Evite utilizar acentos pois eles são considerados como dois caracteres.

Resposta

{
   "MerchantOrderId":"2014111701",
   "Customer":{
      "Name":"Comprador Teste",
      "Identity":"11225468954",
      "IdentityType":"CPF",
      "Email":"compradorteste@teste.com",
      "Birthdate":"1991-01-02",
      "Address":{
         "Street":"Rua Teste",
         "Number":"123",
         "Complement":"AP 123",
         "ZipCode":"12345987",
         "City":"Rio de Janeiro",
         "State":"RJ",
         "Country":"BRA"
      },
      "DeliveryAddress":{
         "Street":"Rua Teste",
         "Number":"123",
         "Complement":"AP 123",
         "ZipCode":"12345987",
         "City":"Rio de Janeiro",
         "State":"RJ",
         "Country":"BRA"
      }
   },
   "Payment":{
      "ServiceTaxAmount":0,
      "Installments":1,
      "Interest":0,
      "Capture":false,
      "Authenticate":false,
      "Recurrent":false,
      "CreditCard":{
         "CardNumber":"402400******2931",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2021",
         "SaveCard":false,
         "Brand":"Visa"
      },
      "Tid":"1223092935684",
      "ProofOfSale":"2935684",
      "AuthorizationCode":"065158",
      "SoftDescriptor":"123456789ABCD",
      "Provider":"Simulado",
      "IsQrCode":false,
      "PaymentFacilitator":{
         "EstablishmentCode":"1234",
         "SubEstablishment":{
            "EstablishmentCode":"1234",
            "Identity":"11111111000100",
            "Mcc":"1234",
            "Address":"Alameda Grajau, 512",
            "City":"Barueri",
            "State":"SP",
            "CountryCode":"076",
            "PostalCode":"06455914",
            "PhoneNumber":"1155855585"
         }
      },
      "Amount":157000,
      "ReceivedDate":"2019-12-23 09:29:34",
      "Status":1,
      "IsSplitted":false,
      "ReturnMessage":"Operation Successful",
      "ReturnCode":"4",
      "PaymentId":"365c3a0d-fd86-480b-9279-4ba3da21333c",
      "Type":"CreditCard",
      "Currency":"BRL",
      "Country":"BRA",
      "Links":[
         {
            "Method":"GET",
            "Rel":"self",
            "Href":"https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/365c3a0d-fd86-480b-9279-4ba3da21333c"
         },
         {
            "Method":"PUT",
            "Rel":"capture",
            "Href":"https://apisandbox.cieloecommerce.cielo.com.br/1/sales/365c3a0d-fd86-480b-9279-4ba3da21333c/capture"
         },
         {
            "Method":"PUT",
            "Rel":"void",
            "Href":"https://apisandbox.cieloecommerce.cielo.com.br/1/sales/365c3a0d-fd86-480b-9279-4ba3da21333c/void"
         }
      ]
   }
}
Propriedade Tipo Tamanho Obrigatório Descrição
PaymentFacilitator.EstablishmentCode Texto* 11 Obrigatório para facilitadores Código do estabelecimento do Facilitador. “Facilitator ID” (Cadastro do facilitador com as bandeiras)
O código é diferente por bandeira, podendo variar inclusive o tamanho do campo:
Bandeira Mastercard –06 dígitos
Bandeira Visa –08 dígitos
Bandeira ELO –de 04 à 05 dígitos
Bandeira Hipercard –06 dígitos
Para demais bandeiras, como Amex e JCB, o campo pode ser preenchido com “0” zeros.
PaymentFacilitator.SubEstablishment.EstablishmentCode Texto* 15 Obrigatório para facilitadores Código do estabelecimento do sub Merchant. “Sub-Merchant ID” (Cadastro do subcredenciado com o facilitador)
PaymentFacilitator.SubEstablishment.Identity Texto* 14 Obrigatório para facilitadores CNPJ ou CPF do sub-merchant.
PaymentFacilitator.SubEstablishment.Mcc Texto* 4 Obrigatório para facilitadores MCC do sub Merchant.
PaymentFacilitator.SubEstablishment.Address Texto* 22 Obrigatório para facilitadores Endereço do sub Merchant.
PaymentFacilitator.SubEstablishment.City Texto* 13 Obrigatório para facilitadores Cidade do sub Merchant.
PaymentFacilitator.SubEstablishment.State Texto* 2 Obrigatório para facilitadores Estado do sub Merchant.
PaymentFacilitator.SubEstablishment.PostalCode Texto* 9 Obrigatório para facilitadores Código postal do sub Merchant.
PaymentFacilitator.SubEstablishment.CountryCode Texto* 3 Obrigatório para facilitadores Código país do sub-merchant com base no ISO 3166.
Ex: código ISO 3166 do Brasil é o 076. Lista completa online
PaymentFacilitator.SubEstablishment.PhoneNumber Texto* 13 Obrigatório para facilitadores Número de telefone do sub Merchant.
Payment.Softdescriptor Texto* 13 Obrigatório para facilitadores Texto impresso na fatura bancaria comprador. Deve ser preenchido de acordo com os dados do sub Merchant.

*Evite utilizar acentos pois eles são considerados como dois caracteres.

Transações CBPS

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

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

Requisição

{
    "merchantorderid": "123456ABCD1234",
    "customer": {
        "name": "João das Contas accept",
        "mobile": "5521923455678"
    },
    "payment": {
        "type": "CreditCard",
        "amount": 100,
        "installments": 1,
        "IsCustomerBillPaymentService":true,
        "capture": false,
        "authenticate": false,
        "recurrent": false,
        "provider": "CieloSandbox",
        "creditcard": {
            "cardnumber": "4532110000001234",
            "holder": "Teste Holder",
            "expirationdate": "12/2022",
            "securitycode": "123",
            "brand": "jcb",
            "savecard": true
        },
        "Wallet": {
            "AdditionalData": {
                "Mcc": "1234"
            }
        }
    }
}
Propriedade Tipo Tamanho Obrigatório Descrição
IsCustomerBillPaymentService Boolean Não True ou false. Indica se é uma transação CBPS (Serviço de Pagamento de Contas para Consumidores)
Wallet.AdditionalData.Mcc String (numérico) 4 Sim, para transações de CBPS MCC do estabelecimento (EC) permitido para transações de CBPS

Transações SDWO

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

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

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

Além dos campos específicos dessa modalidade, para transações SDWO também é obrigatório o envio do Soft Descriptor (campo Payment.SoftDescriptor) e CPF ou CNPJ do portador (campo Customer.Identity e campo Customer.IdentityType). Confira mais detalhes desses campos na tabela de campos da requisição.

Para efetuar testes, é necessário apenas seguir as orientações do menu Sandbox e ferramentas

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

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

Requisição

{
   "MerchantOrderId":"2012345678",
   "Customer":{
      "Name":"Comprador Carteira",
      "Identity":"11225468954",
      "IdentityType":"CPF",
   },
   "Payment":{
      "Type":"CreditCard",
      "Amount":15700,
      "Installments":1,
      "SoftDescriptor":"CARTEIRA*NOMELOJA",
      "CreditCard":{
         "CardNumber":"4532110000001234",
         "Brand":"Visa",
         "SecurityCode":"123"
      },
      "Wallet":{
"PlatformOperator":"ABC",
     "AdditionalData": {
        "Mcc": "1234"
     }
      }
   }
}
Propriedade Tipo Tamanho Obrigatório Descrição
Wallet.PlatformOperator String (texto) 3 Sim, para transações de SDWO Sigla da carteira que está cadastrada aqui na Cielo como carteira digital (verificar sua sigla com seu gestor comercial)
Wallet.AdditionalData.Mcc String (numérico) 4 Sim, para transações de SDWO MCC do varejista subjacente (pra transações de compra); MCC da carteira digital (para transações de abastecimento de crédito na carteira caso aplicável – no qual é necessária a marcação de cash in também vista nessa sessão)
Customer.Identity Texto 14 Sim, para transações de SDWO Número do CPF ou CNPJ do comprador.
Customer.IdentityType Texto 255 Sim, para transações de SDWO Tipo de documento de identificação do comprador (CPF/CNPJ).
SoftDescriptor Texto 13 Sim, para transações de SDWO Texto que será impresso na fatura bancária do portador.
Não permite caracteres especiais.
Necessário preencher com Nome da carteira*nome do lojista.

Transações Cash In

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

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

Além dos campos específicos dessa modalidade, para transações Cash In também é obrigatório o envio do Soft Descriptor (campo Payment.SoftDescriptor) e CPF ou CNPJ do portador (campo Customer.Identity e campo Customer.IdentityType). No caso de Cash In, o campo do Soft Descriptor precisa ser preenchido com nome da carteira*nome do portador. Confira mais detalhes na tabela de campos da requisição.

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

Requisição

{

   "MerchantOrderId":"2012345678",
   "Customer":{
      "Name":"Comprador Carteira",
      "Identity":"11225468954",
      "IdentityType":"CPF",
   },
   "Payment":{
      "Type":"CreditCard",
      "Amount":15700,
      "Installments":1,
      "SoftDescriptor":"CARTEIRA*NOMEPORTADOR",
      "CreditCard":{
         "CardNumber":"4532110000001234",
         "Brand":"Visa",
         "SecurityCode":"123"
      },
      "Wallet":{
"PlatformOperator":"ABC",
     "AdditionalData": {
       "CashIn": "true"
     }
      }
   }
}

Propriedade Tipo Tamanho Obrigatório Descrição
Wallet.PlatformOperator String (texto) 3 Sim, para transações de Cash In Sigla da carteira que está cadastrada aqui na Cielo como carteira digital (verificar sua sigla com seu gestor comercial)
Wallet.AdditionalData.CshIn String (texto) - Sim, para transações de Cash In Enviar como “True” se for uma transação de Cash In
Customer.Identity Texto 14 Sim, para transações de Cash In Número do CPF ou CNPJ do comprador.
Customer.IdentityType Texto 255 Sim, para transações de Cash In Tipo de documento de identificação do comprador (CPF/CNPJ).
SoftDescriptor Texto 13 Sim, para transações de Cash In Texto que será impresso na fatura bancária do portador.
Não permite caracteres especiais.
Necessário preencher com Nome da carteira*nome do portador.

Tokenização de cartões

O que é a tokenização de cartões?

É uma criptografia que permite o armazenamento seguro de dados sensíveis de cartão de crédito. Estes dados são transformados em um código criptografado chamado de token, que poderá ser armazenado em banco de dados. Com a tokenização, a loja poderá oferecer recursos como “Compra com um clique” e compras com recorrência, sempre preservando a integridade e a confidencialidade das informações.

Criando um cartão tokenizado antes da autorização

Para salvar um cartão sem autorizar uma transação, basta realizar uma requisição de tokenização com os dados do cartão.

Requisição

{
    "CustomerName": "Comprador Teste Cielo",
    "CardNumber":"4532117080573700",
    "Holder":"Comprador T Cielo",
    "ExpirationDate":"12/2030",
    "Brand":"Visa"
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/card/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "CustomerName": "Comprador Teste Cielo",
    "CardNumber":"4532117080573700",
    "Holder":"Comprador T Cielo",
    "ExpirationDate":"12/2030",
    "Brand":"Visa"
}
--verbose
Propriedade Tipo Tamanho Obrigatório Descrição
Name Texto 255 Sim Nome do comprador.
CardNumber Texto 16 Sim Número do cartão do comprador.
Holder Texto 25 Sim Nome do comprador impresso no cartão.
ExpirationDate Texto 7 Sim Data de validade impressa no cartão.
Brand Texto 10 Sim Bandeira do cartão (Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover).

Resposta

{
  "CardToken": "db62dc71-d07b-4745-9969-42697b988ccb",
  "Links": {
    "Method": "GET",
    "Rel": "self",
    "Href": "https://apiquerydev.cieloecommerce.cielo.com.br/1/card/db62dc71-d07b-4745-9969-42697b988ccb"}
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
  "CardToken": "db62dc71-d07b-4745-9969-42697b988ccb",
  "Links": {
    "Method": "GET",
    "Rel": "self",
    "Href": "https://apiquerydev.cieloecommerce.cielo.com.br/1/card/db62dc71-d07b-4745-9969-42697b988ccb"}
}
Propriedade Descrição Tipo Tamanho Formato
Cardtoken Token de identificação do cartão. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Criando um cartão tokenizado durante uma autorização

Para salvar um cartão criando seu token durante a autorização da transação de crédito, envie a requisição padrão de transação de crédito e no campo SaveCard informe o valor “true”.

A resposta da requisição retornará o token do cartão no campo CardToken.

Tokenização de bandeira

Algumas bandeiras de cartão possuem uma solução de tokenização que oferece o armazenamento de cartões em cofres na própria bandeira, de forma criptografada. Essa tokenização de bandeira tem o intuito de melhorar a segurança e qualidade das informações de cartão trafegadas, o que acarreta em possíveis aumentos na conversão de aprovação pelos bancos emissores.

Veja todos os benefícios:

Como funciona?

As bandeiras participantes disponibilizam APIs para o recebimento e armazenamento do cartão de forma segura para adquirentes, gateways e parceiros, com a criação do token único e exclusivo para aquele cartão naquele estabelecimento.

A Cielo fornece esse serviço para os clientes de duas formas:

Para obter essa funcionalidade, entre em contato com nosso canal de suporte ecommerce solicitando a habilitação: cieloecommerce@cielo.com.br

Confira os campos a serem enviados na transação caso a opção escolhida seja a integração por fora:

Requisição

{  
   "MerchantOrderId":"2014111701",
   "Customer":{  
      "Name":"Comprador Teste",
      "Email":"compradorteste@teste.com",
      "Birthdate":"1991-01-02",
      "Address":{  
         "Street":"Rua Teste",
         "Number":"123",
         "Complement":"AP 123",
         "ZipCode":"12345987",
         "City":"Rio de Janeiro",
         "State":"RJ",
         "Country":"BRA"
      },
        "DeliveryAddress": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        }
   },
   "Payment":{  
     "Type":"CreditCard",
     "Amount":15700,
     "Currency":"BRL",
     "Country":"BRA",
     "ServiceTaxAmount":0,
     "Installments":1,
     "Interest":"ByMerchant",
     "Capture":true,
     "Authenticate":false,
     "SoftDescriptor":"123456789ABCD",
     "CreditCard":{  
         "CardNumber":"1234123412341231",
         "Holder":"Teste Holder",
         "Cryptogram":"abcdefghijklmnopqrstuvw==",
         "ExpirationDate":"12/2030",
         "SecurityCode":"123",
         "SaveCard":"true",
         "Brand":"Visa"
     }
   }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{  
   "MerchantOrderId":"2014111701",
   "Customer":{  
      "Name":"Comprador Teste",
      "Identity":"11225468954",
      "IdentityType":"CPF",
      "Email":"compradorteste@teste.com",
      "Birthdate":"1991-01-02",
      "Address":{  
         "Street":"Rua Teste",
         "Number":"123",
         "Complement":"AP 123",
         "ZipCode":"12345987",
         "City":"Rio de Janeiro",
         "State":"RJ",
         "Country":"BRA"
      },
        "DeliveryAddress": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        }
   },
   "Payment":{  
     "Type":"CreditCard",
     "Amount":15700,
     "ServiceTaxAmount":0,
     "Installments":1,
     "Interest":"ByMerchant",
     "Capture":true,
     "Authenticate":false,
     "SoftDescriptor":"123456789ABCD",
     "CreditCard":{  
         "CardNumber":"4551870000000183",
         "Holder":"Teste Holder",
         "Cryptogram":"abcdefghijklmnopqrstuvw==",
         "ExpirationDate":"12/2030",
         "SecurityCode":"123",
         "SaveCard":"true",
         "Brand":"Visa"
     }
   }
}
--verbose
Propriedade Tipo Tamanho Obrigatório Descrição
Payment.CreditCard.CardNumber Texto 19 Sim Token gerado pela bandeira (DPAN). A indicação de que o CardNumber deve ser preenchido com o DPAN para caso de tokenização de bandeira.
Payment.CreditCard.Holder Texto 25 Não Nome do Comprador impresso no cartão.
Payment.CreditCard.Cryptogram Texto 28 Não Criptograma gerado pela bandeira.
Payment.CreditCard.ExpirationDate Texto 7 Sim Data de validade do token gerado pela bandeira.
Payment.CreditCard.SecurityCode Texto 4 Não Código de segurança impresso no verso do cartão - Ver Anexo.
Payment.CreditCard.SaveCard Booleano Não (Default false) Booleano que identifica se o cartão será salvo para gerar o CardToken.
Payment.CreditCard.Brand Texto 10 Sim Bandeira do cartão (Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard / Hiper).

Resposta

{
    "MerchantOrderId": "2014111706",
    "Customer": {
        "Name": "Comprador Teste",
        "Identity":"11225468954",
        "IdentityType":"CPF",
        "Email": "compradorteste@teste.com",
        "Birthdate": "1991-01-02",
        "Address": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "DeliveryAddress": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        }
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": true,
        "Authenticate": false,
        "CreditCard": {
            "CardNumber": "455187******0183",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": true,
            "CardToken": "d37bf475-307d-47be-b50a-8dcc38c5056c",
            "Brand": "Visa"
        },
        "ProofOfSale": "674532",
        "Tid": "0305020554239",
        "AuthorizationCode": "123456",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "CreditCard",
        "Amount": 15700,
        "CapturedAmount": 15700,
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 2,
        "ReturnCode": "6",
        "ReturnMessage": "Operation Successful",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            }
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2014111706",
    "Customer": {
        "Name": "Comprador Teste",
        "Identity":"11225468954",
        "IdentityType":"CPF",
        "Email": "compradorteste@teste.com",
        "Birthdate": "1991-01-02",
        "Address": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "DeliveryAddress": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        }
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": true,
        "Authenticate": false,
        "CreditCard": {
            "CardNumber": "455187******0183",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": true,
            "CardToken": "d37bf475-307d-47be-b50a-8dcc38c5056c"
            "Brand": "Visa"
        },
        "ProofOfSale": "674532",
        "Tid": "0305020554239",
        "AuthorizationCode": "123456",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "CreditCard",
        "Amount": 15700,
        "CapturedAmount": 15700,
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 2,
        "ReturnCode": "6",
        "ReturnMessage": "Operation Successful",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            }
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
Propriedade Descrição Tipo Tamanho Formato
ProofOfSale Número da autorização, identico ao NSU. Texto 6 Texto alfanumérico
Tid Id da transação na adquirente. Texto 20 Texto alfanumérico
AuthorizationCode Código de autorização. Texto 6 Texto alfanumérico
SoftDescriptor Texto que será impresso na fatura bancaria do portador - Disponivel apenas para VISA/MASTER - não permite caracteres especiais Texto 13 Texto alfanumérico
PaymentId Número de identificação do pagamento, necessário para operações como Consulta, Captura e Cancelamento. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ECI Eletronic Commerce Indicator. Representa o quão segura é uma transação. Texto 2 Exemplos: 7
Status Status da Transação. Byte 2
ReturnCode Código de retorno da Adquirência. Texto 32 Texto alfanumérico
ReturnMessage Mensagem de retorno da Adquirência. Texto 512 Texto alfanumérico
Cardtoken Token de identificação do Cartão. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Criando uma venda com cartão tokenizado

Para criar uma venda de cartão de crédito tokenizado, envie uma requisição de transação de crédito com o CardToken conforme o exemplo a seguir.

Requisição

{  
   "MerchantOrderId":"2014111706",
   "Customer":{  
      "Name":"Comprador Teste"
   },
   "Payment":{  
     "Type":"CreditCard",
     "Amount":100,
     "Installments":1,
     "SoftDescriptor":"123456789ABCD",
     "CreditCard":{  
         "CardToken":"6e1bf77a-b28b-4660-b14f-455e2a1c95e9",
         "SecurityCode":"262",
         "Brand":"Visa"
     }
   }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{  
   "MerchantOrderId":"2014111706",
   "Customer":{  
      "Name":"Comprador Teste"
   },
   "Payment":{  
     "Type":"CreditCard",
     "Amount":100,
     "Installments":1,
     "SoftDescriptor":"123456789ABCD",
     "CreditCard":{  
         "CardToken":"6e1bf77a-b28b-4660-b14f-455e2a1c95e9",
         "SecurityCode":"262",
         "Brand":"Visa"
     }
   }
}
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
CreditCard.CardToken Token de identificação do Cartão. Guid 36 Sim
CreditCard.SecurityCode Código de segurança impresso no verso do cartão. Texto 4 Não
CreditCard.Brand Bandeira do cartão. Texto 10 Sim

Resposta

{
    "MerchantOrderId": "2014111706",
    "Customer": {
        "Name": "Comprador Teste"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": false,
        "Authenticate": false,
        "CreditCard": {
            "SaveCard": false,
            "CardToken": "6e1bf77a-b28b-4660-b14f-455e2a1c95e9",
            "Brand": "Visa"
        },
        "ProofOfSale": "5036294",
        "Tid": "0310025036294",
        "AuthorizationCode": "319285",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId": "c3ec8ec4-1ed5-4f8d-afc3-19b18e5962a8",
        "Type": "CreditCard",
        "Amount": 100,
        "Currency": "BRL",
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 1,
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            },
            {
                "Method": "PUT",
                "Rel": "capture",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
        {
    "MerchantOrderId": "2014111706",
    "Customer": {
        "Name": "Comprador Teste"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": false,
        "Authenticate": false,
        "CreditCard": {
            "SaveCard": false,
            "CardToken": "6e1bf77a-b28b-4660-b14f-455e2a1c95e9",
            "Brand": "Visa"
        },
        "ProofOfSale": "5036294",
        "Tid": "0310025036294",
        "AuthorizationCode": "319285",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId": "c3ec8ec4-1ed5-4f8d-afc3-19b18e5962a8",
        "Type": "CreditCard",
        "Amount": 100,
        "Currency": "BRL",
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 1,
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            },
            {
                "Method": "PUT",
                "Rel": "capture",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
Propriedade Descrição Tipo Tamanho Formato
ProofOfSale Número da autorização, identico ao NSU. Texto 6 Texto alfanumérico
Tid Id da transação na adquirente. Texto 20 Texto alfanumérico
AuthorizationCode Código de autorização. Texto 6 Texto alfanumérico
SoftDescriptor Texto que será impresso na fatura bancaria do portador - Disponivel apenas para VISA/MASTER - nao permite caracteres especiais Texto 13 Texto alfanumérico
PaymentId Número de identificação do pagamento, necessário para operações como Consulta, Captura e Cancelamento. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ECI Eletronic Commerce Indicator. Representa o quão segura é uma transação. Texto 2 Exemplos: 7
Status Status da Transação. Byte 2
ReturnCode Código de retorno da Adquirência. Texto 32 Texto alfanumérico
ReturnMessage Mensagem de retorno da Adquirência. Texto 512 Texto alfanumérico

Criando uma venda com Cartão Tokenizado na 1.5

Para criar uma venda de cartão de crédito com token do webservice 1.5, é necessário fazer um POST para o recurso Payment conforme o exemplo.

Para uso em Sandbox, é possivel simular transações autorizadas ou negadas via tokens de teste:

Status Token
Autorizado 6fb7a669aca457a9e43009b3d66baef8bdefb49aa85434a5adb906d3f920bfeA
Negado 6fb7a669aca457a9e43009b3d66baef8bdefb49aa85434a5adb906d3f920bfeB

Requisição

{  
   "MerchantOrderId":"2014111706",
   "Customer":{  
      "Name":"Comprador token 1.5"     
   },
   "Payment":{  
     "Type":"CreditCard",
     "Amount":100,
     "Installments":1,
     "CreditCard":{  
        "CardToken":"6fb7a669aca457a9e43009b3d66baef8bdefb49aa85434a5adb906d3f920bfeA",
        "Brand":"Visa"
     }
   }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{  
   "MerchantOrderId":"2014111706",
   "Customer":{  
      "Name":"Comprador token 1.5"     
   },
   "Payment":{  
     "Type":"CreditCard",
     "Amount":100,
     "Installments":1,
     "CreditCard":{  
        "CardToken":"6fb7a669aca457a9e43009b3d66baef8bdefb49aa85434a5adb906d3f920bfeA",
        "Brand":"Visa"
     }
   }
}
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API Cielo eCommerce. Guid 36 Sim
MerchantKey Chave Publica para Autenticação Dupla na API Cielo eCommerce. Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
MerchantOrderId Numero de identificação do Pedido. Texto 50 Sim
Customer.Name Nome do Comprador. Texto 255 Não
Customer.Status Status de cadastro do comprador na loja (NEW / EXISTING) - Utilizado pela análise de fraude Texto 255 Não
Payment.Type Tipo do Meio de Pagamento. Texto 100 Sim
Payment.Amount Valor do Pedido (ser enviado em centavos). Número 15 Sim
Payment.Installments Número de Parcelas. Número 2 Sim
CreditCard.CardToken Token de identificação do Cartão. Guid 300 Sim
CreditCard.Brand Bandeira do cartão. Texto 10 Sim

Resposta

{
  "MerchantOrderId": "2014111706",
  "Customer": {
    "Name": "Comprador token 1.5"
  },
  "Payment": {
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": 0,
    "Capture": false,
    "Authenticate": false,
    "Recurrent": false,
    "CreditCard": {
      "SaveCard": false,
      "CardToken": "6fb7a669aca457a9e43009b3d66baef8bdefb49aa85434a5adb906d3f920bfeA",
      "Brand": "Visa"
    },
    "Tid": "0307050140148",
    "ProofOfSale": "140148",
    "AuthorizationCode": "045189",
    "Provider": "Simulado",
    "PaymentId": "8c14cdcf-d5a9-46b0-b040-c0d054cd8f76",
    "Type": "CreditCard",
    "Amount": 100,
    "ReceivedDate": "2017-03-07 17:01:40",
    "Currency": "BRL",
    "Country": "BRA",
    "ReturnCode": "4",
    "ReturnMessage": "Operation Successful",
    "Status": 1,
    "Links": [
      {
        "Method": "GET",
        "Rel": "self",
        "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/8c14cdcf-d5a9-46b0-b040-c0d054cd8f76"
      },
      {
        "Method": "PUT",
        "Rel": "capture",
        "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/8c14cdcf-d5a9-46b0-b040-c0d054cd8f76/capture"
      },
      {
        "Method": "PUT",
        "Rel": "void",
        "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/8c14cdcf-d5a9-46b0-b040-c0d054cd8f76/void"
      }
    ]
  }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
  "MerchantOrderId": "2014111706",
  "Customer": {
    "Name": "Comprador token 1.5"
  },
  "Payment": {
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": 0,
    "Capture": false,
    "Authenticate": false,
    "Recurrent": false,
    "CreditCard": {
      "SaveCard": false,
      "CardToken": "6fb7a669aca457a9e43009b3d66baef8bdefb49aa85434a5adb906d3f920bfeA",
      "Brand": "Visa"
    },
    "Tid": "0307050140148",
    "ProofOfSale": "140148",
    "AuthorizationCode": "045189",
    "Provider": "Simulado",
    "PaymentId": "8c14cdcf-d5a9-46b0-b040-c0d054cd8f76",
    "Type": "CreditCard",
    "Amount": 100,
    "ReceivedDate": "2017-03-07 17:01:40",
    "Currency": "BRL",
    "Country": "BRA",
    "ReturnCode": "4",
    "ReturnMessage": "Operation Successful",
    "Status": 1,
    "Links": [
      {
        "Method": "GET",
        "Rel": "self",
        "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/8c14cdcf-d5a9-46b0-b040-c0d054cd8f76"
      },
      {
        "Method": "PUT",
        "Rel": "capture",
        "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/8c14cdcf-d5a9-46b0-b040-c0d054cd8f76/capture"
      },
      {
        "Method": "PUT",
        "Rel": "void",
        "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/8c14cdcf-d5a9-46b0-b040-c0d054cd8f76/void"
      }
    ]
  }
}

Propriedade Descrição Tipo Tamanho Formato
ProofOfSale Número da autorização, identico ao NSU. Texto 6 Texto alfanumérico
Tid Id da transação na adquirente. Texto 20 Texto alfanumérico
AuthorizationCode Código de autorização. Texto 6 Texto alfanumérico
SoftDescriptor Texto que será impresso na fatura bancaria do portador - Disponivel apenas para VISA/MASTER - nao permite caracteres especiais Texto 13 Texto alfanumérico
PaymentId Número de identificação do pagamento, necessário para operações como Consulta, Captura e Cancelamento. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ECI Eletronic Commerce Indicator. Representa o quão segura é uma transação. Texto 2 Exemplos: 7
Status Status da Transação. Byte 2
ReturnCode Código de retorno da Adquirência. Texto 32 Texto alfanumérico
ReturnMessage Mensagem de retorno da Adquirência. Texto 512 Texto alfanumérico

Recorrência

Pagamentos recorrentes são transações de cartão de crédito que devem se repetir após um determinado período de tempo.

São pagamentos normalmente encontrados em assinaturas, nas quais o comprador deseja ser cobrado automaticamente mas não quer informar novamente os dados do cartão de crédito.

Tipos de recorrências

A API E-commerce Cielo funciona com dois tipos de recorrências que possuem comportamentos diferentes:

Recorrência Própria

Nesse modelo, a loja é responsável por criar a inteligência necessária para:

Inteligência Descrição
Salvar os dados da transação A loja precisará armazenar a transação e dados do pagamento.
Criar repetição transacional A loja deverá enviar uma nova transação sempre que necessitar de uma autorização.
Comportamento para transação negada Caso uma das transações seja negada, caberá a loja a decisão de retentar uma nova autorização.

A recorrência própria é uma transação padrão para a Cielo, sendo sua única diferença a necessidade de enviar um parâmetro adicional que a define como Recorrência Própria:

Parâmetro: Payment.Recurrent= “true”.

Fluxo recorrência própria

Caso de uso

Este é um exemplo de como a API E-commerce Cielo permite a utilização de sistemas externos de recorrência em suas transações.

A recorrência própria é uma configuração da API E-commerce Cielo que permite que uma loja use um sistema de recorrência interno específico às suas necessidades de negócio.

Nesse modelo, o sistema da loja é encarregado por definir o período, os dados transacionais e, quando necessário, nos enviar a transação de recorrência.

Recorrência Própria + Cartão Tokenizado

A academia CleverFit possui um sistema de cobrança diferenciado onde a matrícula é cobrada quinzenalmente, mas nunca nos fins de semana.

Por ser um modelo altamente customizado, a CleverFit possui um sistema de recorrência própria, utilizando a API E-commerce Cielo via dois mecanismos:

  1. Recorrência Própria: a CleverFit envia os dados da transação como uma venda normal, mas a API identifica que é uma recorrência e aplica regras de autorização diferenciada ao pedido;
  2. Cartão Tokenizado: a CleverFit mantém os cartões salvos de forma tokenizada na Cielo, de acordo com as regras de segurança, evitando armazenar dados de cartões em seu sistema.

A CleverFit envia a transação quinzenalmente para a API E-commerce Cielo, usando os tokens salvos na própria API e optando pela Recorrência Própria, que altera a regra de autorização para se adequar ao seu modelo de cobrança.

Recorrência Programada

Nesse modelo, a Cielo é a responsável por executar uma recorrência de maneira automática.

A Recorrência Programada permite que a loja crie uma transação base que, ao ser enviada para a API E-commerce Cielo, será salva e executada seguindo as regras definidas pela loja.

Nesse modelo, a API realiza e permite:

Vantagens Descrição
Salvar dados transacionais Salva dados da transação, criando assim um modelo de como serão as próximas recorrências.
Automatizar a recorrência Sem atuação da loja, a API cria as transações futuras de acordo com as definições da loja.
Atualizar dados Caso necessário, a API permite modificações das informações da transação (como dados do comprador) ou do ciclo de recorrência (como data e intervalo).

A Recorrência Programada possui dois fluxos de requisição; a diferença está no parâmetro AuthorizeNow.

Quando a primeira transação deve ser autorizada no momento do agendamento, envie AuthorizeNow como “true”.

Fluxo recorrência programada

*Se o Post de Notificação estiver configurado pela loja.

Quando a primeira transação deve ser autorizada em momento posterior ao agendamento, envie AuthorizeNow como “false”; nesse caso, envie também o parâmetro StartDate.

Fluxo recorrência programada

*A transação de agendamento precisa do nó RecurrentPayment, da data da transação e do campo AuthorizeNow = “false”.
**Se o Post de Notificação estiver configurado pela loja.

Veja o exemplo do trecho com o nó RecurrentPayment, que deve ser inserido numa transação de crédito.

"RecurrentPayment":
{
       "AuthorizeNow":"False",
       "StartDate":"2019-06-01"
       "EndDate":"2019-12-01",
       "Interval":"SemiAnnual"
}

Podemos definir os dados como:

Paramêtros Descrição
AuthorizeNow Define qual o momento que uma recorrência será criada. Se for enviado como “true”, ela é criada no momento da autorização; se “false”, a recorrência ficará suspensa até a data escolhida para ser iniciada (StartDate).
StartDate Define a data que transação da Recorrência Programada será autorizada.
EndDate Define a data que a Recorrência Programada será encerrada. Se não for enviada, a recorrência será executada até ser cancelada pela loja.
Interval Intervalo da recorrência.
Monthly - Mensal;
Bimonthly - Bimestral;
Quarterly - Trimestral;
SemiAnnual - Semestral;
Annual - Anual.

Quando uma transação é enviada à API E-commerce Cielo com o nó de Recorrência Programada (RecurrentPayment), o processo de recorrência passa a ser efetivo quando a transação é considerada AUTORIZADA. Desse ponto em diante, a transação passará a ocorrer dentro do intervalo definido pela loja.

Características importantes da Recorrência Programada:

Informação Descrição
Criação A primeira transação é chamada de “Transação de agendamento”. Todas as transações posteriores serão cópias dessa primeira transação. Ela não precisa ser capturada para que a recorrência seja criada, basta ser AUTORIZADA.
Captura Transações de Recorrência Programada não precisam ser capturadas. Após a primeira transação, todas as transações de recorrência são capturadas automaticamente pela API.
Identificação Transações de Recorrência Programada geram dois tipos de identificação:
PaymentId: identifica uma transação. É o mesmo identificador das outras transações na API.
RecurrentPaymentId: identifica pedido de recorrência. Um RecurrentPaymentId possui inúmeros PaymentIds vinculados a ele. Essa é a variável usada para cancelar uma Recorrência Programada.
Consulta Para consultar, basta usar um dos dois tipos de identificação:
PaymentId: Utilizada para consultar UMA TRANSAÇÃO DENTRO DA RECORRÊNCIA.
RecurrentPaymentId: Utilizado para consultar A RECORRÊNCIA.
Cancelamento Uma Recorrência Programada pode ser cancelada de duas maneiras:
* Lojista: Solicita o cancelamento da recorrência. Não cancela transações ja finalizadas antes da ordem de cancelamento da recorrência.
* Por cartão invalido: Caso a API identifique que um cartão salvo está inválido (ex.: expirado) a recorrência será cancelada e não se repetirá, até que a loja atualize o meio de pagamento.
OBS: Cancelamento de transações dentro da recorrência não encerra o agendamento de transações futuras. Somente o Cancelamento usando o RecurrentPaymentId encerra agendamentos futuros.

Estrutura de um RecurrentPaymentId

Estrutura RecurrentPaymentId

Caso de uso

Este é um exemplo de como usar as recorrências da API E-commerce Cielo para elevar suas vendas.

A recorrência é o processo de salvar uma transação e repeti-la em um intervalo de tempo pré-definido. É ideal para modelo de assinaturas.

A Recorrência Programada Cielo tem as seguintes características:

Recorrência mensal e anual

A empresa Musicfy oferece um serviço de assinatura online no qual seus clientes pagam para poderem acessar uma biblioteca de músicas e ouví-las via streaming.

Para captar o máximo de clientes, eles oferecem duas maneiras de pagamento:

Como eles executam a cobrança mensal ou anual de seus clientes?

A MusicFy utiliza a Recorrência Programada da API E-commerce Cielo.

Ao criar uma transação, o Musicfy informa que o pedido em questão deve se repetir mensalmente ou anualmente e que não há data de término para a cobrança.

Quais as vantagens de usar a recorrência programada para o MusicFy?

  1. Facilidade: a cobrança de mensalidade é automática, logo o MusicFy não precisa se preocupar em construir um sistema de cobrança;

  2. Usabilidade: o valor das assinaturas pode ser atualizado sem a necessidade de refazer a transação. Um mês pode ser cancelado ou a recorrência pode ter um delay (o modelo de 30 dias gratuito) com apenas uma configuração;

  3. Segurança: a MusicFy não precisa armazenar dados sensíveis do cartão e do comprador;

  4. Conversão: a Recorrência Programada Cielo possui um sistema de retentativa automática. Caso uma das transações seja negada, ela será retentada até quatro vezes, buscando atingir a autorização.

Criando Recorrências

Criando uma Recorrência Própria

Para criar uma venda recorrente cuja o processo de recorrência e intervalo serão executados pela própria loja, basta fazer um POST conforme o exemplo.

A requisição segue a estrutura de uma transação de crédito padrão, mas o paramêtro Payment.Recurrent deve ser true; caso contrário, a transação será negada.

Requisição

{  
   "MerchantOrderId":"2014113245231706",
   "Customer":{  
      "Name":"Comprador rec propria"
   },
   "Payment":{  
     "Type":"CreditCard",
     "Amount":1500,
     "Installments":1,
     "SoftDescriptor":"123456789ABCD",
     "Recurrent": true,
     "CreditCard":{  
         "CardNumber":"1234123412341231",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"262",
         "SaveCard":"false",
         "Brand":"Visa"
     }
   }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
    {
   "MerchantOrderId":"2014113245231706",
   "Customer":{  
      "Name":"Comprador rec propria"
   },
   "Payment":{  
     "Type":"CreditCard",
     "Amount":1500,
     "Installments":1,
     "SoftDescriptor":"123456789ABCD",
     "Recurrent": true,
     "CreditCard":{  
         "CardNumber":"1234123412341231",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"262",
         "SaveCard":"false",
         "Brand":"Visa"
     }
   }
}
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API E-commerce Cielo. Guid 6 Sim
MerchantKey Chave Pública para Autenticação Dupla na API E-commerce Cielo. Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
MerchantOrderId Numero de identificação do Pedido. Texto 50 Sim
Customer.Name Nome do Comprador. Texto 255 Sim
Payment.Type Tipo do Meio de Pagamento. Texto 100 Sim
Payment.Amount Valor do Pedido (ser enviado em centavos). Número 15 Sim
Payment.Installments Número de Parcelas. Número 2 Sim
Payment.SoftDescriptor Texto que será impresso na fatura bancaria do portador - Disponivel apenas para VISA/MASTER - não permite caracteres especiais Texto 13 Não
Payment.Recurrent marcação de uma transação de recorrencia não programada boolean 5 Não
CreditCard.CardNumber Número do Cartão do Comprador. Texto 19 Sim
CreditCard.Holder Nome do Comprador impresso no cartão. Texto 25 Não
CreditCard.ExpirationDate Data de validade impresso no cartão. Texto 7 Sim
CreditCard.SecurityCode Código de segurança impresso no verso do cartão. Texto 4 Não
CreditCard.Brand Bandeira do cartão. Texto 10 Sim

Resposta

{
    "MerchantOrderId": "2014113245231706",
    "Customer": {
        "Name": "Comprador rec propria"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": false,
        "Authenticate": false,
        "Recurrent": true,
        "CreditCard": {
            "CardNumber": "123412******1231",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa"
        },
        "ProofOfSale": "3827556",
        "Tid": "0504043827555",
        "AuthorizationCode": "149867",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId": "737a8d9a-88fe-4f74-931f-acf81149f4a0",
        "Type": "CreditCard",
        "Amount": 1500,
        "Currency": "BRL",
        "Country": "BRA",
        "Provider": "Simulado",
        "ExtraDataCollection": [],
        "Status": 1,
        "ReturnCode": "4",
        "ReturnMessage": "Operation Successful",
        "Link": {
                "Method": "GET",
                "Rel": "recurrentPayment",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}"
            },
            "AuthorizeNow": true
        },
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            },
            {
                "Method": "PUT",
                "Rel": "capture",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2014113245231706",
    "Customer": {
        "Name": "Comprador rec propria"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": false,
        "Authenticate": false,
        "Recurrent": true,
        "CreditCard": {
            "CardNumber": "123412******1231",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa"
        },
        "ProofOfSale": "3827556",
        "Tid": "0504043827555",
        "AuthorizationCode": "149867",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId": "737a8d9a-88fe-4f74-931f-acf81149f4a0",
        "Type": "CreditCard",
        "Amount": 1500,
        "Currency": "BRL",
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 1,
        "ReturnCode": "4",
        "ReturnMessage": "Operation Successful",
        "Link": {
                "Method": "GET",
                "Rel": "recurrentPayment",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}"
            },
            "AuthorizeNow": true
        },
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            },
            {
                "Method": "PUT",
                "Rel": "capture",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API E-commerce Cielo. Guid 6 Sim
MerchantKey Chave Publica para Autenticação Dupla na API E-commerce Cielo. Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
MerchantOrderId Numero de identificação do Pedido. Texto 50 Sim
Customer.Name Nome do Comprador. Texto 255 Não
Payment.Type Tipo do Meio de Pagamento. Texto 100 Sim
Payment.Amount Valor do Pedido (ser enviado em centavos). Número 15 Sim
Payment.Installments Número de Parcelas. Número 2 Sim
Payment.SoftDescriptor Texto que será impresso na fatura bancaria do portador - Disponivel apenas para VISA/MASTER - não permite caracteres especiais Texto 13 Não
Payment.Recurrent marcação de uma transação de recorrencia não programada boolean 5 Não
CreditCard.CardNumber Número do Cartão do Comprador. Texto 19 Sim
CreditCard.Holder Nome do Comprador impresso no cartão. Texto 25 Não
CreditCard.ExpirationDate Data de validade impresso no cartão. Texto 7 Sim
CreditCard.SecurityCode Código de segurança impresso no verso do cartão. Texto 4 Não
CreditCard.Brand Bandeira do cartão. Texto 10 Sim

Criando uma Recorrência Programada

Para criar uma venda recorrente cuja a primeira recorrência é autorizada com a forma de pagamento cartão de crédito, basta fazer um POST conforme o exemplo.

Requisição

{  
   "MerchantOrderId":"2014113245231706",
   "Customer":{  
      "Name":"Comprador rec programada"
   },
   "Payment":{  
     "Type":"CreditCard",
     "Amount":1500,
     "Installments":1,
     "SoftDescriptor":"123456789ABCD",
     "RecurrentPayment":{
       "AuthorizeNow":"true",
       "EndDate":"2019-12-01",
       "Interval":"SemiAnnual"
     },
     "CreditCard":{  
         "CardNumber":"1234123412341231",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"262",
         "SaveCard":"false",
         "Brand":"Visa"
     }
   }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
    {
   "MerchantOrderId":"2014113245231706",
   "Customer":{  
      "Name":"Comprador rec programada"
   },
   "Payment":{  
     "Type":"CreditCard",
     "Amount":1500,
     "Installments":1,
     "SoftDescriptor":"123456789ABCD",
     "RecurrentPayment":{
       "AuthorizeNow":"true",
       "EndDate":"2019-12-01",
       "Interval":"SemiAnnual"
     },
     "CreditCard":{  
         "CardNumber":"1234123412341231",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"262",
         "SaveCard":"false",
         "Brand":"Visa"
     }
   }
}
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API Cielo eCommerce. Guid 6 Sim
MerchantKey Chave Publica para Autenticação Dupla na API Cielo eCommerce. Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
MerchantOrderId Numero de identificação do Pedido. Texto 50 Sim
Customer.Name Nome do Comprador. Texto 255 Sim
Payment.Type Tipo do Meio de Pagamento. Texto 100 Sim
Payment.Amount Valor do Pedido (ser enviado em centavos). Número 15 Sim
Payment.Installments Número de Parcelas. Número 2 Sim
Payment.SoftDescriptor Texto que será impresso na fatura bancaria do portador - Disponivel apenas para VISA/MASTER - não permite caracteres especiais Texto 13 Não
Payment.RecurrentPayment.EndDate Data para termino da recorrência. Texto 10 Não
Payment.RecurrentPayment.Interval Intervalo da recorrência.
Monthly (Default) Bimonthly Quarterly SemiAnnual Annual
Texto 10 Não
Payment.RecurrentPayment.AuthorizeNow Booleano para saber se a primeira recorrência já vai ser Autorizada ou não. Booleano Sim
CreditCard.CardNumber Número do Cartão do Comprador. Texto 19 Sim
CreditCard.Holder Nome do Comprador impresso no cartão. Texto 25 Não
CreditCard.ExpirationDate Data de validade impresso no cartão. Texto 7 Sim
CreditCard.SecurityCode Código de segurança impresso no verso do cartão. Texto 4 Não
CreditCard.Brand Bandeira do cartão. Texto 10 Sim

Resposta

{
    "MerchantOrderId": "2014113245231706",
    "Customer": {
        "Name": "Comprador rec programada"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": false,
        "Authenticate": false,
        "Recurrent": false,
        "CreditCard": {
            "CardNumber": "123412******1231",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa"
        },
        "ProofOfSale": "3827556",
        "Tid": "0504043827555",
        "AuthorizationCode": "149867",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId": "737a8d9a-88fe-4f74-931f-acf81149f4a0",
        "Type": "CreditCard",
        "Amount": 1500,
        "Currency": "BRL",
        "Country": "BRA",
        "Provider": "Simulado",
        "ExtraDataCollection": [],
        "Status": 1,
        "ReturnCode": "4",
        "ReturnMessage": "Operation Successful",
        "RecurrentPayment": {
            "RecurrentPaymentId": "61e5bd30-ec11-44b3-ba0a-56fbbc8274c5",
            "NextRecurrency": "2015-11-04",
            "EndDate": "2019-12-01",
            "Interval": "SemiAnnual",
            "Link": {
                "Method": "GET",
                "Rel": "recurrentPayment",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}"
            },
            "AuthorizeNow": true
        },
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            },
            {
                "Method": "PUT",
                "Rel": "capture",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2014113245231706",
    "Customer": {
        "Name": "Comprador rec programada"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": false,
        "Authenticate": false,
        "Recurrent": false,
        "CreditCard": {
            "CardNumber": "123412******1231",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa"
        },
        "ProofOfSale": "3827556",
        "Tid": "0504043827555",
        "AuthorizationCode": "149867",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId": "737a8d9a-88fe-4f74-931f-acf81149f4a0",
        "Type": "CreditCard",
        "Amount": 1500,
        "Currency": "BRL",
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 1,
        "ReturnCode": "4",
        "ReturnMessage": "Operation Successful",
        "RecurrentPayment": {
            "RecurrentPaymentId": "61e5bd30-ec11-44b3-ba0a-56fbbc8274c5",
            "NextRecurrency": "2015-11-04",
            "EndDate": "2019-12-01",
            "Interval": "SemiAnnual",
            "Link": {
                "Method": "GET",
                "Rel": "recurrentPayment",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}"
            },
            "AuthorizeNow": true
        },
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            },
            {
                "Method": "PUT",
                "Rel": "capture",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
Propriedade Descrição Tipo Tamanho Formato
RecurrentPaymentId Campo Identificador da próxima recorrência. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
NextRecurrency Data da próxima recorrência. Texto 7 12/2030 (MM/YYYY)
EndDate Data do fim da recorrência. Texto 7 12/2030 (MM/YYYY)
Interval Intervalo entre as recorrências. Número 10
Monthly = 1
Bimonthly = 2
Quarterly = 3
SemiAnnual = 6
Annual = 12
AuthorizeNow Booleano para saber se a primeira recorrência já vai ser autorizada ou não. Booleano true

Agendando uma Recorrência Programada

Para criar uma venda recorrente cuja a primeira recorrência não será autorizada na mesma data com a forma de pagamento cartão de crédito, basta fazer um POST conforme o exemplo.

Diferente da recorrência anterior, este exemplo não autoriza imediatamente, mas agenda uma autorização futura. Para programar a primeira transação da série de recorrências, passe o parâmetro AuthorizeNow como “false” e adicione o parâmetro StartDate.

Requisição

{  
   "MerchantOrderId":"2014113245231706",
   "Customer":{  
      "Name":"Comprador rec programada"
   },
   "Payment":{  
     "Type":"CreditCard",
     "Amount":1500,
     "Installments":1,
     "SoftDescriptor":"123456789ABCD",
     "RecurrentPayment":{
       "AuthorizeNow":"false",
       "EndDate":"2019-12-01",
       "Interval":"SemiAnnual",
       "StartDate":"2015-06-01"
     },
     "CreditCard":{  
         "CardNumber":"1234123412341231",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"262",
         "SaveCard":"false",
         "Brand":"Visa"
     }
   }
}
curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{  
   "MerchantOrderId":"2014113245231706",
   "Customer":{  
      "Name":"Comprador rec programada"
   },
   "Payment":{  
     "Type":"CreditCard",
     "Amount":1500,
     "Installments":1,
     "SoftDescriptor":"123456789ABCD",
     "RecurrentPayment":{
       "AuthorizeNow":"false",
       "EndDate":"2019-12-01",
       "Interval":"SemiAnnual",
       "StartDate":"2015-06-01"
     },
     "CreditCard":{  
         "CardNumber":"1234123412341231",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"262",
         "SaveCard":"false",
         "Brand":"Visa"
     }
   }
}
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API Cielo eCommerce Guid 36 Sim
MerchantKey Chave Publica para Autenticação Dupla na API Cielo eCommerce Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
RecurrentPaymentId Numero de identificação da Recorrência. Texto 50 Sim
Customer.Name Nome do Comprador. Texto 255 Não
Customer.Status Status de cadastro do comprador na loja (NEW / EXISTING) - Utilizado pela análise de fraude Texto 255 Não
Customer.Email Email do Comprador. Texto 255 Não
Customer.Birthdate Data de nascimento do Comprador. Date 10 Não
Customer.Identity Número do RG, CPF ou CNPJ do Cliente. Texto 14 Não
Customer.Address.Street Endereço do Comprador. Texto 255 Não
Customer.Address.Number Número do endereço do Comprador. Texto 15 Não
Customer.Address.Complement Complemento do endereço do Comprador. Texto 50 Não
Customer.Address.ZipCode CEP do endereço do Comprador. Texto 9 Não
Customer.Address.City Cidade do endereço do Comprador. Texto 50 Não
Customer.Address.State Estado do endereço do Comprador. Texto 2 Não
Customer.Address.Country Pais do endereço do Comprador. Texto 35 Não
Customer.Address.District Bairro do Comprador. Texto 50 Não
Customer.DeliveryAddress.Street Endereço do Comprador. Texto 255 Não
Customer.DeliveryAddress.Number Número do endereço do Comprador. Texto 15 Não
Customer.DeliveryAddress.Complement Complemento do endereço do Comprador. Texto 50 Não
Customer.DeliveryAddress.ZipCode CEP do endereço do Comprador. Texto 9 Não
Customer.DeliveryAddress.City Cidade do endereço do Comprador. Texto 50 Não
Customer.DeliveryAddress.State Estado do endereço do Comprador. Texto 2 Não
Customer.DeliveryAddress.Country Pais do endereço do Comprador. Texto 35 Não
Customer.DeliveryAddress.District Bairro do Comprador. Texto 50 Não

Resposta

{
    "MerchantOrderId": "2014113245231706",
    "Customer": {
        "Name": "Comprador rec programada"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": false,
        "Authenticate": false,
        "Recurrent": false,
        "CreditCard": {
            "CardNumber": "123412******1231",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa"
        },
        "SoftDescriptor":"123456789ABCD",
        "Type": "CreditCard",
        "Amount": 1500,
        "Currency": "BRL",
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 20,
        "RecurrentPayment": {
            "RecurrentPaymentId": "0d2ff85e-594c-47b9-ad27-bb645a103db4",
            "NextRecurrency": "2015-06-01",
            "StartDate": "2015-06-01",
            "EndDate": "2019-12-01",
            "Interval": "SemiAnnual",
            "Link": {
                "Method": "GET",
                "Rel": "recurrentPayment",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{PaymentId}"
            },
            "AuthorizeNow": false
        }
    }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2014113245231706",
    "Customer": {
        "Name": "Comprador rec programada"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": false,
        "Authenticate": false,
        "Recurrent": false,
        "CreditCard": {
            "CardNumber": "123412******1231",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa"
        },
        "SoftDescriptor":"123456789ABCD",
        "Type": "CreditCard",
        "Amount": 1500,
        "Currency": "BRL",
        "Country": "BRA",
        "Provider": "Simulado",
        "ExtraDataCollection": [],
        "Status": 20,
        "RecurrentPayment": {
            "RecurrentPaymentId": "0d2ff85e-594c-47b9-ad27-bb645a103db4",
            "NextRecurrency": "2015-06-01",
            "StartDate": "2015-06-01",
            "EndDate": "2019-12-01",
            "Interval": "SemiAnnual",
            "Link": {
                "Method": "GET",
                "Rel": "recurrentPayment",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{PaymentId}"
            },
            "AuthorizeNow": false
        }
    }
}
Propriedade Descrição Tipo Tamanho Formato
RecurrentPaymentId Campo Identificador da próxima recorrência. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
NextRecurrency Data da próxima recorrência. Texto 7 12/2030 (MM/YYYY)
StartDate Data do inicio da recorrência. Texto 7 12/2030 (MM/YYYY)
EndDate Data do fim da recorrência. Texto 7 12/2030 (MM/YYYY)
Interval Intervalo entre as recorrências. Número 10
Monthly = 1
Bimonthly = 2
Quarterly = 3
SemiAnnual = 6
Annual = 12
AuthorizeNow Booleano para saber se a primeira recorrência já vai ser autorizada ou se será apenas agendada. Booleano false

Modificando Recorrências

Modificando dados do comprador

Altera dados do comprador da recorrência.

Requisição

{  
      "Name":"Customer",
      "Email":"customer@teste.com",
      "Birthdate":"1999-12-12",
      "Identity":"22658954236",
      "IdentityType":"CPF",
      "Address":{  
         "Street":"Rua Teste",
         "Number":"174",
         "Complement":"AP 201",
         "ZipCode":"21241140",
         "City":"Rio de Janeiro",
         "State":"RJ",
         "Country":"BRA"
      },
      "DeliveryAddress":{  
         "Street":"Outra Rua Teste",
         "Number":"123",
         "Complement":"AP 111",
         "ZipCode":"21241111",
         "City":"Qualquer Lugar",
         "State":"QL",
         "Country":"BRA",
        "District":"Teste"
      }
}
curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}/Customer"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{  
      "Name":"Customer",
      "Email":"customer@teste.com",
      "Birthdate":"1999-12-12",
      "Identity":"22658954236",
      "IdentityType":"CPF",
      "Address":{  
         "Street":"Rua Teste",
         "Number":"174",
         "Complement":"AP 201",
         "ZipCode":"21241140",
         "City":"Rio de Janeiro",
         "State":"RJ",
         "Country":"BRA"
      },
      "DeliveryAddress":{  
         "Street":"Outra Rua Teste",
         "Number":"123",
         "Complement":"AP 111",
         "ZipCode":"21241111",
         "City":"Qualquer Lugar",
         "State":"QL",
         "Country":"BRA",
        "District":"Teste"
      }
   }
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API Cielo eCommerce Guid 36 Sim
MerchantKey Chave Publica para Autenticação Dupla na API Cielo eCommerce Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
RecurrentPaymentId Numero de identificação da Recorrência. Texto 50 Sim
Customer.Name Nome do Comprador. Texto 255 Não
Customer.Status Status de cadastro do comprador na loja (NEW / EXISTING) - Utilizado pela análise de fraude Texto 255 Não
Customer.Email Email do Comprador. Texto 255 Não
Customer.Birthdate Data de nascimento do Comprador. Date 10 Não
Customer.Identity Número do RG, CPF ou CNPJ do Cliente. Texto 14 Não
Customer.IdentityType Texto 255 Não Tipo de documento de identificação do comprador (CFP/CNPJ).
Customer.Address.Street Endereço do Comprador. Texto 255 Não
Customer.Address.Number Número do endereço do Comprador. Texto 15 Não
Customer.Address.Complement Complemento do endereço do Comprador. Texto 50 Não
Customer.Address.ZipCode CEP do endereço do Comprador. Texto 9 Não
Customer.Address.City Cidade do endereço do Comprador. Texto 50 Não
Customer.Address.State Estado do endereço do Comprador. Texto 2 Não
Customer.Address.Country Pais do endereço do Comprador. Texto 35 Não
Customer.Address.District Bairro do Comprador. Texto 50 Não
Customer.DeliveryAddress.Street Endereço do Comprador. Texto 255 Não
Customer.DeliveryAddress.Number Número do endereço do Comprador. Texto 15 Não
Customer.DeliveryAddress.Complement Complemento do endereço do Comprador. Texto 50 Não
Customer.DeliveryAddress.ZipCode CEP do endereço do Comprador. Texto 9 Não
Customer.DeliveryAddress.City Cidade do endereço do Comprador. Texto 50 Não
Customer.DeliveryAddress.State Estado do endereço do Comprador. Texto 2 Não
Customer.DeliveryAddress.Country Pais do endereço do Comprador. Texto 35 Não
Customer.DeliveryAddress.District Bairro do Comprador. Texto 50 Não

Resposta


HTTP Status 200

Veja o Anexo HTTP Status Code para a lista com todos os códigos de status HTTP possivelmente retornados pela API.

Modificando data final da recorrência

Altera a data final da recorrência.

Requisição


"2021-01-09"

curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}/EndDate"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
"2021-01-09"
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API Cielo eCommerce. Guid 36 Sim
MerchantKey Chave Publica para Autenticação Dupla na API Cielo eCommerce. Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
RecurrentPaymentId Numero de identificação da Recorrência. Texto 50 Sim
EndDate Data para termino da recorrência. Texto 10 Sim

Resposta


HTTP Status 200

Veja o Anexo HTTP Status Code para a lista com todos os códigos de status HTTP possivelmente retornados pela API.

Modificando intevalo da Recorrência

Altera o intervalo da Recorrência.

Requisição


6

curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}/Interval"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
6
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API Cielo eCommerce. Guid 36 Sim
MerchantKey Chave Publica para Autenticação Dupla na API Cielo eCommerce. Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
RecurrentPaymentId Numero de identificação da Recorrência. Texto 50 Sim
Interval Intervalo da recorrência.
Monthly = 1
Bimonthly = 2
Quarterly = 3
SemiAnnual = 6
Annual = 12
Número 2 Sim

Resposta

HTTP Status 200

Veja o Anexo HTTP Status Code para a lista com todos os códigos de status HTTP possivelmente retornados pela API.

Modificar dia da recorrência

Altera o dia da recorrência.

Ao efetuar a alteração do dia da recorrência, considere as seguintes regras para execução da atualização na API:

1) Se o novo dia informado for depois do dia atual, iremos atualizar o dia da recorrência com efeito na próxima recorrência. Ex.: Hoje é dia 05/05 e a próxima recorrência é dia 25/05. Quando atualizado para o dia 10, a data da próxima recorrência será dia 10/05.

2) Se o novo dia informado for antes do dia atual, iremos atualizar o dia da recorrência, mas este só terá efeito depois que a próxima recorrência for executada com sucesso. Ex.: Hoje é dia 05/05 e a próxima recorrência é dia 25/05. Quando atualizado para o dia 03, a data da próxima recorrência permanecerá dia 25/05. Após sua execução, a recorrência seguinte será agendada para o dia 03/06.

3) Se o novo dia informado for antes do dia atual, mas a próxima recorrência for em outro mês, iremos atualizar o dia da recorrência com efeito na próxima recorrência. Ex.: Hoje é dia 05/05 e a próxima recorrência é dia 25/09. Quando atualizado para o dia 03, a data da próxima recorrência será 03/09.

Requisição

16
curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}/RecurrencyDay"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
16
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API Cielo eCommerce. Guid 36 Sim
MerchantKey Chave Publica para Autenticação Dupla na API Cielo eCommerce. Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
RecurrentPaymentId Numero de identificação da Recorrência. Texto 50 Sim
RecurrencyDay Dia da Recorrência. Número 2 Sim

Resposta

HTTP Status 200

Veja o Anexo HTTP Status Code para a lista com todos os códigos de status HTTP possivelmente retornados pela API.

Modificando o valor da recorrência

Altera o valor da recorrência.

Requsição

156
curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}/Amount"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
156
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API Cielo eCommerce. Guid 36 Sim
MerchantKey Chave Publica para Autenticação Dupla na API Cielo eCommerce. Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
RecurrentPaymentId Numero de identificação da Recorrência. Texto 50 Sim
Payment.Amount Valor do Pedido em centavos: 156 equivale a R$ 1,56 Número 15 Sim

Resposta

HTTP Status 200

Veja o Anexo HTTP Status Code para a lista com todos os códigos de status HTTP possivelmente retornados pela API.

Modificando data do próximo pagamento

Altera a data do próximo pagamento.

Requisição

"2016-06-15"
curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}/NextPaymentDate"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
"2016-06-15"
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API Cielo eCommerce. Guid 36 Sim
MerchantKey Chave Publica para Autenticação Dupla na API Cielo eCommerce. Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
RecurrentPaymentId Numero de identificação da Recorrência. Texto 50 Sim
NextPaymentDate Data de pagamento da próxima recorrência. Texto 10 Sim

Resposta

HTTP Status 200

Veja o Anexo HTTP Status Code para a lista com todos os códigos de status HTTP possivelmente retornados pela API.

Modificando dados do pagamento da recorrência

Alterar os dados de pagamento da recorrência.

Requisição

{  
   "Type":"CreditCard",
   "Amount":"123",
   "Installments":3,
   "Country":"USA",
   "Currency":"BRL",
   "SoftDescriptor":"123456789ABCD",
   "CreditCard":{  
      "Brand":"Master",
      "Holder":"Teset card",
      "CardNumber":"1234123412341232",
      "ExpirationDate":"12/2030"
   }
}
curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}/Payment"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{  
   "Type":"CreditCard",
   "Amount":"123",
   "Installments":3,
   "Country":"USA",
   "Currency":"BRL",
   "SoftDescriptor":"123456789ABCD",
   "CreditCard":{  
      "Brand":"Master",
      "Holder":"Teset card",
      "CardNumber":"1234123412341232",
      "ExpirationDate":"12/2030"
   }
}
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API Cielo eCommerce. Guid 36 Sim
MerchantKey Chave Publica para Autenticação Dupla na API Cielo eCommerce. Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
RecurrentPaymentId Numero de identificação da Recorrência. Texto 50 Sim
Payment.Type Tipo do Meio de Pagamento. Texto 100 Sim
Payment.Amount Valor do Pedido (ser enviado em centavos). Número 15 Sim
Payment.Installments Número de Parcelas. Número 2 Sim
Payment.SoftDescriptor Texto que será impresso na fatura bancaria do portador - Disponivel apenas para VISA/MASTER - não permite caracteres especiais Texto 13 Não
CreditCard.CardNumber Número do Cartão do Comprador. Texto 16 Sim
CreditCard.Holder Nome do Comprador impresso no cartão. Texto 25 Não
CreditCard.ExpirationDate Data de validade impresso no cartão. Texto 7 Sim
CreditCard.SecurityCode Código de segurança impresso no verso do cartão. Texto 4 Não
CreditCard.Brand Bandeira do cartão. Texto 10 Sim

Resposta

HTTP Status 200

Veja o Anexo HTTP Status Code para a lista com todos os códigos de status HTTP possivelmente retornados pela API.

Desabilitando um pedido recorrente

Para desabilitar um pedido recorrente, basta fazer um Put conforme o exemplo.

Requisição

curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}/Deactivate"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API Cielo eCommerce. Guid 36 Sim
MerchantKey Chave Publica para Autenticação Dupla na API Cielo eCommerce. Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
RecurrentPaymentId Numero de identificação da Recorrência. Texto 50 Sim

Resposta

HTTP Status 200

Veja o Anexo HTTP Status Code para a lista com todos os códigos de status HTTP possivelmente retornados pela API.

Reabilitando um pedido recorrente

Reabilita um pedido recorrente.

Requisição

curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}/Reactivate"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API Cielo eCommerce. Guid 36 Sim
MerchantKey Chave Publica para Autenticação Dupla na API Cielo eCommerce. Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
RecurrentPaymentId Numero de identificação da Recorrência. Texto 50 Sim

Resposta

HTTP Status 200

Veja o Anexo HTTP Status Code para a lista com todos os códigos de status HTTP possivelmente retornados pela API.

Renova Fácil

O Renova Fácil é um serviço desenvolvido pela Cielo em conjunto com os emissores, cujo objetivo é aumentar a taxa de conversão de vendas recorrentes com cartão de crédito e débito.

O uso desta funcionalidade permite a substituição automática de um cartão de crédito ou débito que foi substituído pelo banco emissor por algum motivo (vencimento atingido, troca etc). Dessa forma, quando uma transação com marcação de recorrência for submetida para a API e a Cielo identificar que o cartão enviado foi substituído, sua autorização será negada e a API retornará os dados do novo cartão nó NewCard.

Veja a seguir o exemplo de resposta de uma transação de crédito.

Resposta

{
  "MerchantOrderId": "2014113245231706",
  "Customer": {
    "Name": "Comprador  Renova facil"
  },
  "Payment": {
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": 0,
    "Capture": false,
    "Authenticate": false,
    "Recurrent": false,
    "CreditCard": {
      "CardNumber": "123412******1231",
      "Holder": "Teste Holder",
      "ExpirationDate": "12/2030",
      "SaveCard": false,
      "Brand": "Visa"
    },
    "Tid": "10447480685P4611AQ9B",
    "ProofOfSale": "087001",
    "SoftDescriptor": "123456789ABCD",
    "Provider": "Cielo",
    "Eci": "0",
    "NewCard": {
       "CardNumber": "40000000000000000",
       "ExpirationDate": "10/2020",
       "SaveCard": false,
        "Brand": "Visa"
    },
    "VelocityAnalysis": {
      "Id": "94f06657-c715-45d2-a563-63f7dbb19e08",
      "ResultMessage": "Accept",
      "Score": 0
    },
    "PaymentId": "94f06657-c715-45d2-a563-63f7dbb19e08",
    "Type": "CreditCard",
    "Amount": 1500,
    "ReceivedDate": "2016-12-26 14:14:21",
    "Currency": "BRL",
    "Country": "BRA",
    "ReturnCode": "KA",
    "ReturnMessage": "Autorizacao negada",
    "Status": 3,
    "RecurrentPayment": {
      "ReasonCode": 7,
      "ReasonMessage": "Denied",
      "EndDate": "2019-12-01",
      "Interval": 6,
      "AuthorizeNow": true
    },
    "Links": [
      {
        "Method": "GET",
        "Rel": "self",
        "Href": "https://apiquery.cieloecommerce.cielo.com.br/1/sales/94f06657-c715-45d2-a563-63f7dbb19e08"
      }
    ]
  }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
  "MerchantOrderId": "2014113245231706",
  "Customer": {
    "Name": "Comprador  Renova facil"
  },
  "Payment": {
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": 0,
    "Capture": false,
    "Authenticate": false,
    "Recurrent": false,
    "CreditCard": {
      "CardNumber": "123412******1231",
      "Holder": "Teste Holder",
      "ExpirationDate": "12/2030",
      "SaveCard": false,
      "Brand": "Visa"
    },
    "Tid": "10447480685P4611AQ9B",
    "ProofOfSale": "087001",
    "SoftDescriptor": "123456789ABCD",
    "Provider": "Cielo",
    "Eci": "0",
    "NewCard": {
       "CardNumber": "40000000000000000",
       "ExpirationDate": "10/2020",
       "SaveCard": false,
        "Brand": "Visa"
    },
    "VelocityAnalysis": {
      "Id": "94f06657-c715-45d2-a563-63f7dbb19e08",
      "ResultMessage": "Accept",
      "Score": 0
    },
    "PaymentId": "94f06657-c715-45d2-a563-63f7dbb19e08",
    "Type": "CreditCard",
    "Amount": 1500,
    "ReceivedDate": "2016-12-26 14:14:21",
    "Currency": "BRL",
    "Country": "BRA",
    "ReturnCode": "KA",
    "ReturnMessage": "Autorizacao negada",
    "Status": 3,
    "RecurrentPayment": {
      "ReasonCode": 7,
      "ReasonMessage": "Denied",
      "EndDate": "2019-12-01",
      "Interval": 6,
      "AuthorizeNow": true
    },
    "Links": [
      {
        "Method": "GET",
        "Rel": "self",
        "Href": "https://apiquery.cieloecommerce.cielo.com.br/1/sales/94f06657-c715-45d2-a563-63f7dbb19e08"
      }
    ]
  }
}
Propriedade Descrição Tipo Tamanho Formato
RecurrentPaymentId Campo Identificador da próxima recorrência. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
NextRecurrency Data da próxima recorrência. Texto 7 12/2030 (MM/YYYY)
EndDate Data do fim da recorrência. Texto 7 12/2030 (MM/YYYY)
Interval Intervalo entre as recorrência. Texto 10 / Monthly / Bimonthly / Quarterly / SemiAnnual / Annual
AuthorizeNow Booleano para saber se a primeira recorrencia já vai ser Autorizada ou não. Booleano true ou false
Propriedade Descrição Tipo Tamanho Obrigatório
NewCard.CardNumber Novo número do Cartão do Comprador. Texto 16 Sim
NewCard.ExpirationDate nova data de validade do cartão. Texto 7 Sim
NewCard.Brand Bandeira do cartão. Texto 10 Sim
NewCard.SaveCard Identifica se o cartão gerou Cardtoken durante a transação Booleano Sim

Bandeiras e emissores habilitados

Bandeiras e emissores que já habilitaram o Renova Fácil:

Emissores VISA MASTER ELO Amex
BRADESCO Sim Sim Sim Sim
BANCO DO BRASIL Sim
SANTANDER Sim
CITI Sim
BANCO PAN Sim

Consulta, Captura e Cancelamento

Consulta de transações

Consulta por PaymentId

Para consultar uma venda de cartão de crédito via PaymentId, siga a requisição de exemplo a seguir.

Requisição

curl
--request GET "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API e-commerce Cielo. Guid 36 Sim
MerchantKey Chave pública para Autenticação Dupla na API e-commerce Cielo. Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
PaymentId Número de identificação do pagamento, necessário para futuras operações como Consulta, Captura e Cancelamento. Texto 36 Sim

Resposta

}
"MerchantOrderId": "2014111706",
"AcquirerOrderId": "202202231037440D1BD0",
"Customer": {
    "Name": "Comprador Teste",
    "Address": {}
},
"Payment": {
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": "ByMerchant",
    "Capture": false,
    "Authenticate": false,
    "CreditCard": {
        "CardNumber": "455187******0183",
        "Holder": "Teste Holder",
        "ExpirationDate": "12/2030",
        "SaveCard": false,
        "Brand": "Visa",
        "PaymentAccountReference":"92745135160550440006111072222"
    },
    "ProofOfSale": "674532",
    "Tid": "0223103744208",
    "AuthorizationCode": "123456",
    "Chargebacks": [
        {
            "Amount": 10000,
            "CaseNumber": "123456",
            "Date": "2022-06-04",
            "ReasonCode": "104",
            "ReasonMessage": "Outras Fraudes - Cartao Ausente",
            "Status": "Received",
            "RawData": "Client did not participate and did not authorize transaction"
        }
    ],
    "FraudAlert": {
        "Date": "2022-05-20",
        "ReasonMessage": "Uso Ind Numeração",
        "IncomingChargeback": false
    },
    "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
    "Type": "CreditCard",
    "Amount": 10000,
    "ReceivedDate": "2022-07-29 17:16:21",
    "CapturedAmount": 9000,
    "CapturedDate": "2022-07-29 17:16:22",
    "VoidedAmount": 1000,
    "VoidedDate": "2022-05-15 16:25:38",
    "Currency": "BRL",
    "Country": "BRA",
    "ExtraDataCollection": [],
    "Status": 1,
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
        },
        {
            "Method": "PUT",
            "Rel": "capture",
            "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
        },
        {
            "Method": "PUT",
            "Rel": "void",
            "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
        }
    ]
}
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2014111706",
    "AcquirerOrderId": "202202231037440D1BD0",
    "Customer": {
        "Name": "Comprador Teste",
        "Address": {}
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": false,
        "Authenticate": false,
        "CreditCard": {
            "CardNumber": "455187******0183",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa",
            "PaymentAccountReference":"92745135160550440006111072222"
        },
        "ProofOfSale": "674532",
        "Tid": "0223103744208",
        "AuthorizationCode": "123456",
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "CreditCard",
        "Amount": 10000,
        "ReceivedDate": "2022-07-29 17:16:21",
        "CapturedAmount": 9000,
        "CapturedDate": "2022-07-29 17:16:22",
        "VoidedAmount": 1000,
        "VoidedDate": "2022-05-15 16:25:38",
        "Currency": "BRL",
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 1,
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            },
            {
                "Method": "PUT",
                "Rel": "capture",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
Propriedade Descrição Tipo Tamanho Formato
MerchantOrderId Número de identificação do pedido. Texto 50 Texto alfanumérico
AcquirerOrderId Id da transação enviado ao autorizador, caso o MerchantOrderId seja maior que 20 caracteres ou tenha símbolos. Texto 50 Texto alfanumérico
AuthorizationCode Código de autorização. Texto 6 Texto alfanumérico
PaymentId Campo Identificador do Pedido. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Status Status da Transação. Byte 2
Customer.Name Nome do Comprador. Texto 255 Texto
Customer.Status Status de cadastro do comprador na loja (NEW / EXISTING) Texto 255 Texto
Payment.ProofOfSale Número da autorização, identico ao NSU. Texto alfanumérico 6 Texto alfanumérico
Payment.Tid Id da transação no provedor do meio de pagamento. Texto alfanumérico 40 Texto alfanumérico
Payment.Type Tipo do Meio de Pagamento. Texto 100 Texto
Payment.Amount Valor do Pedido (ser enviado em centavos). Número 15 10000
Payment.ReceivedDate Data em que a transação foi recebida. Texto 19 AAAA-MM-DD HH:mm:SS
Payment.CapturedAmount Valor capturado. Número 15 10000
Payment.CapturedDate Data da captura. Texto 19 AAAA-MM-DD HH:mm:SS
Payment.VoidedAmount Valor cancelado/estornado, em centavos. Número 15 10000
Payment.VoidedDate Data do cancelamento/estorno. Texto 19 AAAA-MM-DD HH:mm:SS
Payment.Provider Define comportamento do meio de pagamento (ver Anexo)/NÃO OBRIGATÓRIO PARA CRÉDITO. Texto 15 Texto
CreditCard.CardNumber Número do Cartão do Comprador. Texto 19 Texto
CreditCard.Holder Nome do Comprador impresso no cartão. Texto 25 Texto
CreditCard.ExpirationDate Data de validade impresso no cartão. Texto 7 MM/AAAA
CreditCard.SecurityCode Código de segurança impresso no verso do cartão - Ver Anexo. Texto 4 Texto
CreditCard.Brand Bandeira do cartão (Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard / Hiper). Texto 10 Texto
CreditCard.PaymentAccountReference O PAR(payment account reference) é o número que associa diferentes tokens a um mesmo cartão. Será retornado pelas bandeiras Master e Visa e repassado para os clientes do e-commerce Cielo. Caso a bandeira não envie a informação o campo não será retornado. Se for pra transação de débito, colocar o campo dentro do nó de DebitCard Alfanumérico 29 Alfanumérico

Consulta por TId

Para consultar uma venda através do número de referência único da transação na adquirente (TId), execute um GET conforme descrito a seguir.

Requisição

curl
--request GET "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/acquirerTid/{TID}"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API e-commerce Cielo. Guid 36 Sim
MerchantKey Chave pública para Autenticação Dupla na API e-commerce Cielo. Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
AcquirerOrderId Id da transação enviado ao autorizador, caso o MerchantOrderId seja maior que 20 caracteres ou tenha símbolos. Texto 50 Sim
Tid Numero de identificação do pagamento na adquirente. Texto 36 Sim

Resposta

}
"MerchantOrderId": "2014111706",
"AcquirerOrderId": "202202231037440D1BD0",
"Customer": {
    "Name": "Comprador Teste",
    "Address": {}
},
"Payment": {
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": "ByMerchant",
    "Capture": false,
    "Authenticate": false,
    "CreditCard": {
        "CardNumber": "455187******0183",
        "Holder": "Teste Holder",
        "ExpirationDate": "12/2030",
        "SaveCard": false,
        "Brand": "Visa",
        "PaymentAccountReference":"92745135160550440006111072222"
    },
    "ProofOfSale": "674532",
    "Tid": "0223103744208",
    "AuthorizationCode": "123456",
    "Chargebacks": [
        {
            "Amount": 10000,
            "CaseNumber": "123456",
            "Date": "2022-06-04",
            "ReasonCode": "104",
            "ReasonMessage": "Outras Fraudes - Cartao Ausente",
            "Status": "Received",
            "RawData": "Client did not participate and did not authorize transaction"
        }
    ],
    "FraudAlert": {
        "Date": "2022-05-20",
        "ReasonMessage": "Uso Ind Numeração",
        "IncomingChargeback": false
    },
    "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
    "Type": "CreditCard",
    "Amount": 10000,
    "ReceivedDate": "2022-07-29 17:16:21",
    "CapturedAmount": 9000,
    "CapturedDate": "2022-07-29 17:16:22",
    "VoidedAmount": 1000,
    "VoidedDate": "2022-05-15 16:25:38",
    "Currency": "BRL",
    "Country": "BRA",
    "ExtraDataCollection": [],
    "Status": 1,
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
        },
        {
            "Method": "PUT",
            "Rel": "capture",
            "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
        },
        {
            "Method": "PUT",
            "Rel": "void",
            "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
        }
    ]
}
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2014111706",
    "AcquirerOrderId": "202202231037440D1BD0",
    "Customer": {
        "Name": "Comprador Teste",
        "Address": {}
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": false,
        "Authenticate": false,
        "CreditCard": {
            "CardNumber": "455187******0183",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa",
            "PaymentAccountReference":"92745135160550440006111072222"
        },
        "ProofOfSale": "674532",
        "Tid": "0223103744208",
        "AuthorizationCode": "123456",
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "CreditCard",
        "Amount": 10000,
        "ReceivedDate": "2022-07-29 17:16:21",
        "CapturedAmount": 9000,
        "CapturedDate": "2022-07-29 17:16:22",
        "VoidedAmount": 1000,
        "VoidedDate": "2022-05-15 16:25:38",
        "Currency": "BRL",
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 1,
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            },
            {
                "Method": "PUT",
                "Rel": "capture",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}
Propriedade Descrição Tipo Tamanho Formato
MerchantOrderId Número de identificação do pedido. Texto 50 Texto alfanumérico
AcquirerOrderId Id da transação enviado ao autorizador, caso o MerchantOrderId seja maior que 20 caracteres ou tenha símbolos. Texto 50 Texto alfanumérico
AuthorizationCode Código de autorização. Texto 6 Texto alfanumérico
PaymentId Campo Identificador do Pedido. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Status Status da Transação. Byte 2
Customer.Name Nome do Comprador. Texto 255 Texto
Customer.Status Status de cadastro do comprador na loja (NEW / EXISTING) Texto 255 Texto
Payment.ProofOfSale Número da autorização, identico ao NSU. Texto alfanumérico 6 Texto alfanumérico
Payment.Tid Id da transação no provedor do meio de pagamento. Texto alfanumérico 40 Texto alfanumérico
Payment.Type Tipo do Meio de Pagamento. Texto 100 Texto
Payment.Amount Valor do Pedido (ser enviado em centavos). Número 15 10000
Payment.ReceivedDate Data em que a transação foi recebida. Texto 19 AAAA-MM-DD HH:mm:SS
Payment.CapturedAmount Valor capturado. Número 15 10000
Payment.CapturedDate Data da captura. Texto 19 AAAA-MM-DD HH:mm:SS
Payment.VoidedAmount Valor cancelado/estornado, em centavos. Número 15 10000
Payment.VoidedDate Data do cancelamento/estorno. Texto 19 AAAA-MM-DD HH:mm:SS
Payment.Provider Define comportamento do meio de pagamento (ver Anexo)/NÃO OBRIGATÓRIO PARA CRÉDITO. Texto 15 Texto
CreditCard.CardNumber Número do Cartão do Comprador. Texto 19 Texto
CreditCard.Holder Nome do Comprador impresso no cartão. Texto 25 Texto
CreditCard.ExpirationDate Data de validade impresso no cartão. Texto 7 MM/AAAA
CreditCard.SecurityCode Código de segurança impresso no verso do cartão - Ver Anexo. Texto 4 Texto
CreditCard.Brand Bandeira do cartão (Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard / Hiper). Texto 10 Texto
CreditCard.PaymentAccountReference O PAR(payment account reference) é o número que associa diferentes tokens a um mesmo cartão. Será retornado pelas bandeiras Master e Visa e repassado para os clientes do e-commerce Cielo. Caso a bandeira não envie a informação o campo não será retornado. Se for pra transação de débito, colocar o campo dentro do nó de DebitCard Alfanumérico 29 Alfanumérico

Consulta por MerchantOrderId

Para alguns estabelecimentos, o MerchantOrderId pode ter várias transações. A consulta por MerchantOrderId retorna o PaymentId de todas as transações associadas a um MerchantOrderId.

A partir disso, é possível consultar detalhes de cada transação pela consulta por PaymentId.

Requisição

curls
--request GET " https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales?merchantOrderId={merchantOrderId}"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API Cielo eCommerce. Guid 36 Sim
MerchantKey Chave Publica para Autenticação Dupla na API Cielo eCommerce. Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
MerchantOrderId Campo identificador do pedido na loja. Texto 36 Sim

Resposta

{
    "Payment": [
        {
            "PaymentId": "5fb4d606-bb63-4423-a683-c966e15399e8",
            "ReceveidDate": "2015-04-06T10:13:39.42"
        },
        {
            "PaymentId": "6c1d45c3-a95f-49c1-a626-1e9373feecc2",
            "ReceveidDate": "2014-12-19T20:23:28.847"
        }
    ]
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "Payment": [
        {
            "PaymentId": "5fb4d606-bb63-4423-a683-c966e15399e8",
            "ReceveidDate": "2015-04-06T10:13:39.42"
        },
        {
            "PaymentId": "6c1d45c3-a95f-49c1-a626-1e9373feecc2",
            "ReceveidDate": "2014-12-19T20:23:28.847"
        }
    ]
}
Propriedade Descrição Tipo Tamanho Formato
PaymentId Número de identificação do pagamento, necessário para futuras operações como Consulta, Captura e Cancelamento. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Consulta de Recorrência

A Consulta de Recorrência traz dados sobre o agendamento e sobre o processo de transações que se repetem. A Consulta de Recorrência não retorna dados sobre as transações em si.

Para obter informações sobre cada transação, faça a Consulta por PaymentId.

Requisição

curl
--request GET "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API Cielo eCommerce. Guid 36 Sim
MerchantKey Chave Publica para Autenticação Dupla na API Cielo eCommerce. Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
RecurrentPaymentId Campo Identificador da Recorrência. Texto 36 Sim

Resposta

{
    "Customer": {
        "Name": "Fulano da Silva"
    },
    "RecurrentPayment": {
        "RecurrentPaymentId": "c30f5c78-fca2-459c-9f3c-9c4b41b09048",
        "NextRecurrency": "2017-06-07",
        "StartDate": "2017-04-07",
        "EndDate": "2017-02-27",
        "Interval": "Bimonthly",
        "Amount": 15000,
        "Country": "BRA",
        "CreateDate": "2017-04-07T00:00:00",
        "Currency": "BRL",
        "CurrentRecurrencyTry": 1,
        "Provider": "Simulado",
        "RecurrencyDay": 7,
        "SuccessfulRecurrences": 0,
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/c30f5c78-fca2-459c-9f3c-9c4b41b09048"
            }
        ],
        "RecurrentTransactions": [
            {
                "PaymentId": "f70948a8-f1dd-4b93-a4ad-90428bcbdb84",
                "PaymentNumber": 0,
                "TryNumber": 1
            }
        ],
        "Status": 1
    }
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "Customer": {
        "Name": "Fulano da Silva"
    },
    "RecurrentPayment": {
        "RecurrentPaymentId": "c30f5c78-fca2-459c-9f3c-9c4b41b09048",
        "NextRecurrency": "2017-06-07",
        "StartDate": "2017-04-07",
        "EndDate": "2017-02-27",
        "Interval": "Bimonthly",
        "Amount": 15000,
        "Country": "BRA",
        "CreateDate": "2017-04-07T00:00:00",
        "Currency": "BRL",
        "CurrentRecurrencyTry": 1,
        "Provider": "Simulado",
        "RecurrencyDay": 7,
        "SuccessfulRecurrences": 0,
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/c30f5c78-fca2-459c-9f3c-9c4b41b09048"
            }
        ],
        "RecurrentTransactions": [
            {
                "PaymentId": "f70948a8-f1dd-4b93-a4ad-90428bcbdb84",
                "PaymentNumber": 0,
                "TryNumber": 1
            }
        ],
        "Status": 1
    }
}
Propriedade Descrição Tipo Tamanho Formato
RecurrentPaymentId Campo Identificador da próxima recorrência. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
NextRecurrency Data da próxima recorrência. Texto 7 12/2030 (MM/YYYY)
StartDate Data do inicio da recorrência. Texto 7 12/2030 (MM/YYYY)
EndDate Data do fim da recorrência. Texto 7 12/2030 (MM/YYYY)
Interval Intervalo entre as recorrência. Texto 10 / Monthly / Bimonthly / Quarterly / SemiAnnual / Annual
CurrentRecurrencyTry Indica o número de tentativa da recorrência atual Número 1 1
OrderNumber Identificado do Pedido na loja Texto 50 2017051101
Status Status do pedido recorrente Número 1
1 - Ativo
2 - Finalizado
3- Desativada pelo Lojista
4 - Desativada por numero de retentativas
5 - Desativada por cartão de crédito vencido
RecurrencyDay O dia da recorrência Número 2 22
SuccessfulRecurrences Quantidade de recorrência realizada com sucesso Número 2 5
RecurrentTransactions.PaymentId Número de identificação do pagamento (que faz parte da recorrência). Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
RecurrentTransactions.TransactionId Payment ID da transação gerada na recorrência Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
RecurrentTransactions.PaymentNumber Número da Recorrência. A primeira é zero Número 2 3
RecurrentTransactions.TryNumber Número da tentativa atual na recorrência específica Número 2 1

Captura

A captura é procedimento exclusivo para transações de cartões de crédito. Há dois tipos de captura:

Ao realizar uma captura, o lojista confirma que o valor autorizado no cartão poderá ser cobrado pela instituição financeira emissora do cartão.

Importante:

Captura parcial ou total

É possível capturar um valor parcial ou o valor total da transação.

A captura parcial é o ato de capturar um valor menor que o valor autorizado. Esse modelo de captura pode ocorrer apenas uma vez por transação.

Após a captura, não é possível realizar capturas adicionais no mesmo pedido.

Requisição



https://api.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture

curl
--request PUT "https://api.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API Cielo eCommerce. Guid 36 Sim
MerchantKey Chave pública para Autenticação Dupla na API Cielo E-commerce. Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
PaymentId Número de identificação do pagamento, necessário para futuras operações como Consulta, Captura e Cancelamento. Guid 36 Sim
Amount Valor a ser capturado, em centavos. Se essa campo não for preenchido, o valor da captura será o valor total da autorização. Número 15 Não
ServiceTaxAmount Exclusivo para empresas aéreas. Montante do valor da autorização que deve ser destinado à taxa de serviço. Obs.: Esse valor não é adicionado ao valor da autorização. Número 15 Não

Resposta

{
    "Status": 2,
    "Tid": "0719094510712",
    "ProofOfSale": "4510712",
    "AuthorizationCode": "693066",
    "ReturnCode": "6",
    "ReturnMessage": "Operation Successful",
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "Href": "https://api.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
        },
        {
            "Method": "PUT",
            "Rel": "void",
            "Href": "https://api.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
        }
    ]
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "Status": 2,
    "Tid": "0719094510712",
    "ProofOfSale": "4510712",
    "ReturnCode": "6",
    "ReturnMessage": "Operation Successful",
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "Href": "https://api.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
        },
        {
            "Method": "PUT",
            "Rel": "void",
            "Href": "https://api.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
        }
    ]
}
Propriedade Descrição Tipo Tamanho Formato
Status Status da Transação. Byte 2
ProofOfSale Número da autorização, identico ao NSU. Texto 6 Texto alfanumérico
Tid Id da transação na adquirente. Texto 20 Texto alfanumérico
AuthorizationCode Código de autorização. Texto 6 Texto alfanumérico
ReturnCode Código de retorno da adquirente. Texto 32 Texto alfanumérico
ReturnMessage Mensagem de retorno da adquirente. Texto 512 Texto alfanumérico

Cancelamento

O cancelamento é uma funcionalidade que permite ao lojista estornar um pedido de compra. O cancelamento pode ocorrer por insuficiência de estoque ou por desistência da compra pelo consumidor, entre outros motivos.

Na API Cielo E-commerce é possível realizar a requisição de cancelamento para cartões de débito e crédito.

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 sejam realizadas a consulta de saldo, reserva do valor na agenda financeira e sensibilização do saldo, evitando assim duplicidade de cancelamento. Esta regra vale para cancelamentos totais e/ou parciais. Para identificar que as solicitações de cancelamento são da mesma transação, consideramos o número do EC, número da autorização de cancelamento, data da venda, valor da venda e NSU.

É importante salientar que, para realizar qualquer solicitação de cancelamento, é necessário que o estabelecimento possua saldo suficiente na transação e na agenda.

Cancelamento total

É possível cancelar uma venda via PaymentID ou MerchantOrderId (numero do pedido).

Requisição

Cancelamento via PaymentId

ou

Cancelamento via MerchantOrderId

O exemplo a seguir exibe a requisição de cancelamento via PaymentId.

curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API Cielo E-commerce. Guid 36 Sim
MerchantKey Chave pública para Autenticação Dupla na API Cielo E-commerce. Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
PaymentId Número de identificação do pagamento, necessário para operações como Consulta, Captura e Cancelamento. Guid 36 Sim
Amount Valor do Pedido (ser enviado em centavos). Número 15 Não

Resposta

{
    "Status": 10,
    "Tid": "0719094510712",
    "ProofOfSale": "4510712",
    "AuthorizationCode": "693066",
    "ReturnCode": "9",
    "ReturnMessage": "Operation Successful",
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
        }
    ]
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "Status": 10,
    "Tid": "0719094510712",
    "ProofOfSale": "4510712",
    "AuthorizationCode": "693066",
    "ReturnCode": "9",
    "ReturnMessage": "Operation Successful",
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
        }
    ]
}
Propriedade Descrição Tipo Tamanho Formato
Status Status da Transação. Byte 2
ProofOfSale Número da autorização, identico ao NSU. Texto 6 Texto alfanumérico
Tid Id da transação na adquirente. Texto 20 Texto alfanumérico
AuthorizationCode Código de autorização. Texto 6 Texto alfanumérico
ReturnCode Código de retorno da adquirente. Texto 32 Texto alfanumérico
ReturnMessage Mensagem de retorno da adquirente. Texto 512 Texto alfanumérico

Cancelamento parcial

O cancelamento parcial é o ato de cancelar um valor menor do que o valor total que foi autorizado e capturado. Esse modelo de cancelamento pode ocorrer inúmeras vezes, até que o valor total da transação seja cancelado.

O cancelamento parcial está disponível apenas para transações capturadas.

Requisição

curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void?amount=XXX"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
MerchantId Identificador da loja na API Cielo E-commerce. Guid 36 Sim
MerchantKey Chave pública para Autenticação Dupla na API Cielo E-commerce. Texto 40 Sim
RequestId Identificador do Request, utilizado quando o lojista usa diferentes servidores para cada GET/POST/PUT Guid 36 Não
PaymentId Número de identificação do pagamento, necessário para operações como Consulta, Captura e Cancelamento. Guid 36 Sim
Amount Valor do Pedido (ser enviado em centavos). Número 15 Não

Resposta

{
    "Status": 2,
    "Tid": "0719094510712",
    "ProofOfSale": "4510712",
    "AuthorizationCode": "693066",
    "ReasonCode": 0,
    "ReasonMessage": "Successful",
    "ProviderReturnCode": "0",
    "ProviderReturnMessage": "Operation Successful",
    "ReturnCode": "0",
    "ReturnMessage": "Operation Successful",
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/4d7be764-0e81-4446-b31e-7eb56bf2c9a8"
        },
        {
            "Method": "PUT",
            "Rel": "void",
            "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/4d7be764-0e81-4446-b31e-7eb56bf2c9a8/void"
        }
    ]
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "Status": 2,
    "Tid": "0719094510712",
    "ProofOfSale": "4510712",
    "AuthorizationCode": "693066",
    "ReasonCode": 0,
    "ReasonMessage": "Successful",
    "ProviderReturnCode": "0",
    "ProviderReturnMessage": "Operation Successful",
    "ReturnCode": "0",
    "ReturnMessage": "Operation Successful",
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/4d7be764-0e81-4446-b31e-7eb56bf2c9a8"
        },
        {
            "Method": "PUT",
            "Rel": "void",
            "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/4d7be764-0e81-4446-b31e-7eb56bf2c9a8/void"
        }
    ]
}
Propriedade Descrição Tipo Tamanho Formato
Status Status da Transação. Byte 2
ProofOfSale Número da autorização, identico ao NSU. Texto 6 Texto alfanumérico
Tid Id da transação na adquirente. Texto 20 Texto alfanumérico
AuthorizationCode Código de autorização. Texto 6 Texto alfanumérico
ReturnCode Código de retorno da adquirente. Texto 32 Texto alfanumérico
ReturnMessage Mensagem de retorno da adquirente. Texto 512 Texto alfanumérico
ProviderReturnCode Código de retorno do Provider. Texto 32 Texto alfanumérico
ProviderReturnMessage Mensagem de retorno do Provider. Texto 512 Texto alfanumérico
https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{paymentId}/void?amount={Valor}&serviceTaxAmount=xxx

Códigos de Retorno de Cancelamento

RETURN CODE DESCRIÇÃO
6 Solicitação de cancelamento parcial aprovada com sucesso.
9 Solicitação de cancelamento total aprovada com sucesso.
72 Erro: Saldo do lojista insuficiente para cancelamento de venda.
77 Erro: Venda original não encontrada para cancelamento.
100 Erro: Forma de pagamento e/ou Bandeira não permitem cancelamento.
101 Erro: Valor de cancelamento solicitado acima do prazo permitido para cancelar.
102 Erro: Cancelamento solicitado acima do valor da transação original.
103 Restrição Cadastral. Cancelamento não permitido. Entre em contato com a Central de Cancelamento.
104 Restrição Cadastral. Cancelamento não permitido. Entre em contato com a Central de Cancelamento.
105 Restrição Cadastral. Cancelamento não permitido. Entre em contato com a Central de Cancelamento.
106 Restrição Cadastral. Cancelamento não permitido. Entre em contato com a Central de Cancelamento.
107 Restrição Cadastral. Cancelamento não permitido. Entre em contato com a Central de Cancelamento.
108 Erro: Número do Estabelecimento (EC) não encontrado. Por favor, verifique o número enviado.
475 Falha no processamento. Por favor, tente novamente.

Cancelamento via site Cielo

É possivel realizar tanto o cancelamento total quanto o cancelamento parcial via site Cielo.

Post de Notificação

O Post de Notificação é um webhook que envia notificações sobre mudanças no status da transação ou sobre criação de pedido recorrente.

Durante seu cadastro na Cielo, você deve configurar um endpoint para que a Cielo envie as notificações e pode também configurar os eventos para os quais deseja receber notificações.

Eventos Notificados

Os eventos passíveis de notificação por meio de pagamento são:

Meio de Pagamento Eventos que podem ser notificados
Cartão de Crédito Captura;
Cancelamento;
Sondagem.
Cartão de débito Captura;
Sondagem.
Boleto Conciliação;
Cancelamento manual
Transferência eletrônica Confirmadas

A notificação ocorre também ocorre em eventos relacionados a Recorrência Programada Cielo

Eventos da Recorrência
Desabilitado ao atingir número máximo de tentativas (transações negadas)
Reabilitação
Finalizado / Data de finalização atingida
Desativação
Criação da transação de recorrência do pedido recorrente.

Os eventos só são notificados quando se você solicitar o recebimento desse tipo de notificação ao Suporte Cielo.

Endpoint de Notificação

Você deve informar um endpoint (URL Status Pagamento) ao Suporte Cielo, para que o Post de Notificação seja executado.

Características da URL Status Pagamento

Características do Post de notificação

Para aumentar a segurança, é possível cadastrar uma informação para retorno do header para o seu endpoint. Com isso, seu endpoint só vai aceitar a notificação se a Cielo enviar o header.

Para configurar as informações do header, informe ao Suporte Cielo os itens a seguir:

Você pode cadastrar até 3 tipos de informação de retorno no header.

A loja deverá retornar como resposta à notificação: HTTP Status Code 200 OK.

O conteúdo da notificação será formado por três campos:

Com os dados acima, você poderá identificar a transação via PaymentId ou RecurrentPaymentId e a mudança ocorrida. A partir da notificação, você pode consultar mais detalhes sobre a transação na Consulta por PaymentId ou na Consulta de Recorrência.

Veja o exemplo do conteúdo do Post de Notificação:

{
   "RecurrentPaymentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "PaymentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "ChangeType": "2"
}
curl
--header "key: value"
{
   "RecurrentPaymentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "PaymentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "ChangeType": "2"
}
Propriedade Descrição Tipo Tamanho Obrigatório
RecurrentPaymentId Identificador que representa o pedido Recorrente (aplicável somente para ChangeType 2 ou 4). GUID 36 Não
PaymentId Número de identificação do pagamento. GUID 36 Sim
ChangeType Especifica o tipo de notificação. Veja a tabela de Changetype. Número 1 Sim

Tabela de ChangeType

ChangeType Descrição
1 Mudança de status do pagamento
2 Recorrência criada
3 Mudança de status do Antifraude. Exclusivo para clientes integrados ao Antifraude.
4 Mudança de status do pagamento recorrente (Ex. desativação automática)
5 cancelamento negado
7 Notificação de chargeback. Exclusivo para clientes integrados à Risk Notification API.
8 Alerta de fraude

Consulta BIN

A Consulta BIN é um serviço de pesquisa de dados do cartão, seja ele de crédito ou débito, que identifica características do cartão com base nos primeiros dígitos e retorna informações que permitem validar os dados preenchidos na tela de pagamento.

A Consulta BIN retorna os seguintes dados sobre o cartão:

Casos de Uso

Com base no resultado da Consulta BIN você pode desenvolver funcionalidades no seu checkout para melhorar a usabilidade para quem está comprando e, assim, ajudar na recuperação de carrinhos e na melhor conversão da sua loja.

1. Evitar erros referentes à bandeira ou ao tipo de cartão:

2. Oferecer recuperação de carrinhos online

Você pode desenvolver um fluxo no seu checkout para que, caso um cartão informado na tela de pagamento seja múltiplo (crédito e débito), a sua loja pode reter os dados do cartão e, caso a transação de crédito falhe, oferecer automaticamente ao consumidor uma transação de débito com o mesmo cartão.

3. Alertar sobre cartões internacionais ou pré-pagos

A Consulta BIN no carrinho pode indicar a tentativa de uso de um cartão internacional ou pré-pago. Se a sua loja não deseja receber pagamentos internacionais ou de cartões pré-pagos, você pode configurar o seu checkout para informar ao consumidor que a loja não aceita o cartão informado.

Integração

Requisição

Basta realizar um GET enviando o BIN à nossa URL de consulta:

Campo Descrição
BIN São os seis ou nove primeiros dígitos do cartão.
https://apiquerysandbox.cieloecommerce.cielo.com.br/1/cardBin/420020

Resposta

{
    "Status": "00",
    "Provider": "MASTERCARD",
    "CardType": "Crédito",
    "ForeignCard": true,
    "CorporateCard": true,
    "Issuer": "Bradesco",
    "IssuerCode": "237"
    "Prepaid":true
}
Paramêtro Tipo Tamanho Descrição
Status Texto 2 Status da requisição de análise de Bins:
00 – Análise autorizada
01 – Bandeira não suportada
02 – Cartão não suportado na consulta de bin
73 – Afiliação bloqueada
Provider Texto 255 Bandeira do cartão.
CardType Texto 20 Tipo do cartão em uso :
Crédito
Débito
Multiplo
ForeingCard Booleano - Se o cartão é emitido no exterior (False/True).
CorporateCard Booleano - Se o cartão é corporativo (False/True).
Issuer Texto 255 Nome do emissor do cartão.
IssuerCode Texto 255 Código do emissor do cartão.
Prepaid Boolean True ou False Retornará “True” caso o cartão seja do tipo pré pago.

Atenção: Em sandbox os valores retornados são simulações e não validações reais de BINS. Considere apenas o retorno da requisição e o seu formato. Para identificação real dos bins, use o ambiente de produção.

Zero Auth

O Zero Auth é uma ferramenta da Cielo que permite verificar se um cartão está válido para realizar uma compra antes que o pedido seja finalizado. O Zero Auth simula uma autorização sem afetar o limite de crédito ou alertar o portador do cartão sobre o teste.

O Zero Auth não informa o limite ou características do cartão ou do portador, apenas simula uma autorização Cielo.

O Zero Auth é a forma correta de validar cartões de acordo com as recomendações das bandeiras e bancos. Antes da criação do Zero Auth, as lojas costumavam criar transações de valores baixos, como um real ou um dólar, e fazer o cancelamento em seguida; é importante saber que essa prática hoje é penalizada pelas bandeiras.

Atenção: Na ocorrência de transações com valor diferente de zero e inferior a um dólar, seguidas do cancelamento da transação, as bandeiras aplicarão tarifas à Cielo, que serão repassadas aos estabelecimentos que estiverem em inconformidade. A bandeira Mastercard por exemplo, está cobrando uma tarifa no valor de R$ 0,21 centavos por transação.

O ZeroAuth faz a validação de cartões abertos ou tokenizados (envio do CardToken criado na API Cielo E-commerce).

Bandeiras suportadas

O Zero Auth suporta as bandeiras Visa, Master e Elo tanto para cartões de crédito quanto de débito.

Caso outras bandeiras sejam enviadas, haverá um erro com o retorno “57-Bandeira inválida”.

Integração

Para realizar a consulta ao Zero Auth, o lojista deverá enviar uma requisição POST para a API Cielo Ecommerce, simulando uma transação.

Requisição

A validação de um cartão aberto necessita de um contrato técnico diferente da validação de um cartão tokenizado. Confira os exemplos de requisição a seguir:

Cartão aberto

{
    "CardNumber":"1234123412341231",
    "Holder":"Alexsander Rosa",
    "ExpirationDate":"12/2021",
    "SecurityCode":"123",
    "SaveCard":"false",
    "Brand":"Visa",
    "CardOnFile":{
       "Usage":"First",
       "Reason":"Recurring"
    }
}

A seguir, a listagem de campos da Requisição:

Paramêtro Descrição Tipo Tamanho Obrigatório
CardType Creditcard ou DebitCard Texto 255 Sim
CardNumber Número do Cartão do Comprador Texto 16 Sim
Holder Nome do Comprador impresso no cartão. Texto 25 Sim
ExpirationDate Data de e validade impresso no cartão. Texto 7 Sim
SecurityCode Código de segurança impresso no verso do cartão. Texto 4 Sim
SaveCard Booleano que identifica se o cartão será salvo para gerar o CardToken. Boolean Sim
Brand Bandeira do cartão:
Visa
Master
Elo
Texto 10 Sim
CardToken Token do cartão na 3.0 GUID 36 Condicional
Usage First se o cartão foi armazenado e é seu primeiro uso.
Used se o cartão foi armazenado e ele já foi utilizado anteriormente em outra transação.
Texto Não
Reason Indica o propósito de armazenamento de cartões, caso o campo “Usage” for “Used”.
Recurring - Compra recorrente programada (ex. assinaturas)
Unscheduled - Compra recorrente sem agendamento (ex. aplicativos de serviços)
Installments - Parcelamento através da recorrência
Veja Mais.
Texto Condicional

Cartão tokenizado

{
  "CardToken":"23712c39-bb08-4030-86b3-490a223a8cc9",
  "SaveCard":"false",
  "Brand":"Visa"
}

A seguir, a listagem de campos da Requisição:

Paramêtro Descrição Tipo Tamanho Obrigatório
Brand Bandeira do cartão:
Visa
Master
Texto 10 não
CardToken Token do cartão na 3.0 GUID 36 Condicional

Resposta

A resposta sempre retorna se o cartão pode ser autorizado no momento. Essa informação apenas significa que o cartão está válido para transacionar, mas não indica que um determinado valor será autorizado.

Os campos retornados na resposta dependem do resultado da validação. A tabela a seguir apresenta todos os campos possíveis; depois da tabela, confira os exemplos de cada tipo de resposta.

Paramêtro Descrição Tipo Tamanho
Valid Situação do cartão:
True – Cartão válido
False – Cartão Inválido
Boolean
ReturnCode Código de retorno Texto 2
ReturnMessage Mensagem de retorno Texto 255
IssuerTransactionId Identificador de autenticação do emissor para transações de débito recorrentes. Este campo deve ser enviado nas transações subsequentes da primeira transação no modelo de recorrência própria. Já no modelo de recorrência programada, a Cielo será a responsável por enviar o campo nas transações subsequentes. Texto 15

POSITIVA - Cartão válido

{
  "Valid": true,
  "ReturnCode": "00",
  "ReturnMessage": "Transacao autorizada",
  "IssuerTransactionId": "580027442382078"
}

Consulte para visualizar a descrição dos códigos de retorno. O código de retorno 00 representa sucesso no Zero Auth, os demais códigos são definidos de acordo com a documentação acima.

NEGATIVA - Cartão inválido

{
       "Valid": false,
       "ReturnCode": "57",
       "ReturnMessage": "Autorizacao negada",
       "IssuerTransactionId": "580027442382078"
}

NEGATIVA - Bandeira inválida

  {    
      "Code": 57,     
      "Message": "Bandeira inválida"   
  }

NEGATIVA - Restrição cadastral

  {    
      "Code": 389,     
      "Message": "Restrição Cadastral"   
  }

Caso ocorra algum erro no fluxo e não seja possível validar o cartão, o serviço irá retornar os erros:

Silent Order Post

Com o Silent Order Post, os dados de pagamentos são trafegados de forma segura, mantendo o controle total sobre a experiência de checkout.

Esse método possibilita o envio dos dados do pagamento do comprador de forma segura diretamente em nosso sistema. Os campos de pagamento são armazenados pela Cielo, que conta com a certificação PCI DSS 3.2.

É ideal para lojistas que exigem um alto nível de segurança, sem perder a identidade de sua página.

Características

O PCI Data Security Standard (PCI DSS) é um padrão global de segurança de dados de cartões, e compreende um conjunto mínimo de requisitos para proteger os dados do titular do cartão.

Fluxo de Autorização

A seguir, apresentamos como funciona um fluxo de autorização padrão e um fluxo de autorização com o Silent Order Post.

Fluxo de Autorização Padrão

No fluxo de autorização padrão, a loja virtual recebe os dados de pagamento do comprador e, por isso, precisa estar em conformidade com o PCI DSS.

Fluxo Padrão

Fluxo de Autorização com Silent Order POST

Com o Silent Order Post, o servidor da loja virtual não trafega os dados do cartão abertamente.

Fluxo Padrão

  1. A loja configura o JavaScript na tela de checkout. Na finalização da compra, o script envia os dados de pagamento diretamente para a API E-Commerce Cielo, sem passar pelo seu servidor;
  2. A API armazena os dados do cartão para aquela compra e cria um código criptografado (PaymentToken, válido apenas para uma compra) ou armazena os dados do cartão e cria um código criptografado para o cartão (CardToken, que pode ser usado em outras compras);
  3. A loja envia o token do script para o próprio servidor;
  4. A loja, por meio do seu servidor, envia a requisição de autorização com o token e os demais campos obrigatórios para uma transação.

Integração

Passo 1. Obtendo dos tokens de acesso

Para que possa usar o Silent Order Post, você vai precisar de dois tokens:

Token de autenticação OAuth2

Obtenha o access_token a partir da API de autenticação da Cielo (OAuth2). Em caso de sucesso, a API retornará um access_token que deverá ser utilizado na próxima camada de autenticação da ferramenta.

Para obter o access_token no padrão OAuth 2.0, envie uma requisição utilizando o VERBO HTTP POST para a URL da tabela a seguir, formada pela “URL base do ambiente + endpoint”, conforme o ambiente desejado:

Ambiente URL base + endpoint Authorization
SANDBOX https://authsandbox.braspag.com.br/oauth2/token “Basic {base64}
PRODUÇÃO https://auth.braspag.com.br/oauth2/token “Basic {base64}

Nota: O valor “{base64}” para a autorização do tipo “Basic” deve ser obtido da seguinte forma:

  1. Concatene o “ClientId” e o “ClientSecret” (ClientId:ClientSecret);
  2. Codifique o resultado da concatenação em base64;
  3. Realize uma requisição ao servidor de autorização utilizando o código alfanumérico gerado.

Para obter o “ClientID” e o “ClientSecret”, envie um e-mail para cieloecommerce@cielo.com.br contendo o MerchantId e informando que deseja obter as credenciais “ClientID” e “ClientSecret” para o Silent Order Post.

Requisição

--request POST "https://authsandbox.braspag.com.br/oauth2/token"
--header "Authorization: Basic {base64}"
--header "Content-Type: application/x-www-form-urlencoded" 
--data-binary "grant_type=client_credentials"
Parâmetros Formato Envio
Authorization “Basic {base64} Envio no header.
Content-Type “application/x-www-form-urlencoded” Envio no header.
grant_type “client_credentials” Envio no body.

Resposta

{
  "access_token": "faSYkjfiod8ddJxFTU3vti_ ... _xD0i0jqcw",
  "token_type": "bearer",
  "expires_in": 599
}
{
  "access_token": "faSYkjfiod8ddJxFTU3vti_ ... _xD0i0jqcw",
  "token_type": "bearer",
  "expires_in": 599
}
Propriedades da Resposta Descrição
access_token O token de autenticação solicitado. Ele será utilizado no próximo passo.
token_type Indica o valor do tipo de token.
expires_in Expiração do token de acesso, em segundos. Quando o token expira, é necessário obter um novo.

Token de autenticação do Silent Order Post

Após a obtenção do token de autenticação OAuth2, envie uma requisição utilizando o VERBO HTTP POST para a URL da tabela a seguir conforme o ambiente desejado:

Ambiente URL base + endpoint
Sandbox https://transactionsandbox.pagador.com.br/post/api/public/v2/accesstoken
Produção https://transaction.pagador.com.br/post/api/public/v2/accesstoken

Requisição

--request POST "https://transactionsandbox.pagador.com.br/post/api/public/v2/accesstoken"
--header "Content-Type: application/json"
--header "MerchantId: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
--header "Authorization: Bearer faSYkjfiod8ddJxFTU3vti_ ... _xD0i0jqcw"
--data-binary
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório?
MerchantId Identificador da loja na API Cielo E-commerce. GUID 36 Sim
Authorization Bearer [AccessToken OAuth2] Texto 36 Sim

Resposta

Como resposta, a loja receberá um json (“HTTP 201 Created”) contendo, entre outras informações, o AccessToken do Silent Order Post.

{
    "MerchantId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "AccessToken": "MzA5YWIxNmQtYWIzZi00YmM2LWEwN2QtYTg2OTZjZjQxN2NkMDIzODk5MjI3Mg==",
    "Issued": "2021-05-05T08:50:04",
    "ExpiresIn": "2021-05-05T09:10:04"
}
--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "AccessToken": "MzA5YWIxNmQtYWIzZi00YmM2LWEwN2QtYTg2OTZjZjQxN2NkMDIzODk5MjI3Mg==",
    "Issued": "2021-05-05T08:50:04",
    "ExpiresIn": "2021-05-05T09:10:04"
}
Propriedade Descrição Tipo Tamanho Formato
MerchantId Identificador da loja na API Cielo E-commerce. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AccessToken Token de acesso (AccessToken do Silent Order Post). O AccessToken obtido permitirá a realização de uma tentativa de autorização no período de 20 minutos. Texto NjBhMjY1ODktNDk3YS00NGJkLWI5YTQtYmNmNTYxYzhlNjdiLTQwMzgxMjAzMQ==
Issued Data e hora da geração. Texto AAAA-MM-DDTHH:MM:SS
ExpiresIn Data e hora da expiração. Texto AAAA-MM-DDTHH:MM:SS

Passo 2. Implementando o script

Faça o download do script fornecido pela Cielo, e anexe o script à sua página de checkout. Esse script permitirá à Cielo processar todas as informações de cartão sem intervenção do estabelecimento.

Faça o download do script correspondente ao ambiente desejado, sandbox ou produção:

AMBIENTE URL do script
SANDBOX https://transactionsandbox.pagador.com.br/post/scripts/silentorderpost-1.0.min.js
PRODUÇÃO https://transaction.cieloecommerce.cielo.com.br/post/scripts/silentorderpost-1.0.min.js

Em seguida, faça a configuração do formulário com as seguintes classes:

Além disso, defina os parâmetros a seguir:

Parâmetros do Script

Propriedade Descrição
accessToken Token de acesso obtido via API de autenticação da Braspag (AccessToken SOP).
environment Tipo de ambiente: “sandbox” / “production”.
language Idioma: “pt” / “en” / “es”.
enableTokenize “true” (salva o cartão diretamente no Cartão Protegido, retornando um cardToken ao invés de um paymentToken) / “false” (caso contrário).
cvvRequired “false” (desliga a obrigatoriedade de envio do CVV) / “true” (caso contrário).

Exemplo de setup a ser realizado pela loja virtual na página de checkout:

Pagina Checkout

Retornos do Script

O script fornecido pela Cielo fornece três eventos para manipulação e tratamento por parte do estabelecimento. São eles:

Na validação dos inputs, o estabelecimento poderá utilizar toda a camada de validação sobre os dados de cartão realizada pela Cielo e assim simplificar o tratamento no seu formulário de checkout. As mensagens retornadas no resultado da validação são disponibilizadas nos idiomas português (padrão), inglês e espanhol.

Propriedade Descrição Condição
PaymentToken Token efêmero utilizado para pagamento no formato de um GUID (36).
CardToken Token permanente utilizado para pagamento no formato de um GUID (36). Quando enableTokenize for “true”.
  • O PaymentToken ou o CardToken representarão todos os dados de cartão fornecido pelo comprador. O token será usado pelo estabelecimento para que não precise tratar e processar dados de cartão em seu servidor.
  • Por questões de segurança o PaymentToken poderá ser usado apenas para uma autorização na API E-commerce Cielo. Após o processamento do token, ele será invalidado.

Passo 3. Requisição de autorização com o token

Requisição com PaymentToken

Envie a requisição de autorização com o PaymentToken no nó CreditCard (para transação com cartão de crédito) ou no nó DebitCard (para transação cmo cartão de débito).

},
    "Payment": {
    "Type": "CreditCard",
    "Amount": 1400,
    "Installments": 1,
    "CreditCard": {
        "PaymentToken": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "Brand": "Master"
        }
    }
}

Para consultar os campos obrigatórios da requisição e a resposta, veja as requisições padrão das transações de crédito ou débito.

Por questões de segurança o PaymentToken poderá ser usado apenas para uma autorização na API E-commerce Cielo. O token será processado e, em seguida, invalidado.

Requisição com CardToken

Envie a requisição de autorização com o CardToken no nó CreditCard (para transação com cartão de crédito) ou no nó DebitCard (para transação cmo cartão de débito).

{  
   "MerchantOrderId":"2014111706",
   "Customer":{  
      "Name":"Comprador Teste"
   },
   "Payment":{  
     "Type":"CreditCard",
     "Amount":100,
     "Installments":1,
     "SoftDescriptor":"123456789ABCD",
     "CreditCard":{  
         "CardToken":"6e1bf77a-b28b-4660-b14f-455e2a1c95e9",
         "SecurityCode":"262",
         "Brand":"Visa"
     }
   }
}

Para consultar os campos obrigatórios da requisição e a resposta, veja as requisições padrão das transações de crédito ou débito.

Autenticação legada do SOP

Não recomendamos essa forma de autenticação, pois será descontinuada.

PASSO 1

a) A loja deverá solicitar um ticket (server to server) enviando um POST para a seguinte URL:

SANDBOX: https://transactionsandbox.pagador.com.br/post/api/public/v1/accesstoken?merchantid={mid_loja}

PRODUÇÃO: https://transaction.cieloecommerce.cielo.com.br/post/api/public/v1/accesstoken?merchantid={mid}

Exemplo: https://transaction.cieloecommerce.cielo.com.br/post/api/public/v1/accesstoken?merchantid=00000000-0000-0000-0000-000000000000

Requisição

curl
--request POST "https://transaction.cieloecommerce.cielo.com.br/post/api/public/v1/accesstoken?merchantid=00000000-0000-0000-0000-000000000000"
--header "Content-Type: application/json"
--data-binary
--verbose
Propriedade Descrição Tipo Tamanho Obrigatório
mid_loja Identificador da loja na API Guid 36 Sim

Resposta

--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "AccessToken": "NjBhMjY1ODktNDk3YS00NGJkLWI5YTQtYmNmNTYxYzhlNjdiLTQwMzgxMjAzMQ==",
    "Issued": "2018-07-23T11:09:32",
    "ExpiresIn": "2018-07-23T11:29:32"
}
Propriedade Descrição Tipo Tamanho Formato
MerchantId Identificador da loja na API Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AccessToken Token de Acesso Texto NjBhMjY1ODktNDk3YS00NGJkLWI5YTQtYmNmNTYxYzhlNjdiLTQwMzgxMjAzMQ==
Issued Data e hora da geração Texto AAAA-MM-DDTHH:MM:SS
ExpiresIn Data e hora da expiração Texto AAAA-MM-DDTHH:MM:SS

b) Para uso este recurso, por questões de segurança, obrigatoriamente a Cielo irá solicitar, no mínimo, um IP válido do estabelecimento. Caso contrário a requisição não será autorizada (HTTP 401 NotAuthorized).

PASSO 2

a) Como resposta, a loja receberá um JSON (HTTP 201 Created) contendo, entre outras, informações o ticket (AccessToken), como por exemplo:

Response Ticket

Por questões de segurança, este ticket dará permissão para a loja salvar apenas um cartão dentro de um prazo de já estipulado na resposta, através do atributo ExpiresIn (por padrão, 20 minutos). O que acontecer primeiro invalidará o ticket para um uso futuro.

Velocity

O Velocity é um tipo de mecanismo de prevenção a tentativas de fraude, que analisa a frequência que determinados dados são utilizados numa transação e se esse dados estão inscritos em uma lista de comportamentos passíveis de ações de segurança.

O Velocity é um aliado na avaliação de comportamentos de compra suspeitos, pois os cálculos são baseados em elementos de rastreabilidade.

Para que suas transações sejam analisadas pelo Velocity, solicite a inclusão desse serviço ao Suporte Cielo.

O Velocity funciona analisando dados enviados na integração padrão da API Cielo E-commerce. Assim, não é necessário incluir nenhum nó adicional na requisição de criação de transação.

Quando o Velocity está ativo, a resposta da transação trará um nó específico chamado Velocity, com os detalhes da análise.

{
  "MerchantOrderId": "2017051202",
  "Customer": {
    "Name": "Nome do Comprador",
    "Identity": "12345678909",
    "IdentityType": "CPF",
    "Email": "comprador@cielo.com.br",
    "Address": {
      "Street": "Alameda Xingu",
      "Number": "512",
      "Complement": "27 andar",
      "ZipCode": "12345987",
      "City": "São Paulo",
      "State": "SP",
      "Country": "BRA"
    },
    "DeliveryAddress": {
      "Street": "Alameda Xingu",
      "Number": "512",
      "Complement": "27 andar",
      "ZipCode": "12345987",
      "City": "São Paulo",
      "State": "SP",
      "Country": "BRA"
    }
  },
  "Payment": {
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": "ByMerchant",
    "Capture": true,
    "Authenticate": false,
    "Recurrent": false,
    "CreditCard": {
      "CardNumber": "455187******0181",
      "Holder": "Nome do Portador",
      "ExpirationDate": "12/2027",
      "SaveCard": false,
      "Brand": "Undefined"
    },
    "VelocityAnalysis": {
      "Id": "2d5e0463-47be-4964-b8ac-622a16a2b6c4",
      "ResultMessage": "Reject",
      "Score": 100,
      "RejectReasons": [
        {
          "RuleId": 49,
          "Message": "Bloqueado pela regra CardNumber. Name: Máximo de 3 Hits de Cartão em 1 dia. HitsQuantity: 3\. HitsTimeRangeInSeconds: 1440\. ExpirationBlockTimeInSeconds: 1440"
        }
      ]
    },
    "PaymentId": "2d5e0463-47be-4964-b8ac-622a16a2b6c4",
    "Type": "CreditCard",
    "Amount": 10000,
    "Currency": "BRL",
    "Country": "BRA",
    "Provider": "Simulado",
    "ReasonCode": 16,
    "ReasonMessage": "AbortedByFraud",
    "Status": 0,
    "ProviderReturnCode": "BP171",
    "ProviderReturnMessage": "Rejected by fraud risk (velocity)",
    "Links": [
      {
        "Method": "GET",
        "Rel": "self",
        "Href": "https://apiquery.cieloecommerce.cielo.com.br/1/sales/2d5e0463-47be-4964-b8ac-622a16a2b6c4"
      }
    ]
  }
}
Propriedade Descrição Tipo Tamanho
VelocityAnalysis.Id Identificador da análise efetuada GUID 36
VelocityAnalysis.ResultMessage Accept ou Reject Texto 25
VelocityAnalysis.Score 100 Número 10
VelocityAnalysis.RejectReasons.RuleId Código da Regra que rejeitou Número 10
VelocityAnalysis.RejectReasons.Message Descrição da Regra que rejeitou Texto 512

Códigos da API

Sobre os códigos

A Api Cielo e-commerce possui 4 tipos de códigos retornados que representam diferentes momentos da transação. Abaixo vamos explica-los na ordem em que podem ocorrer:

Código Descrição
HTTP Status Code São códigos do padrão HTTP. Eles informam se as informações enviadas a API estão de fato obtendo sucesso ao atingir nossos ENDPOINTs. Se valores diferentes de 200 ou 201 estejam aparecendo, há algum empecilho com a comunicação com a API
Retornado no momento da requisição a API
Erros da API Esses códigos são respostas a validação do conteúdo dos dados enviados. Se eles estão sendo exibidos, as chamadas a nossa API foram identificadas e estão sendo validadas. Se esse código for exibido, a requisição contem erros (EX: tamanho/condições/erros de cadastro) que impedem a criação da transação
Retornado no momento da requisição a API
Status Depois de criada a transação, esses códigos serão retornados, informando como se encontra a transação no momento (EX: Autorizada > Capturada > Cancelada)
*Retornado no campo Status *
Retorno das Vendas Formado por um código de Retorno e uma mensagem, esses códigos indicam o motivo de um determinado Status dentro de uma transação. Eles indicam, por exemplo, se uma transação com status negada não foi autorizada devido saldo negativo no banco emissor.
Retornados nos campos ReturnCode e ReturnMessage
Ocorrem somente em Cartões de crédito e Débito

OBS: No antigo Webservice 1.5 Cielo, o ReturnCode era considerado como Status da transação. Na API CIELO ECOMMERCE, o campo Status possui códigos próprios, sendo assim, o campo a ser considerado como base de identificação do status de uma transação

HTTP Status Code

HTTP Status Code Descrição
200 OK (Capture/Void/Get)
201 OK (Authorization)
400 Bad Request
404 Resource Not Found
500 Internal Server Error

Programa de Retentativa das Bandeiras

O que são retentativas?

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

O que mudou?

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

E no e-commerce?

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

Qual o impacto para a loja?

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

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

  • Irreversível: nunca realizar retentativa

    Significa, por exemplo, que o cartão está cancelado para uso, foi perdido ou roubado, há uma fraude confirmada ou a transação não é permitida para aquele produto, indicando que não há circunstâncias nas quais o emissor concederia uma aprovação. Qualquer tentativa de autorização que, após uma recusa irreversível, não tenha alterado nenhum campo da mensageria, não obterá sucesso.

  • Reversível: permitido realizar retentativa

    Significa que o emissor pode aprovar a transação, mas não pode fazê-lo agora, possivelmente devido a um problema do sistema (inoperante) ou falta de limite, suspeita de fraude ou excesso de número de tentativas de digitação da senha. São decisões de recusas temporárias tomadas pelo emissor que podem mudar com o tempo.

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

Mastercard

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

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

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

1. Excessive Attempts

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

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

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

Tabela Excessive Attempts

Categorias Códigos Vigência Tarifa Doméstica Tarifa Internacional Quando Ocorre Permitido Retentar
Cartão presente e cartão não presente Qualquer código de negativa que não está atribuído ao MAC 03 e 21. E também os códigos MAC caso não respeite os limites do “Excessive Attempts” Até 31/01/2023 R$ 2,00 - A partir 11ª retentativa Permitido retentar em 24h.
Cartão presente e cartão não presente Qualquer código de negativa que não está atribuído ao MAC 03 e 21. E também os códigos MAC caso não respeite os limites do “Excessive Attempts” Nova regra a partir de 01/02/2023 R$ 2,00 - A partir 8ª retentativa Permitido retentar em 24h.
  1. O excesso considerado no programa ocorrerá a partir da oitava retentativa dentro do mês de apuração; os valores cobrados sofreram alteração.
  2. E a Mastercard também está introduzindo um limite de 35 tentativas negadas no mesmo cartão e mesmo número de estabelecimento por período contínuo de 30 dias. Mesmo se a loja não ultrapassar o limite de sete retentativas no período de 24h, mas ultrapassar a quantidade do limite mensal, a cobrança será aplicada.

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

2. Merchant Advice Code Transaction Excellence (MAC)

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

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

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

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

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

Tabela com toda relação de MACs

MAC Descrição Observação
01 Informações da nova conta disponíveis (ABU) Necessidade de realizar atualização dos dados da conta que está sendo utilizada na transação, usando o ABU, por exemplo.
02 Não pode aprovar no momento, tente depois Tente novamente a transação após 72 horas ou tente a transação com um método de pagamento diferente.
03 Não é permitido retentar Busque outro meio de garantir o pagamento, evitando custos desnecessários de várias solicitações de autorização que continuarão a resultar em declínios.
04 Requisitos de token não atendidos para este token modelo Há necessidade de revisar os requisitos de token, pois os requisitos não foram atendidos para este token modelo enviado na transação.
21 Plano cancelado Comprador realiza cancelamento de plano e mesmo após o cancelamento, estabelecimento continua enviando solicitação de autorização de compra.
24 Tente novamente após 1 hora Válido somente para o código de resposta 51 (insuficiência de fundos)
25 Tente novamente após 24 horas Válido somente para o código de resposta 51 (insuficiência de fundos)
26 Tente novamente após 2 dias Válido somente para o código de resposta 51 (insuficiência de fundos)
27 Tente novamente após 4 dias Válido somente para o código de resposta 51 (insuficiência de fundos)
28 Tente novamente após 6 dias Válido somente para o código de resposta 51 (insuficiência de fundos)
29 Tente novamente após 8 dias Válido somente para o código de resposta 51 (insuficiência de fundos)
30 Tente novamente após 10 dias Válido somente para o código de resposta 51 (insuficiência de fundos)

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

Categorização de retornos Mastercard

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

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

Por exemplo:

Quando Então E o código de resposta
O emissor recusar a transação usando o código de resposta 54 (Cartão Expirado) A Mastercard substituirá o código 54 para o código 79 (recusa por ciclo de vida) Acompanha o devido Merchant Advice Code (MAC)

Programa de retentativas MAC 03 e MAC 21

Forma de apuração:

Tabela de valores:

Número de retentativa Regra
A partir 1ª rententativa R$ 2,50 (dois reais e cinquenta centavos) por retentativa, a partir da 1ª retentativa.

Visa

O que é?

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

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

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

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

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

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

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

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

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

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

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

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

Tabela com as regras e códigos de recusa:

VISA

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

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

Elo

O que é?

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

Formas de Apuração

Tabela de cobrança de retentativas para a bandeira Elo

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

Mês Cenário Cobrança
1º (agosto) EC Excede limites Advertência
2º (setembro) EC Não excede Limites Não gera cobrança
3º (outubro) EC Excede limites Neste caso será advertido novamente. A cobrança só será feita em caso de recorrência.
4º (novembro) EC Excede limites Aplicação da multa
5º (dezembro) EC Excede limites Aplicação da multa
6º (janeiro) EC Não excede Limites Não gera cobrança
7º (fevereiro) EC Excede limites Será advertido novamente.

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

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

CÓDIGOS DESCRIÇÃO QUANDOO EMISSOR DEVE UTILIZAR O CÓDIGO DE RESPOSTA RETENTATIVA
4 REFAZER A TRANSAÇÃO Esse código deve ser usado pelo Emissor para solicitar que o portador/EC realize novamente a transação caso ele (Emissor) detecte falha na captura das informações da transação ou caso seja necessário atualização da senha negando a 1ª transação Reversível
5 GENÉRICA A Bandeira poderá utilizar esse código para outras tratativas (genérica). Reversível
6 CONSULTAR CREDENCIADOR Esse motivo deve ser utilizado pelo Credenciador quando ele identificar problemas internos que não necessitem de mudanças na mensageria para que a transação siga o fluxo correto. Reversível
12 ERRO NO CARTÃO - Esse código deve ser usado pelo Emissor quando ele identificar falha na validação do CAVV de transações 3DS ou tokenizada.
- Esse código deve ser usado pelo Emissor quando identificar CÓDIGO DE SERVIÇO incorreto/inválido para cartões físicos.
- Esse código deve ser usado pelo Emissor para problemas identificados no TOKEN
- Este código deve ser utilizado para negar reversões e avisos de reversão onde a transação original não é localizada pelo Emissor.
Irreversível
13 VALOR DA TRANSAÇÃO INVÁLIDA - Esse código deve ser usado pelo Emissor quando identificar que o valor da transação é inválido de acordo com os parâmetros do Emissor. Irreversível
14 NÚMERO DO CARTÃO INVÁLIDA - Esse código deve ser utilizado pelo Emissor para Nº DO CARTÃO INVÁLIDO/INCORRETO.
- A Bandeira poderá utilizar esse código para outras tratativas.
Irreversível
19 PROBLEMAS ADQUIRENTE - Esse motivo deve ser utilizado pelo Credenciador quando ele identificar problemas internos que necessitem de mudanças na mensageria para que a transação siga o fluxo correto. Irreversível
23 VALOR DA PARCELA INVÁLIDO - Esse código deve ser utilizado pelo Emissor quando o VALOR DA PARCELA ESTÁ FORA DOS LIMITES estabelecidos por ele. Esse código deve ser utilizado quando o emissor não aceitar o produto Elo Parcelado Loja (produto 072) com o número de parceladas menor que 12. Irreversível
30 ERRO DE FORMATO DA MENSAGEM - Esse código deve ser usado pelo Emissor quando ele identificar ERRO DE FORMATO NA MENSAGERIA (campo obrigatório, domínios, formatos, tamanho não presentes ou divergentes da especificação). Irreversível
38 COMPRA/EXCEDIDAS TENTATIVAS SENHA - Esse código deve ser utilizado pelo Emissor quando for EXCEDIDO O Nº DE TENTATIVAS PERMITIDAS DE DIGITAÇÃO DA SENHA (utilizado apenas para compras). Reversível
41 CARTÃO PERDIDO - Esse código deve ser utilizado pelo Emissor para CARTÃO COM BLOQUEIO DEFINITIVO pelo motivo “PERDA”. Irreversível
43 CARTÃO ROUBADO - Esse código deve ser utilizado pelo Emissor para CARTÃO COM BLOQUEIO DEFINITIVO pelo motivo “ROUBO”. Irreversível
51 LIMITE/SALDO INSUFICIENTE - Esse código deve ser utilizado pelo Emissor para CARTÃO que está TEMPORARIAMENTE SEM SALDO OU LIMITE SUFICIENTE para realizar a transação.
- Saque/advance 2 sem trilha 2
- Compra com Troco não suportada.
- Verificação de endereço não suportada (somente quando o código de processo for “13” sem valor de compra). * Verificação de conta de cartão não suportada (somente quando o código de processo for “18” sem valor de compra).
Reversível
54 DATA DE VALIDADE DO CARTÃO - Esse código deve ser utilizado pelo Emissor para CARTÃO FÍSICO ou TOKEN COM VALIDADE / EXPIRAÇÃO VENCIDA ou INVÁLIDA. Irreversível
55 SENHA INVÁLIDA / NÃO ENVIADA - Esse código deve ser utilizado pelo Emissor quando a SENHA DIGITADA PELO CLIENTE NÃO CONFERE, ESTÁ INVÁLIDA/INCORRETA.
- Esse código deve ser utilizado pelo Emissor quando a SENHA NÃO FOR ENVIADA NA MENSAGERIA E A MESMA É EXIGIDA PARA APROVAÇÃO DA TRANSAÇÃO.
Reversível
56 SEM REGISTRO DO CARTÃO
1. Nº do cartão não pertence ao Emissor
2. Nº do cartão não é válido
Irreversível
57 TRANSAÇÃO NÃO PERMITIDA PARA ESSE CARTÃO - Esse código deve ser utilizado pelo Emissor quando o cartão estiver com BLOQUEIO DEFINITIVO, exceto bloqueio perda e roubo que já possuem códigos específicos (ex: falecimento, fraude confirmada, cancelamento definitivo a pedido do cliente, etc).
- Esse código deve ser utilizado para PRODUTOS E SERVIÇOS NÃO SUPORTADOS pelo emissor do cartão.
- Esse código pode ser usado para TOKEN INVÁLIDO / SUSPENSO / INATIVO.
- Esse código deve ser usado para negar o modo de entrada FALLBACK.
Irreversível
58 COMERCIANTE INVÁLIDO - Esse código deve ser utilizado pelo Emissor quando o MCC do estabelecimento não estiver cadastrado para obtenção de token junto ao Emissor. Irreversível
59 SUSPEITA DE FRAUDE - Esse código deve ser utilizado pelo Emissor quando regras de prevenção SUSPEITAM DE FRAUDE, sendo necessário o contato do portador com o Emissor para liberação do cartão e realização de nova transação.
- Esse código deve ser utilizado pelo Emissor para negar transações por ausência do AVISO VIAGEM que deve ser realizado pelo portador do cartão antes de viagens ao exterior ou em alguns casos antes de realizar transações em sites internacionais.
Reversível
61 VALOR MÁXIMO SAQUE/COMPRAS EXCEDIDO - Esse código deve ser utilizado pelo Emissor quando o valor do saque/compras exceder o limite permitido por ele. Reversível
62 BLOQUEIO TEMPORÁRIO DE COBRANÇA - Esse código deve ser utilizado pelo Emissor para cartões com BLOQUEIO TEMPORÁRIO DE COBRANÇA. Reversível
63 VIOLAÇÃO DE SEGURANÇA - Esse código deve ser utilizado pelo Emissor quando o CÓDIGO DE SEGURANÇA DO CARTÃO (CVE2) estiver INCORRETO / INVÁLIDO ou MST inválido (token). Irreversível
64 VALOR MÍNIMO DA TRANSAÇÃO - INVÁLIDO - Esse código deve ser utilizado pelo Emissor quando o VALOR DA TRANSAÇÃO ESTIVER ABAIXO DO MÍNIMO permitido pelo Emissor Irreversível
65 QUANTIDADE DE SAQUES EXCEDIDOS - Esse código deve ser utilizado pelo Emissor quando o limite de quantidade de saques estiver excedido Reversível
75 SAQUE/ EXCEDIDAS TENTATIVAS SENHA - Esse código deve ser utilizado pelo Emissor quando for excedida a quantidade de tentativas de digitação de senha estipuladas pelo Emissor (utilizado apenas para SAQUES) Reversível
76 CONTA DESTINO INVÁLIDA OU INEXISTENTE - Esse código deve ser utilizado pelo Emissor quando conta “PARA” (destino) no BIT 3 é inválida ou inexistente e exclusivamente para transações de Transferência de Fundos Irreversível
77 CONTA ORIGEM INVÁLIDA OU INEXISTENTE - Esse código deve ser utilizado pelo Emissor quando conta “DE” (origem) no BIT 3 é inválida ou inexistente e exclusivamente para transações de Transferência de Fundos. Irreversível
78 CARTÃO NOVO SEM DESBLOQUEIO / CARTÃO BLOQUEADO - Esse código deve ser utilizado pelo Emissor quando o cartão novo ainda não foi desbloqueado (ativado) pelo portador junto ao Emissor ou quando o Portador, mediante autonomia, desejar bloquear temporariamente o cartão através do aplicativo do Emissor. Reversível
82 CARTÃO INVÁLIDO (dados internos) - Esse código deve ser utilizado pelo Emissor quando dados internos do cartão não conferem (ex: criptograma inválido, ATC inválido etc.) Irreversível
83 NÃO É POSSÍVEL VALIDAR A SENHA - Esse código deve ser utilizado pelo Emissor e será utilizado pela Elo quando não for possível validar ou descriptografar a senha. Irreversível
91 EMISSOR FORA DO AR - Esse código será utilizado pela Bandeira quando o Emissor está temporariamente indisponível para autorizar a transação ou não foi recebida a resposta do Emissor no tempo estabelecido. Reversível
96 FALHA DO SISTEMA - Esse código será utilizado pela Bandeira ou pelo Emissor por problemas no processamento da transação. Reversível
AB FUNÇÃO INCORRETA (DÉBITO) - Esse código será utilizado pelo Emissor para sinalizar o estabelecimento que ele solicitou a autorização na função DÉBITO, mas o cartão não possui essa função ativa. Irreversível
AC FUNÇÃO INCORRETA (CRÉDITO) - Esse código será utilizado pelo Emissor para sinalizar o estabelecimento que ele solicitou a autorização na função CRÉDITO, mas o cartão não possui essa função ativa. Irreversível
FM UTILIZAR O CHIP - Esse código será utilizado pelo Emissor para informar ao estabelecimento que a transação contactless não terá sucesso e que o portador deve utilizar o chip (contato). Irreversível
P5 TROCA DE SENHA / FALHA NO DESBLOQUEIO - Esse código será utilizado pelo Emissor quando ocorreu falha na troca de senha ou falha no desbloqueio. Irreversível
P6 NOVA SENHA NÃO ACEITA - Esse código será utilizado pelo Emissor quando a nova senha que o cliente escolheu não atende os critérios mínimos estabelecidos pelo Emissor. Reversível

Hipercard

O que é?

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

Programa Cartão Presente Cartão não presente
Excesso de Retentativa R$ 1,85 por retentativa a partir da 9ª resposta negada – mesmo cartão e mesmo dia (regra 2) R$ 1,85 por Retentativas a partir da 9ª resposta negada – mesmo cartão e mesmo mês de referência (regra 3)
Retentativa de transação ASI (Zero Auth) R$ 0,15 por retentativa de transação ASI após negativa do emissor – mesmo cartão e mesmo dia (item 2) R$ 0,15 por retentativa de transação ASI após negativa do emissor – mesmo cartão e mesmo mês de referência (regra 3)
Retentativa de transação irreversível 0,03% do valor da transação por retentativa
Mínimo R$ 0,15
Máximo R$ 0,80
Mesmo cartão e mesmo dia após resposta com código irreversível
0,03% do valor da transação por retentativa
Mínimo R$ 0,15
Máximo R$ 0,80
Mesmo cartão e mesmo mês após resposta com código irreversível (regra 3)

Regras:

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

Demais bandeiras

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

Códigos de retorno ABECS

Para acessar o programa de retentativa das bandeira acesse esse Link

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

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

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

Mensagem Tipo de Código ELO VISA MASTERCARD/HIPER AMEX AMEX - De/Para Cielo Mensagem POS/Ecommerce Houve alteração da ABECS em 2022?  
GENÉRICA REVERSÍVEL 5 5 5 100 FA CONTATE A CENTRAL DO SEU CARTÃO Não  
SALDO/LIMITE INSUFICIENTE REVERSÍVEL 51 51 51 116 A5 NÃO AUTORIZADA Não  
SALDO/LIMITE INSUFICIENTE REVERSÍVEL 51 51 51 121 A5 NÃO AUTORIZADA Somente na nossa Documentação  
SENHA INVÁLIDA REVERSÍVEL 55 55 ou 86 55 117 A6 SENHA INVÁLIDA Não  
TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO REVERSÍVEL - 57 57 200 FD TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO Sim  
TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO IREVERSÍVEL 57 - - - - TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO - NÃO TENTE NOVAMENTE Novo  
NÚMERO CARTÃO NÃO PERTENCE AO EMISSOR / NÚMERO CARTÃO INVÁLIDO IRREVERSÍVEL 14 ou 56 14 14 ou 01 122 8 VERIFIQUE OS DADOS DO CARTÃO Sim  
VIOLAÇÃO DE SEGURANÇA IRREVERSÍVEL 63 63 - 122 8 VERIFIQUE OS DADOS DO CARTÃO Sim  
VIOLAÇÃO DE SEGURANÇA REVERSÍVEL - - 63 - - VERIFIQUE OS DADOS DO CARTÃO Novo  
SUSPEITA DE FRAUDE REVERSÍVEL 59 59 63 100 FA CONTATE A CENTRAL DO SEU CARTÃO Não  
COMERCIANTE INVÁLIDO IRREVERSÍVEL 58 3 3 109 DA TRANSAÇÃO NÃO PERMITIDA - NÃO TENTE NOVAMENTE Sim  
REFAZER A TRANSAÇÃO (EMISSOR SOLICITA RETENTATIVA) REVERSÍVEL 4 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE REFAZER A TRANSAÇÃO Sim  
CONSULTAR CREDENCIADOR REVERSÍVEL 6 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE LOJISTA, CONTATE O ADQUIRENTE Sim  
PROBLEMA NO ADQUIRENTE IRREVERSÍVEL 19 19 30 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE ERRO NO CARTÃO – NÃO TENTE NOVAMENTE Não  
ERRO NO CARTÃO IRREVERSÍVEL 12 6 SEM CÓDIGO CORRESPONDENTE 115 A2 VERIFIQUE OS DADOS DO CARTÃO Não  
ERRO DE FORMATO (MENSAGERIA) IRREVERSÍVEL 30 12 30 181 A3 ERRO NO CARTÃO - NÃO TENTE NOVAMENTE Não  
VALOR DA TRANSAÇÃO INVÁLIDA IRREVERSÍVEL 13 13 13 110 JB VALOR DA TRANSAÇÃO NÃO PERMITIDO - NÃO TENTE NOVAMENTE Não  
VALOR DA PARCELA INVÁLIDA IRREVERSÍVEL 23 SEM CÓDIGO CORRESPONDENTE 12 115 A2 PARCELAMENTO INVÁLIDO - NÃO TENTE NOVAMENTE Não  
EXCEDIDAS TENTATIVAS DE SENHA / COMPRAS REVERSÍVEL 38 75 75 106 A4 EXCEDIDAS TENTATIVAS DE SENHA.CONTATE A CENTRAL DO SEU CARTÃO Não  
CARTÃO PERDIDO IRREVERSÍVEL 41 41 41 200 FD TRANSAÇÃO NÃO PERMITIDA - NÃO TENTE NOVAMENTE Não  
CARTÃO ROUBADO IRREVERSÍVEL 43 43 43 200 FD TRANSAÇÃO NÃO PERMITIDA - NÃO TENTE NOVAMENTE Não  
CARTÃO VENCIDO / DT EXPIRAÇÃO INVÁLIDA IRREVERSÍVEL 54 54 54 101 BV VERIFIQUE OS DADOS DO CARTÃO Sim  
TRANSAÇÃO NÃO PERMITIDA CAPACIDADE DO TERMINAL IRREVERSÍVEL 57 58 58 116 A5 TRANSAÇÃO NÃO PERMITIDA - NÃO TENTE NOVAMENTE Não  
VALOR EXCESSO / SAQUE REVERSÍVEL 61 61 ou N4 61 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE VALOR EXCEDIDO. CONTATE A CENTRAL DO SEU CARTÃO Não  
BLOQUEIO TEMPORÁRIO (EX: INADIMPLÊNCIA) REVERSÍVEL 62 62 57 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE CONTATE A CENTRAL DO SEU CARTÃO Novo  
CARTÃO DOMÉSTICO - TRANSAÇÃO INTERNACIONAL IRREVERSÍVEL 62 SEM CÓDIGO CORRESPONDENTE 62 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE CARTÃO NÃO PERMITE TRANSAÇÃO INTERNACIONAL Somente na nossa Documentação  
CARTÃO DOMÉSTICO - TRANSAÇÃO INTERNACIONAL REVERSÍVEL SEM CÓDIGO CORRESPONDENTE 62 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE CARTÃO NÃO PERMITE TRANSAÇÃO INTERNACIONAL Somente na nossa Documentação  
VALOR MÍNIMO DA TRANSAÇÃO INVÁLIDO IRREVERSÍVEL 64 SEM CÓDIGO CORRESPONDENTE 13 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE VALOR DA TRANSAÇÃO NÃO PERMITIDO - NÃO TENTE NOVAMENTE Sim  
QUANT. DE SAQUES EXCEDIDO REVERSÍVEL 65 65 65 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE QUANTIDADE DE SAQUES EXCEDIDA. CONTATE A CENTRAL DO SEU CARTÃO Não  
SENHA VENCIDA / ERRO DE CRIPTOGRAFIA DE SENHA IRREVERSÍVEL 83 74 ou 81 88 180 A7 SENHA INVÁLIDA - NÃO TENTE NOVAMENTE Sim  
EXCEDIDAS TENTATIVAS DE SENHA SAQUE REVERSÍVEL 75 75 75 106 A4 EXCEDIDAS TENTATIVAS DE SENHA.CONTATE A CENTRAL DO SEU CARTÃO Não
CONTA DESTINO INVÁLIDA OU INEXISTENTE IRREVERSÍVEL 76 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE CONTA DESTINO INVÁLIDA - NÃO TENTE NOVAMENTE Não  
CONTA ORIGEM INVÁLIDA OU INEXISTENTE IRREVERSÍVEL 77 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE CONTA ORIGEM INVÁLIDA - NÃO TENTE NOVAMENTE Não  
CARTÃO NOVO SEM DESBLOQUEIO REVERSÍVEL 78 - 57 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE DESBLOQUEIE O CARTÃO Sim  
CARTÃO NOVO SEM DESBLOQUEIO IRREVERSÍVEL - 78 - - - DESBLOQUEIE O CARTÃO Novo  
CARTÃO INVÁLIDO (criptograma) IRREVERSÍVEL 82 82 88 180 A7 ERRO NO CARTÃO - NÃO TENTE NOVAMENTE Não  
EMISSOR FORA DO AR REVERSÍVEL 91 91 91 912 A1 FALHA DE COMUNICAÇÃO - TENTE MAIS TARDE Não  
FALHA DO SISTEMA REVERSÍVEL 96 96 96 911 AE FALHA DE COMUNICAÇÃO - TENTE MAIS TARDE Não  
DIFERENÇA - PRÉ AUTORIZAÇÃO IRREVERSÍVEL SEM CÓDIGO CORRESPONDENTE N8 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE VALOR DIFERENTE DA PRÉ AUTORIZAÇÃO - NÃO TENTE NOVAMENTE Sim  
FUNÇÃO INCORRETA (DÉBITO) IRREVERSÍVEL AB 52 ou 53 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE UTILIZE FUNÇÃO CRÉDITO Não  
FUNÇÃO INCORRETA (CRÉDITO) IRREVERSÍVEL AC 39 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE UTILIZE FUNÇÃO DÉBITO Não  
TROCA DE SENHA / DESBLOQUEIO IRREVERSÍVEL P5 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SENHA INVÁLIDA - NÃO TENTE NOVAMENTE Não  
NOVA SENHA NÃO ACEITA REVERSÍVEL P6 SEM CÓDIGO CORRESPONDENTE 55 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SENHA INVÁLIDA UTILIZE A NOVA SENHA Sim  
RECOLHER CARTÃO (NÃO HÁ FRAUDE) IRREVERSÍVEL SEM CÓDIGO CORRESPONDENTE 4 4 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE CONTATE A CENTRAL DO SEU CARTÃO - NÃO TENTE NOVAMENTE Sim  
ERRO POR MUDANÇA DE CHAVE DINÂMICA IRREVERSÍVEL SEM CÓDIGO CORRESPONDENTE N7 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE ERRO NO CARTÃO - NÃO TENTE NOVAMENTE Sim  
FRAUDE CONFIRMADA IRREVERSÍVEL 57 7 4 200 FD TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO - NÃO TENTE NOVAMENTE Não  
EMISSOR Ñ LOCALIZADO - BIN INCORRETO (negativa do adquirente) IRREVERSÍVEL SEM CÓDIGO CORRESPONDENTE 15 15 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE DADOS DO CARTÃO INVÁLIDO - NÃO TENTE NOVAMENTE Não  
NÃO CUMPRIMENTO PELAS LEIS DE ANTE LAVAGEM DE DINHEIRO IRREVERSÍVEL SEM CÓDIGO CORRESPONDENTE 64 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE CONTATE A CENTRAL DO SEU CARTÃO - NÃO TENTE NOVAMENTE Não  
REVERSÃO INVÁLIDA IRREVERSÍVEL SEM CÓDIGO CORRESPONDENTE 76 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE CONTATE A CENTRAL DO SEU CARTÃO - NÃO TENTE NOVAMENTE Não  
NÃO LOCALIZADO PELO ROTEADOR IRREVERSÍVEL SEM CÓDIGO CORRESPONDENTE 92 92 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE CONTATE A CENTRAL DO SEU CARTÃO - NÃO TENTE NOVAMENTE Não  
TRANSAÇÃO NEGADA POR INFRAÇÃO DE LEI IRREVERSÍVEL 57 93 62 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO - NÃO TENTE NOVAMENTE Sim  
VALOR DO TRACING DATA DUPLICADO IRREVERSÍVEL SEM CÓDIGO CORRESPONDENTE 94 94 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE CONTATE A CENTRAL DO SEU CARTÃO - NÃO TENTENOVAMENTE Não  
SURCHARGE NÃO SUPORTADO REVERSÍVEL SEM CÓDIGO CORRESPONDENTE B1 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE CONTATE A CENTRAL DO SEU CARTÃO Não  
SURCHARGE NÃO SUPORTADO PELA REDE DE DÉBITO REVERSÍVEL SEM CÓDIGO CORRESPONDENTE B2 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE CONTATE A CENTRAL DO SEU CARTÃO Não  
FORÇAR STIP REVERSÍVEL SEM CÓDIGO CORRESPONDENTE N0 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE CONTATE A CENTRAL DO SEU CARTÃO Não  
SAQUE NÃO DISPONÍVEL IRREVERSÍVEL SEM CÓDIGO CORRESPONDENTE N3 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SAQUE NÃO DISPONÍVEL - NÃO TENTE NOVAMENTE Não  
SUSPENSÃO DE PAGAMENTO RECORRENTE PARA UM SERVIÇO IRREVERSÍVEL SEM CÓDIGO CORRESPONDENTE R0 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SUSPENSÃO DE PAGAMENTO RECORRENTE PARA SERVIÇO - NÃO TENTE NOVAMENTE Não  
SUSPENSÃO DE PAGAMENTO RECORRENTE PARA TODOS SERVIÇO IRREVERSÍVEL SEM CÓDIGO CORRESPONDENTE R1 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SUSPENSÃO DE PAGAMENTO RECORRENTE PARA SERVIÇO - NÃO TENTE NOVAMENTE Não  
TRANSAÇÃO NÃO QUALIFICADA PARA VISA PIN IRREVERSÍVEL SEM CÓDIGO CORRESPONDENTE R2 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO - NÃO TENTE NOVAMENTE Não  
SUSPENSÃO DE TODAS AS ORDENS DE AUTORIZAÇÃO IRREVERSÍVEL SEM CÓDIGO CORRESPONDENTE R3 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SUSPENSÃO DE PAGAMENTO RECORRENTE PARA SERVIÇO - NÃO TENTE NOVAMENTE Não  
NÃO É POSSÍVEL LOCALIZAR O REGISTRO NO ARQUIVO IRREVERSÍVEL SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE CONTATE A CENTRAL DO SEU CARTÃO - NÃO TENTE NOVAMENTE Sim  
ARQUIVO NÃO DISPONÍVEL PARA ATUALIZAÇÃO IRREVERSÍVEL SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE CONTATE A CENTRAL DO SEU CARTÃO - NÃO TENTE NOVAMENTE Sim  
CONTA ENCERRADA IRREVERSÍVEL SEM CÓDIGO CORRESPONDENTE 46 62 SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO - NÃO TENTE NOVAMENTE Novo  
FALHA VALIDAÇÃO DE ID IRREVERSÍVEL SEM CÓDIGO CORRESPONDENTE 6P SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE FALHA NA VERIFICAÇÃO DO ID Novo  
UTILIZAR O CHIP IRREVERSÍVEL FM SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE SEM CÓDIGO CORRESPONDENTE UTILIZE O CHIP Novo  

Outros códigos de retorno

Código Resposta Definição Significado Ação Permite Retentativa
0 Transação autorizada com sucesso. Transação autorizada com sucesso. Transação autorizada com sucesso. Não
2 Transação não autorizada. Transação referida. Transação não autorizada. Referida (suspeita de fraude) pelo banco emissor. Transação não autorizada. Entre em contato com seu banco emissor. Não
9 Transação cancelada parcialmente com sucesso. Transação cancelada parcialmente com sucesso Transação cancelada parcialmente com sucesso Não
11 Transação autorizada com sucesso para cartão emitido no exterior Transação autorizada com sucesso. Transação autorizada com sucesso. Não
21 Cancelamento não efetuado. Transação não localizada. Não foi possível processar o cancelamento. Se o erro persistir, entre em contato com a Cielo. Não foi possível processar o cancelamento. Tente novamente mais tarde. Persistindo o erro, entrar em contato com a loja virtual. Não
22 Parcelamento inválido. Número de parcelas inválidas. Não foi possível processar a transação. Número de parcelas inválidas. Se o erro persistir, entre em contato com a Cielo. Não foi possível processar a transação. Valor inválido. Refazer a transação confirmando os dados informados. Persistindo o erro, entrar em contato com a loja virtual. Não
24 Quantidade de parcelas inválido. Não foi possível processar a transação. Quantidade de parcelas inválido. Se o erro persistir, entre em contato com a Cielo. Não foi possível processar a transação. Quantidade de parcelas inválido. Refazer a transação confirmando os dados informados. Persistindo o erro, entrar em contato com a loja virtual. Não
60 Transação não autorizada. Transação não autorizada. Tente novamente. Se o erro persistir o portador deve entrar em contato com o banco emissor. Não foi possível processar a transação. Tente novamente mais tarde. Se o erro persistir, entre em contato com seu banco emissor. Apenas 4 vezes em 16 dias.
67 Transação não autorizada. Cartão bloqueado para compras hoje. Transação não autorizada. Cartão bloqueado para compras hoje. Bloqueio pode ter ocorrido por excesso de tentativas inválidas. O cartão será desbloqueado automaticamente à meia noite. Transação não autorizada. Cartão bloqueado temporariamente. Entre em contato com seu banco emissor. A partir do dia seguinte, apenas 4 vezes em 16 dias.
70 Transação não autorizada. Limite excedido/sem saldo. Transação não autorizada. Limite excedido/sem saldo. Transação não autorizada. Entre em contato com seu banco emissor. A partir do dia seguinte, apenas 4 vezes em 16 dias.
72 Cancelamento não efetuado. Saldo disponível para cancelamento insuficiente. Cancelamento não efetuado. Saldo disponível para cancelamento insuficiente. Se o erro persistir, entre em contato com a Cielo. Cancelamento não efetuado. Tente novamente mais tarde. Se o erro persistir, entre em contato com a loja virtual. Não
79 TRANSAÇÃO MASTERCARD NÃO PERMITIDA PARA O CARTÃO Transação não autorizada. Não é possível processar a transação devido a erro relacionado ao cartão do portador. Solicite ao portador que entre em contato com o banco emissor. Entre em contato com o seu banco Não
80 Transação não autorizada. Divergencia na data de transação/pagamento. Transação não autorizada. Data da transação ou data do primeiro pagamento inválida. Transação não autorizada. Refazer a transação confirmando os dados. Não
82 TRANSAÇÃO MASTERCARD NÃO AUTORIZADA. LIGUE PARA O EMISSOR Transação não autorizada devido a regras do emissor. Oriente o portador a entrar em contato com o banco emissor. Entre em contato com o seu banco Não
83 TRANSAÇÃO MASTERCARD SUSPEITA DE FRAUDE Transação não autorizada. Suspeita de fraude pelo banco emissor. Entre em contato com o seu banco Não
85 Transação não permitida. Falha da operação. Transação não permitida. Houve um erro no processamento.Solicite ao portador que digite novamente os dados do cartão, se o erro persistir pode haver um problema no terminal do lojista, nesse caso o lojista deve entrar em contato com a Cielo. Transação não permitida. Informe os dados do cartão novamente. Se o erro persistir, entre em contato com a loja virtual. Não
89 Erro na transação. Transação não autorizada. Erro na transação. O portador deve tentar novamente e se o erro persistir, entrar em contato com o banco emissor. Transação não autorizada. Erro na transação. Tente novamente e se o erro persistir, entre em contato com seu banco emissor. Apenas 4 vezes em 16 dias.
90 Transação não permitida. Falha da operação. Transação não permitida. Houve um erro no processamento.Solicite ao portador que digite novamente os dados do cartão, se o erro persistir pode haver um problema no terminal do lojista, nesse caso o lojista deve entrar em contato com a Cielo. Transação não permitida. Informe os dados do cartão novamente. Se o erro persistir, entre em contato com a loja virtual. Não
97 Valor não permitido para essa transação. Transação não autorizada. Valor não permitido para essa transação. Transação não autorizada. Valor não permitido para essa transação. Não
98 Sistema/comunicação indisponível. Transação não autorizada. Sistema do emissor sem comunicação. Se for geral, verificar SITEF, GATEWAY e/ou Conectividade. Sua Transação não pode ser processada, Tente novamente mais tarde. Se o erro persistir, entre em contato com a loja virtual. Apenas 4 vezes em 16 dias.
475 Timeout de Cancelamento A aplicação não respondeu dentro do tempo esperado. Realizar uma nova tentativa após alguns segundos. Persistindo, entrar em contato com o Suporte. Não
999 Sistema/comunicação indisponível. Transação não autorizada. Sistema do emissor sem comunicação. Tente mais tarde. Pode ser erro no SITEF, favor verificar ! Sua Transação não pode ser processada, Tente novamente mais tarde. Se o erro persistir, entre em contato com a loja virtual. A partir do dia seguinte, apenas 4 vezes em 16 dias.
AA Tempo Excedido Tempo excedido na comunicação com o banco emissor. Oriente o portador a tentar novamente, se o erro persistir será necessário que o portador contate seu banco emissor. Tempo excedido na sua comunicação com o banco emissor, tente novamente mais tarde. Se o erro persistir, entre em contato com seu banco. Apenas 4 vezes em 16 dias.
AF Transação não permitida. Falha da operação. Transação não permitida. Houve um erro no processamento.Solicite ao portador que digite novamente os dados do cartão, se o erro persistir pode haver um problema no terminal do lojista, nesse caso o lojista deve entrar em contato com a Cielo. Transação não permitida. Informe os dados do cartão novamente. Se o erro persistir, entre em contato com a loja virtual. Não
AG Transação não permitida. Falha da operação. Transação não permitida. Houve um erro no processamento.Solicite ao portador que digite novamente os dados do cartão, se o erro persistir pode haver um problema no terminal do lojista, nesse caso o lojista deve entrar em contato com a Cielo. Transação não permitida. Informe os dados do cartão novamente. Se o erro persistir, entre em contato com a loja virtual. Não
AH Transação não permitida. Cartão de crédito sendo usado com débito. Use a função crédito. Transação não permitida. Cartão de crédito sendo usado com débito. Solicite ao portador que selecione a opção de pagamento Cartão de Crédito. Transação não autorizada. Tente novamente selecionando a opção de pagamento cartão de crédito. Não
AI Transação não autorizada. Autenticação não foi realizada. Transação não autorizada. Autenticação não foi realizada. O portador não concluiu a autenticação. Solicite ao portador que reveja os dados e tente novamente. Se o erro persistir, entre em contato com a Cielo informando o BIN (6 primeiros dígitos do cartão) Transação não autorizada. Autenticação não foi realizada com sucesso. Tente novamente e informe corretamente os dados solicitado. Se o erro persistir, entre em contato com o lojista. Não
AJ Transação não permitida. Transação de crédito ou débito em uma operação que permite apenas Private Label. Tente novamente selecionando a opção Private Label. Transação não permitida. Transação de crédito ou débito em uma operação que permite apenas Private Label. Solicite ao portador que tente novamente selecionando a opção Private Label. Caso não disponibilize a opção Private Label verifique na Cielo se o seu estabelecimento permite essa operação. Transação não permitida. Transação de crédito ou débito em uma operação que permite apenas Private Label. Tente novamente e selecione a opção Private Label. Em caso de um novo erro entre em contato com a loja virtual. Não
AV Transação não autorizada. Dados Inválidos Falha na validação dos dados da transação. Oriente o portador a rever os dados e tentar novamente. Falha na validação dos dados. Reveja os dados informados e tente novamente. Apenas 4 vezes em 16 dias.
BD Transação não permitida. Falha da operação. Transação não permitida. Houve um erro no processamento.Solicite ao portador que digite novamente os dados do cartão, se o erro persistir pode haver um problema no terminal do lojista, nesse caso o lojista deve entrar em contato com a Cielo. Transação não permitida. Informe os dados do cartão novamente. Se o erro persistir, entre em contato com a loja virtual. Não
BL Transação não autorizada. Limite diário excedido. Transação não autorizada. Limite diário excedido. Solicite ao portador que entre em contato com seu banco emissor. Transação não autorizada. Limite diário excedido. Entre em contato com seu banco emissor. A partir do dia seguinte, apenas 4 vezes em 16 dias.
BM Transação não autorizada. Cartão Inválido Transação não autorizada. Cartão inválido. Pode ser bloqueio do cartão no banco emissor ou dados incorretos. Tente usar o Algoritmo de Lhum (Mod 10) para evitar transações não autorizadas por esse motivo. Transação não autorizada. Cartão inválido. Refaça a transação confirmando os dados informados. Não
BN Transação não autorizada. Cartão ou conta bloqueado. Transação não autorizada. O cartão ou a conta do portador está bloqueada. Solicite ao portador que entre em contato com seu banco emissor. Transação não autorizada. O cartão ou a conta do portador está bloqueada. Entre em contato com seu banco emissor. Não
BO Transação não permitida. Falha da operação. Transação não permitida. Houve um erro no processamento. Solicite ao portador que digite novamente os dados do cartão, se o erro persistir, entre em contato com o banco emissor. Transação não permitida. Houve um erro no processamento. Digite novamente os dados do cartão, se o erro persistir, entre em contato com o banco emissor. Apenas 4 vezes em 16 dias.
BP Transação não autorizada. Conta corrente inexistente. Transação não autorizada. Não possível processar a transação por um erro relacionado ao cartão ou conta do portador. Solicite ao portador que entre em contato com o banco emissor. Transação não autorizada. Não possível processar a transação por um erro relacionado ao cartão ou conta do portador. Entre em contato com o banco emissor. Não
BP176 Transação não permitida. Parceiro deve checar se o processo de integração foi concluído com sucesso. Parceiro deve checar se o processo de integração foi concluído com sucesso.
BR Transação não autorizada. Conta encerrada A conta do portador está encerrada. Solicite ao portador que entre em contato com seu banco emissor. A conta do portador está encerrada. Solicite ao portador que entre em contato com seu banco emissor. Não
C1 Transação não permitida. Cartão não pode processar transações de débito. Troque a modalidade de pagamento ou o cartão utilizado. Troque a modalidade de pagamento ou o cartão utilizado. Não
C2 Transação não permitida. Dados incorretos. Favor rever os dados preenchidos na tela de pagamento. Dados incorretos. Favor rever os dados preenchidos na tela de pagamento. Não
C3 Transação não permitida. Período inválido para este tipo de transação. Período inválido para este tipo de transação. Não
CF Transação não autorizada.C79:J79 Falha na validação dos dados. Transação não autorizada. Falha na validação dos dados. Solicite ao portador que entre em contato com o banco emissor. Transação não autorizada. Falha na validação dos dados. Entre em contato com o banco emissor. Não
CG Transação não autorizada. Falha na validação dos dados. Transação não autorizada. Falha na validação dos dados. Solicite ao portador que entre em contato com o banco emissor. Transação não autorizada. Falha na validação dos dados. Entre em contato com o banco emissor. Não
DF Transação não permitida. Falha no cartão ou cartão inválido. Transação não permitida. Falha no cartão ou cartão inválido. Solicite ao portador que digite novamente os dados do cartão, se o erro persistir, entre em contato com o banco Transação não permitida. Falha no cartão ou cartão inválido. Digite novamente os dados do cartão, se o erro persistir, entre em contato com o banco Apenas 4 vezes em 16 dias.
DM Transação não autorizada. Limite excedido/sem saldo. Transação não autorizada. Limite excedido/sem saldo. Transação não autorizada. Entre em contato com seu banco emissor. A partir do dia seguinte, apenas 4 vezes em 16 dias.
DQ Transação não autorizada. Falha na validação dos dados. Transação não autorizada. Falha na validação dos dados. Solicite ao portador que entre em contato com o banco emissor. Transação não autorizada. Falha na validação dos dados. Entre em contato com o banco emissor. Não
DS Transação não permitida para o cartão Transação não autorizada. Transação não permitida para o cartão. Transação não autorizada. Entre em contato com seu banco emissor. Apenas 4 vezes em 16 dias.
EB Número de parcelas maior que o Permitido. Transação não autorizada. Entre em contato com a Cielo e verifique se o cadastro possui parcelamento liberado. Transação não autorizada. Entre em contato com a Cielo e verifique se o cadastro possui parcelamento liberado. Sim
EE Transação não permitida. Valor da parcela inferior ao mínimo permitido. Transação não permitida. Valor da parcela inferior ao mínimo permitido. Não é permitido parcelas inferiores a R$ 5,00. Necessário rever calculo para parcelas. Transação não permitida. O valor da parcela está abaixo do mínimo permitido. Entre em contato com a loja virtual. Não
EK Transação não permitida para o cartão Transação não autorizada. Transação não permitida para o cartão. Transação não autorizada. Entre em contato com seu banco emissor. Apenas 4 vezes em 16 dias.
FC Transação não autorizada. Ligue Emissor Transação não autorizada. Oriente o portador a entrar em contato com o banco emissor. Transação não autorizada. Entre em contato com seu banco emissor. Não
FE Transação não autorizada. Divergencia na data de transação/pagamento. Transação não autorizada. Data da transação ou data do primeiro pagamento inválida. Transação não autorizada. Refazer a transação confirmando os dados. Não
FF Cancelamento OK Transação de cancelamento autorizada com sucesso. ATENÇÂO: Esse retorno é para casos de cancelamentos e não para casos de autorizações. Transação de cancelamento autorizada com sucesso Não
FG Transação não autorizada. Ligue AmEx 08007285090. Transação não autorizada. Oriente o portador a entrar em contato com a Central de Atendimento AmEx. Transação não autorizada. Entre em contato com a Central de Atendimento AmEx no telefone 08007285090 Não
GA Aguarde Contato Transação não autorizada. Referida pelo Lynx Online de forma preventiva. Transação não autorizada. lojista deve aguardar contato por parte da Cielo Não
GF Transação negada. Transação não autorizada, verifique se o IP informado está liberado para processar a transação Transação não permitida. Entre em contato com a Cielo. Não
GD Transação não permitida. Transação não permitida. Entre em contato com a Cielo. Transação não permitida. Entre em contato com a Cielo.
GT Transação negada. Ataque de força bruta. Transação não permitida. Entre em contato com a Cielo. Não
GK Transação negada. Bloqueio temporário por ataque de força bruta. Transação não permitida. Entre em contato com a Cielo. Não
HJ Transação não permitida. Código da operação inválido. Transação não permitida. Código da operação Coban inválido. Transação não permitida. Código da operação Coban inválido. Entre em contato com o lojista. Não
IA Transação não permitida. Indicador da operação inválido. Transação não permitida. Indicador da operação Coban inválido. Transação não permitida. Indicador da operação Coban inválido. Entre em contato com o lojista. Não
KA Transação não permitida. Falha na validação dos dados. Transação não permitida. Houve uma falha na validação dos dados. Solicite ao portador que reveja os dados e tente novamente. Se o erro persistir verifique a comunicação entre loja virtual e Cielo. Transação não permitida. Houve uma falha na validação dos dados. reveja os dados informados e tente novamente. Se o erro persistir entre em contato com a Loja Virtual. Não
KB Transação não permitida. Selecionado a opção incorrente. Transação não permitida. Selecionado a opção incorreta. Solicite ao portador que reveja os dados e tente novamente. Se o erro persistir deve ser verificado a comunicação entre loja virtual e Cielo. Transação não permitida. Selecionado a opção incorreta. Tente novamente. Se o erro persistir entre em contato com a Loja Virtual. Não
KE Transação não autorizada. Falha na validação dos dados. Transação não autorizada. Falha na validação dos dados. Opção selecionada não está habilitada. Verifique as opções disponíveis para o portador. Transação não autorizada. Falha na validação dos dados. Opção selecionada não está habilitada. Entre em contato com a loja virtual. Não
NR Transação não permitida. Transação não permitida. Transação não permitida. Retentar a transação após 30 dias Retentar a transação após 30 dias.
RP Transação não permitida. Transação não permitida. Transação não permitida. Retentar a transação após 72h Retentar a transação após 72 horas.
SC Transação não permitida. Transação não permitida. Pagamento recorrente, serviço cancelado. Não retentar. Transação não permitida. Pagamento recorrente, serviço cancelado. Não retentar. Não.
U3 Transação não permitida. Falha na validação dos dados. Transação não permitida. Houve uma falha na validação dos dados. Solicite ao portador que reveja os dados e tente novamente. Se o erro persistir verifique a comunicação entre loja virtual e Cielo. Transação não permitida. Houve uma falha na validação dos dados. reveja os dados informados e tente novamente. Se o erro persistir entre em contato com a Loja Virtual. Não
6P Transação não autorizada. Dados Inválidos Falha na validação dos dados da transação. Oriente o portador a rever os dados e tentar novamente. Falha na validação dos dados. Reveja os dados informados e tente novamente. Apenas 4 vezes em 16 dias.

Status transacional

Código Status Meio de pagamento Descrição
0 NotFinished Todos Aguardando atualização de status.
1 Authorized Todos Pagamento apto a ser capturado ou definido como pago.
2 PaymentConfirmed Todos Pagamento confirmado e finalizado.
3 Denied Cartões de crédito e débito (transferência eletrônica) e e-wallets. Pagamento negado por Autorizador.
10 Voided Todos, exceto boleto Pagamento cancelado.
11 Refunded Cartões de crédito e débito e e-wallets. Pagamento cancelado após 23h59 do dia de autorização.
12 Pending Cartões de crédito e débito (transferência eletrônica), e-wallets e pix. Aguardandoretorno da instituição financeira.
13 Aborted Todos Pagamento cancelado por falha no processamento ou por ação do Antifraude.
20 Scheduled Cartão de crédito e e-wallets. Recorrência agendada.

Erros de integração

Erros da API - Esses códigos são respostas à validação do conteúdo dos dados enviados no momento da requisição à API.
Se um código de erro for exibido, a requisição contém erros (como tamanho, condições ou erros de cadastro etc.) que impedem a criação da transação

Exemplo

[
    {
        "Code": 126,
        "Message": "Credit Card Expiration Date is invalid"
    }
]
Propriedade Descrição
Code Código de Erro da API. Veja a lista de códigos
Message Descrição do erro. Veja a lista de códigos

Códigos de Erros da API

Códigos retornados em caso de erro, identificando o motivo do erro e suas respectivas mensagens.

Código Mensagem Descrição  
0 Internal error Dado enviado excede o tamanho do campo  
100 RequestId is required Campo enviado está vazio ou inválido  
101 MerchantId is required Campo enviado está vazio ou inválido  
102 Payment Type is required Campo enviado está vazio ou inválido  
103 Payment Type can only contain letters Caracteres especiais não permitidos  
104 Customer Identity is required Campo enviado está vazio ou inválido  
105 Customer Name is required Campo enviado está vazio ou inválido  
106 Transaction ID is required Campo enviado está vazio ou inválido  
107 OrderId is invalid or does not exists Campo enviado excede o tamanho ou contem caracteres especiais  
108 Amount must be greater or equal to zero Valor da transação deve ser maior que “0”  
109 Payment Currency is required Campo enviado está vazio ou inválido  
110 Invalid Payment Currency Campo enviado está vazio ou inválido  
111 Payment Country is required Campo enviado está vazio ou inválido  
112 Invalid Payment Country Campo enviado está vazio ou inválido  
113 Invalid Payment Code Campo enviado está vazio ou inválido  
114 The provided MerchantId is not in correct format O MerchantId enviado não é um GUID  
115 The provided MerchantId was not found O MerchantID não existe ou pertence a outro ambiente (EX: Sandbox)  
116 The provided MerchantId is blocked Loja bloqueada, entre em contato com o suporte Cielo  
117 Credit Card Holder is required Campo enviado está vazio ou inválido  
118 Credit Card Number is required Campo enviado está vazio ou inválido  
119 At least one Payment is required Nó “Payment” não enviado  
120 Request IP not allowed. Check your IP White List IP bloqueado por questões de segurança  
121 Customer is required Nó “Customer” não enviado  
122 MerchantOrderId is required Campo enviado está vazio ou inválido  
123 Installments must be greater or equal to one Numero de parcelas deve ser superior a 1  
124 Credit Card is Required Campo enviado está vazio ou inválido  
125 Credit Card Expiration Date is required Campo enviado está vazio ou inválido  
126 Credit Card Expiration Date is invalid Campo enviado está vazio ou inválido  
127 You must provide CreditCard Number Numero do cartão de crédito é obrigatório  
128 Card Number length exceeded Numero do cartão superiro a 16 digitos  
129 Affiliation not found Meio de pagamento não vinculado a loja ou Provider inválido  
130 Could not get Credit Card  
131 MerchantKey is required Campo enviado está vazio ou inválido  
132 MerchantKey is invalid O Merchantkey enviado não é um válido  
133 Provider is not supported for this Payment Type Provider enviado não existe  
134 FingerPrint length exceeded Dado enviado excede o tamanho do campo  
135 MerchantDefinedFieldValue length exceeded Dado enviado excede o tamanho do campo  
136 ItemDataName length exceeded Dado enviado excede o tamanho do campo  
137 ItemDataSKU length exceeded Dado enviado excede o tamanho do campo  
138 PassengerDataName length exceeded Dado enviado excede o tamanho do campo  
139 PassengerDataStatus length exceeded Dado enviado excede o tamanho do campo  
140 PassengerDataEmail length exceeded Dado enviado excede o tamanho do campo  
141 PassengerDataPhone length exceeded Dado enviado excede o tamanho do campo  
142 TravelDataRoute length exceeded Dado enviado excede o tamanho do campo  
143 TravelDataJourneyType length exceeded Dado enviado excede o tamanho do campo  
144 TravelLegDataDestination length exceeded Dado enviado excede o tamanho do campo  
145 TravelLegDataOrigin length exceeded Dado enviado excede o tamanho do campo  
146 SecurityCode length exceeded Dado enviado excede o tamanho do campo  
147 Address Street length exceeded Dado enviado excede o tamanho do campo  
148 Address Number length exceeded Dado enviado excede o tamanho do campo  
149 Address Complement length exceeded Dado enviado excede o tamanho do campo  
150 Address ZipCode length exceeded Dado enviado excede o tamanho do campo  
151 Address City length exceeded Dado enviado excede o tamanho do campo  
152 Address State length exceeded Dado enviado excede o tamanho do campo  
153 Address Country length exceeded Dado enviado excede o tamanho do campo  
154 Address District length exceeded Dado enviado excede o tamanho do campo  
155 Customer Name length exceeded Dado enviado excede o tamanho do campo  
156 Customer Identity length exceeded Dado enviado excede o tamanho do campo  
157 Customer IdentityType length exceeded Dado enviado excede o tamanho do campo  
158 Customer Email length exceeded Dado enviado excede o tamanho do campo  
159 ExtraData Name length exceeded Dado enviado excede o tamanho do campo  
160 ExtraData Value length exceeded Dado enviado excede o tamanho do campo  
161 Boleto Instructions length exceeded Dado enviado excede o tamanho do campo  
162 Boleto Demostrative length exceeded Dado enviado excede o tamanho do campo  
163 Return Url is required URL de retorno não é valida - Não é aceito paginação ou extenções (EX .PHP) na URL de retorno  
166 AuthorizeNow is required  
167 Antifraud not configured Antifraude não vinculado ao cadastro do lojista  
168 Recurrent Payment not found Recorrência não encontrada  
169 Recurrent Payment is not active Recorrência não está ativa. Execução paralizada  
170 Cartão Protegido not configured Token não vinculado ao cadastro do lojista  
171 Affiliation data not sent Falha no processamento do pedido - Entre em contato com o suporte Cielo  
172 Credential Code is required Falha na validação das credenciadas enviadas  
173 Payment method is not enabled Meio de pagamento não vinculado ao cadastro do lojista  
174 Card Number is required Campo enviado está vazio ou inválido  
175 EAN is required Campo enviado está vazio ou inválido  
176 Payment Currency is not supported Campo enviado está vazio ou inválido  
177 Card Number is invalid Campo enviado está vazio ou inválido  
178 EAN is invalid Campo enviado está vazio ou inválido  
179 The max number of installments allowed for recurring payment is 1 Campo enviado está vazio ou inválido  
180 The provided Card PaymentToken was not found Token não encontrado  
181 The MerchantIdJustClick is not configured Token bloqueado  
182 Brand is required Bandeira do cartão não enviado  
183 Invalid customer bithdate Data de nascimento inválida ou futura  
184 Request could not be empty Falha no formado da requisição. Verifique o código enviado  
185 Brand is not supported by selected provider Bandeira não suportada pela API Cielo  
186 The selected provider does not support the options provided (Capture, Authenticate, Recurrent or Installments) Meio de pagamento não suporta o comando enviado  
187 ExtraData Collection contains one or more duplicated names    
188 Avs with CPF invalid    
189 Avs with length of street exceeded    
190 Avs with length of number exceeded    
191 Avs with length of district exceeded    
192 Avs with zip code invalid    
193 Split Amount must be greater than zero    
194 Split Establishment is Required Campo enviado está vazio ou inválido  
195 The PlataformId is required Campo enviado está vazio ou inválido  
196 DeliveryAddress is required Campo enviado está vazio ou inválido  
197 Street is required Campo enviado está vazio ou inválido  
198 Number is required Campo enviado está vazio ou inválido  
199 ZipCode is required Campo enviado está vazio ou inválido  
200 City is required Campo enviado está vazio ou inválido  
201 State is required Campo enviado está vazio ou inválido  
202 District is required Campo enviado está vazio ou inválido  
203 Cart item Name is required Campo enviado está vazio ou inválido  
204 Cart item Quantity is required Campo enviado está vazio ou inválido  
205 Cart item type is required Campo enviado está vazio ou inválido  
206 Cart item name length exceeded    
207 Cart item description length exceeded    
208 Cart item sku length exceeded    
209 Shipping addressee sku length exceeded    
210 Shipping data cannot be null    
211 WalletKey is invalid    
212 Merchant Wallet Configuration not found    
213 Credit Card Number is invalid    
214 Credit Card Holder Must Have Only Letters    
215 Agency is required in Boleto Credential    
216 Customer IP address is invalid    
300 MerchantId was not found    
301 Request IP is not allowed    
302 Sent MerchantOrderId is duplicated    
303 Sent OrderId does not exist    
304 Customer Identity is required Campo enviado está vazio ou inválido  
306 Merchant is blocked Merchant está bloqueado  
307 Transaction not found    
308 Transaction not available to capture    
309 Transaction not available to void    
310 Payment method doest not support this operation    
311 Refund is not enabled for this merchant    
312 Transaction not available to refund    
313 Recurrent Payment not found    
314 Invalid Integration    
315 Cannot change NextRecurrency with pending payment    
316 Cannot set NextRecurrency to past date    
317 Invalid Recurrency Day    
318 No transaction found    
319 Smart recurrency is not enabled    
320 Can not Update Affiliation Because this Recurrency not Affiliation saved    
321 Can not set EndDate to before next recurrency    
322 Zero Dollar Auth is not enabled    
323 Bin Query is not enabled    

Códigos de Motivo de Retorno

Reason Code Reason Message
0 Successful
1 AffiliationNotFound
2 IssuficientFunds
3 CouldNotGetCreditCard
4 ConnectionWithAcquirerFailed
5 InvalidTransactionType
6 InvalidPaymentPlan
7 Denied
8 Scheduled
9 Waiting
10 Authenticated
11 NotAuthenticated
12 ProblemsWithCreditCard
13 CardCanceled
14 BlockedCreditCard
15 CardExpired
16 AbortedByFraud
17 CouldNotAntifraud
18 TryAgain
19 InvalidAmount
20 ProblemsWithIssuer
21 InvalidCardNumber
22 TimeOut
23 CartaoProtegidoIsNotEnabled
24 PaymentMethodIsNotEnabled
98 InvalidRequest
99 InternalError

Códigos e Mensagens de Erro - Pix

CÓDIGO EVENTO MENSAGEM DESCRIÇÃO/AÇÃO
422 Autorização Error on Merchant Integration Verifique se o Pix consta habilitado em seu cadastro
422 Autorização Error on bki service integration for charge Erro Transação Pix Bancos, entre em contato com Suporte E-commerce
BP904 Autorização O json informado não é válido Entre em contato com Suporte E-commerce para avaliar o motivo.
BP901 Autorização Falha na operação Refaça o pagamento, caso persista entre em contato com suporte e-commerce
422 Cancelamento Error on pix service integration for moneyback Não é possível cancelar a transação, A devolução ocorrerá somente se houver saldo.
422 Cancelamento Merchant bank for moneyback is not Cielo Transação Pix Banco não permite operações de cancelamento