En esta documentación se definen los parámetros y elementos necesarios para utilizar el SDK de Mobbex en la plataforma Windows, permitiendo su integración con otras aplicaciones.

Repositorio

URL: https://github.com/mobbexco/desktop-sdk

Primeros Pasos

Antes de comenzar, debe asegurarse de tener instalada la plataforma .NET Framework versión 4.5.2 Todos los archivos descargados desde nuestro repositorio se deben copiar juntos en la ubicación que usted elija dentro de su aplicación. El archivo principal y con el cuál deberá interactuar vía consola es Mobbex.exe

Configuración de parámetros

Para poder utilizar este SDK, es necesario que el usuario inicie sesión desde el propio ejecutable, utilizando la ventana que se le mostrará la primera vez que lo utilice. En el caso de vencerse la sesión, el sistema automáticamente le pedirá que inicie sesión nuevamente.

En forma conjunta, es necesario establecer mediante la variable de entorno ENTITY la entidad con la cual el usuario quiere acceder y operar. Sin este parámetro no es posible acceder a los servicios.

En en caso de algunas operaciones, en lugar de iniciar sesión es posible utilizar las credenciales de API y Access Token generadas para el comercio, posibilitando utilizar el SDK en entornos de backend. Las mismas se definen en las variables de entorno XAPIKEY y XACCESSTOKEN respectivamente Estas operaciones estarán indicadas en cada uno de sus apartados.

Por otro lado, es necesario configurar las opciones de salida del SDK, utilizadas para almacenar y/o imprimir los cupones correspondientes a las transacciones, una vez que son completadas (independientemente de su resultado). Al menos una de las dos opciones de salida debe estar configuradas, caso contrario se generará una alerta al iniciar la aplicación. Estos parámetros se definen en el mismo archivo de configuraciones, dentro del nodo "output".

• folder: indica la carpeta donde se almacenarán los cupones en formato PDF al finalizar la transacción
• printer: este nodo contiene las propiedades de la impresora utilizada para imprimir los cupones al finalizar la transacción. La propiedad name hace referencia al nombre de la impresora tal como está definida en Windows. La propiedad type indica el tipo de impresora (valores admitidos: "normal" y "ticket").

"output":{
    "folder": "..",
  "printer": {
      "name": "HP Laserjet 1102W",
    "type": "normal"
  }
}

La definición de la carpeta y/o impresora de cupones también puede realizarse enviando estos parámetros como opciones al ejecutar Mobbex.exe, teniendo en cuenta la sintaxis de opciones por consola:

Mobbex.exe -f ".." -p "HP Laserjet 1102W:normal"

Donde el caracter : es el separador del nombre y tipo de la impresora. Si se opta por esta opción, estas opciones deberán ser enviadas en toda llamada al SDK.

Operaciones

Crear Checkout

Para esto se debe ejecutar la opción -cit del programa, pasando como parámetros de la opción todos los atributos de la operación en formato JSON. Los parámetros son los mismos que los definidos para un Checkout tradicional (para más información ver documentación de Checkout)

Para generar un checkout en modo test o modo de pruebas, simplemente se debe agregar al programa la opción -t Ejemplo:

Mobbex.exe -t -cit "{\"total\": 100, \"currency\": \"ARS\", \"description\": \"Venta de Prueba\", \"reference\": \"Referencia001\", \"customer\": {\"identification\": \"99999999\", \"email\": \"demo@mobbex.com\", \"name\": \"Demo User\"}}"

La respuesta del SDK será similar a la siguiente:

{
 "operation": "cit", 
 "type": "result", 
 "data": {
   "result":true,
   "data":{
     "id":"ZNLLBHDO0DK1E1FC3G",
     "url":"https://mobbex.com/p/checkout/v2/ZNLLBHDO0DK1E1FC3G",
     "description":"Venta de Prueba",
     "currency":"ARS",
     "total":100,
     "created":1606264299516
     }
   }
 }
}

Crear POS de Cobros

Con el SDK es posible utilizar el servicio de cobros presenciales de Mobbex y ser integrado a otras aplicaciones.

El primer paso para utilizar el servicio es crear el token de la operación, necesario para todas las demás etapas.

Esto se realiza con la opción -cp, pasando como parámetros en formato JSON los siguientes:

• description: Descripción de la Operación. Obligatorio.
• total: Total de la operación. Obligatorio.
• reference: Referencia de la operación a realizar. Este parámetro es opcional.
• input: Alternativa de ingreso de los datos de tarjeta. Este parámetro es obligatorio. Valores posibles: reader / manual

