Micro Pagos SMS Premium

Transcripción

1 Micro Pagos SMS Premium Idioma: Español - España

2 Índice. Información general! 4 Definiciones e información básica necesaria! 5 Concepto herramienta Micropagos! 6 Gestión de alias y precios! 7 Modo alias global 7 Modo con alias de usuario 7 Extra: valores virtuales por alias 7 Opciones de configuración generales! 8 Notificación HTTP generales 8 Respuestas a peticiones HTTP 9 Control de estado 10 Control de errores en notificaciones HTTP 11 Forzar error en notificación 11 Uso general para consultas por API 13 Opción 1: Pagos virtuales (opción común)! 15 Descripción 15 Usos y características 15 Notificación HTTP 15 Consultas API 17 Extra: valores virtuales por alias 18 Opción 2: Control de usuarios web! 19 Descripción 19 Usos y características 19 Notificación HTTP 19 Consultas API 24 Extra: valores virtuales por alias 27 Opción 3: Descarga de archivos! 28 Descripción 28 Descripción del Proceso ( formulario ) 28 Usos y características 28 URL de descarga HTTP. 28 Formula para verificar autenticidad. 29 Extra: valores virtuales por alias. 29 Opción 4: Productos numerados! 30 Descripción 30 Usos y características 30 Notificación HTTP 30 Consultas API 31 Extra: valores virtuales por alias 31 Herramienta formulario predefinido! 32 Definir oferta en tiempo de ejecución 33 Configuración general 34 Seleccionar oferta por defecto. 34 Definir ofertas alternativas. 35 Callbacks Javascript. 36 General information! 38 Definitions and basic necessary information! 39 Micropayments Tool concept! 40

3 Management of Alias and rates! 41 Global Alias mode 41 User Alias mode 41 Extra: Virtual values for aliases 41 General configuration options! 42 General HTTP notifications 42 Response for HTTP requests 43 Status control 44 Error control on HTTP requests 45 Force error on request 45 General use for API requests 47 Option 1: Virtual payments (common opt)! 49 Description 49 Uses and characteristics 49 HTTP Request 49 API requests 51 Extra: Virtual values for alias 52 Option 2: Web user management! 53 Description 53 Uses and characteristics 53 HTTP Requests 53 API Requests 57 Extra: virtual values for alias 60 Option 3: File Downloads! 61 Description 61 Process description (formulary) 61 Uses and characteristics 61 HTTP Download URL 61 Formula to verify the authenticity 62 Extra: virtual values for alias. 62 Option 4: Numbered products! 63 Description 63 Uses and characteristics 63 HTTP requests 63 API Methods 64 Extra: virtual values for alias 64 Window payment tool! 65 General configuration 66 Define offers on run time 67 Callbacks Javascript 69

4 Información general Introducción MobiAdvanced es una plataforma que permite ofrecer medios de pago vía teléfono móvil a través de SMS Premium, los cuales pueden ser egrados y automatizados con otras aplicaciones, webs u otros medios. MobiAdvanced también ofrece herramientas de uso útil, relacionadas con los pagos mediante SMS Premium y diferentes servicios relacionados el marketing móvil. Declaración de responsabilidad MobiAdvanced no ofrece garantía de ningún tipo, ya sea expresa, implícita o legal sobre el contenido declarado en este documento, MobiAdvanced no asume ninguna responsabilidad por los daños directos o indirectos que pueda ocasionar el uso del documento o los ejemplos de código indicados en el mismo. MobiAdvanced se reserva el derecho a realizar cambios y correcciones del documento sin previo aviso. MobiAdvanced no garantiza que este documento siga siendo válido en el futuro. Antes del uso de este documento, se recomienda revisar si este documento es la última versión del mismo. Documento Este documento describe como realizar una egración de la herramienta Micropagos ofrecida por MobiAdvanced. Pese a que la egración de esta herramienta ofrece métodos sencillos de implementación para el uso del mismo es necesario tener un mínimo de conocimiento en desarrollo web, estándares de comunicación HTTP y lenguajes estándares de comunicación web. Cuando se vaya a realizar la egración, debe tener en cuenta los detalles legales de cada método de pago usado. Audiencia Este documento está dirigido a desarrolladores y comerciantes clientes de MobiAdvanced que requieren egrar sus servicios de pago en comercios.

5 Definiciones e información básica necesaria A continuación se describen una serie de conceptos y definiciones las cuales son necesarias conocer antes de realizar cualquier tipo de egración con MobiAdvanced. SMS Premium Se definen como SMS Premium, los SMS que tienen un coste adicional a cambio de recibir un servicio extra. El proceso básico de un pago mediante SMS Premium se podría resumir de la siguiente forma: El usuario envía un SMS a un número corto, este SMS es entregado a la operadora de telefonía, posteriormente la operadora entrega el SMS al proveedor del servicio y este responde al usuario un SMS indicando el servicio contratado. Al usuario se le aplica una tarifa especial en su factura telefónica, pasado un periodo de tiempo definido, al prestador del servicio se le pagará un porcentaje del total de ese SMS cobrado al usuario en su factura telefónica. SMS MO Un SMS MO es aquel que se origina en el terminal del usuario ( Mobile Originated ), por ejemplo cuando el usuario escribe un SMS para solicitar un servicio. SMS MT Un SMS MT es aquel que se entrega en el terminal del usuario ( Mobile Terminated ), por ejemplo cuando el usuario recibe un SMS de respuesta de un servicio.sms Premium con doble opt-in Alias Es el texto que deben incluir los usuarios al principio del SMS para poder determinar a que campaña pertenece esa venta.

6 Concepto herramienta Micropagos La herramienta de micropagos proporciona una manera sencilla de realizar cobros de bajo importe, por productos y/o servicios. Algunos ejemplos comunes de uso son: Pagos por vienes virtuales, descargas de archivos on-line, control de acceso a webs, venta de artículos numerados Esta herramienta es muy versátil y dispone de varios modos de configuración/uso, vea la sección opciones de configuración en este manual. También dispone de diversos métodos de egración / comunicación con terceros mediante peticiones HTTP o uso de API. Este servicio además proporciona una serie de herramientas para facilitar su egración y puesta en marcha, como son los formularios de pago predefinidos. Todas las opciones de configuración podrán ser definidas en el panel de control de este servicio.

