Guia de Integracion QR Manager v1.4.2

Soluciones Corporativas
Digital Factory
Proyecto QR Payments
Guía de Integración – QR Manager
Versión 1.4.2
Último cambio al documento: 26 Mayo 2020

Autores: Robert More
Enviar comentarios a: rmore@niubiz.com.pe
Nombre del Documento: Guía de Integración QR Manager
Confidencial Niubiz:
Tabla de Contenido
1. PREFACIO ............................................................................................... 4
1.1. ACERCA DEL DOCUMENTO ............................................................................................... 4
1.2. HISTORIA DE CAMBIOS ..................................................................................................... 4
1.3. APROBACIONES .............................................................................................................. 4
1.4. DISTRIBUCIÓN ................................................................................................................. 4
1.5. REVISORES .................................................................................................................... 4
2. INTRODUCCIÓN ......................................................................................6
2.1. PROPÓSITO .................................................................................................................... 6
2.2. ALCANCE........................................................................................................................ 6
2.3. PÚBLICO OBJETIVO .......................................................................................................... 6
2.4. DOCUMENTOS RELACIONADOS ......................................................................................... 6
3. DESCRIPCIÓN DE LA SOLUCIÓN ......................................................... 7
3.1. DIAGRAMA TÉCNICO ........................................................................................................ 8
4. PASOS PARA INTEGRARME ............................................................... 10
5. INTEGRACIÓN API SECURITY ............................................................. 12
6. DIAGRAMAS DE LA SOLUCIÓN .......................................................... 13
6.1. DIAGRAMAS DE SECUENCIA – GENERACIÓN DE QR SIMPLE .............................................. 13
6.2. DIAGRAMAS DE SECUENCIA – GENERACIÓN DE QR BATCH............................................... 14
7. INTEGRACIÓN API QR MANAGER ...................................................... 15
7.1. DETALLE DEL SERVICIO GENERADOR DE QRS SIMPLE ...................................................... 15
7.2. EJEMPLO DE TRAMA QR ESTÁTICO ................................................................................. 16
7.3. EJEMPLO DE TRAMA QR DINÁMICO ................................................................................. 18
7.4. EJEMPLO DE FORMATO TLV EMVCO ............................................................................. 20
8. INTEGRACIÓN API QR BATCH ............................................................ 21
8.1. DETALLE DEL SERVICIO GENERADOR DE QRS BATCH ...................................................... 21
8.2. DETALLE DEL SERVICIO STATUS QRS BATCH .................................................................. 22
8.3. FORMATO DE ARCHIVOS BATCH ...................................................................................... 23
8.4. EJEMPLO TRAMA DE ENVÍO DE BATCH QR ...................................................................... 24
8.5. CONSULTA STATUS DE BATCH QR ................................................................................. 24
8.6. DICCIONARIO DE ERRORES ............................................................................................ 24
9. INTEGRACIÓN API RSCA CALLBACK ................................................ 25
9.1. FLUJO DE CALLBACK ..................................................................................................... 25
9.2. EJEMPLO DE TRAMA RSCA............................................................................................ 26
10. INTEGRACIÓN APIS CONSULTA TRANSACCIONES ......................... 27
10.1. DETALLE DEL SERVICIO DE OBTENER TRANSACCIÓN .................................................... 27
10.2. EJEMPLO DE LA TRAMA A ENVIAR ............................................................................... 28
10.3. DETALLE DEL SERVICIO DE CONSULTAR TRANSACCIONES POR FECHA ........................... 29
11. INTEGRACIÓN API VOID ...................................................................... 31
11.1. DETALLE DEL SERVICIO DE ANULACIÓN DE TRANSACCIÓN ............................................ 31
Confidencial – Niubiz Página 2 de 34

12. CONSULTA DE DEUDA ........................................................................ 33
12.1. DETALLE DEL SERVICIO DE CONSULTA DE DEUDA ........................................................ 33
12.2. EJEMPLO DE TRAMA CONSULTA DE DEUDA ................................................................. 34

1. Prefacio
1.1. Acerca del documento
Este documento especifica en detalle los componentes y su interacción para la implementación de requerimien-
tos con metodología Agile.
1.2. Historia de cambios
Fecha de revisión Autor Resumen de cambios Versión

20 Agosto 2019 Robert More Versión Inicial 1.0
15 Octubre 2019 Robert More Se ingresa flujo general de Pago QR 1.1
07 Diciembre 2019 Robert More Se agrega el detalle del servicio Callback para 1.2
la notificación de Pago
30 Diciembre 2019 Robert More Se agrega detalle de servicio para anular y 1.3
consultar transacciones procesadas correcta-
mente
20 Mayo 2020 Robert More Se agrega pasos para integración 1.4
Se agrega qrdemo para las integraciones
26 Mayo 2020 Robert More Se agrega estructura estándar del servicio 1.4.1
consulta de deuda.
28 Junio 2020 Robert More Se agrega los campos idc a los servicios con- 1.4.2
sulta de deuda y notificación de pago, como
identificador único del cliente al momento de
asociar un producto o servicio a venta con QR
1.3. Aprobaciones
La versión consolidada de este documento será incluida en el repositorio del proyecto en la herramienta interna
de Niubiz. Las aprobaciones son documentadas vía la distribución del documento y la firma de los aprobadores.
Nombre Rol Fecha de aprobación
1.4. Distribución
Este documento ha sido distribuido a:
Nombre Rol
1.5. Revisores
Revisor Rol Requerido

Revisor Rol Requerido

2. Introducción
2.1. Propósito
El propósito del presente documento es especificar en detalle los componentes y su interacción para lograr la
integración con el gestor de QRs del directorio de Niubiz
2.2. Alcance
El documento técnico define el contexto de la implementación de la integración completa con el autorizador

HubProcess
2.3. Público objetivo

Es de utilidad para los implementadores de la solución, como marco de referencia para implementar los dife-
rentes requerimientos de integración
2.4. Documentos relacionados
Título del Documento Autor Nombre del Documento Ubicación del

Documento
EMVCo QR Specification EMV EMVCo-Merchant-Presen- https://www.cbe.
ted-QR-Specification-v1_0 org.eg/en/Pay-
mentSys-
tems/Regula-
tionsDL/Uni-
fied%20Stan-
dard%20for%20
Quick%20Res-
ponse%20Code
%20-%20QR.pd
f

