ESPECIFICACIONES DE PROTOCOLO SERVICIOS DE BANCA MOVIL RECARGAS CELULARES
Conectividad
El esquema de seguridad para el procesamiento de recargas requiere medidas de seguridad más estrictas que para la mensajería sms, por lo que los esquemas de conectividad entre Movilgate y el Banco podrán ser solo de dos tipos:
- HTTPS.
- VPN IPSec.
Glosario:
- PR: Pedido de Recarga: Originado por el Banco y procesado por Movilgate.
- CR: Confirmación de Recarga: Status definitivo para el PR solicitado previamente por el Banco. Originado por Movilgate y enviado al Banco tan pronto se conoce el mismo.
Arquitectura
La arquitectura de comunicaciones se basa en un modelo cliente/servidor bilateral asíncrono. Los pedidos de recarga celular del Banco (PR) serán enviados por un cliente del mismo a un webservice que nosotros proveeríamos. La confirmación del procesamiento del pedido de recarga (CR: una vez el mismo haya pasado por todas las instancias necesarias) realizado previamente será enviado por un cliente nuestro a un webservice que debería implementar el Banco. La comunicación asíncrona se refiere a que las confirmaciones a los pedidos de recarga no son generadas y enviadas en la misma transacción en que se realiza el pedido de la misma, sino que son generadas y enviadas como una transacción/servicio separado. Este punto se comprenderá en detalle en la descripción del protocolo propuesto.
Protocolo de comunicaciones
El mismo se basa en transacciones HTTP del tipo Post por las cuales se transfieren contenidos (paquetes) del tipo XML.
Manejo de PR
REQUEST:
Para hacer una solicitud de recargas, los servidores bancarios deberán enviar vía HTTP/Post el siguiente paquete XML:
<?xml version="1.0"?>
<PRRequest>
<Operador>operador.pais</Operador>
<MSISDN>nnnnnnnnnn</MSISDN>
<Monto>float</Monto>
<Moneda>Text</Moneda>
<Operacion>Text</Operacion>
<Integrador>Text</Integrador>
<Fecha>yyyy-mm-dd hh:mm:ss</Fecha>
<Id_Banco>Text</Id_Banco>
<usuario>Text</usuario>
<clave>Text</clave>
</PRRequest>
Donde:
- Operador: Es el operador celular al que pertenece el usuario. El armado de este campo se realiza de la siguiente manera: Servicio = operador.pais Donde:
- Operador: Nombre del operador al que pertenece el respectivo teléfono celular. Ejemplo: personal
- País: siglas IANA (Internet Assigned Numbers Authority) para el país del respectivo operador. Ejemplo: ar.
- Teléfono MSISDN: Teléfono del usuario. El mismo se conformará según el standard vigente para el operador/país de que se trate.
- Monto: Monto a recargar sobre la línea celular. El mismo es del tipo float con dos decimales. Los montos permitidos dependerán de cada operador y país en que se esté operando, detallándose en cada caso los montos mínimos, máximos e incremento posibles para cada operador. El separador decimal a utilizar es el carácter ‘.’.
- Moneda: Moneda a la que se refiere el monto. Dependerá de cada país y operador.
- Operacion: Dependerá de las facilidades operativas que ofrezca el integrador a utilizar. Como mínimo siempre estará disponible la operación ‘RECARGAR’ la cual se aplica a la recarga de la línea celular. Podrían estar disponibles otras tales como ‘SALDO’ por la cual se consultaría el saldo de la respectiva línea.
- Integrador: Identificador del integrador de recargas a utilizar. Dependerá de la cobertura geográfica (países) que requiera el Banco y/o cliente.
- Fecha: Fecha y hora actuales según los servidores bancarios. El formato para la misma será: yyyy-mm-dd hh:mm:ss
- Id_Banco: Id de transacción generada por el banco. El propósito de la misma es facilitar el posterior seguimiento/auditoría de las transacciones realizadas dado que deberá existir una relación biunívoca entre los id de transacción generados por Movilgate y los generados por el banco. Es alfanumérico de hasta 30 dígitos.
- usuario: Nombre de usuario provisto por Movilgate necesario para validar cada transacción.
- clave: Contraseña asociada al usuario, provista por Movilgate.
Ejemplo:
<?xml version="1.0"?>
<PRRequest>
<Operador>movistar.ar</Operador>
<MSISDN>1161958630</MSISDN>
<Monto>50.00</Monto>
<Moneda>PESOS</Moneda>
<Operacion>RECARGAR</Operacion>
<Integrador>meflur.ar</Integrador>
<Fecha>2007-11-10 14:37:05</Fecha>
<Id_Banco>ABC1234</Id_Banco>
<usuario>bancoXX</usuario>
<clave>passXX</clave>
</PRRequest>
RESPONSE:
A este request nuestros servidores responderán con un código HTTP 200 (considerando que el request Post fue realizado de forma correcta). Con esta respuesta, se enviará el siguiente paquete xml como respuesta:
<?xml version="1.0"?>
<PRResponse>
<IdStatus>n</IdStatus>
<IdTran>xxxxx</IdTran>
<Status>yyyyyyyy</Status>
</PRResponse>
Donde:
- IdStatus: Numérico, describiendo el status de la transacción. Se adoptará para la misma 0 para indicar una transacción exitosa. Valores distintos de cero indicarán distintas posibles condiciones de error.
- IdTran: Id de transacción, generado por Movilgate y utilizado para mantener identificadas las cadenas de eventos generadas por este PR. Entero de 10 dígitos con numeración consecutiva.
- Status: Texto descriptivo del status de la transacción. Caso de producirse errores, la descripción detallada de los mismos se podrá obtener en este campo.
Ejemplo:
<?xml version="1.0"?>
<PRResponse>
<IdStatus>0</IdStatus>
<IdTran>1234567890</IdTran>
<Status>Transaccion exitosa</Status>
</PRResponse>
Manejo de CR
REQUEST:
Para el envío de la confirmación de recargas (CR) Movilgate hará el siguiente request HTTP con contenido XML a un servidor provisto por el Banco:
<?xml version="1.0"?>
<CRRequest>
<Fecha>yyyy-mm-dd hh:mm:ss</Fecha>
<IdStatus_Recarga>n</IdStatus_Recarga>
<IdTran>mmmm</IdTran>
<Id_Banco>yyyyy</Id_Banco>
<Integrador>xxxxx</Integrador>
<Ref_Integrador>xxxxxxxxxx</Ref_Integrador>
<Status_Recarga>xxxx</Status_Recarga>
<codproducto_Integrador>zzzz</codproducto_Integrador>
</CRRequest>
Para el envío de la confirmación de recargas (CR) Movilgate hará el siguiente request HTTP con contenido XML a un servidor provisto por el Banco:
<?xml version="1.0"?>
<CRRequest>
<Fecha>yyyy-mm-dd hh:mm:ss</Fecha>
<IdStatus_Recarga>n</IdStatus_Recarga>
<IdTran>mmmm</IdTran>
<Id_Banco>yyyyy</Id_Banco>
<Integrador>xxxxx</Integrador>
<Ref_Integrador>xxxxxxxxxx</Ref_Integrador>
<Status_Recarga>xxxx</Status_Recarga>
<codproducto_Integrador>zzzz</codproducto_Integrador>
</CRRequest>
Donde:
- Fecha: Fecha y hora actuales según nuestros servidores. El formato para la misma será: yyyy-mm-dd hh:mm:ss
- IdStatus_Recarga: Numérico, describiendo el status de la transacción de recarga. Se adoptará para la misma 0 para indicar una transacción exitosa. Valores distintos de cero indicarán distintas posibles condiciones de error.
- IdTran: IdTran del PR que origina este CR.
- Id_Banco: Id del banco para el PR originante tal como fue descripto previamente.
- Integrador: Id de referencia del integrador utilizado para esta recarga. Necesario en caso de haber procesos de conciliación directos entre el Banco y el respectivo integrador. De haber algún error de comunicaciones entre Movilgate y el respectivo integrador por el cual no se pueda procesar esta operación, se indicará este evento a través de los respectivos Status y este campo vendrá vacio.
- Ref_Integrador: Identificador de referencia provisto por el ente de recarga para identificar la transacción. Este dato es único e irrepetible.
- Status_Recarga: Texto descriptivo del status de la transacción. Caso de producirse errores, la descripción detallada de los mismos se podrá obtener en este campo.
- codproducto_Integrador: Código de producto utilizado por el integrador invocado para esta recarga. Necesario en caso de haber procesos de conciliación directos entre el Banco y el respectivo integrador. De haber algún error de comunicaciones entre Movilgate y el respectivo integrador por el cual no se pueda procesar esta operación, se indicará este evento a través de los respectivos Status y este campo vendrá vacio.
Ejemplo:
<?xml version="1.0"?>
<CRRequest>
<Fecha>2014-04-07 16:42:37</Fecha>
<IdStatus_Recarga>0</IdStatus_Recarga>
<IdTran>484655</IdTran>
<Id_Banco>BANCO1</Id_Banco>
<Integrador>seac.ar</Integrador>
<Ref_Integrador>JVAFUWPU76</Ref_Integrador>
<Status_Recarga>Transaccion exitosa</Status_Recarga>
<codproducto_Integrador>21</codproducto_Integrador>
</CRRequest>
RESPONSE:
La respuesta HTTP de los servidores bancarios deberá ser un código 200 que se acompañará del siguiente paquete XML:
<?xml version="1.0"?>
<CRResponse>
<Id_Status_Banco>n</Id_Status_Banco>
<Status_Banco>yyyyyyyy</Status_Banco>
</CRResponse>
Donde:
- Id_Status_Banco y Status_Banco: Corresponden a condiciones de éxito u error que el Banco puede utilizar para facilitar la depuración y seguimiento de las operaciones. Al igual que para otras situaciones, la condición de ‘éxito’ se denotará con un valor de 0 en Id_Status_Banco adjuntando el respectivo texto descriptivo de la situación en el campo Status_Banco.
Ejemplo:
<?xml version="1.0"?>
<CRResponse>
<Id_Status_Banco>0</Id_Status_Banco>
<Status_Banco>Transaccion exitosa</Status_Banco>
</CRResponse>
Flujo de recargas:
Apéndice A: Parámetros para la República Argentina
Parámetros a utilizar para recargas de usuarios correspondientes a operadores de la República Argentina. Para las solicitudes PRRequest:
- Operador: movistar.ar, personal.ar o cti.ar
- Operación: Sólo ‘RECARGAR’.
- Integrador: meflur.ar
- Monto: Para los tres operadores:
- mínimo: $ 10.00
- máximo: $ 100.00
- incremento: $1.00
