Cielo

A loja tem a possibilidade de configurar o roteamento de transações feitas com cartão de crédito no Carat por vários meios de pagamento, um desses meios é o Cielo e-Commerce.

Nesta página será usada a nomenclatura "CieloEC" para referenciar o roteamento no Carat.

Assim, a loja pode configurar o Carat para que as transações feitas com cartões VISA, por exemplo, sejam roteadas pela CieloEC enquanto que as feitas com MASTERCARD sejam roteadas pela CIELO.

Interfaces Carat suportadas para integração

É possível utilizar as seguintes interfaces para a integração com o roteamento CieloEC:

• Interface Pré Autorização REST
• Interface Pagamento REST
• Interface Cancelamento REST
• Interface Pagamento HTML
• Interface Pré-Autorização HTML

Observação: Esta integração também aceita o envio de dados de autenticação 3DS (eci, reference_id e cavv). Saiba mais.

Autorizadoras permitidas

As seguintes autorizadoras são suportadas pelo roteamento CieloEC:

• CRÉDITO

  • VISA (1)
  • MASTERCARD (2)
  • AMERICAN EXPRESS (3)
  • ELO (41)
  • AURA (6)
  • JCB (43)
  • DINERS (33)
  • DISCOVER (44)

• DÉBITO

  • VISA ELECTRON (221)
  • MASTERCARD DÉBITO (286)

• TRANSFERÊNCIA

  • BRADESCO (8)
  • BANCO DO BRASIL (408)

• ZERO DÓLLAR

  • VISA (1)
  • VISA ELECTRON (221)
  • MASTERCARD (2)
  • MASTERCARD DÉBITO (286)
  • ELO (41)

Credenciais necessárias

A loja deve obter com a CieloEC as credenciais listadas abaixo, e repassá-las à Software Express ou fazer o cadastro como explicado mais a frente neste mesmo documento.

Campo	Descrição	Formato
merchantID	Identificador da loja na CieloEC.	< 36 AN
merchantKey	Chave pública para a autenticação dupla na CieloEC.	< 40 AN

Importante para Pagamento HTML: No caso de uma autorizadora da loja não ter cadastrado essas credenciais, essa autorizadora não será exibida na tela de seleção de cartão de crédito durante a operação de pagamento.

Cadastro das informações pelo portal do lojista

O próprio lojista pode cadastrar as informações obtidas com a CieloEC no Portal do Lojista do Carat. Para essa finalidade, o lojista deve selecionar a autorizadora e entrar na tela de edição como no exemplo exibido abaixo:

Cadastro do SoftDescriptor no Carat

O cadastro do softDescriptor é opcional, possui tamanho 13, não aceita caracteres especiais e está disponível apenas para Visa e Mastercard.

Fluxos

Nesta seção serão apresentadas as particularidades do fluxo transacional CieloEC.

Pagamento REST

Essa interface suporta o envio da de campos de autenticação externa

Crédito

É possível enviar os seguintes campos na etapa de efetivação do pagamento:

Parâmetro	Descrição	Formato	Obrigatório
card
holder	Nome do portador impresso no cartão	< 25 AN	NÃO
external_authentication
eci	Eletronic Commerce Indicator – indica o nível de segurança da transação com autenticação do dono do cartão	< 3 N	NÃO
xid	Identificador da transação de autenticação do dono do cartão no 3DS, feita em serviço externo ao Carat (No nosso 3DS o xid é referenciado pelo three_ds_server.trans_id no retorno do serviço de criação da transação do 3DS )	< 40 N	Condicional (uso obrigatório apenas para transações autenticadas por 3DS 2.0)
cavv	Cardholder Authentication Verification Value - Código que indica o resultado da autenticação do dono do cartão.	< 40 N	NÃO
version	Versão do 3DS utilizado no processo de autenticação.	1 AN	SIM para versão 2 do 3DS
reference_id	RequestID retornado no processo de autenticação.	36 AN	SIM para versão 2 do 3DS

Crédito com autenticação

É possível enviar o seguinte campo na etapa de criação da transação:

Parâmetro	Descrição	Formato	Obrigatório
authorizer_authentication	Define se o lojista deseja um pagamento com autenticação. Enviar true caso positivo.	< 5 AN	SIM para crédito com autenticação

Caso o pagamento seja bem sucedido, o serviço retornará a transação com status PEN (pendente) e terá o seguinte campo:

