Pré-Autorização

Visão Geral

O e-SiTef é um gateway de pagamentos multisserviços com capacidade de processamento de transações de cartões de crédito, transferência bancária, geração de boletos, integração com opções de mobile payment, entre outros serviços que podem ser facilmente agregados à plataforma.

O e-SiTef possui duas interfaces para integração com a Loja Virtual, Interface HTML e Web Services, possibilitando a maneira adequada de interação da loja com o e-SiTef, conforme a linguagem e plataforma de execução da loja virtual.

A interface REST disponibiliza pagamentos com cartão de crédito, pré-autorização, captura de pré-autorização e recarga de celular pré-pago.

Para pagamentos via banco como transferência bancária, boleto, utilize a Interface HTML; a recarga de celular pré-pago também está disponível na Interface HTML.

Processo de Certificação

O processo de certificação da aplicação integrada ao e-SiTef será realizado pela equipe do Suporte Autorizadores/e-SiTef. É de responsabilidade do cliente informar ao Suporte técnico que o desenvolvimento do aplicativo foi finalizado, para que sejam tomadas as devidas providências para a realização da certificação.

Para tanto, o cliente deverá entrar em contato com autorizadores5317@softwareexpress.com.br

Somente estará apto para a entrada em Produção o aplicativo que finalizar o processo de Certificação com sucesso; a Certificação, portanto, é um processo obrigatório

Roteamentos Suportados

A funcionalidade de pré-autorização do e-SiTef suporta os seguintes roteamentos:

• Rede (via SiTef)
• Cielo (via SiTef)
• Amex (via SiTef)
• GetNetLac (via SiTef)
• Safra (via SiTef)
• Adiq (via SiTef)
• BIN (via SiTef)
• Sipag (via SiTef)
• iCards (via SiTef)
• e-Rede
• GetNet WS
• GlobalPayments WS
• Cielo e-Commerce
• Stone WS
• EPX

Configurações necessárias no e-SiTef

O uso da funcionalidade de Pré Autorização sempre deve ter sua permissão habilitada pelas equipes de Suporte (ambiente de Certificação) e Produção (ambiente de Produção).

Integração de Pré-Autorização, Captura de Pré-Autorização e Cancelamento via Web Service REST

O propósito deste documento é descrever a interface de pré-autorização via REST onde a coleta dos parâmetros será realizada pela Loja Virtual e o e-SiTef apenas se encarrega de realizar a transação junto à rede adquirente/roteamento.

A pré-autorização é uma transação cujo valor será reservado do limite do cartão, porém não será debitado imediatamente, podendo ser capturado posteriormente por um valor igual ou menor que o autorizado. O prazo para realizar a captura, assim como a possibilidade de capturar valores menores vai depender da negociação com a rede adquirente/roteamento, caberá a Loja Virtual consultar a rede adquirente/roteamento.

O cancelamento da pré-autorização pode ser realizado para disponibilizar novamente o valor reservado do limite do cartão, caso ainda a captura da pré-autorização não seja realizada.

Após a conclusão da transação de captura da pré-autorização, a mesma também poderá ser estornada. Para mais detalhes sobre o cancelamento e estorno, o documento Interface Web Service REST de Pagamento, Agendamento e Cancelamento deve ser consultado. Caso o lojista não tenha este em mãos, deve solicitar às equipes de atendimento do e-SiTef.

Fluxo de Pré-Autorização, Captura e Consulta de Status

O fluxo de pré-autorização será iniciado pela Loja Virtual quando o aplicativo enviar a operação beginTransaction (Figura 1), na resposta da requisição o aplicativo receberá o nit (identificador da transação) e outros parâmetros (Tabela 2). O nit recebido no beginTransaction juntamente com outros parâmetros (Tabela 3), serão enviados pela Loja Virtual na operação doPreAuthorization e deverá tratar os parâmetros recebidos na resposta da requisição de beginTransaction. Posteriormente (conforme a regra de negócio) o mesmo nit enviado na pré-autorização, deverá ser enviado na operação capture juntamente com outros parâmetros (Tabela 9) e deverá tratar os parâmetros recebidos no webservice response.

Se ocorrer uma falha no recebimento do webservice response (i.e, timeout) do doPreAuthorization ou do capture, a aplicação da loja obrigatoriamente deverá realizar a consulta de status com a operação getStatus, para verificar o resultado da transação.

No caso do aplicativo não receber a resposta da operação beginTransaction, não será necessário realizar a operação getStatus, basta que o aplicativo realize novamente o beginTransaction. Porque nesse momento, ainda não houve o envio da transação que comprometerá o limite ou a cobrança na fatura do cartão do cliente.

A consulta de status (getStatus) é de extrema importância para evitar que ocorra a cobrança indevida (possível cobrança em duplicidade ou cobrança sem o recebimento do produto/serviço) na fatura do cliente. As figuras abaixo ilustram os fluxos:

Pré-Autorização

Toda a comunicação será realizada via HTTPS/TLS, e é importante que o servidor do lojista suporte criptografia com no mínimo 128 bits e protocolo mínimo TLS 1.2. O servidor de aplicação da Loja Virtual realizará a chamada no endereço para pré-autorização via Web Service, conforme descrito abaixo, de acordo com o ambiente em questão.

URL do ambiente de Certificação/testes:

https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/

URL do ambiente de Produção:

https://esitef-ec.softwareexpress.com.br/e-sitef/api/

Atenção: Nunca utilizar o IP ao invés do domínio esitef-ec.softwareexpress.com.br, porque o IP poderá mudar a qualquer momento e sem aviso prévio, portanto, é importante a utilização do domínio para acesso ao e-SiTef.

Web Service possui as seguintes operações: beginTransaction, doPreAuthorization, capture, doCardQuery e getStatus.

Outras operações poderão ser incluídas sem aviso prévio.

Importante: Além dos parâmetros de resposta do webservice descrito nesta especificação, o e-SiTef poderá retornar outros parâmetros sem aviso prévio. É importante que o aplicativo esteja preparado para receber parâmetros extras além dos parâmetros já especificados e simplesmente desprezá-los.

Operação beginTransaction – criação de transação

Parâmetros de requisição da operação beginTransaction

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.

A operação beginTransaction deverá ser enviado com os parâmetros da tabela abaixo.

• 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

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 A	Não
transaction_type	Valor fixo “preauthorization”	= 15 A	Sim

Legenda do tipo do campo “Tamanho”:

A = alfanumérico

N = numérico

N A = não utilizado

Parâmetros de resposta da operação beginTransaction

A tabela abaixo mostra os parâmetros de resposta da operação beginTransaction:

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 o documento "Anexo A-2 - Codigos 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 A
status	Status da transação de pré-autorização no e-SiTef.	= 3 A

Exemplo de 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"
}

Exemplo de resposta

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

Operação doPreAuthorization - efetivação da pré-autorização

O nit obtido no retorno da operação beginTransaction, deverá ser enviado na operação doPreAuthorization juntamente com os parâmetros descritos na tabela abaixo (conforme a necessidade de cada aplicação):

