Biaani Products Processor v1.1

Menú

Generales

  1. Flujo de una transacción
  2. Proceso general de solicitud de una operación.
  3. Utilización de claves y sesiones.
  4. Métodos para procesamiento de operaciones.

Giftcards

  1. Método sessionrequest.
  2. Método echorequest.
  3. Método activationrequest.
  4. Método deactivationrequest.

PINes Redimibles

  1. Notas generales en produtos PINes.
  2. Método echorequest.
  3. Método pinrequest.

Flujo de solicitud activacion de tarjeta y de requerimiento de pin de producto

La figura 2 nos muestra el flujo de un proceso de activación de tarjeta o de requerimiento de codigo digital (PIN), recordemos que una tarjeta se encuentra exhibida en el comercio, sin servicio asociado, y que, por otro lado un codigo debe ser impreso dentro del ticket (PIN On Receipt). Para que proveer la tarjeta del servicio es necesario pasarla por la caja, pagarla y activarla. Los códigos necesitan de la exhibición de carteles donde se avise al cliente la existencia del producto, para ser solicitado en caja. Un “reverso” viaja de la misma manera, sin embargo, la acción es iniciada de manera automática, y no por demanda como lo es la activación. En el caso de un código, nunca será manual, y únicamente debe ser invocado en caso de un “timeout” ó sobrepaso del tiempo máximo de procesamiento. Una vez impreso, un código, no debe ser cancelado con un reverso.

Proceso general de solicitud de una operación.

La figura 2 nos muestra el flujo de un proceso de activación de tarjeta o de requerimiento de codigo digital (PIN), recordemos que una tarjeta se encuentra exhibida en el comercio, sin servicio asociado, y que, por otro lado un codigo debe ser impreso dentro del ticket (PIN On Receipt). Para que proveer la tarjeta del servicio es necesario pasarla por la caja, pagarla y activarla. Los códigos necesitan de la exhibición de carteles donde se avise al cliente la existencia del producto, para ser solicitado en caja. Un “reverso” viaja de la misma manera, sin embargo, la acción es iniciada de manera automática, y no por demanda como lo es la activación. En el caso de un código, nunca será manual, y únicamente debe ser invocado en caso de un “timeout” ó sobrepaso del tiempo máximo de procesamiento. Una vez impreso, un código, no debe ser cancelado con un reverso.

procesamiento y uso de clave y tokes de autentificació para el uso en sesión.

El proceso para intercambio de clave es sumamente sencillo y completamente estándar. No sayuda a no intercambiar información sensible por medios públicos.
Biaani proporcionará a sus socios comerciales una identificación de comercio afiliado y una clave asignadas, esta puede ser cambiada cada 3 meses para mantener su confidencialidad. El algorito es el siguiente:

Cadena de verificación = SHA256( IDMERCHANT + “|” + md5(CLAVE_OTORGADA))
Se concatena el ID de comercio otorgado con el carácter “|” (pipeline) y el “hash” resultante de pasar por MD5 la clave otorgada.
Como ejemplo, para un ID de comercio ”COM11MX” y una clave “12345abcde”:

1.- md5(clave) = d5170a3e24af791ba3d674760619fcd9
2.- SHA256(“COM11MX”+”|”+“d5170a3e24af791ba3d674760619fcd9”) = 14eecdb913c0562dc2af93f2956656094d8d98edfa3686e84905ce65e72a5318
Ejemplo de procesamiento de clave

Para una solicitud de sesión:

{
"datetime" :"202120040000",
"idtrx": "31",
"idmerchant" :"COM11MX",
"merchpassword" :"14eecdb913c0562dc2af93f2956656094d8d98edfa3686e84905ce65e72a5318"
}
Ejemplo de uso de clave en mensaje
una respuesta exitosa enviaría, por ejemplo, el campo "auth": "9KDRP7P5756Y" es el que se utilizará para la siguiente operación. /td>

Un dato adicional de seguridad es que. las solicitud de operaciones subsecuentes (todas excepto sessionrequest) es un encabezado “header” dentro del mensaje “Authorization: “ (estándar para usuario y claves) el resultado del siguiente algoritmo:

1.- Cadena de autorización = SHA256(CLAVE_OTORGADA + “|” + token_de_sesión_obtenida)
2.- Continuando con el ejemplo anterior: sha256( "12345abcde" + "|" + "9KDRP7P5756Y")
3.- Resultado: 49a64c85b4710c5858de0af88edfea0366396800499090c83555578d96b02536

