Visão geral - API Cielo eCommerce

O objetivo desta documentação é orientar o desenvolvedor sobre como integrar com a API Cielo eCommerce da Cielo, descrevendo as funcionalidades, os métodos a serem utilizados, listando informações a serem enviadas e recebidas, e provendo exemplos.

O mecanismo de integração com o Cielo eCommerce é simples, de modo que apenas conhecimentos intermediários em linguagem de programação para Web, requisições HTTP/HTTPS e manipulação de arquivos JSON, são necessários para implantar a solução Cielo eCommerce com sucesso.

Nesse manual você encontrará a referência sobre todas as operações disponíveis na API REST da API Cielo eCommerce. Estas operações devem ser executadas utilizando sua chave específica (Merchant ID e Merchant Key) nos respectivos endpoints dos ambientes:

  SandBox Produção
Requisições 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.

Características da solução

A solução API Cielo eCommerce da plataforma Cielo eCommerce foi desenvolvida com a tecnologia REST, que é padrão de mercado e independe da tecnologia utilizada por nossos clientes. Dessa forma, é possível integrar-se utilizando as mais variadas linguagens de programação, tais como:

Para Obter exemplos dessas linguagens, veja nosso tutorial de conversão via nosso Tutorial Postman

Entre outras características, os atributos que mais se destacam na plataforma Cielo eCommerce:

Arquitetura

A integração é realizada através de serviços disponibilizados como Web Services. O modelo empregado é bastante simples: Existem duas URLs (endpoint), uma específica operações que causam efeitos colaterais - como autorização, captura e cancelamento de transações, e uma URL específica para operações que não causam efeitos colaterais, como pesquisa de transações. Essas duas URLs receberão as mensagens HTTP através dos métodos POST, GET ou PUT. Cada tipo de mensagem deve ser enviada para um recurso identificado através do path.

Método Descrição
POST O método HTTP POST é utilizado na criação dos recursos ou no envio de informações que serão processadas. Por exemplo, criação de uma transação.
PUT O método HTTP PUT é utilizado para atualização de um recurso já existente. Por exemplo, captura ou cancelamento de uma transação previamente autorizada.
GET O método HTTP GET é utilizado para consultas de recursos já existentes. Por exemplo, consulta de transações.
  Métodos SandBox Produção
Requisição de transação POST / PUT https://apisandbox.cieloecommerce.cielo.com.br https://api.cieloecommerce.cielo.com.br/
Consultas GET https://apiquerysandbox.cieloecommerce.cielo.com.br https://apiquery.cieloecommerce.cielo.com.br/

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.
Chave de acesso é um código de segurança específico de cada loja, gerado pela Cielo, usada para realizar a autenticação e comunicação em todas as mensagens trocadas com a Cielo. Também conhecido como chave de produção e key data.
Comprador é o 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 Entidade que responde pela loja virtual.
Gateway de pagamentos Empresa responsável pelo integração técnica e processamento das transações.
Número de credenciamento é um número identificador que o lojista recebe após seu credenciamento junto à Cielo.
Portador é a pessoa que tem o porte do cartão no momento da venda.
SecureCode programa internacional da Mastercard para possibilitar a autenticação do comprador no momento de uma compra em ambiente eCommerce.
TID (Transaction Identifier) código composto por 20 caracteres que identificada unicamente uma transação Cielo eCommerce.
Transação é o pedido de compra do portador do cartão na Cielo.
VBV (Verified by Visa) Programa internacional da Visa que possibilita a autenticação do comprador no momento de uma compra em ambiente eCommerce.

Produtos e Bandeiras suportadas

A versão atual do Webservice 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

Cartões emitidos no exterior não possuem permissão de parcelamento.

Últimas Implementações

Facilitadores de Pagamento

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

Os novos campos estão contidos dentro do nó Payment Facilitator. Além dos campos deste novo nó, os facilitadores terão também de enviar obrigatoriamente o campo softdescriptor do nó payment. Segue abaixo exemplo do envio e da resposta.

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 Numérico 11 Obrigatório para facilitadores Código do estabelecimento do Facilitador. “Facilitator ID” (Cadastro do facilitador com as bandeiras)
PaymentFacilitator.SubEstablishment.EstablishmentCode Numérico 15 Obrigatório para facilitadores Código do estabelecimento do sub Merchant. “Sub-Merchant ID” (Cadastro do subcredenciado com o facilitador)
PaymentFacilitator.SubEstablishment.Identity Numérico 14 Obrigatório para facilitadores CNPJ ou CPF do sub-merchant.
PaymentFacilitator.SubEstablishment.Mcc Numérico 4 Obrigatório para facilitadores MCC do sub Merchant.
PaymentFacilitator.SubEstablishment.Address Alfanumérico 22 Obrigatório para facilitadores Endereço do sub Merchant.
PaymentFacilitator.SubEstablishment.City Alfanumérico 13 Obrigatório para facilitadores Cidade do sub Merchant.
PaymentFacilitator.SubEstablishment.State Alfanumérico 2 Obrigatório para facilitadores Estado do sub Merchant.
PaymentFacilitator.SubEstablishment.PostalCode Numérico 9 Obrigatório para facilitadores Código postal do sub Merchant.
PaymentFacilitator.SubEstablishment.CountryCode Numérico 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 Numérico 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.

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 Numérico 11 Obrigatório para facilitadores Código do estabelecimento do Facilitador. “Facilitator ID” (Cadastro do facilitador com as bandeiras)
PaymentFacilitator.SubEstablishment.EstablishmentCode Numérico 15 Obrigatório para facilitadores Código do estabelecimento do sub Merchant. “Sub-Merchant ID” (Cadastro do subcredenciado com o facilitador)
PaymentFacilitator.SubEstablishment.Identity Numérico 14 Obrigatório para facilitadores CNPJ ou CPF do sub-merchant.
PaymentFacilitator.SubEstablishment.Mcc Numérico 4 Obrigatório para facilitadores MCC do sub Merchant.
PaymentFacilitator.SubEstablishment.Address Alfanumérico 22 Obrigatório para facilitadores Endereço do sub Merchant.
PaymentFacilitator.SubEstablishment.City Alfanumérico 13 Obrigatório para facilitadores Cidade do sub Merchant.
PaymentFacilitator.SubEstablishment.State Alfanumérico 2 Obrigatório para facilitadores Estado do sub Merchant.
PaymentFacilitator.SubEstablishment.PostalCode Numérico 9 Obrigatório para facilitadores Código postal do sub Merchant.
PaymentFacilitator.SubEstablishment.CountryCode Numérico 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 Numérico 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.

Transações CBPS

Atualmente, os consumidores geralmente precisam fazer login em diversos sites de cobrança para pagar suas contas, muitos dos quais não aceitam pagamentos de cartão. Os fornecedores do Serviço de Pagamento de Contas para Consumidores (CBPS) simplificam o processo ao permitir que os consumidores façam todos os pagamentos de contas com cartão e em um único canal. Geralmente os fornecedores CBPS oferecem um aplicativo móvel ou um comercio eletrônico para o portador fazer a gestão e efetuar os pagamentos.

A Visa solicita que os provedores deste tipo de serviço passem a informar quais transações são CBPS a partir de Out20. Para isso, é necessário enviar o campo “IsCustomerBillPaymentService” como TRUE conforme exemplo abaixo.

Requisição

{
   "MerchantOrderId":"2014111703",
   "Customer":{
      "Name":"Comprador crédito simples"
   },
   "Payment":{
      "Type":"CreditCard",
      "Amount":15700,
      "Installments":1,
      "SoftDescriptor":"123456789ABCD",
      "CreditCard":{
         "CardNumber":"1234123412341231",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"123",
         "Brand":"Visa",
         "CardOnFile":{
            "Usage":"Used",
            "Reason":"Unscheduled"
         }
      },
      "IsCustomerBillPaymentService":true
   }
}
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)

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 é composto por duas áreas:

  1. Cadastro de conta de testes
  2. Endpoints transacionais
Requisição https://apisandbox.cieloecommerce.cielo.com.br
Consulta https://apiquerysandbox.cieloecommerce.cielo.com.br

Vantagens de utilizar o Sandbox

Ferramenta para Integração: POSTMAN

O Postman é um API Client que facilita aos desenvolvedores criar, compartilhar, testar e documentar APIs. Isso é feito, permitindo aos usuários criar e salvar solicitações HTTPs simples e complexas, bem como ler suas respostas.

A Cielo oferece coleções completas de suas integrações via Postamn, o que facilita o processo de integração com a API Cielo.

Sugerimos que desenvolvedores acessem nosso Tutorial sobre a ferramenta para compreender melhor todas as vantagens que ela oferece.

Cartão de crédito - Sandbox

No sandbox, é necessario utilizar o Provider seja utilizado como SIMULADO

O Simulado é uma configuração que emula a utilização de pagamentos com Cartão de Crédito. Com esse meio de pagamento é possível simular os fluxos de:

Para melhor utilização do Meio de Pagamento Simulado, estamos disponibilizando cartões de testes na tabela abaixo.

Status da Transação Final do Cartão Código de Retorno Mensagem de Retorno
Autorizado 0000.0000.0000.0001
0000.0000.0000.0004		 4/6 Operação realizada com sucesso
Não Autorizado 0000.0000.0000.0002 05 Não Autorizada
Não Autorizado 0000.0000.0000.0003 57 Cartão Expirado
Não Autorizado 0000.0000.0000.0005 78 Cartão Bloqueado
Não Autorizado 0000.0000.0000.0006 99 Time Out
Não Autorizado 0000.0000.0000.0007 77 Cartão Cancelado
Não Autorizado 0000.0000.0000.0008 70 Problemas com o Cartão de Crédito
Autorização Aleatória 0000.0000.0000.0009 99 Operation Successful / Time Out

Exemplo de um Cartão de teste - 4024.0071.5376.3191

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

Cartão de débito - Sandbox

Cartões de débito não possuem cartões ou dados específicos simulados, como no caso do cartão de crédito.

O fluxo transacional do cartão de Débito funciona com o Response da transação retornando uma URL DE AUTENTICAÇÃO . Na tela de autenticação a opção escolhida define o status da transação.

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 Diferenças
Boleto Não há validação bancaria. O boleto se comporta como um boleto sem registro
Cartão de débito O provider utilizado deve ser SIMULADO
A URL de redirecionamento para o ambiente do banco será na verdade uma tela para escolher o estado da autenticação
Transferência online O provider utilizado deve ser SIMULADO
A URL de redirecionamento para o ambiente do banco será na verdade uma tela para escolher o estado da autenticação

Meios de Pagamento

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
Autorização A autorização (ou pré-autorização) é a principal operação no eCommerce, pois através dela é que uma venda pode ser concretizada. A pré-autorização apenas sensibiliza o limite do cliente, mas ainda não gera cobrança para o consumidor.
Captura Ao realizar uma pré-autorização, é necessário a confirmação desta para que a cobrança seja efetivada ao portador do cartão. Através desta operação que se efetiva uma pré-autorização, podendo esta ser executada, em normalmente, em até 5 dias após a data da pré-autorização.
Cancelamento O cancelamento é necessário quando, por algum motivo, não se quer mais efetivar uma venda.
Autenticação O processo de autenticação possibilita realizar uma venda a qual passará pelo processo de autenticação do banco emissor do cartão, assim trazendo mais segurança para a venda e transferindo para o banco, o risco de fraude.
Cartão protegido É uma plataforma que permite o armazenamento seguro de dados sensíveis de cartão de crédito. Estes dados são transformados em um código criptografrado chamado de “token”, que poderá ser armazenado em banco de dados. Com a plataforma, a loja poderá oferecer recursos como “Compra com 1 clique” e “Retentativa de envio de transação”, sempre preservando a integridade e a confidencialidade das informações.
Antifraude É uma plataforma de prevenção à fraude que fornece uma análise de risco detalhada das compras on-line. Cada transação é submetida a mais de 260 regras, além das regras específicas de cada segmento, e geram uma recomendação de risco em aproximadamente dois segundos. Este processo é totalmente transparente para o portador do cartão. De acordo com os critérios preestabelecidos, o pedido pode ser automaticamente aceito, recusado ou encaminhado para análise manual.
Recorrente A Recorrência Inteligente é um recurso indispensável para estabelicimentos que precisam cobrar regularmente por seus produtos/serviços. É muito utilizado para assinaturas de revistas, mensalidades, licenças de software, entre outros. Os lojistas contarão com recursos diferenciados para modelar sua cobrança de acordo com o seu negócio, pois toda parametrização é configurável, tais como: periodicidade, data de início e fim, quantidade de tentativas, intervalo entre elas, entre outros.

Transação Simples

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":"2014111703",
   "Customer":{
      "Name":"Comprador crédito simples"
   },
   "Payment":{
     "Type":"CreditCard",
     "Amount":15700,
     "Installments":1,
     "SoftDescriptor":"123456789ABCD",
     "CreditCard":{
         "CardNumber":"1234123412341231",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"123",
         "Brand":"Visa",
         "CardOnFile":{
            "Usage": "Used",
            "Reason":"Unscheduled"
         }
     },
     "IsCryptoCurrencyNegotiation": true
   }
}

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":"2014111703",
   "Customer":{
      "Name":"Comprador crédito simples"
   },
   "Payment":{
     "Type":"CreditCard",
     "Amount":15700,
     "Installments":1,
     "SoftDescriptor":"123456789ABCD",
     "CreditCard":{
         "CardNumber":"1234123412341231",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"123",
         "Brand":"Visa",
         "CardOnFile":{
            "Usage": "Used",
            "Reason":"Unscheduled"
         }
     },
     "IsCryptoCurrencyNegotiation": true
   }
}
--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.
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.
Payment.Amount Número 15 Sim Valor do Pedido (ser enviado em centavos).
Payment.Installments Número 2 Sim Número de Parcelas.
Payment.SoftDescriptor Texto 13 Não Texto impresso na fatura bancaria comprador - Exclusivo para VISA/MASTER - não permite caracteres especiais - Ver Anexo
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
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.
CreditCard.ExpirationDate Texto 7 Sim Data de validade impresso no cartão.
CreditCard.SecurityCode Texto 4 Não Código de segurança impresso no verso do cartão - Ver Anexo.
CreditCard.Brand Texto 10 Sim Bandeira do cartão (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
Veja Mais

Resposta

{
    "MerchantOrderId": "2014111706",
    "Customer": {
        "Name": "Comprador crédito simples"
    },
    "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",
            "CardOnFile":{
               "Usage": "Used",
               "Reason":"Unscheduled"
            }
        },
        "IsCryptoCurrencyNegotiation": true,
        "tryautomaticcancellation":true,
        "ProofOfSale": "674532",
        "Tid": "0305023644309",
        "AuthorizationCode": "123456",
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "CreditCard",
        "Amount": 15700,
        "Currency": "BRL",
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 1,
        "ReturnCode": "4",
        "ReturnMessage": "Operation Successful",
        "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 crédito simples"
    },
    "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",
            "CardOnFile":{
               "Usage": "Used",
               "Reason":"Unscheduled"
            }
        },
        "IsCryptoCurrencyNegotiation": true,
        "tryautomaticcancellation":true,
        "ProofOfSale": "674532",
        "Tid": "0305023644309",
        "AuthorizationCode": "123456",
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "CreditCard",
        "Amount": 15700,
        "Currency": "BRL",
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 1,
        "ReturnCode": "4",
        "ReturnMessage": "Operation Successful",
        "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 impresso na fatura bancaria comprador - Exclusivo para VISA/MASTER - não permite caracteres especiais - Ver Anexo Texto 13 Texto alfanumérico
PaymentId Campo Identificador do Pedido. 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
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á sondada 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

Transação completa

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 todos os campos possíveis que podem ser enviados.

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"
        }
   },
   "Payment":{  
     "Currency":"BRL",
     "Country":"BRA",
     "ServiceTaxAmount":0,
     "Installments":1,
     "Interest":"ByMerchant",
     "Capture":true,
     "Authenticate":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"
        }
   },
   "Payment":{  
     "ServiceTaxAmount":0,
     "Installments":1,
     "Interest":"ByMerchant",
     "Capture":true,
     "Authenticate":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.
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 Pais 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 Texto impresso na fatura bancaria comprador - Exclusivo para VISA/MASTER - não permite caracteres especiais - Ver Anexo
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.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.
CreditCard.ExpirationDate Texto 7 Sim Data de validade impresso no cartão.
CreditCard.SecurityCode Texto 4 Não Código de segurança impresso no verso do cartão - Ver Anexo.
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 (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
Veja Mais

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"
        }
    },
    "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",
        "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"
        }
    },
    "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",
        "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 - nao permite caracteres especiais Texto 13 Texto alfanumérico
PaymentId Campo Identificador do Pedido. 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
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á sondada 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
Payment.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. Numérico 29 —

Transação Autenticada

Para criar uma transação com autenticaçã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.

Requisição