Parâmetro	Descrição	Formato
authentication_url	URL para qual o lojista deve redirecionar o comprador para a realização da autenticação.	< 56 AN

Após uma autenticação bem sucedida, o pagamento estará sempre confirmado (status CON), ou seja, não é possível um crédito com autenticação sem auto confirmação.

Na imagem abaixo é possível verificar o funcionamento do fluxo de uma transação com autenticação:

Débito

Com exceção das transações efetuadas por meio do Corona Voucher, todas as operações de débito sempre exigem autenticação e, com isso, independem do envio do campo authorizer_authentication. O fluxo a ser seguido é o mesmo de um crédito com autenticação.

Toda operação de débito é auto-confirmada, logo não permitimos realizar débito com confirmação tardia.

Crédito com análise de fraude

Para realizar um crédito com análise de fraude, é necessário enviar o campo additional_data contendo informações adicionais para anti-fraude. Seu valor segue o formato JSON conforme o exemplo abaixo:

{

"amount":"1000",

"authorizer_id":"1",

"installments":"1",

"installment_type":"4",

"additional_data":{

"payer":{

"name":"Comprador",

"surname":"credito AF",

"email":"compradorteste@live.com",

"city":"Rio de Janeiro",

"state":"RJ",

"address_street_name":"Rua Jupiter",

"address_street_number":"174",

"address_zip_code":"21241140",

"born_date":"1991-01-02T08:30:00",

"address_street_complement":"AP 201",

"address_country":"BRA"

},

"shipment":{

"method":"LOW_COST",

"name":"Sr Comprador Teste",

"phones":[

{

"number":"21114740",

"ddd":"16",

"ddi":"55"

}

],

"receiver_address":{

"complement":"AP 201",

"city":"Rio de Janeiro",

"state":"RJ",

"country":"BRA",

"zip_code":"21241140",

"street_number":"174",

"street_name":"Rua Jupiter"

}

},

"connections":[

{

"from":"RAO",

"to":"SAO",

"flight_date":"2020-01-02T20:15:00"

}

],

"gift":"false",

"browser":{

"email":"compradorteste@live.com",

"agent":"Chrome",

"cookies_accepted":"false",

"host_name":"Teste",

"ip_address":"200.190.150.350"

},

"items":[

{

"title":"ItemTeste",

"quantity":"1",

"id":"1487337308522",

"risk":"HIGH",

"hedge":{

"time":"NORMAL",

"host":"OFF",

"nonSensical":"OFF",

"obscenities":"OFF",

"phone":"OFF",

"velocity":"HIGH"

},

"passenger":{

"name":"Comprador accept",

"email":"compradorteste@live.com",

"rating":"ADULT",

"phone":{

"number":"999994444",

"ddd":"11",

"ddi":"55"

},

"legal_document":"1234567890",

"customer_class":"Gold"

},

"unit_price":"1000",

"category_id":"other",

"gift_category":"OFF"

}

],

"extra_param":{

"acquirer_params":[

{

"key":"95",

"value":"Eu defini isso"

}

]

},

"anti_fraud":"enabled_before_auth",

"anti_fraud_institution":"AUTHORIZER",

"anti_fraud_criteria":"ALWAYS",

"finger_print_id":"074c1ee676ed4998ab66491013c565e2",

"returns_accepted":"true",

"journey_type":"OUTWARD"

}

}

Na tabela a seguir estão descritos os campos do JSON:

Dados adicionais do comprador Dados adicionais do endereço de entrega Dados adicionais do navegador Dados adicionais do produto Dados adicionais da compra do produto Dados adicionais do passageiro Dados adicionais do telefone do passageiro Parâmetros adicionais da adquirente Dados sobre o serviço de entrega Dados sobre o telefone do destinatário Dados sobre conexões do voo