7 Gestión de alias y precios La herramienta Micropagos de MobiAdvanced dispone de dos opciones a la hora de asignar precios y alias. los precios y alias serán asignados mediante el panel de configuración de la campaña. Modo alias global Se usará un alias general para toda la plataforma de mobiadvanced, el usuario solo deberá enviar un texto con la palabra clave y recibirá la información para continuar con su compra. Esta opción es la más cómoda ya que por defecto podrá disponer y activar los precios y países que desee sin tener que definir alias propios para cada uno de ellos. Modo con alias de usuario Podrá usar sub-alias o alias exclusivos, de esta forma tendrá que definir los alias que querrá usar en cada país y tarifa que desee. Recomendable solo usar con alias exclusivos. Esta opción es indicada para servicios que prevean un volumen alto de venta y requieren de una mayor personalización. Extra: valores virtuales por alias Tanto en alias global como en alias de usuario, podrá definir para cada método de pago (tarifa / país) un valor virtual y nombre de producto, de tal forma que este será enviado si usa notificaciones HTTP y/o Se mostrarán las ofertas en el formulario predefinido si se usa. Según la opción de uso elegida para esta herramienta, estos valores pueden tener dista funcionalidad. Revise el apartado Valores virtuales de cada opción. Las variables usadas para informar vía HTTP son psms_cmp_alias_product_value y psms_cmp_alias_product_name revisar la lista de variables en Notificación HTTP generales.

8 Opciones de configuración generales La herramienta de micropagos puede proveer diferentes tipos de configuración según la necesidad de su negocio y el tipo de producto que desea vender. Todos los servicios mostrados a continuación pueden usarse en conjunto con el formulario de pago predefinido. Notificación HTTP generales En todas las opciones de configuración, se puede configurar recibir cierta información mediante peticiones HTTP en cada venta ya sea mediante POST o GET. Nombre de variables generales A continuación se detalla el conjunto de variables enviadas por los métodos HTTP POST y HTT GET, el nombre de estas es idéntico para los 2 métodos. La codificación de caracteres usada es UTF-8 para todos los campos. Nombre Tipo Valor id_psms_sale id_psms_cmp psms_cmp_title operator_mcc operator_mnc operator_code operator_title psms_method_sc_number psms_method_sc_price psms_method_sc_currency psms_method_sc_price_vat psms_method_lang psms_method_country psms_sale_mo_number psms_sale_mo_time psms_sale_mo_data psms_sale_alias psms_sale_alias_sub psms_sale_track psms_sale_simulated psms_cmp_alias_product_value psms_cmp_alias_product_name psms_form_extra_args psms_form_ip Varchar(32) (9) varchar(128) (3) (3) varchar(16) varchar(64) (10) float(6,3) ISO float(4,2) ISO ISO varchar(16) timestamp varchar(160) varchar(32) varchar(32) varchar(32) Enum(Y, N) (11) varchar(64) text 1Kb varchar(15) ID de la transacción ID erno de la campaña en MobiAdvanced Título que definió en su campaña. Código MCC del operador Código MNC del operador se usa como identificador único para conocer el operador. ( ver lista de operadores ) Código de texto indica el nombre del operador ( puede no ser único ) para determinar el operador usar MCC+MCN Nombre descriptivo del operador. Número corto del método de pago donde se envía el MO Importe del método de pago en la moneda local del país. Moneda del método de pago. Porcentaje de impuesto que se aplica en el país de la venta. Lenguaje por defecto para el método - Alpha 2 Letras. País del método de pago Alpha 2 letras Número del cliente que envía el SMS-MO. inicio de la transacción, Formato: YYYY-mm-dd hh:ii:ss Contenido completo del mensaje que se envió, incluye ALIAS Palabra clave principal, por la que se determina la campaña Sub palabra clave (opcional) Parámetro adicional para seguimiento de la venta (opcional) SI el mensaje es una simulación. Valor virtual que definió al producto de al alias (opcional) Nombre virtual que definió a el producto del alias (opcional) Variable extra para uso del comercio. (solo si usa formulario) IP del usuario que realiza el pago (solo si usa formulario)

9 Respuestas a peticiones HTTP Todas las peticiones deben ser respondidas con código HTTP 200. Puede elegir entre 3 métodos de respuesta. TEXTO PLANO JSON XML Es recomendable que mire nuestros códigos de ejemplo donde ya se incluyen los métodos necesarios para gestionar estas respuestas. Respondiendo TEXTO PLANO Es necesario que a la hora de realizar la respuesta HTTP se defina con header content-type: text/ plain Los mensajes separan por punto y coma ; y un salto de línea \n, el último mensaje no es necesario añadir punto y coma y salto de línea. Ver ejemplos. Respondiendo JSON Es necesario que a la hora de realizar la respuesta HTTP se defina con header content-type: application/json Siguiendo el estándar de JSON, los caracteres no ASCII serán codificados de forma escapada UCS2. SI usted usa funciones nativas de su lenguaje de programación, no deberá preocuparse por eso. Respondiendo XML Es necesario que a la hora de realizar la respuesta HTTP se defina con header content-type: text/ xml Siguiendo el estándar de XML, Los tags que definen el contenido de mensajes de respuestas deberán estar definidos con <![CDATA[ contenido ]]>

10 Control de estado Este control sirve para verificar si las URL son correctas en caso de haber configurado una notificación vía HTTP, también nos indica la diferencia de horario entre servidores. Donde deberá incluir el valor unix_timestamp con la hora configurada en su servidor, esto nos ayudará a conocer las diferencias horarias a la hora de realizar una petición de control de estado. Ejemplos de respuesta de Estado Ejemplo: Texto plano STATUS. statements; STATUS; Ejemplo: JSON STATUS. "psms_sale_action":"status", "status_time":" " Ejemplo: XML STATUS. <?xml version="1.0" encoding="utf-8"?> <statements> <psms_sale_action>status</psms_sale_action> <status_time> </status_time> </statements>

