Criar pré-autorização
import ApiDoc from '../../src/components/api-doc/ApiDoc'; import ResponseCodes from './codigos-de-resposta.md';
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
<ApiDoc method="post" path="/e-sitef/api/v1/transactions" />
- 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<br/> <URLPOSTMAN/>
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. <br/> 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.<br/> Opções: <br/>1. "true" <br/>2. "false" (valor default) | < 5 AN | Não |
merchant_usn | Número sequencial único para cada pedido, criado pela loja. <br/> 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.<br/> 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). | < 4020 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:<br/>valor 3 = parcelamento com juros da administradora do cartão.<br/>valor 4 = parcelamento realizado pela loja e sem juros (adotar este valor como padrão/default para transações à vista).<br/>Valor 6 = parcelamento com juros da administradora (IATA).<br/>valor 7 = parcelamento realizado pela loja e sem juros (IATA).<br/>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 |
| 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. <br/> 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.<br/> Opções: <br/>1. "true" <br/>2. "false" (valor default) | < 5 AN | Não |
merchant_usn | Número sequencial único para cada pedido, criado pela loja. <br/> 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.<br/> 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). | < 4020 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:<br/>valor 3 = parcelamento com juros da administradora do cartão.<br/>valor 4 = parcelamento realizado pela loja e sem juros (adotar este valor como padrão/default para transações à vista).<br/>Valor 6 = parcelamento com juros da administradora (IATA).<br/>valor 7 = parcelamento realizado pela loja e sem juros (IATA).<br/>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 |
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 | <4020 AN |
status | Status da transação de pré-autorização no Carat. | = 3 A |