Ejemplo:

Mobbex.exe -cp "{\"description\": \"Descripción del POS\", \"total\": 10, \"input\": \"reader\"}"

Deberemos almacenar el valor de intent.token para utilizarlo en los pasos siguientes.



Crear Token de Tarjeta

En este paso crearemos el token perteneciente a la tarjeta con la cuál se realizará la operación. Se realiza con la opción -ct, pasando como parámetro el intent token generado en el paso anterior.

Mobbex.exe -ct "{\"it\": \"a143c8e2-46ae-4e61-8ddb-ec6f10f6d57b\"}"

Tal como se especificó al crear el token del POS, existen 2 formas de cargar los datos de la tarjeta:

• Ingreso manual: con la opción -m luego de los parámetros de la opción -ct. Esta opción abre una ventana para que el usuario pueda cargar los datos de la tarjeta y, además, seleccionar el plan de cuotas de la operación. Ejemplo:

Mobbex.exe -ct "{\"it\": \"a143c8e2-46ae-4e61-8ddb-ec6f10f6d57b\"}" -m

• Ingreso a través de lector de tarjetas Mox: con la opción -r luego de los parámetros de la opción -ct. Se debe indicar como parámetro de esta opción el tipo de lector a utilizar para realizar la operación, siendo los valores actualmente soportados:
  • BBPOS_CHBT: Permite utilizar el lector BBPOS modelo CHB10

Mobbex.exe -ct "{\"it\": \"a143c8e2-46ae-4e61-8ddb-ec6f10f6d57b\"}" -r "BBPOS_CHBT"

El resultado de ejecutar el comando tendrá una salida como la siguiente:

{
  "operation": "ct",
  "type": "result",
  "data": {
    "result":true,
    "data":{
      "token":"T:abgtu~Olh",
      "description":"Visa Débito terminada en 0010",
      "source":{
        "references":["visa.debit"],
        "reference":"visa.debit",
        "generic":"visa.debit",
        "compatReference":"visa.debit",
        "name":"Visa Débito",
        "shortName":"Visa Débito",
        "currency":"ARS",
        "card":{
          "level":"classic",
          "product":{
            "name":"Visa Débito",
            "shortName":"Visa Débit",
            "variant":"debit",
            "lengths":[16],
            "gaps":[4,8,12],
            "code":{
              "name":"CVV",
              "length":3,
              "position":1
            },           "logo":"https://res.mobbex.com/images/sources/png/visa.png",
            "validation":["length","exp","cvv","luhn"]
          },
          "issuer":{
            "shortName":"Visa",
            "name":"Visa",
            "color":"#122d98",
            "logo":"https://res.mobbex.com/images/sources/png/visa.png"
          }
        },
        "type":"card",
        "priority":0
      }
    }
  }, 
  "options":{
    "bin":"450799"
    }
  }
}

En este paso debemos almacenar los siguientes valores:

• data.data.token: Es el token que hace referencia a la tarjeta almacenada.
• options.bin: Será utilizado en el próximo paso para identificar el tipo de tarjeta.
• options.installment.reference: Hace referencia al plan de cuotas seleccionado. Aplica solo a carga manual de tarjeta.



Obtener cuotas de una tarjeta específica

En el caso de que la operación de tokenización haya sido realizada con un lector, o simplemente requiera obtener los medios de pago (planes de cuotas) asociados a una determinada marca de tarjeta, debe utilizar esta opción del SDK. Debe llamarse al archivo con la opción -gi pasando como parámetro de la opción los siguientes datos:

• it: Intent token de la operación. Este parámetro es Obligatorio.
• bin: Primeros 6 dígitos de la tarjeta sobre los cuales se quieren obtener los planes de cuotas. Es un valor retornado también de la operación anterior. Este parámetro es Obligatorio.
• installments: esta opción indica si calcular los valores de cuotas de las formas de pago. Valores true/false. Este parámetro es opcional y por defecto es true.

Ejemplo de utilización de esta opción:

Mobbex.exe -gi "{\"it\": \"a143c8e2-46ae-4e61-8ddb-ec6f10f6d57b\", \"bin\": \"450799\", \"installments\": true}"

El resultado de esta operación es la siguiente:

