Serviço de criar Recarga

import RecargaVisaoGeral from './recarga-html-fluxo.md';

<RecargaVisaoGeral />

Processo de criação da transação

O processo de criação de transação deverá seguir os seguintes passos:

• A transação é criada conforme os parâmetros enviados na chave request e representados por um objeto JSON via POST na requisição;
• A loja recebe uma mensagem de sucesso ou erro, formatada como XML ou JSON, conforme o parâmetro "tipo de retorno" na URL enviada ao se iniciar uma transação.

URL para iniciar uma transação via POST HTTPS:

Ambiente de Homologação:
https://{{url}}/e-sitef-hml/init/[tipo_de_retorno].se
Ambiente de Produção
https://esitef-ec.softwareexpress.com.br/e-sitef/init/[tipo_de_retorno].se

Atenção: Nunca deve ser usado o IP ao invés do domínio esitef-ec.softwareexpress.com.br (ou {{url}} para ambiente de homologação). O IP pode mudar a qualquer instante e sem aviso prévio, logo é importante sempre utilizar o domínio para acessar o Carat.

Parâmetros do POST:

• Key/chave: request;
• Value/valor: objeto JSON;
• [tipo_de_retorno]: json ou xml;

Exemplo de requisição JSON (JavaScriptObjectNotation):

URL: https://{{url}}/e-sitef-hml/init/json.se

Objeto JSON request mínimo:

{
  "merchant_id": "codigoDaLoja",
  "amount": "1800"
}

Objeto JSON "request" com alguns parametros adicionais:

{
  "merchant_id": "codigoDaLoja",
  "order_id": "123456",
  "installments": "4",
  "recharge_included": "true",
  "recharge": {
    "dealer_code": "2",
    "phone": {
      "number": "87654321",
      "ddd": "11"
    }
  }
}

Ferramentas para testes

Para testes iniciais nesta interface, caso necessário, podem ser usadas algumas ferramentas a fim de um melhor entendimento da comunicação via REST:

• Aplicação para Windows/Linux/Mac:
  • POSTMAN
• Extensão para Firefox:
  • RESTClient

Abaixo seguem exemplos de tela destas ferramentas:

Parâmetros de requisição

O objeto JSON additional_data possui campos que se alteram conforme a autorizadora utilizada para o pagamento, pelo campo authorizer_id. Para mais detalhes do campo additional_data, por favor consulte a documentação específica para cada autorizadora suportada pela Interface de Pagamento HTML 2.0.

Para iniciar uma transação na nova interface de pagamento HTML, inicialmente podem ser preenchidos os seguintes parâmetros no formato JSON.

{
  "merchant_id": "codigoDaLoja",
  "recharge_included": "true",
  "recharge": {}
}

Parâmetro	Descrição	Formato	Obrigatório
amount	Valor total a ser pago pelo comprador.<br/>Formato:<br/>Deve ser enviado em centavos.<br/>Ex.: 1000 (10 reais).	< 12 N	SIM
recharge_included	Informa se uma recarga será feita.<br/><br/>Valores permitidos:<br/> true – caso uma recarga for realizada.<br/>false – caso uma recarga não for realizada. <br/>Valor default - false	< 5 A	SIM
recharge	Objeto do tipo RECHARGE.<br/>Contêm dados relacionados a uma transação de recarga.		NÃO

RECHARGE (recharge)

{
  "dealer_code": "1",
  "phone": {}
}

Parâmetro	Descrição	Formato	Obrigatório
dealer_code	Código da concessionária/operadora	< 3 N	NÃO
phone	Objeto do tipo PHONE.<br/>Contêm dados relacionados ao telefone da recarga.		NÃO

PHONE (phone)

{
  "number": "123456789",
  "ddd": "11"
}

Parâmetro	Descrição	Formato	Obrigatório
number	número do telefone.	< 20 N	NÃO
ddd	ddd (código de área) do telefone.	< 4 N	NÃO

Parâmetros de resposta

O retorno da operação de criação de transação se dá na forma solicitada no [tipo de retorno].

Abaixo segue um exemplo de retorno JSON:

{
  "responseCode": 0,
  "description": "OK. Transaction successful.",
  "url": "https:// {{url}}/e-sitef/do.se?input['nit']= 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
  "nsuesitef": "123456789012345",
  "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
}

Os campos retornados são descritos na tabela abaixo:

Parâmetro	Descrição	Formato
responseCode	Código de resposta do Carat. Qualquer código diferente de 0(zero) significa falha. Saiba mais.	< 5 N
description	Descrição da resposta	< 1024 A
url	URL de redirecionamento para iniciar o pagamento.	< 256 A
nit	Identificador da transação no Carat	= 64 A
nsuesitef	NSU (Número Sequencial Único) da transação no Carat	= 15 A