Parâmetro	Descrição	Formato	Obrigatório
anti_fraud_institution	Instituição que efetuará a análise de fraude para a loja. Deve ser enviado com o valor AUTHORIZER.	< 10 AN	SIM para análise de fraude
anti_fraud	Habilita o serviço de análise de fraude. Valores permitidos: enabled_before_auth – a análise de fraude será realizada ANTES da autorização do pagamento. Caso a análise seja rejeitada, o pagamento não será iniciado. enabled_after_auth – a análise de fraude será realizada APÓS a autorização do pagamento. Caso a análise seja rejeitada, o pagamento que já foi autorizado será cancelado.	< 19 AN	SIM para análise de fraude
anti_fraud_criteria	Critério de execução da análise de fraude. Valores permitidos: ON_SUCCESS – só realiza a análise se tiver sucesso na transação. ALWAYS – sempre realiza a análise.	< 10 AN	NÃO
finger_print_id	Identificador utilizado para cruzar informações obtidas pelo Browser do internauta com os dados enviados para análise. Saiba mais	< 50 AN	NÃO
gift	Indica se o pedido é para presente ou não.	< 5 T/F	NÃO
returns_accepted	Define se devoluções são aceitas para o pedido.	< 5 T/F	NÃO
journey_type	Tipo de viagem. Valores permitidos: ROUND_TRIP – ida e volta. OUTWARD - ida RETURN- volta.	< 10 AN	NÃO
payer
name	Nome do comprador. Obs.: a concatenação de nome com o sobrenome não pode ultrapassar 255 caracteres.	< 200 AN	NÃO
surname	Sobrenome do comprador. Obs.: a concatenação de nome com o sobrenome não pode ultrapassar 255 caracteres.	< 200 AN	NÃO
email	E-mail do comprador.	< 255 AN	NÃO
born_date	Data de nascimento do comprador, no formato YYYY-MM-DDTHH:MM:SS Ex.: 1991-01-02T08:30:00	19 AN	NÃO
adress_street_name	Endereço do comprador.	< 255 AN	NÃO
adress_street_number	Número do endereço do comprador.	< 15 AN	NÃO
adress_street_complement	Complemento do endereço do comprador.	< 50 AN	NÃO
adress_zip_code	CEP do endereço do comprador. Ex.: 21241140.	< 9 AN	NÃO
city	Cidade do endereço do comprador.	< 9 AN	NÃO
state	Estado do endereço do comprador. Ex. SP	2 AN	NÃO
addres_country	País do endereço do comprador. Ex. BRA	< 35 AN	NÃO
shipment .receiver_address
street_name	Endereço de entrega.	< 255 AN	NÃO
street_number	Número do endereço de entrega.	< 15 AN	NÃO
complement	Complemento do endereço de entrega.	< 50 AN	NÃO
zip_code	CEP do endereço de entrega. Ex.: 21241-140.	< 9 AN	NÃO
city	Cidade do endereço de entrega.	< 50 AN	NÃO
state	Estado do endereço de entrega.	< 2 AN	NÃO
country	País do endereço de entrega seguindo a ISO 3166-1. Ex.: BRA	3 AN	NÃO
browser
cookies_accepted	Identifica se o browser do cliente aceita cookies. Enviar ‘true’ caso positivo.	< 5 AN	NÃO
email	E-mail registrado no browser do comprador.	< 100 AN	NÃO
host_name	Nome do host onde o comprador estava antes de entrar no site da loja.	< 60 AN	NÃO
ip_address	Endereço IP do comprador. É altamente recomendável o envio deste campo.	< 15 AN	NÃO
agent	Nome do browser utilizado pelo comprador. Ex.: Chrome.	< 40 AN	NÃO
items[]
gift_category	Campo que avaliará os endereços de cobrança e entrega para diferentes cidades, estados ou países. Pode assumir os seguintes valores: OFF - Ignora a análise de risco para endereços divergentes. YES - Em caso de divergência entre endereços de cobrança e entrega, marca com risco pequeno. NO - Em caso de divergência entre endereços de cobrança e entrega, marca com risco alto.	< 3 AN	NÃO
risk	Nível do risco do produto. Pode assumir os seguintes valores: LOW - O produto tem um histórico de poucos chargebacks. NORMAL - O produto tem um histórico de chargebacks considerado normal. HIGH - O produto tem um histórico de chargebacks acima da média.	< 6 AN	NÃO
title	Nome do produto.	< 255 AN	NÃO
quantity	Quantidade do produto a ser adquirido.	< 15 N	NÃO
id	Código comerciante identificador do produto.	< 255 AN	NÃO
unit_price	Preço unitário do produto em centavos.	< 15 N	NÃO
category_id	Tipo do produto. Pode assumir os seguintes valores: art, baby, coupon, donation, computing, camera, video_game, television, car_electronic, electronic, automotive, entertainment, fashion, game, home, musical, phone, service, learning, ticket, travel, virtual_good, physical, other, adult_content, gift_certificate, handling, shipping, shipping_and_handling ou subscription	< 21 AN	NÃO
items[] .hedge
time	Nível de importância da hora do dia do pedido do cliente. Pode assumir os seguintes valores: LOW - Baixa importância no horário do dia em que foi feita a compra, para a análise de risco. NORMAL - Média importância no horário do dia em que foi feita a compra, para a análise de risco. HIGH - Alta importância no horário do dia em que foi feita a compra, para a análise de risco. OFF - O horário da compra não afeta a análise de risco.	< 6 AN	NÃO
host	Nível de importância do e-mail e endereços IP dos clientes em risco de pontuação. Pode assumir os seguintes valores: LOW - Baixa importância do e-mail e endereço IP na análise de risco. NORMAL - Média importância do e-mail e endereço IP na análise de risco. HIGH - Alta importância do e-mail e endereço IP na análise de risco. OFF - E-mail e endereço IP não afetam a análise de risco.	< 6 AN	NÃO
non_sensical	Nível dos testes realizados sobre os dados do comprador com pedidos recebidos sem sentido. Pode assumir os seguintes valores: LOW - Baixa importância da verificação feita sobre o pedido do comprador, na análise de risco. NORMAL - Média importância da verificação feita sobre o pedido do comprador, na análise de risco. HIGH - Alta importância da verificação feita sobre o pedido do comprador, na análise de risco. OFF - Verificação do pedido do comprador não afeta a análise de risco.	< 6 AN	NÃO
obscenities	Nível de obscenidade dos pedidos recebidos. Pode assumir os seguintes valores: LOW - Baixa importância da verificação sobre obscenidades do pedido do comprador, na análise de risco. NORMAL - Média importância da verificação sobre obscenidades do pedido do comprador, na análise de risco. HIGH- Alta importância da verificação sobre obscenidades do pedido do comprador, na análise de risco. OFF - Verificação de obscenidade no pedido do comprador não afeta a análise de risco.	< 6 AN	NÃO
phone	Nível dos testes realizados com os números de telefones. Pode assumir os seguintes valores: LOW - Baixa importância nos testes realizados com números de telefone. NORMAL - Média importância nos testes realizados com números de telefone. HIGH - Alta importância nos testes realizados com números de telefone. OFF - Testes de números de telefone não afetam a análise de risco.	< 6 AN	NÃO
velocity	Nível de importância de frequência de compra do cliente. Pode assumir os seguintes valores: LOW - Baixa importância no número de compras realizadas pelo cliente nos últimos 15 minutos. NORMAL - Média importância no número de compras realizadas pelo cliente nos últimos 15 minutos. HIGH - Alta importância no número de compras realizadas pelo cliente nos últimos 15 minutos. OFF - A frequência de compras realizadas pelo cliente não afeta a análise de fraude.	< 6 AN	NÃO
items[] .passenger
email	E-mail do passageiro.	< 255 AN	NÃO
legal_document	Id do passageiro a quem o bilhete foi emitido.	< 32 AN	NÃO
name	Nome do passageiro.	< 120 AN	NÃO
rating	Classificação do passageiro. Pode assumir os seguintes valores: ADULT - Passageiro adulto. CHILD - Passageiro criança. INFANT - Passageiro infantil. YOUTH - Passageiro adolescente. STUDENT - Passageiro estudante. SENIOR_CITIZEN - Passageiro idoso. MILITARY - Passageiro militar.	< 14 AN	NÃO
customer_class	Classificação da empresa aérea. Pode-se usar valores como Gold ou Platina.	< 32 AN	NÃO
items[] .passenger .phone
ddi	Código do país do telefone do passageiro. Para pedidos fora dos EUA, é recomendável o envio deste campo.	< 3 N	NÃO
ddd	Código da área do telefone do passageiro.	< 3 N	NÃO
number	Número de telefone do passageiro.	< 9 N	NÃO
extra_param .acquirer_params[]
key	Id das informações adicionais a serem enviadas.	< 1024 N	NÃO
value	Valor das informações adicionais a serem enviadas.	< 1024 AN	NÃO
shipment
name	Nome do destinatário da entrega.	< 255 AN	NÃO
method	Tipo de serviço de entrega do produto. Pode assumir os seguintes valores: SAME_DAY – Serviço de entrega no mesmo dia. ONE_DAY – Serviço de entrega noturna ou no dia seguinte. TWO_DAY – Serviço de entrega em dois dias. THREE_DAY – Serviço de entrega em três dias. LOW_COST – Serviço de entrega de baixo custo. PICKUP – Produto retirado na loja. OTHER – Outro método de entrega. NONE – Sem serviço de entrega, pois é um serviço ou assinatura.	< 9 AN	NÃO
shipment .phones
ddi	Código do país do telefone do destinatário da entrega. Para pedidos fora dos E.U.A., é recomendável o envio deste campo.	< 3 AN	NÃO
ddd	Código da área do telefone do destinatário da entrega.	< 3 AN	NÃO
number	Número de telefone do destinatário da entrega.	< 9 AN	NÃO
connections[]
flight_date	Data, hora e minuto de partida do voo no formato YYYY-MM-DDTHH:MM:SS Ex.: 1991-01-02T08:30:00	< 19 AN	NÃO
from	Código do aeroporto do ponto de origem da viagem. Ex.: CGH.	< 3 AN	NÃO
to	Código do aeroporto do ponto de destino da viagem. Ex.: GYN.	< 3 AN	NÃO

