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:

Portal CieloEC -no-filter

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`	<td colspan="3" />
`holder`	Nome do portador impresso no cartão	< 25 AN	NÃO
`external_authentication`	<td colspan="3" />
`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:

Crédito com autenticação CieloEC

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:

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:<br/><br/> `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.<br/><br/>`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: <br/><br/>`ON_SUCCESS` – só realiza a análise se tiver sucesso na transação. <br/>`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: <br/><br/>`ROUND_TRIP` – ida e volta. <br/>`OUTWARD` - ida <br/>`RETURN`- volta.	< 10 AN	NÃO
payer	<td colspan="3" /> Dados adicionais do comprador
`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<br/>.receiver_address	<td colspan="3" /> Dados adicionais do endereço de entrega
`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	<td colspan="3" /> Dados adicionais do navegador
`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[]	<td colspan="3" /> Dados adicionais do produto
`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:<br/><br/>`OFF` - Ignora a análise de risco para endereços divergentes. <br/>`YES` - Em caso de divergência entre endereços de cobrança e entrega, marca com risco pequeno. <br/>`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:<br/><br/>`LOW` - O produto tem um histórico de poucos chargebacks. <br/>`NORMAL` - O produto tem um histórico de chargebacks considerado normal. <br/>`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[]<br/>.hedge	<td colspan="3" /> Dados adicionais da compra do produto
`time`	Nível de importância da hora do dia do pedido do cliente. Pode assumir os seguintes valores: <br/><br/>`LOW` - Baixa importância no horário do dia em que foi feita a compra, para a análise de risco. <br/>`NORMAL` - Média importância no horário do dia em que foi feita a compra, para a análise de risco. <br/>`HIGH` - Alta importância no horário do dia em que foi feita a compra, para a análise de risco. <br/>`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: <br/><br/>`LOW` - Baixa importância do e-mail e endereço IP na análise de risco. <br/>`NORMAL` - Média importância do e-mail e endereço IP na análise de risco. <br/>`HIGH` - Alta importância do e-mail e endereço IP na análise de risco. <br/>`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: <br/><br/>`LOW` - Baixa importância da verificação feita sobre o pedido do comprador, na análise de risco. <br/>`NORMAL` - Média importância da verificação feita sobre o pedido do comprador, na análise de risco. <br/>`HIGH` - Alta importância da verificação feita sobre o pedido do comprador, na análise de risco. <br/>`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:<br/> <br/>`LOW` - Baixa importância da verificação sobre obscenidades do pedido do comprador, na análise de risco. <br/>`NORMAL` - Média importância da verificação sobre obscenidades do pedido do comprador, na análise de risco. <br/>`HIGH`- Alta importância da verificação sobre obscenidades do pedido do comprador, na análise de risco. <br/>`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:<br/><br/>`LOW` - Baixa importância nos testes realizados com números de telefone. <br/>`NORMAL` - Média importância nos testes realizados com números de telefone. <br/>`HIGH` - Alta importância nos testes realizados com números de telefone. <br/>`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: <br/><br/>`LOW` - Baixa importância no número de compras realizadas pelo cliente nos últimos 15 minutos. <br/>`NORMAL` - Média importância no número de compras realizadas pelo cliente nos últimos 15 minutos. <br/>`HIGH` - Alta importância no número de compras realizadas pelo cliente nos últimos 15 minutos. <br/>`OFF` - A frequência de compras realizadas pelo cliente não afeta a análise de fraude.	< 6 AN	NÃO
items[]<br/>.passenger	<td colspan="3" /> Dados adicionais do passageiro
`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: <br/><br/>`ADULT` - Passageiro adulto. <br/>`CHILD` - Passageiro criança. <br/>`INFANT` - Passageiro infantil. <br/>`YOUTH` - Passageiro adolescente. <br/>`STUDENT` - Passageiro estudante. <br/>`SENIOR_CITIZEN` - Passageiro idoso. <br/>`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[]<br/>.passenger<br/>.phone	<td colspan="3" /> Dados adicionais do telefone do passageiro
`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<br/>.acquirer_params[]	<td colspan="3" /> Parâmetros adicionais da adquirente
`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	<td colspan="3" /> Dados sobre o serviço de entrega
`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: <br/><br/>`SAME_DAY` – Serviço de entrega no mesmo dia. <br/>`ONE_DAY` – Serviço de entrega noturna ou no dia seguinte. <br/>`TWO_DAY` – Serviço de entrega em dois dias. <br/>`THREE_DAY` – Serviço de entrega em três dias. <br/>`LOW_COST` – Serviço de entrega de baixo custo. <br/>`PICKUP` – Produto retirado na loja. <br/>`OTHER` – Outro método de entrega. <br/>`NONE` – Sem serviço de entrega, pois é um serviço ou assinatura.	< 9 AN	NÃO
shipment<br/>.phones	<td colspan="3" /> Dados sobre o telefone do destinatário
`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[]	<td colspan="3" /> Dados sobre conexões do voo
`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:

Parâmetro	Descrição	Formato
payment<br/>.analysis	<td colspan="3" /> Dados sobre análise de fraude
`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: <br/><br/>`NOV` – Nova. <br/>`EXP` – Expirada. <br/>`ACC` – Aceita <br/>`REJ` – Rejeitada <br/>`REV` – Em revisão <br/>`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`	<td colspan="3" />
`holder`	Nome do portador impresso no cartão	< 25 AN	NÃO
`external_authentication`	<td colspan="3" />
`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:

Parâmetro	Descrição	Formato
pre_authorization<br/>.analysis	<td colspan="3" /> Dados sobre análise de fraude
`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: <br/><br/>`NOV` – Nova. <br/>`EXP` – Expirada. <br/>`ACC` – Aceita <br/>`REJ` – Rejeitada <br/>`REV` – Em revisão <br/>`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:

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	<td colspan="3" /> Elemento para envio de dados adicionais.
`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	<td colspan="3" /> Elemento para envio de dados referentes ao lojista de uma subadquirente.
`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<br/> <URLPOSTMAN/>

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<br/> <URLPOSTMAN/>

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