3. Descripción de la solución
La presente solución tiene como finalidad de facilitar a los comercios incorporar como medio de pago adicional
el código QR, esto con el fin de facilitar a los usuarios de las Wallets hacer el pago correspondiente de uno de
sus productos o servicios.
Para ello es necesario tener claro el termino Wallet o Billetera electrónica que hace referencia a una aplicación
que permite usar dispositivos móviles para guardar dinero, pagar, cobrar y hasta hacer transferencias.
Aceptación: Yape, Lukita, Tunki, Ligo, MobileCard
¿Cómo funciona?
El comercio puede disponer de dos tipos de QR:
1. QR Estático: puede recibir “n” pagos con el mismo QR y tiene un periodo de Vigencia extendida.
Este puede ser aplicado a puntos de ventas físico cuando el QR es impreso.
2. QR Dinámico: puede recibir un sólo pago y queda desactivado una vez hecho el pago.
Es aplicado cuando el QR está impreso en un recibo o boleta o corresponde únicamente a un pro-
ducto. Por ejemplo: Recibo de servicios, Boleta de Pagos.
El comercio puede tener QRs físicos que pueden ser los parante o fotocheck que son QR estáticos y son asig-
nados directamente al comercio para su punto físico una vez afiliado, los pagos realizados a este QR serán
recibidos únicamente al aplicativo QR Niubiz que podrán descargarlo desde PlayStore (Android) o AppStore
(iOS) e ingresarán al mismo con el usuario asignado.

Si el comercio requiere generar QRs de manera dinámica para imprimirlos es su recibo o donde requiera colo-
carlos se tendrá que integrar a las APIs de Niubiz para la generación de los mismo y para la recepción de las
notificaciones de Pago para poder conciliar con sus sistemas.
3.1. Diagrama Técnico
1. Todo Comercio el cual requiera generar códigos QR como medio de pago adicional deberá estar registrado
previamente dentro del QR Directory; es decir, debe solicitar a Niubiz un Código de Comercio QR.
Una vez registrado podrá realizar la generación de los códigos QR ya sea de forma integrada a su sistema
(QR Dinámico) o puntualmente un solo QR en su punto de venta (QR Estático)
Para el caso de un Bill Payments la generación debe ser por Batch.
2. Si el comercio se encuentra integrado a las APIs para la generación de los QR, deberá disponibilizar un
servicio Callback para recibir las notificaciones de Pago de los QR Dinámicos, caso contrario podrá descar-
gar el aplicativo Niubiz QR donde podrá visualizar los pagos realizados a su parante (QR Estático).
3. Las Billeteras podrán escanear los QRs Estáticos o Dinámicos para poder iniciar el Pago QR,
4. Seleccionarán la tarjeta de su banco ya sea crédito o débito donde se les hará el cargo por la compra.
5. Las billeteras una vez validado el saldo de la tarjeta y junto al QR escaneado procederá a generar la trama
para enviarlo al banco o al adquiriente que se encuentre integrado.
6. Las Billeteras enviarán una petición de autorización de la transacción a Niubiz a través del componente
“Authorization HUB”

7. El autorizador de Niubiz validará si el QR es una transacción P2MB o Comercio electrónico, de ello depen-
derá el abono inmediato o diferido.
8. Una vez autorizada la transacción se notificará el pago primero a la Billetera
9. Luego al comercio a través de Push Notification al aplicativo, SMS, correo o al servicio Callback disponible
por el cliente.

4. Pasos para integrarme
QR Integrado: Dirigido a comercio que requieran generar sus QRs en línea para la venta de su producto o
servicio a través del pago con Billetera Electrónica
Paso 1 Credenciales
Deberá generar tokens a través del API Security del punto 5 para el uso de todas las APIs de QR,
las credenciales para integrarse están en la misma sección, en el ambiente productivo deberá
proporcionar un correo custodio para las credenciales de las APIs a donde se les enviará de ma-
nera anónima.
Paso 2 Generar QRs
Deberá generar los QRs Dinámicos en línea a través del servicio de la sección 7.1, para esto utili-
zará el codigo de comercio 438933213 para la integración.
En producción en necesario la generación de un nuevo código de comercio luego de la afiliación.
Para los QRs en línea tener en cuenta que deberán tener una fecha de vencimiento como mínimo
posterior al día de su generación.
El QR devuelto es en formato base64 por lo que podrá ajustar el tamaño de este dependiendo el
contenedor donde este embebido.
Paso 3 Notificación de Pago
Una vez generado los QRs y al hacer un pago este será notificado vía Callback al servicio (URL)
que proporcione el comercio de manera automática con el formato de trama indicado en la sec-
ción 9.2, quedando en responsabilidad del comercio interpretar los campos para conciliar.
El comercio deberá proporcionar un correo de derivar las notificaciones de error en caso el servi-
cio empiece a reportar inconvenientes para tomar acciones inmediatas.
El comercio tendrá la responsabilidad de restringir las IPs de los ambientes correspondientes.
Desarrollo:
35.153.17.226
Producción:
52.207.94.42 / 52.54.136.111 / 18.232.138.252 / 3.86.214.217
Todos los pagos son liquidados a las 12:00 pm, posterior a ello no se podrá anular la transacción
y pasará a un flujo de devolución regular.
En caso de algún cambio, Niubiz lo notificará.
Paso 4 Anulación
Únicamente se podrán anular las transacciones notificadas via Callback según el detalle del ser-
vicio de la sección 11
Paso 5 Simular Pagos
El comercio podrá simular Pagos al QR generado a través de nuestra demo en el link siguiente:
https://soporteqa.vnportalqr.com.pe/qrdemo/