O retorno do pagamento contará com os seguintes campos adicionais:

Dados sobre análise de fraude

Parâmetro	Descrição	Formato
payment .analysis
code	Código de resposta da operação de análise de fraude.	< 4 N
message	Mensagem de resposta da operação de análise de fraude.	< 200 AN
status	Status da transação de análise de fraude do Carat. Este campo pode assumir os seguintes valores: NOV – Nova. EXP – Expirada. ACC – Aceita REJ – Rejeitada REV – Em revisão INV – Inválida	= 3 AN

Zero Dóllar

A chamada do Zero Dóllar consiste numa chamada de pagamento com o campo amount com valor igual a zero e pode ser efetuada para Visa, Mastercard e Elo, Crédito e Débito, utilizando a interface REST.

Pagamento HTML

Os tópicos abaixo se referem à etapa de criação da transação, em que o lojista envia um documento JSON para o Carat. Para mais informações sobre como efetuar um pagamento pela interface HTML, consulte a página de pagamento via HTML.

Crédito

Nenhuma particularidade em relação a outros meios de pagamento.

Crédito com autenticação

Para realizar um crédito com autenticação, o parâmetro abaixo deve ser enviado: | Parâmetro | Descrição | Formato | Obrigatório | | :-: | :- | :-: | :-: | | authorizer_authentication | Define se o lojista deseja um pagamento com autenticação. Enviar true caso positivo ou false caso contrário. Este campo deve ser enviado com o valor true caso se deseje confirmar a transação, ou false, caso queira desfazer o pagamento. | < 5 AN | SIM para crédito com autenticação |