{
    "MerchantOrderId":"2014111903",
    "Customer":
    {
        "Name":"Comprador crédito autenticação"
    },
    "Payment":
    {
        "Type":"CreditCard",
        "Amount":15700,
        "Installments":1,
        "Authenticate":true,
        "SoftDescriptor":"123456789ABCD",
        "ReturnUrl":"https://www.cielo.com.br",
        "CreditCard":
        {
            "CardNumber":"1234123412341231",
            "Holder":"Teste Holder",
            "ExpirationDate":"12/2030",
            "SecurityCode":"123",
            "Brand":"Visa",
            "CardOnFile":{
               "Usage": "Used",
               "Reason":"Unscheduled"
            }
        },
        "IsCryptoCurrencyNegotiation": true
    }
}

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":"2014111903",
   "Customer":{  
      "Name":"Comprador crédito autenticação"
   },
   "Payment":{  
      "Type":"CreditCard",
      "Amount":15700,
      "Installments":1,
      "Authenticate":true,
      "ReturnUrl":"http://www.cielo.com.br",
      "SoftDescriptor":"123456789ABCD",
      "CreditCard":{  
         "CardNumber":"4551870000000183",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"123",
         "Brand":"Visa",
         "CardOnFile":{
            "Usage": "Used",
            "Reason":"Unscheduled"
         }
      },
     "IsCryptoCurrencyNegotiation": true
   }
}
--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.
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)
Payment.Type Texto 100 Sim Tipo do Meio de Pagamento.
Payment.Amount Número 15 Sim Valor do Pedido (ser enviado em centavos).
Payment.Provider Texto 15 — Define comportamento do meio de pagamento (ver Anexo)/NÃO OBRIGATÓRIO PARA CRÉDITO.
Payment.Installments Número 2 Sim Número de Parcelas.
Payment.Authenticate Booleano — Não (Default false) Define se o comprador será direcionado ao Banco emissor para autenticação do cartão
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
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.
CreditCard.ExpirationDate Texto 7 Sim Data de validade impresso no cartão.
CreditCard.SecurityCode Texto 4 Não Código de segurança impresso no verso do cartão - Ver Anexo.
CreditCard.Brand Texto 10 Sim Bandeira do cartão (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
Veja Mais

Resposta

{
    "MerchantOrderId":"2014111903",
    "Customer":
    {
        "Name":"Comprador crédito autenticação"
    },
    "Payment":
    {
        "ServiceTaxAmount":0,
        "Installments":1,
        "Interest":"ByMerchant",
        "Capture":false,
        "Authenticate":true,
        "CreditCard":
        {
            "CardNumber":"123412******1112",
            "Holder":"Teste Holder",
            "ExpirationDate":"12/2030",
            "SaveCard":false,
            "Brand":"Visa",
            "CardOnFile":{
               "Usage": "Used",
               "Reason":"Unscheduled"
            }
        },
        "IsCryptoCurrencyNegotiation": true,
        "AuthenticationUrl":"https://xxxxxxxxxxxx.xxxxx.xxx.xx/xxx/xxxxx.xxxx?id=c5158c1c7b475fdb91a7ad7cc094e7fe",
        "Tid": "1006993069257E521001",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId":"f2dbd5df-c2ee-482f-ab1b-7fee039108c0",
        "Type":"CreditCard",
        "Amount":15700,
        "Currency":"BRL",
        "Country":"BRA",
        "ExtraDataCollection":[],
        "Status":0,
        "ReturnCode": "0",
        "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":"2014111903",
    "Customer":
    {
        "Name":"Comprador crédito autenticação"
    },
    "Payment":
    {
        "ServiceTaxAmount":0,
        "Installments":1,
        "Interest":"ByMerchant",
        "Capture":false,
        "Authenticate":true,
        "CreditCard":
        {
            "CardNumber":"123412******1112",
            "Holder":"Teste Holder",
            "ExpirationDate":"12/2030",
            "SaveCard":false,
            "Brand":"Visa",
            "CardOnFile":{
               "Usage": "Used",
               "Reason":"Unscheduled"
            }
        },
        "IsCryptoCurrencyNegotiation": true,
        "AuthenticationUrl":"https://xxxxxxxxxxxx.xxxxx.xxx.xx/xxx/xxxxx.xxxx?id=c5158c1c7b475fdb91a7ad7cc094e7fe",
        "Tid": "1006993069257E521001",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId":"f2dbd5df-c2ee-482f-ab1b-7fee039108c0",
        "Type":"CreditCard",
        "Amount":15700,
        "Currency":"BRL",
        "Country":"BRA",
        "ExtraDataCollection":[],
        "Status":0,
        "ReturnCode": "0",
        "Links":
        [
            {
                "Method":"GET",
                "Rel":"self",
                "Href":"https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{Paymentid}"
            }
        ]
    }
}
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 Campo Identificador do Pedido. 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

ECI (E-commerce Indicator)

E-Commerce Indicator (ECI) é retornado no processo de autenticação. Este código é um indicador do que exatamente ocorreu no processo de autenticação da transação. Por meio do ECI, pode-se verificar se a transação foi autenticada e quem foi o agente responsável por aquela autenticação, conforme tabela abaixo:

Bandeira ECI Significado da Transação
Visa 05 Autenticada pelo Banco Emissor – risco de chargeback passa a ser do banco Emissor
Visa 06 Autenticada pela Bandeira – risco de chargeback passa a ser do banco Emissor
Visa Diferente de 05 e 06 Não autenticada – risco de chargeback permanece com o estabelecimento
Mastercard 01 Autenticada pela Bandeira – risco de chargeback passa a ser do banco Emissor
Mastercard 02 Autenticada pelo Banco Emissor – risco de chargeback passa a ser do banco Emissor
Mastercard 04 Não autenticada, transação caracterizada como Data Only – risco de chargeback permanece com o estabelecimento
Mastercard Diferente de 01, 02 e 04 Não autenticada – risco de chargeback permanece com o estabelecimento
Elo 05 Autenticada pelo Banco Emissor – risco de chargeback passa a ser do banco Emissor
Elo 06 Autenticada pela Bandeira – risco de chargeback passa a ser do banco Emissor
Elo 07 Não autenticada – risco de chargeback permanece com o estabelecimento

Cartão de Débito

Esse meio de pagamento é liberado automaticamente junto a afiliação de Cielo, podendo ser utilizado com as seguintes bandeiras e bancos:

MASTERCARD VISA
Bradesco Bradesco
Banco do Brasil Banco do Brasil
Santander Santander
Itaú Itaú
CitiBank CitiBank
BRB N/A
Caixa N/A
BancooB N/A

Autenticação Débito - 3DS 1.0

Por regra de mercado, todas as transações online realizadas com cartão de débito devem ser autenticadas através de um protocolo chamado 3DS, obrigatoriamente. Atualmente existem 2 versões: 3DS 1.0 e 3DS 2.0.

Na versão 1, o portador será direcionado para o ambiente bancário, onde será desafiado pelo emissor do cartão, digitando a sua senha e concluindo a autenticação. Essa versão não é compatível com dispositivos mobile e ocorrerá desafio em 100% dos casos. Existe a possibilidade de não autenticar transações de débito no e-Commerce, o que é conhecido como “Débito sem Senha”, porém, cabe aos Bancos Emissores do cartão aprovarem tal modelo, pois não é uma permissão concedida pela Cielo.

A autenticação é um processo que é mandatório para transações de débito no eCommerce, porém, é possível utilizá-la também para transações de crédito. Fica à critério do lojista autenticar transações de crédito no e-Commerce.

Recentemente, houve o lançamento da nova versão do 3DS 2.0 pelas bandeiras no mercado, permitindo a Cielo e emissores o desenvolvimento dessa solução, que já está disponível para integração. A tendência é que cada vez mais seja utilizada, considerando as suas diversas melhorias e benefícios. Para conhecer o 3DS 2.0, acesse https://developercielo.github.io/manual/emv3ds.

MPI – Merchant Plug-in

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 1.0 ou 2.0 através do MPI Interno ou do MPI Externo.

Autenticação Externa – MPI 3DS 1.0

Considerando a escolha por autenticar com 3DS 1.0 utilizando um serviço/fornecedor de MPI contratado (MPI Externo), a Cielo está preparada para receber essas informações na autorização.

Criando uma venda com autenticação externa

Para criar uma venda com cartão de crédito ou débito contendo dados de autenticação externa, é necessário enviar uma requisição utilizando o método POST para o recurso Payment conforme o exemplo.

Requisição
{
    "MerchantOrderId":"2014111903",
    "Customer":
    {
        "Name":"Comprador crédito autenticação",
        "Identity":"12345678912",
        "IdentityType":"cpf"
    },
    "Payment":
    {
        "Type":"CreditCard",
        "Amount":15700,
        "Installments":1,
        "Authenticate":true,
        "SoftDescriptor":"123456789ABCD",
        "ReturnUrl":"https://www.cielo.com.br",
        "CreditCard":
        {
            "CardNumber":"1234123412341231",
            "Holder":"Teste Holder",
            "ExpirationDate":"12/2030",
            "SecurityCode":"123",
            "Brand":"Visa"
        },
        "ExternalAuthentication":
        {
            "Cavv":"123456789",
            "Xid":"987654321",
            "Eci":"5"
        }
    }
}

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":"2014111903",
   "Customer":{  
      "Name":"Comprador crédito autenticação",
      "Identity":"12345678912",
      "IdentityType":"cpf"
   },
   "Payment":{  
      "Type":"CreditCard",
      "Amount":15700,
      "Installments":1,
      "Authenticate":true,
      "ReturnUrl":"http://www.cielo.com.br",
      "SoftDescriptor":"123456789ABCD",
      "CreditCard":{  
         "CardNumber":"4551870000000183",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"123",
         "Brand":"Visa"
      },
      "ExternalAuthentication":{
         "Cavv":"123456789",
         "Xid":"987654321",
         "Eci":"5"
      }
   }
}
--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.
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)
Payment.Type Texto 100 Sim Tipo do Meio de Pagamento.
Payment.Amount Número 15 Sim Valor do Pedido (ser enviado em centavos).
Payment.Provider Texto 15 — Define comportamento do meio de pagamento (ver Anexo)/NÃO OBRIGATÓRIO PARA CRÉDITO.
Payment.Installments Número 2 Sim Número de Parcelas.
Payment.Authenticate Booleano — Não (Default false) Indica se a transação deve ser autenticada (true) ou não (false). Mesmo para transações autenticadas externamente (fornecedor de autenticação de sua escolha), este campo deve ser enviado com valor “True”, e no nó ExternalAuthentication deve-se enviar os dados retornados pelo mecanismo de autenticação externa escolhido (XID, CAVV e ECI).
Payment.ExternalAuthentication.Cavv Texto - Sim O valor Cavv é retornado pelo mecanismo de autenticação.
Payment.ExternalAuthentication.Xid Texto - Sim O valor Xid é retornado pelo mecanismo de autenticação.
Payment.ExternalAuthentication.Eci Número 1 Sim O valor Eci é retornado pelo mecanismo de autenticaçã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.
CreditCard.ExpirationDate Texto 7 Sim Data de validade impresso no cartão.
CreditCard.SecurityCode Texto 4 Não Código de segurança impresso no verso do cartão - Ver Anexo.
CreditCard.Brand Texto 10 Sim Bandeira do cartão (Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard / Hiper).
Resposta
{
    "MerchantOrderId":"2014111903",
    "Customer":
    {
        "Name":"Comprador crédito autenticação",
        "Identity":"12345678912",
        "IdentityType":"cpf"
    },
    "Payment":
    {
        "ServiceTaxAmount":0,
        "Installments":1,
        "Interest":"ByMerchant",
        "Capture":false,
        "Authenticate":true,
        "CreditCard":
        {
            "CardNumber":"123412******1112",
            "Holder":"Teste Holder",
            "ExpirationDate":"12/2030",
            "SaveCard":false,
            "Brand":"Visa"
        },
        "AuthenticationUrl":"https://xxxxxxxxxxxx.xxxxx.xxx.xx/xxx/xxxxx.xxxx?id=c5158c1c7b475fdb91a7ad7cc094e7fe",
        "Tid": "1006993069257E521001",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId":"f2dbd5df-c2ee-482f-ab1b-7fee039108c0",
        "Type":"CreditCard",
        "Amount":15700,
        "Currency":"BRL",
        "Country":"BRA",
        "ExtraDataCollection":[],
        "Status":0,
        "ReturnCode":"0",
        "ReturnMessage":"Transacao autorizada"
        "ExternalAuthentication":
        {  
            "Cavv":"123456789",
            "Xid":"987654321",
            "Eci":"5"
        },
        "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":"2014111903",
    "Customer":
    {
        "Name":"Comprador crédito autenticação",
        "Identity":"12345678912",
        "IdentityType":"cpf"
    },
    "Payment":
    {
        "ServiceTaxAmount":0,
        "Installments":1,
        "Interest":"ByMerchant",
        "Capture":false,
        "Authenticate":true,
        "CreditCard":
        {
            "CardNumber":"123412******1112",
            "Holder":"Teste Holder",
            "ExpirationDate":"12/2030",
            "SaveCard":false,
            "Brand":"Visa"
        },
        "AuthenticationUrl":"https://xxxxxxxxxxxx.xxxxx.xxx.xx/xxx/xxxxx.xxxx?id=c5158c1c7b475fdb91a7ad7cc094e7fe",
        "Tid": "1006993069257E521001",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId":"f2dbd5df-c2ee-482f-ab1b-7fee039108c0",
        "Type":"CreditCard",
        "Amount":15700,
        "Currency":"BRL",
        "Country":"BRA",
        "ExtraDataCollection":[],
        "Status":0,
        "ReturnCode": "0",
        "ReturnMessage":"Transacao autorizada",
        "ExternalAuthentication":
        {  
            "Cavv":"123456789",
            "Xid":"987654321",
            "Eci":"5"
        },
        "Links":
        [
            {
                "Method":"GET",
                "Rel":"self",
                "Href":"https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{Paymentid}"
            }
        ]
    }
}
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 Campo Identificador do Pedido. 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

Transação padrão

Para criar uma venda que utilizará cartão de débito, é necessário fazer um POST para o recurso Payment conforme o exemplo.

Para realizar uma transação sem autenticação, basta enviar Authenticate = FALSE

O exemplo contempla o mínimo de campos necessários a serem enviados para a autorização.

Requisição

{  
   "MerchantOrderId":"2014121201",
   "Customer":{  
      "Name":"Comprador Cartão de débito"
   },
   "Payment":{  
     "Type":"DebitCard",
     "Authenticate": true,
     "Amount":15700,
     "ReturnUrl":"http://www.cielo.com.br",
     "DebitCard":{  
         "CardNumber":"4551870000000183",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"123",
         "Brand":"Visa"
     },
     "IsCryptoCurrencyNegotiation": true
   }
}

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,
     "ReturnUrl":"http://www.cielo.com.br",
     "DebitCard":{  
         "CardNumber":"4551870000000183",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"123",
         "Brand":"Visa"
     },
     "IsCryptoCurrencyNegotiation": true
   }
}
--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 (Default TRUE)
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

Resposta

{
    "MerchantOrderId": "2014121201",
    "Customer": {
        "Name": "Comprador Cartão de débito"
    },
    "Payment": {
        "DebitCard": {
            "CardNumber": "453211******3703",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa"
        },
        "IsCryptoCurrencyNegotiation": true,
        "AuthenticationUrl": "https://xxxxxxxxxxxx.xxxxx.xxx.xx/xxx/xxxxx.xxxx?{PaymentId}",
        "Tid": "1006993069207A31A001",
        "PaymentId": "0309f44f-fe5a-4de1-ba39-984f456130bd",
        "Type": "DebitCard",
        "Amount": 15700,
        "Currency": "BRL",
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 0,
        "ReturnCode": "0",
        "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": "2014121201",
    "Customer": {
        "Name": "Comprador Cartão de débito"
    },
    "Payment": {
        "DebitCard": {
            "CardNumber": "453211******3703",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa"
        },
        "IsCryptoCurrencyNegotiation": true,
        "AuthenticationUrl": "https://xxxxxxxxxxxx.xxxxx.xxx.xx/xxx/xxxxx.xxxx?{PaymentId}",
        "Tid": "1006993069207A31A001",
        "PaymentId": "0309f44f-fe5a-4de1-ba39-984f456130bd",
        "Type": "DebitCard",
        "Amount": 15700,
        "Currency": "BRL",
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 0,
        "ReturnCode": "0",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            }
        ]
    }
}
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 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

Cartões Alelo

Para criar uma venda que utilizará cartão de Alelo, é necessário fazer um POST para o recurso Payment utilizando o contrato técnico 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

Parâmetro Padrão ALELO
Payment.Authenticate FALSE ou não enviado
DebitCard.Brand Precisa ser enviado como ELO

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
Customer.Status Status de cadastro do comprador na loja (NEW / EXISTING) - Utilizado pela análise de fraude. Texto 255 Não
Payment.Authenticate Define se o comprador será direcionado ao Banco emissor para autenticação do cartão Booleano — Não (Defaul 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.SecurityCode Código de segurança impresso no verso do cartão. Texto 4 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
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 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

Transferência Eletrônica

Transação Simples

Para criar uma venda de transferência eletronica, é necessário fazer um 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":"2017051109",
    "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",
             "District":"Alphaville"
         }
  },
    "Payment":
    {  
        "Provider":"Bradesco",
        "Type":"EletronicTransfer",
        "Amount":10000,
        "ReturnUrl":"http://www.cielo.com.br"
    }
}

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":"2017051109",
    "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",
             "District":"Alphaville"
         }
  },
    "Payment":
    {  
        "Provider":"Bradesco",
        "Type":"EletronicTransfer",
        "Amount":10000,
        "ReturnUrl":"http://www.cielo.com.br"
    }
}
--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 Sim
Customer.Identity Número do RG, CPF ou CNPJ do Cliente Texto 14 Sim
Customer.IdentityType Tipo de documento de identificação do comprador (CPF ou CNPJ) 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.Address.Street Endereço de contato do comprador Texto 255 Sim
Customer.Address.Number Número endereço de contato do comprador Texto 15 Sim
Customer.Address.Complement Complemento do endereço de contato do Comprador Texto 50 Sim
Customer.Address.ZipCode CEP do endereço de contato do comprador Texto 9 Sim
Customer.Address.City Cidade do endereço de contato do comprador Texto 50 Sim
Customer.Address.State Estado do endereço de contato do comprador Texto 2 Sim
Customer.Address.Country Pais do endereço de contato do comprador Texto 35 Sim
Customer.Address.District Bairro do endereço de contato do comprador Texto 35 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.Provider Define comportamento do meio de pagamento (Veja Anexo)/NÃO OBRIGATÓRIO PARA CRÉDITO. Texto 15 —

Resposta

{
    "MerchantOrderId": "2014111706",
    "Customer": {
        "Name": "Comprador Transferência Eletronica",
    },
    "Payment": {
        "Url": "https://xxx.xxxxxxx.xxx.xx/post/EletronicTransfer/Redirect/{PaymentId}",
        "PaymentId": "765548b6-c4b8-4e2c-b9b9-6458dbd5da0a",
        "Type": "EletronicTransfer",
        "Amount": 15700,
        "Currency": "BRL",
        "Country": "BRA",
        "Provider": "Bradesco",
        "ExtraDataCollection": [],
        "Status": 0,
        "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 Transferência Eletronica",
    },
    "Payment": {
        "Url": "https://xxx.xxxxxxx.xxx.xx/post/EletronicTransfer/Redirect/{PaymentId}",
        "PaymentId": "765548b6-c4b8-4e2c-b9b9-6458dbd5da0a",
        "Type": "EletronicTransfer",
        "Amount": 15700,
        "Currency": "BRL",
        "Country": "BRA",
        "Provider": "Bradesco",
        "ExtraDataCollection": [],
        "Status": 0,
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            }
        ]
    }
}
Propriedade Descrição Tipo Tamanho Formato
PaymentId Campo Identificador do Pedido. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Url URL para qual o Lojista deve redirecionar o Cliente para o fluxo de Transferência Eletronica. Texto 256 Url de Autenticação
Status Status da Transação. Byte — 0

Boleto

Transação de Boletos

Para criar uma venda cuja a forma de pagamento é boleto, basta fazer um POST conforme o exemplo.

OBS: A API suporta boletos registrados e não registrados, sendo o provider o diferenciador entre eles. Sugerimos que valide com seu banco qual o tipo de boleto suportado por sua carteira. A API Aceita apenas boletos Bradesco e Banco do Brasil

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"
        }
    },
    "Payment":
    {  
        "Type":"Boleto",
        "Amount":15700,
        "Provider":"INCLUIR PROVIDER",
        "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"
        }
    },
    "Payment":
    {  
        "Type":"Boleto",
        "Amount":15700,
        "Provider":"INCLUIR PROVIDER",
        "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
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. Texto 15 Sim
Payment.Adress Endereço do Cedente. Texto 255 Não
Payment.BoletoNumber Número do Boleto enviado pelo lojista. Usado para contar boletos emitidos (“NossoNumero”). Texto 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

{
    "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"
        }
    },
    "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": "Bradesco",
        "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": {}
    },
    "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": "Bradesco",
        "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 Campo Identificador do Pedido. 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:

Propriedade Observações Bradesco Banco do Brasil
Provider N/A Bradesco2 BancoDoBrasil2
MerchantOrderId OBS 1 27 50
Payment.BoletoNumber OBS 2 11 9
Customer.Name OBS 3 34 60
Customer.Address.Street OBS 4 70 OBS 3 / Ver comentário
Customer.Address.Number OBS 4 10 OBS 3 / Ver comentário
Customer.Address.Complement OBS 4 20 OBS 3 / Ver comentário
Customer.Address.District OBS 4 50 OBS 3 / Ver comentário
Customer.Address.City N/A 50 - OBS 4 18 - OBS 3
Payment.Instructions N/A 255 255
Payment.Demonstrative N/A 255 Não é enviado ao banco do Brasil

Comentário Banco Do Brasil: Os campos Customer.Address.Street; Customer.Address.Number; Customer.Address.Complement; Customer.Address.District devem totalizar até 60 caracteres.

Observações Bradesco Banco do Brasil
OBS 1: Apenas Letras, números e caracteres como “_” e “$” Não é enviado ao banco
OBS 2: O dado é validado pelo banco Quando enviado acima de 9 posições, a API Cielo trunca automaticamente, considerando os últimos 9 dígitos
OBS 3: A API Cielo trunca automaticamente 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
OBS 4: O dado é validado pela API Cielo N/A