• Recurso: /v1/preauthorizations/{nit}
• Método 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

Parâmetros de requisição da operação doPreAuthorization

Nome do parâmetro	Descrição	Tamanho	Obrigatório
authorizer_id	Código da autorizadora no e-Sitef. Ver documento Anexo A – Autorizadoras e-SiTef.	≤ 3 N	Sim
customer_id	Documento de identidade do comprador. Use apenas caracteres alfanuméricos (sem pontos, traços ou outros caracteres especiais).	≤ 20 A	Não
discount	Valor do desconto, em centavos. Em caso de pré-autorizações com valores promocionais pelo uso do Visa Checkout, a VISA sugere que este campo seja enviado adicionalmente.	N	Não
installments	Juntamente com o campo installment_type, indica parcelamento (**), utilizados APENAS com autorizadoras roteadas, e-Rede, GetNetLac via SiTef, Rede via SiTef e iCards via SiTef. Envie ‘1’ para transações à vista.	< 2 N	Condicional
installment_type	Juntamente com o campo installments, indica parcelamento (**), utilizados APENAS com autorizadoras roteadas por e-Rede, GetNetLac via SiTef, Rede via SiTef e iCards via SiTef. Para as demais roteamentos, o parcelamento é possível somente na captura. Os valores possíveis para installment_type são: 3: Parcelamento com juros da administradora do cartão 4: Parcelamento realizado pela loja e sem juros (adotar este valor como padrão/default para transações à vista)	= 1 N	Condicional
mcc	Merchant Category Code - Indica o código de categoria da loja. Necessário ao utilizar subadquirência Stone WS.	< 4 N	Obrigatório apenas para subadquirência Stone WS
merchant_email	e-mail da Loja. Este parâmetro quando enviado sobrescreve o e-mail do cadastro da Loja.	≤ 40 A	Opcional
nit	Identificador da transação no e-SiTef (criptografado). Obtido no retorno da chamada ao beginTransaction.	= 64 A	Sim
promo_code	Código de promoção Visa Checkout utilizado na pré-autorização. Em caso de pré-autorizações com valores promocionais pelo uso do Visa Checkout, a VISA sugere que este campo seja enviado adicionalmente.	A	Não
soft_descriptor	Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. funcionalidade disponível apenas para as redes adquirentes/roteamentos e-Rede e Bin via SiTef.	≤ 30 A	Não
subtotal	Valor do subtotal, em centavos. Em caso de pré-autorizações com valores promocionais pelo uso do Visa Checkout, a VISA sugere que este campo seja enviado adicionalmente.	N	Não
expiry_date	Data de vencimento do cartão no formato MMAA.	= 4 N	Sim
holder	Nome do portador do cartão. Obrigatório apenas para roteamentos e-Rede, GetNet WS e VR (SmartNet).	≤ 30 A	Condicional
security_code	Código de segurança.	≤ 5 N	Sim
number (*)	Número do cartão do comprador (PAN). Obrigatório utilizar um entre os campos (number, token ou initial_wallet_transaction_id)	≤ 19 N	Sim
token (*)	Utilizado para casos de pré-autorização recorrente, onde o cartão já deverá estar armazenado na base de dados do e-SiTef.	= 88 A	Condicional
wallet_transaction_id(*)	Código de identificação de transação com wallet Visa Checkout. Sobre o uso de Visa Checkout, por favor ver o documento Anexo M-1 - VisaCheckout via WS	< 25 A	Condicional
initial_wallet_transaction_id	Informa se o Wallet ID (WALLET_TRANSACTION_ID) está sendo utilizado pela primeira vez. Se for a primeira vez, enviar true, caso contrário, enviar false. Possíveis valores: true/false Valor default: true	< 5 A	Necessário apenas para Visa Checkout

(*) Obrigatório utilizar apenas um entre os campos: number, token ou initial_wallet_transaction_id

(**) Parcelamento roteada por GetNetLac via SiTef: Neste caso, a loja será responsável pelo controle do parcelamento, logo não entrarão em vigor as regras de parcelamento configuradas para a interface de pagamento HTML do e-SiTef, somente as regras de parcelamento da autorizadora serão verificadas e aplicadas. Para estas redes mencionadas, caso a pré-autorização seja feita à vista, a captura não pode ser parcelada. Ainda, pré- autorizações roteadas por GetNetLac via SiTef, quando parceladas, apenas são aceitos sem juros, isto é, com o parâmetro installment_type = 4. Parcelamentos sem juros não são aceitos para este roteamento.

Parâmetros de resposta da operação doPreAuthorization

A tabela abaixo contém os parâmetros de resposta da operação doPreAuthorization. O aplicativo deverá armazenar os parâmetros que achar necessário. Sugerimos que sejam armazenados os parâmetros: order_id, authorization_number, merchant_usn, esitef_usn, sitef_usn, host_usn, status, code, amount, message (o parâmetro message poderá ser exibido ao cliente).

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 o documento Anexo A-2 - Codigos de Resposta.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
acquirer_id	Código do adquirente/roteamento utilizado na transação.	< 4 N
acquirer_name	Nome do adquirente/roteamento utilizado na transação.	< 100 AN
amount	Valor da compra especificado pela loja (em centavos) na criação da transação.	< 12 AN
authorization_number	Número de autorização.	< 6 AN
authorizer_code	Código de resposta do autorizador.	< 10 AN
authorizer_date	Data de efetivação da pré-autorização retornada pelo autorizador no formato DD/MM/AAAA’T’HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
authorizer_id	Código da autorizadora utilizada na transação.	< 4 N
authorizer_merchant_id	Código de afiliação do lojista na autorizadora.	< 100 AN
authorizer_message	Mensagem de resposta do autorizador.	< 500 AN
customer_receipt	Cupom (via cliente).	< 4000 AN
eci	Eletronic Commerce Indicator (indicador do nível de segurança da transação da pré-autorização via Cielo e-Commerce).	< 3 AN
esitef_usn	Número sequencial único da transação de pré-autorização no e-SiTef.	= 6 N
host_usn	NSU da autorizadora.	< 15 AN
issuer	Código da bandeira retornado pelo autorizador.	< 5 AN
merchant_receipt	Cupom (via estabelecimento).	< 4000 AN
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 AN
nit	Identificador da transação de pré-autorização no e-SiTef.	= 64 AN
order_id	Código de pedido enviado pela loja na criação da transação.	< 40 AN
payment_type	Tipo do pagamento da autorizadora escolhida: B = boleto, C = crédito, D = débito, P = cartão crédito Private Label puro, T = tranferência bancária, G = cartão gift, O = outros meios e pagamentos, W = Boleto NR via Web Service	= 1 A
sitef_usn	Número sequencial único da transação de pré-autorização no SiTef.	= 6 N
status	Status da transação de pré-autorização no e-SiTef.	= 3 AN
tid	ID da transação no adquirente/roteamento. Este campo só é retornado em transações com adquirentes externos ao SiTef.	< 40 AN
xid	Campo XID retornado em autenticações 3DS ou certos adquirentes/roteamentos.	< 40 AN