11 Control de errores en notificaciones HTTP La plataforma de MobiAdvanced dispone de un avanzado control de errores y un log de consulta. Algunas de las causas de errores: 1. La URL indicada en la configuración, no responde o responde un código HTTP incorrecto. 2. La configuración de respuesta o el contenido es incorrecto. 3. La petición tardo más de 10 segundos en responder. Este tipo de errores son guardados en el log que podrá ver en la configuración de su herramienta. En el momento que se producen este tipo de errores, se inicia el siguiente proceso: 1. Se re-enta la notificación pasado 1 minuto. 2. Si el problema continua se re-enta cada minuto. 3. pasados 30 entos se re-entará cada 5 minutos. 4. Se notifica vía de la incidencia al contacto técnico definido en MobiAdvanced. Forzar error en notificación También es posible forzar errores en caso de no poder procesar la petición para que esta se reenvíe más tarde. Para forzar un error debe responder con código HTTP 503. en el momento que no se pueda entregar se inicia el proceso de errores indicado en el punto anterior. Además puedes opcionalmente puedes definir una respuesta con un mensaje que será guardado en el log de incidencias. Caso práctico: Si su servicio depende de un motor de base de datos y este no responde, puede forzar un error para que la notificación sea enviada más tarde. Ejemplo: Respuesta de ERROR con mensaje TEXTO PLANO statements; ERROR; This message will be saved in the log

12 Ejemplo: Respuesta de ERROR. "psms_sale_action":"error", "psms_sale_error_msn":"este mensaje se guardará en el log" Ejemplo: Respuesta de ERROR con mensaje XML <?xml version="1.0" encoding="utf-8"?> <statements> <psms_sale_action>error</psms_sale_action> <psms_sale_error_msn> Este mensaje se guardará </psms_sale_error_msn> </statements>

13 Uso general para consultas por API En caso de no recibir consultas HTTP, podrá consultar las claves/ventas mediante el uso del API de esta herramienta. Para más información sobre el API, ver manual dedicado al API de MobiAdvanced. El API de entrada de datos de MobiAdvanced se basa en peticiones HTTP simples. POST y GET Todos los datos enviados deben usar la codificación UTF-8, Dispone de varios métodos de respuesta: JSON json, XML xml, PHP serializado php-serialized Patrón URL solicitud de peticiones API. method=class.method& lang=lg& version=ver Ejemplo URL petición con respuesta JSON method=psms_set.mt& lang=es& version=1.1 Esquema de objeto de respuesta. Este ejemplo de esquema es mostrado en JSON pero el esquema y nombres de variables es similar para otros métodos de respuesta como XML, PHP "status":"ok", "message": "public":"clave comprobada correctamente.", "private":"ok" Esquema de respuesta con datos. "status":"ok", "message": "public":"consulta correcta", "private":"ok" returndata : [ id : 12, title : ejemplo, id : 13, title : ejemplo ]

14 Ejemplo 1: Esquema de consulta con mensaje de error. "status":"error", "message": "public":"la clave comprobada no existe.", "private":"error" Ejemplo 2: Esquema de consulta con mensaje de error. "status":"error", "message": "public":"el api key usado es incorrecto.", "private":"error" Es posible que en los objetos de respuesta existan más variables con información que no son de erés en este manual. Para más información vea la documentación especifica para APIs

15 Opción 1: Pagos virtuales (opción común) Descripción Esta opción es la más simple y puede adaptarse a cualquier modelo de pago. El usuario realiza una compra, este recibe un código para validar la venta y una vez comprobado ese código se procede a proveer el servicio. El código / venta podrá ser comprobado mediante el API o informado automáticamente al comercio, según la configuración. Usos y características Venta de bienes virtuales ( Juegos, Sistemas de créditos ) Esta opción puede ser adaptada a cualquier tipo de servicio, no obstante es posible que alguna de las otras opciones se adapten mejor a su necesidad y faciliten el trabajo de egración. Esta opción es compatible con el formulario de pago predefinido. Notificación HTTP Si elige la configuración con notificaciones HTTP, cada vez que se complete una venta, la URL indicada recibirá una petición HTTP. la URL deberá mostrar ciertos contenido a la hora de recibir la petición, para comprobar que la notificación de venta fue correcta. Además es posible definir un mensaje de finalización de compra en el caso de usarse la herramienta de formulario predefinido. Este mensaje no puede superar los 100 caracteres. Nombres de variables Esta opción no tiene más variables adicionales, solo se enviarán las variables definidas en la sección Variables HTTP generales. Respuesta Texto plano Ejemplo: Respuesta recibida correcta. OK Ejemplo: Respuesta recibida correcta con mensaje para Formulario predefinido OK; Tus créditos se han añadido a tu cuenta Jugador332

16 Respuesta JSON Ejemplo: Respuesta de OK. "psms_sale_action": OK, "psms_sale_form_msn":"tus créditos se han añadido a tu cuenta Jugador332" Ejemplo: Respuesta de OK con callback JS (solo si se usa herramienta formulario pago). En caso de usar la herramienta de ventana de pago, es posible enviar un código JavaScript que será ejecutado el completarse el proceso. Para más información sobre los callbacks JavaScript para la ventana de pago, vaya a la sección Herramienta formulario predefinido de este manual. "psms_sale_action": OK, "psms_sale_form_msn":"tus créditos se han añadido a tu cuenta Jugador332", psms_sale_form_callback_out : alert( callback ) Respuesta XML Ejemplo: Respuesta de OK. <?xml version="1.0" encoding="utf-8"?> <statements> < psms_sale_action >OK</psms_sale_action > <psms_sale_form_msn> Tus créditos se han añadido </psms_sale_form_msn> </statements>

