Manual de Integração API e-commerce Cielo

Redirecionando para https://docs.cielo.com.br/ecommerce-cielo/docs/ ...

As documentações da API E-commerce Cielo estão em um novo portal

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

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

API E-commerce Cielo

Sobre essa documentação

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 suas credenciais (MerchantId e MerchantKey) nos respectivos endpoints dos ambientes:

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 as credenciais 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:

• Ausência de aplicativos proprietários: não é necessário instalar aplicativos no ambiente da loja virtual em nenhuma hipótese.
• Simplicidade: o protocolo utilizado é puramente o HTTPS.
• Facilidade de testes: a plataforma Cielo oferece um ambiente Sandbox publicamente acessível, que permite ao desenvolvedor a criação de uma conta de testes sem a necessidade de credenciamento, facilitando e agilizando o início da integração.
• Credenciais: o tratamento das credenciais do cliente, número de afiliação (MerchantId)e chave de acesso(MerchantKey) trafega no cabeçalho da requisição HTTP da mensagem.
• Segurança: a troca de informações se dá sempre entre o Servidor da Loja e da Cielo, ou seja, sem o browser do comprador.
• Multiplataforma: a integração é realizada através de Web Service REST.

Arquitetura da integração

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

• URL transacional - específica para operações como autorização, captura e cancelamento de transações.
• URL de consulta - para operações consultivas, como uma pesquisa de transações.

Para executar uma operação:

1. Combine a base da URL do ambiente com o endpoint da operação desejada. Ex.: https://api.cieloecommerce.cielo.com.br/1/sales/.
2. Envie a requisição para a URL utilizando o método HTTP adequado à operação.

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:

Produtos e bandeiras suportadas

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

Como melhorar a performance de aprovação

A combinação apropriada de parâmetros e produtos podem melhorar a taxa de aprovação das suas transações. Por exemplo, antes de salvar um cartão tokenizado, é possível validar o cartão pelo Zero Auth e apenas armazenar o cartão se estiver válido.

Confira a seguir alguns cenários com a indicação de informações que podem ser enviadas para auxiliar na aprovação junto aos emissores.

Cenário: validação de cartão

A validação do cartão no Zero Auth é o primeiro passo antes do armazenamento do cartão ou do envio da transação.

1. Envie o código de segurança do cartão (CVV) no parâmetro Payment.CreditCard.SecurityCode: emissores e bandeiras recomendam o envio do campo para assertividade na validação dos dados do cartão;
2. Envie o parâmetro Payment.CreditCard.CardOnFile.Usage como “First” (se for a primeira vez que armazena o cartão);
3. Realize o tratamento dos códigos de retorno – armazene o cartão (tokenizado) apenas se o retorno da validação for “0 - aprovada”.

Cenário: onboarding/armazenamento do cartão

Antes de salvar um cartão para uma compra futura do portador (compra com um clique ou envio de recorrências, por exemplo), a validação do cartão é recomendada.

1. Valide o cartão pelo Zero Auth, conforme cenário validação de cartão;
2. Se a validação foi positiva, salve o cartão para compras futuras ou recorrência.

Cenário: transação iniciada pelo portador

Quando a transação é iniciada pelo portador do cartão e o cartão ainda não está armazenado.

1. Envie o código de segurança do cartão (CVV) no parâmetro Payment.CreditCard.SecurityCode;

Se o cartão for armazenado a partir dessa primeira transação e a bandeira for Mastercard, é necessário enviar o Indicador de Início da Transação Mastercard

Cenário: transação recorrente iniciada pelo portador com armazenamento do cartão

Nesse cenário o portador está realizando uma compra de produto ou serviço recorrente (com cobrança periódica) e o cartão ainda não foi armazenado.

1. Valide o cartão utilizando o Zero Auth – antes do armazenamento do cartão, conforme cenário de validação do cartão;
2. Envie o parâmetro Payment.Recurrent como “true”;
3. Envie o parâmetro CardOnFile.Usage como “First”;
4. Envie o parâmetro IssuerTransactionId a partir da 2ª transação recorrente. O IssuerTransactionId é retornado pelos emissores/bandeiras na 1ª transação recorrente e funciona como um agrupador de recorrências.

Cenário: transação não recorrente iniciada pelo portador com cartão previamente armazenado

Nesse cenário o portador está iniciando a transação usando um cartão previamente salvo na loja, como a compra com um clique.