Exemplo de requisição

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-
sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz123456
7890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header “merchant_key: xxxxxxxxxxx”
--data-binary
{
"authorizer_id":"2",
"installments":"2",
"installment_type":"4",
"card":{
"number":"xxxxxxxxxxxxxxxx",
"expiry_date":"1222",
"security_code":"123"
}
}
--verbose

Exemplo de resposta

{
    "code":"0",
    "message":"OK. Transaction successful.",
    "pre_authorization":{
        "authorizer_code":"000",
        "authorizer_message":"Transacao OK.",
        "status":"CON",
        "nit":
    "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr
    ",
        "customer_receipt":
        ".....S.O.F.T.W.A.R.E.E.X.P.R.E.S.S....
        \nSI                                Rede 5
        \nMU                 Codigo transacao: 100
        \nLA                 Codigo operacao: 3000
        \nDO                           Valor: 1,00
        \n.....S...I...M...U...L...A...D...O....
        \nSI                     NSU SiTef: 212194
        \nMU                        21/09/18 16:27
        \nLA                      ID PDV: ES000115
        \nDO               Estab.: 000000000000005
        \n.....S...I...M...U...L...A...D...O....
        \nSI                       Host: 999212194
        \nMU           Transacao Simulada Aprovada
        \n                                 (SiTef)
        \n",                   "merchant_receipt":
        ".....S.O.F.T.W.A.R.E.E.X.P.R.E.S.S....
        \nSI                                Rede 5
        \nMU                 Codigo transacao: 100
        \nLA                 Codigo operacao: 3000
        \nDO                           Valor: 1,00
        \n.....S...I...M...U...L...A...D...O....
        \nSI                     NSU SiTef: 212194
        \nMU                        21/09/18 16:27
        \nLA                      ID PDV: ES000115
        \nDO               Estab.: 000000000000005
        \n.....S...I...M...U...L...A...D...O....
        \nSI                       Host: 999212194
        \nMU           Transacao Simulada Aprovada
        \n                                 (SiTef)
        \n",                  "authorizer_id":"2",
        "authorizer_date":"09/11/2018T19:40",
        "acquirer_id":"1005",
        "acquirer_name":"Redecard",
        "authorization_number":"013245",
        "merchant_usn":"20190101",
        "esitef_usn":"181109017689784",
        "order_id":"orderID",
        "sitef_usn":"212194",
        "host_usn":"999212194
        ",
        "amount":"100",
        "issuer":"2",
        "payment_type":"C",
        "authorizer_merchant_id":"000000000000000"
    }
}

Operação editPreAuthorization - alteração de valor de pré-autorização

Para o roteamento GetNetLac via SiTef é possível alterar o valor de uma pré-autorização não capturada. Para utilizar essa funcionalidade, basta chamar novamente a operação doPreAuthorization com os dados de uma transação de pré-autorização com status CON (confirmada) com adição do campo amount. Abaixo estão os detalhes dessa chamada.

Nome do Parâmetro	Descrição	Tamanho	Obrigatório
nit	Identificador da transação no e-SiTef. Obtido no retorno da chamada ao beginTransaction.	= 64 A	Sim
authorizer_id	Código da autorizadora no e-Sitef. Ver documento Anexo A – Autorizadoras e-SiTef.	≤ 3 N	Sim
amount	Valor total da compra (em centavos).	≤ 12 N	Sim
number	Número do cartão do comprador (PAN).	≤ 19 N	Sim
token	Utilizado para casos de pagamento recorrente, onde o cartão já deverá estar armazenado na base de dados do e-SiTef. Obrigatório utilizar um entre os campos (number, token ou initial_wallet_transaction_id)	= 88 A	Condicional
expiry_date	Data de vencimento no formato MMAA.	= 4 N	Sim
security_code	Código de segurança.	≤ 5 N	Sim

Os campos de resposta são os mesmos da operação doPreAuthorization, descritos na Tabela 6.

Em caso de sucesso, será retornado o responseCode ‘0’. O status da transação não será alterado em hipótese alguma (sucesso ou falha). Porém, os campos sitef_usn, host_usn, authorization_number, sitef_date, customer_receipt e merchant_receipt sofrerão mudanças caso a alteração seja confirmada.

Operação capture – captura de pré-autorização

A captura da Pré-Autorização tem como objetivo a efetivação da Pré-Autorização, que poderá ser no valor total ou inferior ao valor total da Pré-Autorização. Isso vai depender da regra de negócio da aplicação da Loja Virtual.

O fluxo seria, realizar a operação doPreAuthorization e se o resultado for aprovado, a operação capture deverá ser consumido para completar o fluxo. A captura será realizada no momento definido pelas regras de negócios da aplicação.

Na operação capture o parâmetro amount pode ter o valor igual ou menor ao valor do parâmetro amount da pré-autorização.

Para o roteamento GetNetLac via SiTef, o parcelamento pode ser feito também na etapa de pré-autorização e nesse caso, a captura deve receber um número de parcelas igual ou superior ao enviado anteriormente. Caso a pré- autorização seja feita à vista, a captura não pode ser parcelada.

Em caso de captura de transações de pré-autorização HTML, as parcelas e o tipo de financiamento seguem obrigatoriamente os valores definidos na pré-autorização. Logo neste caso não há a possibilidade de alteração destes valores no momento da captura.

Detalhes da chamada

Recurso: /v1/preauthorizations/capture/{nit}

Método 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

Parâmetros da requisição da operação capture

Nome do Parâmetro	Descrição	Tamanho	Obrigatório
amount	Valor total da compra (em centavos).	≤ 12 N	Sim
discount	Valor do desconto, em centavos. Em caso de pré-autorizações com valores promocionais pelo uso do Visa Checkout, a VISA sugere que este campo seja enviado adicionalmente.	N	Não
installments (*)	Número de parcelas, 1 = à vista	≤ 2 N	Sim
installment_type	Juntamente com o campo installments, indica parcelamento. Os valores possíveis para installment_type são: 3: Parcelamento com juros da administradora do cartão 4: Parcelamento realizado pela loja e sem juros (adotar este valor como padrão/default para transações à vista)	= 1 N	Sim
promo_code	Código de promoção Visa Checkout utilizado no pré-autorização. Em caso de pré-autorizações com valores promocionais pelo uso do Visa Checkout, a VISA sugere que este campo seja enviado adicionalmente.	A	Não
subtotal	Valor do subtotal, em centavos. Em caso de pré-autorizações com valores promocionais pelo uso do Visa Checkout, a VISA sugere que este campo seja enviado adicionalmente.	N	Não
number (**)	Número do cartão do comprador (PAN).	≤ 19 N	Sim
token (**)	Utilizado para casos de pré-autorização recorrente, onde o cartão já deverá estar armazenado na base de dados do e-SiTef.	= 88 A	Condicional
wallet_transaction_id (**)	Código de identificação de transação com wallet VisaCheckout.	< 25 A	Necessário apenas para Visa Checkout
initial_wallet_transaction_id	Informa se o Wallet ID (WALLET_TRANSACTION_ID) está sendo utilizado pela primeira vez. Se for a primeira vez, enviar true, caso contrário, enviar false. Possíveis valores: true/false Valor default: true	< 5 A	Necessário apenas para Visa Checkout
acquirer.submerchant_split[]	Consiste em um array para pagamentos split, exclusivos para roteamentos BIN e Sipag, ambos via SiTef. Permite a divisão de partes do valor total do pagamento entre outras empresas. O máximo de itens permitido neste array é de 5 itens. Cada item é composto pelos campos submechant_code e submerchant_amount.		Não
submerchant_code	código de estabelecimento BIN/Sipag	≤ 15 AN	Não
submerchant_amount	valor de transação referente ao estabelecimento	≤ 12 N	Não

