Serviço de criação da transação
O consumo do serviço de criação de transação é obrigatório nos fluxos de pagamento e agendamento. Como resultado dessa operação, o lojista obterá um NIT (pagamento) e/ou um SID (agendamento) que serão necessários para os próximos passos do fluxo, assim como a utilização do serviço de consulta de transações.
O NIT e o SID possuem um tempo limite para sua utilização. Este prazo está configurado na API, e caso seja excedido, a transação passará do status NOV (nova) para EXP (expirada), que impede futuras operações com essa transação, tornando necessário consumir novamente o serviço de criação de transação.
Detalhes da chamada#
- Recurso:
/v1/transactions - Método HTTP:
POST - Formato da requisição:
JSON - Formato da resposta:
JSON - Parâmetros de cabeçalho:
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
merchant_id | Código da loja no Carat. Os códigos de produção e certificação serão diferentes. | < 15 AN | SIM |
merchant_key | Chave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes. | < 80 AN | SIM |
Content-Type | Deve ser enviado com o valor application/json. | = 15 AN | SIM |
Exemplos#
Abaixo estão alguns exemplos de chamada do serviço de criação de transações utilizando a ferramenta cURL.
Criação de pagamento com confirmação automática#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
Criação de pagamento com confirmação tardia#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
Criação de pagamento com agendamento#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
Criação de agendamento sem pagamento#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
Criação de pagamento com análise de risco Cielo e-Commerce #
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
Criação de pagamento com análise de risco (utlizando o anti fraude Konduto)#
Para mais informações verifique nossa seção específica da Konduto
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
Códigos de resposta
Veja a referencia no Códigos da API - códigos de resposta
Parâmetros de requisição#
Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de criação de transações:
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
merchant_usn | Número sequencial único para cada pedido, criado pela loja. O NSU será utilizado em toda a comunicação com a loja, de forma a identificar o pedido. Como se trata de uma possível chave para acesso do lado da loja, apesar de ser opcional para o Carat, é fortemente recomendado que o campo seja formatado e enviado pela aplicação da loja. | < 12 N | NÃO |
order_id | Código do pedido para ser exibido ao comprador, definido pelo lojista. É aconselhável que seja diferente a cada pedido para que facilite a rastreabilidade. Se a integração da Loja com as redes adquirentes (Cielo, Redecard, etc) for com Carat e SiTef, o campo orderId que tem o tamanho máximo de 40 caracteres, será reduzido a 12 caracteres, devido a uma restrição do SiTef. Essa redução será realizada mantendo os caracteres da esquerda para direita (ex.: se um código de pedido inserido for 12345678901234567890 no Carat, no SiTef ele será apenas 123456789012). | < 40 AN | NÃO |
installments | Número de parcelas. Envie ‘1’ para transações à vista. | < 2 N | SIM |
installment_type | Tipo de financiamento do parcelamento: valor 3 = parcelamento com juros da administradora do cartão. valor 4 = parcelamento realizado pela loja e sem juros (adotar este valor como padrão/default para transações à vista). Valor 6 = parcelamento com juros da administradora (IATA). valor 7 = parcelamento realizado pela loja e sem juros (IATA). O parcelamento IATA é utilizado somente por empresas do seguimento de transporte aéreo. | < 2 N | SIM |
authorizer_id | Código da autorizadora no Carat. Saiba mais. Nas operações com cartão tokenizado, se o codigo da autorizadora não for informado, será usado o código da autorizadora usado no armazenamento do cartão. | < 3 N | NÃO |
amount | Valor total da compra (em centavos). Exemplo: 1,00 = 100 ou 1.100,00 = 110000 – enviar o valor sem a vírgula e ponto. | < 12 N | SIM |
soft_descriptor | Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais | < 30 AN | NÃO |
authorizer_authentication | Este campo deve ser enviado com valor true caso se deseje um pagamento com autenticação. Essa funcionalidade só está disponível para Cielo e-Commerce e e.Rede REST. | < 5 T/F | NÃO |
encrypted_card | Este campo deve ser enviado com valor true caso o número do cartão a ser enviado na próxima etapa do fluxo use a criptografia do SiTef.A opção de envio do cartão criptografado só será possível com roteamento via SiTef e é necessário a configuração prévia do SiTef em questão | < 5 T/F | NÃO |
| iata | Este elemento contém campos específicos de transações IATA. | ||
departure_tax | Taxa de embarque em centavos. | < 12 N | SIM apenas para installment_type = 6 ou 7 |
first_installment | Entrada em transações IATA em centavos. Funcionalidade disponível apenas para o adquirente Getnet. | < 12 N | NÃO |
| schedule | O envio do elemento schedule implica no uso da funcionalidade de agendamento de recorrência. Nenhum de seus campos é obrigatório caso se deseje apenas fazer um pagamento simples. | ||
amount | Valor em centavos dos pagamentos recorrentes. Caso esse campo não seja enviado, será utilizado o valor do pagamento. | < 12 N | SIM |
initial_date | Data de execução do primeiro pagamento agendado. Essa data deve ter pelo menos dois dias à frente do dia atual e dias 29, 30 e 31 nunca são permitidos. O formato da data a ser seguido é: DD/MM/AAAAExemplo: 20/04/2021 | = 10 D | SIM |
number_of_times | Número de pagamentos agendados a serem executados. Caso esse campo não seja enviado, agendamento ficará ativo infinitamente. | < 3 N | NÃO |
interval | Intervalo em meses entre cada pagamento agendado. Caso esse campo não seja enviado, assume-se o valor 1 (execuções mensais). | < 2 N | NÃO |
do_payment_now | Enviar esse campo com valor false caso se deseje realizar um agendamento sem pagamento imediato.No caso deste campo ser ausente ou para qualquer valor diferente de false, será criado um agendamento COM pagamento imediato. | < 5 T/F | NÃO |
installments | Número de parcelas de cada pagamento agendado. Caso esse campo não seja enviado, assume-se o valor 1. | <2 N | NÃO |
installment_type | Tipo de financiamento do parcelamento de cada pagamento agendado: Valor 3 = parcelamento com juros da administradora do cartão.Valor 4 = parcelamento realizado pela loja e sem juros. (Adotar este valor como padrão/default para transações à vista).Caso esse campo não seja enviado, assume-se o valor 4. | < 2 N | NÃO |
soft_descriptor | Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais | < 30 AN | NÃO |
show_times_invoice | Para agendamentos por tempo finito, enviar esse campo com valor true caso se deseje acrescentar ao final do campo soft_descriptor o número de execuções/total de execuções (exemplo: Assinatura 3/12). | < 5 T/F | NÃO |
| additional_data | Elemento para envio de dados adicionais. | ||
postpone_confirmation | Esse campo deve ser enviado com valor true caso se deseje um pagamento com confirmação tardia. | < 5 T/F | NÃO |
financing_plan | Código de plano de financiamento. Necessário apenas para pagamentos parcelados com juros roteados pela Via Certa Financiadora via SiTef. | < 4 N | COND. |
ecomm_pos_ref | Este campo enviará uma identificação que constará no campo PDV do relatório do SiTef Web para transações e-commerce. | < 8 AF | NÃO |
customer_email | Se informado, deve conter o e-mail para o envio do recibo do consumidor, quando uma transacao for efetivada via REST. | < 50 AN | NÃO |
| additional_data.payer | Elemento para envio de dados referentes ao comprador. | ||
identification_number | Documento de identificação do comprador (CPF/RG). | < 20 AN | NÃO |
store_identification | Identificação do comprador para armazenamento de cartão. Esta identificação deve ser única para cada usuário da loja. Mas atenção, essa garantia de unicidade é de total responsabilidade da loja, A API não realizará nenhuma validação. | < 20 AN | SIM para agendamento |
name | Primeiro nome do comprador | < 100 AN | Não |
surname | Sobrenome nome do comprador | < 100 AN | Não |
| additional_data.merchant | Elemento para envio de dados referentes ao lojista. | ||
email | Endereço de e-mail do lojista. | < 1024 AN | NÃO |
| additional_data.extra_param.prefixes | Elemento para envio de prefixos do SiTef, como CICLOS, CPLANO e VLRADD. Caso o prefixo enviado não seja suportado pelo cartão enviado, a API invalidará a transação, impedindo que se dê uma falsa impressão do uso de uma determinada funcionalidade. Exemplo: { "key" : "value" } -> { "CICLOS" : "01" } | ||
key | Nome do prefixo. | < 1024 AN | NÃO |
value | Valor do prefixo. | < 1024 AN | NÃO |
Na tabela abaixo está a descrição dos parâmetros adicionais que devem ser enviados num pagamento com análise de fraude (por enquanto disponível apenas para Cielo e-Commerce):
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
| additional_data | |||
anti_fraud_institution | Esse campo é utilizado quando não se tem um contrato com uma instituição de analise de antifraude e quer que a analise de antifraude seja feita por uma autorizadora, nesse caso deve ser enviado com o valor ‘AUTHORIZER’. Caso você tenha um contrato com uma instituição de analise de antifraude tais como: Konduto, CyberSource e ClearSale esse campo não deve ser usado. | = 10 AN | COND. |
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 annálise. Para maiores detalhes de como executar o fingerprint e obter o identificador, consultar a documentaçãoo disponível com o antifraude escolhido. | < 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 |
| additional_data.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 do 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 |
address_street_name | Endereço do comprador. | < 255 AN | NÃO |
address_street_number | Número do endereço do comprador. | < 15 AN | NÃO |
address_street_complement | Complemento do endereço do comprador. | < 50 AN | NÃO |
address_zip_code | CEP do endereço do comprador. Ex.: 21241140. | < 9 AN | NÃO |
city | Cidade do endereço do comprador. | < 50 AN | NÃO |
state | Estado do endereço do comprador. Ex.: SP. | = 2 AN | NÃO |
address_country | País do endereço do comprador. Ex.: BRA. | < 35 AN | NÃO |
| additional_data.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 AN 3166-1. Ex.: BRA | = 3 AN | NÃO |
| additional_data.browser | |||
cookies_accepted | Identifica se o browser do cliente aceita cookies. Enviar true caso positivo. | < 5 T/F | 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 |
| additional_data.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 |
| additional_data.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 |
| additional_data.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 |
| additional_data.items[].passenger.phone | |||
ddi | Código do país do telefone do passageiro. Para pedidos fora dos E.U.A., é 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 |
| additional_data.extra_param.acquirer_params[] | |||
key | Id das informações adicionais a serem enviadas. Maiores detalhes sobre o envio desse campo entrar em contato com a Cielo | < 1024 N | NÃO |
value | Valor das informações adicionais a serem enviadas. | < 1024 AN | NÃO |
| additional_data.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 |
| additional_data.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 N | NÃO |
ddd | Código da área do telefone do destinatário da entrega. | < 3 N | NÃO |
number | Número de telefone do destinatário da entrega. | < 9 N | NÃO |
| additional_data.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 |
Parâmetros de resposta#
Em caso de sucesso, o código de resposta HTTP será 201. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de criação de transações:
| Parâmetro | Descrição | Formato |
|---|---|---|
code | Código de resposta do Carat. Qualquer código diferente de 0 significa falha. Saiba mais. | < 4 N |
message | Mensagem de resposta do Carat. | < 500 AN |
| payment | ||
status | Status da transação de pagamento no Carat. Saiba mais. | = 3 AN |
nit | Identificador da transação de pagamento no Carat. | = 64 AN |
order_id | Código de pedido enviado pela loja na criação da transação. | < 40 AN |
merchant_usn | Número sequencial único enviado pela loja na criação da transação. | < 12 N |
amount | Valor da compra especificado pela loja (em centavos) na criação da transação. | < 12 N |
| schedule | ||
sid | Identificador da transação de agendamento no Carat. | = 64 AN |
amount | Valor dos pagamentos agendados especificado pela loja (em centavos) na criação da transação. | < 12 N |
status | Status do agendamento no Carat. Saiba mais. | = 3 AN |
order_id | Código de pedido enviado pela loja na criação da transação. | < 40 AN |
merchant_usn | Número sequencial único enviado pela loja na criação da transação. | < 12 N |