QR Bill Payments: Dirigido a comercio que requieran generar sus QRs de manera asíncrona o Batch para
la inserción del QR posteriormente en algún medio ya sea recibos, medios digitales, etc.
Paso 1 Credenciales
Deberá generar tokens a través del API Security del punto 5 para el uso de todas las APIs de QR,
las credenciales para integrarse están en la misma sección, en el ambiente productivo deberá
proporcionar un correo custodio para las credenciales de las APIs a donde se les enviará de ma-
nera anónima.
Paso 2 Generar QRs
Deberá generar los QRs Dinámicos en Batch a través del servicio de la sección 8, para esto utili-
zará el codigo de comercio 438933213 para la integración.
En producción en necesario la generación de un nuevo código de comercio luego de la afiliación.
Es importante tener en cuenta el correcto formato de la generación del archivo TXT y zipeado
para luego codificarlo en base64 según la sección 8.3
El servicio devolverá un idprocess con el cual podrá recuperar el archivo resultante en el paso 3
Ver demo: https://soporteqa.vnportalqr.com.pe/qrdemo/
Paso 3 Consulta QRs
El comercio deberá consultar el status de su petición a través del servicio de la sección 8.2 con el
idprocess devuelto en el paso 2
El formato del archivo devuelto será similar al enviado, codificado en base64, zipeado y dentro
encontrará el archivo TXT con el resultante.
Paso 4 Consulta de Deuda
El comercio podrá proporcionar un servicio para la consulta de deuda de los recibos para no reali-
zar pagos dobles. Esto implica una integración por parte de Niubiz que puede llevar a un costo
adicional que será notificado al comercio.
Paso 5 Notificación de Pago
Una vez generado los QRs y al hacer un pago este será notificado vía Callback al servicio (URL)
que proporcione el comercio de manera automática con el formato de trama indicado en la sec-
ción 9.2, quedando en responsabilidad del comercio interpretar los campos para conciliar.
Los campos adicionales al momento de crear los QRs via Batch será notificados via dataMap
(campo:valor) al comercio via la trama Callback
El comercio deberá proporcionar un correo de derivar las notificaciones de error en caso el servi-
cio empiece a reportar inconvenientes para tomar acciones inmediatas.
El comercio tendrá la responsabilidad de restringir las IPs de los ambientes correspondientes.
Todos los pagos son liquidados a las 12:00 pm, posterior a ello no se podrá anular la transacción
y pasará a un flujo de devolución regular.
En caso de algún cambio, Niubiz lo notificará.
Paso 6 Anulación
Únicamente se podrán anular las transacciones notificadas via Callback según el detalle del ser-
vicio de la sección 11

5. Integración API Security
API encargado de la administración de la seguridad, este será necesario para cada API posterior que se quiera
consumir.
URLs Servicios
QA https://apitestenv.vnforapps.com/api.security/v1/security
PROD https://apiprod.vnforapps.com/api.security/v1/security
Método: GET
AUTHORIZATION
Nombre del
Tipo Descripción Mandatorio Valor
Fila Entidad Campo
Usuario asignado para la ge-
1 N/A username Alfanumérico Si Solicitar a VNT
neración de tokens
contraseña asignada para la
2 N/A Password Alfanumérico Si Solicitar a VNT
generación de tokens
RESPONSE
Nombre del
Fila Campo
Token para el consumo de los servicios siguien-
1 N/A String Si
tes
Código Descripción del error

200 successful operation
401 Unauthorized
500 Request is not valid
Credenciales del Ambiente de Integración
Usrtest: integraciones.visanet@necomplus.com
Password: d5e7nk$M

6. Diagramas de la solución
6.1. Diagramas de Secuencia – Generación de QR Simple

6.2. Diagramas de Secuencia – Generación de QR Batch

7. Integración API QR Manager
7.1. Detalle del servicio Generador de QRs Simple
API encargado de la creación de QRs en formato ASCII
URLs Servicios
QA https://apitestenv.vnforapps.com/api.qr.manager/v1/qr/ascii
PROD https://apiprod.vnforapps.com/api.qr.manager/v1/qr/ascii
Método: POST
HEADERS
Nombre del
Fila Entidad Campo
1 N/A Content-Type String Tipo de encoding del Request Si
2 N/A Authorization String Token generado por el api.security Si
REQUEST
Fila Entidad Nombre del Campo Tipo Descripción Mandatorio Valor
1 N/A Boolean String estado de QR Si true
Utilizar el codigo de co-
mercio 438933213 en
Código de comercio NIUBIZ
3 param merchantId String Si QA
asignado
Código asignado por
Niubiz en producción
En el caso de Payment
Facilitator con un solo
código de comercio, po-
4 param merchantName String Nombre del comercio No drá cambiar el nombre
de comercio depen-
diendo su comercio afi-
liado.
Opcional dependiendo
5 param mcc String Código MCC Internacional No
el PF
código de moneda de afilia- 604 Soles
6 param transactionCurrency String Si
ción 840 Dólares
(*) Solo cuando el tipo
7 param transactionAmount String importe de la transacción No
de QR es DYNAMIC
Información adicional
param additionalData String Data adicional No para la notificación de
pago
STATIC
8 N/A tagType String tipo de QR Si
DYNAMIC
9 N/A validityDate String fecha de vencimiento Si Formato ddmmyyyyy

RESPONSE
Nombre del
Fila Campo
1 codResponse String Código de respuesta de la transacción 0 - Éxito
2 message String Descriptivo de código de respuesta
3 tagId String Identificador único de QR generado
4 tagImg String imagen en base 64
Código Descripción del error