1. Envie o parâmetro Payment.Recurrent como “false”;
2. Envie o parâmetro CardOnFile.Usage como “Used”;
3. Envie o código de segurança do cartão (CVV) no parâmetro Payment.CreditCard.SecurityCode.

Cenário: transação não recorrente iniciada pela loja

Nesse cenário entende-se que o cartão já está armazenado com a validação pelo Zero Auth.

1. Envie o parâmetro Payment.Recurrent como “false”;
2. Envie o parâmetro CardOnFile.Usage como “Used”.

O cartão deve ser excluído da base caso o emissor retorne um código irreversível.

Cenário: transação recorrente iniciada pela loja

Nesse cenário entende-se que o cartão já está armazenado com a validação pelo Zero Auth.

1. Envie o parâmetro Payment.Recurrent como “true”;
2. Envie o parâmetro CardOnFile.Usage como “Used”;
3. Envie o parâmetro IssuerTransactionId a partir da 2ª transação recorrente. O IssuerTransactionId é retornado pelos emissores/bandeiras na 1ª transação recorrente e funciona como um agrupador de recorrências.

O cartão deve ser excluído da base caso o emissor retorne um código irreversível.

Cenário: transação recorrente iniciada pela loja com cartão armazenado não utilizado ou sem validação

Nesse cenário trata-se a primeira transação iniciada pela loja com cartão previamente armazenado (base antiga, por exemplo).

1. Valide o cartão pelo Zero Auth, conforme cenário validação de cartão;
2. Envie o parâmetro Payment.Recurrent como “true”;
3. Envie o parâmetro CardOnFile.Usage como “Used”.

O cartão deve ser excluído da base caso a validação pelo Zero Auth retorne um código irreversível.

Cenário: transação não recorrente, iniciada pelo portador, com armazenamento de cartão não utilizado ou sem validação

Nesse caso trata-se a primeira transação iniciada pelo portador com cartão previamente armazenado (base antiga, por exemplo).

1. Valide o cartão pelo Zero Auth antes de armazenar o cartão, conforme cenário validação de cartão;
2. Envie o parâmetro Payment.Recurrent como “false”;
3. Envie o parâmetro CardOnFile.Usage como “Used”;
4. Envie o código de segurança do cartão (CVV) no parâmetro Payment.CreditCard.SecurityCode.

O cartão deve ser excluído da base caso a validação pelo Zero Auth retorne um código irreversível.

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:

• Capitais e regiões metropolitanas: (11) 4002-5472
• Demais localidades: 0800 570 8472

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:

Firefox:

Google Chrome:

O que é Certificado EV SSL?

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

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

Como instalar o Certificado Extended Validation no servidor da Loja?

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

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

Passo a Passo para a Instalação

Instalação no Servidor da Loja Virtual

Para o passo a passo para a instalação do Certificado EV, contate 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:

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

2o Passo:

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

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

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

3o Passo:

No Internet Explorer, em Certificados, clique em Importar…:

No Firefox, clique em Ver Certificados, clique em Importar…:

No Chrome, clique em Gerenciar Certificados…, clique em Importar…:

4o Passo:

No Internet Explorer e Chrome, na aba Assistente para Importação de Certificados, clique em Avançar:

No Firefox, na aba Servidores, clique em Importar…:

5o Passo:

No Chrome e Internet Explorer, na aba 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.

6o Passo:

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

7o Passo:

Clique em Concluir:

8o Passo:

Clique em Ok para concluir a importação:

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

9o Passo:

Repita o mesmo procedimento para os 3 arquivos enviados.

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.

Vantagens de utilizar o Sandbox

• Não é necessário uma afiliação para utilizar o Sandbox Cielo.
• Basta acessar o Cadastro do Sandbox para criar uma conta.

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

Environment

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

Cartão de crédito em sandbox

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

• Autorização;
• Captura parcial e total;
• Cancelamento;
• Consulta.
  

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.

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 em sandbox

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

• Autorização;
• Cancelamento;

• Consulta.
  A transação de débito precisa passar por uma autenticação:

• Autenticação via 3DS 2.2: aprenda a simular a autenticação 3DS 2.2 em sandbox na documentação do 3DS;
• URL de Autenticação: está sendo descontinuada. Nesse tipo de autenticação, o fluxo transacional do cartão de débito funciona com a Resposta da transação retornando uma URL de Autenticação. Na tela de autenticação a opção escolhida define o status da transação:
  

