Serviço de consulta de pré-autorização
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 Carat 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 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 Carat.
Exemplo: Caso uma transação de pré-autorização 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 transação do Carat.
Detalhes da chamada#
Recurso:
/v1/transactions/{nit}Método HTTP:
GETFormato da requisição:
JSONFormato da resposta:
JSONParâ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 | ||
merchant_key | Chave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes. | ≤ 80 A | Sim |
nit | Identificador da transação no Carat. Obtido no retorno da chamada ao beginTransaction. | = 64 A | Sim |
Parâmetros de Requisição#
Na URL do recurso deve ser enviado o nit
| Nome do Parâmetro | Descrição | Tamanho | Obrigatório |
|---|---|---|---|
nit | Identificador da transação no Carat. 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 de Resposta#
| Nome do Parâmetro | Descrição | Tamanho | ||
|---|---|---|---|---|
code | Código de resposta do Carat. 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 Carat 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 Carat. | = 16 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 Carat. | = 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 Carat. | = 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 Carat. | = 15 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 Carat. | = 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 Carat. | = 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 | ||
| pre_authorization.analysis | ||||
code | Código de resposta da operação de análise de fraude na pre-autorização. | < 4 N | ||
message | Mensagem de resposta da operação de análise de fraude na pre-autorização. | < 200 AN | ||
status | Status da transação de análise de fraude na pre-autorização. Este campo pode assumir os seguintes valores:NOV – Nova.EXP – Expirada.ACC – AceitaREJ – RejeitadaREV – Em revisãoINV – Inválida | = 3 AN | ||
Atenção: Os campos
codeemessagese referem ao código e mensagem referentes à requisição de consulta. Estes não se referem às transações consultadas.
Exemplo#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
Códigos de resposta
Veja a referencia no Códigos da API - códigos de resposta
Consulta de transações em um grupo de lojas#
O Carat exige que as credenciais (merchant_id e merchant_key) sejam as mesmas utilizadas na transação a ser consultada. No entanto, caso o lojista precise, o Carat pode permitir consultas com credenciais de outras lojas de um mesmo grupo. Para isso, basta solicitar às nossas equipes de suporte e produção para que façam essa liberação.