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 e-SiTef 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 e-SiTef, 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 e-SiTef. Os códigos de produção e certificação serão diferentes | ≤ 15 A | Sim |
merchant_key | Chave de autenticação da loja no e-SiTef. 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.
Requisição:
curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/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 e-SiTef, é 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 e-SiTef, 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 |
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 e-SiTef. Qualquer código diferente de ‘0’ significa falha. Para maiores informações, consulte Códigos de Resposta. | < 4 N |
message | Mensagem de resposta do e-SiTef. | < 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 e-SiTef. | = 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 e-SiTef. | = 3 A |