Transferência Online: O mesmo comportamento do Cartão de débito em Sandbox é valido para cartão de débito.

Outros meios de pagamento em 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:

Renova Fácil em 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:

• No campo CreditCard.CardNumber: enviar um cartão com o número final sendo 3 (que simula um cenário de cartão vencido, vide tabela de cartões simulados presente na documentação).
• No campo CreditCard.ExpirationDate: enviar uma data de validade já vencida.
• Mandar o campo Payment.Recurrent preenchido como true, para marcar a transação como recorrente.

Consulta BIN em 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.

Exemplo

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

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.

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.

Atenção: Não é possível realizar uma transação com valor (Amount) 0. Para verificar a validade de um cartão, use o Zero Auth.

Transações de crédito Mastercard com credenciais armazenadas: a bandeira Mastercard exige o envio do Indicador de Início da Transação para compras de cartão de crédito e débito que usam os dados armazenados de um cartão. O objetivo é indicar se a transação foi iniciada pelo comprador (Cardholder-Initiated Transaction - CIT) ou pela loja (Merchant-Initiated Transaction - MIT). Nesse cenário é obrigatório o envio do nó InitiatedTransactionIndicator com os parâmetros Category e SubCategory para transações Mastercard, dentro do nó Payment. Confira o exemplo do nó e a lista de categorias e subcategorias em Indicador de início da transação Mastercard.

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",
      "Tip":false,
      "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",
      "Tip":false,
      "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

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,
      "Tip":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",
      "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,
        "Tip":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",
        "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"
            }
        ]
    }
}

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.2; 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.2.

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.

Transações de débito Mastercard com credenciais armazenadas: a bandeira Mastercard exige o envio do Indicador de Início da Transação para compras de cartão de crédito e débito que usam os dados armazenados de um cartão. O objetivo é indicar se a transação foi iniciada pelo comprador (Cardholder-Initiated Transaction - CIT) ou pela loja (Merchant-Initiated Transaction - MIT). Nesse cenário é obrigatório o envio do nó InitiatedTransactionIndicator com os parâmetros Category e SubCategory para transações Mastercard, dentro do nó Payment. Confira a lista de categorias na descrição do parâmetro Category e a tabela completa de subcategorias em Indicador de início da transação Mastercard.

Atenção: Não é possível realizar uma transação com valor (Amount) 0. Para verificar a validade de um cartão, use o Zero Auth.

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,
      "Tip":false,
      "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,
       "Tip":false,
       "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

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,
      "Tip":false,
      "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,
        "Tip":false,
        "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"
            }
        ]
    }
}

Autenticação 3DS

O que é?

É um protocolo de autenticação que confirma se o comprador é de fato o portador do cartão (de crédito ou débito). O objetivo do 3DS (também chamado de EMV 3DS) é evitar fraudes em transações de cartão não presente (CNP).

Por meio do 3DS, os dados do comprador são enviados para as bandeiras e emissores do cartão, que irão realizar a autenticação. Para uma transação autenticada pelo 3DS, a responsabilidade em caso de chargeback será das bandeiras ou emissores.

Todas as transações de cartão de débito devem ser autenticadas pelo protocolo 3DS.

Qual é o objetivo?

O 3DS realiza a autenticação validando dados do portador. A autenticação pode ser silenciosa ou com desafio (o desafio é uma interface para autenticação, ou seja, o cliente será submetido a uma validação adicional do emissor).

Qual é o impacto do uso no meu negócio?

Ao autenticar transações pelo protocolo 3DS, a responsabilidade em caso de chargeback será das bandeiras ou emissores.

Como usar o 3DS?

O processo de autorização de cartão autenticada via 3D Secure 2.2 ocorre em duas etapas:

1. Etapa de autenticação: por meio do protocolo 3DS, a bandeira ou o emissor autentica que o comprador é de fato o titular do cartão. O protocolo é integrado ao e-commerce por meio de um script em JavaScript, que retorna o resultado da autenticação e alguns parâmetros (como o ECI) que devem ser enviados na autorização. Saiba mais em Integração do script;
2. Etapa de autorização: a loja submete a transação para autorização, informando os parâmetros retornados pelo script na etapa de autenticação. Saiba mais em Autorização com Autenticação.

O fluxo a seguir descreve as etapas de autenticação em alto nível:

