Serviço de efetivação de recarga
Detalhes da chamada#
- Recurso:
/v3/recharge/{nit} - Método HTTP:
PUT - Formato da requisição:
JSON - Formato da resposta:
JSON - Parâmetros de cabeçalho:
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
Content-Type | Deve ser enviado com o valor application/json. | = 15 AN | SIM |
Authorization | Assinatura 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 AN | COND. |
Exemplos#
Abaixo estão exemplos de chamada do serviço de efetivação de recarga utilizando a ferramenta cURL.
Recarga tipo normal 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:
Recarga tipo normal sem 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:
Recarga tipo others#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
Recarga tipo invoice#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
Parâmetros de requisição#
Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de efetivação de recarga:
| Parâmetro | Descrição | Formato | Obrigatório | |||
|---|---|---|---|---|---|---|
nit | Identificação da transação de recarga no Carat | = 64 AN | SIM | |||
amount | Valor da recarga, em centavos | < 12 N | SIM | |||
amount_key | Código do valor da recarga | < 10 AN | NÃO | |||
terminal_type | 01 - PDV02 - TU03 - TAS04 - Internet05 - POS-Sitef/POS | = 2 N | NÃO | |||
cpf | CPF do cliente | < 20 AN | NÃO | |||
cnpj | CNPJ do cliente | < 20 AN | NÃO | |||
zip_code | CEP do cliente | < 9 AN | NÃO | |||
| hashes | ||||||
general | Código de identificação da tabela com os dados relativos às recargas (operadoras, filiais, faixas de valores, validades dos créditos, dentre outros). | = 16 AN | NÃO | |||
| dealer | ||||||
code | Código da concessionária/operadora | < 3 N | SIM | |||
type_code | Código do tipo concessionária/operadora | < 2 N | SIM | |||
| dealer.branch | ||||||
code | Código da filial da concessionária/operadora. Obrigatório apenas para recarga tipo others. | 11 N | COND. | |||
| phone | ||||||
phone.ddd | Código DDD do telefone. Obrigatório apenas para recarga tipo normal. | = 2 N | COND. | |||
phone.number | Número do telefone. Obrigatório apenas para recarga tipo normal. | < 9 N | COND. | |||
| answers[] | ||||||
code | Código da pergunta a ser respondida | < 20 AN | COND. | |||
description | Resposta da pergunta | < 200 AN | COND. | |||
| invoice | ||||||
bar_code | Código de barras da fatura escolhida. | = 48 N | SIM para tipo invoice | |||
description | Descrição da fatura escolhida. | < 64 AN | SIM para tipo invoice | |||
expiry_date | Data de validade da fatura escolhida em formato DDMMAAAA. | = 8 N | SIM para tipo invoice | |||
reference_data | Dados de referência da fatura escolhida. | < 32 AN | SIM para tipo invoice | |||
echo | Valor do campo echo recebido na listagem de dados da filial. | < 11 N | SIM para tipo invoice | |||
| payment | ||||||
amount | Valor do pagamento, em centavos | < 12 N | SIM* | |||
authorizer_id | Código da autorizadora no Carat. Saiba mais. | < 5 N | SIM* | |||
customer_id | Documento de identidade do comprador. Use apenas caracteres alfanuméricos | < 20 AN | NÃO | |||
merchant_key | Chave da loja cadastrada no Carat. Deve ser a mesma loja utilizada para efetuar a recarga. | < 80 AN | SIM* | |||
| payment.installment | ||||||
number | Número de parcelas | < 2 N | SIM* | |||
type | Tipo de financiamento do parcelamento:3 - parcelamento com juros da administradora do cartão,4 - parcelamento realizado pela loja e sem juros. (Adotar este valor como padrão/default para transações à vista)6 - parcelamento com juros da administradora (IATA)7 - parcelamento realizado pela loja e sem juros (IATA) | = 1 N | SIM* | |||
| payment.card | ||||||
number | Número do cartão. | < 19 N | SIM* | |||
token | Token do cartão armazenado no Carat. | = 88 AN | SIM* | |||
security_code | Código de segurança do cartão. Campo opcional, se enviado, será utilizado o código de empresa SiTef principal, não o de recorrência (que não pede código de segurança). Sua obrigatoriedade depende do contrato firmado com as Adm. de cartão. | < 5 N | COND. | |||
expiry_date | Data de vencimento no formato MMAA | = 4 N | SIM* | |||
| payment.extra_param[] | ||||||
key | Chave do parâmetro extra | N/A | NÃO | |||
value | Valor do parâmetro extra | N/A | NÃO | |||
| used_payment_methods[] | ||||||
Envio do campo used_payment_methods#
A loja deve utilizar o próprio campo used_payment_methods para indicar ao Carat quais formas de pagamento foram utilizadas para pagar uma determinada transação, como por exemplo uma recarga.
A quantidade de dados a serem gravadas no campo used_payment_methods é limitada pelo campo payment_methods.max. Se, por exemplo, foi recebido o valor 3 no campo payment_methods.max, então a loja só poderá gravar 3 informações no campo used_payment_methods.
Para cada forma de pagamento utilizada deve ser gravado um elemento (dado) no campo used_payment_methods. O dado a ser gravado no campo used_payment_methods possui o seguinte formato:
TipoN:ValorN:IDColetaN1:DadoColetaN1-IDColetaN2:DadoColetaN2-...-IDColetaNn:DadoColetaNn
Onde:
TipoN: indica a forma de pagamento utilizada (conforme tabela já apresentada acima).ValorN: indica o valor utilizado com esta forma de pagamento, com duas casas decimais, sem a vírgula.IDColetaNn: indica o ID do campo que foi coletado pela loja (conforme tabela já apresentada acima).DadoColetaNn: indica o conteúdo coletado pela loja para este campo.
Observações:
Se para uma determinada forma de pagamento nenhum campo deva ser coletado pela loja, o campo used_payment_methods deve ser valorizado com os seguintes dados: TipoN:ValorN.
A consistência dos valores (soma das várias formas de pagamento utilizadas, totalizando o valor da transação realizada) deve ser feita pela loja, sendo que o Carat só utilizará os valores da maneira como foram enviados.
Exemplo
Vamos supor que na execução de uma transação de recarga, a loja obteve o valor 2 na leitura do campo payment_methods.max e os seguintes valores do campo used_payment_methods:
O valor 2 recebido no campo payment_methods.max, indica à loja que o mesmo só pode fazer o pagamento da recarga com no máximo 2 formas de pagamento diferentes.
Supondo que a loja realizou o pagamento da recarga da seguinte maneira: R$ 30,00 em dinheiro e R$ 20,00 com cartão de débito processados pela rede adquirente Rede (Rede Destino = 5; NSU do Host = 123456789; Dados de confirmação = 0520200001A6). Neste caso, o campo used_payment_methods deverá ser valorizado com os seguintes dados:
Envio de dados do cartão para pagamento#
Caso se deseje enviar o token de cartão armazenado no Carat, os demais dados de cartão (card.number, card.expiry_date) não serão considerados.
Caso se deseje enviar os dados abertos do cartão, o token não deve ser enviado.
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 efetivação de recarga:
| Parâmetro | Descrição | Formato |
|---|---|---|
status | Status da transação de recarga no Carat. Saiba mais. | = 3 AN |
order_id | Código do pedido gerado pela loja. | < 20 AN |
merchant_usn | NSU da transação gerado pela loja. | < 12 N |
tv_package_subscription_codes[] | Códigos de assinaturas de pacotes de TV. | < 32 AN |
resubmit_transaction | Se este campo receber o valor true, a loja deve reenviar a requisição de efetivação de recarga com o campo answers preenchido da seguinte maneira:"answers":[{"code":"126","description":"<um dos códigos recebidos no campo tv_package_subscription_codes>"}] Neste caso, o status da transação será retornado como AGU.Este fluxo só é possível na realização de Recarga TV. | T/F |
send_payment_methods | Flag que indica que as formas de pagamento devem ser enviadas na próxima transação. Terá o valor true caso positivo. | < 5 AN |
| esitef | ||
code | Código de resposta do Carat. Qualquer código diferente de 0(zero) significa falha. Saiba mais. | < 4 N |
message | Mensagem de resposta do Carat. | < 500 AN |
usn | NSU da transação de recarga no Carat | = 15 N |
| sitef | ||
code | Código de resposta do SiTef | = 3 AN |
message | Mensagem de resposta do SiTef | < 500 AN |
| host | ||
code | Código de resposta retornado pela autorizadora | < 4 AN |
message | Mensagem retornada pela autorizadora | < 64 AN |
| acquirer | ||
branch_code | Código da filial da recarga | < 5 N |
merchant_code | Código da loja cadastrada no adquirente | < 15 N |
| authorization | ||
confirmation_data | Código da confirmação | < 128 AN |
authorizer_date | Data da autorização na autorizadora no formato MMDD | = 4 N |
authorizer_time | Horário da autorização na autorizadora no formato HHmmSS | = 6 N |
host_usn | NSU do Host | < 20 N |
sitef_usn | NSU do SiTef | < 10 N |
number | Número da autorização na autorizadora | < 6 N |
| customer | ||
total_copies | Número de vias do comprovante do cliente | < 2 N |
receipt | Comprovante do cliente | < 4000 AN |
| merchant | ||
total_copies | Número de vias do comprovante do estabelecimento | < 2 N |
receipt | Comprovante do estabelecimento | < 4000 AN |
| hashes | ||
general | Código de identificação da tabela com os dados relativos às recargas (operadoras, filiais, faixas de valores, validades dos créditos, dentre outros). | = 16 AN |
wallet | Hash das carteiras digitais. | < 32 AN |
| payment_methods | ||
max | Número máximo de formas de pagamento | < 2 N |
| payment_methods.available[] | Este campo agrega uma lista de formas de pagamento disponíveis. | |
name | Nome da forma de pagamento disponível. Saiba mais. | < 200 AN |
| payment | Este elemento somente é retornado caso um pagamento atrelado à recarga tenha sido enviado. | |
status | Status da transação de pagamento no Carat. Saiba mais. | = 3 AN |
amount | Valor do pagamento, o mesmo enviado na criação da transação de pagamento. | < 12 AN |
type | Tipo do pagamento da autorizadora escolhida:
| = 1A |
authorizer_id | Id da autorizadora no Carat onde o pagamento foi feito | < 5 N |
acquirer | Tipo de pagamento | < 50 AN |
| payment.esitef | ||
usn | NSU do Carat | < 15 AN |
date | Data do pagamento no formato DD/MM/AAAA hh:mm no Carat. | < 19A |
| payment.sitef | ||
code | Código de resposta retornado pelo SiTef | = 3 AN |
| payment.customer | ||
receipt | Comprovante do pagamento (via cliente) | < 4000 AN |
| payment.merchant | ||
receipt | Comprovante do pagamento (via estabelecimento) | < 4000 AN |
| payment.authorization | ||
number | Número de autorização do pagamento | < 6 AN |
sitef_usn | NSU do SiTef | < 15 AN |
host_usn | NSU da autorizadora | < 15 AN |
tid | ID da transação na autorizadora, retornado por alguns tipos de pagamento. | < 40 AN |
eci | Eletronic commerce indicator retornado por alguns tipos de pagamento. | < 3 AN |
sitef_date | Data do pagamento no formato DD/MM/AAAA hh:mm no SiTef. | < 19 AN |
| payment.analysis | ||
status | Status da transação na instituição de análise. | = 3 AN |
code | Código de resposta da análise de risco. | < 4 AN |
message | Mensagem de resposta da análise de risco. | < 100 AN |
| payment.extra_param[] | ||
key | Chave do parâmetro extra | N/A |
value | Valor do parâmetro extra | N/A |
Importante:
No caso de recargas de outros produtos (
others) que envolvam pins (por exemplo, pins de jogos), o pin será retornado uma única vez, como parte do campopayment.customer.receipt. Por se tratar de um campo sensível, o Carat não o armazena, de forma que consultas de status posteriores não devolverão o pin. Caso ocorra algum problema após o retorno do pin pelo Carat, o pin não poderá ser recuperado e será necessário gerar outro.