17 Consultas API Método: ptool_mp_sr.keypass_check Método usado para comprobar las claves y confirmar la venta, este método si se usa con alias global, asocia la venta a la campaña indicada. Las claves usadas son eliminadas pasados 7 días. Argumentos. (Ver uso general para consultas por API.) Nombre Tipo Valor user_api_key char(40) API key del usuario, obligatorio. id_psms_cmp ID de la campaña. ptool_mp_sr_keypass vchar(24) clave de control de venta a comprobar. ptool_mp_sr_user_ip vchar(15) IP del usuario que comprueba la clave. ptool_mp_sr_product vchar(255) (opcional) establece el producto comprado Variables de respuesta en caso de existir la clave. (Ver esquema de respuesta con datos.) Nombre Tipo Valor user_api_key id_psms_cmp id_psms_sale id_ptool_mp_sr ptool_mp_sr_time ptool_mp_sr_status ptool_mp_sr_check_count ptool_mp_sr_check_time ptool_mp_sr_valid_time ptool_mp_sr_uses_limit ptool_mp_sr_uses_left ptool_mp_sr_user_ip ptool_mp_sr_product ptool_mp_sr_extra_args char(40) API key del usuario, obligatorio. ID de la campaña. ID de la venta SMS ID de la clave timestamp Fecha en la que se estableció la clave set OK, CLOSED, OPEN Número de veces que se comprobó la clave timestamp Fecha de la última comprobación tiempo en segundos de validez de la clave Número de veces que se puede usar la clave Número de veces que quedan por usarse vchar(15) IP del usuario que ha usado la clave. vchar(255) (opcional) producto comprado si se estableció anteriormente text Argumentos extra definidos por el usuario Si la clave comprobada no existe, se responderá con el esquema de error por defecto del API.

18 Extra: valores virtuales por alias Esta opción facilitará el proceso a la hora de ajustar precios a su producto. Ejemplo 1: Puede definir un valor virtual de 100 con nombre de producto 100 monedas de oro para la tarifa 1,20 de España, y un valor virtual de 900 con un nombre de producto 800 monedas de oro de regalo para la tarifa de 4,00, estas 2 opciones se mostrarán en el caso de usar el formulario predefinido y el valor virtual será enviado por HTTP o consultado vía API. así no tendrá que llevar un control erno que valor tiene cada tarifa en su producto.

19 Opción 2: Control de usuarios web Descripción Esta opción facilita la egración de micropagos para sistemas de usuarios y login. Genera un usuario y contraseña que son enviados mediante HTTP o consultados por API cuando un usuario hace login, También puede definirse un tiempo de actividad y cuando este tiempo es completado puede notificarse vía HTTP o consultar por API. Este tiempo de actividad, puede contabilizarse de forma automática o restando/añadiendo tiempo vía API en caso de solo consumir tiempo en ciertas actividades. Usos y características Venta de accesos a zona privada en Web. Venta de acceso por tiempo a Web Esta opción es compatible con el formulario de pago predefinido. Notificación HTTP Si elige la configuración con notificaciones HTTP, cada vez que se complete una venta, la URL indicada recibirá una petición HTTP. la URL deberá mostrar ciertos contenido a la hora de recibir la petición, para comprobar que la notificación de venta fue correcta. Además es posible definir un mensaje de finalización de compra en el caso de usarse la herramienta de formulario predefinido. Este mensaje no puede superar los 100 caracteres. Existen 3 tipos de notificaciones en esta opción, Variables enviadas en nuevas ventas. Se enviará este tipo de variables si es una nueva venta. Además se enviarán las variables definidas en Notificación HTTP generales Cuando reciba esta notificación podrá añadir o activar el usuario en su sistema. Nombre Tipo Valor ptool_mp_lr_type ptool_mp_lr_login_mode ptool_mp_lr_login_user ptool_mp_lr_login_pass ptool_mp_lr_login_time_left ptool_mp_lr_login_time_mode set set varchar(64) varchar(64) set NEW AUTO, USER, RESPONSE Nombre de usuario, auto-generado o elegido por el usuario. Si el usuario y contraseña se definen en la respuesta a la petición HTTP esta campo será nulo. Contraseña, auto-generada o elegido por el usuario. Si el usuario y contraseña se definen en la respuesta a la petición HTTP esta campo será vacío. Tiempo en segundos que le quedan de uso AUTO CRONO, si el tiempo es contabilizado de forma automática desde la compra, o se usará cronometro por API

20 Respuestas HTTP Donde será un ID único por usuario. No variable en el tiempo. Ejemplo: TEXTO PLANTO para ptool_mp_lr_login_mode AUTO y USER. donde el usuario y contraseña son generados automáticamente o elegidas por el sistema. OK; 34429; Tu cuenta ha sido creada con éxito! puedes acceder en Ejemplo: TEXTO PLANTO para ptool_mp_lr_login_mode RESPONSE. Donde el usuario y contraseña son respondidas por el comercio y mostradas al finalizar la compra. OK; 34429; Tu cuenta ha sido creada con éxito! puedes acceder en user2973; password Ejemplo: JSON para ptool_mp_lr_login_mode AUTO y USER. "psms_sale_action": OK, "ptool_mp_lr_login_id":"34429", "ptool_mp_lr_form_msn":"tu cuenta ha sido creada con éxito!" Ejemplo: JSON para ptool_mp_lr_login_mode RESPONSE. Donde será un ID único por usuario. No variable en el tiempo. "psms_sale_action": OK, "ptool_mp_lr_login_id":"34429", ptool_mp_lr_login_user : user2973, ptool_mp_lr_login_pass : password937983, "ptool_mp_lr_form_msn":"tu cuenta ha sido creada con éxito!"

21 Ejemplo: XML para ptool_mp_lr_login_mode AUTO y USER. <?xml version="1.0" encoding="utf-8"?> <statements> < psms_sale_action >OK</psms_sale_action > <ptool_mp_lr_form_msn> Tu cuenta ha sido creada </ptool_mp_lr_form_msn> </statements> Ejemplo: XML para ptool_mp_lr_login_mode RESPONSE. <?xml version="1.0" encoding="utf-8"?> <statements> < psms_sale_action >OK</psms_sale_action > <ptool_mp_lr_login_id>34429</ptool_mp_lr_login_id> <ptool_mp_lr_login_user >user2973 </ptool_mp_lr_login_user> <ptool_mp_lr_login_pass>password </ptool_mp_lr_login_pass> <ptool_mp_lr_form_msn>tu cuenta ha sido creada </ptool_mp_lr_form_msn> </statements> Variables enviadas en Actualizaciones. Se enviará este tipo de variables si el usuario que realiza una compra ya existe y está activo con tiempo restante, se sumará el valor de tiempo virtual al tiempo restante disponible. Además se enviarán las variables definidas en Notificación HTTP generales Cuando reciba esta notificación podrá añadir el tiempo restante o activar el usuario en su sistema. Nombre Tipo Valor ptool_mp_lr_type ptool_mp_lr_login_id ptool_mp_lr_login_user ptool_mp_lr_login_pass ptool_mp_lr_login_time_left ptool_mp_lr_login_time_mode set varchar(32) varchar(64) varchar(64) set UPDATE ID respondido la notificación de alta. Nombre usuario actual Contraseña usuario actual Tiempo total restante actualizado. En segundos. AUTO CRONO, si el tiempo es contabilizado de forma automática desde la compra, o se usará cronometro por API Ejemplo: TEXTO PLANTO OK; Se han sumado 30 minutos a tu cuenta user2973