1. O comprador escolhe pagar com cartão de crédito ou débito;
2. A loja executa um script, solicitando à Cielo autenticação através da solução 3DS 2.2;
3. A loja envia requisição com dados do comprador para a bandeira;
4. A bandeira envia a requisição para avaliação de risco do emissor;
5. O emissor avalia as informações e determina se fluxo será com ou sem desafio ao portador;
5.1. Se o emissor solicitar desafio, cria e envia a URL para a loja;
5.2. A loja apresenta lightbox do desafio na página de checkout para obter resposta do comprador;
5.3. O comprador responde o desafio, completando a autenticação;
6. O emissor envia o resultado da autenticação para o 3DS Server;
7. O 3DS Server envia resultado da autenticação no campo ECI. A loja decide seguir ou não para autorização.

A loja pode optar por submeter uma transação não autenticada para autorização; no entanto, nesse caso, a loja será responsável em caso de chargeback.

Como não utilizar? O que não fazer?

• Não realizar transações de débito sem autenticação ou utilização de senha;
• Não realizar transações de débito sem CVV.

Como saber se a transação foi autenticada?

Isso irá depender do resultado da Tabela de ECI.

Detalhes importantes

O ECI (Eletronic Commerce Indicator) retornado na resposta da autenticação indica se o portador foi autenticado ou não pela bandeira ou emissor.

Se o ECI retornado indicar que o portador não foi autenticado, recomendamos a utilização de Antifraude para analisar o risco da transação.

Caso a loja envie suas transações primeiro para o Antifraude e a análise indique alto risco, recomendamos que o pedido seja encaminhado para autenticação no 3DS 2.2.

Integração do 3DS 2.2

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

1. Integre o script do 3DS 2.2 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.

Acesse o padrão mais atual do autenticador em 3DS 2.2, sendo que a versão 3DS 1.0 foi descontinuada.

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

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

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.

• MPI Interno: serviço já integrado a solução de 3DS Cielo, sem necessidade de integração e/ou contratação adicional.

• MPI Externo: usado quando o seu e-commerce contrata uma solução de MPI, sem participação da Cielo. Independente da versão do 3DS contratada, siga as orientações em Autorização com Autenticação para a integração.

Indicador de início da transação Mastercard

As tabelas a seguir se aplicam para transações de crédito e débito Mastercard com credenciais armazenadas. O objetivo é identificar se a transação foi iniciada pelo titular do cartão ou pela loja:

• Cardholder-Initiated Transaction (CIT): a transação é iniciada pela pessoa titular do cartão, que fornece suas credenciais de pagamento e permite que sejam armazenadas;
• Merchant-Initiated Transaction (MIT): a transação é iniciada pela loja, após um acordo no qual a pessoa titular do cartão autoriza a loja a armazenar e usar os dados de sua conta para iniciar uma ou mais transações futuras (como pagamentos recorrentes, pagamentos parcelados e cobranças posteriores, como as praticadas pelo setor de hospitalidade e turismo, por exemplo).
  
  Para indicar o iniciador de transação, é obrigatório enviar o nó Payment.InitiatedTransactionIndicator. Este nó tem dois parâmetros, categoria (Category) e subcategoria (Subcategory); confira a seguir o exemplo do nó na requisição e as tabelas com os valores correspondentes:

Requisição

   "Payment":{
     (...)
    "InitiatedTransactionIndicator": {
        "Category": "C1",
        "Subcategory": "Standingorder"
    },
    (...)
   }

   "Payment":{
     (...)
    "InitiatedTransactionIndicator": {
        "Category": "C1",
        "Subcategory": "Standingorder"
    },
    (...)
   }

Confira o exemplo de requisição completa em Criando uma transação de crédito ou em Criando uma transação de débito

Resposta

A resposta será o padrão da transação de crédito ou débito com o retorno do mesmo nó inserido na requisição.

Tabelas do indicador de início da transação Mastercard

Categorias CIT e MIT

As categorias (C1, M1 ou M2) devem ser informadas no parâmetro Payment.InitiatedTransactionIndicator.Category.

Subcategorias CIT e MIT

As subcategorias devem ser informadas no parâmetro Payment.InitiatedTransactionIndicator.Subcategory.

Atenção: Os dados do cartão são armazenados de forma criptografada.

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.

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

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