Por lo que el header debe contener, por ejemplo:
Accept: */*
Authorization: 49a64c85b4710c5858de0af88edfea0366396800499090c83555578d96b02536
Ejemplo de procesamiento de clave

Descripción de métodos para procesamiento de operaciones

Método sessionrequest

Endpoint: http://api.biaani.com.mx:8888/v1/sessionrequest
Método de envío: POST

Descripción general: Método de seguridad y validación. Abre una sesión de usuario valido para un comercio, los subsecuentes métodos requieren del Id de Sesión que se obtiene. Ésta caduca, o se invalida, una vez realizado un proceso ó pasado un período de máximo de uso de cinco minuto.

Campo Largo Carácter Descripción Formato
datetime 12 M Fecha y hora de solicitud YYMMDDHHMMSS
idtrx 8 M Identificador de la solicitud Entero numérico
idmerchant 30 M Identificador de comercio *1
merchpassword 120 M Clave para comercio *1
*1 : Dato proporcionado por BIAANI, podría requerirse cambios inmediatos periódicos. El procesamiento para envío del pass se detalla en reactivo siguiente.
M: Dato cuyo requerimiento es mandatorio.
O: Opcional, si no se envía este va en vacío (no NULL).

{
"datetime" :"202130040000",
"idtrx": "18",
"idmerchant" :"MERCHANTID",
"merchpassword" :"f7ee4e2d0c20dbc620d1b2c02a4a6a6d893dfa67bbqweqwedsadqwedsad"
}
Ejemplo de consumo sessionrequest

Respuesta

Descripción general: Si la transacción es exitosa (responsecode=”00”) se envía el código de sesión dentro del “auth”, este se utilizará para la siguiente operación, debe ser pasada por una operación que se describe a continuación. Se tiene una vida de 5 minuto para su uso. Si la respuesta es fallida el campo se encontrará vacío (no nulo).

Campo Largo Carácter Descripción Formato
datetime 12 M Fecha y hora de solicitud YYMMDDHHMMSS
idtrx 8 M Identificador de la solicitud Entero numérico
idmerchant 30 M Identificador de comercio *1
responsecode 2 M Código de respuesta *2
auth 16 M Si es exitoso: Código de sesión
message 32 M Descripción del resultado
*2: Listado completo en Apéndice A.
M: Dato cuyo requerimiento es mandatorio.
O: Opcional, si no se envía este va en vacío (no NULL).

{
"datetime" :"202130040000",
"idtrx": "18",
"idmerchant" :"MERCHANTID",
"responsecode": "00",
"auth": "SD9TQ4P3F1L",
"message": "SUCCESS"
}
Ejemplo de consumo sessionrequest

Método echorequest

Endpoint: http://api.biaani.com.mx:8888/v1/echorequest
Método de envío: POST

Descripción general: Método para realizar la verificación de disponibilidad del API y de sus métodos.

Campo Largo Carácter Descripción Formato
idsession 32 M Token obtenido en sessionrequest CCCCCCCC
datetime 12 M Fecha y hora de solicitud YYMMDDHHMMSS
idtrx 8 M Identificador único de la solicitud Entero numérico
idmerchant 32 M Identificador de comercio *1
*1: Dato proporcionado por BIAANI, podría requerirse cambios inmediatos periódicos. El procesamiento para envío del pass se detalla en reactivo siguiente.
*3: Detalle de la obtención de numero de cuenta y UPC en una tarjeta física en Apéndice.
M: Dato cuyo requerimiento es mandatorio.
O: Opcional, si no se envía este va en vacío (no NULL).

{
"idsession":"9KDRP7P5756Y",
"datetime":"210430223807",
"idtrx":"223807",
"idmerchant":"COM11MX",
}
Ejemplo de consumo echorequest

Respuesta

Descripción general: Si la transacción es exitosa, se obtendrá un responsecode=”00”, igualmente se envía una autorización dentro del campo “auth”. Por otro lado una transaccion rechazada tendrá una respuesta acorde al error encontrado dentro del procesador. Puede consultar la tabla de codigos de error en el Apéndice. Todos los campos recibidos son respondido con los mismo valores (“eco”) y se adicionan los resultados de la operación en los siguientes campos:.

Campo Largo Carácter Descripción Formato
idsession 32 M Token obtenido en sessionrequest CCCCCCCC
datetime 12 M Fecha y hora de solicitud YYMMDDHHMMSS
idtrx 8 M Identificador único de la solicitud Entero numérico
idmerchant 32 M Identificador de comercio *1
responsecode 2 M Código de respuesta *2
auth 16 M Si es exitoso: Código de sesión
message 32 M Descripción del resultado
*1: Dato proporcionado por BIAANI, podría requerirse cambios inmediatos periódicos. El procesamiento para envío del pass se detalla en reactivo siguiente.
*2: Listado completo en Apéndice A.
*3: Detalle de la obtención de numero de cuenta y UPC en una tarjeta física en Apéndice.
M: Dato cuyo requerimiento es mandatorio.
O: Opcional, si no se envía este va en vacío (no NULL).

{
"idsession":"9KDRP7P5756Y ",
"datetime":"210430223807",
"idtrx":"223807",
"idmerchant":"COM11MX",
"responsecode": "00",
"auth": "SD9TQ4P3F1L",
"message": "SUCCESS"
}
Ejemplo de respuesta exitosa en echorequest

Método activationrequest

Endpoint: http://api.biaani.com.mx:8888/v1/activationrequest
Método de envío: POST

Descripción general: Método para realizar la activación de una tarjeta de prepago física. Pasa de su estado inactivo (sin servicio) a activo (lista para ser canjeada). Utiliza el header “Authorization” con el valor que se describe en "Procesamiento de clave y auth para el uso en sesión".

Campo Largo Carácter Descripción Formato
idsession 32 M Token obtenido en sessionrequest CCCCCCCC
accountnumber 32 M Identificador de la tarjeta (actualmente 16 números) *3 NNNNNNNNNNN
amount 8 M Precio de tarjeta (por ejemplo: $100.00 = 10000) MMMCC
datetime 12 M Fecha y hora de solicitud YYMMDDHHMMSS
idtrx 8 M Identificador único de la solicitud Entero numérico
idmerchant 32 M Identificador de comercio *1
idstore 32 M Identificador de sucursal
idterminal 32 M Identificador de terminal o caja
upc 12 M Número identificador de un producto
*1: Dato proporcionado por BIAANI, podría requerirse cambios inmediatos periódicos. El procesamiento para envío del pass se detalla en reactivo siguiente.
*3: Detalle de la obtención de numero de cuenta y UPC en una tarjeta física en Apéndice.
M: Dato cuyo requerimiento es mandatorio.
O: Opcional, si no se envía este va en vacío (no NULL).

{
"idsession":"9KDRP7P5756Y ",
"accountnumber":"636981000154235678",
"amount":"10000",
"datetime":"210430223807",
"idtrx":"223807",
"idmerchant":"COM11MX",
"idstore":"1",
"idterminal":"A1",
"upc":"75869900000"
}
Ejemplo de consumo activationrequest

Respuesta

Descripción general: Si la transacción es exitosa, se obtendrá un responsecode=”00”, igualmente se envía una autorización dentro del campo “auth”. Por otro lado una transaccion rechazada tendrá una respuesta acorde al error encontrado dentro del procesador. Puede consultar la tabla de codigos de error en el Apéndice. Todos los campos recibidos son respondido con los mismo valores (“eco”) y se adicionan los resultados de la operación en los siguientes campos:.

Campo Largo Carácter Descripción Formato
idsession 32 M Token obtenido en sessionrequest CCCCCCCC
accountnumber 32 M Identificador de la tarjeta (actualmente 16 números) *3 NNNNNNNNNNN
amount 8 M Precio de tarjeta (por ejemplo: $100.00 = 10000) MMMCC
datetime 12 M Fecha y hora de solicitud YYMMDDHHMMSS
idtrx 8 M Identificador único de la solicitud Entero numérico
idmerchant 32 M Identificador de comercio *1
idstrore 32 M Identificador de sucursal
idterminal 32 M Identificador de terminal o caja
upc 12 M Número identificador de un producto
responsecode 2 M Código de respuesta *2
auth 16 M Si es exitoso: Código de sesión
message 32 M Descripción del resultado
*1: Dato proporcionado por BIAANI, podría requerirse cambios inmediatos periódicos. El procesamiento para envío del pass se detalla en reactivo siguiente.
*2: Listado completo en Apéndice A.
*3: Detalle de la obtención de numero de cuenta y UPC en una tarjeta física en Apéndice.
M: Dato cuyo requerimiento es mandatorio.
O: Opcional, si no se envía este va en vacío (no NULL).

{
"idsession":"9KDRP7P5756Y ",
"accountnumber":"636981000154235678",
"amount":"10000",
"datetime":"210430223807",
"idtrx":"223807",
"idmerchant":"COM11MX",
"idstore":"1",
"idterminal":"A1",
"upc":"75869900000"
"responsecode": "00",
"auth": "SD9TQ4P3F1L",
"message": "SUCCESS"
}
Ejemplo de respuesta exitosa en activationrequest

Método deactivationrequest

Endpoint: http://api.biaani.com.mx:8888/v1/deactivationrequest
Método de envío: POST

Descripción general: Método para realizar la desactivación ó "reversos" a una activación para determinada tarjeta de prepago física. Pasa de su estado activo (lista para ser canjeada) a inactivo (sin servicio). Utiliza el header “Authorization” con el valor que se describe en "Procesamiento de clave y auth para el uso en sesión". Se utilizan todos los datos de la tarjeta "original" de la activación a crear el "reverso".

Campo Largo Carácter Descripción Formato
idsession 32 M Token obtenido en sessionrequest CCCCCCCC
accountnumber 32 M Identificador de la tarjeta a "desactivar" (actualmente 16 números) *3 NNNNNNNNNNN
amount 8 M Precio de tarjeta (por ejemplo: $100.00 = 10000) MMMCC
datetime 12 M Fecha y hora de solicitud YYMMDDHHMMSS
idtrx 8 M Identificador único de la solicitud ORIGINAL Entero numérico
idmerchant 32 M Identificador de comercio *1  
idstore 32 M Identificador de sucursal  
idterminal 32 M Identificador de terminal o caja  
upc 12 M Número identificador de un producto  
*1: Dato proporcionado por BIAANI, podría requerirse cambios inmediatos periódicos. El procesamiento para envío del pass se detalla en reactivo siguiente.
*3: Detalle de la obtención de numero de cuenta y UPC en una tarjeta física en Apéndice.
M: Dato cuyo requerimiento es mandatorio.
O: Opcional, si no se envía este va en vacío (no NULL).

{
"idsession":"9KDRP7P5756Y ",
"accountnumber":"636981000154235678",
"amount":"10000",
"datetime":"210430223807",
"idtrx":"223807",
"idmerchant":"COM11MX",
"idstore":"1",
"idterminal":"A1",
"upc":"75869900000"
}
Ejemplo de consumo deactivationrequest

Respuesta

Descripción general: Si la transacción es exitosa, se obtendrá un responsecode=”00”, igualmente se envía una autorización dentro del campo “auth”. Por otro lado una transaccion rechazada tendrá una respuesta acorde al error encontrado dentro del procesador. Puede consultar la tabla de codigos de error en el Apéndice. Todos los campos recibidos son respondido con los mismo valores (“eco”) y se adicionan los resultados de la operación en los siguientes campos:.

Campo Largo Carácter Descripción Formato
idsession 32 M Token obtenido en sessionrequest CCCCCCCC
accountnumber 32 M Identificador de la tarjeta (actualmente 16 números) *3 NNNNNNNNNNN
amount 8 M Precio de tarjeta (por ejemplo: $100.00 = 10000) MMMCC
datetime 12 M Fecha y hora de solicitud YYMMDDHHMMSS
idtrx 8 M Identificador único de la solicitud Entero numérico
idmerchant 32 M Identificador de comercio *1
idstore 32 M Identificador de sucursal
idterminal 32 M Identificador de terminal o caja
upc 12 M Número identificador de un producto
responsecode 2 M Código de respuesta *2
auth 16 M Si es exitoso: Código de sesión
message 32 M Descripción del resultado
*1: Dato proporcionado por BIAANI, podría requerirse cambios inmediatos periódicos. El procesamiento para envío del pass se detalla en reactivo siguiente.
*2: Listado completo en Apéndice A.
*3: Detalle de la obtención de numero de cuenta y UPC en una tarjeta física en Apéndice.
M: Dato cuyo requerimiento es mandatorio.
O: Opcional, si no se envía este va en vacío (no NULL).

{
"idsession":"9KDRP7P5756Y ",
"accountnumber":"636981000154235678",
"amount":"10000",
"datetime":"210430223807",
"idtrx":"223807",
"idmerchant":"COM11MX",
"idstore":"1",
"idterminal":"A1",
"upc":"75869900000"
"responsecode": "00",
"auth": "SD9TQ4P3F1L",
"message": "SUCCESS"
}
Ejemplo de respuesta exitosa deactivationrequest

Notas generales en procesos sobre PINes y productos Digitales.

Requerimiento de codigo digital (PIN).

Método pinrequest

Endpoint: http://api.biaani.com.mx:8888/v1/pinrequest
Método de envío: POST

Descripción general: Método para realizar la solicitud de un código digital redimible. al obtener el PIN, el cliente podrá directamente llegar al sitio ó aplicación del proveedor del servicio y redimirlo/canjearlo por el producto, saldo ó servicio que este ofrezca.

Campo Largo Carácter Descripción Formato
idsession 32 M Token obtenido en sessionrequest CCCCCCCC
accountnumber 32 M Identificador de la tarjeta (actualmente 16 números) *3 NNNNNNNNNNN
amount 8 M Precio de tarjeta (por ejemplo: $100.00 = 10000) MMMCC
datetime 12 M Fecha y hora de solicitud YYMMDDHHMMSS
idtrx 8 M Identificador único de la solicitud Entero numérico
idmerchant 32 M Identificador de comercio *1
idstore 32 M Identificador de sucursal
idterminal 32 M Identificador de terminal o caja
upc 12 M Número identificador de un producto
*1: Dato proporcionado por BIAANI, podría requerirse cambios inmediatos periódicos. El procesamiento para envío del pass se detalla en reactivo siguiente.
*3: Detalle de la obtención de numero de cuenta y UPC en una tarjeta física en Apéndice.
M: Dato cuyo requerimiento es mandatorio.
O: Opcional, si no se envía este va en vacío (no NULL).

{
"idsession":"9KDRP7P5756Y ",
"accountnumber":"636981000154235678",
"amount":"10000",
"datetime":"210430223807",
"idtrx":"223807",
"idmerchant":"COM11MX",
"idstore":"1",
"idterminal":"A1",
"upc":"75869900000"
}
Ejemplo de consumo pinrequest

Respuesta

Descripción general: Si la transacción es exitosa, se obtendrá un responsecode=”00”, igualmente se envía una autorización dentro del campo “auth”. Por otro lado una transaccion rechazada tendrá una respuesta acorde al error encontrado dentro del procesador. Puede consultar la tabla de codigos de error en el Apéndice. Todos los campos recibidos son respondido con los mismo valores (“eco”) y se adicionan los resultados de la operación en los siguientes campos:.

Campo Largo Carácter Descripción Formato
idsession 32 M Token obtenido en sessionrequest CCCCCCCC
accountnumber 32 M Identificador de la tarjeta (actualmente 16 números) *3 NNNNNNNNNNN
amount 8 M Precio de tarjeta (por ejemplo: $100.00 = 10000) MMMCC
datetime 12 M Fecha y hora de solicitud YYMMDDHHMMSS
idtrx 8 M Identificador único de la solicitud Entero numérico
idmerchant 32 M Identificador de comercio *1
idstrore 32 M Identificador de sucursal
idterminal 32 M Identificador de terminal o caja
upc 12 M Número identificador de un producto
responsecode 2 M Código de respuesta *2
digital-code 32 M PIN Redimible *2
auth 16 M Si es exitoso: Código de sesión
message 32 M Descripción del resultado
*1: Dato proporcionado por BIAANI, podría requerirse cambios inmediatos periódicos. El procesamiento para envío del pass se detalla en reactivo siguiente.
*2: Listado completo en Apéndice A.
*3: Detalle de la obtención de numero de cuenta y UPC en una tarjeta física en Apéndice.
M: Dato cuyo requerimiento es mandatorio.
O: Opcional, si no se envía este va en vacío (no NULL).

{
"idsession":"9KDRP7P5756Y ",
"accountnumber":"636981000154235678",
"amount":"10000",
"datetime":"210430223807",
"idtrx":"223807",
"idmerchant":"COM11MX",
"idstore":"1",
"idterminal":"A1",
"upc":"75869900000"
"responsecode": "00",
"digital-code":"6NZ9LHPBC5RF"
"auth": "SD9TQ4P3F1L",
"message": "SUCCESS"
}
Ejemplo de respuesta exitosa en pinrequest