22 Ejemplo: JSON "psms_sale_action": OK, "ptool_mp_lr_form_msn":"se han sumado 30 minutos a tu cuenta user2973" Ejemplo: XML <?xml version="1.0" encoding="utf-8"?> <statements> < psms_sale_action >OK</psms_sale_action > <ptool_mp_lr_form_msn>se han sumado 30 minutos </ptool_mp_lr_form_msn> </statements> Variables enviadas en Bajas. Se enviará este tipo de variables cuando el tiempo restante ha llegado a 0. Además se enviarán las variables definidas en Notificación HTTP generales Esta notificación puede tener un retraso de hasta 1 minuto, en caso de necesitar mayor control, deberá controlar el tiempo restante en la Sesión de su sistema. Cuando reciba esta notificación podrá eliminar el usuario del sistema. Nombre Tipo Valor ptool_mp_lr_type set END ptool_mp_lr_login_id varchar(32) ID respondido la notificación de alta. ptool_mp_lr_login_user varchar(64) Nombre usuario actual Ejemplo: TEXTO PLANTO OK Ejemplo: JSON "psms_sale_action": OK

23 Ejemplo: XML <?xml version="1.0" encoding="utf-8"?> <statements> < psms_sale_action >OK</psms_sale_action > </statements>

24 Consultas API Método: ptool_mp_lr.keypass_check Método usado para comprobar las clave enviada al móvil y confirmar la venta, este método si se usa con alias global, asocia la venta a la campaña indicada. Cuando se usa este método para comprobar la clave de venta se genera el usuario. Argumentos. (Ver uso general para consultas por API.) Nombre Tipo Valor user_api_key char(40) API key del usuario, obligatorio. id_psms_cmp ID de la campaña. ptool_mp_lr_login_mode set AUTO, USER ptool_mp_lr_login_user varchar(64) Nombre de usuario que se establece, No si se usa auto. ptool_mp_lr_login_pass varchar(64) Contraseña de usuario que se establece, No si se usa auto. ptool_mp_lr_keypass vchar(24) clave de control de venta a comprobar. ptool_mp_lr_user_ip vchar(15) IP del usuario que comprueba la clave. ptool_mp_lr_product vchar(255) (opcional) establece el producto comprado Variables de respuesta en caso de existir la clave. (Ver esquema de respuesta con datos.) Nombre Tipo Valor user_api_key id_psms_cmp id_psms_sale id_ptool_mp_sl ptool_mp_lr_login_time_left ptool_mp_lr_login_time_mode char(40) set API key del usuario, obligatorio. ID de la campaña. ID de la venta SMS ID de la clave / usuario Tiempo total restante en segundos AUTO CRONO, si el tiempo es contabilizado de forma automática desde la compra, o se usará cronometro por API Si la clave comprobada no existe, se responderá con el esquema de error por defecto del API.

25 Método: ptool_mp_lr.login_check Método usado para comprobar si el login existe, este método si se usa con alias global, asocia la venta a la campaña indicada. Los usuarios inactivos son eliminados pasados 7 días. Argumentos. (Ver uso general para consultas por API.) Nombre Tipo Valor user_api_key char(40) API key del usuario, obligatorio. id_psms_cmp ID de la campaña. ptool_mp_lr_login_user varchar(64) Nombre de usuario que se establece, No si se usa auto. ptool_mp_lr_login_pass varchar(64) Contraseña de usuario que se establece, No si se usa auto. Variables de respuesta en caso de existir la clave. (Ver esquema de respuesta con datos.) Nombre Tipo Valor id_ptool_mp_sl ptool_mp_lr_time ptool_mp_lr_login_time_left ptool_mp_lr_login_time_mode timestamp set ID de la clave / usuario Fecha en la que se estableció la clave Tiempo total restante en segundos AUTO CRONO, si el tiempo es contabilizado de forma automática desde la compra, o se usará cronometro por API Si el login comprobado no existe, se responderá con el esquema de error por defecto del API.

26 Método: ptool_mp_lr.login_mod_time Método usado para añadir o restar tiempo a un usuario determinado. Útil en el caso de querer contabilizar el tiempo usado de forma manual. Si el usuario se llega a 0 en tiempo restante se establecerá como inactivo y será borrado a los 7 días, si no se le vuelve a añadir tiempo. Este método solo se podrá usar en usuarios en modo contador de tiempo CRONO Los usuarios inactivos son eliminados pasados 7 días. Argumentos. (Ver Uso general para consultas por API.) Nombre Tipo Valor user_api_key char(40) API key del usuario, obligatorio. id_psms_cmp ID de la campaña. ptool_mp_lr_time_op SET ADD SUBS ( add para sumar, subs para restar ) ptool_mp_lr_time_set total segundos para añadir o restar. ptool_mp_lr_login_user varchar(64) Nombre de usuario que se establece, No si se usa auto. ptool_mp_lr_login_pass varchar(64) Contraseña de usuario que se establece, No si se usa auto. Variables de respuesta en caso de existir la clave. (Ver esquema de respuesta con datos.) Nombre Tipo Valor id_ptool_mp_sl ptool_mp_lr_login_time_left ptool_mp_lr_login_time_mode set ID de la clave / usuario Tiempo total restante en segundos AUTO CRONO, si el tiempo es contabilizado de forma automática desde la compra, o se usará cronometro por API Si el login comprobado no existe, se responderá con el esquema de error por defecto del API.