Conheça o ciclo de vida de uma transação 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:

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:

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

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

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.

• É necessário que o comprador (usuário pagador) solicite para a loja (usuário recebedor) a devolução total ou parcial de um pagamento realizado, via algum meio de comunicação adequado;
  
• A loja (usuário recebedor) concorda e identifica o pagamento original realizado pelo Pix.

Quando posso solicitar uma devolução Pix?

É possível solicitar uma devolução Pix quando, por exemplo, houver devolução do produto, erro na cobrança e indisponibilidade do produto em estoque.

Quem solicita a devolução Pix pela API E-commerce Cielo?

A loja (vendedor que recebeu a transação Pix) é quem solicita a devolução à API E-commerce Cielo, em acordo com o comprador. É importante se atentar aos prazos (de acordo com regulamento do Banco Central).

Como solicitar à devolução Pix?

Via API E-commerce Cielo ou App Cielo Gestão.

Regras para devolução Pix

• A devolução ocorrerá somente se houver saldo;
• Para transferências, vendas e demais transações com o Pix o prazo para cancelamento é de 90 dias, conforme especificação do BACEN;
• Os clientes que optarem pela transferência automática não terão saldo em conta de pagamento. Com isso não será possível efetuar a devolução com sucesso, e o retorno será “Lojista com saldo insuficiente para devolução”.

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

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

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

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

Regras Adicionais

Quantidade de caracteres por campo e Provider:

Bradesco

Banco do Brasil

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:

• Apple Pay
• Samsung Pay
• Google Pay

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:

QR Code

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

Para testar em sandbox 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:

• CVV com 3 dígitos;
• Validade no formato MM/YYYY.

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.

Facilitadores de Pagamento (ou subcredenciadores) devem, obrigatoriamente, enviar os parâmetros do nó PaymentFacilitator por exigência do Banco Central e das bandeiras. Caso não sejam enviados, a bandeira pode aplicar penalidades ao facilitador de pagamento.

Requisição

{
  "MerchantOrderId": "2019010101",
  "Customer": {
    "Name": "QRCode Test"
  },
  "Payment": {
    "Type": "qrcode",
    "Amount": 100,
    "Installments": 1,
    "Capture": false,
    "Modality": "Credit"
    "QrCode": {
    "MerchantName": "Loja Teste"
    },
    "PaymentFacilitator": {     
        "EstablishmentCode": "12345",
        "SubEstablishment": {
            "EstablishmentCode": "2000130733",
            "Mcc": "8999",
            "Address": "Av Marechal Camara 160",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "CountryCode": "76",
            "PostalCode": "20020080",
            "CompanyName": "Lojinha01",
            "Identity": "90501654000191",
            "PhoneNumber": "24999399555"
      }
    }
  }
}

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"
    "QrCode": {
    "MerchantName": "Loja Teste"
    },
    "PaymentFacilitator": {     
        "EstablishmentCode": "12345",
        "SubEstablishment": {
            "EstablishmentCode": "2000130733",
            "Mcc": "8999",
            "Address": "Av Marechal Camara 160",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "CountryCode": "76",
            "PostalCode": "20020080",
            "CompanyName": "Lojinha01",
            "Identity": "90501654000191",
            "PhoneNumber": "24999399555"
      }
    }
  }
}
--verbose

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

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(...)",
    "PaymentFacilitator": {     
        "EstablishmentCode": "12345",
        "SubEstablishment": {
            "EstablishmentCode": "2000130733",
            "Mcc": "8999",
            "Address": "Av Marechal Camara 160",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "CountryCode": "76",
            "PostalCode": "20020080",
            "CompanyName": "Lojinha01",
            "Identity": "90501654000191",
            "PhoneNumber": "24999399555"
      }
    },
    "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(...)",
        "PaymentFacilitator": {     
            "EstablishmentCode": "12345",
            "SubEstablishment": {
                "EstablishmentCode": "2000130733",
                "Mcc": "8999",
                "Address": "Av Marechal Camara 160",
                "City": "Rio de Janeiro",
                "State": "RJ",
                "CountryCode": "76",
                "PostalCode": "20020080",
                "CompanyName": "Lojinha01",
                "Identity": "90501654000191",
                "PhoneNumber": "24999399555"
      }
    },
        "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"
            }
        ]
    }
}

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.2. Obtenha mais informações sobre o protocolo de autenticação no manual do 3DS 2.2.

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