200 Successful operation
401 Unauthorized
500 Request is not valid
7.2. Ejemplo de trama QR Estático
Request
{ "enabled": true,
"param": [
{
"name": "merchantId",
"value": " 438933213"
}, {
"name": "transactionCurrency",
"value": "604"
}
],
"tagType": "STATIC",
"validityDate": "17122019"
}
Response
{
"codeResponse": 0,
"message": "Exito",
"tagId": "67adc6875aec44cb9485a636042e6438",

"tagImg": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAV4AAAFeAQAAAADlUEq3AAAE40lE-
QVR42u2bTY7iUAyEHbHIkiO8m8DFkEDiYuQmOQLLLKJ4XJ+fIE1rpNl6BAuGIZWW4ue-
fctmY//trtS/4C/6CS4FXi9fVbfC-
bLWe/x6fndfaHXWc7He/zMjwDMBQGN/e4ugS46Tu3s/sc/8a9Q9wb4Kv7VBncH/8oiJ78dFzDLvrOn4c5rl5s/A/A8V8f
H3aYR/f7bOfnpfkU947T/wC+tPFxFETHHa82bmEc2aXptuJg/BlD+Ha86cLa-
FrMLZ+6j/3b+WmA9fVhjev717SN9FQNnvVA-
yUpjquPVp3LCGMvD5swCVA4fHmpz6oLwbt/E6hT8v8aYgjtCtDFYyCi9Wyh05/bOsMaWFomie4tba4Djag9spApbz-
deVY6mV8OjihqzMvC3Ygi447Eu2aRVPlpC292CRdKAsOG8AFwm0XMTxVFw+SADW44NmvlFsRzA2ReCyKZtSU-
wHlCgtfpTSRBBisLJudEWVS9JPmOgIlVZdsFel4bvMkQj3x8J0zhsTr44Af-
niNp3fq4I1vk2eivPEkOXBdcTFZryallw8DqR8ohV2owI2ClOGhfgO4Vu2xHXcmAR8KDiO-
lUCVn2j6oy8OAI2/9Q75dYDr3gxHZVnr0HzmJ1/v81fpqsJHqABykN2JAW5msdO7jycOvqPwuDmaR-
KLBktdFtmWFpnyiRDwKkAlwaYeUdSgZR6K6hL84IiZIohNzjA-
VBmfxV/bJ/CutqpM7T16HcQqD1T3pzeIO0R5ddUyCU+PjQ2FwQ15cdKpIOfADR+SQSX6SwJJgpEQ1WLOYeR-
hCAnF37ytRO7sXBuuQo3vSSUvVa-
JRKPo38qU38YKgLhpnTKCJj3PBsSY7JBWShXftfEyzfhb6FSdKVTU7dCGI8+8XrKoJTyVcym-
tETlx61Xc8Zf9D4gmAedUXTlxdfU2PMXhKTTJ28lwUbHsu8ws4pSZlwd1H2a3r7rsLWAzdExWXI3ISoCMNL-
DeDXrK0cWAGrlnFTj8hxM6mZYDzPJOXzLuWWA4v2MIWSDE5bZamp9oYSKmSFwSg2aBmXFBoh6pLlZkRU5O
N3fq4HRs6/NdrhLJ/cMaQasKp8MukvC86631hMGLuWcctK4lOPVX8XzYr-
geGh30iuNIgo4CpVmwh8ialGwrEEl0SfIHU7NcgZ9spUGp6CB5gb3gbOigNN/MNyY6oL-
VHsZ3UBxXWqLBskxGTKbM2i4/FwSjmuZQlOE9Mrihb7jo+XHP6+qBPbcxFLAZuqOm-
hwwYOfjR+wCgKphH7Rf6DIOtIX3H6G1jX6ouWEWE9S7ngmZPYQ00D+LXU0mtDU-
biN6h4KouOKq47nNH+m9dVBI99/ou8eGu5qrclcb2mrXatRzmwNKicBN9RhD1XhyRT-
vRbb2k5jLAdmVU+Dw7gjV2iR4Fg8oTt23xHXguC+IbRQG6V7j54DbgYAa2+wSoN-
RhCHgL+Gt5VAqx8EaABQG9809bXSnF8s4hg1Q5FJj9Lrg3L20LCKiBmRbxhdoHtk7T4XBbM+697hkgs985tZyU3H
4IUhWBLOI0TUAqY3dgVeWoH9pjDXBSQgY1+Tyu-
gppg8KSpd7DxKpgDrnBfXTBkTYoNqNnO1IYnGPtjUmN1i8meF1mqUsWlo+fydQC5++AW-
BjCd/2Ry1AIH7k465XB35+qfcFf8Bf8BywXj86YucsDAAAAAElFTkSuQmCC"
Imagen QR ASCII

7.3. Ejemplo de trama QR Dinámico
Request
{
"enabled": true,
"param": [
{
"name": "merchantId",
"value": "438933213"
},
{
"name": "transactionCurrency",
"value": "604"
},
{
"name": "transactionAmount",
"value": "20.20"
},
{
"name": "additionalData",
"value": “12312"
},
{
"name": "idc",
"value": “995500"
}
],
"tagType": "DYNAMIC",
"validityDate": "31122020"
}
Response
{
"codeResponse": 0,
"message": "Exito",
"tagId": "de077968cc394f318bd29daad08cba4b",

"tagImg": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAV4AAAFeAQAAAADlUEq3AAAFcklE-
QVR42u1bS66jQAw0YsGSI3CTcDEkIuVicBOOwJIFwuOq6iZ5T3rSLGZjzcsCQSgi0e1PueyY//3ntF/w/wXeza-
zZbfDVnzib7LDeN9zdjkf/cnv0Z2Bszgqe3de9jXvA-
PXr3Y4zLY4xvjmZvN9wY4pAWPFm3xmpYgwVYDJf+wrM2HA9rt3hiiru5wbHTfmFXmzjrrp4LYQN/xZf+zA+G2Vrr-
cebeLRaLY/0Tlv3yzr+vRjJwsedugZvysCL4rPErFpYd2+3nd+NPBWZEmrC1Px++hq9cYH7iEr46dBcOs-
RqDjViDy2au0JcElA18Gt83cO3WIZPg1SP4Bg7Jxg44cfzUnBS8x/te8lDfs-
BAWln1a5JRwYhzgzttt/PnAcYbAswUk7ja4bASJZ2P3reQUbXdGcHyuwGFJsMmkPacSaZ-
CEJ/hQ/FRZjYRgbDeTpsNNI/DEQsR3kTnDYUvcDScOr00Kjo/BOfG+2N9ZhCC+Dn4QBwSoJwjQnBQcSf-
MAA2BYOiyoQSwJmcJJSIRchKq6dBnBWAMTKTcZcHwXweiJxMIoFWF4rPac-
DozcuMRqAGe8y7BkeJax+MBj1Z4TgmO7GVmZPxycNTa+3ZhitEJImjhLCsaukgbAqMHHh/ssbqJ4XBil-
PCsYq4En4JcOhwVJwHcg5QxVzClXjUjpwF7eHFoGS/2wbCxOU8rmIE-
AfzDwj+JSvwpQl5chXFwUoV0FZeV1CMMQaEDnUiKCrUTyCBQUrCIY3xmp49d+kYLCCUez1LIL-
GBYfls0qasIMrLbhWT0fVNzbxukXpEzkFObTxrGDsdLy0K7ICwixZc0opR7xEpJRgFMEz6g+IU7HnUt+gBjA-
YYTX8XYilA8MlL+70PkumOooqfhLH0tLfClU6MCoMWDGjjzIJNh6XInxOUad4d0Iw4unI+lcEv-
CWbw5kZZSozBl9PC54hSbXSbvjmwX0Yd935WMmmacESL6aBRl3FfjympNmWUHVHpHxgijVMIigzqjas-
BtSqiERh1ZOCd0ob4gIDxSmsxkAey5xyNPu9GinBEjSQRFo-
vZVV8cLlRCDj0RSWB+cDGNoyU1ANVB2srlVXk5Ozj1ASUEEwNaqL4PUi2gVFjk4vOD6+tOSUn2FRhoOpwe-
WirjmJHUgQbrxMLCcFwTnhoxyoLGqPkVAYjMlr0Uru8YA0rwENRa0CrUjHlahEzpc4f1XE+MGgAIisPDyu-
qhjObruJ6b3tOCEZtVdgc+lF3R/GBYrmWI+aJwRpMQLvGNUpTFX/WVsWe/Zbg0oHVLa-
XINhn7M84u1NKXsvlovrdWc4ERaNVcQ5NmlOuK7JCUD1/sOSEYragRJwuDEbhPIXItjdo4NZQaXJI/FSqAacAa-
bGPpsaoHnhZskjGY/NFSc228qRXFxfkggfnA6PVqaK8npaMaBV8tKWZgGXmH3IRgMoBzEONZJftj3GSnPZMa-
TEN3z5ykA0vEf5HdiM2x3qgqcYuahFWlZwXPmkq0MhT8Kv39JZ7VbBTXpTbHE4JZBGMeWCqOyagZoBi-
qaM/2qEuXDiwRf6KU6NrfR20Ho78Py0aDMS/4NM1xU8vg3UYjpdAYjb028oM5KRhnnMsgXeU0RqOBoZdEV-
CbS94BKOnAZfOJLuxdSzrGoe/chWN0JKB/YS3V8n0klLnNfXlo4n6O2ucC6+wQ1FWTgsCXpOWjP7c5pwSwPiz-
ZMnV8tDSRNSuPS+T/G3bOBy79IVEypbrTaA2/Yj9rfKnFacKtmoopHZk66qZobmo-
TODZ7u3lOR4DpVlcgzVCCXPi1YEs1mHH0ubaeTAjEzCfPl9vmXk2zgGpEUd9XvbkFmbZC+MSrte-
FLw799Ff8H/APwHwfHKWnvbIcIAAAAASUVORK5CYII="
}
Imagen QR Dinámico ASCII

7.4. Ejemplo de formato TLV EMVCo
0002
01
0102
11
0216
40***********261
0416
50***********261
2636
0032c455512a6bd946fb8c6ef42dc386e57b
5204
5499
5303
604
5802
PE
5920
UNIVERSE NUTRITION D
6004
LIMA
6304
482E

8. Integración API QR Batch
8.1. Detalle del servicio Generador de QRs Batch
API encargado de la generación de QR en Batch desde un archivo INBOUND zipeado en Base64
URLs Servicios
QA https://apitestenv.vnforapps.com/api.qr.batch/qr/batch
PROD https://provisioning.vnmpos.com/api.qr.batch/qr/batch
Método: POST
HEADERS
Nombre del
Fila Entidad Campo
REQUEST
Nombre del
Fila Campo
Archivo recibido en formato .zip
1 file String Si
codificado en Base64
Valor en ambiente de pruebas: 100
2 origin String Parámetro asignado por Niubiz Si Valor en producción es asignado por
el equipo de integración de Niubiz
Valor en ambiente de pruebas:
438933213
3 merchant String Parámetro asignado por Niubiz Si
Valor en producción será el asignado
por su funcionario.
Número de registro que viajan
4 rows String Si
en el archivo dentro del zip
No debe contener la extensión del ar-
nombre del archivo interno chivo, tener en cuenta que el nombre
5 nameFileProcess String Si
zipeado y la extensión debe respetar el Camel-
Case del archivo original
RESPONSE
Nombre del
Fila Campo
1 statusCode String Token para el consumo de los servicios siguientes Si
Id generado del proceso recibido para la generación del
2 idProcess String Si
Batch
3 description String Successful Si

8.2. Detalle del servicio Status QRs Batch
API encargado de consultar la generación de QR en Batch
URLs Servicios
QA https://apitestenv.vnforapps.com/api.qr.batch/qr/fileStatus
PROD https://provisioning.vnmpos.com/api.qr.batch/qr/fileStatus
Método: POST
HEADERS
Nombre del
Fila Entidad Campo
REQUEST
Nombre del
Fila Campo
Identificador del proceso Batch
1 idProcess String Si
ejecutado
False: para retorna el estado de la
ejecución sin traer el archivo
2 status String Parámetro asignado por Niubiz Si True: para retorna el estado de la eje-
cución pero retorna el archivo el for-
mato .zip encoding Base64
RESPONSE
Nombre del
Fila Campo
Token para el consumo de los ser-
1 statusCode String Si 0
vicios siguientes
2 description String Descripción de la ejecución Si Archivo procesado correctamente
3 idProcess String Identificador del proceso Si
DONE
4 status String Estado de la ejecución Si PENDING
FORMAT ERROR
5 merchant String Código de comercio Si
Archivo en formato zip con encoding
6 fileResponse String Archivo en base64 No
Base64
Nombre del archivo original que
7 nameFileProcess String Si
viene en el zip

8.3. Formato de archivos Batch
A continuación se detalla el contenido de los archivos INBOUND / OUTBOUND para el proceso en Batch.
• El archivo INBOUND debe manejar las siguientes posiciones y usa un formato TXT, para ser enviado
luego comprimido como .zip
• El archivo TXT debe dejar un salto de línea al final
• El separador entre cada valor será “|” (Palote)
• El formato del nombre del archivo TXT y zip debe ser:
INBOUND_{{codigocomercio}}_{{ddmmyyyyhhii}}, como por ejemplo:
INBOUND_438933213_260520200845
NRO. POSICION CAMPO VALOR

POSICION 1 TIPO DE QR Valor fijo DYNAMIC
POSICION 2 IDC Identificador del Cliente, este será retornado en el archivo OUT-
BOUND
POSICION 3 CURRENCY Valor fijo 604
POSICION 4 MONTO Decimal (10,2)
POSICION 5 FECHA DE VENCIMIENTO Hay que considerar que la fecha de vencimiento en el QR debe
(ddmmyyyy) tener como mínimo un día adicional.
P.e. Si la fecha de vencimiento es 06/09/2019, en el QR debe ir

07/09/2019 debido a que nosotros validamos hasta las 00:00 ho-
ras del día.
POSICION 6 DATOS ADICIONALES Estructura:
<CAMPO: VALOR>#<CAMPO: VALOR>#<CAMPO: VALOR>
Aquí se agregan los valores necesarios para informar la notifica-

ción de pago del recibo.
Los mismo serán retornados como campo:valor en la sección da-

taMap del response Callback, sección 9
• Archivo OUTBOUND maneja las siguientes posiciones y es retornado dentro de un zip en formato TXT
• Retorna con el formato de nombre OUTBOUND{{ddmmyyyyhhii}}
NRO. POSICION CAMPO VALOR

POSICION 1 IDC Identificador del Cliente
POSICION 2 File Base64

8.4. Ejemplo Trama de Envío de Batch QR
Request
{
"file": "UEsDBBQAAAAIAOiYtVAgcWOZTAAAAGoAAAAiAAAASU5CT1VORF80Mzg5MzMyMTNfMjYwN-
TIwMjAwODQ1LnR4dHOJ9HP09XSuMTQ2MTczMjGsMTMwqTEy1DM0qDE0MjQyMjAyqClKTc5MyrcyNDA1Njc1M+XlckHSZGlqYQrRZ
KRnhFWThZGFkREvFwBQSwECFAAUAAAACADomLVQIHFjmUwAAABqAAAAIgAA-
AAAAAAABACAAAAAAAAAASU5CT1VORF80Mzg5MzMyMTNfMjYwNTIwMjAwODQ1LnR4dFBLBQYAAAAAAQABAFAAAACMAAAAA
AA=",
"origin": "10",
"merchant": "438933213",
"rows": "2",
"nameFileProcess":"INBOUND_438933213_260520200845"
}
Response
{
"statusCode": "0",
"idProcess": "8a21a7fe-8072-4110-84ad-a2a2ec3bd815",
"description": "Successful"
}
8.5. Consulta Status de Batch QR
Request
{
"status":"true"
}
Response
{
"statusCode": "0",
"description": "Archivo procesado correctamente",
"status": "DONE",
"merchant": "438933213",
"fileResponse": "{{file}}”
"nameFileProcess": "INBOUND_438933213_260520200845"
}
8.6. Diccionario de Errores

A continuación se describe el diccionario de errores que puede aparecer al momento de la generación
de los QRs
Código Mensaje Descripción
00 Successful / Done Archivo recibido correctamente
El archivo presenta error de codificación o no está
FORMAT ERROR
01 siendo enviado en el formato correspondiente
El archivo presenta error de codificación o no está
Formato de Archivo invalido
02 siendo enviado en el formato correspondiente
05 ERROR PROCESS Error durante la ejecución del archivo

9. Integración API RSCA Callback
Si el comercio se encuentra integrado a las APIs para la generación de los QR, deberá disponibilizar un servi-
cio Callback para recibir las notificaciones de Pago de los QR Dinámicos o estáticos:
• Al ser Niubiz quien tiene que ser la integración hacia el servicio del cliente, este último se encargará de
proporcionar y asegurar que el canal de transporte sea seguro.
• Niubiz se encargará de dar de alta el nuevo flujo Callback del comercio para el codigo de comercio QR
en producción.
• El comercio tendrá la responsabilidad de restringir las IPs de los ambientes correspondientes.

• El comercio brindará un correo para ser notificado en caso su servicio se encuentre inactivo y no ten-
gamos respuesta.
Desarrollo:
35.153.17.226
Producción:
52.207.94.42 / 52.54.136.111 / 18.232.138.252 / 3.86.214.217
9.1. Flujo de Callback
RESPONSE
Fila Entidad Nombre del Campo Oblig. Tipo Descripcion
1 N/A purchaseNumber Si String [10] Identificador de la billetera electrónica
Si Decimal
2 N/A transactionAmount Monto de la transacción
[10,2]
3 N/A transactionCountry No String[2] tiempo de procesamiento
4 N/A transactionCurrency Si String [3] Codigo de la moneda: 604 / 840
5 N/A authorizationCode Si String [6] Código de autorización del banco

6 N/A authorizationStatus Si String Estado de la autorización del banco
7 N/A actionCode Si String [3] Código de acción de autorización Niubiz
8 N/A actionDescription Si String descripción de código de acción Niubiz
9 N/A transactionDate Si String fecha de transacción
10 N/A transactionId Si String [15] Identificador de la transacción Niubiz
11 N/A tagId Si String [32] Identificador del QR
N/A Si Identificador de la transacción para anu-
12 transactionIdCore String [36]
lación
13 N/A maskCard Si String [16] número de tarjeta enmascarada
14 N/A wallet Si String [10] Nombre de la Billetera
N/A No Identificador único del comercio al crear
15 idc String [15]
el QR Dinámico
N/A No Datos adicionales enviados al momento
16 additionalData Text
de crear el QR
17 dataMap Campo No String additionalData desagregado
18 dataMap valor No String additionalData desagregado
NOTA: Niubiz puede agregar campos adicionales a la trama ya definida en un futuro según la necesidad
del producto, el comercio debe contemplar en su desarrollo interpretar sólo los campos que crea con-
veniente, para evitar incidentes más adelante.
9.2. Ejemplo de trama RSCA

Trama Propuesta a enviar
{
"purchaseNumber":"9566750767",
"transactionAmount": "56.85",
"transactionCountry" : "PE",
"transactionCurrency": "604",
"authorizationCode": "001539",
"authorizationStatus": "Autorized",
"actionCode": "000",
"actionDescription" : "Aprobado y completado con exito.",
"transactionDate": "18/11/2019 15:08",
"tagId": "40aabd0fbd814e458ea7f536164a5382",
"transactionId" : "993201480086855",
"transactionIdCore" : "aabd0-fbd814e4-58ea7f53-6164a-5382",
"maskCard" : "426398******9299",
"wallet": "Niubiz",
"idc": "210254789",
"additionalData": "campo1:valor1#campo2:valor2",
"dataMap": {
"campo1": "valor1",
"campo2": "valor2"
}
}

10. Integración APIs Consulta Transacciones
10.1. Detalle del servicio de obtener transacción
Este servicio será utilizado únicamente por el comercio para poder consultar las transacciones que han sido
notificadas por un servicio Callback previamente, expuesto por el cliente.
Tener en cuenta que el comercio tiene acceso a la vista de las transacciones a través del BackOffice, donde
también puede realizar la acción de ver una transacción pero de forma manual
API encargado de consultar una transacción QR
URLs Servicios
QA https://apitestenv.vnforapps.com/api.qr.manager/v1/qr/queryTransaction/{transactionIdCore}
PROD https://apiprod.vnforapps.com/api.qr.manager/v1/qr/queryTransaction/{transactionIdCore}
Método: GET
Postman: https://www.getpostman.com/collections/49517f16d903ce66556a
HEADERS
Nombre del
Fila Entidad Campo
REQUEST
Fila Nombre del Campo Tipo Descripción Mandatorio Valor
Este campo es el obtenido del campo
1 transactionIdCore String Identificador de la transacción Si transactionIdCore del servicio Call-
back integrado en el punto 8
RESPONSE
1 transactionId String Identificador de la transacción Si
2 tagId String Identificador del QR procesado Si
3 merchantId String Código del comercio Si
4 broker String Usuario interno del QR No
Dispositivo desde donde se realiza
5 device String No
la modificación del QR
6 amount String Monto de Pago Si
7 operationNumber String Código de autorización del emisor Si
Numero de operación generado
8 purchaseNumber String Si
por la billetera
9 cardNumber String Tarjeta enmascarada Si

9 cardType String Marca No
10 fechaHoraTransaction String Fecha y hora de Pago Si Formato: 2019-10-21 17:56:48.0
11 fechaHoraVoid String Fecha y hora de la anulación No
12 fechaHoraClosing String Fecha y hora del cierre No
TP = Transacción procesada
13 status String Estado de Pago No
TA = Transacción Anulada
VISANET
14 flow String Origen de la creación del QR No
VENDEMAS
15 currency String Moneda Si 0604 / 604
10.2. Ejemplo de la trama a enviar

Request
https://apitestenv.vnforapps.com/api.qr.manager/v1/qr/queryTransaction/62dca019-0d3c-4819-a3fb-9a0bf2078c6d
Response
{
"codeResponse": 0,
"transactions": {
"transactionId": "62dca019-0d3c-4819-a3fb-9a0bf2078c6d",
"tagId": "0e00452b193b4bb8826f2af287a79d46",
"merchantId": "438933213",
"broker": "USERQRPRD",
"device": null,
"amount": "190.00",
"operationNumber": "173850",
"purchaseNumber": 501000030,
"cardNumber": "455147******5511",
"cardType": null,
"fechaHoraTransaction": "2019-10-21 17:56:48.0",
"fechaHoraVoid": null,
"fechaHoraClosing": null,
"status": "TP",
"flow": "VISANET",
"currency": "0604"
},
}

10.3. Detalle del servicio de consultar transacciones por fecha
Este servicio será utilizado únicamente por el comercio para poder consultar las transacciones por su código
de comercio y determinado rango de fechas
también puede realizar la acción de ver un reporte manual por rango de fechas
URLs Servicios
QA https://apitestenv.vnforapps.com/api.qr.manager/v1/qr/transactionQuery/{CodigoComercio}
PROD https://apiprod.vnforapps.com/api.qr.manager/v1/qr/transactionQuery/{CodigoComercio}
Método: POST
HEADERS
Nombre del
Fila Entidad Campo
REQUEST
1 fechaInicio String Fecha de inicio de la transacción Si Formato: yyyy-mm-dd
2 fechaFin String Fecha fin de la transacción Si Formato: yyyy-mm-dd
RESPONSE
1 transactionId String Identificador de la transacción Si
2 tagId String Identificador del QR procesado Si
3 merchantId String Código del comercio Si
4 broker String Usuario interno del QR No
Dispositivo desde donde se realiza
5 device String No
la modificación del QR
6 amount String Monto de Pago Si
7 operationNumber String Código de autorización del emisor Si
Numero de operación generado
8 purchaseNumber String Si
por la billetera
9 cardNumber String Tarjeta enmascarada Si
9 cardType String Marca No
10 fechaHoraTransaction String Fecha y hora de Pago Si Formato: 2019-10-21 17:56:48.0
11 fechaHoraVoid String Fecha y hora de la anulación No
12 fechaHoraClosing String Fecha y hora del cierre No
13 status String Estado de Pago No TP = Transacción procesada

TA = Transacción Anulada
VISANET
14 flow String Origen de la creación del QR No
VENDEMAS
15 currency String Moneda Si 0604 / 604

Request
https://apitestenv.vnforapps.com/api.qr.manager/v1/qr/transactionQuery/438933213
{
"fechaInicio": "2019-10-21",
"fechaFin": "2019-10-21"
}
Response
{
"codeResponse": 0,
"transactions": [
{
"transactionId": "62dca019-0d3c-4819-a3fb-9a0bf2078c6d",
"tagId": "0e00452b193b4bb8826f2af287a79d46",
"merchantId": "438933213",
"device": null,
"amount": "190.00",
"cardNumber": "455147******5511",
"cardType": null,
"status": "TP",
"flow": "VISANET",
"currency": "0604"
}, {
"transactionId": "d59c7654-3835-4d91-8cf3-6bfac09e6a1d",
"tagId": "53710953aac34c4e9d7fca0ec21cea6b",
"merchantId": "438933213",
"device": null,
"amount": "200.00",
"cardNumber": "455787******5224",
"cardType": null,
"status": "TP",
"flow": "VISANET",
"currency": "0604"
}
],
}

11. Integración API Void
11.1. Detalle del servicio de anulación de transacción
Este servicio de anulación será utilizado únicamente por el comercio para poder anular una transacción que ha
sido notificada por un callback previamente.
también puede realizar la acción de anular una transacción pero de forma manual.
API encargado de anular una transacción QR
URLs Servicios
QA https://apitestenv.vnforapps.com/api.qr.manager/v1/qr/void
PROD https://apiprod.vnforapps.com/api.qr.manager/v1/qr/void
Método: POST
HEADERS
Nombre del
Fila Entidad Campo
REQUEST
Este campo es el obtenido del campo
1 transactionId String Identificador de la transacción Si transactionIdCore del servicio Call-
back integrado en el punto 8
Indicador externo desde donde
2 externalTransactionId String se hace la invocación de la Si Identificador del sistema origen
transacción
comment String Motivo de la anulación Si
RESPONSE
Nombre del
Fila Campo
1 codeResponse String Código de respuesta Si 0
2 httpCode String Código de respuesta http Si 200
3 description String Descripción de la ejecución Si Successful

Request
{
"transactionId": "39b31b02-3530-4a66-a6ae-48c392802fa4",
"externalTransactionId": "2985698556",
"comment":"TEST"
}
Response
{
"codeResponse": 0,
"httpCode": 200,

12. Consulta de Deuda
12.1. Detalle del servicio de consulta de deuda
Este servicio deberá ser expuesto por el comercio y tiene como finalidad consultar el estado del pago
asociado al producto o servicio a pagar, en caso se haya pagado por otro canal físico o digital.
A continuación la estructura que debe aceptar el comercio por parte del request con método POST
NOTA: Niubiz puede agregar campos adicionales a la trama ya definida en un futuro según la
necesidad del producto, el comercio debe contemplar en su desarrollo interpretar sólo los cam-
pos que crea conveniente, para evitar incidentes más adelante.
REQUEST
Fila Nombre del Campo Tipo Descripción Req Valor
1 transactionAmount String [10] Monto del QR Si
2 transactionCurrency String [100] Codigo de la moneda Si
3 tagId String [100] Identificador único del QR Si
Identificador único del cliente enviado en el
archivo Batch para el caso de Billpayments
en la posición 2
Identificador único del cliente enviado en el

request al crear el QR para el caso de QR in-
4 idc String Si
tegrado.
{
"name": "idc",
"value": "1123"
}
Datos adicionales enviado en el campo
“additionalData” al crear el QR en línea.
5 dataMap Object Si
Datos adicionales enviado en la Posición 6
al crear el QR en Batch
Body
Nombre del
Fila Campo
1 codeResponse String Codigo de respuesta Si 0000=Pendiente de pago
2 messageResponse String Mensaje de respuesta Si 0001=Pagado
Descripcion en caso error al
3 descriptionError String No
momento de la recepción

12.2. Ejemplo de trama consulta de deuda
Request
{
"transactionAmount": "15.3",
"transactionCurrency": "604",
"tagId": "fd8eb3c799ee4ed4b369d19df777f38a",
"idc": "995555",
"dataMap": {
"campo1": "valor1",
"campo2": "valor2",
"campo3": "valor3",
Response
{
"codeResponse": “0000”,
"messageResponse": “Con pago pendiente”,
"descriptionError": ""

Guia de Integracion QR Manager v1.4.2

Cargado por

Información del documento

Derechos de autor

Formatos disponibles

Compartir este documento

Compartir o incrustar documentos

Opciones para compartir

¿Le pareció útil este documento?

¿Este contenido es inapropiado?

Copyright:

Formatos disponibles

Guia de Integracion QR Manager v1.4.2

Cargado por

Copyright:

Formatos disponibles

Soluciones Corporativas

Guía de Integración – QR Manager

Último cambio al documento: 26 Mayo 2020

Confidencial – Niubiz Página 2 de 34

Confidencial – Niubiz Página 3 de 34

1.2. Historia de cambios

Fecha de revisión Autor Resumen de cambios Versión

Nombre Rol Fecha de aprobación

Este documento ha sido distribuido a:

Revisor Rol Requerido

Confidencial – Niubiz Página 4 de 34

Confidencial – Niubiz Página 5 de 34

El documento técnico define el contexto de la implementación de la integración completa con el autorizador

2.3. Público objetivo

2.4. Documentos relacionados

Título del Documento Autor Nombre del Documento Ubicación del

Confidencial – Niubiz Página 6 de 34

El comercio puede disponer de dos tipos de QR:

Confidencial – Niubiz Página 7 de 34

3.1. Diagrama Técnico

Confidencial – Niubiz Página 8 de 34

Confidencial – Niubiz Página 9 de 34

En caso de algún cambio, Niubiz lo notificará.

Confidencial – Niubiz Página 10 de 34

En caso de algún cambio, Niubiz lo notificará.

Confidencial – Niubiz Página 11 de 34

Código Descripción del error

Credenciales del Ambiente de Integración

Confidencial – Niubiz Página 12 de 34

Confidencial – Niubiz Página 13 de 34

Confidencial – Niubiz Página 14 de 34

Confidencial – Niubiz Página 15 de 34

Código Descripción del error

7.2. Ejemplo de trama QR Estático

Confidencial – Niubiz Página 16 de 34

Confidencial – Niubiz Página 17 de 34

Confidencial – Niubiz Página 18 de 34

Imagen QR Dinámico ASCII

Confidencial – Niubiz Página 19 de 34

Confidencial – Niubiz Página 20 de 34

Confidencial – Niubiz Página 21 de 34

Confidencial – Niubiz Página 22 de 34

NRO. POSICION CAMPO VALOR

P.e. Si la fecha de vencimiento es 06/09/2019, en el QR debe ir

<CAMPO: VALOR>#<CAMPO: VALOR>#<CAMPO: VALOR>

Aquí se agregan los valores necesarios para informar la notifica-

Los mismo serán retornados como campo:valor en la sección da-

NRO. POSICION CAMPO VALOR

Confidencial – Niubiz Página 23 de 34

8.5. Consulta Status de Batch QR

8.6. Diccionario de Errores

Confidencial – Niubiz Página 24 de 34

• El comercio tendrá la responsabilidad de restringir las IPs de los ambientes correspondientes.

9.1. Flujo de Callback

Confidencial – Niubiz Página 25 de 34

9.2. Ejemplo de trama RSCA

Confidencial – Niubiz Página 26 de 34

Confidencial – Niubiz Página 27 de 34

10.2. Ejemplo de la trama a enviar

Confidencial – Niubiz Página 28 de 34

Confidencial – Niubiz Página 29 de 34

10.4. Ejemplo de la trama a enviar

Confidencial – Niubiz Página 30 de 34

Confidencial – Niubiz Página 31 de 34