27 Extra: valores virtuales por alias En esta opción dicho valor virtual será usado para definir el número de segundos que dispone un usuario para usar un sitio web. Ejemplo 1: Los valores virtuales se usarán como tiempo en segundos, puede definir un valor virtual de 1800 con nombre de producto 30 minutos de acceso para la tarifa 1,20 de España, y un valor virtual de con un nombre de producto 1 día completo de acceso para la tarifa de 4,00, estas 2 opciones se mostrarán en el caso de usar el formulario predefinido y el valor virtual será enviado por HTTP o consultado vía API. así no tendrá que llevar un control erno que valor tiene cada tarifa en su producto. Si está usando notificaciones HTTP, cuando se complete el número de minutos desde la compra, se enviará una notificación de baja.

28 Opción 3: Descarga de archivos Descripción Esta opción facilita la egración de micropagos para comercios que quieren cobrar por descargas de contenidos virtuales como Música, Vídeos, Documentos o cualquier tipo de archivo. Estos archivos alojados en el servidor del comercio, serán protegidos para acceso al público y un script / código, se encargará de dar acceso comprobando la autenticidad del comprador. Con esta opción es recomendable usar el formulario de pago predefinido. Descripción del Proceso ( formulario ) El usuario abre el formulario de pago, donde se han pasado las variables con el nombre de archivo a descargar. El usuario realiza un pago por una descarga, cuando este pago se ha confirmado se da acceso a la URL de descarga generada por MobiAdvanced. Esta URL llevara una serie de parámetros como nombre de archivo, IP del comprador, hora de compra, y una clave hash para verificar la autenticidad de los datos y el comprado. ( Ver formulara para calcular hash ) Usos y características Descarga de archivos, documentos Esta opción es compatible con el formulario de pago predefinido. URL de descarga HTTP. En la configuración se debe establecer una URL de un script que gestionará las descargas. La URL recibirá una serie de variables mediante el método POST. Dispone de un SDK con ejemplos y códigos para proteger y gestionar las descargas de archivos. Variables enviadas a la URL de descarga. Esta opción no es una notificación automática y NO se enviarán las variables definidas en Notificación HTTP generales Nombre Tipo Valor id_psms_sale id_psms_cmp ptool_mp_fr_hash ptool_mp_fr_file_name ptool_mp_fr_file_time Varchar(32) (9) char(32) varchar(64) timestamp Unix ID de la transacción ID erno de la campaña en MobiAdvanced HASH para verificar autenticidad Contraseña usuario actual UTC - momento en la que se confirma el pago. Puede ser usado para que un usuario permita descargar cierto archivo durante un tiempo determinado.

29 Formula para verificar autenticidad. Ejemplo: PHP <?php $ptool_mp_fr_file_time = ; $ptool_mp_fr_file_name = 'archivo.zip'; $ip_usuario = $_SERVER['REMOTE_ADDR']; # IP del usuario $hash = md5($api_key.$ptool_mp_fr_file_time.$ptool_mp_fr_file_name. $ip_usuario);?> Extra: valores virtuales por alias. El valor virtual en esta opción, es encargada de establecer cuantos archivos diferentes se pueden descargar por cada compra. Ejemplo 1: Si se establece 1 como valor virtual en el alias. el usuario solo podrá descargar un archivo. No confundir 1 archivo, con 1 ento de descarga. El usuario tendrá un tiempo establecido para descargar un archivo, pero solo ese mismo archivo. Ejemplo 2: Si se establece 3 como valor virtual en el alias, el usuario podrá descargar 3 archivos con nombre diferente usando la misma clave / venta. Además si usa el formulario predefinido, este detectará si aún le quedan archivos por descargar y ofrecerá la descarga directamente.

30 Opción 4: Productos numerados Descripción Esta opción permite definir previamente una serie de productos con una numeración única, este registro de productos es guardado por MobiAdvanced y repartido en cada compra, una vez enviado los datos del producto, esta se marca como usado y ya no se volverá a enviar. El estado de las ventas podrá ser revisado mediante el panel de control Usos y características Venta de productos únicos numerados ( seriales, pines, entradas ) Esta opción permite configurar que se envíe el número de serie al móvil directamente Esta opción es compatible con el formulario de pago predefinido. Notificación HTTP Este modo no envía ninguna notificación HTTP debido a que los productos necesarios son definidos previamente a la compra

31 Consultas API Método: ptool_mp_sk.add_serial Método para añadir nuevas claves / series. Los productos usados son eliminados pasados 120 días. Argumentos. (Ver uso general para consultas por API.) Nombre Tipo Valor user_api_key id_psms_cmp id_psms_method ptool_mp_sk_data ptool_mp_sk_valid_until char(40) vchar(64) timestamp API key del usuario, obligatorio. ID de la campaña. (opcional) si la serie es solo válida para un número / tarifa Número serie o clave (opcional) Si el número de serie tiene fecha limite para ser enviado, una vez haya superado esta fecha, no se enviará o usará. Y se eliminará automáticamente Cuando se ejecute el método responderá si se ejecutó correctamente. (Ver Esquema de objeto de respuesta) Método: ptool_mp_sk.add_serial_batch Método para añadir nuevas claves / series en grupos de hasta 2000 separados por ; Los productos usados son eliminados pasados 120 días. Argumentos. (Ver uso general para consultas por API.) Nombre Tipo Valor user_api_key id_psms_cmp id_psms_method ptool_mp_sk_data ptool_mp_sk_batch_sep ptool_mp_sk_valid_until char(40) text API key del usuario, obligatorio. ID de la campaña. (opcional) si la serie es solo válida para un número / tarifa Número serie o clave vchar(3) Texto usado para separar las claves por defecto ; timestamp (opcional) Si el número de serie tiene fecha limite para ser enviado, una vez haya superado esta fecha, no se enviará o usará. Y se eliminará automáticamente Cuando se ejecute el método responderá si se ejecutó correctamente. (Ver Esquema de objeto de respuesta) Extra: valores virtuales por alias Esta opción no proporciona ninguna funcionalidad en este modo.

