Serviço de criar Recarga

Visão Geral#

O Carat possui duas interfaces para integração com a loja virtual, POST/HTML e Web Services (REST ou SOAP), possibilitando a maneira adequada de interação da loja com o Carat, conforme a linguagem e plataforma de execução da loja virtual.

A interface HTML foi definida para ser uma maneira simples e rápida de integração com os meios de pagamentos e serviços existentes no Carat, no entanto sem perder a flexibilidade. A interface padrão possui apenas dois parâmetros obrigatórios, realizando a coleta dos demais no próprio portal ou através de configurações realizadas pelo administrador da loja na retaguarda do Carat, no entanto se a aplicação da loja virtual quiser passar definições ou restrições para um determinado tipo de serviço, rede ou mesmo número de parcelas, isto poderá ser feito através do conjunto de parâmetros passados no início da transação, antes do redirecionamento do cliente.

Fluxo#

O fluxo padrão é iniciado pela loja após o comprador finalizar a compra:

Fluxo de recarga com pagamento Interface HTML 2.0#

A loja deverá iniciar a transação com o Carat enviando os dados da compra através do serviço de criação de transação.

O fluxo de recarga consiste nos seguintes passos:

Após o comprador finalizar a compra, a loja cria uma nova transação no Carat, através de um POST na URL para iniciar uma transação, informando todos os parâmetros necessários. Saiba mais.
Como resposta ao POST, a loja receberá uma URL do Carat a qual o comprador deve ser redirecionado. Esta URL será diferente a cada transação de recarga.
O comprador selecionará os dados de recarga como concessionária/operadora, ddd, número de telefone e valor da recarga, e visualizará dados associados a este valor, como validade, bônus, etc.
Após isto, o comprador seguirá com o fluxo de pagamento, selecionando a autorizadora de pagamento, dentre as disponíveis para a loja.
Na etapa final do pagamento, as transações de pagamento e de recarga serão efetivadas, respectivamente na autorizadora e na concessionária/operadora, nesta ordem.
Ao final do fluxo, o Carat irá redirecionar de volta o comprador para a loja, conforme configuração de URL’s de retorno já cadastrados na loja, ou para as back_url’s (vide Tabela 1) enviadas na criação das transações.

Para cada alteração de status da transação de pagamento no Carat, a loja receberá um POST de aviso de status, informando a situação da mesma. Saiba mais.

Todas as chamadas realizadas serão respondidas de forma síncrona exceto o aviso de status que será realizado pelo Carat de forma assíncrona.

Iniciando uma transação de recarga#

Para iniciar um recarga HTML, veja a documentação de quickstart.

Efetuando uma transação de recarga#

Ao acessar a url retornada pelo serviço de criação de transação, a tela de seleção de valores de recarga será retornada, conforme a figura abaixo:

Fluxo de recarga HTML -no-filter

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:

POSTMAN -no-filter

RESTClient -no-filter

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. Formato: Deve ser enviado em centavos. Ex.: 1000 (10 reais).	< 12 N	SIM
`recharge_included`	Informa se uma recarga será feita. Valores permitidos: `true` – caso uma recarga for realizada. `false` – caso uma recarga não for realizada. Valor default - `false`	< 5 A	SIM
`recharge`	Objeto do tipo RECHARGE. 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. 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

Home