Exemplo:

{

"merchant_id": "LOJATESTE",

"order_id": "20150925001",

"amount": "1000",

"transaction_type": "payment",

"authorizer_authentication": "true"

}

Débito

Operações de débito sempre exigem autenticação e, com isso, independem do envio do campo authorizer_authentication.

Toda operação de débito é auto-confirmada, logo não permitimos realizar débito com confirmação tardia.

Crédito com análise de fraude

O lojista deverá enviar no elemento additional_data os campos referentes à análise de fraude. Exemplo:

{

"merchant_id": "LOJACIELOEC",

"merchant_usn": "9876",

"order_id": "11",

"redirect": "M",

"authorizer_id": "",

"amount": "1000",

"installments": "",

"installment_type": "",

"style": "N",

"soft_descriptor": "",

"transaction_type": "payment",

"back_url": {

"url_success": "lojateste/loja/loja-index.jsp?pagina=sucesso",

"url_failure": "lojateste/loja/loja-index.jsp?pagina=fracasso",

"url_cancel": "lojateste/loja/loja-index.jsp?pagina=fracasso"

},

"additional_data": {

"payer": {

"name": "Comprador",

"surname": "credito AF",

"email": "compradorteste@live.com",

"city": "Rio de Janeiro",

"state": "RJ",

"address_street_name": "Rua Jupiter",

"address_street_number": "174",

"address_zip_code": "21241140",

"born_date": "1991-01-02T08:30:00",

"address_street_complement": "AP 201",

"address_country": "BRA"

},

"shipment": {

"method": "LOW_COST",

"name": "Sr Comprador Teste",

"phones": [

{

"number": "21114740",

"ddd": "16",

"ddi": "55"

}

],

"receiver_address": {

"complement": "AP 201",

"city": "Rio de Janeiro",

"state": "RJ",

"country": "BRA",

"zip_code": "21241140",

"street_number": "174",

"street_name": "Rua Jupiter"

}

},

"connections": [

{

"from": "RAO",

"to": "SAO",

"flight_date": "2020-01-02T20:15:00"

}

],

"gift": "false",

"browser": {

"email": "compradorteste@live.com",

"agent": "Chrome",

"cookies_accepted": "false",

"host_name": "Teste",

"ip_address": "200.190.150.350"

},

"items": [

{

"title": "ItemTeste",

"quantity": "1",

"id": "1488392648367",

"risk": "HIGH",

"hedge": {

"time": "NORMAL",

"host": "OFF",

"17efine17ical": "OFF",

"obscenities": "OFF",

"phone": "OFF",

"velocity": "HIGH"

},

"passenger": {

"name": "Comprador accept",

"email": "compradorteste@live.com",

"rating": "ADULT",

"phone": {

"number": "999994444",

"ddd": "11",

"ddi": "55"

},

"legal_document": "1234567890",

"customer_class": "Gold"

},

"unit_price": "1000",

"category_id": "other",

"gift_category": "OFF"

}

],

"extra_param": {

"acquirer_params": [

{

"key": "95",

"value": "Eu 17efine isso"

}

]

},

"anti_fraud": "enabled_before_auth",

"anti_fraud_institution": "AUTHORIZER",

"anti_fraud_criteria": "ALWAYS",

"finger_print_id": "074c1ee676ed4998ab66491013c565e2",

"returns_accepted": "true",

"journey_type": "OUTWARD"

}

}