(*) installments: O número máximo de parcelas configurado no portal e-SiTef do lojista não será verificado neste campo, servindo somente para pagamentos HTML.

(**) Obrigatório utilizar apenas um entre os campos: number, token ou initial_wallet_transaction_id

Parâmetros de resposta da operação capture

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 o documento anexo A-2 - Codigos de Resposta.	< 4 N
message	Mensagem de resposta do e-SiTef.	< 500 AN
acquirer_id	Código do adquirente/roteamento utilizado na transação.	< 4 N
acquirer_name	Nome do adquirente/roteamento utilizado na transação.	< 100 AN
amount	Valor da compra especificado pela loja (em centavos) na criação da transação.	< 12 AN
authorization_number	Número de autorização.	< 6 AN
authorizer_code	Código de resposta do autorizador.	< 10 AN
authorizer_date	Data de efetivação da pré-autorização retornada pelo autorizador no formato DD/MM/AAAA’T’HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
authorizer_id	Código da autorizadora utilizada na transação.	< 4 N
authorizer_merchant_id	Código de afiliação do lojista na autorizadora.	< 100 AN
authorizer_message	Mensagem de resposta do autorizador.	< 500 AN
customer_receipt	Cupom (via cliente).	< 4000 AN
eci	Eletronic Commerce Indicator (indicador do nível de segurança da transação do pré-autorização via Cielo e-Commerce).	< 3 AN
esitef_usn	Número sequencial único da transação de pré-autorização no e-SiTef.	= 6 N
host_usn	NSU da autorizadora.	< 15 AN
issuer	Código da bandeira retornado pelo autorizador.	< 5 AN
merchant_receipt	Cupom (via estabelecimento).	< 4000 AN
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 AN
nit	Identificador da transação de pré-autorização no e-SiTef.	= 64 AN
payment_type	Tipo do pagamento da autorizadora escolhida: B = boleto, C = crédito, D = débito, P = cartão crédito Private Label puro, T = tranferência bancária, G = cartão gift, O = outros meios de pagamentos, W = Boleto NR via Web Service	= 1 A
sitef_usn	Número sequencial único da transação de pré-autorização no SiTef.	= 6 N
status	Status da transação de pré-autorização no e-SiTef.	= 3 AN
tid	ID da transação no adquirente/roteamento. Este campo só é retornado em transações com adquirentes externos ao SiTef.	< 40 AN
xid	Campo XID retornado em autenticações 3DS ou certos adquirentes/roteamentos.	< 40 AN

Exemplo de requisição

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-
sitef/api/v1/preauthorizations/capture/1234567890abcdefghijklmnopqrstuvwx
yz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header “merchant_key: xxxxxxxxxxx”
--data-binary
{
    "amount":"100",
    "installments":"1",
    "installment_type":"4",
    "card":{
    "number":"xxxxxxxxxxxxxxxx",
    "expiry_date":"1222",
    "security_code":"123"
},
"acquirer":{
    "submerchant_split":[
        {
            "submerchant_code":"empresa01",
            "submerchant_amount":"10"
        },
        {
            "submerchant_code":"empresa02",
            "submerchant_amount":"20"
        },
        {
            "submerchant_code":"empresa03",
            "submerchant_amount":"20"
        },
        {
            "submerchant_code":"empresa04",
            "submerchant_amount":"30"
        },
        {
            "submerchant_code":"empresa05",
            "submerchant_amount":"30"
        }
    ]
}
}
--verbose

Exemplo de resposta