32 Herramienta formulario predefinido La herramienta de formulario predefinido proporciona un erface de pago ya creado, listo para usar e egrar en páginas web. Este formulario de pago ya incluye todas las características necesarias para gestionar múltiples países, idiomas, tarifas y productos. En caso de usar múltiples países definidos en las tarifas a usar, el país del cliente se detectará automáticamente y se mostrarán las opciones disponibles para ese país En caso de usar múltiples idiomas definidos en las tarifas a usar, el idioma del cliente se detectará automáticamente. Esta herramienta también muestra de forma automática los textos legales informativos que deben mostrarse según el método de pago. Para usar esta herramienta deberás acceder a la pestaña de ayuda e egración en la configuración de la campaña. Fig. 1. Ejemplo de formulario de pago.

33 Definir oferta en tiempo de ejecución Usted puede definir qué ofertas serán mostradas y seleccionadas de forma predeterminada en el momento en que se abre la ventana de herramienta de pago. Puede pasar un JSON string en el parámetro: mp_form_offer_defined Debería definir qué países y los ID de las ofertas que desea mostrar. Hay algunos ejemplos a continuación indican que el esquema a seguir. Puede veros ID de las ofertas en la sección de configuración de su campaña, pestaña Países y tarifas, y pulsando el botón de acción. También se puede definir qué oferta será seleccionada por defecto. Las ofertas se mostrarán en el mismo orden que se define en el JSON. Ejemplo: Sólo muestra España y tres ofertas "ES":[106,155,107] Sólo muestra España y la oferta ID: 155 "ES":[155] Mostrará España con tres ofertas y la oferta seleccionada por defecto ID:155 "offer":"155","es":[106,155,107] Mostrará España y Portugal con dos ofertas "ES":[155],"PT":[23,45] Mostrará España con tres ofertas seleccionadas y la oferta ID:155, también la fuerza para seleccionar España "country": "ES","offer":"155","ES":[106,155,107]

34 Configuración general Variables de configuración. A la hora de abrir el formulario se deben enviar estas variables vía GET o POST. Nombre Tipo Valor id_psms_cmp ID de la campaña. mp_form_offer_selected varchar MIN, MAX, o número de opción, 1, 2,3 (opcional) defecto: 1 Opcionales, si se definen debe enviarse HASH de verificación Nombre Tipo Valor mp_form_hash mp_form_offer_defined mp_form_extra_args mp_form_url_css char(32) opcional ( hash para verificar los datos y su procedencia ) text text text Para configurar ofertas de forma dinámica al abrir el formulario Campo para argumentos personalizados de usuario, esté campo será enviado a la hora de hacer notificaciones HTTP Campo para cargar URL CSS alternativa Hash de verificación. Permite modificar opciones del formulario a la hora de abrirse. Este hash se calcula usando una frase clave definida por el usuario en el panel de control. De esta forma podremos comprobar que realmente las opciones las está modificando el usuario que estableció de dicha frase. Formulara para calcular HASH Ejemplo: PHP <?php $mp_form_offer_defined = false; $mp_form_extra_args = 'extra1=blabla&extra2=blabla'; $mp_form_url_css = ' $hash = md5($api_key.$mp_form_offer_defined.$mp_form_extra_args. $mp_form_url_css);?> Seleccionar oferta por defecto. Puedes marcar que oferta será elegida por defecto al abrir el formulario con el argumento mp_form_offer_selected, usa MIN para la oferta de menor coste, MAX para la de mayor o el número según la posición

35 Definir ofertas alternativas. Puedes cambiar los valores de las ofertas actuales, por ejemplo para hacer ofertas personalizadas y definir el nombre de producto y su valor virtual a la hora de abrir el formulario, usando el argumento mp_form_offer_defined. Debe pasar el esquema como texto en el argumento mp_form_offer_defined. Puedes modificar varias ofertas separando las definiciones Donde id_psms_method se establecerá el ID del método de pago usado. (ver manual lista de métodos) Es obligatorio definir el HASH de verificación. Esquema para modificar las ofertas [id_psms_method:texto:valorvirtual@ id_psms_method:texto:valorvirtual] Ejemplo 1: modificando la primera oferta. [2:Oferta limitada 2000 diamantes:200] Ejemplo 2: modificando 2 ofertas. [1:Oferta limitada 2000 diamantes:200@2:super oferta solo para ti 5000 diamantes:5000] Ha de tener en cuenta las modificaciones que realiza, si está usando varios países en el formulario de pago.

36 Callbacks Javascript. Si está usando la herramienta de formulario de pago, es posible que en ciertas ocasiones requiera realizar ciertas acciones a la hora de completar un proceso de compra y esta sea notificada a su comercio. Este código de JavaScript debe ser definido en el contenido de respuesta que muestra su comercio al enviar los datos de la venta. Esta opción solo es compatible si usa el modelo de respuesta XML o JSON. Existen dos parámetros para enviar callbacks, que son diferenciados según el scope o alcance que se requiera psms_sale_form_callback_out: si el callback requiere eracturar con el site o elementos eternos, por ejemplo objetos Flash etc. Debido a la limitación de los navegadores y su protección en la comunicación entre iframes, este sistema usa un método para pasar información a través de la URL. con lo que la cantidad de código javascript debe limitarse a 400 caracteres máximo. Esta opción no es compatible con sites que usen técnicas de control de eventos mediante datos del anchor URL. psms_sale_form_callback_in: si el callback requiere eracturar con los elementos ernos del formulario predefinido o que no requieren eractuar con el site. Ejemplo: Respuesta JSON cerrar ventana de pago y ejecutar myfunction() en el site. "psms_sale_action": OK, "psms_sale_form_msn":"tus créditos se han añadido a tu cuenta Jugador332", psms_sale_form_callback_out : mobi_modal.modalout(); myfunction(); Ejemplo: Respuesta JSON redireccionar a la URL "psms_sale_action": OK, "psms_sale_form_msn":"tus créditos se han añadido a tu cuenta Jugador332", psms_sale_form_callback_in : window.top.location = '

