Guia de migração Cielo
Para novas integrações, veja API Cielo E-commerce
Esse guia tem como propósito facilitar a migração da integração entre as soluções Webservice 1.5 e API 3.0. Antes de ler esse guia, é altamente recomentado que você tenha lido o manual de integração da solução para qual pretende migrar sua integração atual. Os manuais podem ser encontrados em:
Visão Geral
De forma geral, a primeira grande diferença entre as duas soluções está no envio das credenciais do estabelecimento comercial. No Webservice 1.5, as credenciais eram enviadas no nó dados-ec, através dos elementos numero e chave; na API 3.0, as credenciais são enviadas utilizando cabeçalhos HTTP, através dos campos de cabeçalho MerchantId e MerchantKey.
A segunda grande diferença entre as duas soluções está no envio dos dados relacionados ao comprador; como na solução Webservice 1.5 esses dados não são enviados na integração, a loja poderá precisar implementar essa coleta de dados caso queira enviá-los.
A terceira grande diferença entre as duas soluções está no AVS; como a API 3.0 ainda não suporta AVS, não há, na API, uma forma para enviá-los.
Ambientes da 3.0
Além dessas diferenças, as requisições HTTP também são feitas em ambientes diferentes utilizado métodos HTTP específicos para cada tipo de requisição; são eles:
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
Métodos HTTP da 3.0
Criação de vendas
Captura ou cancelamento de vendas
Consulta de vendas
Tabelas comparativas
A seção das tabelas comparativas mostra, campo a campo, cada especificidade das soluções em cada caso de uso; as colunas GUIAR POR são utilizadas para colocar o foco em uma das soluções.
Comparar Soluções:
Caso sua integração atual utilize a solução Webservice 1.5 e você queira fazer a comparação com a API 3.0 ou vice versa, basta visulizar as tabelas abaixo
Integração com cartão de crédito
Tabela da Requisição de Crédito
Nessa seção você poderá analisar, campo a campo, cada especificidade das soluções no cenário de uma requisição de venda por crédito.
| solução 3.0 | solução 1.5 | Observações |
|---|---|---|
| ”–Header.MerchantId” | dados-ec.numero | O 1.5 recebe EC no corpo do request e o 3.0 recebe o MerchantId no header. Estes campos não possuem o mesmo valor |
| ”–Header.MerchantKey” | dados-ec.chave | O 1.5 recebe a Chave no corpo do request e o 3.0 recebe o MerchantKey no header. Estes campos não possuem o mesmo valor |
| ”–Header.RequestId” | – | No 1.5 não existe campo com o identificador do Request |
| MerchantOrderId | dados-pedido.numero | |
| Customer.Name | – | O 1.5 não recebe dados relacionados ao comprador |
| Customer.Email | – | O 1.5 não recebe dados relacionados ao comprador |
| Customer.Birthdate | – | O 1.5 não recebe dados relacionados ao comprador |
| Customer.Address.Street | – | O 1.5 não recebe dados relacionados ao comprador |
| Customer.Address.Number | – | O 1.5 não recebe dados relacionados ao comprador |
| Customer.Address.Complement | – | O 1.5 não recebe dados relacionados ao comprador |
| Customer.Address.ZipCode | – | O 1.5 não recebe dados relacionados ao comprador |
| Customer.Address.City | – | O 1.5 não recebe dados relacionados ao comprador |
| Customer.Address.State | – | O 1.5 não recebe dados relacionados ao comprador |
| Customer.Address.Country | – | O 1.5 não recebe dados relacionados ao comprador |
| Customer.DeliveryAddress.Street | – | O 1.5 não recebe dados relacionados ao comprador |
| Customer.DeliveryAddress.Number | – | O 1.5 não recebe dados relacionados ao comprador |
| Customer.DeliveryAddress.Complement | – | O 1.5 não recebe dados relacionados ao comprador |
| Customer.DeliveryAddress.ZipCode | – | O 1.5 não recebe dados relacionados ao comprador |
| Customer.DeliveryAddress.City | – | O 1.5 não recebe dados relacionados ao comprador |
| Customer.DeliveryAddress.State | – | O 1.5 não recebe dados relacionados ao comprador |
| Customer.DeliveryAddress.Country | – | O 1.5 não recebe dados relacionados ao comprador |
| Payment.Type | forma-pagamento.produto | No 3.0 a forma de pagamento (Crédito e Débito) e o tipo de juros são definidos em campos distintos |
| Payment.Amount | dados-pedido.valor | |
| Payment.Currency | dados-pedido.moeda | |
| Payment.Country | – | |
| Payment.Provider | – | O 1.5 não dispobiliza outras formas de pagamento que não seja Cielo. O 3.0 dispobibiliza, além da Cielo, Bradesco e BB |
| Payment.SeviceTaxAmount | dados-pedido.taxa-embarque | |
| Payment.Installments | forma-pagamento.parcelas | |
| Payment.Interest | forma-pagamento.produto | No 3.0 a forma de pagamento (Crédito e Débito) e o tipo de juros são definidos em campos distintos |
| Payment.Capture | capturar | |
| Payment.SoftDescriptor | dados-pedido.soft-descriptor | |
| Payment.ReturnUrl | url-retorno | |
| Payment.ExtraData[] | campo-livre | No 1.5 é uma string e no 3.0 é uma coleção chave/valor |
| Payment.Authenticate | autorizar | |
| Payment.CreditCard.CardNumber | dados-portador.numero | |
| Payment.CreditCard.Holder | – | |
| Payment.CreditCard.ExpirationDate | dados-portador.validade | |
| Payment.CreditCard.SecurityCode | dados-portador.codigo-seguranca | |
| Payment.CreditCard.CardToken | dados-portador.token | |
| Payment.CreditCard.SaveCard | gerar-token | |
| Payment.CreditCard.Brand | forma-pagamento.bandeira | |
| Payment.RecurrentPayment.EndDate | – | O 1.5 utiliza uma outra forma de recorrência |
| Payment.RecurrentPayment.Interval | – | |
| Payment.RecurrentPayment.AuthorizeNow | – | |
| – | dados-portador.indicador | No 3.0 não existe campo para informar o envio do CVV. |
| – | dados-pedido.data-hora | |
| – | dados-pedido.descricao | |
| – | dados-pedido.idioma | |
| – | bin | |
| – | avs.dados-avs.endereco | O 3.0 ainda não suporta AVS |
| – | avs.dados-avs.complemento | O 3.0 ainda não suporta AVS |
| – | avs.dados-avs.numero | O 3.0 ainda não suporta AVS |
| – | avs.dados-avs.bairro | O 3.0 ainda não suporta AVS |
| – | avs.dados-avs.cep | O 3.0 ainda não suporta AVS |
Tabela da Resposta de Crédito
Nessa seção você poderá analisar, campo a campo, cada especificidade das soluções no cenário da resposta de uma requisição de venda por crédito.
| solução 3.0 | solução 1.5 | Observações |
|---|---|---|
| –Header.MerchantId | – | O 1.5 não retorna os dados de request no response |
| –Header.MerchantKey | – | O 1.5 não retorna os dados de request no response |
| –Header.RequestId | – | |
| MerchantOrderId | dados-pedido.numero | |
| Customer.Name | – | |
| Customer.Email | – | |
| Customer.Birthdate | – | |
| Customer.Address.Street | – | |
| Customer.Address.Number | – | |
| Customer.Address.Complement | – | |
| Customer.Address.ZipCode | – | |
| Customer.Address.City | – | |
| Customer.Address.State | – | |
| Customer.Address.Country | – | |
| Customer.DeliveryAddress.Street | – | |
| Customer.DeliveryAddress.Number | – | |
| Customer.DeliveryAddress.Complement | – | |
| Customer.DeliveryAddress.ZipCode | – | |
| Customer.DeliveryAddress.City | – | |
| Customer.DeliveryAddress.State | – | |
| Customer.DeliveryAddress.Country | – | |
| Payment.Type | forma-pagamento.produto | |
| Payment.Amount | dados-pedido.valor | |
| Payment.Amount | autenticacao.valor | |
| Payment.Amount | autorizacao.valor | |
| Payment.CapturedAmount | captura.valor | |
| Payment.Currency | dados-pedido.moeda | |
| Payment.Country | – | O 1.5 não retorna os dados de request no response |
| Payment.Provider | – | O 1.5 não retorna os dados de request no response |
| Payment.SeviceTaxAmount | dados-pedido.taxa-embarque | |
| Payment.Installments | forma-pagamento.parcelas | |
| Payment.Interest | forma-pagamento.produto | |
| Payment.Capture | – | O 1.5 não retorna os dados de request no response |
| Payment.SoftDescriptor | – | O 1.5 não retorna os dados de request no response |
| Payment.ReturnUrl | – | O 1.5 não retorna os dados de request no response |
| Payment.ExtraData[] | – | O 1.5 não retorna os dados de request no response |
| Payment.Authenticate | – | O 1.5 não retorna os dados de request no response |
| Payment.Tid | tid | |
| Payment.ProofOfSale | autorizacao.nsu | |
| Payment.AuthorizationCode | autorizacao.arp | |
| Payment.Status | status | Os valores retornados pelas aplicações são diferentes |
| Payment.ReturnCode | autenticacao.codigo | No 3.0 existe apenas um campo para código de retorno |
| Payment.ReturnCode | autorizacao.lr | No 3.0 existe apenas um campo para código de retorno |
| Payment.ReturnCode | captura.codigo | No 3.0 existe apenas um campo para código de retorno |
| Payment.ReturnMessage | autenticacao.mensagem | No 3.0 existe apenas um campo para mensagem de retorno |
| Payment.ReturnMessage | autorizacao.mensagem | No 3.0 existe apenas um campo para mensagem de retorno |
| Payment.ReturnMessage | captura.mensagem | No 3.0 existe apenas um campo para mensagem de retorno |
| Payment.ReceivedDate | dados-pedido.data-hora | |
| Payment.CapturedDate | captura.data-hora | |
| Payment.Eci | autenticacao.eci | |
| Payment.CreditCard.CardNumber | – | O 1.5 não retorna os dados de request no response |
| Payment.CreditCard.Holder | – | |
| Payment.CreditCard.ExpirationDate | – | O 1.5 não retorna os dados de request no response |
| Payment.CreditCard.SecurityCode | – | O 1.5 não retorna os dados de request no response |
| Payment.CreditCard.CardToken | – | O 1.5 não retorna os dados de request no response |
| Payment.CreditCard.SaveCard | – | O 1.5 não retorna os dados de request no response |
| Payment.CreditCard.Brand | forma-pagamento.bandeira | |
| Payment.RecurrentPayment.EndDate | – | A recorrência funciona de forma diferente nas APIs |
| Payment.RecurrentPayment.Interval | – | A recorrência funciona de forma diferente nas APIs |
| Payment.RecurrentPayment.AuthorizeNow | – | A recorrência funciona de forma diferente nas APIs |
| Payment.Links[].Method | – | O 1.5 não suporta HATEOAS |
| Payment.Links[].Rel | – | O 1.5 não suporta HATEOAS |
| Payment.Links[].Href | – | O 1.5 não suporta HATEOAS |
| – | pan | |
| – | dados-pedido.descricao | |
| – | dados-pedido.idioma | |
| – | autenticacao.data-hora | |
| – | autorizacao.data-hora | |
| – | autorizacao.codigo |
Integração com cartão de débito
Tabela da Requisição de Débito
Nessa seção você poderá analisar, campo a campo, cada especificidade das soluções no cenário de uma requisição de venda por débito.
| Guiar por | solução 3.0 | Guiar por | solução 1.5 | Observações | |
|---|---|---|---|---|---|
| 1 | –Header.MerchantId | 1 | dados-ec.numero | O 1.5 recebe EC no corpo do request e o 3.0 recebe o MerchantId no header. Estes campos não possuem o mesmo valor | |
| 2 | –Header.MerchantKey | 2 | dados-ec.chave | O 1.5 recebe a Chave no corpo do request e o 3.0 recebe o MerchantKey no header. Estes campos não possuem o mesmo valor | |
| 3 | –Header.RequestId | 30 | – | No 1.5 não existe campo com o identificador do Request | |
| 4 | MerchantOrderId | 11 | dados-pedido.numero | ||
| 5 | Customer.Name | 31 | – | O 1.5 não recebe dados relacionados ao comprador | |
| 6 | Customer.Email | 32 | – | O 1.5 não recebe dados relacionados ao comprador | |
| 7 | Customer.Birthdate | 33 | – | O 1.5 não recebe dados relacionados ao comprador | |
| 8 | Customer.Address.Street | 34 | – | O 1.5 não recebe dados relacionados ao comprador | |
| 9 | Customer.Address.Number | 35 | – | O 1.5 não recebe dados relacionados ao comprador | |
| 10 | Customer.Address.Complement | 36 | – | O 1.5 não recebe dados relacionados ao comprador | |
| 11 | Customer.Address.ZipCode | 37 | – | O 1.5 não recebe dados relacionados ao comprador | |
| 12 | Customer.Address.City | 38 | – | O 1.5 não recebe dados relacionados ao comprador | |
| 13 | Customer.Address.State | 39 | – | O 1.5 não recebe dados relacionados ao comprador | |
| 14 | Customer.Address.Country | 40 | – | O 1.5 não recebe dados relacionados ao comprador | |
| 15 | Customer.DeliveryAddress.Street | 41 | – | O 1.5 não recebe dados relacionados ao comprador | |
| 16 | Customer.DeliveryAddress.Number | 42 | – | O 1.5 não recebe dados relacionados ao comprador | |
| 17 | Customer.DeliveryAddress.Complement | 43 | – | O 1.5 não recebe dados relacionados ao comprador | |
| 18 | Customer.DeliveryAddress.ZipCode | 44 | – | O 1.5 não recebe dados relacionados ao comprador | |
| 19 | Customer.DeliveryAddress.City | 45 | – | O 1.5 não recebe dados relacionados ao comprador | |
| 20 | Customer.DeliveryAddress.State | 46 | – | O 1.5 não recebe dados relacionados ao comprador | |
| 21 | Customer.DeliveryAddress.Country | 47 | – | O 1.5 não recebe dados relacionados ao comprador | |
| 22 | Payment.Type | 9 | forma-pagamento.produto | No 3.0 a forma de pagamento (Crédito e Débito) e o tipo de juros são definidos em campos distintos | |
| 23 | Payment.Amount | 12 | dados-pedido.valor | ||
| 24 | Payment.Currency | 13 | dados-pedido.moeda | ||
| 25 | Payment.Country | 48 | – | ||
| 26 | Payment.Provider | 49 | – | O 1.5 não dispobiliza outras formas de pagamento que não seja Cielo. O 3.0 dispobibiliza, além da Cielo, Bradesco e BB | |
| 27 | Payment.SoftDescriptor | 18 | dados-pedido.soft-descriptor | ||
| 28 | Payment.ReturnUrl | 19 | url-retorno | ||
| 29 | Payment.ExtraData[] | 21 | campo-livre | ||
| 30 | Payment.DebitCard.CardNumber | 3 | dados-portador.numero | No 3.0 a forma de pagamento (Crédito e Débito) e o tipo de juros são definidos em campos distintos | |
| 31 | Payment.DebitCard.Holder | 50 | – | ||
| 32 | Payment.DebitCard.ExpirationDate | 4 | dados-portador.validade | No 3.0 não existe campo para informar o envio do CVV. | |
| 33 | Payment.DebitCard.SecurityCode | 6 | dados-portador.codigo-seguranca | ||
| 34 | Payment.DebitCard.CardToken | 7 | dados-portador.token | No 1.5 é uma string e no 3.0 é uma coleção chave/valor | |
| 35 | Payment.DebitCard.SaveCard | 24 | gerar-token | ||
| 36 | Payment.DebitCard.Brand | 8 | forma-pagamento.bandeira | ||
| 37 | – | 17 | dados-pedido.taxa-embarque | ||
| 38 | – | 10 | forma-pagamento.parcelas | ||
| 39 | – | 9 | forma-pagamento.produto | ||
| 40 | – | 20 | capturar | ||
| 41 | – | 23 | autorizar | ||
| 42 | – | 5 | dados-portador.indicador | ||
| 43 | – | 14 | dados-pedido.data-hora | ||
| 44 | – | 15 | dados-pedido.descricao | ||
| 45 | – | 16 | dados-pedido.idioma | ||
| 46 | – | 22 | bin | ||
| 47 | – | 25 | avs.dados-avs.endereco | O 3.0 ainda não suporta AVS | |
| 48 | – | 26 | avs.dados-avs.complemento | O 3.0 ainda não suporta AVS | |
| 49 | – | 27 | avs.dados-avs.numero | O 3.0 ainda não suporta AVS | |
| 50 | – | 28 | avs.dados-avs.bairro | O 3.0 ainda não suporta AVS | |
| 51 | – | 29 | avs.dados-avs.cep | O 3.0 ainda não suporta AVS |
Tabela da Resposta de Débito
Nessa seção você poderá analisar, campo a campo, cada especificidade das soluções no cenário da resposta de uma requisição de venda por débito.
| Guiar por | solução 3.0 | Guiar por | solução 1.5 | Observações | |
|---|---|---|---|---|---|
| 1 | –Header.MerchantId | 30 | – | O 1.5 não retorna os dados de request no response | |
| 2 | –Header.MerchantKey | 31 | – | O 1.5 não retorna os dados de request no response | |
| 3 | –Header.RequestId | 32 | – | ||
| 4 | MerchantOrderId | 3 | dados-pedido.numero | ||
| 5 | Customer.Name | 33 | – | ||
| 6 | Customer.Email | 34 | – | ||
| 7 | Customer.Birthdate | 35 | – | ||
| 8 | Customer.Address.Street | 36 | – | ||
| 9 | Customer.Address.Number | 37 | – | ||
| 10 | Customer.Address.Complement | 38 | – | ||
| 11 | Customer.Address.ZipCode | 39 | – | ||
| 12 | Customer.Address.City | 40 | – | ||
| 13 | Customer.Address.State | 41 | – | ||
| 14 | Customer.Address.Country | 42 | – | ||
| 15 | Customer.DeliveryAddress.Street | 43 | – | ||
| 16 | Customer.DeliveryAddress.Number | 44 | – | ||
| 17 | Customer.DeliveryAddress.Complement | 45 | – | ||
| 18 | Customer.DeliveryAddress.ZipCode | 46 | – | ||
| 19 | Customer.DeliveryAddress.City | 47 | – | ||
| 20 | Customer.DeliveryAddress.State | 48 | – | ||
| 21 | Customer.DeliveryAddress.Country | 49 | – | ||
| 22 | Payment.Type | 11 | forma-pagamento.produto | ||
| 23 | Payment.Amount | 4 | dados-pedido.valor | ||
| 23 | Payment.Amount | 17 | autenticacao.valor | ||
| 23 | Payment.Amount | 22 | autorizacao.valor | ||
| 24 | CapturedAmount | 29 | captura.valor | ||
| 25 | Payment.Currency | 5 | dados-pedido.moeda | ||
| 26 | Payment.Country | 50 | – | O 1.5 não retorna os dados de request no response | |
| 27 | Payment.Provider | 51 | – | O 1.5 não retorna os dados de request no response | |
| 28 | Payment.SoftDescriptor | 53 | – | O 1.5 não retorna os dados de request no response | |
| 29 | Payment.ReturnUrl | 54 | – | O 1.5 não retorna os dados de request no response | |
| 30 | Payment.ExtraData[] | 55 | – | O 1.5 não retorna os dados de request no response | |
| 31 | Payment.Tid | 1 | tid | ||
| 32 | Payment.ProofOfSale | 25 | autorizacao.nsu | ||
| 33 | Payment.AuthorizationCode | 19 | autorizacao.arp | ||
| 34 | Payment.Status | 13 | status | Os valores retornados pelas aplicações são diferentes | |
| 35 | Payment.ReturnCode | 14 | autenticacao.codigo | No 3.0 existe apenas um campo para código de retorno | |
| 35 | Payment.ReturnCode | 23 | autorizacao.lr | No 3.0 existe apenas um campo para código de retorno | |
| 35 | Payment.ReturnCode | 26 | captura.codigo | No 3.0 existe apenas um campo para código de retorno | |
| 36 | Payment.ReturnMessage | 15 | autenticacao.mensagem | No 3.0 existe apenas um campo para mensagem de retorno | |
| 36 | Payment.ReturnMessage | 20 | autorizacao.mensagem | No 3.0 existe apenas um campo para mensagem de retorno | |
| 36 | Payment.ReturnMessage | 27 | captura.mensagem | No 3.0 existe apenas um campo para mensagem de retorno | |
| 37 | Payment.ReceivedDate | 6 | dados-pedido.data-hora | ||
| 38 | CapturedDate | 28 | captura.data-hora | ||
| 39 | Payment.Eci | 18 | autenticacao.eci | ||
| 40 | Payment.DebitCard.CardNumber | 57 | – | O 1.5 não retorna os dados de request no response | |
| 41 | Payment.DebitCard.Holder | 58 | – | ||
| 42 | Payment.DebitCard.ExpirationDate | 59 | – | O 1.5 não retorna os dados de request no response | |
| 43 | Payment.DebitCard.SecurityCode | 60 | – | O 1.5 não retorna os dados de request no response | |
| 44 | Payment.DebitCard.CardToken | 61 | – | O 1.5 não retorna os dados de request no response | |
| 45 | Payment.DebitCard.SaveCard | 62 | – | O 1.5 não retorna os dados de request no response | |
| 46 | Payment.DebitCard.Brand | 10 | forma-pagamento.bandeira | ||
| 47 | Payment.Links[].Method | 66 | – | O 1.5 não suporta HATEOAS | |
| 48 | Payment.Links[].Rel | 67 | – | O 1.5 não suporta HATEOAS | |
| 49 | Payment.Links[].Href | 68 | – | O 1.5 não suporta HATEOAS | |
| 50 | – | 2 | pan | ||
| 51 | – | 7 | dados-pedido.descricao | ||
| 52 | – | 8 | dados-pedido.idioma | ||
| 53 | – | 16 | autenticacao.data-hora | ||
| 54 | – | 21 | autorizacao.data-hora | ||
| 55 | – | 24 | autorizacao.codigo | ||
| 56 | – | 12 | forma-pagamento.parcelas | ||
| 57 | – | 11 | forma-pagamento.produto | ||
| 58 | – | 9 | dados-pedido.taxa-embarque |
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:
- 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.
