Criar pré-autorização

O fluxo da transação de Pré-Autorização é iniciado consumindo a operação beginTransaction, que irá gerar um registro no Carat de uma transação com status=NOV, e, retornará ao aplicativo o parâmetro nit, que identificará essa transação.

O nit tem um prazo de utilização configurado no Carat, se esse tempo limite exceder a transação passará do status "NOV" para o status "EXP". Neste caso não será mais permitido a utilização do mesmo nit, sendo necessário consumir novamente a operação beginTransaction para gerar outro nit válido.

Análise de risco#

Para as transações com análise de risco (antifraude), são utilizados os mesmos campos da criação de pagamento com antifraude.

Detalhes da Chamada#

Recurso: /v1/transactions
Operação HTTP: POST
Formato da requisição: JSON
Formato da resposta: JSON
Parâmetros de cabeçalho:

Nome do Parâmetro	Descrição	Tamanho	Obrigatório
`Content-Type`	Valor fixo "application/json"	= 15 A	Sim
`merchant_id`	Código da loja no Carat. Os códigos de produção e certificação serão diferentes	≤ 15 A	Sim
`merchant_key`	Chave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes.	< 80 A	Sim

Exemplos#

Abaixo estão alguns exemplos de chamada do serviço de criação de transações utilizando a ferramenta cURL.

Pré-Autorização#

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: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "order_id":"orderID",
    "merchant_usn":"20190101",
    "amount":"100",
    "transaction_type":"preauthorization"
}
--verbose

Resposta:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "pre_authorization": {
    "status": "NOV",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "order_id": "orderID",
    "merchant_usn": "20190101",
    "amount": "100"
  }
}

Parâmetros de Requisição#

Nome do Parâmetro	Descrição	Tamanho	Obrigatório
`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	< 12N	Sim
`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. Opções: 1. "true" 2. "false" (valor default)	< 5 AN	Não
`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/roteamentos (Cielo, Redecard, etc) for via SiTef (TEF), 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
`transaction_type`	Valor fixo "preauthorization"	= 15 A	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	< 22 AN	Não
`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
`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
`installments`	Número de parcelas. Envie ‘1’ para transações à vista.	< 2 N	SIM
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

Legenda do tipo do campo "Tamanho":

A = alfanumérico

N = numérico

N A = não utilizado

Parâmetros de resposta#

Nome do Parâmetro	Descrição	Tamanho
`code`	Código de resposta do Carat. Qualquer código diferente de ‘0’ significa falha. Para maiores informações, consulte Códigos de Resposta.	< 4 N
`message`	Mensagem de resposta do Carat.	< 500 A
`amount`	Valor da transação especificado pela loja (em centavos) na criação da transação.	< 12 N
`merchant_usn`	Número sequencial único enviado pela loja na criação da transação.	< 12 N
`nit`	Identificador da transação de pré-autorização no Carat.	= 64 A
`order_id`	Código de pedido enviado pela loja na criação da transação	<40 AN
`status`	Status da transação de pré-autorização no Carat.	= 3 A