Serviço de consulta de transação
A aplicação da loja deverá efetuar a consulta de status, quando ocorrer problemas no recebimento do status da transação.
Fluxo#
Para realizar a consulta, a loja deverá fazer um POST no seguinte endereço:
https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/consultarTransacao.se?nit=XXXXX
Onde XXXXX é o NIT recebido pelo site do Carat no pedido de consulta. A resposta será "OK" caso o NIT da transação esteja correto e a comunicação é encerrada.
A seguir o Carat irá enviar um POST/HTTPS na URL de aviso de status cadastrada no servidor Carat, enviando como parâmetro o código do status da transação. A loja deve estar preparada para lidar com estes status, e com a chamada HTTPS (SSL/TLS) na URL de aviso de status cadastrada.
O POST/HTTPS do Carat pode não ser imediato, mas sim, será assíncrono, com o tempo podendo variar conforme carga do servidor e da Internet. Caso haja algum problema no envio, o Carat tentará reenviar amensagem após um determinado período de tempo.
Oportuno lembrar que a loja deve aceitar o POST via HTTPS via SSL/TLS com certificado válido, e mesmo sendo válido pode ser necessária a importação do mesmo no Carat.
Outro ponto importante é que o Carat espera sempre a resposta 200 ("OK") na URL de aviso de status, não aceitando em hipótese alguma um redirecionamento (302) para outra URL e muito menos outro site.
Atenção:
A consulta de status da transação no Carat 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 pagamento seja confirmada no Carat, mas seja estornada via telefone diretamente no adquirente / autorizador, este estorno não será necessariamente refletido no serviço de consulta de status da transação do Carat.
Quando utilizar a Consulta de Status?#
Se por algum motivo o aplicativo do lojista atingir o timeout de espera e não receber o aviso de status do Carat, devido a algum problema de infraestrutura ou até mesmo problema no servidor que impediu o recebimento da resposta, nesse caso o aplicativo do lojista deverá realizar a Consulta de Status. Nessa consulta o aplicativo do lojista recebe todos os parâmetros da transação, que ele teria recebido caso o aviso de status tivesse sido recebido normalmente. Dessa forma, evita-se que um mesmo pagamento seja enviado duas vezes ou que ocorra o abandono de um pagamento que já foi enviado e depois vir a debitar o valor na fatura do cartão.
É extremamente importante que o aplicativo do lojista tenha conhecimento do status da transação no Carat antes de realizar qualquer tratamento da transação, assim impede-se que o cliente realize uma nova tentativa de pagamento de um mesmo pedido, sem saber o resultado do pagamento enviado anteriormente.
Exemplo:
Caso a URL de aviso de Status da loja cadastrada seja:
https://www.lojateste.com.br/status.php
A loja receberá um POST em:
https://www.lojateste.com.br/status.php
Segue exemplo abaixo.
POST de aviso de status:
Segue um exemplo de um post de aviso de status
Parâmetros enviados pelo post de aviso de status#
Na tabela abaixo está a descrição dos parâmetros enviados pelo Carat no POST de aviso de status:
| Parâmetro | Descrição | Formato |
|---|---|---|
nsuSitef | Número da Transação | = 6 AN |
nit | Identificador da transação de pagamento no Carat. | = 64 AN |
pedido | Código de identificação do pedido gerado pela loja | < 20 AN |
status | Indica o Status de uma transacao no e-SiTef. | = 3 N |
O Carat também pode enviar novos parâmetros sem aviso prévio, o que significa que a aplicação do lojista deve estar preparada para receber campos extras e simplesmente ignorá-los.
Atenção:
Não abuse da chamada do serviço de consulta de status, chamando-o constantemente, sob pena de o Carat passar a ignorar as chamadas.