Serviço de efetivação de recarga

import ApiDoc from '../../src/components/api-doc/ApiDoc';

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.<br/><br/>Exemplo: `Bearer {TOKEN_JWT_EXAMPLE}`.<br/><br/>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<br/> <URLPOSTMAN/>

curl
--request PUT "https://{{url}}/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
   "do_recharge_request":{
      "hashes":{
         "general":"0000000000000000"
      },
      "dealer":{
         "code":"1",
         "type_code":"03",
         "branch":{
            "code":"98006000000"
         }
      },
      "phone":{
         "ddd":"11",
         "number":"123456789"
      },
      "amount":"3000",
      "amount_key":"3",
      "used_payment_methods":[
         "11",
         "12"
      ],
      "answers":[
         {
            "code":"1",
            "description":"resposta"
         },
         {
            "code":"2",
            "description":"resposta2"
         }
      ],
      "terminal_type":"03",
      "cpf":"8298374982374",
      "cnpj":"123121333000123",
      "zip_code":"01310100",
      "payment":{
         "amount":"12",
         "authorizer_id":"1",
         "customer_id":"12341234",
         "merchant_key":"OIAUSWHFN012375901J23047FNN00UYWHN0R871Y2ND87",
         "installment":{
            "number":"2",
            "type":"4"
         },
         "card":{
            "number":"1111111111111111",
            "token":"",
            "security_code":"123",
            "expiry_date":"1222"
         },
         "extra_param":[
            {
               "key":"CRIPTO",
               "value":"1"
            }
         ]
      }
   }
}
--verbose

Resposta:

{
   "do_recharge_response":{
      "status":"PPC",
      "order_id":"12344231",
      "merchant_usn":"5123",
      "esitef":{
         "message":"OK",
         "code":"0",
         "usn":"123456789012345"
      },
      "sitef":{
         "message":"OK",
         "code":"0"
      },
      "host":{
         "message":"OK",
         "code":"0"
      },
      "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 via do cliente"
      },
      "merchant":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA via do estabelecimento"
      },
      "payment_methods":{
         "max":4,
         "available":[
            {
               "name":"dinheiro"
            },
            {
               "name":"cheque"
            }
         ]
      },
      "payment":{
         "status":"PPC",
         "amount":"12",
         "type":"C",
         "esitef":{
            "usn":"098765432109876",
            "date":"12/12/2012 12:12"
         },
         "customer":{
            "receipt":"nwiugrnboinb APROVADO via do cliente"
         },
         "merchant":{
            "receipt":"nwiugrnboinb APROVADO via do estabelecimento "
         },
         "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":"aprovado"
         },
         "extra_param":[
            {
               "key":"CRIPTO",
               "value":"1"
            }
         ],
         "sitef":{
            "code":"000"
         }
      }
   }
}

Recarga tipo `normal` sem pagamento

Requisição:

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

curl
--request PUT "https://{{url}}/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
   "do_recharge_request":{
      "dealer":{
         "code":"1"
      },
      "phone":{
         "ddd":"11",
         "number":"123456789"
      },
      "amount":"3000"
   }
}
--verbose

Resposta:

{
   "do_recharge_response":{
      "status":"PPC",
      "order_id":"12344231",
      "merchant_usn":"5123",
      "esitef":{
         "message":"OK",
         "code":"0",
         "usn":"123456789012345"
      },
      "sitef":{
         "message":"OK",
         "code":"0"
      },
      "host":{
         "message":"OK",
         "code":"0"
      },
      "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 via do cliente"
      },
      "merchant":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA via do estabelecimento"
      },
      "payment_methods":{
         "max":4,
         "available":[
            {
               "name":"dinheiro"
            },
            {
               "name":"cheque"
            }
         ]
      }
   }
}

Recarga tipo `others`

Requisição:

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

curl
--request PUT "https://{{url}}/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
   "do_recharge_request":{
      "dealer":{
         "code":"901",
         "type_code":"03",
         "branch":{
            "code":"98006000000"
         }
      },
      "amount":"3000"
   }
}
--verbose

Resposta:

{
   "do_recharge_response":{
      "status":"PPC",
      "order_id":"12344231",
      "merchant_usn":"5123",
      "esitef":{
         "message":"OK",
         "code":"0",
         "usn":"123456789012345"
      },
      "sitef":{
         "message":"OK",
         "code":"0"
      },
      "host":{
         "message":"OK",
         "code":"0"
      },
      "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 via do cliente"
      },
      "merchant":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA via do estabelecimento"
      }
   }
}

Recarga tipo `invoice`

Requisição:

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

