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

Ambiente Sandbox

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: