Consultas

#


Api Pagos Api Pagos

Usa las API Consultas para complementar tu integración a nuestras soluciones.
Para comenzar a disfrutar los beneficios de API Consultas, sigue los siguientes pasos:


Pasos que debes seguir Detalle de cada paso
Paso 1. ¿Ya utilizas alguna solución de Niubiz? Asegúrate de ya contar con alguna de nuestras soluciones como Pago Web, Pago App, Pago Programado o Telepago.
Paso 2. Revisa la información técnica En esta web podrás encontrar todos los recursos necesarios para iniciar la integración.
Paso 3. Certifica tu integración y empieza a vender! Luego de culminar la certificación y puesta en producción, estás listo para empezar a vender!

Flujo de uso de las API #

Aquí podrás visualizar el flujo de uso de cada de las API que se encuentran en esta sección.

Flujo Consulta Flujo Consulta

  • Por temas de seguridad, es necesario crear un token de acceso con las credenciales (usuario y password) entregadas por Niubiz (1a) el cual permitirá la comunicación con las diferentes APIs. Para ello, será necesario consumir la API de seguridad para poder encriptar las credenciales.

  • Para poder realizar la consulta de las ventas (2a) es necesario el token de acceso y otros parámetros (criterio de búsqueda, código de comercio, valor del criterio de búsqueda).

API de Seguridad #


A. Descripción y consideraciones

Se utiliza el API de seguridad para la generación del token de acceso que le permitirá la comunicación con las diferentes APIs. Cabe indicar que este token de acceso tiene un tiempo de vigencia para poder ser utilizado. Si el token de acceso llega a caducar se debe generar uno nuevo.

El comercio afiliado debe asegurar que su integración (desarrollo) sea lo más segura posible aplicando las medidas preventivas que considere necesario.

Todas las invocaciones a las APIs (servicios backend) de Niubiz tienen que ser realizadas host to host.



B. Endpoint

Ambiente URL de API
Testing https://apisandbox.vnforappstest.com/api.security/v1/security
Producción https://apiprod.vnforapps.com/api.security/v1/security


C. Request y Casos:

  C.1 Tabla de campos

Campo Tipo Longitud Obligatorio Descripción
HEADER
userName Texto Max 100 SI Usuario compartido con el comercio para la integración
password Texto Max 100 SI Contraseña compartida con el comercio para la integración


  C.2 Trama de ejemplo:

  • Request

GET /api.security/v1/security HTTP/1.1

Host: apisandbox.vnforappstest.com

Authorization: Basic Z2lhbmNhZ2FsbGFyZG9AZ21haWwuY29tOkF2MyR0cnV6

(*) Authorization: Basic EncodeBase64(“userName” + “:” + “password”)



D. Lenguajes


  • Node
  • JavaScript
  • Python

const request = require('request');

var userName = "{{userName}}"

var password = "{{password}}"

var authorization = new Buffer(userName + ":" + password).toString("base64")

const options = {

method: 'GET',

url: 'https://apisandbox.vnforappstest.com/api.security/v1/security',

headers: {

'Authorization': "Basic " + authorization,

accept: 'application/json',

'content-type': 'application/json'

},

};

request(options, function (error, response, body) {

if (error) throw new Error(error);

console.log(body);

});



E. Response

  E.1 Tabla de campos

Campo Tipo Longitud Descripción
TRAMA EXITOSA: 201
accessToken text Max 1000 Token de acceso generado con la API
TRAMA ERRÓNEA: 401
description text Max 100 Descripción relacionada al error. Este error se presenta cuando las credenciales no son válidas


  E.2 Trama de ejemplo:

  • Caso 201
  • Caso 401

Status Code 201 Created

Content-Type: text/plain