{
  "operation": "gi", 
  "type": "result", 
  "data": {
    "result":true,
    "data":{
      "type":"card",
      "source":{
        "references":["visa.debit"],
        "reference":"visa.debit",
        "generic":"visa.debit",
        "compatReference":"visa.debit",
        "name":"Visa Débito",
        "shortName":"Visa Débito",
        "currency":"ARS",
        "card":{
          "level":"classic",
          "product":{
            "name":"Visa Débito",
            "shortName":"Visa Débit",
            "variant":"debit",
            "lengths":[16],
            "gaps":[4,8,12],
            "code":{
              "name":"CVV",
              "length":3,
              "position":1
            },
           "logo":"https://res.mobbex.com/images/sources/png/visa.png",
           "validation":["length","exp","cvv","luhn"]
          },
          "issuer":{
            "shortName":"Visa",
            "name":"Visa",
            "color":"#122d98",
            "logo":"https://res.mobbex.com/images/sources/png/visa.png"
          }
        },
        "type":"card",
        "priority":0
      },
      "installments":[{
        "name":"Débito",
        "description":"10% de descuento",
        "sourceReference":"",
        "count":1,
        "reference":"1",
        "percentage":-10,
        "entity_percentage":0,
        "discount":0,
        "promo_code":"",
        "modes":["CNP","CP"],
        "status":"active",
        "order":1,
        "updated":"2020-10-27T13:39:59.829Z",
        "created":"2020-03-25T22:37:02.155Z",
        "_id":"5e7bdd0e2b6c8c490948ad8d",
        "uid":"4EZZXHEe4",
        "type":"direct",
        "updatedBy":"5d682afc8d0b0318fd9691d7",
        "totals":{
          "currency":{
            "value":"TEST",
            "label":"Test Money",
            "symbol":"T$",
            "hidden":false
          },
          "installment":{
            "amount":90,
            "count":1
          },
          "total":90,
          "financial":{
            "percentage":-10,
            "amount":-10
          }
        }
      }]
    }
  }
}

El parámetro a almacenar en este caso es reference del plan de cuotas elegido.



Listar medios de pago de una entidad

La opción -gp permite listar todos los medios de pago y cuotas configuradas y habilitadas en un comercio. Simplemente se debe indicar el importe con el cual se desea procesar la operación y mostrar los diferentes planes de cuotas.

El importe se indica dentro de las opciones en formato JSON del comando, en la propiedad total

Ejemplo:

Mobbex.exe -gp "{\"total\": 100}"



Crear token de cliente

Esta opción debe ser utilizada al cargar los datos de tarjeta a través del lector. De esta forma se especifican los datos del propietario de la tarjeta. En el caso de las tarjetas cargadas manualmente, este paso es opcional.

Se debe utilizar la opción -cc pasando como parámetros los siguientes:

• it: Indica el token del POS generado anteriormente. Obligatorio.
• customer: nodo con los datos del cliente
  • customer.email: Email del cliente al cual se le enviará el comprobante. Obligatorio.
  • customer.identification: Número de documento del cliente propietario de la tarjeta. Obligatorio.
  • customer.name: Nombre del cliente propietario de la tarjeta. Obligatorio.
  • customer.phone: Número de celular del cliente. Opcional.

Ejemplo:

Mobbex.exe -cc "{\"it\": \"a143c8e2-46ae-4e61-8ddb-ec6f10f6d57b\", \"customer\": {\"email\": \"demo@mobbex.com\", \"identification\": \"12123123\", \"name\": \"Cliente Demo\"}}"

Debemos almacenar el valor uid con el token del cliente, para luego confirmar la operación.



Confirmar Operación

Para confirmar la operación y ejecutar finalmente el cobro, únicamente debe llamar al SDK con la opción -co y los siguientes parámetros en formato JSON:

• it: Intent token de la operación.
• source: Nodo que contiene los datos referidos a la tarjeta a procesar.
  • source.token: Token de la tarjeta.
  • source.bin: Primeros 6 dígitos de la tarjeta (BIN) obtenido en la etapa de tokenización de la tarjeta.
• installment: referencia del plan de cuotas o forma de pago de la tarjeta.
• customer: Token del cliente con el que se procesa la operación. Obligatorio cuando el ingreso de la tarjeta es por lector, opcional cuando el ingreso es manual.

Ejemplo:

Mobbex.exe -co "{\"it\": \"a143c8e2-46ae-4e61-8ddb-ec6f10f6d57b\", \"source\":{\"token\":\"T:abgtu~Olh\", \"bin\": \"450799\"}, \"installment\": \"1\", \"customer\": \"cus:EOSHWL65hh\"}"

Al ejecutar el comando se abrirá una ventana donde deberá ingresar el código de seguridad (CVV) de la tarjeta, para poder confirmar finalmente la operación.

Luego de ingresar el CVV y confirmar, el resultado del comando es similar al siguiente:

{"operation": "co",
 "type": "result",
 "data": {
   "result":true,
   "data":{
     "view":"result",
     "options":{},
     "id":"Erne0MBjK",
     "status":{
       "code":"400",
       "text":"Rechazado",
       "message":"La tarjeta ingresada es inválida. Verifique la tarjeta ingresada. (Cod. 103)"
     },
     "total":90,
     "currency":{
       "value":"TEST",
       "label":"Test Money",
       "symbol":"T$",
       "hidden":false},
     "data":[
       {
         "type":"item",
        "key":"transactionId",
         "label":"ID de Transacción",
         "value":"Erne0MBjK",
         "priority":2,
         "visibility":"visible"
       },
       {
         "type":"item",
         "key":"cardNumber",
         "label":"Tarjeta",
         "value":"450799******0010",
         "priority":99,
         "visibility":"hidden"
       }
     ],
     "actions":[
       {
         "label":"Imprimir",
         "key":"print",
         "type":"default",
         "action":{
           "type":"print",
           "data":{
             "url":"https://ms.mobbex.com/prod/reports",
             "path":"/v2/coupon/",
             "id":"Erne0MBjK",
             "schema":"card"}
         }
       },
       {
         "label":"Reintentar",
         "key":"retry",
         "type":"primary",
         "action":{
           "type":"reload"}
       }]
   }
 }
}

Además de la salida por consola, el sistema almacenará el cupón de la operación en formato PDF en la carpeta indicada y/o realizará la impresión del mismo por la impresora configurada.



Recuperar Operación por Cupón

Si se desea recuperar los datos de una operación teniendo su identificador de cupón, se puede hacer utilizando la opción -go del SDK, pasando como parámetro el identificador de operación en formato JSON dentro de la propiedad uid Ejemplo:

Mobbex.exe -go "{\"uid\": \"Erne0MBjK\"}"

Si además de mostrar los datos por consola se desea obtener el comprobante de la operación (en formado PDF o por impresora según lo configurado) se puede agregar opcionalmente la propiedad save con valor true

Mobbex.exe -go "{\"uid\": \"Erne0MBjK\", \"save\": true}"

En este caso el comprobante se almacenará y/o imprimirá según los parámetros de configuración definidos.



Recuperar Operación por Referencia

Si desea recuperar los datos de una operación teniendo la referencia definida al crearla, se puede hacer utilizando la opción -gr del SDK, pasando como parámetro el identificador de operación en formato JSON dentro de la propiedad reference Ejemplo:

Mobbex.exe -gr "{\"reference\": \"pago-123456\"}"



Recuperar Listado de Operaciones

Permite recuperar un conjunto de operaciones en base en un parámetro particular de las mismas. Se realiza utilizando la opción -gos del SDK. Tiene 2 tipos de parámetros:

Obligatorios

• -page: el listado se muestra paginado, por lo que debe indicar la página a mostrar. Comienza en el índice 0.

Opcionales

• -limit: indica la cantidad de registros a mostrar por página. Máximo 50 operaciones. Por defecto se muestran 15 operaciones.

Los parámetros que permiten filtrar las operaciones a listar se deben colocar en formato JSON a continuación del comando. Si no se desean aplicar filtros, simplemente se debe enviar el objeto JSON vacío {}. Los parámetros válidos son equivalentes a los definidos en Listado de Operaciones

Ejemplo:

Mobbex.exe -gos "{\"reference\": \"pago-123456\"}" -page 0 -limit 20



Devolver Operación

Desde esta opción puede gestionar la devolución de una operación realizada a través del POS. La opción a utilizar es -ro y únicamente se deben indicar 2 parámetros:

• uid: Identificador único de la operación. Obligatorio.
• total: Indica el monto a devolver, en el caso de que quiera realizarse una devolución parcial. En el caso de devolución total, este parámetro no es obligatorio.

Ejemplo:

Mobbex.exe -ro "{\"uid\": \"Erne0MBjK\", \"total\": 10}"

En el caso de que la operación haya sido procesada utilizando lector, automáticamente el sistema solicitará deslizar la tarjeta para validar la devolución.



Capturar Operación

Esta opción sólo puede utilizarse en el caso de que se tenga autorizada la operatoria en 2 pasos. Se utiliza la opción -cap indicando 2 parámetros:

• uid: Identificador único de la operación. Obligatorio.
• total: Indica el monto a capturar, en función del porcentaje autorizado por la marca. Obligatorio.

Ejemplo

Mobbex.exe -cap "{\"uid\": \"Erne0MBjK\", \"total\": 10}"