Transferência Eletrônica

Nenhuma particularidade em relação a outros meios de pagamento.

Pré-Autorização REST

Crédito

É possível enviar o campo abaixo na etapa de efetivação da pré-autorização:

Parâmetro	Descrição	Formato	Obrigatório
card
holder	Nome do portador impresso no cartão	< 25 AN	NÃO
external_authentication
eci	Eletronic Commerce Indicator – indica o nível de segurança da transação com autenticação do dono do cartão	< 3 N	NÃO
xid	Identificador da transação de autenticação do dono do cartão no 3DS, feita em serviço externo ao Carat (No nosso 3DS o xid é referenciado pelo three_ds_server.transId no retorno do serviço de criação da transação do 3DS )	< 40 N	Condicional (uso obrigatório apenas para transações autenticadas por 3DS 2.0)
cavv	Cardholder Authentication Verification Value - Código que indica o resultado da autenticação do dono do cartão.	< 40 N	NÃO
version	Versão do 3DS utilizado no processo de autenticação.	1 AN	SIM para versão 2 do 3DS
reference_id	RequestID retornado no processo de autenticação.	36 AN	SIM para versão 2 do 3DS

Crédito com análise de fraude

Para realizar um crédito com análise de fraude, é necessário enviar o campo additional_data contendo informações adicionais de anti-fraude. O formato de seu valor é o mesmo descrito aqui.

No retorno da pré-autorização, serão devolvidos adicionalmente os seguintes campos:

Dados sobre análise de fraude

Parâmetro	Descrição	Formato
pre_authorization .analysis
code	Código de resposta da operação de análise de fraude.	< 4 N
message	Mensagem de resposta da operação de análise de fraude.	< 200 AN
status	Status da transação de análise de fraude do Carat. Este campo pode assumir os seguintes valores: NOV – Nova. EXP – Expirada. ACC – Aceita REJ – Rejeitada REV – Em revisão INV – Inválida	= 3 AN

Parcelamento

Dados de parcelamento devem ser enviados na etapa de efetivação da pré-autorização e caso não sejam enviados, o Carat assume que a transação é à vista. Em seguida, na captura, os mesmos dados de parcelamento devem ser enviados.

Pré-Autorização HTML

Os tópicos abaixo se referem à etapa de criação da transação, em que o lojista envia um documento JSON para o Carat. Para mais informações sobre como efetuar uma pré-autorização pela interface HTML, consulte a página de pré-autorização.

Crédito com/sem análise de fraude

Os parâmetros a serem enviados seguem o mesmo formato de um pagamento HTML.

Parcelamento

Na etapa de captura, os mesmos dados de parcelamento utilizados na pré-autorização devem ser enviados.

Cancelamento REST

Saiba mais sobre essa interface.

Cartões de testes

A Cielo disponibiliza o seguinte número de cartão para testes:

Bandeira	Número do Cartão	Vencimento	CVV
VISA	4024007197692931	12/2022	123