eyJraWQiOiJmWk1tV3pZR0RBckxHektvalNCK2w3SjFhMnNPXC9zQnNwOTlNNmNuM3F5M D0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJkMTlhM2I0Zi01NzYxLTRlYTEtYjBmYS1i NWNiNjU5OWQ5NWQiLCJjb2duaXRvOmdyb3VwcyI6WyJjdXN0b2RpbyJdLCJldmVudF9p ZCI6ImM2OTZmZjVkLTZjOTctNDE4NC05MGIxLTA5NjM2MWY4M2E2ZSIsInRva2VuX3Vz ZSI6ImFjY2VzcyIsInNjb3BlIjoiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4i LCJhdXRoX3RpbWUiOjE2MDIxMTM4NzksImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlk cC51cy1lYXN0LTEuYW1hem9uYXdzLmNvbVwvdXMtZWFzdC0xXzJjSjFTZTFmSSIsImV4 cCI6MTYwMjExNzQ3OSwiaWF0IjoxNjAyMTEzODc5LCJqdGkiOiJiOTVmOGU0ZS1kZGE4 LTRkZmUtOTc0NC1kOGQwZGEyMDFlMzMiLCJjbGllbnRfaWQiOiIxMGx2MDYxN281ZGlj NTFlYnNucWVpaWpiNyIsInVzZXJuYW1lIjoiZ2lhbmNhZ2FsbGFyZG9AZ21haWwuY29t In0.GrO2XLoMnChN3Dg6H8G7LC3ZY4O_c1-DwvRYHCx8iiDqprFMK7jU43vo6W4ILNqP _QA1sDoEQaD9HJJ7iLfVBojh1tgiFyzFzkX4T3m63eHRSFfIZAToTGYOQoeZchsYb3UA ffvrzR1JlUPjwf3U1YRfBEu8ueIR6_OUMZdXC8TLS3pqEpXnPr6S-_bndpFRs5wZpt0B PSJ4OnhM2AYh6pqFucjL9nsPmIaujJQVwdR8oNcrfeFuIv5t55H_DRDpQCSYstac1nFS m00P3EMdbOX6Lh8dTU5dBOXe17Bfh7mDEP-FnF_J47COVFB_sYh7JXyePfK6kKTlSeV0 Ev0pew

API de Consulta #


A. Descripción

Este documento describe los lineamientos generales a los proveedores encargados de desarrollo, para realizar la consulta de una venta a través del API de Consulta.

El comercio afiliado debe asegurar que su integración (desarrollo) sea lo más segura posible aplicando las medidas preventivas que considere necesario.

Todas las invocaciones a las APIs (servicios backend) de Niubiz tienen que ser realizadas host to host.



B. Endpoint

Ambiente URL API
Testing https://apisandbox.vnforappstest.com/api.authorization/v3/retrieve/{queryType}/{merchantId}/{identifier}
Producción https://apiprod.vnforapps.com/api.authorization/v3/retrieve/{queryType}/{merchantId}/{identifier}


C. Request y casos

  B.1 Tabla de parámetros

Campo Tipo Longitud Obligatorio Descripción
HEADER
accessToken text Max 1000 SI Token generado con el API de Seguridad
URL
queryType text Max 100 SI Criterio por el cual se realiza la búsqueda – external: La búsqueda se realiza por el campo externalTransactionId.
purchase: La búsqueda se realiza por el campo purchaseNumber.
transaction: La búsqueda se realiza por el campo transactionId.
merchantId text Max 100 SI Código de comercio Niubiz
identifier text Max 100 SI Valor correspondiente para el campo queryType


  C.2 Trama de ejemplo:

  • Request

GET /api.authorization/v3/retrieve/external/341198210/3ac183ca-06a6-4438-80ad-aa82e88c14697 HTTP/1.1

Host: apisandbox.vnforappstest.com

Authorization: eyJraWQiOiJmWk1tV3pZR0RBckxHektvalNCK2w3SjFhMnNPXC9z QnNwOTlNNmNuM3F5MD0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJjNTAxNjYyOS04Z jc2LTQ1M2QtYjhlNC01MGJjZDI5YjI2NTAiLCJldmVudF9pZCI6IjA0Mjc1ODJhLWE 0MzEtNGVlNy05NzVhLWRmYTI4OGI1YjVkNyIsInRva2VuX3VzZSI6ImFjY2VzcyIsI nNjb3BlIjoiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWU iOjE2MDI3MDUwNjUsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC51cy1lYXN0L TEuYW1hem9uYXdzLmNvbVwvdXMtZWFzdC0xXzJjSjFTZTFmSSIsImV4cCI6MTYwMjc wODY2NSwiaWF0IjoxNjAyNzA1MDY1LCJqdGkiOiI4NzM1YjM3ZS02OWU4LTQ0ZDUtO DRkMS01YTcyYWRiNmU3N2MiLCJjbGllbnRfaWQiOiIxMGx2MDYxN281ZGljNTFlYnN ucWVpaWpiNyIsInVzZXJuYW1lIjoiaW50ZWdyYWNpb25lcy52aXNhbmV0QG5lY29tc Gx1cy5jb20ifQ.JUAGPxDroOt-I1PcWBviXPUIn_RlDUDNquYnnBFVTOkq44UEMjJ



  C.3 Lenguajes:


  • Node
  • JavaScript
  • Python

const request = require('request');

const options = {

method: 'GET',

url: 'https://apisandbox.vnforappstest.com/api.authorization/v3/retrieve/queryType/merchantId/identifier',

headers: {

var authorization = new Buffer(userName + ":" + password).toString("base64")

'Authorization': '{{accessToken}}',

accept: 'application/json',

'content-type': 'application/json'

}

};

request(options, function (error, response, body) {

if (error) throw new Error(error);

console.log(body);

});



D. Response:

  D.1 Tabla de parámetros:

Campo Tipo Longitud Descripción
TRAMA EXITOSA: 200
accessToken text Max 1000 Token de acceso generado con la API
header json Entidad que representa el encabezado de respuesta a la petición
header.ecoreTransactionUUID string($uuid) Identificador único de transacción para la plataforma
header.ecoreTransactionDate string Fecha de la operación expresada en formato UNIX TimeStamp
header.millis integer($int32) Tiempo de ejecución de la operación
fulfillment json Entidad que representa información complementaria al pedido
fulfillment.channel string Canal desde donde se originó la operación.
– web: Si son operaciones realizadas con el botón de pago web
fulfillment.merchantId string max 9 Código de comercio Niubiz al cual pertenece la transacción
fulfillment.terminalId string max 8 Número de terminal asociado a la transacción
fulfillment.captureType string max 6 Tipo de captura en el canal. Siempre es el valor manual
fulfillment.countable boolean Indica si la venta es contable true o no contable false
fulfillment.fastPayment boolean Indica si la venta es pago rápido true o no es pago rápido false
fulfillment.signature string($uuid) Código único generado por el sistema Niubiz al momento de la venta
order json Entidad que representa la información del pedido
order.purchaseNumber string max 12 Número de pedido generado por el comercio
order.amount number($double) Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
order.currency string max 3 Código de moneda en la que se ejecuta la transacción
– PEN
– USD
order.externalTransactionId string($uuid) Identificador único de transacción enviado por el comercio
order.authorizedAmount number($double) Importe del pedido confirmado. Precisión hasta 8 valores enteros con 2 decimales
order.authorizationCode string max 6 Código de autorización asignado a la aprobación de la transacción por la entidad resolutora
order.actionCode string max 3 Código que identifica la acción a tomar o tomada, así como la razón de la misma. Define la respuesta a la petición de autorización realizada
order.status string max 20 Descripción del estado del pedido
– Authorized
Not Authorized
– Confirmed
Not Confirmed
– Verified
– Not Verified
– Voided
– Not Voided
– Reject
– Review
order.traceNumber string max 6 Número asignado para identificar de forma unívoca a la transacción
order.transactionDate string Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
order.transactionId string max 15 Identificador de la transacción asociado a la autorización
dataMap json Entidad que representa información complementaria del pedido
dataMap.TERMINAL string max 8 Código numérico
dataMap.CURRENCY string max 4 Código numérico de moneda en la que se ejecuta la transacción
dataMap.TRANSACTION_DATE string Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
dataMap.ACTION_CODE string max 3 Código que identifica la acción a tomar o tomada, así como la razón de la misma. Define la respuesta a la petición de autorización realizada
dataMap.TRACE_NUMBER string max 6 Número asignado para identificar de forma unívoca a la transacción
dataMap.ECI_DESCRIPTION string max 100 Descripción del código ECI asociado a la autenticación de la transacción
dataMap.ECI string max 2 Código ECI asociado a la autenticación de la transacción
dataMap.CARD string max 16 Número de tarjeta enmascarado usada en la venta
dataMap.MERCHANT string max 9 Código de comercio Niubiz al cual pertenece la transacción
dataMap.STATUS string max 20 Descripción del estado de la transacción
– Authorized
– Not Authorized
– Confirmed
– Not Confirmed
– Verified
– Not Verified
– Voided
– Not Voided
– Reject
– Review
– Confirmed
dataMap.ADQUIRENTE string max 15 Nombre de identificación del adquirente. Identifica el punto donde se origina la transacción
visa
procesos-mc
dataMap.BIN string max 6 Número de BIN de la tarjeta usada en la venta. Son los 6 primeros dígitos de una tarjeta
dataMap.BRAND string max 15 Marca de la tarjeta usada en la venta
visa
– amex
– mastercard
– dinersclub
dataMap.SETTLEMENT string max 20 Indica si la operación está o no está liquidada
– Not Applicable
– Pending
– Automatic
– Completed
dataMap.ACTION_DESCRIPTION string max 100 Texto descriptivo de la autorización o denegación
dataMap.ID_UNICO string max 15 Identificador de la transacción asociado a la autorización
dataMap.AMOUNT number($double) Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
dataMap.AUTHORIZED_AMOUNT number($double) Importe del pedido confirmado. Precisión hasta 8 valores enteros con 2 decimales
dataMap.TRANSACTION_ID string max 15 Identificador de la transacción asociado a la autorización
dataMap.AUTHORIZATION_CODE string max 6 Código de autorización asignado a la aprobación de la transacción por la entidad resolutora
dataMap.QUOTA_NUMBER integer($int32) Número de cuotas en que se realizó la venta
dataMap.QUOTA_AMOUNT number($double) Importe aproximado del valor de cuota. Precisión hasta 8 valores enteros con 2 decimales
dataMap.QUOTA_DEFERRED integer($int32) Indica si el pago en cuotas debe procesarse con pagos en diferido. 0, el pago no se procesa en diferido y 1 o 2, el pago se procesa en diferido
dataMap.QUOTA_NI_PROGRAM integer($int32) Código de programa para cuota sin intereses
dataMap.QUOTA_NI_TYPE integer($int32) Indicador de tipo de cobro para cuotas sin intereses. 0, cobro como porcentaje y 1, cobro como importe
dataMap.QUOTA_NI_AMOUNT number($double) Valor asociado al tipo de cobro para cuotas sin intereses
dataMap.QUOTA_NI_DISCOUNT number($double) Porcentaje de descuento que corresponde al emisor por el programa cuota sin intereses
dataMap.QUOTA_NI_MESSAGE string max 50 Mensaje asociado al cobro para cuota sin intereses
TRAMA EXITOSA: 400
errorCode integer($int32) Código de error de la operación. Siempre es el valor 400
errorMessage string Mensaje de error de la operación
header json Entidad que representa el encabezado de respuesta a la petición
header.ecoreTransactionUUID string($uuid) Identificador único de transacción para la plataforma
header.ecoreTransactionDate string Fecha de la operación expresada en formato UNIX TimeStamp
header.millis integer($int32) Tiempo de ejecución de la operación
data json Entidad que representa información relacionada a errores en la operación realizada
TRAMA EXITOSA: 401
description text max 1000 Descripción relacionada al error. Este error se presenta cuando las credenciales no son válidas


  D.2 Trama de ejemplo:

  • Caso 200
  • Caso 400
  • Caso 401

Status Code 200 OK

Content-Type: application/json

{

 "header": {

  "ecoreTransactionUUID": "d65819ee-a2eb-49dc-a37b-916b1a243f91",

  "ecoreTransactionDate": 1602701623643,

  "millis": 3410

 },

 "fulfillment": {

  "channel": "web",

  "merchantId": "341198210",

  "terminalId": "1",

  "captureType": "manual",

  "countable": false,

  "fastPayment": false,

  "signature": "1353dbd4-e783-4ebb-8476-9c10d97abd07"

 },

 "order": {

  "purchaseNumber": "54321",

  "amount": 100.0,

  "currency": "PEN",

  "externalTransactionId": "d629eeae-b0f0-4b90-a648-aa9e4c1d7182",

  "authorizedAmount": 100.0,

  "authorizationCode": "",

  "actionCode": "180",

  "status": "Not Authorized",

  "traceNumber": "342291",

  "transactionDate": "190529100749",

  "transactionId": ""

 },

 "dataMap": {

  "TERMINAL": "00000001",

  "TRACE_NUMBER": "342291",

  "ECI_DESCRIPTION": "Transaccion no autenticada pero enviada en canal seguro",

  "MERCHANT": "341198210",

  "CARD": "444433******1111",

  "QUOTA_NI_DISCOUNT": "0.00",

  "STATUS": "Not Authorized",

  "ACTION_DESCRIPTION": "Tarjeta no válida",

  "ID_UNICO": "",

  "AMOUNT": "100.00",

  "QUOTA_NUMBER": "0",

  "QUOTA_NI_AMOUNT": "0.00",

  "QUOTA_NI_PROGRAM": "0",

  "AUTHORIZATION_CODE": "",

  "CURRENCY": "0604",

  "TRANSACTION_DATE": "190529100749",

  "ACTION_CODE": "180",

  "BIN": "444433",

  "ECI": "07",

  "BRAND": "visa",

  "QUOTA_NI_TYPE": "0",

  "AUTHORIZED_AMOUNT": "100.00",

  "QUOTA_AMOUNT": "0.00",

  "ADQUIRENTE": "Niubiz",

  "SETTLEMENT": "Not Applicable",

  "TRANSACTION_ID": "",

  "QUOTA_NI_MESSAGE": "",

  "QUOTA_DEFERRED": "0"

 }

}