{
    "code":"0",
    "message":"OK. Transaction successful.",
    "capture":{
        "status":"CON",
    "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr
    ",
    "order_id":"orderID",
    "customer_receipt":
    ".....S.O.F.T.W.A.R.E.E.X.P.R.E.S.S....
    \nSI                              Rede 5
    \nMU               Codigo transacao: 220
    \nLA               Codigo operacao: 3000
    \nDO                         Valor: 1,00
    \n.....S...I...M...U...L...A...D...O....
    \nSI                   NSU SiTef: 212195
    \nMU                      21/09/18 16:27
    \nLA                    ID PDV: ES000115
    \nDO             Estab.: 000000000000005
    \n.....S...I...M...U...L...A...D...O....
    \nSI                     Host: 999212195
    \nMU         Transacao Simulada Aprovada
    \n                               (SiTef)
    \n"
    "merchant_receipt":".....S.O.F.T.W.A.R.E.E.X.P.R.E.S.S....
    \nSI                              Rede 5
    \nMU               Codigo transacao: 220
    \nLA               Codigo operacao: 3000
    \nDO                         Valor: 1,00
    \n.....S...I...M...U...L...A...D...O....
    \nSI                   NSU SiTef: 212195
    \nMU                      21/09/18 16:27
    \nLA                    ID PDV: ES000115
    \nDO             Estab.: 000000000000005
    \n.....S...I...M...U...L...A...D...O....
    \nSI                     Host: 999212195
    \nMU         Transacao Simulada Aprovada
    \n                               (SiTef)
    \n",
    "authorizer_id":"2",
    "acquirer_id":"1005",
    "acquirer_name": "Redecard",
    "authorizer_code": "000",
    "authorizer_message": "Transacao OK.”
    "authorizer_date":"Fri Sep 21 16:27:29 BRT 2018",
    "authorizer_merchant_id": "000000000000000",
    "authorization_number":"212195",
    "esitef_usn":"180921015287704",
    "merchant_usn": "20190101",
    "sitef_usn":"212195",
    "host_usn":"999212195
    ",
    "amount":"100",
    "payment_type":"C",
    "issuer":"2"
}

Operação doCardQuery - consulta de cartão

A partir de um NIT de pré autorização com status NOV (novo), é possível realizar uma consulta do BIN do cartão (seis primeiros dígitos) no SiTef para obter dados sobre suas capacidades (possibilidade de pagamento parcelado, máximo de parcelas, exigência de código de segurança, etc.), ou ainda, saber qual autorizadora da loja é a mais adequada para a realização do pagamento.

No caso de transações com Visa Checkout, este serviço também retornará dados do cartão e do usuário retornados pelo Visa.

Fluxo

Descrição do fluxo:

1. O lojista cria uma transação no e-SiTef passando informações como código da loja, número de parcelas e código de pedido e obtém como resposta um NIT (Número Identificador de Transação).
2. O lojista envia o NIT obtido na etapa anterior e os dados do cartão a ser consultado. Com isso, o e-SiTef retorna dados sobre as capacidades do cartão enviado.
3. A loja virtual prossegue então consumindo o serviço de efetivação do pagamento, passando o NIT e os dados do cartão do comprador. Em caso de sucesso, a transação de pagamento mudará seu status para CON (confirmada).

Detalhes da chamada

• Recursos: /v1/preauthorizations/{nit}/cards

• Método HTTP: POST

Obs.: apesar de se tratar de uma consulta, o método POST foi escolhido por questões de segurança.

• Formato da requisição: JSON

• Formato da resposta: JSON

• Parâmetros de cabeçalho:

Nome do Parâmetro	Descrição	Tipo	Tamanho	Obrigatório
merchant_id	Código da loja no e-SiTef. Os códigos de produção e certificação serão diferentes.	AN	≤ 15	SIM
merchant_key	Chave de autenticação da loja no e-SiTef. As chaves de produção e certificação serão diferentes.	AN	≤ 80	SIM
Content-Type	Deve ser enviado com o valor “application/json”.	AN	= 15	SIM

Exemplo de Consulta de cartão com envio de autorizadora

Requisição:

curl
--request POST “https://esitef-homologacao.softwareexpress.com.br/e-
sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz123456
7890abcdefghijklmnopqr /cards”
--header “Content-Type: application/json”
--header “merchant_id: xxxxxxxxxxx”
--header “merchant_key: xxxxxxxxxxx”
--data-binary
{
    “card”:{
        “number”:”5555555555555555”
    },
    “authorizer_id”:”1”
}
--verbose

Resposta:

{
    “code”:”0”,
    “message”:”OK. Transaction successful.”,
    “preauthorization”:{
        “status”:”NOV”
    },
    “card”:{
        “acquirer_name”:”Redecard”,
        “authorizer_id”:”1”,
        “authorizer_response_code”:”000”,
        “is_customer_id_required”:”false”,
        “is_expiry_date_required”:”true”,
        “is_installment_funding_enabled”:”true”,
        “is_security_code_required”:”true”,
        “is_spot_sale_enabled”:”true”,
        “is_with_interest_sale_enabled”:”true”,
        “is_without_interest_sale_enabled”:”true”,
        “max_installments_with_interest”:”12”,
        “min_installments_with_interest”:”01”,
        “prefixes”:{
            “TRAT”:”2”,
            “PERIFERICO”:”1”,
            “CSEG”:”2”
        }
    }
}

Exemplo de Consulta de cartão sem envio de autorizadora

Requisição:

curl
--request POST “https://esitef-homologacao.softwareexpress.com.br/e-
sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz123456
7890abcdefghijklmnopqr/cards”
--header “Content-Type: application/json”
--header “merchant_id: xxxxxxxxxxx”
--header “merchant_key: xxxxxxxxxxx”
--data-binary
{
    “card”:{
        “number”:”6543210987654321”
    }
}
--verbose

Resposta:

{
    “code”:”0”,
    “message”:”OK. Transaction successful.”,
    “preauthorization”:{
        “status”:”NOV”
    },
    “card”:{
        “acquirer_name”:”Redecard”,
        “authorizer_id”:”1”,
        “authorizer_response_code”:”000”,
        “is_customer_id_required”:”false”,
        “is_expiry_date_required”:”true”,
        “is_installment_funding_enabled”:”true”,
        “is_security_code_required”:”true”,
        “is_spot_sale_enabled”:”true”,
        “is_with_interest_sale_enabled”:”true”,
        “is_without_interest_sale_enabled”:”true”,
        “max_installments_with_interest”:”12”,
        “min_installments_with_interest”:”01”,
        “prefixes”:{
            “TRAT”:”2”,
            “PERIFERICO”:”1”,
            “CSEG”:”2”
        }
    }
}

Exemplo de Consulta de cartão Visa Checkout

Requisição:

curl
--request POST “https://esitef-homologacao.softwareexpress.com.br/e-
sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz123
4567890abcdefghijklmnopqr/cards”
--header “Content-Type: application/json”
--header “merchant_id: xxxxxxxxxxx”
--header “merchant_key: xxxxxxxxxxx”
--data-binary
{
    “card”:{
        “wallet_transaction_id”:”4444444444444444444”
    },
    “authorizer_id”:”406”
}
--verbose

Resposta:

{
    “code”:”0”,
    “message”:”OK. Transaction successful.”,
    “preauthorization”:{
        “status”:”NOV”
    },
    “card”:{
        “acquirer_name”:”Redecard”,
        “authorizer_id”:”406”,
        “authorizer_response_code”:”000”,
        “is_customer_id_required”:”false”,
        “is_expiry_date_required”:”true”,
        “is_installment_funding_enabled”:”true”,
        “is_security_code_required”:”true”,
        “is_spot_sale_enabled”:”true”,
        “is_with_interest_sale_enabled”:”true”,
        “is_without_interest_sale_enabled”:”true”,
        “max_installments_with_interest”:”12”,
        “min_installments_with_interest”:”01”,
        “prefixes”:{
            “TRAT”:”2”,
            “PERIFERICO”:”1”
        },
        “visa_checkout_data”:{
            “payment_request”:{
                “currency_code”:”BRL”,
                “subtotal”:”115.5”,
                “total”:”115.5”,
                “order_id”:”09387”,
                “source_id”:”LOJAVISACHECK”
            },
            “user_data”:{
                “user_first_name”:”Comprador”,
                “user_last_name”:”Esitef”,
                “user_full_name”:”Comprador Esitef”,
                “user_name”:”esitef2@gmail.com”,
                “user_email”:”esitef2@gmail.com”,
                “enc_user_id”:”c5DmPXTXC3VwZywsFESEGAqiLM5PXSZG7hgyQgRv0j8=”,
                “user_personal_id”:”12345678909”
            },
            “creation_time_stamp”:1502206049403,
            “payment_instrument”:{
                “id”:”AWUU0/rQrmKCMx+C740kBefZP2GNsdAMYUTXAzCPk+M=”,
                “last_four_digits”:”1010”,
                “bin_six_digits”:”406897”,
                “verification_status
                “issuer_bid”:”10029901”,
                “nick_name”:”Cartão PAN”,
                “name_on_card”:”aaaaaaaaaa vvvvvvvvvv”,
                “card_first_name”:”aaaaaaaaaa”,
                “card_last_name”:”vvvvvvvvvv”,
                “payment_type”:{
                    “card_brand”:”VISA”,
                    “card_type”:”CREDIT”
                },
                “billing_address”:{
                    “person_name”:”aaaaaaaaaa vvvvvvvvvv”,
                    “first_name”:”aaaaaaaaaa”,
                    “last_name”:”vvvvvvvvvv”,
                    “line1”:”qqqqqqqqqq”,
                    “line2”:”eeeeee”,
                    “line3”:”wwwwwwwww”,
                    “city”:”cccccccc”,
                    “state_province_code”:”SP”,
                    “postal_code”:”01238010”,
                    “country_code”:”BR”,
                    “phone”:”987654321”,
                    “default”:”false”
                },
                “card_arts”:{
                    “card_art”:[
                        {
                            “base_image_file_name”:”https://sandbox.secure.checkout.visa.com/VmeCa
                            rdArts/lg_visa_card.png”,
                            “height”:105,
                            “width”:164
                        }
                    ]
                },
                “expiration_date”:{
                    “month”:”11”,
                    “year”:”2022”
                }
            },
            “risk_data”:{
                “advice”:”UNAVAILABLE”,
                “score”:0,
                “avs_response_code”:”0”,
                “cvv_response_code”:”0”,
                “age_of_account”:”704”
            },
            “visa_checkout_guest”:”false”
        }
    }
}

Exemplo de Consulta de cartão com dados adicionais para roteamento iCards via SiTef

Requisição:

curl
--request POST “https://esitef-homologacao.softwareexpress.com.br/e-
sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz123456
7890abcdefghijklmnopqr/cards”
--header “Content-Type: application/json”
--header “merchant_id: xxxxxxxxxxx”
--header “merchant_key: xxxxxxxxxxx”
--data-binary
{
    “card”:{
        “number”:”6543210987654321”
    },
    “authorizer_id”:”38”
}
--verbose

Resposta:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "card": {
        "acquirer_name": "iCards",
        "authorizer_id": "38",
        "authorizer_response_code": "000",
        "is_customer_id_required": "true",
        "is_expiry_date_required": "true",
        "is_installment_funding_enabled": "true",
        "is_security_code_required": "true",
        "is_spot_sale_enabled": "true",
        "is_with_interest_sale_enabled": "true",
        "is_without_interest_sale_enabled": "true",
        "max_installments_with_interest": "12",
        "min_installments_with_interest": "01",
        "prefixes": {
            "NPSAQ": "0299",
            "CAPTPPRE": "1",
            "XCAPPREAUT": "11"
        },
        "is_customer_postal_code_required": "true",
        "is_card_holder_required": "true"
    },
    "preauthorization": {
        "status": "NOV"
    }
}