Restrições

O roteamento CieloEC não suporta pagamentos do tipo IATA (International Air Transport Association).

Campos de MCC Dinâmico

Inicialização da transação de pagamento ou de pré-autorização REST

Parâmetros de requisição

Adicionalmente aos campos mencionados no Serviço de criação de transação REST, os campos abaixo são usados no cenário específico de MCC dinâmico da integração com o Cielo ECommerce:

Elemento para envio de dados adicionais. Elemento para envio de dados referentes ao lojista de uma subadquirente.

Parâmetro	Descrição	Formato	Obrigatório
soft_descriptor	Frase personalizada que será impressa na fatura do portador. Para informação referente ao MCC dinâmico, equivale ao nome do sublojista.	< 18 AN	SIM
additional_data
mcc	MCC do sublojista.	= 4 N	SIM
subacquirer_merchant_id	Código do sublojista. Campo legado!!! Dar preferência ao additional_data.subacquirer_merchant.id	< 15 N	NÃO
additional_data.subacquirer_merchant
id	Código do sublojista.	< 15 N	SIM
phone_number	Número de Telefone do sublojista.	< 14 AN	NÃO
address	Endereço do sublojista.	< 48 AN	NÃO
city	Cidade do sublojista.	< 13 AN	NÃO
state	Estado do sublojista, em formato de sigla de dois dígitos (ex.: SP).	= 2 A	SIM
country	País do sublojista. Seguir o padrão ISO 3166-1 alpha-2 (ex.: BR).	= 2 A	SIM
zip_code	Código postal do sublojista.	< 9 AN	SIM
identification_number	CNPJ do sublojista.	< 18 N	SIM
payment_facilitator_id	Código do facilitador.	< 11 N	SIM

Exemplo

Requisição:

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br

curl

--request POST "https://{{url}}/e-sitef/api/v1/transactions"

--header "Content-Type: application/json"

--header "merchant_id: xxxxxxxx"

--header "merchant_key: xxxxxxxxxxx"

--data-binary

{

"merchant_usn": "19035815234",

"order_id": "1616438400044",

"installments": "1",

"installment_type": "4",

"authorizer_id": "2",

"amount": "1300",

"soft_descriptor": "L012121",

"additional_data": {

"mcc": "1111",

"subacquirer_merchant": {

"id": "12345",

"address": "Avenida Paulista, 2000",

"city": "São Paulo",

"state": "SP",

"country": "BR",

"zip_code": "01107001",

"identification_number": "53455823000178",

"payment_facilitator_id": "654321",

"phone_number": "+55 11 99999-9999"

}

}

}

Resposta:

{

"code": "0",

"message": "OK. Transaction successful.",

"payment": {

"status": "NOV",

"nit": "6215a32a557f5dc4627b540f517e40abd6a8411cf89a2e073913aa25d7c95590",

"order_id": "1616438400044",

"merchant_usn": "19035815234",

"amount": "1300"

}

}

Parâmetros na efetivação do pagamento ou da pré-autorização REST

Adicionalmente aos campos mencionados nos Serviço de efetivação de pagamento REST e Serviço de efetivação de Pré-Autorização REST, os campos abaixo são usados no cenário específico de MCC dinâmico da integração com a Cielo EC:

Parâmetro	Descrição	Formato	Obrigatório
soft_descriptor	Frase personalizada que será impressa na fatura do portador. Para informação referente ao MCC dinâmico, equivale ao nome do sublojista. Obrigatório somente se não foi enviado no soft_descriptor da etapa de inicialização da transação.	< 18 AN	COND.
mcc	MCC do sublojista. Obrigatório somente se não foi enviado no additional_data.mcc da etapa de inicialização da transação.	= 4 N	COND.
subacquirer_merchant_id	Código do sublojista. Obrigatório somente se não foi enviado no additional_data.subacquirer_merchant.id da etapa de inicialização da transação.	< 15 N	COND.

ATENÇÃO!

É na efetivação que enviamos os dados acumulados de MCC dinâmico. Porém, se o campo mcc não for enviado em nenhum momento nem estiver cadastrado, os outros campos de MCC dinâmico não serão repassados. Este campo é necessário para identificar que o lojista deseja enviar dados de subadquirência.

Exemplo

Requisição:

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br

curl

--request POST "https://{{url}}/e-sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"

--header "Content-Type: application/json"

--header "merchant_id: xxxxxxxx"

