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:
- ASP
- Net
- Java
- PHP
- Ruby
- Python
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:
- Ausência de aplicativos proprietários: não é necessário instalar aplicativos no ambiente da loja virtual em nenhuma hipótese.
- Simplicidade: o protocolo utilizado é puramente o HTTPS.
- Facilidade de testes: a plataforma Cielo oferece um ambiente Sandbox publicamente acessível, que permite ao desenvolvedor a criação de uma conta de testes sem a necessidade de credenciamento, facilitando e agilizando o início da integração.
- Credenciais: o tratamento das credenciais do cliente (número de afiliação e chave de acesso) trafega no cabeçalho da requisição HTTP da mensagem.
- Segurança: a troca de informações se dá sempre entre o Servidor da Loja e da Cielo, ou seja, sem o browser do comprador.
- Multiplataforma: a integração é realizada através de Web Service REST.
Arquitetura
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 |
| Hiper | 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",
"Mcc":"1234",
"Address":"Alameda Grajau, 512",
"City":"Barueri",
"State":"SP",
"PostalCode":"06455914",
"PhoneNumber":"1155855585"
}
}
}
}
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",
"Mcc":"1234",
"Address":"Alameda Grajau, 512",
"City":"Barueri",
"State":"SP",
"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.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.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. |
Certificados e segurança
O que é Certificado SSL?
O Certificado SSL para servidor web oferece autenticidade e integridade dos dados de um web site, proporcionando aos clientes das lojas virtuais a garantia de que estão realmente acessando o site que desejam, e não uma um site fraudador.
Empresas especializadas são responsáveis por fazer a validação do domínio e, dependendo do tipo de certificado, também da entidade detentora do domínio.
Internet Explorer:
Firefox
Google Chrome
O que é Certificado EV SSL?
O Certificado EV foi lançado no mercado recentemente e garante um nível de segurança maior para os clientes das lojas virtuais.
Trata-se de um certificado de maior confiança e quando o https for acessado a barra de endereço ficará verde, dando mais confiabilidade aos visitantes do site.
Como instalar o Certificado Extended Validation no servidor da Loja?
Basta instalar os três arquivos a seguir na Trustedstore do servidor. A Cielo não oferece suporte para a instalação do Certificado. Caso não esteja seguro sobre como realizar a instalação do Certificado EV, então você deverá ser contatado o suporte do fornecedor do seu servidor.
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”:
No “Firefox”, clique no menu “Abrir Menu” e acesse “Avançado” e “Opções”:
No “Chrome”, clique no “Personalizar e Controlar o Google Chrome” e acesse “Configurações” e “Mostrar configurações avançadas… “Alterar Configurações de Proxy e “Conteúdo” e Certificados:
3o Passo:
No Internet Explorer, em “Certificados”, clique em “Importar”.
No Firefox clique em “Ver Certificados”, clique em “Importar”
No Chrome clique em “Gerenciar Certificados”, clique em “Importar”
4o Passo:
No Internet Explorer e Chrome “Assistente para Importação de Certificados”, clique em “Avançar”.
No Firefox “Aba Servidores ”, clique em “Importar”
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”.
6o Passo:
Selecionar a opção desejada: adicionar o Certificado em uma pasta padrão ou procurar a pasta de sua escolha.
7o Passo:
Clique em “Concluir”.
8o Passo:
Clique em “Ok” para concluir a importação.
O Certificado poderá ser visualizado na aba padrão “Outras Pessoas” ou na escolhida pelo cliente.
9o Passo:
Repita o mesmo procedimento para os 3 arquivos enviados.
Sandbox e Ferramentas
Sobre o Sandbox
Para facilitar os testes durante a integração, a Cielo oferece um ambiente Sandbox que é composto por duas áreas:
- Cadastro de conta de testes
- Endpoints transacionais
| Requisição | https://apisandbox.cieloecommerce.cielo.com.br |
| Consulta | https://apiquerysandbox.cieloecommerce.cielo.com.br |
Vantagens de utilizar o Sandbox
- Não é necessário uma afiliação para utilizar o Sandbox Cielo.
- Basta acessar o Cadastro do Sandbox criar uma conta.
- com o cadastro você receberá um
MerchantIde umMerchantKey,que são as credenciais necessarias para os métodos da API
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:
- Autorização
- Captura
- Cancelamento.
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.
-
MPI Interno: serviço já integrado a solução de 3DS Cielo, sem necessidade de integração e/ou contratação adicional. Em caso de utilização de MPI Interno para o 3DS 1.0 siga para a etapa “Transação Padrão”
-
MPI Externo: serviço contratado pelo lojista, sem interferência da Cielo. Muito utilizado quando o lojista já possui um fornecedor de MPI contratado. Em caso de utilização de MPI Externo para o 3DS 1.0, siga a próxima etapa “Autenticação Externa 3DS 1.0”
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 |
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.Districtdevem 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
- Requisição de transação: https://api.cieloecommerce.cielo.com.br/
- Consulta transação: https://apiquery.cieloecommerce.cielo.com.br/
Ambiente Sandbox
- Requisição de transação: https://apisandbox.cieloecommerce.cielo.com.br
- Consulta transação: https://apiquerysandbox.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.
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 |
| Hiper | 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:
- Cadastro de conta de testes
- Endpoints transacionais
| Requisição | https://apisandbox.cieloecommerce.cielo.com.br |
| Consulta | https://apiquerysandbox.cieloecommerce.cielo.com.br |
Vantagens de utilizar o Sandbox
- Não é necessário uma afiliação para utilizar o Sandbox Cielo.
- Basta acessar o Cadastro do Sandbox criar uma conta.
- com o cadastro você receberá um
MerchantIde umMerchantKey,que são as credenciais necessarias para os métodos da API
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:
- Ela executa a cobrança do cartão
- Ela inclui o valor da venda na fatura do comprador
- Somente transações capturadas são pagas pela Cielo ao lojista
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:
- Ela executa a cobrança do cartão
- Ela inclui o valor da venda na fatura do comprador
- Somente transações capturadas são pagas pela Cielo ao lojista
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
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.
| Meio de pagamento | Descrição | Prazo | Participação Cielo |
|---|---|---|---|
| Cartão de crédito | A Cielo devolve o valor via crédito bancario | 300 dias pós autorização | Sim |
| Cartão de Débito | Cancelamento apenas na API. O retorno do valor é feito pelo proprio lojista | 300 dias pós autorização | Não |
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
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:
RecurrentPaymentId- Identificador que representa um conjunto de transações recorrentesPaymentId- Identificador que representa a transaçãoChangeType- Especifica o tipo de notificação
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
- Deve ser estática
- Limite de 255 carácteres.
Características do Post de notificação
- É disparado a cada 30 minutos
- Em caso de falha, 3 novas tentativas são realizadas.Se as 3 tentativas falharem, novos envios não ocorrerã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
KEY- Nome do paramêtroVALUE- Valor estático a ser retornado
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 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:
As variáveis, quando devidamente preenchidas, forneceriam uma URL semelhante ao exemplo abaixo:
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 - Quando a inteligência da repetição e dados do cartão da recorrência ficam sobre responsabilidade do lojista
- Recorrência Programada - Quando a inteligência da repetição e dados do cartão da recorrência ficam sobre responsabilidade da Cielo
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:
- Recorrência própria + Cartão Tokenizado
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:
- 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.
- 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:
- Intervalos programados: Mensal, bimestral, trimestral semestral e anual
- Data de validade: Permite definir se a recorrência vai se encerrar
- Retentativa: se uma transação for negada, vamos retentar a transação até 4x
- Atualização: Permite alterar dados da recorrência, como valor, intervalo.
Veja um exemplo em uso:
- Recorrência Mensal e anual
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:
- Mensal por R$19,90
- Anual (com desconto) de R$180,00
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:
-
Facilidade: A cobrança de mensalidade é automática, logo o MusicFy não precisa se preocupar em construir um sistema de cobrança.
-
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.
-
Segurança: Não é necessário armazenar dados sensíveis do cartão e do comprador junto a loja.
-
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:
- Bandeira do cartão: Nome da Bandeira
- Tipo de cartão: Crédito, Débito ou Múltiplo (Crédito e Débito)
- Nacionalidade do cartão: Estrangeiro ou Nacional
- Cartão Corporativo: Se o cartão é ou não é corporativo
- Banco Emissor: Código e Nome
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!
- Impedir erros com tipo de cartão
- Oferecer recuperação de carrinhos online
- Alertar sobre cartões internacionais
- 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:
-
Bandeira errada e confundir cartão de crédito com débito ○ Bandeiras erradas: Ao preencher o formulário de pagamento, é possível realizar uma consulta e já definir a bandeira correta. Esse é um método muito mais seguro do que sebasear em algoritmos no formulário, pois a base de bins consultada é a da bandeira emissora do cartão.
-
Confusões com cartões: Ao preencher o formulário de pagamento, é possível realizar uma consulta e avisar ao consumidor se ele está usando um cartão de débito quando na verdade deveria usar um de débito
Oferecer recuperação de carrinhos online
-
O Submergível pode usar a consulta bins no carrinho para oferecer um novo meio de pagamento caso a transação falhe na primeira tentativa.
-
Realizando uma consulta no momento de preenchimento do formulário de pagamento, caso o cartão seja múltiplo (Crédito e Débito), o Submergível pode reter os dados do cartão, e caso a transação de crédito falhe, ele pode oferecer automaticamente ao consumidor uma transação de débito com o mesmo cartão.
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:
- Padrão - Envio de um cartão padrão, sem tokenização ou analises adicionais
- 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:
- Limite de crédito do cartão
- Informações sobre o portador
- Não aciona a base bancaria (dispara SMS so portador)
O Zero Auth suporta as seguintes bandeiras:
- Visa
- MasterCard
- Elo
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:
- Se o cartão está valido junto ao banco emissor
- Se o cartão possui limite disponível
- Se o cartão funciona no Brasil
- Se o número do cartão está correto
- 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:
- Cadastro: é necessário incluir um cartão para ganhar 30 dias grátis no primeiro mês.
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.
- Recorrência: todo mês, antes de realizar a cobrança da Assinatura, a Flixnet testa o cartão com o zero auth, assim sabendo se ele será autorizado ou não. Isso ajuda o FlixNet a prever quais cartões serão negados, já acionando o assinante para atualização do cadastro antes do dia de pagamento.
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:
- 500 – Internal Server Erro
- 400 – Bad Request
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
- Captura de dados de pagamento diretamente para os sistemas da Cielo por meio dos campos hospedados na sua página através de um script (javascript).
- Compatibilidade com todos os meios de pagamentos disponibilizados ao Gateway (Nacional e Internacional)
- Autenticação do comprador (disponível)
- Redução do escopo de PCI DSS
- Mantenha controle total sobre a experiência de check-out e elementos de gestão da sua marca.
Fluxo de Autorização
Fluxo Padrão de Autorizaçã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
O servidor não trafega os dados do cartão abertamente.
Fluxo Transacional
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:
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:
- Para o portador do cartão de crédito/débito: bp-sop-cardholdername
- Para o número do cartão de crédito/débito: bp-sop-cardnumber
- Para a validade do cartão de crédito/débito: bp-sop-cardexpirationdate
- Para o código de segurança do cartão de crédito/débito: bp-sop-cardcvvc
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).
-
Na validação dos inputs, o estabelecimento poderá utilizar toda a camada de validação sobre os dados de cartão realizada pela Cielo e assim simplificar o tratamento no seu formulário de checkout. As mensagens retornadas no resultado da validação são disponibilizadas nas seguintes linguagens: português (default), inglês e espanhol.
-
O PaymentToken será o token que representará todos os dados de cartão fornecido pelo comprador. O mesmo será utilizado pelo estabelecimento para não haver necessidade de tratar e processar dados de cartão do seu lado.
},
"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:
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.
- Descriptografia - Quando o lojista envia os dados da wallet para que a API Cielo e-commerce realize o processamento do cartão
- 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. OWalletKeyApple Pay pode ser obtido dentro do campoDATAdo 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:
- Log em Apple Developer
- Selecione Certificates, IDs & Profiles
- Dentro da área “Identifiers” clique em “Merchant IDs”
- Clique no + no canto direito, abaixo de “Registering a Merchant ID”
- Defina a descrição do MerchantID e o identificador. Exemplo: “merchant.com.CIELO.merchantAccount”
- Clique em “continuar” e verifique se as informações inseridas estão corretas.
- Finalize o processo.
O
MerchantIdentifierdeve 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:
- Log em Apple Developer
- Selecione Certificates, IDs & Profiles
- Realize o Upload do Certificado
- 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
- CAVV - pode ser extraido do campo
onlinePaymentCryptogramretornado pela Apple no payload - ECI - pode ser extraido do campo
eciIndicatorretornado pela Apple no payload
{
"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 parametroCallIDretornado 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
- ECI - retornado pela Visa no payload como
DSC_ECI
{
"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 |
Type |
indica qual o tipo de carteira: VisaCheckout/ Masterpass / SamsungPay / ApplePay |
Texto | 255 | Texto alfanumérico |
MasterPass
Envio de Cartão
A Wallet MasterPass possui integração apenas no formato
Envio de cartão.
Para utilizar a wallet Masterpass é necessario que a loja ja esteja cadastrada junto a Mastercard, e integrada a busca de dados de cartão da plataforma.
Requisição
Exemplo de Requisição Masterpass
É necessário que a loja ja possua cadastro e uma integração Masterpass, caso contrario não será possivel a integração com a API
{
"MerchantOrderId":"2014111708",
"Customer":{
"Name":"Comprador MasterPass"
},
"Payment":{
"Type":"CreditCard",
"Amount":15700,
"Installments":1,
"CreditCard":{
"CardNumber": "4532117080573703",
"Brand": "Visa",
"SecurityCode":"023"
},
"Wallet":{
"Type":"MasterPass",
"Eci":"7",
"Cavv":"AM1mbqehL24XAAa0J04CAoABFA=="
"AdditionalData":{
"CaptureCode": "103"
}
}
}
}
| 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.AdditionalData.capturecode |
Texto | 255 | Sim | Código informado pela MasterPass ao lojista |
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": "Masterpass",
"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: VisaCheckout/ Masterpass / SamsungPay / ApplePay |
Texto | 255 | Texto alfanumérico |
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 | – |
Samsung Pay
Pré-Requisitos
Para utilização da Samsung no formato Descriptografia é necessario que a loja ja esteja cadastrada junto a plataforma da Samsung. 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 produtos Cielo para obter o Certificado.
Certificado CSR
Após se cadastrar junto a SamsungPay, a loja deverá requisitar um certificado de extensão PEM a equipe de produtos Cielo. Com o certificado em mãos, deverá seguir os sequintes passos:
- Log em Samsung
- Selecione My Projects para criar serviço
- Realize o Upload do Certificado Cielo
- Finalize o processo.
O Certificado PEM contem o código CSR solicitado pela Samsung.
Formato de um Certificado.PEM
–
—–BEGIN CERTIFICATE REQUEST—– MIICezCCAWMCAQAwODELMAkGA1UEBhMCQlIxEDAOBgNVBAoMB2JyYXNwYWcxFzAV
BgNVBAMMDmJyYXNwYWcuY29tLmJyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB
CgKCAQEApsk94DAhdgvgUgGT/fufNkofB2AeX/sPXRT0mm92DM8XgbyWw6FgsE2T
3SFi5WmYwDo12tVjAydUCRzMc6HDIrLBFJsfHgrZWLlf9QIPLZFW/zA9+qZLP+VW
nGyGBil+rgNhylXfDGjCvUMJ5bSLbcC2oC1HGO613HsJrbsB96sE107RkFhDEChD
9fZi3MoD2lCwVjbAu/zDatoloxy8Bc02HqlK4sVZuPUzFIZ9gg19G/QU6WI2ompv
akkhc07xS8QIU/XuzMV5KdpCs/mlRH1QQICSHdviu2UKbKlM9KWqpBOeLwGsQ59P
mQVb5bPgdAix8KvBAWAi8pcdgjWiIwIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQBh
4XwAmQabopYgJgb+8UwIV+LbWKszwXVUq9nYfiDN0OT4KguilfNQQMHvULlHVahJ
ibiRsuFfkmEkvGkrUm1IMCHjwZjDzJmbB/7VwqHzq5HJ9pa9Dt6xRO7psCycSE4N
m+iQs18muHWkzPFouBw+HDVgD8NJZS0mPKSnOmdWpajUHkpDsXY+XctLI2n6NAc3
sy65A6ljFGpjdHG+aJc7TjzjSBpNXyY5bys5zGF44wgOKq/md5nMp6IeqYAZ+D1N
aWvYpwra9kiVLR3742JWgF7P25rCdpwzXO9KiD9T8VxYnEZeFli+LQXb7c6UJjHl
/mYyDuIyBIna9ij0Ygff
—–END CERTIFICATE REQUEST—–
”,
Descriptografia
No modelo apresentado a seguir, demonstramos como utilizar a integração SamsungPay Cielo via o envio do WalletKey + EphemeralPublicKey retornados pela Samsung via Payload
Requisição
Exemplo de Requisição SamsungPay
É necessário que a loja ja possua cadastro e uma integração SamsungPay, 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":1,
"Provider":"Cielo",
"Installments":1,
"Currency":"BRL",
"Wallet":{
"Type":"SamsungPay",
"WalletKey":"eyJhbGciOiJSU0ExXzUiLCJraWQiOiIvam1iMU9PL2hHdFRVSWxHNFpxY2VYclVEbmFOUFV1ZUR5M2FWeHBzYXVRPSIsInR5cCI6IkpPU0UiLCJjaGFubmVsU2VjdXJpdHlDb250ZXh0IjoiUlNBX1BLSSIsImVuYyI6IkExMjhHQ00ifQ.cCsGbqgFdzVb1jhXNR--gApzoXH-LldMArSoG59x6i0BbI7jttqxyAdcriSy8q_77VAp3854P9kekjj54RKLrP6APDIr46DI97kjG9E99ONXImnEyamHj95ZH_AW8lvkfa09KAr4537RM8GEXyZoys2vfIW8zqjjicZ8EKIpAixNlmrFJu6-Bo_utsmDN_DuGm69Kk2_nh6txa7ML9PCI59LFfOMniAf7ZwoZUBDCY7Oh8kx3wsZ0kxNBwfyLBCMEYzET0qcIYxePezQpkNcaZ4oogmdNSpYY-KbZGMcWpo1DKhWphDVp0lZcLxA6Q25K78e5AtarR5whN4HUAkurQ.CFjWpHkAVoLCG8q0.NcsTuauebemJXmos_mLMTyLhEHL-p5Wv6J88WkgzyjAt_DW7laiPMYw2sqRXkOiMJLwhifRzbSp8ZgJBM25IX05dKKSS4XfFjJQQjOBHw6PYtEF5pUDMLHML3jcddCrX07abfef_DuP41PqOQYsjwesLZ8XsRj-R0TH4diOZ_GQop8_oawjRIo9eJr9Wbtho0h8kAzHYpfuhamOPT718EaGAY6SSrR7t6nBkzGNkrKAmHkC7aRwe.AbZG53wRqgF0XRG3wUK_UQ"
}
}
}
| 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 / SamsungPay / 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": "SamsungPay",
"WalletKey": "eyJhbGciOiJSU0ExXzUiLCJraWQiOiIvam1iMU9PL2hHdFRVSWxHNFpxY2VYclVEbmFOUFV1ZUR5M2FWeHBzYXVRPSIsInR5cCI6IkpPU0UiLCJjaGFubmVsU2VjdXJpdHlDb250ZXh0IjoiUlNBX1BLSSIsImVuYyI6IkExMjhHQ00ifQ.cCsGbqgFdzVb1jhXNR--gApzoXH-LldMArSoG59x6i0BbI7jttqxyAdcriSy8q_77VAp3854P9kekjj54RKLrP6APDIr46DI97kjG9E99ONXImnEyamHj95ZH_AW8lvkfa09KAr4537RM8GEXyZoys2vfIW8zqjjicZ8EKIpAixNlmrFJu6-Bo_utsmDN_DuGm69Kk2_nh6txa7ML9PCI59LFfOMniAf7ZwoZUBDCY7Oh8kx3wsZ0kxNBwfyLBCMEYzET0qcIYxePezQpkNcaZ4oogmdNSpYY-KbZGMcWpo1DKhWphDVp0lZcLxA6Q25K78e5AtarR5whN4HUAkurQ.CFjWpHkAVoLCG8q0.NcsTuauebemJXmos_mLMTyLhEHL-p5Wv6J88WkgzyjAt_DW7laiPMYw2sqRXkOiMJLwhifRzbSp8ZgJBM25IX05dKKSS4XfFjJQQjOBHw6PYtEF5pUDMLHML3jcddCrX07abfef_DuP41PqOQYsjwesLZ8XsRj-R0TH4diOZ_GQop8_oawjRIo9eJr9Wbtho0h8kAzHYpfuhamOPT718EaGAY6SSrR7t6nBkzGNkrKAmHkC7aRwe.AbZG53wRqgF0XRG3wUK_UQ",
"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: ApplePay / SamsungPay / 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 SamsungPay 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 SamsungPay e envia os dados ECI e CAVV fornecidos pela Samsung
- CAVV - pode ser extraido do campo
Cryptogramretornado pela Samsung no payload - ECI - retornado pela Samsung Pay no payload campo
eci_indicator
{
"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": "SamsungPay",
"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 / SamsungPay / VisaCheckout/ Masterpass |
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":