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

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
esitef-homologacao.softwareexpress.com.br

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
esitef-homologacao.softwareexpress.com.br

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"
]
}
}

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

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"
]
}
}

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âmetroDescriçãoFormato
codeCódigo de resposta do Carat. Qualquer código diferente de 0 significa falha. Saiba mais.< 4 N
messageMensagem de resposta do Carat.< 500 AN
payment
authorizer_codeCódigo de resposta do autorizador.< 10 AN
authorizer_messageMensagem de resposta do autorizador.< 500 AN
statusStatus da transação de pagamento no Carat. Saiba mais.= 3 AN
nitIdentificador da transação de pagamento no Carat.= 64 AN
order_idCódigo de pedido enviado pela loja na criação da transação.< 40 AN
merchant_usnNúmero sequencial único enviado pela loja na criação da transação.< 12 N
amountValor da compra especificado pela loja (em centavos) na criação da transação.< 12 N
sitef_usnNúmero sequencial único da transação de pagamento no SiTef.= 6 N
esitef_usnNúmero sequencial único da transação de pagamento no Carat.= 15 N
customer_receiptCupom (via cliente).< 4000 AN
merchant_receiptCupom (via estabelecimento).< 4000 AN
authorizer_idCódigo da autorizadora utilizada na transação.< 4 N
acquirer_idCódigo do adquirente utilizado na transação.< 4 N
acquirer_nameNome do adquirente utilizado na transação.< 100 AN
authorizer_dateData de efetivação do pagamento retornada pelo autorizador no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03= 16 D
authorization_numberNúmero de autorização.< 6 AN
host_usnNSU da autorizadora.< 15 AN
tidID da transação no adquirente. Este campo só é retornado em transações com adquirentes externos ao SiTef.< 40 AN
eciEletronic Commerce Indicator (indicador do nível de segurança da transação do pagamento via Cielo e-Commerce).< 3 AN
payment_dateData de efetivação do pagamento no Carat no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03= 16 D
issuerCódigo da bandeira retornado pelo autorizador.< 5 AN
authorizer_merchant_idCódigo de afiliação do lojista na autorizadora.< 100 AN
xidCampo XID retornado em autenticações 3DS ou certos adquirentes.< 40 AN
balanceSaldo disponível após pagamentos com cartões tipo Gift.< 12 N
payment.analysis
codeCódigo de resposta da operação de análise de fraude.< 4 N
messageMensagem de resposta da operação de análise de fraude.< 200 AN
statusStatus da transação de análise de fraude do Carat. Este campo pode assumir os seguintes valores:
NOV – Nova.
EXP – Expirada.
ACC – Aceita
REJ – Rejeitada
REV – Em revisão
INV – Inválida
= 3 AN
schedule
statusStatus do agendamento no Carat. Saiba mais.= 3 AN
sidIdentificador da transação de agendamento no Carat.= 64 AN
schedule_usnNúmero sequencial único do agendamento no Carat.= 15 N
authorizer_idCódigo da autorizadora a ser utilizada nos pagamentos agendados.= 4 N
amountValor dos pagamentos agendados especificado pela loja (em centavos) na criação da transação.< 12 N
order_idCódigo de pedido enviado pela loja na criação da transação.< 40 AN
merchant_usnNúmero sequencial único enviado pela loja na criação da transação.< 12 N
initial_dateData de execução do primeiro pagamento agendado no formato DD/MM/AAAA.= 10 D
next_dateData de execução do próximo pagamento agendado no formato DD/MM/AAAA.= 10 D
number_of_timesNúmero total de pagamentos agendados.< 3 N
current_timesNúmero de pagamentos agendados já executados.< 3 N
installmentsNúmero de parcelas a ser utilizado nos pagamentos agendados.< 2 N
installment_typeTipo de financiamento a ser utilizado nos pagamentos agendados.< 2 N
soft_descriptorTexto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador.< 30 AN
show_times_invoicePara 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
nitsNITs dos últimos seis pagamentos agendados já executados.= 64 AN[]
cancellation
authorizer_codeCódigo de resposta do autorizador.< 10 AN
authorizer_messageMensagem de resposta do autorizador.< 500 AN
statusStatus da transação de cancelamento no Carat. Saiba mais.= 3 AN
nitNúmero identificador da transação de cancelamento no Carat.= 64 AN
order_idCódigo de pedido enviado pela loja na criação da transação.< 40 AN
merchant_usnNúmero sequencial único enviado pela loja na criação da transação.< 12 N
amountValor do cancelamento especificado pela loja (em centavos).< 12 N
sitef_usnNúmero sequencial único da transação de cancelamento no SiTef.= 6 N
esitef_usnNúmero sequencial único da transação de cancelamento no Carat.= 15 N
customer_receiptCupom (via cliente).< 4000 AN
merchant_receiptCupom (via estabelecimento).< 4000 AN
authorizer_idCódigo da autorizadora utilizada na transação.< 4 N
acquirer_idCódigo do adquirente utilizado na transação.< 4 N
acquirer_nameNome do adquirente utilizado na transação.< 100 AN
authorizer_dateData de efetivação do cancelamento retornada pelo autorizador no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03= 16 D
authorization_numberNúmero de autorização.< 6 AN
host_usnNSU da autorizadora.< 15 AN
tidID da transação no adquirente. Este campo só é retornado em transações com adquirentes externos ao SiTef.< 40 AN
esitef_dateData de efetivação do cancelamento no Carat no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03= 16 D
issuerCódigo da bandeira retornado pelo autorizador.< 5 AN
authorizer_merchant_idCódigo de afiliação do lojista na autorizadora.< 100 AN
is_host_cancelEste campo retornará o valor true em caso de cancelamento via host.< 5 T/F
terminal_idCódigo do terminal utilizada na transação< 8 AN
payment_typeTipo 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.