Serviço de consulta de transação

import ApiDoc from '../../src/components/api-doc/ApiDoc'; import ApiParams from '../../src/components/api-doc/ApiParams'; import ResponseCodes from './codigos-de-resposta.md';

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

<ApiDoc method="get" path="/e-sitef/api/v1/transactions/{nit}" />

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:

<ApiParams method="get" path="/e-sitef/api/v1/transactions/{nit}" />

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:

<ApiParams method="get" path="/e-sitef/api/v1/schedules/{sid}" />

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<br/> <URLPOSTMAN/>

curl
--request GET "https://{{url}}/e-sitef/api/v1/transactions/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"13064421440",
      "customer_receipt":"==== CUPOM COMPRADOR ====",
      "merchant_receipt":"==== CUPOM ESTABELECIMENTO ====",
      "authorizer_id":"2",
      "acquirer_id":"229",
      "acquirer_name":"Bin",
      "authorizer_date":"13/07/2017T18:44",
      "authorization_number":"132048",
      "merchant_usn":"13064421441",
      "esitef_usn":"170713097341620",
      "sitef_usn":"132048",
      "host_usn":"999132048   ",
      "payment_date":"13/07/2017T18:44",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005"
   }
}

Consulta de agendamento

Requisição:

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor<br/> <URLPOSTMAN/>

curl
--request GET "https://{{url}}/e-sitef/api/v1/schedules/qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "schedule":{
      "status":"ATV",
      "sid":"qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01",
      "schedule_usn":"170713000000050",
      "authorizerId":"2",
      "amount":"900",
      "initial_date":"03/08/2017",
      "next_date":"03/08/2017",
      "number_of_times":"3",
      "current_times":"0",
      "installments":"1",
      "installment_type":"4",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false"
   }
}

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<br/> <URLPOSTMAN/>

curl
--request GET "https://{{url}}/e-sitef/api/v1/transactions/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"13065054564",
      "customer_receipt":"==== CUPOM COMPRADOR ====",
      "merchant_receipt":"==== CUPOM ESTABELECIMENTO ====",
      "authorizer_id":"2",
      "acquirer_id":"229",
      "acquirer_name":"Bin",
      "authorizer_date":"13/07/2017T18:51",
      "authorization_number":"132050",
      "merchant_usn":"13065054565",
      "esitef_usn":"170713097341630",
      "sitef_usn":"132050",
      "host_usn":"999132050   ",
      "payment_date":"13/07/2017T18:51",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005"
   },
   "schedule":{
      "status":"ATV",
      "sid":"qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01",
      "schedule_usn":"170713000000060",
      "authorizerId":"2",
      "amount":"900",
      "initial_date":"03/08/2017",
      "next_date":"03/10/2017",
      "number_of_times":"3",
      "current_times":"2",
      "installments":"1",
      "installment_type":"4",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false",
      "nits":[
         "123412341234111",
         "123412341234222"
      ]
   }
}

<ApiDoc method="get" path="/e-sitef/api/v1/schedules/{sid}" />

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<br/> <URLPOSTMAN/>

curl
--request GET "https://{{url}}/e-sitef/api/v1/schedules/qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"13065054564",
      "customer_receipt":"==== CUPOM COMPRADOR ====",
      "merchant_receipt":"==== CUPOM ESTABELECIMENTO ====",
      "authorizer_id":"2",
      "acquirer_id":"229",
      "acquirer_name":"Bin",
      "authorizer_date":"13/07/2017T18:51",
      "authorization_number":"132050",
      "merchant_usn":"13065054565",
      "esitef_usn":"170713097341630",
      "sitef_usn":"132050",
      "host_usn":"999132050   ",
      "payment_date":"13/07/2017T18:51",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005"
   },
   "schedule":{
      "status":"ATV",
      "sid":"qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01",
      "schedule_usn":"170713000000060",
      "authorizerId":"2",
      "amount":"900",
      "initial_date":"03/08/2017",
      "next_date":"03/10/2017",
      "number_of_times":"3",
      "current_times":"2",
      "installments":"1",
      "installment_type":"4",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false",
      "nits":[
         "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqs",
         "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqt"
      ]
   }
}

<ResponseCodes />

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:<br/>NOV – Nova.<br/>EXP – Expirada.<br/>ACC – Aceita<br/>REJ – Rejeitada<br/>REV – Em revisão<br/>INV – 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.