Parâmetros de requisição

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de consulta de cartão:

Nome do Parâmetro	Descrição	Tipo	Tamanho	Obrigatório
authorizer_id	Código da autorizadora no e-SiTef, conforme listado no documento “Anexo A – Autorizadoras e-SiTef”. Este campo só é obrigatório caso o campo “wallet_transaction_id” seja enviado.	N	≤ 3	NÃO
number	Número do cartão do comprador (PAN).	N	≤ 19	NÃO
token	HASH de um cartão armazenado no e-SiTef. Não é permitido enviar um número de cartão aberto (campo ‘number’) e um cartão armazenado (campo ‘token’) na mesma requisição.	AN	= 88	NÃO
wallet_transaction_id	ID de uma transação de carteiras digitais. Por enquanto, essa funcionalidade está disponível apenas para a autorizadora Visa Checkout (authorizer_id:406). Não é permitido enviar um número de cartão aberto (campo ‘number’), um cartão armazenado (campo ‘token’) e um wallet_transaction_id na mesma requisição.	AN	≤ 25	NÃO

Obs: Apesar de não obrigatório, recomenda-se o envio do authorizer_id para a consulta de cartão, principalmente para roteamentos via SiTef, a fim de comportamentos mais efetivos em relação ao roteamento cadastrado para a autorizadora.

Parâmetros de resposta

Em caso de sucesso, o código de resposta HTTP será 200. 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 consulta de cartão:

Nome do Parâmetro	Descrição	Tipo	Tamanho
code	Código de resposta do e-SiTef. Qualquer código diferente de ‘0’ significa falha. Para maiores informações, consulte o documento “Anexo A-2 – Codigos de Resposta”.	N	≤ 4
message	Mensagem de resposta do e-SiTef.	AN	≤ 500
status	Status da transação de pré-autorização no e-SiTef. Para mais informações, consulte o item 11.1.	AN	= 3
authorizer_code	Código de resposta do autorizador.	AN	≤ 10
authorizer_message	Mensagem de resposta do autorizador.	AN	≤ 500
acquirer_name	Nome do roteamento. Ex.: Cielo	AN	≤ 256
authorizer_id	Código da autorizadora (utilizar este ID ao realizar o pagamento).	N	≤ 3
is_customer_id_required	Indica a obrigatoriedade da coleta do documento do cliente.	T/F	≤ 5
is_expiry_date_required	Indica a obrigatoriedade da coleta da data de validade do cartão do comprador.	T/F	≤ 5
is_installment_funding_enabled	Indica se o parcelamento está habilitado.	T/F	≤ 5
is_security_code_required	Indica a obrigatoriedade da coleta do código de segurança.	T/F	≤ 5
is_spot_sale_enabled	Indica se o pagamento à vista está habilitado.	T/F	≤ 5
is_with_interest_sale_enabled	Indica se o pagamento com juros está habilitado.	T/F	≤ 5
is_without_interest_sale_enabled	Indica se o pagamento sem juros está habilitado.	T/F	≤ 5
max_installments_with_interest	Parcelamento máximo com juros.	N	≤ 2
min_installments_with_interest	Parcelamento mínimo com juros.	N	≤ 2
visa_checkout_data	Objeto com os dados retornados pela Visa Checkout.
financing_plan_list	Objeto que consiste em um array de planos de financiamento apresentados em roteamento Via Certa Financiadora. Um plano de financiamento consiste dos seguintes campos: - cod_plano: código de identificação do plano de financiamento, que deve ser enviado no momento da efetivação do pagamento; - tipo_plano: código do tipo do plano de financiamento; - desc_plano: descrição do plano, que pode ser apresentado ao comprador; - parc_plano: número máximo de parcelas possíveis para o plano.
is_customer_postal_code_required	Indica a obrigatoriedade da coleta do código postal do usuário (CEP no Brasil).	T/F	< 5
Key	Nome do prefixo.	AN	≤ 1024
value	Valor do prefixo	AN	≤ 1024

Cancelamento de pré-autorização e captura

Se a transação de pré-autorização foi realizada com sucesso e a Loja Virtual não queira realizar a captura, poderá cancelar a pré-autorização, liberando o valor reservado do limite do cartão ao cliente. Caso a captura não ocorra, após um determinado período de tempo a pré-autorização é desfeita automaticamente, porém o cliente pode desejar que a pré-autorização seja cancelada antes, de forma a liberar o valor do seu limite do cartão.