curl
--request PUT "https://{{url}}/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
   "do_recharge_request":{
      "hashes":{
         "general":"85E791AD85E791AD"
      },
      "dealer":{
         "code":"800",
         "branch":{
            "code":"80019000000"
         }
      },
      "amount":"6339",
      "terminal_type":"04",
      "cpf":"12312312312",
      "cnpj":"11110110000101",
      "zip_code":"12345678",
      "invoice":{
         "bar_code":"88888888888888888888888888888888888888888888",
         "description":"Boleto Parcial Credito Manual",
         "expiry_date":"21082007",
         "reference_data":"082007",
         "echo":"12340000000"
      }
   }
}
--verbose

Resposta:

{
   "do_recharge_response":{
      "status":"PPC",
      "order_id":"31045431771",
      "merchant_usn":"2047986911",
      "esitef":{
         "message":"OK. Transaction successful.",
         "code":"0",
         "usn":"200831056294572"
      },
      "sitef":{
         "message":"Transacao Aprovada",
         "code":"000"
      },
      "acquirer":{
         "merchant_code":"302800000000000"
      },
      "authorization":{
         "confirmation_data":"0831310011A6",
         "authorizer_date":"0831",
         "authorizer_time":"165459",
         "host_usn":"000310011",
         "sitef_usn":"310011",
         "number":"000000"
      },
      "customer":{
         "receipt":"----- COMPROVANTE -----"
      },
      "merchant":{
         "receipt":"----- COMPROVANTE -----"
      },
      "payment_methods":{
         "max":"4",
         "available":[
            {
               "name":"00"
            },
            {
               "name":"01"
            },
            {
               "name":"02:03-07-08-09-10-14"
            },
            {
               "name":"03:03-07-08-09-10-14"
            },
            {
               "name":"04:10"
            },
            {
               "name":"05:10"
            },
            {
               "name":"06:10"
            }
         ]
      },
      "hashes":{
         "general":"85E791AD85E791AD",
         "wallet":""
      },
      "send_payment_methods":"true"
   }
}

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` - PDV<br/>`02` - TU<br/>`03` - TAS<br/>`04` - Internet<br/>`05` - 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
	<td colspan="3" /> 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
	<td colspan="3" /> 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	<td colspan="3" />
`code`	Código da filial da concessionária/operadora. Obrigatório apenas para recarga tipo `others`.	11 N	COND.
	<td colspan="3" /> 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.
	<td colspan="3" /> answers[]<br/>Este campo agrega uma lista de respostas. Obrigatório caso perguntas tenham sido recebidas na listagem de dados da filial.
`code`	Código da pergunta a ser respondida	< 20 AN	COND.
`description`	Resposta da pergunta	< 200 AN	COND.
	<td colspan="3" /> invoice<br/> Este objeto contém campos obrigatórios para pagamento sem fatura (recarga tipo `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`
	<td colspan="3" /> payment<br/>Este elemento somente deve ser enviado caso se deseje efetuar um pagamento atrelado à recarga.<br/><br/>Atenção:* O pagamento é permitido apenas no tipo de recarga `normal`. Para o tipo de recarga `others` a transação será invalidada.
`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*
	<td colspan="3" /> payment.installment
`number`	Número de parcelas	< 2 N	SIM*
`type`	Tipo de financiamento do parcelamento:<br/>`3` - parcelamento com juros da administradora do cartão,<br/>`4` - parcelamento realizado pela loja e sem juros. (Adotar este valor como padrão/default para transações à vista)<br/>`6` - parcelamento com juros da administradora (IATA)<br/>`7` - parcelamento realizado pela loja e sem juros (IATA)	= 1 N	SIM*
	<td colspan="3" /> 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*
	<td colspan="3" /> payment.extra_param[]<br/> Este campo agrega uma lista de parâmetros extras.
`key`	Chave do parâmetro extra	N/A	NÃO
`value`	Valor do parâmetro extra	N/A	NÃO
	<td colspan="3" /> used_payment_methods[]<br/>Formas de pagamento utilizadas. Este campo agrega uma lista de valores que devem ser enviados conforme descrito no capítulo abaixo.

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:

00
02:03-07-10-13(5,125)
03:10

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:

00:3000
02:2000:03:5-07:123456789-10:0520200001A6

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:<br/><br/>`"answers":[{"code":"126","description":"<um dos códigos recebidos no campo tv_package_subscription_codes>"}]`<br/><br/>Neste caso, o status da transação será retornado como `AGU`.<br/><br/>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: `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_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 campo payment.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.

Detalhes da chamada

Exemplos

Recarga tipo normal com pagamento

Recarga tipo normal sem pagamento

Recarga tipo others

Recarga tipo invoice

Parâmetros de requisição

Envio do campo used_payment_methods

Envio de dados do cartão para pagamento

Parâmetros de resposta

Recarga tipo `normal` com pagamento

Recarga tipo `normal` sem pagamento

Recarga tipo `others`

Recarga tipo `invoice`

Envio do campo `used_payment_methods`