Crear servicio de recarga

Descripción general#

Portal Carat dispone de dos interfaces de integración con la tienda online, POST/HTML y Web Services (REST), que permiten a la tienda interactuar con la tienda online de forma adecuada, dependiendo del idioma y plataforma de ejecución de la tienda online.

La interfaz HTML se definió como una forma sencilla y rápida de integrarse con los métodos y servicios de pago que existen en Portal Carat, pero sin perder flexibilidad. La interfaz estándar tiene solo dos parámetros obligatorios, recopilando los demás en el propio portal o mediante la configuración realizada por el administrador de la tienda en la parte posterior de Portal Carat, sin embargo, si la aplicación de la tienda virtual desea pasar definiciones o restricciones para un cierto tipo de servicio, red o incluso número de cuotas, esto se puede hacer a través del conjunto de parámetros pasados al inicio de la transacción, antes de la redirección del cliente.

Flujo#

La tienda inicia el flujo predeterminado después de que el comprador completa la compra:

! Flujo de recarga de HTML

La tienda debe iniciar la transacción con Portal Carat enviando los datos de compra a través del [servicio de creación de transacciones] (pagamento-html-begin.md).

El flujo de recarga consta de los siguientes pasos:

Después de que el comprador finalice la compra, la tienda crea una nueva transacción en Portal Carat, a través de un POST en la URL para iniciar una transacción, informando de todos los parámetros necesarios. Más información
En respuesta al POST, la tienda recibirá una URL de Portal Carat a la que el comprador debe ser redirigido. Esta URL será diferente para cada transacción de recarga.
El comprador seleccionará los datos de la recarga, como concesionario/operador, ddd y el valor de la recarga, y verá los datos asociados a este valor, como la validez, la bonificación, etc.
Después de esto, el comprador procederá con el flujo de pago, seleccionando el pago entre los disponibles para la tienda.
En el último paso del pago, se realizarán las operaciones de pago y recarga, en el autorizador y en el concesionario/operador, respectivamente, en este orden.
Al final del flujo, el Portal Carat redirigirá al comprador de vuelta a la tienda, según la configuración de las URL´s de retorno ya registradas en la tienda, o a las back_url´s (ver Tabla 1) enviadas al crear las transacciones.

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

Todas las llamadas realizadas serán atendidas sincrónicamente, excepto la notificación de Status que se realizará mediante Portal Carat de forma asincrónica.

Iniciar una transacción de recarga#

Para iniciar una recarga de HTML, consulte la documentación de [quickstart] (recarga-html-quickstart.md).

Realización de una transacción de recarga#

Al acceder a la URL devuelta por el [servicio de creación de transacciones] (pagamento-html-begin.md), se devolverá la pantalla de selección del valor de recarga, como se muestra en la siguiente figura:

! Flujo de recarga de HTML-no-filter

Proceso de creación de transacciones#

El proceso de creación de la transacción debe seguir estos pasos:

La transacción se crea de acuerdo con los parámetros enviados en la clave request y se representa mediante un objeto JSON a través de POST en la solicitud;
La tienda recibe un mensaje de éxito o error, con formato XML o JSON, según el parámetro "tipo de devolución" en la URL enviada al iniciar una transacción.

URL para iniciar una transacción a través de HTTPS POST:

Ambiente de homologación:
https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/init/[tipo_de_retorno].se
Ambiente de producción
https://esitef-ec.softwareexpress.com.br/e-sitef/init/[tipo_de_retorno].se

Atención: La IP nunca debe usarse en lugar del dominio esitef-ec.softwareexpress.com.br (o esitef-homologacao.softwareexpress.com.br para el entorno de homologación). La IP puede cambiar en cualquier momento y sin previo aviso, por lo que es importante utilizar siempre el dominio para acceder al Portal Carat .

Parámetros POST:

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

Ejemplo de solicitud JSON (JavaScriptObjectNotation):

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/init/json.se

Objeto JSON request mínimo:

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

Objeto JSON "request" con algunos parámetros adicionales:

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

Herramientas de prueba#

Para las pruebas iniciales en esta interfaz, si es necesario, se pueden utilizar algunas herramientas para comprender mejor la comunicación a través de REST:

Aplicación para Windows / Linux / Mac:
- [POSTMAN] (https://www.getpostman.com)
Extensión para Firefox:
- [RESTClient] (http://restclient.net)

Abajo, se muestran ejemplos de pantalla de estas herramientas:

POSTMAN -no-filter

RESTClient -no-filter

Parámetros de solicitud#

El objeto JSON additional_data tiene campos que cambian según el autorizador utilizado para el pago, por el campo authorizer_id. Para obtener más detalles sobre el campo additional_data, consulte la documentación específica de cada autorizador compatible con la interfaz de Pago HTML 2.0.

Para iniciar una transacción en la nueva interfaz de pago HTML, inicialmente se pueden completar los siguientes parámetros en formato JSON.

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

| Parámetro | Descripción | Formato | Obligatorio | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ----------- | | amount | Importe total a pagar por el comprador.
Formato:
Debe enviarse en centavos.
Ex.: 1000 (10 reales). | < 12 N | SÍ | | recharge_included | Informa si se realizará una recarga.

Valores permitidos:
true - si se realiza una recarga.
false - si no se realiza una recarga.
Valor predeterminado - falso | < 5 A | SÍ | | recharge | Objeto de tipo RECHARGE.
Contiene datos relacionados con una transacción de recarga. | | NO |

RECHARGE (`recharge`)#

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

Parámetro	Descripción	Formato	Obligatorio
`dealer_code`	Código del concesionario/operador	< 3 N	NO
`phone`	Objeto de tipo PHONE. Contiene datos relacionados con la recarga del teléfono.		NO

PHONE (`phone`)#

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

Parámetro	Descripción	Formato	Obligatorio
`number`	numero de teléfono.	< 20 N	NO
`ddd`	ddd (código de área) del teléfono.	< 4 N	NO

Parámetros de respuesta#

La devolución de la operación de creación de la transacción se da en el formulario solicitado en [tipo de devolución].

Abajo se muestra un ejemplo de un retorno JSON:

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

Los campos devueltos se describen en la siguiente tabla:

| Parámetro | Descripción | Formato | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | | responseCode | Código de respuesta de Portal Carat. Cualquier código que no sea 0(cero) significa falla. Sepa mas. | < 5 N | | description | Descripción de la respuesta | < 1024 A | | url | URL de redirección para iniciar el pago. | < 256 A | | nit | Identificador de transacción de Portal Carat | = 64 A | | nsuesitef |NSU (número secuencial único) de la transacción de Portal Carat | = 15 A |

Home