É importante saber que apenas uma transação de pré-autorização não capturada pode ser cancelada em dias posteriores. Uma transação de captura só pode ser cancelada no mesmo dia em que foi feita.

Para realizar o cancelamento da pré-autorização ou da captura de pré-autorização o fluxo é ligeiramente diferente, no sentido que a criação da transação de cancelamento devolve o nit na URL de Autenticidade, ou seja, a chamada aa operação beginCancelTransaction retornará simplesmente um “OK” e o nit será devolvido na URL de Autenticidade previamente cadastrada.

Note que o e-SiTef somente irá enviar a mensagem “OK” caso o envio do NIT tenha sido bem-sucedido, com o servidor da loja respondendo “HTTP 200 OK” e só depois do retorno do “HTTP 200 OK” que o nit da transação de cancelamento poderá ser utilizado.

Informações para o desenvolvimento da transação de cancelamento inclusive com hash, consulte o manual Interface Web Service REST de Pagamento, Agendamento e Cancelamento. Caso ainda não tenha recebido o documento, solicitar ao e-mail autorizadores5317@softwareexpress.com.br ou pelo tel. (11)3170-5317.

Operação getStatus – consulta de transações

Em caso de falha na comunicação ou demora excessiva na resposta (timeout) em qualquer uma das operações subsequentes ao beginTransaction, a loja obrigatoriamente deverá consumir a operação getStatus. Esta operação permite que se verifique o status de uma requisição a qual o lojista não obteve a resposta, recuperando os parâmetros que não pôde receber no fluxo normal.

A loja deverá recuperar o status da transação (com o prazo máximo para a consulta de 15 dias) desde que possua o nit, através do webservice getStatus, passando como parâmetro a chave de autenticação da loja (merchantKey) e o nit.

Desenvolvimento/Certificação: caso não tenha recebido o merchantKey para desenvolvimento/certificação, favor solicitar através do e-mail autorizadores5317@softwareexpress.com.br ou pelo telefone (11) 3170-5317.

Produção: o merchantKey para Produção será enviado pela equipe do e-SiTef de Produção, caso não tenha recebido depois dos devidos procedimentos para a entrada em Produção, favor solicitar ao e-mail esitef.prod6773@softwareexpress.com.br.

Note que em casos excepcionais a chave de autenticação (merchantKey) pode ser alterada por questões de segurança, porém a equipe de produção irá entrar em contato com a loja antes da alteração.

Lembrando que diversos fatores podem ocasionar a demora na resposta, incluindo instabilidade de internet e o host da rede autorizadora do cartão. Recomendamos que o servidor da loja tenha configurado o timeout igual ou superior a 90 segundos.

Nota: Este serviço só irá devolver os dados se a transação tiver sido efetuada via Web Services, não irá funcionar em caso de transações via Interface HTML.

Atenção: A consulta de transação no e-SiTef NÃO efetua uma consulta do status da transação no adquirente / autorizador. Este serviço retorna o status da transação na base de dados do e-SiTef.
Exemplo: Caso uma transação de pré-autorização seja confirmada no e-SiTef, mas seja estornada via telefone diretamente no adquirente / autorizador, este estorno não será necessariamente refletido no serviço de consulta de transação do e-SiTef.

Detalhes da chamada

Recurso: /v1/transactions/{nit}

Método HTTP: GET

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
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
nit	Identificador da transação no e-SiTef. Obtido no retorno da chamada ao beginTransaction.	= 64 A	Sim

Parâmetros da requisição da operação getStatus

Na URL do recurso deve ser enviado o nit

Nome do Parâmetro	Descrição	Tamanho	Obrigatório
nit	Identificador da transação no e-SiTef. Obtido no retorno da chamada ao beginTransaction.	= 64 A	Sim

A chamada da operação de consulta de transações – getStatus – não necessita de corpo de requisição.

Parâmetros da resposta da operação getStatus

Nome do Parâmetro	Descrição	Tamanho
code	Código de resposta do e-SiTef. Qualquer código diferente de "0" significa falha na consulta. Para maiores informações, consulte o documento Anexo A-2 - Codigos de Resposta.	< 4 N
message	Mensagem de resposta do e-SiTef da consulta.	< 500 AN
acquirer_id	Código do adquirente/roteamento utilizado na transação.	< 4 N
acquirer_name	Nome do adquirente/roteamento utilizado na transação.	< 100 AN
amount	Valor da compra especificado pela loja (em centavos) na criação da transação.	< 12 AN
authorization_number	Número de autorização.	< 6 AN
authorizer_code	Código de resposta do autorizador.	< 10 AN
authorizer_date	Data de efetivação da pré-autorização retornada pelo autorizador no formato DD/MM/AAAA’T’HH:mm.
Exemplo: 13/07/2017T16:03	= 16 D
authorizer_id	Código da autorizadora utilizada na transação.	< 4 N
authorizer_merchant_id	Código de afiliação do lojista na autorizadora.	< 100 AN
authorizer_message	Mensagem de resposta do autorizador.	< 500 AN
customer_receipt	Cupom (via cliente).	< 4000 AN
eci	Eletronic Commerce Indicator (indicador do nível de segurança da transação do pré-autorização via Cielo e-Commerce).	< 3 AN
esitef_usn	Número sequencial único da transação de pré-autorização no e-SiTef.	= 6 N
host_usn	NSU da autorizadora.	< 15 AN
issuer	Código da bandeira retornado pelo autorizador.	< 5 AN
merchant_receipt	Cupom (via estabelecimento).	< 4000 AN
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 AN
nit	Identificador da transação de pré-autorização no e-SiTef.	= 64 AN
order_id	Código de pedido enviado pela loja na criação da transação.	< 40 AN
payment_type	Tipo do pagamento da autorizadora escolhida: B = boleto, C = crédito, D = débito, P = cartão crédito Private Label puro, T = tranferência bancária, G = cartão gift, O = outros meios de pagamentos, W = Boleto NR via Web Service	= 1 A
sitef_usn	Número sequencial único da transação de pré-autorização no SiTef.	= 6 N
status	Status da transação de pré-autorização no e-SiTef.	= 3 AN
tid	ID da transação no adquirente/roteamento. Este campo só é retornado em transações com adquirentes externos ao SiTef.	< 40 AN
xid	Campo XID retornado em autenticações 3DS ou certos adquirentes/roteamentos.	< 40 AN
acquirer_id	Código do adquirente/roteamento utilizado na transação.	< 4 N
acquirer_name	Nome do adquirente/roteamento utilizado na transação.	< 100 AN
amount	Valor da compra especificado pela loja (em centavos) na criação da transação.	< 12 AN
authorization_number	Número de autorização.	< 6 AN
authorizer_code	Código de resposta do autorizador.	< 10 AN
authorizer_date	Data de efetivação do pré-autorização retornada pelo autorizador no formato DD/MM/AAAA’T’HH:mm. Exemplo: 13/07/2017T16:03	= 16 D
authorizer_id	Código da autorizadora utilizada na transação.	< 4 N
authorizer_merchant_id	Código de afiliação do lojista na autorizadora.	< 100 AN
authorizer_message	Mensagem de resposta do autorizador.	< 500 AN
customer_receipt	Cupom (via cliente).	< 4000 AN
eci	Eletronic Commerce Indicator (indicador do nível de segurança da transação do pré-autorização via Cielo e-Commerce).	< 3 AN
esitef_usn	Número sequencial único da transação de pré-autorização no e-SiTef.	= 6 N
host_usn	NSU da autorizadora.	< 15 AN
issuer	Código da bandeira retornado pelo autorizador.	< 5 AN
merchant_receipt	Cupom (via estabelecimento).	< 4000 AN
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 AN
nit	Identificador da transação de pré-autorização no e-SiTef.	= 64 AN
order_id	Código de pedido enviado pela loja na criação da transação.	< 40 AN
payment_type	Tipo do pagamento da autorizadora escolhida: B = boleto, C = crédito, D = débito, P = cartão crédito Private Label puro, T = tranferência bancária, G = cartão gift, O = outros meios de pagamentos, W = Boleto NR via Web Service	= 1 A
sitef_usn	Número sequencial único da transação de pré-autorização no SiTef.	= 6 N
status	Status da transação de pré-autorização no e-SiTef.	= 3 AN
tid	ID da transação no adquirente/roteamento. Este campo só é retornado em transações com adquirentes externos ao SiTef.	< 40 AN
xid	Campo XID retornado em autenticações 3DS ou certos adquirentes/roteamentos.	< 40 AN

