Serviço de consulta de recarga

Essa chamada permite que a loja consulte o status de uma transação de recarga e pagamento atrelado (caso exista) no Carat, a qualquer momento dentro do fluxo, após criar uma recarga.

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 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 status da transação do Carat.

Detalhes da chamada#

  • Recurso: /v3/recharge/{nit}
  • Método HTTP: GET
  • Formato da requisição: query string
  • Formato da resposta: JSON
  • Parâmetros de cabeçalho:
ParâmetroDescriçãoFormatoObrigatório
AuthorizationAssinatura de autenticidade no formato Bearer {assinatura}. Saiba mais.

Exemplo: Bearer hh39458f73hf45324765ft349h5f73t4h95f34.

Este campo é obrigatório caso a transação tenha sido criada pelo processo de assinatura.
< 2000 ANCOND.

Exemplos#

Abaixo está um exemplo de chamada do serviço de consulta de recarga utilizando a ferramenta cURL.

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/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678/?merchantkey=ASDFGHJK12345678ASDFGHJK12345678"
--verbose

Resposta:

{
"get_status_recharge_response":{
"status":"CON",
"esitef":{
"message":"OK",
"code":"0"
},
"authorizers":[
{
"name":"sitef",
"message":"textoExibicao",
"code":"codigoRespSitef"
},
{
"name":"nome operadora (186)",
"message":"OK",
"code":"196"
}
],
"acquirer":{
"branch_code":"cod filial",
"merchant_code":"codigoEstab"
},
"authorization":{
"confirmation_data":"000033333",
"authorizer_date":"20150514",
"authorizer_time":"1100",
"host_usn":"11122",
"sitef_usn":"333",
"number":"332234"
},
"customer":{
"total_copies":3,
"receipt":"COMPROVANTE DE RECARGA mimimim cliente whiskas sache"
},
"merchant":{
"total_copies":3,
"receipt":"COMPROVANTE DE RECARGA mimimim estabelecimento lorem ipsum"
},
"payment_methods":{
"max":2,
"available":[
{
"name":"dinheiro"
},
{
"name":"cheque"
}
]
},
"payment":{
"status":"PPC",
"amount":"12",
"type":"C",
"esitef":{
"usn":"098765432109876",
"date":"12/12/2012 12:12"
},
"customer":{
"receipt":"nwiugrnboinbAPROVADOaoisuerhn"
},
"merchant":{
"receipt":"nwiugrnboinbAPROVADOaoisuerhn"
},
"authorizer_id":"1",
"acquirer":"CIELO",
"authorization":{
"number":"163457212",
"sitef_usn":"456456",
"host_usn":"654654",
"tid":"7334312a2",
"eci":"fr3u214wf71",
"sitef_date":"12122012"
},
"analysis":{
"status":"PEN",
"code":"0",
"message":"hahaha"
},
"extra_param":[
{
"key":"CRIPTO",
"value":"1"
}
],
"sitef":{
"code":"000"
}
}
}
}

Parâmetros de requisição#

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de consulta de recarga:

ParâmetroDescriçãoFormatoObrigatório
nitIdentificação da transação de recarga no Carat= 64 ANSIM
merchantkeyChave da loja no Carat utilizada na recarga.< 80 ANSIM

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 recarga:

