Serviço de consulta de transação
Estes serviços podem ser chamados para obter os dados da transação de pagamento, cancelamento ou agendamento. É essencial o uso dessa operação em casos de erro de comunicação para verificar o status atual da transação, que pode ter sido efetuada ou não recebida pelo Carat.
O Carat disponibiliza um serviço para consulta a partir do NIT (pagamento/cancelamento) e um serviço para consulta a partir do SID (agendamento). No caso de pagamento com agendamento, as consultas retornarão os dados das duas transações.
Atenção: Existe um prazo máximo de 15 dias para a consulta da transação. Depois deste período, o identificador da transação (nit) é invalidado.
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 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 transação do Carat.
Detalhes da chamada#
Consulta por NIT#
- Recurso:
/v1/transactions/{nit} - Método HTTP:
GET - Formato da requisição: não há parâmetros de requisição
- Formato da resposta:
JSON - Parâmetros de cabeçalho:
Consulta por SID#
- Recurso:
/v1/schedules/{sid} - Método HTTP:
GET - Formato da requisição: não há parâmetros de requisição
- Formato da resposta:
JSON - Parâmetros de cabeçalho:
Exemplos#
Abaixo estão alguns exemplos de chamada dos serviços de consulta utilizando a ferramenta cURL.
Consulta de pagamento#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
Consulta de agendamento#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
Consulta por NIT de pagamento com agendamento#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
Consulta por SID de agendamento com pagamento#
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
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 transações:
| Parâmetro | Descrição | Formato |
|---|---|---|
code | Código de resposta do Carat. Qualquer código diferente de 0 significa falha. Saiba mais. | < 4 N |
message | Mensagem de resposta do Carat. | < 500 AN |
| payment | ||
authorizer_code | Código de resposta do autorizador. | < 10 AN |
authorizer_message | Mensagem de resposta do autorizador. | < 500 AN |
status | Status da transação de pagamento no Carat. Saiba mais. | = 3 AN |
nit | Identificador da transação de pagamento no Carat. | = 64 AN |
order_id | Código de pedido enviado pela loja na criação da transação. | < 40 AN |
merchant_usn | Número sequencial único enviado pela loja na criação da transação. | < 12 N |
amount | Valor da compra especificado pela loja (em centavos) na criação da transação. | < 12 N |
sitef_usn | Número sequencial único da transação de pagamento no SiTef. | = 6 N |
esitef_usn | Número sequencial único da transação de pagamento no Carat. | = 15 N |
customer_receipt | Cupom (via cliente). | < 4000 AN |
merchant_receipt | Cupom (via estabelecimento). | < 4000 AN |
authorizer_id | Código da autorizadora utilizada na transação. | < 4 N |
acquirer_id | Código do adquirente utilizado na transação. | < 4 N |
acquirer_name | Nome do adquirente utilizado na transação. | < 100 AN |
authorizer_date | Data de efetivação do pagamento retornada pelo autorizador no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03 | = 16 D |
authorization_number | Número de autorização. | < 6 AN |
host_usn | NSU da autorizadora. | < 15 AN |
tid | ID da transação no adquirente. Este campo só é retornado em transações com adquirentes externos ao SiTef. | < 40 AN |
eci | Eletronic Commerce Indicator (indicador do nível de segurança da transação do pagamento). | < 3 AN |
payment_date | Data de efetivação do pagamento no Carat no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03 | = 16 D |
issuer | Código da bandeira retornado pelo autorizador. | < 5 AN |
authorizer_merchant_id | Código de afiliação do lojista na autorizadora. | < 100 AN |
xid | Campo XID retornado em autenticações 3DS ou certos adquirentes. | < 40 AN |
balance | Saldo disponível após pagamentos com cartões tipo Gift. | < 12 N |
| payment.analysis | ||
code | Código de resposta da operação de análise de fraude. | < 4 N |
message | Mensagem de resposta da operação de análise de fraude. | < 200 AN |
status | Status da transação de análise de fraude do Carat. Este campo pode assumir os seguintes valores:NOV – Nova.EXP – Expirada.ACC – AceitaREJ – RejeitadaREV – Em revisãoINV – Inválida | = 3 AN |
| schedule | ||
status | Status do agendamento no Carat. Saiba mais. | = 3 AN |
sid | Identificador da transação de agendamento no Carat. | = 64 AN |
schedule_usn | Número sequencial único do agendamento no Carat. | = 15 N |
authorizer_id | Código da autorizadora a ser utilizada nos pagamentos agendados. | = 4 N |
amount | Valor dos pagamentos agendados especificado pela loja (em centavos) na criação da transação. | < 12 N |
order_id | Código de pedido enviado pela loja na criação da transação. | < 40 AN |
merchant_usn | Número sequencial único enviado pela loja na criação da transação. | < 12 N |
initial_date | Data de execução do primeiro pagamento agendado no formato DD/MM/AAAA. | = 10 D |
next_date | Data de execução do próximo pagamento agendado no formato DD/MM/AAAA. | = 10 D |
number_of_times | Número total de pagamentos agendados. | < 3 N |
current_times | Número de pagamentos agendados já executados. | < 3 N |
installments | Número de parcelas a ser utilizado nos pagamentos agendados. | < 2 N |
installment_type | Tipo de financiamento a ser utilizado nos pagamentos agendados. | < 2 N |
soft_descriptor | Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. | < 30 AN |
show_times_invoice | Para agendamentos por tempo finito, caso esse campo tenha valor true acrescenta ao final do campo soft_descriptor o número de execuções/total de execuções (exemplo: Assinatura 3/12). | < 5 T/F |
nits | NITs dos últimos seis pagamentos agendados já executados. | = 64 AN[] |
| cancellation | ||
authorizer_code | Código de resposta do autorizador. | < 10 AN |
authorizer_message | Mensagem de resposta do autorizador. | < 500 AN |
status | Status da transação de cancelamento no Carat. Saiba mais. | = 3 AN |
nit | Número identificador da transação de cancelamento no Carat. | = 64 AN |
order_id | Código de pedido enviado pela loja na criação da transação. | < 40 AN |
merchant_usn | Número sequencial único enviado pela loja na criação da transação. | < 12 N |
amount | Valor do cancelamento especificado pela loja (em centavos). | < 12 N |
sitef_usn | Número sequencial único da transação de cancelamento no SiTef. | = 6 N |
esitef_usn | Número sequencial único da transação de cancelamento no Carat. | = 15 N |
customer_receipt | Cupom (via cliente). | < 4000 AN |
merchant_receipt | Cupom (via estabelecimento). | < 4000 AN |
authorizer_id | Código da autorizadora utilizada na transação. | < 4 N |
acquirer_id | Código do adquirente utilizado na transação. | < 4 N |
acquirer_name | Nome do adquirente utilizado na transação. | < 100 AN |
authorizer_date | Data de efetivação do cancelamento retornada pelo autorizador no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03 | = 16 D |
authorization_number | Número de autorização. | < 6 AN |
host_usn | NSU da autorizadora. | < 15 AN |
tid | ID da transação no adquirente. Este campo só é retornado em transações com adquirentes externos ao SiTef. | < 40 AN |
esitef_date | Data de efetivação do cancelamento no Carat no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03 | = 16 D |
issuer | Código da bandeira retornado pelo autorizador. | < 5 AN |
authorizer_merchant_id | Código de afiliação do lojista na autorizadora. | < 100 AN |
is_host_cancel | Este campo retornará o valor true em caso de cancelamento via host. | < 5 T/F |
terminal_id | Código do terminal utilizada na transação | < 8 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 AN |
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.