API QR Code via API E-Commerce

O objetivo desta documentação é orientar o desenvolvedor sobre como integrar com a API E-Commerce da Cielo para gerar o QRCode de Pagamento, descrevendo as funcionalidades, os métodos a serem utilizados, listando informações a serem enviadas e recebidas, e provendo exemplos.

O mecanismo de integração com o Cielo eCommerce é simples, de modo que apenas conhecimentos intermediários em linguagem de programação para Web, requisições HTTP/HTTPS e manipulação de arquivos JSON, são necessários para implantar a solução Cielo eCommerce com sucesso.

Nesse manual você encontrará a referência sobre todas as operações disponíveis na API REST da API Cielo eCommerce. Estas operações devem ser executadas utilizando sua chave específica (Merchant ID e Merchant Key) nos respectivos endpoints dos ambientes:

Ambiente Produção

Ambiente Sandbox

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.

Arquitetura

A integração é realizada através de serviços disponibilizados como Web Services. O modelo empregado é bastante simples: Existem duas URLs (endpoint), uma específica operações que causam efeitos colaterais - como autorização, captura e cancelamento de transações, e uma URL específica para operações que não causam efeitos colaterais, como pesquisa de transações. Essas duas URLs receberão as mensagens HTTP através dos métodos POST, GET ou PUT. Cada tipo de mensagem deve ser enviada para um recurso identificado através do path.

Método Descrição
POST O método HTTP POST é utilizado na criação dos recursos ou no envio de informações que serão processadas. Por exemplo, criação de uma transação.
PUT O método HTTP PUT é utilizado para atualização de um recurso já existente. Por exemplo, captura ou cancelamento de uma transação previamente autorizada.
GET O método HTTP GET é utilizado para consultas de recursos já existentes. Por exemplo, consulta de transações.

Produtos e Bandeiras suportadas

QR Code de Pagamento possui suporte às seguintes bandeiras e produtos:

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

Sandbox e Ferramentas

Sobre o Sandbox

Para facilitar os testes durante a integração, a Cielo oferece um ambiente Sandbox que é composto por duas áreas:

  1. Cadastro de conta de testes
  2. Endpoints transacionais
Requisição https://apisandbox.cieloecommerce.cielo.com.br
Consulta https://apiquerysandbox.cieloecommerce.cielo.com.br

Vantagens de utilizar o Sandbox

Ferramenta para Integração: POSTMAN

O Postman é um API Client que facilita aos desenvolvedores criar, compartilhar, testar e documentar APIs. Isso é feito, permitindo aos usuários criar e salvar solicitações HTTPs simples e complexas, bem como ler suas respostas.

A Cielo oferece coleções completas de suas integrações via Postamn, o que facilita o processo de integração com a API Cielo.

Sugerimos que desenvolvedores acessem nosso Tutorial sobre a ferramenta para compreender melhor todas as vantagens que ela oferece.

Cartão de crédito - 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 - CVV (3 dígitos) Validade (MM/YYYY).

Gerando um QRCode 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
   }
}

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

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 Campo Identificador do Pedido, 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

Consulta - PaymentID

Para consultar uma venda de cartão de crédito, é necessário fazer um GET para o recurso Payment conforme o exemplo.

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 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
PaymentId Numero de identificação do Pagamento. Texto 36 Sim

Resposta

{
    "MerchantOrderId": "2014111706",
    "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"
        },
        "ProofOfSale": "674532",
        "AuthorizationCode": "123456",
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "qrcode",
        "Amount": 15700,
        "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",
        "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"
        },
        "ProofOfSale": "674532",
        "AuthorizationCode": "123456",
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "CreditCard",
        "Amount": 15700,
        "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
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 Texto 255 Não Nome do Comprador.
Customer.Status Texto 255 Não Status de cadastro do comprador na loja (NEW / EXISTING)
Payment.Type Texto 100 Sim Tipo do Meio de Pagamento.
Payment.Amount Número 15 Sim Valor do Pedido (ser enviado em centavos).
Payment.Provider Texto 15 — Define comportamento do meio de pagamento (ver Anexo)/NÃO OBRIGATÓRIO PARA CRÉDITO.
Payment.Installments Número 2 Sim Número de Parcelas.
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.
CreditCard.ExpirationDate Texto 7 Sim Data de validade impresso no cartão.
CreditCard.SecurityCode Texto 4 Não Código de segurança impresso no verso do cartão - Ver Anexo.
CreditCard.Brand Texto 10 Não Bandeira do cartão (Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard / Hiper).

Consulta - MerchandOrderID

Não é possível consultar diretamente uma pagamento pelo identificador enviado pela loja (MerchantOrderId), mas é possível obter todos os PaymentIds associados ao identificador.

Para consultar uma venda pelo identificador da loja, é necessário fazer um GET para o recuso sales conforme o exemplo.

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 Campo Identificador do Pedido. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Captura

A Captura é passo exclusivo para transações de Cartões de Crédito.

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

O que a captura gera:

Requisição - Captura Parcial


https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{paymentId}/capture?amount={Valor}


curl
--request PUT "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{paymentId}/capture?amount={Valor}"
--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 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
PaymentId Campo Identificador do Pedido. Guid 36 Sim
Amount Valor do Pedido (ser enviado em centavos). Número 15 Não
ServiceTaxAmount 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. Número 15 Não

Resposta

{
    "Status": 2,
    "ReasonCode": 0,
    "ReasonMessage": "Successful",
    "ProviderReturnCode": "6",
    "ProviderReturnMessage": "Operation Successful",
    "ReturnCode": "6",
    "ReturnMessage": "Operation Successful",
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/8b1d43ee-a918-40d2-ba62-e5665e7ccbd3"
        },
        {
            "Method": "PUT",
            "Rel": "void",
            "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/8b1d43ee-a918-40d2-ba62-e5665e7ccbd3/void"
        }
    ]
}

--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "Status": 2,
    "ReasonCode": 0,
    "ReasonMessage": "Successful",
    "ProviderReturnCode": "6",
    "ProviderReturnMessage": "Operation Successful",
    "ReturnCode": "6",
    "ReturnMessage": "Operation Successful",
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/8b1d43ee-a918-40d2-ba62-e5665e7ccbd3"
        },
        {
            "Method": "PUT",
            "Rel": "void",
            "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/8b1d43ee-a918-40d2-ba62-e5665e7ccbd3/void"
        }
    ]
}
Propriedade Descrição Tipo Tamanho Formato
Status Status da Transação. Byte — 2
ReasonCode Código de retorno da Operação. Texto 32 Texto alfanumérico
ReasonMessage Mensagem de retorno da Operaçãoe. Texto 512 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

Resposta