ParâmetroDescriçãoFormato
statusStatus da transação de recarga no Carat. Saiba mais.= 3 AN
order_idCódigo do pedido gerado pela loja.< 20 AN
merchant_usnNSU da transação gerado pela loja.< 12 N
send_payment_methodsFlag que indica que as formas de pagamento utilizadas podem ser enviadas na próxima transação.Terá o valor true caso positivo.< 5 N
esitef
codeCódigo de resposta do Carat. Qualquer código diferente de 0(zero) significa falha. Saiba mais.< 4 N
messageMensagem de resposta do Carat.< 500 AN
usnNSU da transação de recarga no Carat= 15 N
authorizers[]Este campo agrega uma lista de elementos.
nameNome do autorizador< 16 AN
codeCódigo de resposta retornado pela autorizadora< 4 AN
messageMensagem retornada pela autorizadora< 64 AN
acquirer
branch_codeCódigo da filial da recarga, responsável pela recarga do conjunto DDD + operadora.< 5 N
merchant_codeCódigo da loja cadastrada no adquirente< 15 N
authorization
confirmation_dataCódigo da confirmação< 128 AN
authorizer_dateData da autorização na autorizadora no formato MMDD= 4 N
authorizer_timeHorário da autorização na autorizadora no formato HHmmSS= 6 N
host_usnNSU do Host< 20 N
sitef_usnNSU do SiTef< 10 N
numberNúmero da autorização na autorizadora< 6 N
customer
total_copiesNúmero de vias do comprovante do cliente< 2 N
receiptComprovante do cliente< 4000 AN
merchant
total_copiesNúmero de vias do comprovante do estabelecimento< 2 N
receiptComprovante do estabelecimento< 4000 AN
payment_methods
maxNúmero máximo de formas de pagamento< 2 N
payment_methods.available[]Este campo agrega uma lista de formas de pagamento disponíveis.
nameNome da forma de pagamento disponível. Saiba mais.< 200 AN
paymentEste elemento somente é retornado caso um pagamento atrelado à recarga tenha sido enviado.
statusStatus da transação de pagamento no Carat. Saiba mais.= 3 AN
amountValor do pagamento, o mesmo enviado na criação da transação de pagamento.< 12 AN
typeTipo do pagamento da autorizadora escolhida:
  • B = boleto
  • C = crédito
  • D = débito
  • P = cartão crédito Private Label
  • T = tranferência bancária
  • G = cartão gift
  • O = outros meios de pagamentos
= 1A
authorizer_idId da autorizadora no Carat onde o pagamento foi feito< 5 N
acquirerTipo de pagamento< 50 AN
payment.esitef
usnNSU do Carat< 15 AN
dateData do pagamento no formato DD/MM/AAAA hh:mm no Carat.< 19A
payment.sitef
codeCódigo de resposta retornado pelo SiTef= 3 AN
payment.customer
receiptComprovante do pagamento (via cliente)< 4000 AN
payment.merchant
receiptComprovante do pagamento (via estabelecimento)< 4000 AN
payment.authorization
numberNúmero de autorização do pagamento< 6 AN
sitef_usnNSU do SiTef< 15 AN
host_usnNSU da autorizadora< 15 AN
tidID da transação na autorizadora, retornado por alguns tipos de pagamento.< 40 AN
eciEletronic commerce indicator retornado por alguns tipos de pagamento.< 3 AN
sitef_dateData do pagamento no formato DD/MM/AAAA hh:mm no SiTef.< 19 AN
payment.analysis
statusStatus da transação na instituição de análise.= 3 AN
codeCódigo de resposta da análise de risco.< 4 AN
messageMensagem de resposta da análise de risco.< 100 AN
payment.extra_param[]
keyChave do parâmetro extraN/A
valueValor do parâmetro extraN/A
hashesHashes que indicam o status das mudanças nas tabelas de recarga
generalHash geral das tabelas de recarga. Este hash será alterado se algum dos hashes de uma rede específica for alterado.= 16 AN
walletHash das tabelas de recarga de uma rede específica. Se as tabelas da rede de recarga sofrer alguma alteração, o hash retornado neste campo também será alterado. O dado retornado neste campo possui o seguinte formato:
<Rede>:<Hash>:<Serviço 1>,< Serviço 2>, <Serviço N> Onde:
  • Rede = Código da rede de recarga
  • Hash = Hash referente às tabelas de recarga da Rede.
  • Serviço n = Tipo de serviço disponibilizado pela Rede, os quais podem ser:
    • F1-1 = Recarga Telefone Nacional
    • F1-3 = Recarga Outros Produtos
  • Os separadores são dois-pontos e vírgula.

Exemplo de dado retornado neste campo: 106:0D0C4FCB0D0C4FCB:F1-1,F1-3
< 100 AN

Consulta de transações em um grupo de lojas#

O Carat exige que as credenciais (merchantkey) 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.