--header "merchant_key: xxxxxxxxxxx"

--data-binary

{

"card": {

"number": "4024007197692931",

"expiry_date": "1222",

"security_code": "123"

}

}

Resposta:

{

"code": "0",

"message": "OK. Transaction successful.",

"payment": {

"authorizer_code": "6",

"authorizer_message": "Operation Successful",

"status": "CON",

"nit": "6215a32a557f5dc4627b540f517e40abd6a8411cf89a2e073913aa25d7c95590",

"order_id": "1616438400044",

"customer_receipt":"=== CUSTOMER RECEIPT ===",

"merchant_receipt":"=== MERCHANT RECEIPT ===",

"authorizer_id": "2",

"acquirer_id": "201",

"acquirer_name": "Cielo e-Commerce",

"authorizer_date": "22/03/2021T15:40",

"authorization_number": "316176",

"merchant_usn": "19035815234",

"esitef_usn": "210322068747730",

"host_usn": "362400",

"tid": "9fcd1663-0662-4761-9b9b-b269217cfc32",

"amount": "1300",

"payment_type": "C",

"authorizer_merchant_id": "6d29e58f-b29f-4e7e-8bf2-4d53b71acc1e",

"payment_date": "22/03/2021T15:40"

}

}

Tabela de correspondência de campos

Segue abaixo a tabela de correspondência entre os campos de MCC dinâmico definidos pela interface do Cielo ECommerce e os campos do Carat.

Campo Cielo EC	Campo Carat	Observações
Softdescriptor(1)	soft_descriptor	O campo soft_descriptor do Carat pode ser enviado na etapa de criação da transação ou cadastrado pela equipe de atendimento do Carat.
EstablishmentCode(3)	additional_data / subacquirer_merchant / payment_facilitator_id ou paymentFacilitatorId	O campo PaymentFacilitatorID do Cielo ECommerce pode ser enviado na etapa de criação da transação ou ser configurado quando um roteamento de uma autorizadora é feito via e.Rede REST. Neste último caso, o seu valor pode ser alterado pelo Portal do Lojista ("Autorizadoras" > "Configurar Autorizadoras") ou por solicitacão à equipe de atendimento do Carat.
Mcc(2)	additional_data / mcc ou mcc	O campo mcc do Carat pode ser enviado na etapa de criação da transação, na efetivação do pagamento ou da pré-autorização REST ou cadastrado pela equipe de atendimento do Carat.
EstablishmentCode(2)	additional_data / subacquirer_merchant_id ou additional_data / subacquirer_merchant / id ou subacquirer_merchant_id ou subacquirerMerchantId	O campo SubMerchant / SubMerchantID pode ser enviado na etapa de criação da transação, na efetivação do pagamento ou da pré-autorização REST ou ser configurado quando um roteamento de uma autorizadora é feito via Cielo ECommerce. Neste último caso, o seu valor pode ser alterado pelo Portal do Lojista ("Autorizadoras" > "Configurar Autorizadoras") ou por solicitacão à equipe de atendimento do Carat.
Identity(2)	additional_data / subacquirer_merchant / identification_number	Este campo pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do Carat para cadastrar ou alterar o valor padrão deste campo em sua loja.
Address(2)	additional_data / subacquirer_merchant / address	Este campo pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do Carat para cadastrar ou alterar o valor padrão deste campo em sua loja.
City(2)	additional_data / subacquirer_merchant / city	Este campo pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do Carat para cadastrar ou alterar o valor padrão deste campo em sua loja.
State(2)	additional_data / subacquirer_merchant / state	Este campo pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do Carat para cadastrar ou alterar o valor padrão deste campo em sua loja.
CountryCode(2)	additional_data / subacquirer_merchant / country	Este campo pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do Carat para cadastrar ou alterar o valor padrão deste campo em sua loja.
PostalCode(2)	additional_data / subacquirer_merchant / zip_code	Este campo pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do Carat para cadastrar ou alterar o valor padrão deste campo em sua loja.
PhoneNumber(2)	additional_data / subacquirer_merchant / phone_number	Este campo pode ser enviado na criação da transação. É possível cadastrar um valor padrão. Entre em contato com o atendimento do Carat para cadastrar ou alterar o valor padrão deste campo em sua loja.

Legenda das estruturas
(1) Estrutura Payment
(2) Estrutura PaymentFacilitator.SubEstablishment
(3) Estrutura PaymentFacilitator