{
    "Status": 2,
    "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,
    "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
ReasonCode Código de retorno da Operação. Texto 32 Texto alfanumérico
ReasonMessage Mensagem de retorno da Operaçãoe. Texto 512 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

Cancelamento

O cancelamento é a operação responsável pela cancelamento total ou parcial de um valor autorizado ou capturado.

Basta realizar um POST enviando o valor a ser cancelado.

Requisição - cancelamento

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 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
PaymentId Campo Identificador do Pedido. Guid 36 Sim
Amount Valor do Pedido (ser enviado em centavos). Número 15 Não

Resposta

{
    "Status": 2,
    "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,
    "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
ReasonCode Código de retorno da Operação. Texto 32 Texto alfanumérico
ReasonMessage Mensagem de retorno da Operaçãoe. Texto 512 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

Erros de Integração

Caso ocorram erros de integração em qualquer um dos meios de pagamento, um “response” será retornado contendo um código de erro e uma descrição

Exemplo

A Data de validade do cartão possui um valor não permitido como “08/A020” e não “08/2020”, a resposta será:

[
    {
        "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

Consulta - Captura - Cancelamento

Consulta de transações

Consulta - PaymentID

Para consultar uma venda de cartão de crédito, é necessário fazer um GET para o recurso Payment conforme o exemplo.

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 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
PaymentId Numero de identificação do Pagamento. Texto 36 Sim

Resposta

{
    "MerchantOrderId": "2014111706",
    "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",
        "AuthorizationCode": "123456",
        "Chargebacks": [
            {
                "Amount": 10000,
                "CaseNumber": "123456",
                "Date": "2017-06-04",
                "ReasonCode": "104",
                "ReasonMessage": "Outras Fraudes - Cartao Ausente",
                "Status": "Received",
                "RawData": "Client did not participate and did not authorize transaction"
            }
        ],
        "FraudAlert": {
            "Date": "2017-05-20",
            "ReasonMessage": "Uso Ind Numeração",
            "IncomingChargeback": false
        },
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "CreditCard",
        "Amount": 15700,
        "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",
        "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",
        "AuthorizationCode": "123456",
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "CreditCard",
        "Amount": 15700,
        "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
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 Texto 255 Não Nome do Comprador.
Customer.Status Texto 255 Não Status de cadastro do comprador na loja (NEW / EXISTING)
Payment.Type Texto 100 Sim Tipo do Meio de Pagamento.
Payment.Amount Número 15 Sim Valor do Pedido (ser enviado em centavos).
Payment.Provider Texto 15 — Define comportamento do meio de pagamento (ver Anexo)/NÃO OBRIGATÓRIO PARA CRÉDITO.
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.
CreditCard.ExpirationDate Texto 7 Sim Data de validade impresso no cartão.
CreditCard.SecurityCode Texto 4 Não Código de segurança impresso no verso do cartão - Ver Anexo.
CreditCard.Brand Texto 10 Sim Bandeira do cartão (Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard / Hiper).
CreditCard.PaymentAccountReference Numérico 29 Não 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.

Consulta - MerchandOrderID

Não é possível consultar diretamente uma pagamento pelo identificador enviado pela loja (MerchantOrderId), mas é possível obter todos os PaymentIds associados ao identificador.

Para consultar uma venda pelo identificador da loja, é necessário fazer um GET para o recuso sales conforme o exemplo.

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 Campo Identificador do Pedido. Guid 36 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Consulta Recorrência

Para consultar uma Recorrência de cartão de crédito, é necessário fazer um GET conforme o exemplo.

A Consulta da Recorrência traz dados sobre o agendamento e sobre o processo de transações que se repetem. Elas não retornam dados sobre as transações em si. Para isso, deve ser realizado um GET na transação (Disponível em “Consultando vendas)

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.RecurrentPaymentId Id 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 é passo exclusivo para transações de Cartões de Crédito.

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

O que a captura gera:

Captura total

Para captura uma venda que utiliza cartão de crédito, é necessário fazer um PUT para o recurso Payment conforme o exemplo.

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 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
PaymentId Campo Identificador do Pedido. Guid 36 Sim
Amount Valor do Pedido (ser enviado em centavos). Número 15 Não
ServiceTaxAmount 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. 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

Captura parcial

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

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

Basta realizar um POST enviando o valor a ser capturado.

Requisição - Captura Parcial


https://api.cieloecommerce.cielo.com.br/1/sales/{paymentId}/capture?amount={Valor}


curl
--request PUT "https://api.cieloecommerce.cielo.com.br/1/sales/{paymentId}/capture?amount={Valor}"
--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 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
PaymentId Campo Identificador do Pedido. Guid 36 Sim
Amount Valor do Pedido (ser enviado em centavos). Número 15 Não
ServiceTaxAmount 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. Número 15 Não

Resposta

{
    "Status": 2,
    "Tid": "0719094510712",
    "ProofOfSale": "4510712",
    "AuthorizationCode": "693066",
    "ReasonCode": 0,
    "ReasonMessage": "Successful",
    "ProviderReturnCode": "6",
    "ProviderReturnMessage": "Operation Successful",
    "ReturnCode": "6",
    "ReturnMessage": "Operation Successful",
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "Href": "https://api.cieloecommerce.cielo.com.br/1/sales/8b1d43ee-a918-40d2-ba62-e5665e7ccbd3"
        },
        {
            "Method": "PUT",
            "Rel": "void",
            "Href": "https://api.cieloecommerce.cielo.com.br/1/sales/8b1d43ee-a918-40d2-ba62-e5665e7ccbd3/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": "6",
    "ProviderReturnMessage": "Operation Successful",
    "ReturnCode": "6",
    "ReturnMessage": "Operation Successful",
    "Links": [
        {
            "Method": "GET",
            "Rel": "self",
            "Href": "https://api.cieloecommerce.cielo.com.br/1/sales/8b1d43ee-a918-40d2-ba62-e5665e7ccbd3"
        },
        {
            "Method": "PUT",
            "Rel": "void",
            "Href": "https://api.cieloecommerce.cielo.com.br/1/sales/8b1d43ee-a918-40d2-ba62-e5665e7ccbd3/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  
ReasonCode Código de retorno da Operação. Texto 32 Texto alfanumérico  
ReasonMessage Mensagem de retorno da Operação. 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  
ReturnCode Código de retorno da adquirente. Texto 32 Texto alfanumérico  
ReturnMessage Mensagem de retorno da adquirente. Texto 512 Texto alfanumérico  

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://api.cieloecommerce.cielo.com.br/1/sales/4d7be764-0e81-4446-b31e-7eb56bf2c9a8"
        },
        {
            "Method": "PUT",
            "Rel": "void",
            "Href": "https://api.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://api.cieloecommerce.cielo.com.br/1/sales/4d7be764-0e81-4446-b31e-7eb56bf2c9a8"
        },
        {
            "Method": "PUT",
            "Rel": "void",
            "Href": "https://api.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  
ReasonCode Código de retorno da Operação. Texto 32 Texto alfanumérico  
ReasonMessage Mensagem de retorno da Operação. 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  
ReturnCode Código de retorno da adquirente. Texto 32 Texto alfanumérico  
ReturnMessage Mensagem de retorno da adquirente. Texto 512 Texto alfanumérico  

Captura Via Backoffice

É possivel realizar tanto a captura total quanto a Captura parcial via O Backoffice Cielo.

Acesse nosso Tutorial para maiores informações

Cancelando uma venda

O cancelamento é uma funcionalidade que permite ao lojista estornar um pedido de compra, seja por insuficiência de estoque, por desistência da compra pelo consumidor, ou qualquer outro motivo.

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

Para transações autorizadas e não capturadas (status transacional = 1), o cancelamento pode ser solicitado antes de ocorrer o desfazimento automático da transação.

Já para transações capturadas (status transacional = 2), é possível realizar a requisição de cancelamento 1 dia após a captura e em um prazo de até 365 dias após a autorização da venda. A aprovação dessa ordem de cancelamento é suscetível a avalição de saldo na agenda financeira do lojista no momento da requisição e a aprovação do banco emissor do cartão utilizado na transação.

Cancelando uma venda via API

O processo de cancelamento via API está disponivel apenas para cartão de crédito e débito.

Cada meio de pagamento sofre impactos diferentes quando uma ordem de cancelamento (VOID) é executada.

Cancelamento total

Para cancelar uma venda que utiliza cartão de crédito, é necessário fazer um PUT para o recurso Payment. É possível realizar o cancelamento via PaymentID ou MerchantOrderId (numero do pedido).

Requisição

ou

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 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
PaymentId Campo Identificador do Pedido. 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 que o valor total autorizado/capturado. Esse modelo de cancelamento pode ocorrer inumeras vezes, até que o valor total da transação seja cancelado.

Basta realizar um POST enviando o valor a ser cancelado.

Requisição - cancelamento parcial

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 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
PaymentId Campo Identificador do Pedido. 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 Backoffice

O Cancelamento via Backoffice é a unica opção para realizar o cancelamento de transações de Débito Online. É possivel realizar tanto o cancelamento total quanto o Cancelamento parcial via O Backoffice Cielo.

Efeitos sobre o meio de pagamento

Meio de pagamento Descrição Prazo Participação Cielo
Transferência Eletrônica Cancelamento apenas na API. O retorno do valor é feito pelo proprio lojista Definido pelo lojista Não

Acesse nosso Tutorial para maiores informações

Post de Notificação

Sobre o POST

A API Cielo e-commerce oferece um sistema de notificação transacional, onde o Lojista fornece um endpoint que receberá uma notificação via POST

O Conteudo da notificação será formado por 3 campos:

Com os dados acima, o lojista poderá identificar a transação (via PaymentId ou RecurrentPaymentId) e a mudança sofrida por ela. Com o PaymentId é possivel realizar uma consulta a base transacional da API Cielo E-commerce

O Post de notificação é enviado com base em uma seleção de eventos pré-definidos no cadastro da API Cielo E-commerce. Esses eventos são cadastros pela equipe de suporte Cielo, quando requisitado pelo lojista

Eventos Notificados

Os eventos passiveis de notificação são:

Meio de Pagamento Evento
Cartão de Crédito Captura
Cartão de Crédito Cancelamento
Cartão de Crédito Sondagem
Boleto Conciliação
Boleto Cancelamento Manual
Transferência eletrônica Confirmadas

Sobre Cartão de débito: Não notificamos transações de Cartão de débito. Sugerimos que seja criada uma URL de RETORNO, onde o comprador será enviado se a transação for finalizada no ambiente do banco. Quando essa URL for acionada, nossa sugestão é que um GET seja executado, buscando informações do pedido na API Cielo</aside>

A notificação ocorre tambem 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

Endpoint de Notificação

Uma URL Status Pagamento deve ser cadastrada pelo Suporte Cielo, para que o POST de notificação seja executado.

Características da URL Status Pagamento

Características do Post de notificação

É possivel cadastrar uma informação para retorno do header da requisição. Basta entrar em contato com o Suporte Cielo e informar os itens abaixo

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

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

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

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 Identificador que representa a transação GUID 36 Sim
ChangeType Especifica o tipo de notificação. Vide tabela abaixo Número 1 Sim
ChangeType Descrição
1 Mudança de status do pagamento
2 Recorrência criada
3 Mudança de status do Antifraude
4 Mudança de status do pagamento recorrente (Ex. desativação automática)
5 cancelamento negado
7 Notificação de chargeback
Para mais detalhes Risk Notification
8 Alerta de fraude

Análise de Fraude

A API e-commerce Cielo oferece um serviço de análise de risco de fraudes em transações online. A Cielo se integra a empresas de analise de risco, como CyberSource, que realizam uma validação dos dados transacionais e do histórico de compras do portador do cartão. Essa análise retorna fatores de risco e permite que o lojista tome a decisão se dará continuidade a venda

Para utilizar a análise de risco, é necessario que o serviço seja ativado junto a Cielo. Existem 3 tipos de configurações de análise de fraude disponíveis:

Tipo Descrição Fornecedor
SuperMID Sem BPO Estratégia de risco definida pela Cielo
Não é possivel costumizar as regras no fornecedor e não há analista de risco dedicado		 CyberSource
SuperMID Com BPO Estratégia de risco definida pela Cielo
Não é possivel costumizar as regras no fornecedor e poderá ter analista de risco dedicado, desde contratado pelo lojista junto ao fornecedor		 CyberSource
Advanced ou Enterprise O Lojista tem um contrato fechado diretamente com o fornecedor de Antifraude, com estratégia de risco e analista dedicados. Cielo deve configurar as credenciais fornecidas pelo fornecedor de Antifraude no seu estabelecimento CyberSource

A análise de fraude está disponível apenas para transações de cartão de crédito!

Integração

Tipo de Integração Descrição Parâmetros necessários
Análise antes da autorização Antes da transação ser enviada para a autorização, o Antifraude avalia se ela tem alto risco ou não. Dessa forma, evita-se o envio de transações arriscadas para autorização FraudAnalysis.Sequence igual a AnalyseFirst
Análise após a autorização Antes da transação ser enviada para o AntiFraude, a mesma será enviada para a autorização FraudAnalysis.Sequence igual a AuthorizeFirst
Análise de risco somente se a transação for autorizada O AntiFraude será acionado apenas para analisar transações com o staus autorizada. Dessa forma evita-se o custo com análises de transações que não seriam autorizadas FraudAnalysis.SequenceCriteria igual a OnSuccess
Análise de risco em qualquer hipótese Independente do status da transação após a autorização, o AntiFraude analisará o risco FraudAnalysis.Sequence igual a AuthorizeFirst e FraudAnalysis.SequenceCriteria como Always
Autorização em qualquer hipótese Independente do score de fraude da transação, ela sempre será enviada para a autorização FraudAnalysis.Sequence como AnalyseFirst e FraudAnalysis.SequenceCriteria como Always
Capturar apenas se uma transação for segura Após a análise de fraude, captura automaticamente uma transação já autorizada se definido baixo risco. Este mesmo parâmetro serve para você que irá trabalhar com revisão manual, que após a Cielo receber a notificação do novo status e for igual a aceita, a transação será capturada automaticamente FraudAnalysis.Sequence igual a AuthorizeFirst, FraudAnalysis.CaptureOnLowRisk igual a true e Payment.Capture igual a false
Cancelar uma transação comprometida Caso a análise de fraude retorne um alto risco para uma transação já autorizada ou capturada, ela será imediamente cancelada ou estornada. Este mesmo parâmetro serve para você que irá trabalhar com revisão manual, que após a Cielo receber a notificação do novo status e for igual a rejeitada, a transação será cancelada automaticamente FraudAnalysis.Sequence como AuthorizeFirst , FraudAnalysis.VoidOnHighRisk igual a true e Payment.Capture igual a false

Para que a análise de fraude via Cybersource seja efetuada durante uma transação de cartão de crédito, é necessário complementar o contrato de autorização com os nós “FraudAnalysis”, “Cart”, “MerchantDefinedFields” e “Travel (somente para venda de passagens aéreas)”.

Requisição

{  
    "MerchantOrderId":"2017051002",
    "Customer":{  
        "Name":"Nome do Comprador",
        "Identity":"12345678910",
        "IdentityType":"CPF",
        "Email":"comprador@provedor.com.br",
        "Birthdate":"1991-01-02",
        "Phone": "5521976781114",
        "BillingAddress":{  
            "Street":"Alameda Xingu",
            "Number":"512",
            "Complement":"27 andar",
            "ZipCode":"12345987",
            "City":"São Paulo",
            "State":"SP",
            "Country":"BR",
            "District":"Alphaville"
        },
        "DeliveryAddress":{  
            "Street":"Alameda Xingu",
            "Number":"512",
            "Complement":"27 andar",
            "ZipCode":"12345987",
            "City":"São Paulo",
            "State":"SP",
            "Country":"BR",
            "District":"Alphaville"
        }
    },
    "Payment":{  
        "Type":"CreditCard",
        "Amount":10000,
        "Currency":"BRL",
        "Country":"BRA",
        "ServiceTaxAmount":0,
        "Installments":1,
        "Interest":"ByMerchant",
        "Capture":false,
        "Authenticate":false,
        "SoftDescriptor":"Mensagem",
        "CreditCard":{  
            "CardNumber":"4551870000000181",
            "Holder":"Nome do Portador",
            "ExpirationDate":"12/2021",
            "SecurityCode":"123",
            "Brand":"Visa",
            "SaveCard":"false"
        },
        "FraudAnalysis":{  
            "Provider":"Cybersource",
            "Sequence":"AuthorizeFirst",
            "SequenceCriteria":"OnSuccess",
            "CaptureOnLowRisk":false,
            "VoidOnHighRisk":false,
            "TotalOrderAmount":10000,
            "Browser":{  
                "BrowserFingerprint":"074c1ee676ed4998ab66491013c565e2",
                "CookiesAccepted":false,
                "Email":"comprador@test.com.br",
                "HostName":"Teste",
                "IpAddress":"127.0.0.1",
                "Type":"Chrome"
            },
            "Cart":{  
                "IsGift":false,
                "ReturnsAccepted":true,
                "Items":[  
                    {  
                        "GiftCategory":"Undefined",
                        "HostHedge":"Off",
                        "NonSensicalHedge":"Off",
                        "ObscenitiesHedge":"Off",
                        "PhoneHedge":"Off",
                        "Name":"ItemTeste1",
                        "Quantity":1,
                        "Sku":"20170511",
                        "UnitPrice":10000,
                        "Risk":"High",
                        "TimeHedge":"Normal",
                        "Type":"AdultContent",
                        "VelocityHedge":"High"
                    },
                    {  
                        "GiftCategory":"Undefined",
                        "HostHedge":"Off",
                        "NonSensicalHedge":"Off",
                        "ObscenitiesHedge":"Off",
                        "PhoneHedge":"Off",
                        "Name":"ItemTeste2",
                        "Quantity":1,
                        "Sku":"20170512",
                        "UnitPrice":10000,
                        "Risk":"High",
                        "TimeHedge":"Normal",
                        "Type":"AdultContent",
                        "VelocityHedge":"High"
                    }
                ]
            },
            "MerchantDefinedFields":[  
                {  
                    "Id":2,
                    "Value":"100"
                },
                {  
                    "Id":4,
                    "Value":"Web"
                },
                {  
                    "Id":9,
                    "Value":"SIM"
                }
            ],
            "Shipping":{  
                "Addressee":"João das Couves",
                "Method":"LowCost",
                "Phone":"551121840540"
            },
            "Travel":{  
                "JourneyType":"OneWayTrip",
                "DepartureTime":"2018-01-09 18:00",
                "Passengers":[  
                    {  
                        "Name":"Passenger Test",
                        "Identity":"212424808",
                        "Status":"Gold",
                        "Rating":"Adult",
                        "Email":"email@mail.com",
                        "Phone":"5564991681074",
                        "TravelLegs":[  
                            {  
                                "Origin":"AMS",
                                "Destination":"GIG"
                            }
                        ]
                    }
                ]
            }
        }
    }
}
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
RequestId Guid 36 Não Identificador do request definido pela loja
MerchantOrderId Texto 50 Sim Número do pedido da loja
Customer.Name Texto 120 Sim Nome completo do comprador
Customer.Identity Texto 16 Sim Número do documento de identificação do comprador
Customer.IdentityType Texto 255 Não Tipo de documento de identificação do comprador
Possíveis valores: CPF ou CNPJ
Customer.Email Texto 100 Sim E-mail do comprador
Customer.Birthdate Date 10 Sim Data de nascimento do comprador
Ex.: 1991-01-10
Customer.Phone Texto 15 Sim Número do telefone do comprador
Ex.: 5521976781114
Customer.BillingAddress.Street Texto 54 Sim Logradouro do endereço de cobrança
Customer.BillingAddress.Number Texto 5 Sim Número do endereço de cobrança
Customer.BillingAddress.Complement Texto 14 Não Complemento do endereço de cobrança
Customer.BillingAddress.ZipCode Texto 9 Sim Código postal do endereço de cobrança
Customer.BillingAddress.City Texto 50 Sim Cidade do endereço de cobrança
Customer.BillingAddress.State Texto 2 Sim Estado do endereço de cobrança
Customer.BillingAddress.Country Texto 2 Sim País do endereço de cobrança. Mais informações em ISO 2-Digit Alpha Country Code
Customer.BillingAddress.District Texto 45 Sim Bairro do endereço de cobrança
Customer.DeliveryAddress.Street Texto 54 Não Logradouro do endereço de entrega
Customer.DeliveryAddress.Number Texto 5 Não Número do endereço de entrega
Customer.DeliveryAddress.Complement Texto 14 Não Complemento do endereço de entrega
Customer.DeliveryAddress.ZipCode Texto 9 Não Código postal do endereço de entrega
Customer.DeliveryAddress.City Texto 50 Não Cidade do endereço de entrega
Customer.DeliveryAddress.State Texto 2 Não Estado do endereço de entrega
Customer.DeliveryAddress.Country Texto 2 Não País do endereço de entrega. Mais informações em ISO 2-Digit Alpha Country Code
Customer.DeliveryAddress.District Texto 45 Não Bairro do endereço de entrega
Payment.Provider Texto 15 Não Define comportamento do meio de pagamento (ver Anexo)
Obs.: Não obrigatório para Payment.Type igual a CreditCard
Payment.Type Texto 100 Sim Tipo do meio de pagamento.
Obs.: Somente o tipo CreditCard funciona com análise de fraude
Payment.Amount Número 15 Sim Valor da transação financeira em centavos
Ex: 150000 = r$ 1.500,00
Payment.Currency Texto 3 Não Moeda na qual o pagamento será feito
Possíveis valores: BRL / USD / MXN / COP / CLP / ARS / PEN / EUR / PYN / UYU / VEB / VEF / GBP
Payment.Country Texto 3 Não País na qual o pagamento será realizado
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.Installments Número 2 Sim Número de parcelas
Payment.Interest Texto 10 Não Tipo de parcelamento
Possíveis valores: ByMerchant (parcelado loja)
ByIssuer (parcelado emissor)
Payment.Capture Booleano — Não Indica se a autorização deverá ser com captura automática
Possíveis valores: true / false (default)
Payment.Authenticate Booleano — Não Indica se a transação deve ser autenticada junto ao emissor
Possíveis valores: true / false (default)
Payment.SoftDescriptor Texto 13 Não Texto que será impresso na fatura do portador
Obs.: O valor deste campo tem que ser claro e fácil de identificar pelo portador o estabelecimento onde foi realizada a compra, pois é um dos principais ofensores para chargeback
Payment.CreditCard.CardNumber Texto 16 Sim Número do cartão de crédito
Payment.CreditCard.Holder Texto 25 Sim Nome do portador impresso no cartão de crédito
Payment.CreditCard.ExpirationDate Texto 7 Sim Data de validade do cartão de crédito
Payment.CreditCard.SecurityCode Texto 4 Sim Código de segurança no verso do cartão de crédito
Payment.CreditCard.Brand Texto 10 Sim Bandeira do cartão de crédito
Payment.CreditCard.SaveCard Booleano — Não Booleano que identifica se o cartão será salvo para gerar o token (CardToken)
Possíveis valores: true / false (default)
Payment.FraudAnalysis.Sequence Texto 14 Sim Tipo de fluxo da análise de fraude
Possíveis valores: AnalyseFirst / AuthorizeFirst
Payment.FraudAnalysis.SequenceCriteria Texto 9 Sim Critério do fluxo da análise de fraude
Possíveis valores: OnSuccess / Always
Payment.FraudAnalysis.Provider Texto 10 Sim Provedor de AntiFraude
Possíveis valores: Cybersource
Payment.FraudAnalysis.CaptureOnLowRisk Booleano — Não Indica se a transação após a análise de fraude será capturada
Possíveis valores: true / false (default)
Obs.: Quando enviado igual a true e o retorno da análise de fraude for de baixo risco (Accept) a transação anteriormente autorizada será capturada
Obs2.: Quando enviado igual a true e o retorno da análise de fraude for revisão (Review) a transação ficará autorizada. A mesma será capturada após a Cielo receber o novo status da análise manual e este for de baixo risco (Accept)
Obs.: Para a utilização deste parâmetro, a sequência do fluxo de análise de risco deve ser obrigatoriamente AuthorizeFirst
Payment.FraudAnalysis.VoidOnHighRisk Booleano — Não Indica se a transação após a análise de fraude será cancelada
Possíveis valores: true / false (default)
Obs.: Quando enviado igual a true e o retorno da análise de fraude for de alto risco (Reject) a transação anteriormente autorizada será cancelada
Obs2.: Quando enviado igual a true e o retorno da análise de fraude for revisão (Review) a transação ficará autorizada. A mesma será cancelada após a Cielo receber o novo status da análise manual e este for alto risco (Reject)
Obs.: Para a utilização deste parâmetro, a sequência do fluxo de análise de risco deve ser obrigatoriamente AuthorizeFirst
Payment.FraudAnalysis.TotalOrderAmount Número 15 Sim Valor total do pedido em centavos
Ex: 123456 = r$ 1.234,56
Payment.FraudAnalysis.Browser.BrowserFingerprint Texto 100 Sim Identificador utilizado para cruzar informações obtidas do dispositivo do comprador. Este mesmo identificador deve ser utilizado para gerar o valor que será atribuído ao campo session_id do script ou utilizando os SDKs (iOS ou Android) que será incluído na página de checkout.
Obs.: Este identificador poderá ser qualquer valor ou o número do pedido, mas deverá ser único durante 48 horas
Payment.FraudAnalysis.Browser.CookiesAccepted Booleano — Sim Identifica se o browser do comprador aceita cookies
Possíveis valores: true / false (default)
Payment.FraudAnalysis.Browser.Email Texto 100 Não E-mail registrado no browser do comprador. Pode diferenciar do e-mail de cadastro na loja(Customer.Email)
Payment.FraudAnalysis.Browser.HostName Texto 60 Não Nome do host informado pelo browser do comprador e identificado através do cabeçalho HTTP
Payment.FraudAnalysis.Browser.IpAddress Texto 45 Sim Endereço de IP do comprador. Formato IPv4 ou IPv6
Payment.FraudAnalysis.Browser.Type Texto 40 Não Nome do browser utilizado pelo comprador e identificado através do cabeçalho HTTP
Ex.: Google Chrome, Mozilla Firefox, Safari, etc
Payment.FraudAnalysis.Cart.IsGift Booleano — Não Indica se o pedido realizado pelo comprador é para presente
Payment.FraudAnalysis.Cart.ReturnsAccepted Booleano — Não Indica se o pedido realizado pelo comprador pode ser devolvido a loja
Possíveis valores: true / false (default)
Payment.FraudAnalysis.Cart.Items.GiftCategory Texto 9 Não Identifica que avaliará os endereços de cobrança e entrega para diferentes cidades, estados ou países
Tabela 1 - Payment.Fraudanalysis.Cart.Items{n}.GiftCategory
Payment.FraudAnalysis.Cart.Items.HostHedge Texto 6 Não Nível de importância dos endereços de IP e e-mail do comprador na análise de fraude
Tabela 2 - Payment.Fraudanalysis.Cart.Items{n}.HostHedge
Payment.FraudAnalysis.Cart.Items.NonSensicalHedge Texto 6 Não Nível de importância das verificações sobre os dados do comprador sem sentido na análise de fraude
Tabela 3 - Cart.Items{n}.NonSensicalHedge
Payment.FraudAnalysis.Cart.Items.ObscenitiesHedge Texto 6 Não Nível de importância das verificações sobre os dados do comprador com obscenidade na análise de fraude
Tabela 4 - Payment.Fraudanalysis.Cart.Items{n}.ObscenitiesHedge
Payment.FraudAnalysis.Cart.Items.PhoneHedge Texto 6 Não Nível de importância das verificações sobre os números de telefones do comprador na análise de fraude
Tabela 5 - Payment.Fraudanalysis.Cart.Items{n}.PhoneHedge
Payment.FraudAnalysis.Cart.Items.Name Texto 255 Sim Nome do Produto
Payment.FraudAnalysis.Cart.Items.Quantity Número 15 Sim Quantidade do produto
Payment.FraudAnalysis.Cart.Items.Sku Texto 255 Sim SKU (Stock Keeping Unit - Unidade de Controle de Estoque) do produto
Payment.FraudAnalysis.Cart.Items.UnitPrice Número 15 Sim Preço unitário do produto
Ex: 10950 = r$ 109,50
Payment.FraudAnalysis.Cart.Items.Risk Texto 6 Não Nível de risco do produto associado a quantidade de chargebacks
Tabela 6 - Payment.Fraudanalysis.CartI.tems{n}.Risk
Payment.FraudAnalysis.Cart.Items.TimeHedge Texto 6 Não Nível de importância da hora do dia na análise de fraude que o comprador realizou o pedido
Tabela 7 - Payment.Fraudanalysis.Cart.Items{n}.TimeHedge
Payment.FraudAnalysis.Cart.Items.Type Texto 19 Não Categoria do produto
Tabela 8 - Payment.Fraudanalysis.Cart.Items{n}.Type
Payment.FraudAnalysis.Cart.Items.VelocityHedge Texto 6 Não Nível de importância da frequência de compra do comprador na análise de fraude dentros dos 15 minutos anteriores
Tabela 9 - Payment.Fraudanalysis.Cart.Items{n}.VelocityHedge
Payment.FraudAnalysis.MerchantDefinedFields.Id Número 2 Sim ID das informações adicionais a serem enviadas
Tabela 20 - Payment.FraudAnalysis.MerchantDefinedFields
Payment.FraudAnalysis.MerchantDefinedFields.Value Texto 255 Sim Valor das informações adicionais a serem enviadas
Tabela 20 - Payment.FraudAnalysis.MerchantDefinedFields
Payment.FraudAnalysis.Shipping.Addressee Texto 120 Não Nome completo do responsável a receber o produto no endereço de entrega
Payment.FraudAnalysis.Shipping.Method Texto 8 Não Meio de entrega do pedido
Tabela 10 - Payment.Fraudanalysis.Shipping.Method
Payment.FraudAnalysis.Shipping.Phone Texto 15 Não Número do telefone do responsável a receber o produto no endereço de entrega
Ex.: 552121114700
Payment.FraudAnalysis.Travel.JourneyType Texto 32 Não Tipo de viagem
Tabela 11 - Payment.FraudAnalysis.Travel.JourneyType
Payment.FraudAnalysis.Travel.DepartureTime DateTime — Não Data e hora de partida
Ex.: 2018-03-31 19:16:38
Payment.FraudAnalysis.Travel.Passengers.Name Texto 120 Não Nome completo do passageiro
Payment.FraudAnalysis.Travel.Passengers.Identity Texto 32 Não Número do documento do passageiro
Payment.FraudAnalysis.Travel.Passengers.Status Texto 15 Não Classificação da empresa aérea
Tabela 12 - Payment.FraudAnalysis.Travel.Passengers{n}.Status
Payment.FraudAnalysis.Travel.Passengers.Rating Texto 13 Não Tipo do passageiro
Tabela 13 - Payment.FraudAnalysis.Travel.Passengers{n}.Rating
Payment.FraudAnalysis.Travel.Passengers.Email Texto 255 Não E-mail do passageiro
Payment.FraudAnalysis.Travel.Passengers.Phone Texto 15 Não Telefone do passageiro
Ex.: 552121114700
Payment.FraudAnalysis.Travel.Passengers.TravelLegs.Origin Texto 3 Não Código do aeroporto de partida. Mais informações em IATA 3-Letter Codes
Payment.FraudAnalysis.Travel.Passengers.TravelLegs.Destination Texto 3 Não Código do aeroporto de chegada. Mais informações em IATA 3-Letter Codes

Resposta

{
    "MerchantOrderId":"2017051002",
    "Customer":{  
        "Name":"Nome do Comprador",
        "Identity":"12345678910",
        "IdentityType":"CPF",
        "Email":"comprador@provedor.com.br",
        "Birthdate":"1991-01-02",
        "Phone": "5521976781114",
        "BillingAddress":{  
            "Street":"Alameda Xingu",
            "Number":"512",
            "Complement":"27 andar",
            "ZipCode":"12345987",
            "City":"São Paulo",
            "State":"SP",
            "Country":"BR",
            "District":"Alphaville"
        },
        "DeliveryAddress":{  
            "Street":"Alameda Xingu",
            "Number":"512",
            "Complement":"27 andar",
            "ZipCode":"12345987",
            "City":"São Paulo",
            "State":"SP",
            "Country":"BR",
            "District":"Alphaville"
        }
    },
    "Payment": {
        "Type":"CreditCard",
        "Amount":10000,
        "Currency":"BRL",
        "Country":"BRA",
        "ServiceTaxAmount":0,
        "Installments":1,
        "Interest":"ByMerchant",
        "Capture":false,
        "Authenticate":false,
        "SoftDescriptor":"Mensagem",
        "CreditCard": {
            "CardNumber":"455187******0181",
            "Holder":"Nome do Portador",
            "ExpirationDate":"12/2021",
            "Brand": "Visa",
            "SaveCard": false
        },
        "FraudAnalysis": {
            "Provider":"Cybersource",
            "Sequence": "AuthorizeFirst",
            "SequenceCriteria": "OnSuccess",
            "CaptureOnLowRisk":false,
            "VoidOnHighRisk":false,
            "TotalOrderAmount":10000,
            "Browser":{  
                "BrowserFingerprint":"074c1ee676ed4998ab66491013c565e2",
                "CookiesAccepted":false,
                "Email":"comprador@test.com.br",
                "HostName":"Teste",
                "IpAddress":"127.0.0.1",
                "Type":"Chrome"
            },
            
            "Cart":{  
                "IsGift":false,
                "ReturnsAccepted":true,
                "Items":[  
                    {  
                        "GiftCategory":"Undefined",
                        "HostHedge":"Off",
                        "NonSensicalHedge":"Off",
                        "ObscenitiesHedge":"Off",
                        "PhoneHedge":"Off",
                        "Name":"ItemTeste1",
                        "Quantity":1,
                        "Sku":"20170511",
                        "UnitPrice":10000,
                        "Risk":"High",
                        "TimeHedge":"Normal",
                        "Type":"AdultContent",
                        "VelocityHedge":"High"
                    },
                    {  
                        "GiftCategory":"Undefined",
                        "HostHedge":"Off",
                        "NonSensicalHedge":"Off",
                        "ObscenitiesHedge":"Off",
                        "PhoneHedge":"Off",
                        "Name":"ItemTeste2",
                        "Quantity":1,
                        "Sku":"20170512",
                        "UnitPrice":10000,
                        "Risk":"High",
                        "TimeHedge":"Normal",
                        "Type":"AdultContent",
                        "VelocityHedge":"High"
                    }
                ]
            },
            "MerchantDefinedFields":[  
                {  
                    "Id":2,
                    "Value":"100"
                },
                {  
                    "Id":4,
                    "Value":"Web"
                },
                {  
                    "Id":9,
                    "Value":"SIM"
                }
            ],
            "Shipping":{  
                "Addressee":"João das Couves",
                "Method":"LowCost",
                "Phone":"551121840540"
            },
            "Travel":{  
                "JourneyType":"OneWayTrip",
                "DepartureTime":"2018-01-09 18:00",
                "Passengers":[  
                    {  
                        "Name":"Passenger Test",
                        "Identity":"212424808",
                        "Status":"Gold",
                        "Rating":"Adult",
                        "Email":"email@mail.com",
                        "Phone":"5564991681074",
                        "TravelLegs":[  
                            {  
                                "Origin":"AMS",
                                "Destination":"GIG"
                            }
                        ]
                    }
                ]
            },
            "Id": "0e4d0a3c-e424-4fa5-a573-4eabbd44da42",
            "Status": 1,
            "ReplyData": {
                "AddressInfoCode": "COR-BA^MM-BIN",
                "FactorCode": "B^D^R^Z",
                "Score": 42,
                "BinCountry": "us",
                "CardIssuer": "FIA CARD SERVICES, N.A.",
                "CardScheme": "VisaCredit",
                "HostSeverity": 1,
                "InternetInfoCode": "FREE-EM^RISK-EM",
                "IpRoutingMethod": "Undefined",
                "ScoreModelUsed": "default_lac",
                "CasePriority": 3
            }
        },
        "ProofOfSale": "492115",
        "Tid": "12345678902606D31001",
        "AuthorizationCode": "123456",
        "PaymentId": "04096cfb-3f0a-4ece-946c-3b7dc5d38f19",
        "ExtraDataCollection": [],
        "Status": 1,
        "ReturnCode": "4",
        "ReturnMessage": "Transação autorizada",
        "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
Payment.ProofOfSale Número do comprovante de venda na Cielo (NSU - Número sequencial único da transação) Texto 6
Payment.Tid Identificador da transação na Cielo Texto 20
Payment.AuthorizationCode Código de autorização na adquirente Texto 6
Payment.PaymentId Identificador da transação na API 3.0 Guid 36
Payment.FraudAnalysis.Id Id da transação no AntiFraude Guid 36
Payment.FraudAnalysis.Status Status da transação no AntiFraude
Tabela 14 - Payment.FraudAnalysis.Status		 Número -
Payment.FraudAnalysis.FraudAnalysisReasonCode Código de retorno da Cybersouce
Tabela 15 - Payment.FraudAnalysis.FraudAnalysisReasonCode		 Número -
Payment.FraudAnalysis.ReplyData.AddressInfoCode Códigos indicam incompatibilidades entre os endereços de cobrança e entrega do comprador
Os códigos são concatenados usando o caracter ^ Ex.: COR-BA^MM-BIN
Tabela 16 - Payment.FraudAnalysis.ReplyData.AddressInfoCode		 Texto 512
Payment.FraudAnalysis.ReplyData.FactorCode Códigos que afetaram a pontuação da análise
Os códigos são concatenados usando o caracter ^. Ex.: B^D^R^Z
Tabela 17 - ProviderAnalysisResult.AfsReply.FactorCode		 Texto 512
Payment.FraudAnalysis.ReplyData.Score Score da análise de fraude. Valor entre 0 e 100 Número -
Payment.FraudAnalysis.ReplyData.BinCountry Código do país do BIN do cartão usado na análise. Mais informações em ISO 2-Digit Alpha Country Code Texto 2
Payment.FraudAnalysis.ReplyData.CardIssuer Nome do banco ou entidade emissora do cartão de crédito Texto 256
Payment.FraudAnalysis.ReplyData.CardScheme Bandeira do cartão Texto 128
Payment.FraudAnalysis.ReplyData.HostSeverity Nível de risco do domínio de e-mail do comprador, de 0 a 5, onde 0 é risco indeterminado e 5 representa o risco mais alto Número -
Payment.FraudAnalysis.ReplyData.InternetInfoCode Códigos que indicam problemas com o endereço de e-mail, o endereço IP ou o endereço de cobrança
Os códigos são concatenados usando o caracter ^. Ex.: FREE-EM^RISK-EM
Tabela 18 - Payment.FraudAnalysis.ReplyData.InternetInfoCode		 Texto 512
Payment.FraudAnalysis.ReplyData.IpRoutingMethod Método de roteamento do comprador obtido a partir do endereço de IP
Tabela 19 - Payment.FraudAnalysis.ReplyData.IpRoutingMethod		 Texto 512
Payment.FraudAnalysis.ReplyData.ScoreModelUsed Nome do modelo de score utilizado na análise. Caso não tenha nenhum modelo definido, o modelo padrão da Cybersource foi o utilizado Texto 256
Payment.FraudAnalysis.ReplyData.CasePriority Define o nível de prioridade das regras ou perfis do lojista. O nível de prioridade varia de 1 (maior) a 5 (menor) e o valor padrão é 3, e este será atribuído caso não tenha definido a prioridade das regras ou perfis. Este campo somente será retornado se a loja for assinante do Enhanced Case Management Número -
Payment.FraudAnalysis.ReplyData.ProviderTransactionId Id da transação na Cybersource Texto 64

Tabelas

Tabela 1 - Payment.FraudAnalysis.Cart.Items[n].GiftCategory

Valor Descrição
Yes Em caso de divergência entre endereços de cobrança e entrega, atribui risco baixo ao pedido
No Em caso de divergência entre endereços de cobrança e entrega, atribui risco alto ao pedido (default)
Off Diferenças entre os endereços de cobrança e entrega não afetam a pontuação

Tabela 2 - Payment.FraudAnalysis.Cart.Items[n].HostHedge

Valor Descrição
Low Baixa
Normal Normal (default)
High Alta
Off Não irá afetar o score da análise de fraude

Tabela 3 - Payment.FraudAnalysis.Cart.Items[n].NonSensicalHedge

Valor Descrição
Low Baixa
Normal Normal (default)
High Alta
Off Não irá afetar o score da análise de fraude

Tabela 4 - Payment.FraudAnalysis.Cart.Items[n].ObscenitiesHedge

Valor Descrição
Low Baixa
Normal Normal (default)
High Alta
Off Não irá afetar o score da análise de fraude

Tabela 5 - Payment.FraudAnalysis.Cart.Items[n].PhoneHedge

Valor Descrição
Low Baixa
Normal Normal (default)
High Alta
Off Não irá afetar o score da análise de fraude

Tabela 7 - Payment.FraudAnalysis.Cart.Items[n].TimeHedge

Valor Descrição
Low Baixa
Normal Normal (default)
High Alta
Off Não irá afetar o score da análise de fraude

Tabela 8 - Payment.FraudAnalysis.Cart.Items[n].Type

Valor Descrição
AdultContent Conteúdo adulto
Coupon Cupom aplicado para todo o pedido
Default Valor default para o tipo do produto. Quando não enviado nenhum outro valor, assume-se o tipo sendo este
EletronicGood Produto eletônico diferente de software
EletronicSoftware Softwares distribuídos eletronicamente via download
GiftCertificate Vale presente
HandlingOnly Taxa que você cobra do seu cliente para cobrir os seus custos administrativos de venda. Ex.: Taxa de conveniência / Taxa de instalação
Service Serviço que será realizado para o cliente
ShippingAndHandling Valor do frete e e taxa que você cobra do seu cliente para cobrir os seus custos administrativos de venda
ShippingOnly Valor do frete
Subscription Assinatura. Ex.: Streaming de vídeos / Assinatura de notícias

Tabela 9 - Payment.FraudAnalysis.Cart.Items[n].VelocityHedge

Valor Descrição
Low Baixa
Normal Normal (default)
High Alta
Off Não irá afetar o score da análise de fraude

Tabela 10 - Payment.FraudAnalysis.Shipping.Method

Valor Descrição
SameDay Meio de entrega no mesmo dia
OneDay Meio de entrega no próximo dia
TwoDay Meio de entrega em dois dias
ThreeDay Meio de entrega em três dias
LowCost Meio de entrega de baixo custo
Pickup Retirada na loja
Other Outro meio de entrega
None Sem meio de entrega, pois é um serviço ou assinatura

Tabela 11 - Payment.FraudAnalysis.Travel.JourneyType

Valor Descrição
OneWayTrip Viagem somente de ida
RoundTrip Viagem de ida e volta

Tabela 12 - Payment.FraudAnalysis.Travel.Passengers[n].Status

Valor
Standard
Gold
Platinum

Tabela 13 - Payment.FraudAnalysis.Travel.Passengers[n].Rating

Valor Descrição
Adult Adulto
Child Criança
Infant Infantil

Tabela 14 - Payment.FraudAnalysis.Status

Código Descrição
0 Unknown
1 Accept
2 Reject
3 Review
4 Aborted
5 Unfinished

Tabela 15 - Payment.FraudAnalysis.FraudAnalysisReasonCode

Valor Descrição
100 Operação realizada com sucesso
101 A transação enviada para análise de fraude está faltando um ou mais campos necessários
Verificar no response o campo ProviderAnalysisResult.Missing
Possível ação: Reenviar a transação com a informação completa
102 A transação enviada para análise de fraude possui um ou mais campos com valores inválidos
Verificar no response o campo ProviderAnalysisResult.Invalid
Possível ação: Reenviar a transação com a informação correta
150 Erro interno
Possível ação: Aguarde alguns minutos e tente reenviar a transação
151 A transação foi recebida, mas ocorreu time-out no servidor. Este erro não inclui time-out entre o cliente e o servidor
Possível ação: Aguarde alguns minutos e tente reenviar a transação
152 O pedido foi recebido, mas ocorreu time-out
Possível ação: Aguarde alguns minutos e tente reenviar a transação
202 Transação recusada pois o cartão expirou ou a data de validade não coincide com a correta
Possível ação: Solicite outro cartão ou outra forma de pagamento
231 Transação recusada pois o cartão é inválido
Possível ação: Solicite outro cartão ou outra forma de pagamento
234 Problema com a configuração da loja na Cybersource
Possível ação: Entre em contato com o suporte para corrigir o problema de configuração
400 A pontuação de fraude ultrapassa o seu limite
Possível ação: Reveja a transação do comprador
480 A transação foi marcada como revisão pelo DM (Decision Manager)
481 A transação foi rejeitada pelo DM (Decision Manager)

Tabela 16 - Payment.FraudAnalysis.ReplyData.AddressInfoCode

Valor Descrição
COR-BA O endereço de cobrança pode ser normalizado
COR-SA O endereço de entrega pode ser normalizado
INTL-BA O país do endereço de cobrança está fora dos EUA
INTL-SA O país do endereço de entrega está fora dos EUA
MIL-USA Endereço militar nos EUA
MM-A Os endereços de cobrança e entrega usam nomes de ruas diferentes
MM-BIN O BIN do cartão (os seis primeiros dígitos do número do cartão) não corresponde ao país
MM-C Os endereços de cobrança e entrega usam cidades diferentes
MM-CO Os endereços de cobrança e entrega usam países diferentes
MM-ST Os endereços de cobrança e entrega usam estados diferentes
MM-Z Os endereços de cobrança e entrega usam códidos postais diferentes
UNV-ADDR O endereço é inverificável

Tabela 17 - Payment.FraudAnalysis.ReplyData.FactorCode

Valor Descrição
A Mudança de endereço excessiva. O comprador mudou o endereço de cobrança duas ou mais vezes nos últimos seis meses
B BIN do cartão ou autorização de risco. Os fatores de risco estão relacionados com BIN de cartão de crédito e/ou verificações de autorização do cartão
C Elevado números de cartões de créditos. O comprador tem usado mais de seis números de cartões de créditos nos últimos seis meses
D Impacto do endereço de e-mail. O comprador usa um provedor de e-mail gratuito ou o endereço de email é arriscado
E Lista positiva. O comprador está na sua lista positiva
F Lista negativa. O número da conta, endereço, endereço de e-mail ou endereço IP para este fim aparece sua lista negativa
G Inconsistências de geolocalização. O domínio do comprador de e-mail, número de telefone, endereço de cobrança, endereço de envio ou endereço IP é suspeito
H Excessivas mudanças de nome. O comprador mudou o nome duas ou mais vezes nos últimos seis meses
I Inconsistências de internet. O endereço IP e de domínio de e-mail não são consistentes com o endereço de cobrança
N Entrada sem sentido. O nome do comprador e os campos de endereço contém palavras sem sentido ou idioma
O Obscenidades. Dados do comprador contém palavras obscenas
P Identidade morphing. Vários valores de um elemento de identidade estão ligados a um valor de um elemento de identidade diferentes. Por exemplo, vários números de telefones estão ligados a um número de conta única
Q Inconsistências do telefone. O número de telefone do comprador é suspeito
R Ordem arriscada. A transação, o comprador e o lojista mostram informações correlacionadas de alto risco
T Cobertura Time. O comprador está a tentar uma compra fora do horário esperado
U Endereço não verificável. O endereço de cobrança ou de entrega não pode ser verificado
V O cartão foi usado muitas vezes nos últimos 15 minutos
W Marcado como suspeito. O endereço de cobrança ou de entrega é semelhante a um endereço previamente marcado como suspeito
Y O endereço, cidade, estado ou país dos endereços de cobrança e entrega não se correlacionam
Z Valor inválido. Como a solicitação contém um valor inesperado, um valor padrão foi substituído. Embora a transação ainda possa ser processada, examinar o pedido com cuidado para detectar anomalias

Tabela 18 - Payment.FraudAnalysis.ReplyData.InternetInfoCode

Valor Descrição
FREE-EM O endereço de e-mail do comprador é de um provedor de e-mail gratuito
INTL-IPCO O país do endereço de e-mail do comprador está fora dos EUA
INV-EM O endereço de e-mail do comprador é inválido
MM-EMBCO O domínio do endereço de e-mail do comprador não é consistente com o país do endereço de cobrança
MM-IPBC O endereço de e-mail do comprador não é consistente com a cidade do endereço de cobrança
MM-IPBCO O endereço de e-mail do comprador não é consistente com o país do endereço de cobrança
MM-IPBST O endereço IP do comprador não é consistente com o estado no endereço de cobrança. No entanto, este código de informação não pode ser devolvido quando a inconsistência é entre estados imediatamente adjacentes
MM-IPEM O endereço de e-mail do comprador não é consistente com o endereço IP
RISK-EM O domínio do e-mail do comprador (por exemplo, mail.example.com) está associado com alto risco
UNV-NID O endereço IP do comprador é de um proxy anônimo. Estas entidades escondem completamente informações sobre o endereço de IP
UNV-RISK O endereço IP é de origem de risco
UNV-EMBCO O país do endereço de e-mail não corresponde ao país do endereço de cobrança

Tabela 19 - Payment.FraudAnalysis.ReplyData.IpRoutingMethod

Valor Descrição
Anonymizer Endereços de IP estão escondidos porque o comprador é extremamente cauteloso, quer privacidade absoluta ou é fraudulento
AOL, AOL dialup, AOL POP and AOL proxy Membros da AOL. Na maioria dos casos, o país pode ser identificado, mas o estado e cidade não podem
Cache proxy Proxy usado através de um acelerador da Internet ou de uma distribuição de conteúdo de serviço. O comprador pode estar localizado em um país diferente do indicado pelo endereço de IP
Fixed O endereço de IP está próximo ou no mesmo local que o comprador
International proxy Proxy que contém tráfego de vários países. O comprador pode estar localizado em um país diferente do indicado pelo endereço de IP. Em muitos casos, redes corporativas estão roteando o tráfego de escritórios internacionais através de um ponto central, muitas vezes a sede corporativa
Mobile gateway Gateway para conectar dispositivos móveis à internet. Muitas operadoras, especialmente na Europa, atendem mais do que um país e tráfego ocorre através de hubs de rede centralizados. O comprador pode estar localizado em um país diferente do indicado pelo endereço de IP
POP Discagem do comprador em um ISP regional provavelmente perto da localização do endereço de IP, mas possivelmente através de limites geográficos
Regional proxy Proxy que contém tráfego de vários estados dentro de um único país. O comprador pode estar localizado em um estado diferente do indicado pelo endereço de IP. Em muitos casos, redes corporativas estão roteando o tráfego de escritórios internacionais através de um ponto central, muitas vezes a sede corporativa
Satellite Conexões por satélite. Se o uplink e o downlink estiverem cadastrados, o método roteamento é considerado padrão porque o remetente é conhecido. No entanto, se o downlink não está registrado, o comprador pode estar em qualquer lugar dentro do feixe padrão do satélite, que pode abranger um continente ou mais
SuperPOP O comprador está discando em um ISP multi-estatal ou multinacional que provavelmente não é provável a localização do endereço de IP. O comprador pode estar discando através de limites geográficos
No value returned O tipo de roteamento é desconhecido

Tabela 20 - Payment.FraudAnalysis.MerchantDefinedFields

Nível de Relevância
1 - Relevante
2 - Muito Relevante
3 - Extremamente Relevante

Conforme nível de relevância dos campos e possibilidade de desenho da estratégia de risco de acordo com a necessidade do seu negócio, na validação das transações de testes os mesmos serão cobrados caso não sejam enviaos. Com isso, solicitamos uma análise prévia da documentação e sinalização dos campos que não serão possíveis de serem enviados.

No caso de não possuir o dado para enviar, pedimos a gentileza de não enviar o campo correspondente como vazio, ou seja, apenas não enviar.

ID Valor Tipo Nível de Relevância Segmento
1 Cliente efetuou Login
Se o cliente final logou no site para comprar, enviar: o login dele
Se fez compra como visitante, enviar: Guest
Se a venda foi feita direto por um terceiro, um agente por exemplo, não enviar o campo		 Texto 2 Todos
2 Quantidade em dias que o cliente é seu cliente
Ex.: 314		 int 3 Todos
3 Quantidade de parcelas do pedido int 3 Todos
4 Canal de Venda
Possíveis valores:
Call Center -> compra pelo telefone
Web -> compra pela web
Portal -> um agente fazendo a compra para o cliente
Quiosque -> compras em quiosques
Movel -> compras feitas em celulares ou tablets		 string 3 Todos
5 Enviar o código do cupom/desconto caso o cliente utilize na compra Texto 1 Todos
6 Quantidade em dias desde a última compra realizada pelo cliente
Ex.: 55		 int 3 Todos
7 Código ou nome do seller (vendedor) Texto 1 Todos
8 Tentativas realizadas pelo cliente de efetuar o pagamento do mesmo pedido, podendo ser com diferentes cartões de créditos e/ou através de outros meios de pagamentos int 2 Todos
9 Identifica se cliente irá retirar o produto na loja
Possíveis valores: SIM ou NAO		 Texto 3 Varejo ou Cosméticos
10 Identifica se o pagamento será realizado por outra pessoa que não esteja presente na viagem ou pacote
Possíveis valores: SIM ou NAO		 Texto 3 Aéreo ou Turismo
11 Categoria do hotel (quantas estrelas)
Possíveis valores:
1 -> Simples
2 -> Econômico
3 -> Turismo
4 -> Superior
5 -> Luxo		 int 3 Turismo
12 Quantidade em dias desde a data da compra até a data do checkin no hotel
Ex.: 123		 int 3 Turismo
13 Quantidade de diárias no hotel
Ex.: 5		 int 3 Turismo
14 Categoria da viagem ou pacote
Possíveis valores: Nacional ou Internacional ou Nacional/Internacional		 Texto 3 Aéreo ou Turismo
15 Nome da companhia áerea / locadora de carro / hotel
Enviar o nome de cada uma das empresas, separado por /		 Texto 2 Aéreo ou Turismo
16 Código PNR da reserva
Quando houver uma alteração da reserva para este PNR, com antecipação da data de voo, é importante fazer uma nova análise de fraude enviando este PNR novamente		 Texto 3 Aérea
17 Identifica se houve antecipação de reserva
Possíveis valores: SIM ou NAO
Se sim, fundamental o envio também do campo 16 - Código PNR da reserva		 Texto 3 Aéreo
18 Categoria do veículo alugado
Possíveis valores:
1 - Básico
2 - Esportivo
3 - Prime
4 - Utilitário
5 - Blindado		 Texto 3 Turismo
19 Identifica se o pacote refere-se a cruzeiro
Possíveis valores: SIM ou NAO		 Texto 2 Turismo
20 Decisão da análise de fraude referente a última compra
Possíveis valores: ACEITA ou REJEITADA		 Texto 3 Todos
21 Valor do frete
Ex.: 10599 = r$ 105,99		 long 1 Varejo ou Cosméticos
22 Código da loja onde o produto será retirado
Este campo deverá ser enviado quando o campo 9 for enviado igual a SIM		 Texto 3 Varejo ou Cosméticos
23 Sufixo (4 últimos dígitos) do cartão de crédito int 1 Todos
24 Quantidade de dias desde a primeira compra realizada pelo cliente
Ex.: 150		 int 3 Todos
25 Sexo do cliente
Possíveis valores:
F -> Feminino
M -> Masculino		 Texto 2 Todos
26 Bin (6 primeiros dígitos) do cartão de crédito int 1 Todos
27 Tipo do logradouro do endereço de entrega
Possíveis valores:
R -> Residencial
C -> Comercial		 Texto 2 Todos
28 Tempo médio em minutos que o cliente levou para realizar a compra int 2 Todos
29 Quantidade de tentativas que o cliente realizou para efetuar login int 2 Todos
30 Quantidade de páginas web que o cliente visitou anteriormente a compra referente a 30 minutos passados int 2 Todos
31 Quantidade de trocas de números de cartão de crédito que o cliente efetuou para realizar o pagamento do pedido int 2 Todos
32 Identifica se o e-mail foi colado ou digitado
Possíveis valores: Digitado ou Colado		 Texto 3 Todos
33 Identifica se o número do cartão de crédito foi colado ou digitado
Possíveis valores: Digitado ou Colado		 Texto 3 Todos
34 Identifica se o e-mail foi confirmado para ativação de conta
Possíveis valores: SIM ou NAO		 Texto 2 Todos
35 Identifica o tipo de cliente
Possíveis valores: Local ou Turista		 Texto 2 Turismo
36 Identifica se foi utilizado cartão presente (GiftCard) na compra como forma de pagamento
Possíveis valores: SIM ou NAO		 Texto 1 Todos
37 Meio de envio do pedido
Possíveis valores: Sedex
Sedex 10
1 Dia
2 Dias
Motoboy
Mesmo Dia
Texto 3 Varejo ou Cosméticos
38 Número do telefone do cliente identificado através da bina quando venda realizada através do canal de venda igual a Call Center
Formato: DDIDDDNúmero - Ex.: 552121114720		 Texto 3 Todos
39 Nome de usuário do Call Center
Este campo deverá ser enviado quando campo 4 for enviado igual a Call Center		 Texto 1 Todos
40 Comentários inseridos quando pedido for presente Texto 1 Todos
41 Tipo do documento
Possíveis valores: CPF ou CNPJ ou Passaporte		 Texto 2 Todos
42 Idade do cliente int 2 Todos
43 Faixa de rendimento do cliente
Ex.: 100000 = r$ 1.000,00		 long 2 Todos
44 Quantidade histórica de compras realizadas pelo cliente int 3 Todos
45 Identifica se é uma compra realizada por funcionário
Possíveis valores: SIM ou NAO		 Texto 2 Todos
46 Nome impresso (portador) no cartão de crédito Texto 3 Todos
47 Identifica se o cartão é private label
Possíveis valores: SIM ou NAO		 Texto 2 Todos
48 Quantidade de meios de pagamentos utilizados para efetuar a compra int 2 Todos
49 Média das compras realizadas nos últimos 6 meses
Ex.: 159050 = r$ 1.590,99		 long 3 Todos
50 Fator de desvio de valor da compra atual sobre a média dos últimos 6 meses 3 Todos  
51 Identifica se é um cliente VIP com tratamento de risco diferenciado ou lista positiva
Possíveis valores: SIM ou NAO		 Texto 3 Todos
52 Categoria do produto
Possíveis valores:
Animais e Bichos de Estimação
Roupas e Acessórios
Negócios e Indústria
Câmeras e Óticas
Eletrônicos
Comidas, Bebidas e Cigarro
Móveis
Ferramentas
Saúde e Beleza
Casa e Jardim
Malas e Bagagens
Adulto
Armas e Munição
Materiais de Escritório
Religião e Cerimoniais
Software
Equipamentos de Esporte
Brinquedos e Jogos
Veículos e Peças
Livros
DVDs e Vídeos
Revistas e Jornais
Música
Outras Categorias Não Especificadas		 Texto 2 Todos
53 Identifica se existe rotina de confirmação de celular por SMS
Possíveis valores: SIM ou NAO		 Texto 2 Todos
54 Qual a 2ª forma de pagamento Texto 2 Todos
55 Qual a 3ª forma de pagamento Texto 2 Todos
56 Se 2ª forma de pagamento for cartão de crédito, enviar a bandeira Texto 1 Todos
57 Se 3ª forma de pagamento for cartão de crédito, enviar a bandeira Texto 1 Todos
58 Se 2ª forma de pagamento, informar o valor pago
Ex.: 128599 = r$ 1.285,99		 long 2 Todos
59 Se 3ª forma de pagamento, informar o valor pago
Ex.: 59089 = r$ 590,89		 long 2 Todos
60 Quantidade em dias desde a data da última alteração
Ex.: 57		 int 3 Todos
61 Identifica se houve alteração cadastral Texto 1 Todos
62 Quantidade de pontos trocados na última compra long 3 Fidelidade
63 Quantidade de pontos restantes no saldo long 2 Fidelidade
64 Quantidade de dias desde a última troca de pontos long 2 Fidelidade
65 Identificador do cliente no programa de fidelidade Texto 2 Fidelidade
66 Quantidade de minutos recarregados nos últimos 30 dias long 2 Digital Goods
67 Quantidade de recargas realizadas nos últimos 30 dias long 2 Digital Goods
68 Quantidade em dias entre a data de partida e a data de retorno int 2 Aéreo
69 Quantidade de passageiros viajando independente da faixa etária int 2 Aéreo
70 Identificador do voô Texto 1 Aéreo
71 Número de infants viajando int 2 Aéreo
72 Número de crianças viajando int 2 Aéreo
73 Número de adultos viajando int 2 Aéreo
74 Identifica se é um passageiro frequente (Frequently Flyer)
Possíveis valores: SIM ou NAO		 Texto 2 Aéreo
75 Identificar do passageiro frequente (Frequently Flyer Number) Texto 2 Aéreo
76 Categoria do passageiro frequente (Frequently Flyer)
Esta categoria pode variar de acordo com a companhia aérea		 int 2 Aéreo
77 Dia da semana do embarque
Possíveis valores: Sunday (Domingo)
Monday (Segunda-feira)
Tuesday (Terça-feira)
Wednesday (Quarta-feira)
Thursday (Quinta-feira)
Friday (Sexta-feira)
Saturday (Sábado)		 Texto 2 Aéreo
78 Código da companhia aérea
Ex.: JJ ou LA ou AA ou UA ou G3 e etc		 Texto 1 Aéreo
79 Classe tarifária da passagem
Ex.: W ou Y ou N e etc		 Texto 2 Aéreo
80 Número do celular do passageiro
Ex.: Formato: DDIDDDNúmero - Ex.: 5521976781114		 Texto 2 Aéreo
81 Identifica se o dono do cartão de crédito irá viajar
Possíveis valores: SIM ou NAO		 Texto 3 Aéreo
82 Identifica se o seller (vendedor) irá trabalhar com revisão manual ou não
Possíveis valores: SIM ou NAO		 Texto 1 Todos
83 Segmento de negócio
Ex.: Varejo		 Texto 2 Todos
84 Nome da plataforma integrada a API 3.0
Caso seja uma integração direta entre a loja e Cielo, enviar valor igual a PROPRIA		 Texto 3 Todos
85 a 89 Campos livres e definidos junto ao provedor de AntiFraude, conforme as regras de negócio - - -
90 a 100 Reservados - - -

Configuração do Fingerprint

Importante componente da análise de fraude, o Fingerprint é um Javascript que deve ser inserido no seu site para capturar dados importantes como: IP do comprador, versão do browser, sistema operacional etc. Muitas vezes, somente os dados do carrinho não são suficientes para garantir uma análise assertiva. Os dados coletados pelo Fingerprint complementam a análise e garantem que sua loja está mais protegida.

Esta página descreve como funciona e como configurar o fingerprint em sua página de checkout e mobiles.

Integração em checkout

Será necessário adicionar duas tags, a script dentro da tag head para uma performance correta e a noscript dentro da tag body, para que a coleta dos dados do dispositivo seja realizada mesmo se o Javascript do browser estiver desabilitado.

Variáveis Existem duas variáveis a serem preenchidas na URL do Javascript. O org_id e o session_id. O org_id é um valor predefinido conforme tabela abaixo, já o session_id é composto pela concatenação dos parâmetros ProviderMerchantId e Payment.FraudAnalysis.Browser.BrowserFingerprint, conforme exemplo abaixo:

Variável Descrição SuperMID Advanced ou Enterprise
org_id para Sandbox = 1snn5n9w
para Produção = k8vif92e		 - -
session_id SuperMID, utilizar o valaor padrão cielo_webservice
Advanced ou Enterprise, solicitar junto a Cielo
ProviderMerchantId = Identificador da sua loja na Cybersource (Caso não tenha uma ID próprio, use cielo_webservice)
Payment.FraudAnalysis.Browser.BrowserFingerprint = Identificador utilizado para cruzar informações obtidas do dispositivo do comprador.
Obs.: Este identificador poderá ser qualquer valor ou o número do pedido, mas deverá ser único durante 48 horas.		    

Aplicação

O modelo do Javascript é o seguinte:

Exemplo Código

As variáveis, quando devidamente preenchidas, forneceriam uma URL semelhante ao exemplo abaixo:

Exemplo Url

Integração em aplicativos mobile

Solicite junto ao chamado de integração os SDKs (iOS e Android) e os manuais.

Velocity

O Que É Velocity

O Velocity é um tipo de mecanismo de prevenção à tentativas de fraude, que analisa especificamente o conceito de “velocidade X dados transacionais”. Ela analisa a frequência que determinados dados são utilizados e se esse dados estão inscritos em uma lista de comportamentos passiveis de ações de segurança.

Para estabelecimentos comerciais que atuam no mercado de comércio eletrônico e eventualmente recebem transações fraudulentas, o Velocity é um produto que identificará os comportamentos suspeitos de fraude. A ferramenta tem o intuito de auxiliar na análise de fraude por um custo bem menor que uma ferramenta mais tradicional de mercado.

Ela é uma aliada na avaliação de comportamentos suspeitos de compra, pois os cálculos serão baseados em elementos de rastreabilidade.

O Velocity oferece 4 tipos de funcionalidades para validar dados transacionais:

Funcionalidade Descrição
Regras de segurança velocity O Lojista defini um grupo de regras de segurança que vão avaliar se determinados dados transacionais se repetem em um intervalo de tempo suspeito
Quarentena Criação de uma lista de dados que serão analisados por um periodo de tempo determinado antes de serem considerados validos ou fraudulentos
BlackList Criação de uma lista de dados que ao serem identificados impedem a transação de ser executada, evitando a criação de uma transação fraudulenta
Whitelist Criação de uma lista de dados que ao serem identificados permitem que a transação de seja executada, mesmo que existam regras de segurança em ação

A funcionalidade deve ser contratada à parte, e posteriormente habilitada em sua loja pela equipe de Suporte Cielo Ecommerce via o Admin 3.0

Integração

O Velocity funciona analisando dados enviados na integração padrão da API Cielo Ecommerce. Não é necessario incluir nenhuma nó adicional a integração da loja para a criação da venda, mas será necessario alterar a forma como os dados são recebidos Response.

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

Recorrência

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

São pagamentos normalmente encontrados em assinaturas, onde 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 Cielo Ecommerce funciona com dois tipos de Recorrencia que possuem comportamentos diferentes.

Recorrência Própria

Nesse modelo, o lojista é responsavel por criar a inteligência necessaria 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

Em todas as instancias, a recorrencia programada é uma transação padrão para a Cielo, sendo sua unica diferença a necessidade de enviar um a parametro adicional que a define como Recorrência Própria

Paramêtro: Payment.Recurrent= True

Caso de Uso

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

A recorrência própria é uma configuração da API Cielo Ecommerce que permite um lojista utilizar um sistema de recorrência interno especifico as suas necessidades de negócio. Nesse modelo, o sistema do lojista é encarregado por definir o período, os dados transacionais, e quando necessário, nos enviar a venda de recorrência.

Veja um exemplo em uso:

A academia CleverFit possui um sistema de cobrança diferenciado, onde a matricula é 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 Cielo Ecommerce 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 mantem os cartões salvos via a tokenização, diminuindo o risco de assegurar os dados transacionais em seu sistema.

A CleverFit envia a transação quinzenalmente a API Cielo Ecommerce, 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 a seu modelo de cobrança

Recorrência Programada

Nesse modelo, a Cielo é responsavel pela inteligência necessaria para executar uma recorrência de maneira automatica.

A Recorrência Programada permite que o lojista crie uma transação base, que ao ser enviada para a API Cielo Ecommerce, será salva e executada seguindo as regras definidas pelo lojista.

Nesse modelo, a API realiza e permite:

Vantagens Descrição
Salva dados transacionais Salva dados da transação, criando assim um modelo de como serão as proximas Recorrências
Automatiza a recorrência Sem atuação da loja, a API cria as transações futuras de acordo com as definições do lojista
Permite atualização de dados Caso necessario, a API permite modificações das informações da transação ou do ciclo de recorrência

A Recorrencia Programada é formada por uma estrutura transacional simples. O Lojista deverá informa na transação os seguintes dados:

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

Onde podemos definir os dados como:

Paramêtros Descrição
AuthorizeNow Define que qual o momento que uma recorrencia será criada. Se for enviado como True, ela é criada no momento da autorização, se False, a recorrencia ficará suspensaaté a data escolhida para ser iniciada.
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 pelo lojista
Interval Intervalo da recorrência.
Monthly - Mensal Bimonthly - Bimestral Quarterly - Trimestral SemiAnnual - Semestral Annual - Anual

Quando uma transação é enviada a API Cielo Ecommerce com o nó de Recorrência Programada, o processo de recorrencia passa a ser efetivo quando a transação é considerada AUTORIZADA.

Desse ponto em diante, ela passará a ocorre dentro do intervalo definido pelo lojista.

Caracteristicas 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 recorrencia 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 recorrencia são capturadas automaticamente pela API
Identificação Transações de Recorrência Programada geram dois tipos de identificação:
PAYMENTID: Identifica 1 transação. É o mesmo identificador das outras transações na API
RECURRENTPAYMENTID: Identifica Pedido de recorrencia. Um RecurrentPaymentID possui inumeros PaymentID vinculados a ela. Essa é a variavel usada para Cancelar uma Recorrencia Programada
Consultando 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 Recorrencia Programada pode ser cancelada de duas maneiras:
Lojista: Solicita o cancelamento da recorrencia. 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á invalido (EX: Expirado) a recorrência será cancelada e não se repetirá, até que o lojista 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

Fluxo de uma Recorrência Programada

Caso de uso

Este é um exemplo de como usar as recorrências da API Cielo Ecommerce para elevar suas vendas:

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

A recorrência programada cielo tem as seguintes características:

Veja um exemplo em uso:

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

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

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

A MusicFy utiliza a Recorrência programada da API Cielo Ecommerce.

Ao criar uma transação, o Musicfy informa que o pedido em questão deve ser repetir mensalmente ou anualmente e que não há data de termino 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: Não é necessário armazenar dados sensíveis do cartão e do comprador junto a loja.

  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é 4 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 propria loja, basta fazer um POST conforme o exemplo.

O paramêtro Payment.Recurrentdeve ser true, caso contrario, 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 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.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 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 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ê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

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.

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

Modificando Recorrências

Modificando dados do comprador

Para alterar os dados do comprador da Recorrência, basta fazer um Put conforme o exemplo.

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

Para alterar a data final da Recorrência, basta fazer um Put conforme o exemplo.

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

Para alterar o Intervalo da Recorrência, basta fazer um Put conforme o exemplo.

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

Para modificar o dia da recorrência, basta fazer um Put conforme o exemplo.

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

Para modificar o valor da recorrência, basta fazer um Put conforme o exemplo.

Requsição

156

curl
--request POST "https://apisandbox.cieloecommerce.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

Para alterar a data do próximo Pagamento, basta fazer um Put conforme o exemplo.

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

Para alterar os dados de pagamento da Recorrência, basta fazer um Put conforme o exemplo.

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

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

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 Facil

O uso desta funcionalidade permite a substituição automática de um cartão vencido . Dessa forma, quando uma transação com marcação de recorrente for submetida para a API e a Cielo identificar que o cartão utilizado foi substituído, sua autorização será negada e serão retornados os dados do novo cartão conforme exemplo.

Requisição

{  
   "MerchantOrderId":"2014113245231706",
   "Customer":{  
      "Name":"Comprador Renova facil"
   },
   "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 Renova facil"
   },
   "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 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
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  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á estão com o Renova Facil habilitados:

Emissores VISA MASTER ELO
BRADESCO Sim Sim Sim
BANCO DO BRASIL Sim — —
SANTADER Sim — —
CITI Sim — —
BANCO PAN Sim — —

Tokenização de cartões

O que é a Tokenização de Cartões:

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

Criando um Cartão Tokenizado

Para salvar um cartão sem autoriza-lo, basta realizar um posto 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 impresso 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, basta enviar uma requisição padrão de criação de venda, enviado SaveCard como “ true”. O response retornará o Token do cartão.

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",
         "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",
         "ExpirationDate":"12/2030",
         "SecurityCode":"123",
         "SaveCard":"true",
         "Brand":"Visa"
     }
   }
}
--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.
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 Pais 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.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.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.
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.
CreditCard.ExpirationDate Texto 7 Sim Data de validade impresso no cartão.
CreditCard.SecurityCode Texto 4 Não Código de segurança impresso no verso do cartão - Ver Anexo.
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 (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 - nao permite caracteres especiais Texto 13 Texto alfanumérico
PaymentId Campo Identificador do Pedido. 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

Tokenização de Bandeira

Clientes que fazem tokenização do cartão junto com as bandeiras poderão enviar as informações para a Cielo no fluxo transacional.

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
MerchantId Guid 36 Sim Identificador da loja na Cielo.
MerchantKey Texto 40 Sim Chave Publica para Autenticação Dupla na Cielo.
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 Pais 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.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.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.CreditCard.CardNumber Texto 19 Sim Número do Cartão do Comprador. 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 - nao permite caracteres especiais Texto 13 Texto alfanumérico
PaymentId Campo Identificador do Pedido. 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 com token do cartão protegido, é necessário fazer um POST para o recurso Payment conforme o exemplo.

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
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
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.ReturnUrl URI para onde o usuário será redirecionado após o fim do pagamento Texto 1024 Sim quando Authenticate = true
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 Campo Identificador do Pedido. 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 Campo Identificador do Pedido. 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

Consulta Bin

O “Consulta de Bins” é um serviço de pesquisa de dados do cartão, de crédito ou débito, que retorna ao lojista da API Cielo e-Commerce informações que permitem validar os dados preenchidos na tela do checkout. O serviço retorna os seguintes dados sobre o cartão:

Essas informações permitem tomar ações no momento do checkout para melhorar a conversão da loja.

Caso de Uso

Veja um exemplo de uso: Consulta Bins + recuperação de carrinho

Um marketplace chamada Submergível possui uma gama de meios de pagamento disponíveis para que suas lojas possam oferecer ao comprador, mas mesmo com toda essa oferta, ela continua com uma taxa de conversão baixa.

Conhecendo a função de consulta Bins da API Cielo Ecommerce, como ela poderia evitar a perda de carrinhos?

Ela pode aplicar a Consulta bins e 3 cenários!

  1. Impedir erros com tipo de cartão
  2. Oferecer recuperação de carrinhos online
  3. Alertar sobre cartões internacionais
  4. Impedir erros com tipo de cartão

O Submergível pode usar a consulta bins no carrinho para identificar 2 dos principais erros no preenchimento de formulários de pagamento:

Oferecer recuperação de carrinhos online

Alertar sobre cartões internacionais O Submergível pode usar a consulta bins no carrinho para alertar compradores internacionais, que caso o cartão não esteja habilitado para transacionar no Brasil, a transação será negada

Integração

Request

Basta realizar um GET enviado o BIN a nossa URL de consulta:

Campo Descrição
BIN 6 primeiros dígitos do cartão
Para simular uma consulta em SandBox com retorno ForeignCard=false, o terceiro dígito do BIN deve ser 1, e o quinto dígito deve ser diferente de 2 e 3.
Exemplos:001040, 501010, 401050		 
https://apiquerysandbox.cieloecommerce.cielo.com.br/1/cardBin/420020

Response

{
    "Status": "00",
    "Provider": "VISA",
    "CardType": "Crédito",
    "ForeignCard": true,
    "CorporateCard": true,
    "Issuer": "Bradesco",
    "IssuerCode": "237"
}
Paramêtro Tipo Tamanho Descrição
Status Texto 2 Status da requisição de análise de Bins:
00 – Analise 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

Atenção: Em SANDBOX os valores retornados são simulações e não validações reais de BINS. Deve ser considerado apenas o retorno do Request e o seu formato. Para identificação real dos BINS, o ambiente de Produção deverá ser utilizado.

Zero Auth

O Zero Auth é uma ferramenta de validação de cartões da API Cielo. A validação permite que o lojista saiba se o cartão é valido ou não antes de enviar a transação para autorização, antecipando o motivo de uma provável não autorização..

O Zero Auth pode ser usado de 2 maneiras:

  1. Padrão - Envio de um cartão padrão, sem tokenização ou analises adicionais
  2. Com cartão Tokenizado - Envio de um TOKEN 3.0 para analise

É importante destacar que o Zero Auth não retorna ou analisa os seguintes itens:

  1. Limite de crédito do cartão
  2. Informações sobre o portador
  3. Não aciona a base bancaria (dispara SMS so portador)

O Zero Auth suporta as seguintes bandeiras:

Caso outras bandeiras sejam enviadas, o erro 57-Bandeira inválida será exibido.

Caso de uso

Este é um exemplo de como usar o zero auth para melhorar sua conversão de vendas.

O Zero Auth é uma ferramenta da Cielo que permite verificar se um cartão está valido para realizar uma compra antes que o pedido seja finalizado. Ele faz isso simulando uma autorização, mas sem afetar o limite de crédito ou alertar o portados do cartão sobre o teste.

Ela não informa o limite ou características do cartão ou portador, mas simula uma autorização Cielo, validando dados como:

  1. Se o cartão está valido junto ao banco emissor
  2. Se o cartão possui limite disponível
  3. Se o cartão funciona no Brasil
  4. Se o número do cartão está correto
  5. Se o CVV é valido

O Zero Auth também funciona com Cartões tokenizados na Api Cielo Ecommerce

Veja um exemplo de uso:

Zero auth como validador de cartão

Uma empresa de Streaming chamada FlixNet possui um serviço via assinatura, onde além de realizar uma recorrência, ela possui cartões salvos e recebe novas inscrições diariamente. Todas essas etapas exigem que transações sejam realizadas para obter acesso a ferramenta, o que eleva o custo da FlixNet caso as transações não sejam autorizadas.

Como ela poderia reduzir esse custo? Validando o cartão antes de envia-lo a autorizado.

A FlixNet usa o Zero Auth em 2 momento diferente:

O problema é que ao se encerrar esse período, se o cartão for invalido, o novo cadastro existe, mas não funciona, pois, o cartão salvo é invalido. A Flix Net resolveu esse problema testando o cartão com o Zero Auth no momento do cadastro, assim, ela já sabe se o cartão está valido e libera a criação da conta. Caso não o cartão não seja aceito, a FlixNet pode sugerir o uso de um outro cartão.

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. O POST deverá ser realizado nas seguintes URL:

Cada tipo de validação necessita de um contrato tecnico diferente. Eles resultarão em responses diferenciados.

Requisição

PADRÃO

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

Abaixo, a listagem de campos da Requisição:

Paramêtro Descrição Tipo Tamanho Obrigatório
CardType Define o tipo de cartão utilizados:
CreditCard
DebitCard
Se não enviado, CreditCard como default		 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
 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

COM TOKEN

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

Abaixo, 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á valido a transacionar, mas não necessariamente indica que um determinado valor será autorizado.

Abaixo os campos retornados após a validação:

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 Identificado 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, onde não seja possível validar o cartão, o serviço irá retornar erro:

Silent Order Post

Integração que a Cielo oferece aos lojistas, onde os dados de pagamentos são trafegue de forma segura, mantendo o controle total sobre a experiência de Ckeckout.

Esse método possibilita o envio dos dados do pagamento do seu cliente final de forma segura diretamente em nosso sistema. Os campos de pagamento são guardados do lado da 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. Esse método permite um alto nível de personalização na sua página de checkout.

Características

Fluxo de Autorização

Fluxo Padrão de Autorização

Fluxo Padrão

É preciso que o estabelecimento seja PCI Compliance (PCI = Regras de segurança para manipular os dados do cartão)

Fluxo de Autorização com Silent Order POST

Fluxo Padrão

O servidor não trafega os dados do cartão abertamente.

Fluxo Transacional

Fluxo Silent Order Post

Integração

PASSO 1

O cliente acaba o checkout, e vai para o processamento do pagamento.

PASSO 2

a) O estabelecimento 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 será requerido do lado da Cielo, no mínimo um IP válido do estabelecimento. Caso contrário a requisição não será autorizada (HTTP 401 NotAuthorized).

PASSO 3

a) Como resposta, o estabelecimento 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 o estabelecimento salvar apenas 1 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á esse mesmo ticket para um uso futuro.

PASSO 4 ao 6

a) O estabelecimento deverá fazer o download de um script fornecido pela Cielo, e anexá-lo a sua página de checkout. Esse script permitirá à Cielo processar todas as informações de cartão sem intervenção do estabelecimento. O download poderá ser realizado a partir da seguinte URL:

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

b) O estabelecimento deverá decorar seus inputs do formulário com as seguintes classes:

c) O script fornecido pela Cielo fornece três eventos para manipulação e tratamento por parte do estabelecimento. São eles: onSuccess (onde será retornado o “PaymentToken” após processar os dados do cartão), onError (caso haja algum erro no consumo dos serviços da Cielo) e onInvalid (onde será retornado o resultado da validação dos inputs).

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

Por questões de segurança esse PaymentToken poderá ser usado apenas para 1 autorização na Cielo 3.0. Após o processamento do mesmo, este será invalidado.

Exemplo de setup a ser realizado pelo estabelecimento na página de checkout:

Pagina Checkout

Wallet

O que são Wallets

São repositorios de cartões e dados de pagamentos para consumidores online. As Carteiras digitais permitem que um consumidor realizar o cadastro de seus dados de pagamento, assim agilizando o processo de compra em lojas habilitadas em suas compras por possuir apenas um cadastro.

Para utilizar carteiras na API Cielo eCommerce, o lojista deverá possuir as carteiras integradas em seu checkout.

Para maiores informações, sugerimos que entre em contato com o setor tecnico da carteira a qual deseja implementar.

Wallets Disponiveis

A API Cielo Ecommerce possui integração com:

Carteira
Apple Pay
VisaCheckout
MasterPass
Samsung Pay
Google Pay

Integração base

As wallets na Api Cielo E-commerce possuem duas maneiras de utilização.

  1. Descriptografia - Quando o lojista envia os dados da wallet para que a API Cielo e-commerce realize o processamento do cartão
  2. Envio do cartão - Quando a loja busca o cartão, e o enviar por conta propria a API Cielo e-commerce para processamento

Componentes

Walletkey

O WalletKey é o identificador utilizado pela Cielo para descriptografar payloads retornados pela Wallet. Ele utilizado apenas em integrações no formado Descriptografia Cada Wallet possui um formato de WalletKeys.

Carteira Exemplo
VisaCheckout 1140814777695873901
Apple Pay 9zcCAciwoTS+qBx8jWb++64eHT2QZTWBs6qMVJ0GO+AqpcDVkxGPNpOR/D1bv5AZ62+5lKvucati0+eu7hdilwUYT3n5swkHuIzX2KO80Apx/SkhoVM5dqgyKrak5VD2/drcGh9xqEanWkyd7wl200sYj4QUMbeLhyaY7bCdnnpKDJgpOY6J883fX3TiHoZorb/QlEEOpvYcbcFYs3ELZ7QVtjxyrO2LmPsIkz2BgNm5f+JaJUSAOectahgLZnZR+sRXTDtqLOJQAprs0MNTkPzF95nXGKCCnPV2mfR7z8FHcP7AGqO7aTLBGJLgxFOnRKaFnYlY2E9uTPBbB5JjZywlLIWsPKur5G4m1/E9A6DwjMd0fDYnxjj0bQDfaZpBPeGGPFLu5YYn1IDc
Samsung Pay eyJhbGciOiJSU0ExXzUiLCJraWQiOiIvam1iMU9PL2hHdFRVSWxHNFpxY2VYclVEbmFOUFV1ZUR5M2FWeHBzYXVRPSIsInR5cCI6IkpPU0UiLCJjaGFubmVsU2VjdXJpdHlDb250ZXh0IjoiUlNBX1BLSSIsImVuYyI6IkExMjhHQ00ifQ.cCsGbqgFdzVb1jhXNR--gApzoXH-LldMArSoG59x6i0BbI7jttqxyAdcriSy8q_77VAp3854P9kekjj54RKLrP6APDIr46DI97kjG9E99ONXImnEyamHj95ZH_AW8lvkfa09KAr4537RM8GEXyZoys2vfIW8zqjjicZ8EKIpAixNlmrFJu6-Bo_utsmDN_DuGm69Kk2_nh6txa7ML9PCI59LFfOMniAf7ZwoZUBDCY7Oh8kx3wsZ0kxNBwfyLBCMEYzET0qcIYxePezQpkNcaZ4oogmdNSpYY-KbZGMcWpo1DKhWphDVp0lZcLxA6Q25K78e5AtarR5whN4HUAkurQ.CFjWpHkAVoLCG8q0.NcsTuauebemJXmos_mLMTyLhEHL-p5Wv6J88WkgzyjAt_DW7laiPMYw2sqRXkOiMJLwhifRzbSp8ZgJBM25IX05dKKSS4XfFjJQQjOBHw6PYtEF5pUDMLHML3jcddCrX07abfef_DuP41PqOQYsjwesLZ8XsRj-R0TH4diOZ_GQop8_oawjRIo9eJr9Wbtho0h8kAzHYpfuhamOPT718EaGAY6SSrR7t6nBkzGNkrKAmHkC7aRwe.AbZG53wRqgF0XRG3wUK_UQ

Observações: A Wallet MasterPass não possui WalletKey. O WalletKey Apple Pay pode ser obtido dentro do campo DATA do payload Apple

EphemeralPublicKey

O EphemeralPublicKey é a chave utilizado pela Cielo para descriptografar payloads contendo WalletKeys enviados pelos lojistas. É utilizado apenas em integrações no formado Descriptografia Cada Wallet possui um formato de EphemeralPublicKey.

Carteira Exemplo
Apple Pay MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEoedz1NqI6hs9hEO6dBsnn0X0xp5/DKj3gXirjEqxNIJ8JyhGxVB3ITd0E+6uG4W6Evt+kugG8gOhCBrdUU6JwQ==

VisaCheckout / MasterPass / SamsungPay não possuem EphemeralPublicKey

Descriptografia

Requisição

-- Descriptografia
{
  "MerchantOrderId": "2014111708",
  "Customer": {
    "Name": "Exemplo Wallet Padrão",
    "Identity": "11225468954",
    "IdentityType": "CPF"
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 100,
    "Installments": 1,
    "Currency": "BRL",
    "Wallet": {
      "Type": "TIPO DE WALLET",
      "WalletKey": "IDENTIFICADOR DA LOJA NA WALLET",
      "AdditionalData": {
        "EphemeralPublicKey": "TOKEN INFORMADO PELA WALLET"
      }
    }
  }
}
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.
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)
Payment.Type Texto 100 Sim Tipo do Meio de Pagamento.
Payment.Amount Número 15 Sim Valor do Pedido (ser enviado em centavos).
Payment.Installments Número 2 Sim Número de Parcelas.
CreditCard.CardNumber. Texto 19 Sim Número do Cartão do Comprador
CreditCard.SecurityCode Texto 4 Não Código de segurança impresso no verso do cartão - Ver Anexo.
CreditCard.Brand Texto 10 Sim Bandeira do cartão (Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard / Hiper).
Wallet.Type Texto 255 Sim indica qual o tipo de carteira: VisaCheckout/ Masterpass / SamsungPay
Wallet.Walletkey Texto 255 Sim Chave criptografica que identifica lojas nas Wallets - Ver tabela WalletKey para mais informações
Wallet.AdditionalData.EphemeralPublicKey Texto 255 Sim Chave retornada pela Wallet para descriptografia. Deve ser enviado em Integrações: ApplePay
Wallet.AdditionalData.capturecode Texto 255 Sim Código informado pela MasterPass ao lojista

Resposta

{
    "MerchantOrderId": "2014111703",
    "Customer": {
        "Name": "[Guest]"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": 0,
        "Capture": false,
        "Authenticate": false,
        "Recurrent": false,
        "CreditCard": {
            "CardNumber": "453211******1521",
            "Holder": "Leonardo Romano",
            "ExpirationDate": "08/2020",
            "SaveCard": false,
            "Brand": "Visa"
        },
        "Tid": "0319040817883",
        "ProofOfSale": "817883",
        "AuthorizationCode": "027795",
        "Wallet": {
            "Type": "TIPO DE WALLET",
            "WalletKey": "IDENTIFICADOR DA LOJA NA WALLET",
            "Eci": 0
            "AdditionalData": {
                "EphemeralPublicKey": "TOKEN INFORMADO PELA WALLET"
                              },                
                 },
        "SoftDescriptor": "123456789ABCD",
        "Amount": 100,
        "ReceivedDate": "2018-03-19 16:08:16",
        "Status": 1,
        "IsSplitted": false,
        "ReturnMessage": "Operation Successful",
        "ReturnCode": "4",
        "PaymentId": "e57b09eb-475b-44b6-ac71-01b9b82f2491",
        "Type": "CreditCard",
        "Currency": "BRL",
        "Country": "BRA",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491"
            },
            {
                "Method": "PUT",
                "Rel": "capture",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491/capture"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491/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 Campo Identificador do Pedido. 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
Type Indica qual o tipo de carteira: VisaCheckout/ Masterpass / ApplePay / SamsungPay Texto 255 Texto alfanumérico
Walletkey Chave criptografica que identifica lojas nas Wallets - Ver tabela WalletKey para mais informações Texto 255 Ver tabela WalletKey
AdditionalData.capturecode Código informado pela MasterPass ao lojista Texto 255 3
AdditionalData.EphemeralPublicKey Token retornado pela Wallet. Deve ser enviado em Integrações: ApplePay Texto 255 Ver Tabela EphemeralPublicKey

Envio de cartão

Requisição

-- Envio de cartão
{
  "MerchantOrderId": "6242-642-723",
  "Customer": {
    "Name": "Guilherme Gama",
    "Identity": "11225468954",
    "IdentityType": "CPF"
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 1100,
    "Provider": "Cielo",
    "Installments": 1,
    "CreditCard": {
      "CardNumber":"4532********6521",
      "Holder":"Guilherme Gama",
          "ExpirationDate":"12/2021",
          "SecurityCode":"123",
          "Brand":"Master"
    },
    "Wallet": {
      "Type": "Tipo de wallet",
      "Eci":"7",
      "Cavv":"AM1mbqehL24XAAa0J04CAoABFA=="
    }
  }
}
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.
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)
Payment.Type Texto 100 Sim Tipo do Meio de Pagamento.
Payment.Amount Número 15 Sim Valor do Pedido (ser enviado em centavos).
Payment.Installments Número 2 Sim Número de Parcelas.
CreditCard.CardNumber. Texto 19 Sim Número do Cartão do Comprador
CreditCard.SecurityCode Texto 4 Não Código de segurança impresso no verso do cartão - Ver Anexo.
CreditCard.Brand Texto 10 Sim Bandeira do cartão (Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard / Hiper).
Wallet.Type Texto 255 Sim indica qual o tipo de carteira: VisaCheckout/ Masterpass / ApplePay / SamsungPay
Wallet.Walletkey Texto 255 Sim Chave criptografica que identifica lojas nas Wallets - Ver tabela WalletKey para mais informações
Wallet.ECI Texto 3 Sim O ECI (Eletronic Commerce Indicator) representa o quão segura é uma transação. Esse valor deve ser levado em consideração pelo lojista para decidir sobre a captura da transação.
Wallet.CAVV Texto 255 Sim Campo de validação retornado pela Wallet e utilizado como base de autorização

Respostas

{
    "MerchantOrderId": "2014111703",
    "Customer": {
        "Name": "[Guest]"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": 0,
        "Capture": false,
        "Authenticate": false,
        "Recurrent": false,
        "CreditCard": {
            "CardNumber": "453211******1521",
            "Holder": "Gama Gama",
            "ExpirationDate": "08/2020",
            "SaveCard": false,
            "Brand": "Visa"
        },
        "Tid": "0319040817883",
        "ProofOfSale": "817883",
        "AuthorizationCode": "027795",
        "Wallet": {
            "Type": "TIPO DE WALLET",
            "Eci": 0
                 },
        "SoftDescriptor": "123456789ABCD",
        "Amount": 100,
        "ReceivedDate": "2018-03-19 16:08:16",
        "Status": 1,
        "IsSplitted": false,
        "ReturnMessage": "Operation Successful",
        "ReturnCode": "4",
        "PaymentId": "e57b09eb-475b-44b6-ac71-01b9b82f2491",
        "Type": "CreditCard",
        "Currency": "BRL",
        "Country": "BRA",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491"
            },
            {
                "Method": "PUT",
                "Rel": "capture",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491/capture"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491/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 Campo Identificador do Pedido. 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
Type indica qual o tipo de carteira: VisaCheckout/ Masterpass / ApplePay / SamsungPay Texto 255 Texto alfanumérico
Walletkey Chave criptografica que identifica lojas nas Wallets - Ver tabela WalletKey para mais informações Texto 255 Ver tabela WalletKey
AdditionalData.capturecode Código informado pela MasterPass ao lojista Texto 255 3

Apple Pay

Pré-Requisitos

Para utilização da Apple Pay no formato Descriptografia é necessario que a loja ja esteja cadastrada junto a Apple e possua um MerchantIdentifier A integração Descriptografia exige que o lojista realize o upload manual de um certificado CSR no formato PEM fornecido pela Cielo. Entre em contato com a equipe de atendimento Cielo para obter o Certificado.

MerchantIdentifier

Para obter o MerchantIdentifier realize os passos abaixo:

  1. Log em Apple Developer
  2. Selecione Certificates, IDs & Profiles
  3. Dentro da área “Identifiers” clique em “Merchant IDs”
  4. Clique no + no canto direito, abaixo de “Registering a Merchant ID”
  5. Defina a descrição do MerchantID e o identificador. Exemplo: “merchant.com.CIELO.merchantAccount”
  6. Clique em “continuar” e verifique se as informações inseridas estão corretas.
  7. Finalize o processo.

O MerchantIdentifier deve ser enviado a Cielo para a criação de um Certificado CSR no formato PEM.

Certificado CSR

Após enviar o MerchantIdentifier para a equipe de atendimento Cielo, a loja receberá um certificado de extensão PEM e deverá seguir os sequintes passos:

  1. Log em Apple Developer
  2. Selecione Certificates, IDs & Profiles
  3. Realize o Upload do Certificado
  4. Finalize o processo.

O Certificado PEM contem o código CSR solicitado pela Apple.
Formato de um Certificado .PEM

-

—–BEGIN CERTIFICATE REQUEST—–
MIHwMIGYAgEAMDgxCzAJBgNVBAYTAkJSMRAwDgYDVQQKDAdicmFzcGFnMRcwFQYD
VQQDDA5icmFzcGFnLmNvbS5icjBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABBIP
ULN00aAwYW+sfTettoIl8l9YrDCkF1HEiI9PgwLcM4jCkIAvnrKZ3loLWDi4J8Jh
ML01OuTohYS46lqF6p4wCgYIKoZIzj0EAwIDRwAwRAIgWLAPtSWKQ3sJYLc6jmWa
RNWCoNR2XBQZKdg5bIGNYpYCIHSLsQVSK8taL7dGirOBxXiOqtUA9hWxn0g1Mf3U
VKeU
—–END CERTIFICATE REQUEST—–

Descriptografia

No modelo apresentado a seguir, demonstramos como utilizar a integração Apple Pay Cielo via o envio do WalletKey + EphemeralPublicKey retornados pela Apple via Payload

Requisição

Exemplo de Requisição Apple Pay

É necessário que a loja ja possua cadastro e uma integração Apple Pay, caso contrario não será possivel a integração com a API

{
  "MerchantOrderId": "6242-642-723",
  "Customer": {
    "Name": "Exemplo Wallet Padrão",
    "Identity": "11225468954",
    "IdentityType": "CPF"
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 1100,
    "Provider": "Cielo",
    "Installments": 1,
    "Currency": "BRL",
    "Wallet": {
      "Type": "ApplePay",
      "WalletKey": "9zcCAciwoTS+qBx8jWb++64eHT2QZTWBs6qMVJ0GO+AqpcDVkxGPNpOR/D1bv5AZ62+5lKvucati0+eu7hdilwUYT3n5swkHuIzX2KO80Apx/SkhoVM5dqgyKrak5VD2/drcGh9xqEanWkyd7wl200sYj4QUMbeLhyaY7bCdnnpKDJgpOY6J883fX3TiHoZorb/QlEEOpvYcbcFYs3ELZ7QVtjxyrO2LmPsIkz2BgNm5f+JaJUSAOectahgLZnZR+sRXTDtqLOJQAprs0MNTkPzF95nXGKCCnPV2mfR7z8FHcP7AGqO7aTLBGJLgxFOnRKaFnYlY2E9uTPBbB5JjZywlLIWsPKur5G4m1/E9A6DwjMd0fDYnxjj0bQDfaZpBPeGGPFLu5YYn1IDc",
      "AdditionalData": {
        "EphemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEoedz1NqI6hs9hEO6dBsnn0X0xp5/DKj3gXirjEqxNIJ8JyhGxVB3ITd0E+6uG4W6Evt+kugG8gOhCBrdUU6JwQ=="
      }
    }
  }
}
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.
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)
Payment.Type Texto 100 Sim Tipo do Meio de Pagamento.
Payment.Amount Número 15 Sim Valor do Pedido (ser enviado em centavos).
Payment.Installments Número 2 Sim Número de Parcelas.
CreditCard.CardNumber. Texto 19 Sim Número do Cartão do Comprador
CreditCard.SecurityCode Texto 4 Não Código de segurança impresso no verso do cartão - Ver Anexo.
CreditCard.Brand Texto 10 Sim Bandeira do cartão (Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard / Hiper).
Wallet.Type Texto 255 Sim indica qual o tipo de carteira: ApplePay / VisaCheckout/ Masterpass
Wallet.Walletkey Texto 255 Sim Chave criptografica que identifica lojas nas Wallets - Ver tabela WalletKey para mais informações
Wallet.AdditionalData.EphemeralPublicKey Texto 255 Sim Token retornado pela Wallet. Deve ser enviado em Integrações: ApplePay
Wallet.AdditionalData.capturecode Texto 255 Sim Código informado pela MasterPass ao lojista

Resposta

{
    "MerchantOrderId": "2014111703",
    "Customer": {
        "Name": "[Guest]"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": 0,
        "Capture": false,
        "Authenticate": false,
        "Recurrent": false,
        "CreditCard": {
            "CardNumber": "453211******1521",
            "Holder": "Leonardo Romano",
            "ExpirationDate": "08/2020",
            "SaveCard": false,
            "Brand": "Visa"
        },
        "Tid": "0319040817883",
        "ProofOfSale": "817883",
        "AuthorizationCode": "027795",
        "Wallet": {
            "Type": "ApplePay",
            "WalletKey": "9zcCAciwoTS+qBx8jWb++64eHT2QZTWBs6qMVJ0GO+AqpcDVkxGPNpOR/D1bv5AZ62+5lKvucati0+eu7hdilwUYT3n5swkHuIzX2KO80Apx/SkhoVM5dqgyKrak5VD2/drcGh9xqEanWkyd7wl200sYj4QUMbeLhyaY7bCdnnpKDJgpOY6J883fX3TiHoZorb/QlEEOpvYcbcFYs3ELZ7QVtjxyrO2LmPsIkz2BgNm5f+JaJUSAOectahgLZnZR+sRXTDtqLOJQAprs0MNTkPzF95nXGKCCnPV2mfR7z8FHcP7AGqO7aTLBGJLgxFOnRKaFnYlY2E9uTPBbB5JjZywlLIWsPKur5G4m1/E9A6DwjMd0fDYnxjj0bQDfaZpBPeGGPFLu5YYn1IDc",
            "Eci": 0
            "AdditionalData": {
                "EphemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEoedz1NqI6hs9hEO6dBsnn0X0xp5/DKj3gXirjEqxNIJ8JyhGxVB3ITd0E+6uG4W6Evt+kugG8gOhCBrdUU6JwQ=="
                              },                
                 },
        "SoftDescriptor": "123456789ABCD",
        "Amount": 100,
        "ReceivedDate": "2018-03-19 16:08:16",
        "Status": 1,
        "IsSplitted": false,
        "ReturnMessage": "Operation Successful",
        "ReturnCode": "4",
        "PaymentId": "e57b09eb-475b-44b6-ac71-01b9b82f2491",
        "Type": "CreditCard",
        "Currency": "BRL",
        "Country": "BRA",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491"
            },
            {
                "Method": "PUT",
                "Rel": "capture",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491/capture"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491/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 Campo Identificador do Pedido. 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
Type indica qual o tipo de carteira: ApplePay / VisaCheckout/ Masterpass Texto 255 Texto alfanumérico
Walletkey Chave criptografica que identifica lojas nas Wallets - Ver tabela WalletKey para mais informações Texto 255 Ver tabela WalletKey
AdditionalData.EphemeralPublicKey Token retornado pela Wallet. Deve ser enviado em Integrações: ApplePay Texto 255 Ver Tabela EphemeralPublicKey
AdditionalData.capturecode Código informado pela MasterPass ao lojista Texto 255 3

Envio de cartão

No modelo apresentado a seguir, demonstramos como a Apple Pay pode ser utilizada com o envio do cartão aberto, sem a necessidade de WalletKey.

Requisição

Nesse modelo, o lojista informa apenas que a transação é de uma Wallet Apple Pay e envia os dados ECI e CAVV fornecidos pela APPLE

{
  "MerchantOrderId": "6242-642-723",
  "Customer": {
    "Name": "Exemplo Wallet Padrão",
    "Identity": "11225468954",
    "IdentityType": "CPF"
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 1100,
    "Provider": "Cielo",
    "Installments": 1,
    "CreditCard": {
      "CardNumber":"4532********6521",
      "Holder":"Exemplo Wallet Padrão",
          "ExpirationDate":"12/2021",
          "SecurityCode":"123",
          "Brand":"Master"
    },
    "Currency": "BRL",
    "Wallet": {
      "Type": "ApplePay",
      "Eci":"7",
      "Cavv":"AM1mbqehL24XAAa0J04CAoABFA=="
    }
  }
}
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.
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)
Payment.Type Texto 100 Sim Tipo do Meio de Pagamento.
Payment.Amount Número 15 Sim Valor do Pedido (ser enviado em centavos).
Payment.Installments Número 2 Sim Número de Parcelas.
CreditCard.CardNumber. Texto 19 Sim Número do Cartão do Comprador
CreditCard.SecurityCode Texto 4 Não Código de segurança impresso no verso do cartão - Ver Anexo.
CreditCard.Brand Texto 10 Sim Bandeira do cartão (Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard / Hiper).
Wallet.Type Texto 255 Sim indica qual o tipo de carteira: ApplePay
Wallet.Walletkey Texto 255 Sim Chave criptografica que identifica lojas nas Wallets - Ver tabela WalletKey para mais informações
Wallet.ECI Texto 3 Sim O ECI (Eletronic Commerce Indicator) representa o quão segura é uma transação. Esse valor deve ser levado em consideração pelo lojista para decidir sobre a captura da transação.
Wallet.CAVV Texto 255 Sim Campo de validação retornado pela Wallet e utilizado como base de autorização

Resposta

{
    "MerchantOrderId": "6242-642-723",
    "Customer": {
        "Name": "Exemplo Wallet Padrão",
        "Identity": "11225468954",
        "IdentityType": "CPF"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": 0,
        "Capture": false,
        "Authenticate": false,
        "Recurrent": false,
        "CreditCard": {
            "CardNumber": "453265******6521",
            "Holder": "Exemplo Wallet Padrão",
            "ExpirationDate": "12/2021",
            "SaveCard": false,
            "Brand": "Visa"
        },
        "Tid": "10447480687BVV8COCRB",
        "ProofOfSale": "457033",
        "Provider": "Cielo",
        "Eci": "7",
        "Wallet": {
            "Type": "ApplePay",
            "Cavv": "AM1mbqehL24XAAa0J04CAoABFA==",
            "Eci": 7
        },
        "VelocityAnalysis": {
            "Id": "98652f2c-bdfd-47b9-8673-77b80a6fe705",
            "ResultMessage": "Accept",
            "Score": 0
        },
        "Amount": 1100,
        "ReceivedDate": "2018-04-18 16:27:22",
        "Status": 2,
        "IsSplitted": false,
        "ReturnMessage": "Operation Successful",
        "ReturnCode": "4",
        "PaymentId": "98652f2c-bdfd-47b9-8673-77b80a6fe705",
        "Type": "CreditCard",
        "Currency": "BRL",
        "Country": "BRA",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491"
            },
            {
                "Method": "PUT",
                "Rel": "capture",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491/capture"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491/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 Campo Identificador do Pedido. 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
Type indica qual o tipo de carteira: ApplePay Texto 255 Texto alfanumérico
AdditionalData.EphemeralPublicKey Token retornado pela Wallet. Deve ser enviado em Integrações: ApplePay Texto 255 Ver Tabela EphemeralPublicKey
AdditionalData.capturecode Código informado pela MasterPass ao lojista Texto 255 3
ECI O ECI (Eletronic Commerce Indicator) indica a segurança de uma transação. Deve ser levado em conta pelo lojista para decidir sobre a captura Texto 3 2
CAVV Campo de validação retornado pela Wallet e utilizado como base de autorização Texto 255 –

VisaCheckout

Descriptografia

No modelo apresentado a seguir, demonstramos como utilizar a integração VisaCheckout Cielo via o envio do WalletKey retornados pela Visa via Payload

O Walletkey é o parametro CallID retornado pelo VisaCheckout

Requisição

Exemplo de Requisição padrão VisaCheckout

É necessário que a loja ja possua cadastro e uma integração VisaCheckout, caso contrario não será possivel a integração com a API

{  
   "MerchantOrderId":"2014111703",
   "Customer":{  
      "Name":"Comprador Teste"
   },
   "Payment":{  
      "Type":"CreditCard",
      "Amount":15700,
      "Installments":1,
      "SoftDescriptor":"123456789ABCD",
      "CreditCard":{  
         "SecurityCode":"123"
      },
      "Wallet":{  
         "Type":"VisaCheckout",
         "WalletKey":"1140814777695873901"
      }
   }
}
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.
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)
Payment.Type Texto 100 Sim Tipo do Meio de Pagamento.
Payment.Amount Número 15 Sim Valor do Pedido (ser enviado em centavos).
Payment.Installments Número 2 Sim Número de Parcelas.
CreditCard.CardNumber. Texto 19 Sim Número do Cartão do Comprador
CreditCard.SecurityCode Texto 4 Não Código de segurança impresso no verso do cartão - Ver Anexo.
CreditCard.Brand Texto 10 Sim Bandeira do cartão (Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard / Hiper).
Wallet.Type Texto 255 Sim indica qual o tipo de carteira: VisaCheckout/ Masterpass / SamsungPay / ApplePay
Wallet.Walletkey Texto 255 Sim Chave criptografica que identifica lojas nas Wallets - Ver tabela WalletKey para mais informações

Resposta

{
    "MerchantOrderId": "2014111703",
    "Customer": {
        "Name": "[Guest]"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": 0,
        "Capture": false,
        "Authenticate": false,
        "Recurrent": false,
        "CreditCard": {
            "CardNumber": "453211******1521",
            "Holder": "Gama Gama",
            "ExpirationDate": "08/2020",
            "SaveCard": false,
            "Brand": "Visa"
        },
        "Tid": "0319040817883",
        "ProofOfSale": "817883",
        "AuthorizationCode": "027795",
        "Wallet": {
            "Type": "VisaCheckout",
            "WalletKey": "1140814777695873901",
            "Eci": 0
            },
        "SoftDescriptor": "123456789ABCD",
        "Amount": 100,
        "ReceivedDate": "2018-03-19 16:08:16",
        "Status": 1,
        "IsSplitted": false,
        "ReturnMessage": "Operation Successful",
        "ReturnCode": "4",
        "PaymentId": "e57b09eb-475b-44b6-ac71-01b9b82f2491",
        "Type": "CreditCard",
        "Currency": "BRL",
        "Country": "BRA",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491"
            },
            {
                "Method": "PUT",
                "Rel": "capture",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491/capture"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/e57b09eb-475b-44b6-ac71-01b9b82f2491/void"
            }
        ]
    }
}

Envio de cartão

No modelo apresentado a seguir, demonstramos como a VisaCheckout pode ser utilizada com o envio do cartão aberto, sem a necessidade de WalletKey.

Requisição

Nesse modelo, o lojista informa apenas que a transação é da Wallet VisaCheckout e envia os dados ECI e CAVV fornecidos pela Visa

{  
   "MerchantOrderId":"2014111703",
   "Customer":{  
      "Name":"Comprador Teste"
   },
   "Payment":{  
      "Type":"CreditCard",
      "Amount":15700,
      "Installments":1,
      "SoftDescriptor":"123456789ABCD",
      "Wallet":{  
         "Type":"VisaCheckout"
         "Eci": 0,
    },
      "CreditCard":{  
         "CardNumber":"1234123412341231",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "Brand":"Visa"
    },
  },
}
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.
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)
Payment.Type Texto 100 Sim Tipo do Meio de Pagamento.
Payment.Amount Número 15 Sim Valor do Pedido (ser enviado em centavos).
Payment.Installments Número 2 Sim Número de Parcelas.
CreditCard.CardNumber. Texto 19 Sim Número do Cartão do Comprador
CreditCard.SecurityCode Texto 4 Não Código de segurança impresso no verso do cartão - Ver Anexo.
CreditCard.Brand Texto 10 Sim Bandeira do cartão (Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard / Hiper).
Wallet.Type Texto 255 Sim indica qual o tipo de carteira: VisaCheckout/ Masterpass / SamsungPay / ApplePay
Wallet.Walletkey Texto 255 Sim Chave criptografica que identifica lojas nas Wallets - Ver tabela WalletKey para mais informações
Wallet.ECI Texto 3 Sim O ECI (Eletronic Commerce Indicator) representa o quão segura é uma transação. Esse valor deve ser levado em consideração pelo lojista para decidir sobre a captura da transação.

Resposta

{
    "MerchantOrderId": "2014111706",
    "Customer": {
        "Name": "Comprador Visa Checkout"
    },
    "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"
        },
        "ProofOfSale": "674532",
        "Tid": "0305023644309",
        "AuthorizationCode": "123456",
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "CreditCard",
        "Amount": 15700,
        "Currency": "BRL",
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 1,
        "ReturnCode": "4",
        "ReturnMessage": "Operation Successful",
        "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 Campo Identificador do Pedido. 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