37 Protección IP SI dispone de un firewall activado en el servidor donde recibe las peticiones, deberá permitir el acceso a las siguientes IPs Es posibles que por motivos de mejoras en la plataforma de MobiAdvanced las IPs puedan ser modificadas. en caso de ser cliente, será informado vía con algunas semanas de antelación. Mas Información Si tiene dudas acerca de este documento o quiere informar de un error en el mismo, por favor no dude en contactarnos. MobiAdvanced ( información general ) soporte@mobiadvanced.com Luis Muñoz - CTO ( información técnica ) luis.munoz.hdez@mobiadvanced.com Skype: luis.munoz.hdez MobiAdvanced.com

38 General information Introduction MobiAdvanced is a platform which allows you to offer methods of payment via mobile telephone through SMS premium,which can be egrated and automated with other applications, webs or other means. MobiAdvanced also offers tools of practical use related to payment via SMS premium and different services related to payment systems and mobile marketing. Notice of non-liability Mobiadvanced offers no warranties of any type be they express, implied or statutory of the information contained in this document. Mobiadvanced assumes no liability of damages direct or indirect resulting from the use of this document or of the examples of the codes contained within. MobiAdvanced reserves the right to carry out changes and corrections in the document with prior notice. MobiAdvanced does not guarantee the future validity of this document. Before using this document we recommend you ensure that it is the latest version of the same. Document This document describes the egration process of the tool Gateway offered by MobiAdvanced. Even though the the egration tool offers simple methods of implementation for its use one needs to posses a minimum knowledge of HTTP communication standards ad language standards of web communication. This document focuses on the technical detail of the egration not the function of each kind of payment service which can be egrated. Intended Audience This document is aimed at developers and MobiAdvanced s clients who want to egrate their payment services and test them before they put them o production.

39 Definitions and basic necessary information Below a series of concepts and definitions which you need to know before carrying out any type of egration with MobiAdvanced. SMS Premium Premium SMS are defined as SMS having an additional cost in exchange for receiving an additional service. The basic process of payment through a premium SMS can be summarized in the following steps: The user sends an SMS to a short number, this SMS is passed on to the telephone operator, afterward the operator passes on the SMS to the service provider which in turn sends an SMS to the user indicating the service contracted. A special rate is included in the users telephone bill, after a predetermined time the service supplier is paid a percentage of the total billed to the user. SMS MO An SMS Mo is that originating in the users terminal ( Mobile Originated ), Ex: when the user writes an SMS to request a service. SMS MT an SMS MT are those received in the users terminal ( Mobile Terminated ), Ex: when the user receives an SMS in response to a service. Alias Is the text that users should include at the beginning of the SMS to determine the campaign they belong to.

40 Micropayments Tool concept The micropayment tool supplies a simple manner of charging small payments for products or services. Some common examples of its use are: Payment of virtual goods, downloads online files, control of web access, sale of numbered articles This is a very versatile tool which has various configurations and uses, see configuration options in this manual. It also contains diverse methods of egration / communication with third parties via HTTP requests or using API. This service also supplies a series of tools to facilitate its egration and implementations such as predefined payment forms. All configuration options can be defined in the control panel of this service.

41 Management of Alias and rates MobiAdvanced s Micropayment tool has two options when assigning aliases and prices. Prices and aliases are assigned on the campaign configuration panel. Global Alias mode A general alias will be used for the whole MobiAdvanced platform, the user only need send a text with a key word and will receive instructions how to continue with the purchase. This is the easiest being that by defect you may obtain and activate prices and countries desired without having to define an alias for each of them. User Alias mode You may use sub-aliases or exclusive aliases, this way you will have to define the aliases you want for each country and tariff you desire. Recommended for use only for exclusive aliases. This option is recommended for services that foresee a high volume of sales or require a greater personalization. Extra: Virtual values for aliases With global aliases as well as user aliases one can assign for each payment method (tariff/country) a virtual value and product name which will be sent if HTTP are used and/or promotions will be reflected if a predefined form is used. Depending on the option chosen for this tool, this values may have different functions. Review the section Virtual values for each option mode. The variables used to inform via HTTP are psms_cmp_alias_product_value y psms_cmp_alias_product_name review list of variables in HTTP general notifications

42 General configuration options The micropayment tool can provide different configurations depending on your business needs an d the product you want to sell. All the services that follow below can be used in conjunction with the predefined payment form.. General HTTP notifications In all configuration options you can receive certain information via HTTP requests in each sale be it through POST or GET. name of general variables. Names of the variables used in HTTP POST and HTTP GET requests. The charset encoding used is UTF-8 for all the variables. Name Type Value id_psms_sale id_psms_cmp operator_mcc operator_mnc operator_code operator_title psms_method_sc_number psms_method_sc_price psms_method_sc_currency psms_method_sc_price_vat psms_method_lang psms_method_country psms_sale_mo_number psms_sale_mo_time psms_sale_mo_data psms_sale_alias psms_sale_alias_sub psms_sale_simulated psms_cmp_alias_product_value psms_cmp_alias_product_name psms_sale_track psms_sale_ip psms_sale_product Varchar(32) (9) (3) (3) varchar(16) varchar(64) (10) float(6,3) ISO float(4,2) Transaction ID ID for the campaign in MobiAdvanced. MCC code operator. MNC code operator. combined MCC/MCN are used to determine the operator ( see the operators list on each payment method details. ) Short name for the operator. Name of the operator. Number of the Short code. User price in local currency, without VAT. ISO 4217 code. ISO ISO Percent of VAT applied in the sale. ISO ISO alpha 2 varchar(16) timestamp varchar(160) varchar(32) varchar(32) Enum(Y, N) (11) varchar(64) varchar(32) varchar(15) varchar(128) Client mobile number, with country prefix, without + symbol Sale timestamp, format: YYYY-mm-dd hh:ii:ss Text in the content of the SMS. Principal ALIAS. Sub alias, only if exists. Y, if the transaction is generated with the simulator tool. Virtual value defined for the Alias (optional). Name of the product defined for the Alias (optional). Tracking parameter, only if exists. IP user (optional) (Only using form tool) Name of the product defined in the form (optional) (Only using form tool)