Atenção: Os campos code e message se referem ao código e mensagem referentes à requisição de consulta. Estes não se referem às transações consultadas.

Exemplo de requisição

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Exemplo de requisição

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "pre_authorization": {
        "acquirer_id": "1181",
        "acquirer_name": "GetNet Lac",
        "amount": "1470",
        "authorization_number": "301367",
        "authorizer_code": "000",
        "authorizer_date": "30/10/2018T11:58",
        "authorizer_id": "1",
        "authorizer_merchant_id": "000000000000000",
        "authorizer_message": "Transacao OK
            SDO DISPONIVEL                                              
            244,00",
        "customer_receipt": 
            ".....S.O.F.T.W.A.R.E.E.X.P.R.E.S.S....
            \nSI                            Rede 181
            \nMU               Codigo transacao: 100
            \nLA             Codigo operacao: 113000
            \nDO                        Valor: 14,70
            \n.....S...I...M...U...L...A...D...O....
            \nSI                   NSU SiTef: 301367
            \nMU                      30/10/18 11:58
            \nLA                    ID PDV: ES000025
            \nDO             Estab.: 000000000000000
            \n.....S...I...M...U...L...A...D...O....
            \nSI                     Host: 010301367
            \nMU         Transacao Simulada Aprovada
            \n                               (SiTef)
            \n",
        "esitef_usn": "181030016873984",
        "host_usn": "010301367   ",
        "issuer": "1",
        "merchant_receipt": 
            ".....S.O.F.T.W.A.R.E.E.X.P.R.E.S.S....  
            \nSI                            Rede 181
            \nMU               Codigo transacao: 100
            \nLA             Codigo operacao: 113000
            \nDO                        Valor: 14,70
            \n.....S...I...M...U...L...A...D...O....
            \nSI                   NSU SiTef: 301367
            \nMU                      30/10/18 11:58
            \nLA                    ID PDV: ES000025
            \nDO             Estab.: 000000000000000
            \n.....S...I...M...U...L...A...D...O....
            \nSI                     Host: 010301367
            \nMU         Transacao Simulada Aprovada
            \n                               (SiTef) 
            \n",
        "merchant_usn": "20180809",
        "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
        "order_id": "oioi",
        "payment_type": "C",
        "sitef_usn": "301367",
        "status": "CON"
    },
    "capture": {
        "acquirer_id": "1181",
        "acquirer_name": "GetNet Lac",
        "amount": "1380",
        "authorization_number": "000000",
        "authorizer_date": "30/10/2018T12:00",
        "authorizer_id": "1",
        "customer_receipt": 
            ".....S.O.F.T.W.A.R.E.E.X.P.R.E.S.S.... 
            \nSI                            Rede 181
            \nMU               Codigo transacao: 220
            \nLA             Codigo operacao: 113002
            \nDO                        Valor: 13,80
            \n.....S...I...M...U...L...A...D...O....
            \nSI                   NSU SiTef: 301368
            \nMU                      30/10/18 12:00
            \nLA                    ID PDV: ES000025
            \nDO             Estab.: 000000000000000
            \n.....S...I...M...U...L...A...D...O....
            \nSI                     Host: 010301368
            \nMU         Transacao Simulada Aprovada 
            \n                               (SiTef)                                          
            \n",
        "esitef_usn": "181030016874034",
        "host_usn": "010301368   ",
        "issuer": "1",
        "authorizer_code": "000",
        "authorizer_message": "Transacao OK
        SDO DISPONIVEL          244,00",
        "merchant_receipt": 
            ".....S.O.F.T.W.A.R.E.E.X.P.R.E.S.S....
            \nSI                            Rede 181                                          
            \nMU               Codigo transacao: 220                                          
            \nLA             Codigo operacao: 113002                                          
            \nDO                        Valor: 13,80                                          
            \n.....S...I...M...U...L...A...D...O....                                          
            \nSI                   NSU SiTef: 301368                                          
            \nMU                      30/10/18 12:00                                          
            \nLA                    ID PDV: ES000025                                          
            \nDO             Estab.: 000000000000000                             
            \n.....S...I...M...U...L...A...D...O....                                          
            \nSI                     Host: 010301368               
            \nMU         Transacao Simulada Aprovada
            \n                               (SiTef)                                          
            \n",
        "merchant_usn": "20180809",
        "nit": "abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr1234567890",
        "order_id": "201808020001",
        "authorizer_merchant_id": "000000000000000"
        "payment_type": "C",
        "sitef_usn": "301368",
        "status": "CON"
    }
}

Tabelas compartilhadas

Status de transações do e-SiTef

Código	Nome	Descrição
NOV	Nova	Transação recém-criada.
INV	Inválida	Transação não foi criada com sucesso, provavelmente a loja enviou algum parâmetro incorreto, e não foi possível inicializar a transação corretamente.
PPC	Pendente de confirmação	Pagamento pendente de confirmação.
PPN	Desfeita	Pagamento pendente não confirmado (cancelado).
PEN	Aguardando pagamento	Transação aguardando resposta da instituição financeira.
CON	Efetuada	Transação confirmada pela instituição financeira.
NEG	Negada	Transação negada pela instituição financeira.
ERR	Erro ao efetuar pagamento	Erro na comunicação com a autorizadora. Tente novamente.
BLQ	Bloqueada	Transação bloqueada após múltiplas tentativas de consulta de cartão.
EXP	Expirada	A transação expirou devido ao prazo de validade do NIT.
EST	Estornada	Pagamento estornado.