E. Códigos de Respuesta

Respuesta Descripción
200 Consulta de venta realizada con éxito
400 Error en la consulta de la venta
401 Error relacionado al acceso no autorizado

Data para pruebas #

Te dejamos aquí lo que necesitas para realizar tus pruebas.

Códigos de comercio

Código de comercio Moneda Tipo Liquidación
456879852 Soles Liquidación automática
456879856 Soles Liquidación manual
456879853 Dólares Liquidación automática
456879854 Dólares Liquidación manual
 

Las credenciales que debes utilizar serán las siguientes:

 
Usuario Password
integraciones@niubiz.com.pe _7z3@8fF

Certificación y pase a producción #


A continuación te mostraremos los pasos resumen que debes tener en cuenta para tu Certificación y Pase a Producción.


Revisa y valida el CheckList de Certificación.
Debes contar con un Código de Comercio en producción.
Coordina la fecha de tu Certificación.
  • Código de comercio
  • Datos de la persona que realizará las pruebas de certificación (Nombre, teléfono y correo)
  • 3 fechas tentativas y horarios (L a V de 9am a 6pm)
Coordina tu Pase a Producción.
  • Durante la certificación podrás realizar el pase a producción o programarlo con un tiempo máximo de 5 días útiles.
  • Durante el pase a producción, revisaremos cada uno de lo puntos que se detallan en Pasos para tu Pase a Producción.


¡Luego de culminar la certificación y puesta en producción, estás listo para empezar a vender!


Checklist de certificación


Requisitos obligatorios que debes considerar:


Validar caso exitoso.
  • Debes revisar la trama de respuesta, el código de acción 200 y que el resultado sea el esperado.
Validar caso Fallido.
  • Debes revisar la trama de respuesta, el código de acción 400 y que el resultado sea el esperado (por ejemplo pruebas con tarjetas vencidas o cvv incorrecto).
Términos y Condiciones.
  • Divulgar los términos y condiciones.
  • En la secuencia de las páginas finales antes del checkout, y debe incluir un “clic para aceptar”, una casilla u otro botón de aceptación, o lugar para una firma electrónica, o
  • En la pantalla final de pago cerca del botón “Enviar”.
  • En un pop up o enlace, cuya lectura y aceptación a través de un check box sea obligatoria en la misma página del checkout antes que el tarjetahabiente acepte la compra.
  • Considerar la casilla de aceptación de términos y condiciones no debe de estar premarcardo.


Pasos para el pase a producción:


Considera los siguientes pasos para tu pase a producción:


Validar caso exitoso.
  • Debes revisar la trama de respuesta, el código de acción 200 y que el resultado sea el esperado.
Validar caso Fallido.
  • Debes revisar la trama de respuesta, el código de acción 400 y que el resultado sea el esperado (por ejemplo pruebas con tarjetas vencidas o cvv incorrecto).
Suggest Edit