Pago con cifrado

#

Api Pagos Cifrado Api Pagos Cifrado

Usa las API Pago con cifrado para complementar tu integración a nuestras soluciones.
Para comenzar a disfrutar los beneficios de API Pago con cifrado, 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 de Anulación Individual

API de Seguridad #

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.


A. Endpoint

Ambiente URL de API
Testing https://apitestenv.vnforapps.com/api.security/v2/security/keys
Producción https://apiprod.vnforapps.com/api.security/v2/security/keys


B. Request y Casos

  B.1 Tabla de campos

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


  B.2 Trama de ejemplo:

Request

GET /api.security/v2/security/keys HTTP/1.1

HOST: apitestenv.vnforapps.com

Authorization: Basic Z2lhbmNhZ2FsbGFyZG9AZ21haWwuY29tOkF2MyR0cnV6

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



  B.3 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://apitestenv.vnforapps.com/api.security/v2/security/keys',

 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);

});



C. Response:

  C.1 Tabla de parámetros:

Campo Tipo Longitud Descripción
TRAMA EXITOSA: 200
accessToken string max 1000 Token de acceso generado con la API
refreshToken string max 1000 Token de seguridad secundario generado para poder extender la duración de la sesión del token de seguridad primario
keys array Conjunto de llaves de encriptación generadas para la encriptación de los datos y/o payload en la invocación
keys.token string max 36 Token identificador de la llave de encriptación
keys.baseKey string max 64 Llave de encriptación. El algoritmo de encriptación para la generación de esta llave es AES (Advanced Encryption Standard) de 256 bits
keys.iv string max 32 Vector relacionado a la llave de encriptación
expiresIn integer($int32) Tiempo de duración para la expiración del token de seguridad primario. El valor de este campo se encuentra expresado en segundos
TRAMA ERRONEA: 401
description text max 1000 Descripción relacionada al error. Este error se presenta cuando las credenciales no son válidas


  C.2 Trama de ejemplo:

  • Caso 201
  • Caso 401

Status Code 201 Created

Content-Type: application/json

{

 "accessToken":

 "eyJraWQiOiJmWk1tV3pZR0RBckxHektvalNCK2w3SjFhMnNPXC9zQnNwOTlNN

mNuM3F5MD0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJjNTAxNjYyOS04Zjc2LTQ1M2Q

tYjhlNC01MGJjZDI5YjI2NTAiLCJldmVudF9pZCI6ImFkNGUxNjgyLTllZGEtNGRjNC

1iZTZiLTU4NzAzOTc0OWI2YSIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiY

XdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE2MDQ5MzQ2

ODgsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC51cy1lYXN0LTEuYW1hem9uYXd

zLmNvbVwvdXMtZWFzdC0xXzJjSjFTZTFmSSIsImV4cCI6MTYwNDkzODI4OCwiaWF0Ij

oxNjA0OTM0Njg4LCJqdGkiOiI4NmFiNmVjMC03NDY2LTRlNWYtYTUyYi1kNGJjMTM4Z

TdhYTkiLCJjbGllbnRfaWQiOiIxMGx2MDYxN281ZGljNTFlYnNucWVpaWpiNyIsInVz

ZXJuYW1lIjoiaW50ZWdyYWNpb25lcy52aXNhbmV0QG5lY29tcGx1cy5jb20ifQ.J60a

64dzjpGSM5UjwV1kYU__w7uE4sLJdOVM2vN5h7dv5X3YcUkOe9jpagEIiuCX4Ebe8gO

BJTF95Y3-JABVs7Rhur05-Za_pkqckAWqLgWZuHTXGwSslOxdFL1YNN2XVQUBuLPYYP

n3n8Jz1xDB8qhIkfbsKpSmIRkcWddJ6oAJVYYB5YQFXYYCnZbXlu-5zVfKBPPMS1_Si

2tJuwzRN1TMK4G3I6Yqi83SNkXXpjYeZNhkYDQ_spl2LL7d_1oJC2Z1aj9uZn1Z27yJ

tKnzwVOObqPTPFedHvanq_KT1J-dPnZAtLy02Oxlne_mYE0IxS2Ff7EL_OSAY6ZGQsQ

zew",

 "refreshToken":

 "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAif

Q.IrMMymNHjklHMNPWw20KZLm9C7sqWLDJTsgP5A9jSQp3bRnLsDfkT5_Cz4fKTBy7n

-3lpa44SZ5hzTJVmvlDLrKmgXcZfedTWrk8WDHh4ojHteml7rARgsUsw6LxY07Q_xA0

HeenwCnc2gCwIMKMWmer05Yx74KTmhFGehrh61yhDWA9qmcF0Yx0T3j336u4p8pOYvg

xBzEEVRkw9oBmLkRbblb4BdYqLbvSwvNzVlfvDzwuuEVIC0Ej8EVjMS0qGSfgGzVnkt

_0o7VHVgL7qXhSx_96W4gZIfUa6m-SgYzQ9nXwCWAnqYO1i8C-1hoaCe7hzwe0gH0-X

3xQ0MlOjg.YVFZ90m009D_ZwCX.b7_W_UA2t4sM1g2uHk4cUm6S80KBAm-vVstlP2Ys

JamRM0v7DFol8mSwM7-UqfM6YsDQaH_3HmjaK2nHT-CcAGhaNswtizbeUfpG40qENmX

gZGAWtDAN1HR0hABeT4KD6g0AMnH13TZzO2xHVcZThMCXNqzUbAXN11PjeC-kideFo0

C0T-xNuVyzae7HeYoTBwHDxfYQDaJEwxweUx3Obnu1su8i8D9FdCvd6naUNPkxAvZvi

-3K91sgED4n2Vf2INUz1JtKIkFDtThaOkffTke2CmiJe1-jCg9TsmH1zxPNn27nDWGJ

ThSICRrOKI3ccqPhQZmnNQnGqVyfUWByibS1diYuOZyS4bqeH6NmnELXHTfSrgAqDV_

Ao2pS7Csf9RNBX8PQz_uCaEiwCVWM0kpJexPnItwGfUF0c5UT8GrGLAOHS89UqT3Nfg

k-Y6N9rgg_HWwf7HJw36GkjeokMM52FtHwYVuvRp7ifGeDFwI5eJmFvKtHV-7KrQmLq

8t0XFBuGUaIwDDHf5CkRsM_ftzEJpdoTcupDs28y7E8x2vD2zGnAheCgieXpE7Sbz1S

Czjh2Sw2ATwsNNPipVmr7gYBlZ9CGXbsKbjAxcLe-k5U74a_unblfzifMX2ATQ_X234

yDYIQ-ZfAjq060JpqeuHrStRv-nZRSpJLBZbEIWQ-KoNETD1MheTJ9WOQg7c-_Uybee

9NwEGujSjcFhezrztVI1dOH7Md2VXvdNrhixufXKmVQNuqTQEQA3QMB-GIWHwBY7lL5

zY3QKi44z46lfGMHnZTZ3eG88bYScCAk91aUWPorUvsqoQP_A2xTSn2Y4L2DHoy8_Ju

-qRkyWCZPBVNDVjtLZCNuP7ttW0JJjb0aY6sPTs2JjpKyuI_hgPzUjO7eeyMwm6Iibo

waWOTuMW9uG215Ui00nMcS_Spw_z1-2lBX9nM5kmmArFjVROv29GyBp_0LZ8N15RGDa

ahrth6E8ts2Pi1U-F1ny7T-yuCapqcM-C08QgiW4gubBhi0Sz8tTABf0J3hhIFmZUPr

0IYcV8FwjKyco3BJoMAiNgjlzQkt69iYVBNlxexgsUYdseHazU12nXtuxL0puJDjXmy

TJ4hCj9dSXjBsDmhfnjbG8EAUWSSDIBM6DLc-4dq0bEvmhclrTZj8eswiQ2VfNbhcjy

QmXzyyBh7_CoOT3wnlno9JA6a2rdKiHm4LNouzeX9pxwHYBLwEMLf6MNsx2z4VYEdQR

tKlzh-ieybfoKOULfLirebMd7wOLFIMqcYoz2ODAYwYOXoo10yLVdn6lyyIrJ0fbS4z

Bx62AT4mL7dhSnVd1e2UNlA5w.1K2xbc2Cvzi1LRGNRYWagw",

 "keys": [

  {

   "token": "8f6f5f7c-b770-4f65-bb2c-faf184553a49",

   "baseKey": "403ace4525ca388130892966e2d7688db0211203918fe09f1364c96afbd57ac2",

   "iv": "113819fd346192874bdb8badd721167e"

   },

  {

   "token": "81525f67-fad9-4cfe-bc99-40891dc657e5",

   "baseKey": "a4181d8e7173c28b8108564d12a9607e6c870249cf551a98986895fa3bdeb5d4",

   "iv": "b37b2b2fbed00d9344a092315af1e76e"

  }

 ],

 "expiresIn": 3600

}



D. Códigos de Respuesta

Respuesta Descripción
201 Token de seguridad generado con éxito
401 Error relacionado al acceso no autorizado

API de Autorización con Alcance Cifrado #

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.


A. Endpoint

Ambiente URL de API
Testing https://apitestenv.vnforapps.com/api.authorization/v3/authorization/{product}/{merchantId}
Producción https://apiprod.vnforapps.com/api.authorization/v3/authorization/{product}/{merchantId}


B. Cifrado

En este punto se detallan los parámetros de encriptación del algoritmo AES y los elementos a codificar o encriptar.

   B.1 Parámetros de encriptación

  • Algoritmo de encriptación: AES
  • Modo de encriptación: CBC
  • Relleno: PKCS7
  • Tamaño de la llave: 256 bits
  • Tamaño de bloque: 128 bits
  • Llave: token (se obtiene del API de seguridad) se requiere convertir de string hexadecimal a byte array.
  • Vector de inicialización: iv (se obtiene del API de seguridad) se requiere convertir de string hexadecimal a byte array.

   B.2 Scope (codificación base64)

Request

{

 "scopes": [

  "key": "9be588af-dd65-4ec3-a0c3-7eaff3c2642a",

  "elements": [

   "card.cardNumber",

   "card.cvv2"

  }

 ]

}


Campo Tipo Longitud Obligatorio Descripción
key text max 36 SI Token relacionado a la llave de encriptación a utilizar obtenido en la respuesta del API de Seguridad
elements array SI Referencia a los atributos encriptados en el cuerpo de la consulta


C. Request y Casos

  C.1 Tabla de parámetros

Campo Tipo Longitud Obligatorio Descripción
HEADER
accessToken Text max 1000 SI Token generado con el API de Seguridad
scope Text max 1000 SI JSON codificado en base64 obtenido en el paso de encriptación
URL
product text max 100 SI Identificador de producto
– ecommerce
– pospc
– recurrent
merchantId text max 100 SI Código de comercio
BODY
channel string SI Canal desde donde se originó la operación.
– web Si son operaciones realizadas con el botón de pago web
– mobile Si son operaciones realizadas con la librería de pago app
– pasarela Si son operaciones realizadas con la API de autorización para el producto comercio electrónico
– callcenter Si son operaciones realizadas con la API de autorización para el producto telepago
– recurrent Si son operaciones realizadas con la API de autorización para el producto pago programado
captureType string SI Tipo de captura en el canal. Siempre es el valor manual
countable boolean SI Tipo de venta a realizar. Siempre es el valor true
order json SI Entidad que representa la información del pedido
order.tokenId string max 32 NO Id del token de transacción obtenido en la respuesta a la validación antifraude o del formulario de pago.
(*) No es obligatorio cuando el canal es recurrente
order.productId string max 10 NO Código del producto para la afiliación.
(*) No es obligatorio cuando el canal es recurrente
order.purchase
Number
string max 12 SI Número de pedido generado por el comercio
order.amount number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
order.installment integer($int32) NO Número de cuotas en que se realizará el pago
order.currency string max 3 SI Código de moneda en la que se ejecuta la transacción
– PEN
– USD
order.external
TransactionId
string($uuid) NO Id único de la transacción enviado por el comercio
card json SI Entidad que representa información de la tarjeta
card.cardNumber string SI Número de la tarjeta encriptado con la llave token y vector iv obtenidos en la respuesta del API de Seguridad
card.expirationMonth integer($int32) SI Mes de expiración
card.expirationYear integer($int32) SI Año de expiración
card.cvv2 string SI Número de CVV2 de la tarjeta encriptado con la llave token y vector iv obtenidos en la respuesta del API de Seguridad
cardHolder json NO Entidad que representa la información del tarjetahabiente
cardHolder.
firstName
string max 25 NO Nombres del tarjetahabiente
cardHolder.
lastName
string max 50 NO Apellidos del tarjetahabiente
cardHolder.
email
string max 35 SI Correo electrónico del tarjetahabiente
cardHolder.
phoneNumber
string max 10 NO Teléfono del tarjetahabiente
cardHolder.
documentType
string max 1 NO Tipo de documento del tarjetahabiente
– 0 DNI
– 1 Carnet extranjería
– 2 Pasaporte
(*) No es obligatorio cuando el canal es recurrente
cardHolder.
documentNumber
string max 12 NO Número de documento del tarjetahabiente
(*) No es obligatorio cuando el canal es recurrente
sponsored json NO Entidad que representa información relacionada al comercio hijo.
(*) No es obligatorio cuando el canal es recurrente
sponsored json NO Entidad que representa información relacionada al comercio hijo.
(*) Es de ingreso obligatorio si se está integrando un facilitador de pagos
sponsored.merchant
Id
string max 9 NO Código de comercio hijo
sponsored.name string max 25 NO Nombre de comercio hijo
sponsored.mcci string max 4 NO MCC internacional de comercio hijo
sponsored.address string max 50 NO Dirección de comercio hijo
sponsored.
phoneNumber
string max 10 NO Teléfono de comercio hijo
authentication json NO Entidad que representa información relacionada a la autenticación en Verified by Visa
(*) No es obligatorio cuando el canal es recurrente
authentication.eci string max 2 NO Valor ECI del proceso de validación de la marca
– 05 Transacción autenticada
– 06 Comercio intentó autenticación, pero TH no está participando
authentication.xid string max 20 NO Valor XID del proceso de validación de la marca
authentication.cavv string max 40 NO Valor CAVV del proceso de validación de la marca
recurrence json NO Entidad que representa información relacionada a la afiliación en el sistema recurrente
(*) No es obligatorio cuando el canal es recurrente
recurrence.beneficiary
Id
string max 15 NO Id del beneficiario
recurrence.beneficiary
FirstName
string max 20 NO Nombres del beneficiario
recurrence.beneficiary
LastName
string max 50 NO Apellidos del beneficiario
recurrence.frequency string NO Frecuencia de pago recurrente
– MONTHLY Periocidad mensual
– QUARTERLY Periocidad trimestal
– BIANNUAL Periocidad semestral
– ANNUAL Periocidad anual
recurrence.amount number($double) NO Importe del cargo para la afiliación a registrar. Precisión hasta 8 valores enteros con 2 decimales
recurrence.maxAmount number($double) NO Importe máximo para los cargos de la afiliación a registrar. Precisión hasta 8 valores enteros con 2 decimales
recurrence.type string NO Tipo de pago recurrente
– FIXED Recurrencia fija
– VARIABLE Recurrencia variable
– FIXEDINITIAL Recurrencia fija más pago inicial
– VARIABLEINITIAL Recurrencia variable más pago inicial
currencyConversion json NO Entidad que representa información relacionada a la conversión DCC
(*) No es obligatorio cuando el canal es recurrente
currencyConversion.
accepted
boolean NO Indica si en la venta se usará o no DCC
currencyConversion.
eligibilityCode
string max 1 NO Indica si en la venta se usará o no DCC
– 0 Requerimiento DCC ha sido aceptado
– 1 El requerimiento DCC ha sido rechazado basado en un error. Verifique los códigos de error para más detalle
– 2 La tarjeta no fue encontrada en la CRT por lo que no puede ser considerada para DCC
– 3 DCC no está permitido para la tarjeta
– 4 No se requirió el servicio DCC
currencyConversion.
currencyCode
string max 3 NO Código de moneda DCC. El código de moneda aplicable al PAN. Este valor se encuentra en la búsqueda CRT (ISO 4217)
currencyConversion.
currencyCodeAlpha
string max 3 NO Código de moneda DCC en texto. El código de moneda expresado en texto, esto ayudará a la presentación de la oferta DCC
currencyConversion.
amount
number($double) NO Importe en moneda DCC. El monto en la moneda extranjera en la menor unidad de la moneda extranjera
currencyConversion.
exponent
integer($int32) NO El exponente extranjero utilizado en dar formato al monto
currencyConversion.
exchangeRate
number($double) NO Factor por el que el monto local es multiplicado para obtener el monto DCC
currencyConversion.
wholeSaleRate
number($double) NO Tasa de conversión antes de que se aplique la comisión
currencyConversion.
markup
number($double) NO Margen de beneficio aplicado a toda la tasa de venta
currencyConversion.
rateSource
string max 12 NO Nombre del origen de las tarifas extranjeras
currencyConversion.
rateDate
string max 6 NO Fecha en la que se obtuvo el tipo de cambio. Expresado como yyMMdd
currencyConversion.
rateTime
string max 6 NO Hora en la que se obtuvo el tipo de cambio. Expresado como hhMMss
currencyConversion.
status
string max 15 NO Estado obtenido en la consulta de elegibilidad DCC
– Authorized
– Not Authorized
currencyConversion.
signature
string max 41 NO Llave generada en la consulta de elegibilidad DCC


  C.2 Trama de ejemplo:

Request

POST /api.authorization/v3/authorization/ecommerce/341198210 HTTP/1.1

Host: apitestenv.vnforapps.com

Content-Type: application/json

Authorization: eyJraWQiOiJmWk1tV3pZR0RBckxHektvalNCK2w3SjFhMn NPXC9zQnNwOTlNNmNuM3F5MD0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJjN TAxNjYyOS04Zjc2LTQ1M2QtYjhlNC01MGJjZDI5YjI2NTAiLCJldmVudF9pZ CI6IjM3NzU5ZTIxLTk0NTItNGY4NC05MzFhLTAxMTY2Yjk1NGNlYyIsInRva 2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXdzLmNvZ25pdG8uc2lnbmluL nVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE2MDUxOTMyNDQsImlzcyI6Imh0d HBzOlwvXC9jb2duaXRvLWlkcC51cy1lYXN0LTEuYW1hem9uYXdzLmNvbVwvd XMtZWFzdC0xXzJjSjFTZTFmSSIsImV4cCI6MTYwNTE5Njg0NCwiaWF0IjoxN jA1MTkzMjQ0LCJqdGkiOiJmOTU5NzE1NC0yZDhmLTQyZjUtOWU2ZS0zMGQ5Z Dg1MjlkMTAiLCJjbGllbnRfaWQiOiIxMGx2MDYxN281ZGljNTFlYnNucWVpa WpiNyIsInVzZXJuYW1lIjoiaW50ZWdyYWNpb25lcy52aXNhbmV0QG5lY29tc Gx1cy5jb20ifQ.c-zXWXr_aGSvatc9bGgC8_RSUB0X_bFM1T6eVnGwcGEqbT VMcXSzSdwNbzfIWzrssOZ6UELNo30lxRjbZDi008I1whJFqRT3YumdhLTiS- FmaJWXlEOZY8WVGJDEu04AkNKtcqoUgyr3sDLXsDytFUCKk7ACe6Y3qB7Zmh 95RzPrum3m8sqJP1lSWY6VUO3fawXC7iNf509R6VHpH1iyKlS7eSvzMRr0yz 8UfjJpKN3mjVmGl_HgOAMigqpA-OdPR_p2STRUrrZnuLDv6pHapFs2inA4l2 Y-WURDrgD5ypEbJZVQH3I2c49EMOFuHuMukVFCsg8viAgCEZQh-VZRuw

Scope: eyJzY29wZXMiOlt7ImtleSI6IjgxODk5NzIyLTU4MzgtNDYwYS1iNj ZkLTVjODAyYzQxNzdhNiIsImVsZW1lbnRzIjpbImNhcmQuY2FyZE51bWJlci IsImNhcmQuY3Z2MiJdfV19


{

 "channel": "web",

 "captureType": "manual",

 "countable": true,

 "order": {

  "tokenId": "1C51C5A85F1B494D91C5A85F1B894D1D",

  "purchaseNumber": "1234567890",

  "amount": 12.35,

  "currency": "PEN"

 },

 "card": {

 "cardNumber": "rkOMvvXX71uaGVIXzow3EmNbR9i3OoDWfofV0nnrm2s=",

 "expirationMonth": 12,

 "expirationYear": 2021,

 "cvv2": "HsOBhExsr4m0sMfrVlIRwA=="

 },

 "cardHolder": {

  "email": "juan.c@latinmail.com"

 }

}



  C.3 Lenguajes:

  • Node
  • JavaScript
  • Python

const request = require('request');

const options = {

 method: 'POST',

 url: 'https://apitestenv.vnforapps.com/api.authorization/v3/authorization/product/merchantId',

 headers: {

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

  'Scope': '{{scope}}',

  accept: 'application/json',

  'content-type': 'application/json'

 },

 body: {

  channel: "web",

  captureType: "manual",

  countable: true,

  order: {

   tokenId: "1C51C5A85F1B494D91C5A85F1B894D1D",

   purchaseNumber: "1234567890",

   amount: 12.35,

   currency: "PEN"

  },

  card: {

   cardNumber: "rkOMvvXX71uaGVIXzow3EmNbR9i3OoDWfofV0nnrm2s=",

   expirationMonth: 12,

   expirationYear: 2021,

   cvv2: "HsOBhExsr4m0sMfrVlIRwA=="

  },

  cardHolder: {

   email: "juan.c@latinmail.com"

  }

  },

  json: true

 };

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 Obligatorio Descripción
TRAMA EXITOSA: 200
header json NO Entidad que representa el encabezado de respuesta a la petición
header.ecore
TransactionUUID
string($uuid) NO Identificador único de transacción para la plataforma
header.ecore
TransactionDate
string NO Fecha de la operación expresada en formato UNIX TimeStamp
header.millis integer($int32) NO Tiempo de ejecución de la operación
fulfillment json SI Entidad que representa información complementaria al pedido
fulfillment.channel string SI Canal desde donde se originó la operación.
– web: Si son operaciones realizadas con el botón de pago web
– mobile: Si son operaciones realizadas con la librería de pago app
– pasarela: Si son operaciones realizadas con la API de autorización para el producto comercio electrónico
– callcenter: Si son operaciones realizadas con la API de autorización para el producto telepago
fulfillment.merchantId string max 9 SI Código de comercio
fulfillment.
terminalId
string max 8 SI Número de terminal asociado a la transacción
fulfillment.
captureType
string max 6 SI Tipo de captura en el canal. Siempre es el valor manual
fulfillment.
countable
boolean SI Indica si la venta es contable true o no contable false
fulfillment.
fastPayment
boolean SI Indica si la venta es pago rápido true o no es pago rápido false
fulfillment.
signature
string($uuid) SI Código único generado por el sistema al momento de la venta
order json SI Entidad que representa la información del pedido
order.tokenId string max 32 NO Id del token de transacción obtenido en la respuesta a la validación antifraude o del formulario de pago
order.productId string max 10 NO Código del producto para la afiliación
order.purchase
Number
string max 12 SI Número de pedido generado por el comercio
order.amount number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
order.installment integer($int32) SI Número de cuotas en que se realizará el pago
order.currency string max 3 SI Código de moneda en la que se ejecuta la transacción
– PEN
– USD
order.external
TransactionId
string($uuid) NO Identificador único de transacción enviado por el comercio
order.authorized
Amount
number($double) SI Importe del pedido confirmado. Precisión hasta 8 valores enteros con 2 decimales
order.authorization
Code
string max 6 SI Código de autorización asignado a la aprobación de la transacción por la entidad resolutora
order.actionCode string max 3 SI 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.traceNumber string max 6 SI Número asignado para identificar de forma unívoca a la transacción
order.transaction
Date
string SI Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
order.transactionId string max 15 SI Identificador de la transacción asociado a la autorización
dataMap json SI Entidad que representa información complementaria del pedido
dataMap.
CURRENCY
string max 4 SI Código numérico de moneda en la que se ejecuta la transacción
dataMap.
TRANSACTION
_DATE
string SI Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
dataMap.
ACTION
_CODE
string max 3 SI 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 SI Código único generado por el sistema
dataMap.
ECI_DESCRIPTION
string max 100 NO Descripción del código ECI asociado a la autenticación de la transacción
dataMap.
ECI
string max 2 SI Código ECI asociado a la autenticación de la transacción
dataMap.
CARD
string max 16 SI Número de tarjeta enmascarado usada en la venta
dataMap.
MERCHANT
string max 9 SI Código de comercio al cual pertenece la transacción
dataMap.
STATUS
string max 20 SI Descripción del estado de la transacción
– Authorized
– Not Authorized
– Confirmed
– Not Confirmed
– Verified
– Not Verified
– Voided
– Not Voided
– Reject
– Review
dataMap.
ADQUIRENTE
string max 15 SI Nombre de identificación del adquirente.
dataMap.
BIN
string max 6 NO 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 SI Marca de la tarjeta usada en la venta
– visa
– amex
– mastercard
– dinersclub
dataMap.
SETTLEMENT
string max 20 NO Indica si la operación está o no está liquidada
– Not Applicable
– Pending
– Automatic
– Completed
dataMap.
ACTION_DESCRIPTION
string max 100 SI Texto descriptivo de la autorización o denegación
dataMap.
ID_UNICO
string max 15 SI Id de la transacción asociado a la autorización
dataMap.
AMOUNT
number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
dataMap.
AUTHORIZED_AMOUNT
number($double) NO Importe del pedido confirmado. Precisión hasta 8 valores enteros con 2 decimales
dataMap.
TRANSACTION_ID
string max 15 SI Id de la transacción asociado a la autorización
dataMap.
AUTHORIZATION_CODE
string max 6 SI Código de autorización asignado a la aprobación de la transacción por la entidad resolutora
dataMap.
CARD_TOKEN
string max 16 SI Token identificador del objeto tokenizado
dataMap.
VAULT_BLOCK
string max 100 NO Valor del campo por el cual se tokeniza la tarjeta
dataMap.
QUOTA_NUMBER
integer($int32) NO Número de cuotas en que se realizó la venta
dataMap.
QUOTA_AMOUNT
number($double) NO Importe aproximado del valor de cuota. Precisión hasta 8 valores enteros con 2 decimales
dataMap.
QUOTA_DEFERRED
integer($int32) NO Indica si el pago en cuotas debe procesarse con pagos en diferido.
– 0 no diferido
– 1 o 2 diferido
dataMap.
QUOTA_NI_PROGRAM
integer($int32) NO Código de programa para cuota sin intereses
dataMap.
QUOTA_NI_TYPE
integer($int32) NO Indicador de tipo de cobro para cuotas sin intereses.
– 0 como porcentaje
– 1 como importe
dataMap.
QUOTA_NI_AMOUNT
number($double) NO Valor asociado al tipo de cobro para cuotas sin intereses
dataMap.
QUOTA_NI_DISCOUNT
number($double) NO Porcentaje de descuento que corresponde al emisor por el programa cuota sin intereses
dataMap.
QUOTA_NI_MESSAGE
string max 50 NO Mensaje asociado al cobro para cuota sin intereses
TRAMA ERRONEA: 400
errorCode integer($int32) SI Código de error de la operación. Siempre es el valor 400
errorMessage string SI Mensaje de error de la operación
header json NO Entidad que representa el encabezado de respuesta a la petición
header.ecoreTransaction
UUID
string($uuid) NO Identificador único de transacción para la plataforma
header.ecoreTransaction
Date
string NO Fecha de la operación expresada en formato UNIX TimeStamp
header.millis integer($int32) NO Tiempo de ejecución de la operación
data json SI Entidad que representa información relacionada a errores en la operación realizada
dataMap.
CURRENCY
string max 4 SI Código numérico de moneda en la que se ejecuta la transacción
dataMap.
TRANSACTION_DATE
string SI Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
dataMap.
ACTION_CODE
string max 3 SI 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 NO Código único generado por el sistema
data.
ECI_DESCRIPTION
string max 100 NO Descripción del código ECI asociado a la autenticación de la transacción
data.
ECI
string max 2 NO Código ECI asociado a la autenticación de la transacción
data.
CARD
string max 16 SI Número de tarjeta enmascarado usada en la venta
data.
MERCHANT
string max 9 SI Código de comercio al cual pertenece la transacción
data.
STATUS
string max 20 SI Descripción del estado de la transacción
– Authorized
– Not Authorized
– Confirmed
– Not Confirmed
– Verified
– Not Verified
– Voided
– Not Voided
– Reject
– Review
data.
ADQUIRENTE
string max 15 SI Nombre de identificación del adquirente.
data.BIN string max 6 NO Número de BIN de la tarjeta usada en la venta. Son los 6 primeros dígitos de una tarjeta
data.BRAND string max 15 SI Marca de la tarjeta usada en la venta
– visa
– amex
– mastercard
– dinersclub
data.SETTLEMENT string max 20 NO Indica si la operación está o no está liquidada
– Not Applicable
– Pending
– Automatic
– Completed
data.ACTION_DESCRIPTION string max 100 NO Texto descriptivo de la autorización o denegación
data.ID_UNICO string max 15 NO Identificador de la transacción asociado a la autorización
data.AMOUNT number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
data.AUTHORIZED_AMOUNT number($double) NO Importe del pedido confirmado. Precisión hasta 8 valores enteros con 2 decimales
data.TRANSACTION_ID string max 15 NO Id de la transacción asociado a la autorización
data.AUTHORIZATION_CODE string max 6 NO Código de autorización asignado a la aprobación de la transacción por la entidad resolutora
data.QUOTA_NUMBER integer($int32) NO Número de cuotas en que se realizó la venta
data.QUOTA_AMOUNT number($double) NO Importe aproximado del valor de cuota. Precisión hasta 8 valores enteros con 2 decimales
data.QUOTA_DEFERRED integer($int32) NO Indica si el pago en cuotas debe procesarse con pagos en diferido.
– 0 no diferido
– 1 o 2 diferido
data.QUOTA_NI_PROGRAM integer($int32) NO Código de programa para cuota sin intereses
data.QUOTA_NI_TYPE integer($int32) NO Indicador de tipo de cobro para cuotas sin intereses.
– 0 como porcentaje
– 1 como importe
data.QUOTA_NI_AMOUNT number($double) NO Valor asociado al tipo de cobro para cuotas sin intereses
data.
QUOTA_NI_DISCOUNT
number($double) NO Porcentaje de descuento que corresponde al emisor por el programa cuota sin intereses
data.
QUOTA_NI_MESSAGE
string max 50 NO Mensaje asociado al cobro para cuota sin intereses
TRAMA ERRONEA: 401
description text max 1000 NO Descripción relacionada al error. Este error se presenta cuando las credenciales no son válidas
TRAMA ERRONEA: 406
description text max 1000 NO Descripción relacionada al error. Este error se presenta cuando hay muchas solicitudes con la misma carga


  D.2 Trama de ejemplo:

  • Caso 200
  • Caso 400
  • Caso 401
  • Caso 406

Status Code 200 OK

Content-Type: application/json

{

 "header": {

  "ecoreTransactionUUID": "b62b1b2c-47b0-44b8-bcf6-fc6328a6a8fc",

  "ecoreTransactionDate": 1605193309897,

  "millis": 7762

  "refreshToken":

 },

 "fulfillment": {

  "channel": "web",

  "merchantId": "341198210",

  "terminalId": "",

  "captureType": "manual",

  "countable": true,

  "fastPayment": false,

  "signature": "b62b1b2c-47b0-44b8-bcf6-fc6328a6a8fc"

 },

 "order": {

  "tokenId": "1C51C5A85F1B494D91C5A85F1B894D1D",

  "purchaseNumber": "1234567890",

  "amount": 12.35,

  "installment": 0,

  "currency": "PEN",

  "authorizedAmount": 12.35,

  "authorizationCode": "007124",

  "actionCode": "000",

  "traceNumber": "273126",

  "transactionDate": "201112100146",

  "transactionId": "953203170000099"

 },

 "dataMap": {

  "TERMINAL": "00000001",

  "BRAND_ACTION_CODE": "00",

  "BRAND_HOST_DATE_TIME": "201112095800",

  "TRACE_NUMBER": "273126",

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

  "CARD_TYPE": "C",

  "SIGNATURE": "b62b1b2c-47b0-44b8-bcf6-fc6328a6a8fc",

  "CARD": "544359******0447",

  "MERCHANT": "341198210",

  "STATUS": "Authorized",

  "ACTION_DESCRIPTION": "Aprobado y completado con exito",

  "ID_UNICO": "953203170000099",

  "AMOUNT": "12.35",

  "BRAND_HOST_ID": "500140",

  "AUTHORIZATION_CODE": "007124",

  "CURRENCY": "0604",

  "TRANSACTION_DATE": "201112100146",

  "ACTION_CODE": "000",

  "CVV2_VALIDATION_RESULT": "M",

  "ECI": "07",

  "ID_RESOLUTOR": "031758787225",

  "BRAND": "mastercard",

  "ADQUIRENTE": "570009",

  "BRAND_NAME": "MC",

  "PROCESS_CODE": "000000",

  "TRANSACTION_ID": "953203170000099"

  }

 }



E. Códigos de Respuesta

Respuesta Descripción
200 Autorización de venta realizada con éxito
400 Error en la autorización de la venta
401 Error relacionado al acceso no autorizado
406 Error por enviar muchas solicitudes con la misma carga

API de Autorización con Petición Cifrada #

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.


A. Endpoint

Ambiente URL de API
Testing https://apitestenv.vnforapps.com/api.authorization/v3/authorization/{product}/{merchantId}
Producción https://apiprod.vnforapps.com/api.authorization/v3/authorization/{product}/{merchantId}


B. Cifrado

En este punto se detallan los parámetros de encriptación del algoritmo AES y los elementos a codificar o encriptar.

   B.1 Parámetros de encriptación

  • Algoritmo de encriptación: AES
  • Modo de encriptación: CBC
  • Relleno: PKCS7
  • Tamaño de la llave: 256 bits
  • Tamaño de bloque: 128 bits
  • Llave: token (se obtiene del API de seguridad) se requiere convertir de string hexadecimal a byte array.
  • Vector de inicialización: iv (se obtiene del API de seguridad) se requiere convertir de string hexadecimal a byte array.
 

   B.2 Request original (encriptación AES)

Request

{

 "channel": "web",

 "captureType": "manual",

 "countable": true,

 "order": {

  "tokenId": "1C51C5A85F1B494D91C5A85F1B894D1D",

  "purchaseNumber": "1234567890",

  "amount": 12.35,

  "currency": "PEN"

 },

 "card": {

  "cardNumber": "5443599980000447",

  "expirationMonth": 12,

  "expirationYear": 2021,

  "cvv2": "123"

 },

 "cardHolder": {

  "email": "juan.c@latinmail.com"

 }

}

 
 
Campo Tipo Longitud Obligatorio Descripción
channel String SI Canal desde donde se originó la operación. – web Si son operaciones realizadas con el botón de pago web – mobile Si son operaciones realizadas con la librería de pago app – pasarela Si son operaciones realizadas con la API de autorización para el producto comercio electrónico – callcenter Si son operaciones realizadas con la API de autorización para el producto telepago – recurrent Si son operaciones realizadas con la API de autorización para el producto pago programado
captureType String SI Tipo de captura en el canal. Siempre es el valor manual
countable Boolean SI Tipo de venta a realizar. Siempre es el valor true
order Json SI Entidad que representa la información del pedido
order.tokenId string max 32 NO Id del token de transacción obtenido en la respuesta a la validación antifraude o del formulario de pago (*) No es obligatorio cuando el canal es recurrente
order.productId string max 10 NO Código del producto para la afiliación. (*) No es obligatorio cuando el canal es recurrente
order.purchaseNumber string max 12 SI Número de pedido generado por el comercio (*) No es obligatorio cuando el canal es recurrente
order.amount Number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
order.installment integer($int32) NO Número de cuotas en que se realizará el pago
order.currency String Max 3 SI Código de moneda en la que se ejecuta la transacción – PEN – USD
order.externalTransactionId String($uuid) NO Id único de la transacción enviado por el comercio
card json SI Entidad que representa información de la tarjeta
card.cardNumber String SI Número de la tarjeta
card.expirationMonth Integer($int32) SI Mes de expiración
card.expirationYear Integer($int32) SI Año de expiración
card.cvv2 String SI Número de CVV2 de la tarjeta
cardHolder Json NO Entidad que representa la información del tarjetahabiente
cardHolder.firstName String Max 25 NO Nombres del tarjetahabiente
cardHolder.lastName String Max 50 NO Apellidos del tarjetahabiente
cardHolder.email String Max 35 SI Correo electrónico del tarjetahabiente
cardHolder.phoneNumber String Max 10 NO Teléfono del tarjetahabiente
cardHolder.documentType String Max 1 NO Tipo de documento del tarjetahabiente – 0 DNI – 1 Carnet extranjería – 2 Pasaporte (*) No es obligatorio cuando el canal es recurrente
cardHolder.documentNumber String max 12 NO Número de documento del tarjetahabiente (*) No es obligatorio cuando el canal es recurrente
sponsored json NO Entidad que representa información relacionada al comercio hijo. (*) Es de ingreso obligatorio si se está integrando un facilitador de pagos
sponsored.merchantId string max 9 NO Código de comercio hijo
sponsored.name string max 25 NO Nombre de comercio hijo
sponsored.mcci string max 4 NO MCC internacional de comercio hijo
sponsored.address string max 50 NO Dirección de comercio hijo
sponsored.phoneNumber string max 10 NO Teléfono de comercio hijo
authentication json NO Entidad que representa información relacionada a la autenticación en Verified by Visa (*) No es obligatorio cuando el canal es recurrente
authentication.eci string max 2 NO Valor ECI del proceso de validación de la marca – 05 Transacción autenticada – 06 Comercio intentó autenticación, pero TH no está participando
authentication.xid string max 20 NO Valor XID del proceso de validación de la marca
authentication.cavv string max 40 NO Valor CAVV del proceso de validación de la marca
recurrence json NO Entidad que representa información relacionada a la afiliación en el sistema recurrente (*) No es obligatorio cuando el canal es recurrente
recurrence.beneficiaryId string max 15 NO Id del beneficiario
recurrence.beneficiaryFirstName string max 20 NO Nombres del beneficiario
recurrence.beneficiaryLastName string max 50 NO Apellidos del beneficiario
recurrence.frequency string NO Frecuencia de pago recurrente – MONTHLY Periocidad mensual – QUARTERLY Periocidad trimestal – BIANNUAL Periocidad semestral – ANNUAL Periocidad anual
recurrence.amount number($double) NO Importe del cargo para la afiliación a registrar. Precisión hasta 8 valores enteros con 2 decimales
recurrence.maxAmount number($double) NO Importe máximo para los cargos de la afiliación a registrar. Precisión hasta 8 valores enteros con 2 decimales
recurrence.type string NO Tipo de pago recurrente – FIXED Recurrencia fija – VARIABLE Recurrencia variable – FIXEDINITIAL – Recurrencia fija más pago inicial – VARIABLEINITIAL Recurrencia variable más pago inicial
currencyConversion json NO Entidad que representa información relacionada a la conversión DCC (*) No es obligatorio cuando el canal es recurrente
currencyConversion.accepted boolean NO Indica si en la venta se usará o no DCC
currencyConversion.eligibilityCode string max 1 NO Valor retornado en la respuesta a la consulta de elegibilidad – 0 Requerimiento DCC ha sido aceptado – 1 El requerimiento DCC ha sido rechazado basado en un error. Verifique los códigos de error para más detalle – 2 La tarjeta no fue encontrada en la CRT por lo que no puede ser considerada para DCC – 3 DCC no está permitido para la tarjeta – 4 No se requirió el servicio DCC
currencyConversion.currencyCode string max 3 NO Código de moneda DCC. El código de moneda aplicable al PAN. Este valor se encuentra en la búsqueda CRT (ISO 4217)
currencyConversion.currencyCodeAlpha string max 3 NO Código de moneda DCC en texto. El código de moneda expresado en texto, esto ayudará a la presentación de la oferta DCC
currencyConversion.amount number($double) NO Importe en moneda DCC. El monto en la moneda extranjera en la menor unidad de la moneda extranjera
currencyConversion.exponent integer($int32) NO El exponente extranjero utilizado en dar formato al monto
currencyConversion.exchangeRate number($double) NO Factor por el que el monto local es multiplicado para obtener el monto DCC
currencyConversion.wholeSaleRate number($double) NO Tasa de conversión antes de que se aplique la comisión
currencyConversion.markup number($double) NO Margen de beneficio aplicado a toda la tasa de venta
currencyConversion.rateSource string max 12 NO Nombre del origen de las tarifas extranjeras
currencyConversion.rateDate string max 6 NO Fecha en la que se obtuvo el tipo de cambio. Expresado como yyMMdd
currencyConversion.rateTime string max 6 NO Hora en la que se obtuvo el tipo de cambio. Expresado como hhMMss
currencyConversion.status string max 15 NO Estado obtenido en la consulta de elegibilidad DCC – Authorized – Not Authorized
currencyConversion.signature string max 41 NO Llave generada en la consulta de elegibilidad DCC


C. Request y Casos

  C.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
product text max 100 SI Identificador de producto – ecommerce – pospc – recurrent
merchantId text max 100 SI Código de comercio
BODY
key string max 36 SI Token obtenido en la respuesta del API de Seguridad y que está relacionado a la llave y vector de encriptación que se usará en el Request original
payload string SI Request original encriptado con la llave token y vector iv obtenidos en la respuesta del API de Seguridad


  C.2 Trama de ejemplo:

Request

POST /api.authorization/v3/authorization/ecommerce/341198210 HTTP/1.1

Host: apitestenv.vnforapps.com

Content-Type: application/json

Authorization: eyJraWQiOiJmWk1tV3pZR0RBckxHektvalNCK2w3SjFhMnNPXC9zQn NwOTlNNmNuM3F5MD0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJjNTAxNjYyOS04Zjc2L TQ1M2QtYjhlNC01MGJjZDI5YjI2NTAiLCJldmVudF9pZCI6ImNmMmQ3ZTQ0LWE1YzYtN DUzNS04ODg5LTc0MDc0Y2VkZWZlYSIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlI joiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE2MDUxO TM2ODAsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC51cy1lYXN0LTEuYW1hem9uY XdzLmNvbVwvdXMtZWFzdC0xXzJjSjFTZTFmSSIsImV4cCI6MTYwNTE5NzI4MCwiaWF0I joxNjA1MTkzNjgwLCJqdGkiOiI3NTlhZTUxYy01MjFlLTRkOWUtOTJjNS1hMDdjODYwM jM4OGMiLCJjbGllbnRfaWQiOiIxMGx2MDYxN281ZGljNTFlYnNucWVpaWpiNyIsInVzZ XJuYW1lIjoiaW50ZWdyYWNpb25lcy52aXNhbmV0QG5lY29tcGx1cy5jb20ifQ.TJtfyc NEKG_BrakQ2pvv3vFvqP4cb_QTmhoTxI7nvDshYopIa64Dp_avNjc7V14ZT4X0AdP3DO Ni1pM38x5LonYjpMbz6YJDMtjijezhZG06mFZ2P6jMCxs83VIEzU2qrrdb6zNLzsw8J5 APIevUNFF2YTBnrx7b3ct3NiQW_pwrkzjPdT9FQsv88wZQS5pg_AGP95mcbSnPoc4hbV Y7p95qexXXK5d16zYnPhf0ThJJZBaFfOgAZK4-66yte-nYTmMQNyeXvv9iID7uv2lFZU THk5BUdsnrVq1FwxzS26SjobD1WFy9F-oXhAqYb4sIfLJY81uRGbXwqleA0nYMhg

{

"key":"169fce06-9f6b-4364-8415-82b661c3e9b2",

 "payload":"qY+91onA5GCjzH3gQrJKOuDCStgfwloNNCr3WBpN3+5TxzNhxCh 74JqNTsEV5ynBzz5n6RH9l2Gu33hwC70PnEO027cu8AAaMTQPQiPYI98wIvqCOOmWe5R VRGcZYcN/I8+frSsUr83PBk49xub4gf7yhDLedbNqbN7zfWwmpcpZ31GaUYG+9BRo8s3 tSFXpMxqpMZJa7XEAfGalh8uzrp7xq0riRpTJ3wJQsfDD0Xz4Iisjns1Rd8XI29o3aZc cQPRG3CiinFj2EhJMGXvZ9OSt11UM8zC0T0HLhxkSHMRnmyoXX/9O21/8VW9ASSJKziS 5eIFfyJvTWl3SebMx7dy8pNKV3yh7AigLXXS5hbGoU/yIzZi0cu5+sYyc+0XcSSn2Sq2 SAKuKLuSK1cTHkTyIL1YBVBQMmnR+7oSO75weCSVbz5bIx7ok3SYS9PzYJBaLGEz/QSx y61BoQ2KflJ5AlVEKhKuSM0HIdo7jOOvuX6G/Lo24rB2RJRstmCoa4qDkhfjfR4XRhzP L+CItXINwb3ftPvactWfsB+NDfS5YHETTdiX8bkORQPinPKoucJC2klkXY42FdYe4xFP Rk/S9/CA2btaa2OTMgmit6UpOl4KqJ62VBuEZnJXgkOPhk/+bee+7kfo35h1W9wk2STL fSTA1uk27wk4pQg3Hxa75kDTPjTCuZZAlsSidhdkFE9rv5832b7ZrgabnEiPZQi0DJE2 aDJvUAFY6P7rOtSwoPQHanu/wv71tfkRbzcPuaszkF+PZowRa71w4Ypf03SNERs/0ULE N0fvEVY8BBvk="

}


  C.3 Lenguajes:

  • Node
  • JavaScript
  • Python

const request = require('request');

const options = {

method: 'POST',

url: 'https://apitestenv.vnforapps.com/api.authorization/v3/authorization/product/merchantId',

headers: {

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

accept: 'application/json',

'content-type': 'application/json'

},

body: {

key:"169fce06-9f6b-4364-8415-82b661c3e9b2",

payload:"qY+91onA5GCjzH3gQrJKOuDCStgfwloNNCr3WBpN3+5TxzNhxCh74J qNTsEV5ynBzz5n6RH9l2Gu33hwC70PnEO027cu8AAaMTQPQiPYI98wIvqCOOmWe5RVRGcZYcN/I 8+frSsUr83PBk49xub4gf7yhDLedbNqbN7zfWwmpcpZ31GaUYG+9BRo8s3tSFXpMxqpMZJa7XEA fGalh8uzrp7xq0riRpTJ3wJQsfDD0Xz4Iisjns1Rd8XI29o3aZccQPRG3CiinFj2EhJMGXvZ9OS t11UM8zC0T0HLhxkSHMRnmyoXX/9O21/8VW9ASSJKziS5eIFfyJvTWl3SebMx7dy8pNKV3yh7Ai gLXXS5hbGoU/yIzZi0cu5+sYyc+0XcSSn2Sq2SAKuKLuSK1cTHkTyIL1YBVBQMmnR+7oSO75weC SVbz5bIx7ok3SYS9PzYJBaLGEz/QSxy61BoQ2KflJ5AlVEKhKuSM0HIdo7jOOvuX6G/Lo24rB2R JRstmCoa4qDkhfjfR4XRhzPL+CItXINwb3ftPvactWfsB+NDfS5YHETTdiX8bkORQPinPKoucJC 2klkXY42FdYe4xFPRk/S9/CA2btaa2OTMgmit6UpOl4KqJ62VBuEZnJXgkOPhk/+bee+7kfo35h 1W9wk2STLfSTA1uk27wk4pQg3Hxa75kDTPjTCuZZAlsSidhdkFE9rv5832b7ZrgabnEiPZQi0DJ E2aDJvUAFY6P7rOtSwoPQHanu/wv71tfkRbzcPuaszkF+PZowRa71w4Ypf03SNERs/0ULEN0fvE VY8BBvk="

},

json: true

};

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 Obligatorio Descripción
TRAMA EXITOSA: 200
header json NO Entidad que representa el encabezado de respuesta a la petición
header.ecoreTransactionUUID string($uuid) NO Identificador único de transacción para la plataforma
header.ecoreTransactionDate string NO Fecha de la operación expresada en formato UNIX TimeStamp
header.millis integer($int32) NO Tiempo de ejecución de la operación
fulfillment json SI Entidad que representa información complementaria al pedido
fulfillment.channel string SI Canal desde donde se originó la operación. – web: Si son operaciones realizadas con el botón de pago web – mobile: Si son operaciones realizadas con la librería de pago app – pasarela: Si son operaciones realizadas con la API de autorización para el producto comercio electrónico – callcenter: Si son operaciones realizadas con la API de autorización para el producto telepago
fulfillment.merchantId string max 9 SI Código de comercio
fulfillment.terminalId string max 8 SI Número de terminal asociado a la transacción
fulfillment.captureType string max 6 SI Tipo de captura en el canal. Siempre es el valor manual
fulfillment.countable boolean SI Indica si la venta es contable true o no contable false
fulfillment.fastPayment boolean SI Indica si la venta es pago rápido true o no es pago rápido false
fulfillment.signature string($uuid) SI Código único generado por el sistema al momento de la venta
order json SI Entidad que representa la información del pedido
order.tokenId string max 32 NO Id del token de transacción obtenido en la respuesta a la validación antifraude o del formulario de pago
order.productId string max 10 NO Código del producto para la afiliación
order.purchaseNumber string max 12 SI Número de pedido generado por el comercio
order.amount number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
order.installment integer($int32) SI Número de cuotas en que se realizará el pago
order.currency string max 3 SI Código de moneda en la que se ejecuta la transacción – PEN – USD
order.externalTransactionId string($uuid) NO Identificador único de transacción enviado por el comercio
order.authorizedAmount number($double) SI Importe del pedido confirmado. Precisión hasta 8 valores enteros con 2 decimales
order.authorizationCode string max 6 SI Código de autorización asignado a la aprobación de la transacción por la entidad resolutora
order.actionCode string max 3 SI 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.traceNumber string max 6 SI Número asignado para identificar de forma unívoca a la transacción
order.transactionDate string SI Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
order.transactionId string max 15 SI Identificador de la transacción asociado a la autorización
dataMap json SI Entidad que representa información complementaria del pedido
dataMap.CURRENCY string max 4 SI Código numérico de moneda en la que se ejecuta la transacción
dataMap.TRANSACTION_DATE string SI Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
dataMap.ACTION_CODE string max 3 SI 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 SI Código único generado por el sistema
dataMap.ECI_DESCRIPTION string max 100 NO Descripción del código ECI asociado a la autenticación de la transacción
dataMap.ECI string max 2 SI Código ECI asociado a la autenticación de la transacción
dataMap.CARD string max 16 SI Número de tarjeta enmascarado usada en la venta
dataMap.MERCHANT string max 9 SI Código de comercio al cual pertenece la transacción
dataMap.STATUS string max 20 SI Descripción del estado de la transacción – Authorized – Not Authorized – Confirmed – Not Confirmed – Verified – Not Verified – Voided – Not Voided – Reject – Review
dataMap.ADQUIRENTE string max 15 SI Nombre de identificación del adquirente.
dataMap.BIN string max 6 NO 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 SI Marca de la tarjeta usada en la venta – visa – amex – mastercard – dinersclub
dataMap.SETTLEMENT string max 20 NO Indica si la operación está o no está liquidada – Not Applicable – Pending – Automatic – Completed
dataMap.ACTION_DESCRIPTION string max 100 SI Texto descriptivo de la autorización o denegación
dataMap.ID_UNICO string max 15 SI Id de la transacción asociado a la autorización
dataMap.AMOUNT number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
dataMap.AUTHORIZED_AMOUNT number($double) NO Importe del pedido confirmado. Precisión hasta 8 valores enteros con 2 decimales
dataMap.TRANSACTION_ID string max 15 SI Id de la transacción asociado a la autorización
dataMap.AUTHORIZATION_CODE string max 6 SI Código de autorización asignado a la aprobación de la transacción por la entidad resolutora
dataMap.CARD_TOKEN string max 16 NO Token identificador del objeto tokenizado
dataMap.VAULT_BLOCK string max 100 NO Valor del campo por el cual se tokeniza la tarjeta
dataMap.QUOTA_NUMBER integer($int32) NO Número de cuotas en que se realizó la venta
dataMap.QUOTA_AMOUNT number($double) NO Importe aproximado del valor de cuota. Precisión hasta 8 valores enteros con 2 decimales
dataMap.QUOTA_DEFERRED integer($int32) NO Indica si el pago en cuotas debe procesarse con pagos en diferido. – 0 no diferido – 1 o 2 diferido
dataMap.QUOTA_NI_PROGRAM integer($int32) NO Código de programa para cuota sin intereses
dataMap.QUOTA_NI_TYPE integer($int32) NO Indicador de tipo de cobro para cuotas sin intereses. – 0 como porcentaje – 1 como importe
dataMap.QUOTA_NI_AMOUNT number($double) NO Valor asociado al tipo de cobro para cuotas sin intereses
dataMap.QUOTA_NI_DISCOUNT number($double) NO Porcentaje de descuento que corresponde al emisor por el programa cuota sin intereses
dataMap.QUOTA_NI_MESSAGE string max 50 NO Mensaje asociado al cobro para cuota sin intereses
TRAMA ERRONEA: 400
errorCode integer($int32) SI Código de error de la operación. Siempre es el valor 400
errorMessage string SI Mensaje de error de la operación
header json NO Entidad que representa el encabezado de respuesta a la petición
header.ecoreTransactionUUID string($uuid) NO Identificador único de transacción para la plataforma
header.ecoreTransactionDate string NO Fecha de la operación expresada en formato UNIX TimeStamp
header.millis integer($int32) NO Tiempo de ejecución de la operación
data json SI Entidad que representa información relacionada a errores en la operación realizada
dataMap.CURRENCY string max 4 SI Código numérico de moneda en la que se ejecuta la transacción
dataMap.TRANSACTION_DATE string SI Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
dataMap.ACTION_CODE string max 3 SI 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 NO Código único generado por el sistema
data.ECI_DESCRIPTION string max 100 NO Descripción del código ECI asociado a la autenticación de la transacción
data.ECI string max 2 NO Código ECI asociado a la autenticación de la transacción
data.CARD string max 16 SI Número de tarjeta enmascarado usada en la venta
data.MERCHANT string max 9 SI Código de comercio al cual pertenece la transacción
data.STATUS string max 20 SI Descripción del estado de la transacción – Authorized – Not Authorized – Confirmed – Not Confirmed – Verified – Not Verified – Voided – Not Voided – Reject – Review
data.ADQUIRENTE string max 15 SI Nombre de identificación del adquirente.
data.BIN string max 6 NO Número de BIN de la tarjeta usada en la venta. Son los 6 primeros dígitos de una tarjeta
data.BRAND string max 15 SI Marca de la tarjeta usada en la venta – visa – amex – mastercard – dinersclub
data.SETTLEMENT string max 20 NO Indica si la operación está o no está liquidada – Not Applicable – Pending – Automatic – Completed
data.ACTION_DESCRIPTION string max 100 NO Texto descriptivo de la autorización o denegación
data.ID_UNICO string max 15 NO Identificador de la transacción asociado a la autorización
data.AMOUNT number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
data.AUTHORIZED_AMOUNT number($double) NO Importe del pedido confirmado. Precisión hasta 8 valores enteros con 2 decimales
data.TRANSACTION_ID string max 15 NO Id de la transacción asociado a la autorización
data.AUTHORIZATION_CODE string max 6 NO Código de autorización asignado a la aprobación de la transacción por la entidad resolutora
data.QUOTA_NUMBER integer($int32) NO Número de cuotas en que se realizó la venta
data.QUOTA_AMOUNT number($double) NO Importe aproximado del valor de cuota. Precisión hasta 8 valores enteros con 2 decimales
data.QUOTA_DEFERRED integer($int32) NO Indica si el pago en cuotas debe procesarse con pagos en diferido. – 0 no diferido – 1 o 2 diferido
data.QUOTA_NI_PROGRAM integer($int32) NO Código de programa para cuota sin intereses
data.QUOTA_NI_TYPE integer($int32) NO Indicador de tipo de cobro para cuotas sin intereses. – 0 como porcentaje – 1 como importe
data.QUOTA_NI_AMOUNT number($double) NO Valor asociado al tipo de cobro para cuotas sin intereses
data.QUOTA_NI_DISCOUNT number($double) NO Porcentaje de descuento que corresponde al emisor por el programa cuota sin intereses
data.QUOTA_NI_MESSAGE string max 50 NO Mensaje asociado al cobro para cuota sin intereses
TRAMA ERRONEA: 401
description text max 1000 NO Descripción relacionada al error. Este error se presenta cuando las credenciales no son válidas
TRAMA ERRONEA: 406
description text max 1000 NO Descripción relacionada al error. Este error se presenta cuando hay muchas solicitudes con la misma carga


  D.2 Trama de ejemplo:

  • Caso 200
  • Caso 400
  • Caso 401
  • Caso 406

Status Code 200 OK

Content-Type: application/json

{

 "header": {

  "ecoreTransactionUUID": "b0061784-9cf8-4c7e-9252-f415c3a33f2e",

  "ecoreTransactionDate": 1605193746627,

  "millis": 8371

 },

 "fulfillment": {

  "channel": "web",

  "merchantId": "341198210",

  "terminalId": "",

  "captureType": "manual",

  "countable": true,

  "fastPayment": false,

  "signature": "b0061784-9cf8-4c7e-9252-f415c3a33f2e"

 },

 "order": {

  "tokenId": "1918B5842CBF411F98B5842CBF511FF3",

  "purchaseNumber": "1234567890",

  "amount": 12.35,

  "installment": 0,

  "currency": "PEN",

  "authorizedAmount": 12.35,

  "authorizationCode": "007127",

  "actionCode": "000",

  "traceNumber": "273147",

  "transactionDate": "201112100902",

  "transactionId": "953203170000140"

 },

 "dataMap": {

  "TERMINAL": "00000001",

  "BRAND_ACTION_CODE": "00",

  "BRAND_HOST_DATE_TIME": "201112100516",

  "TRACE_NUMBER": "273147",

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

  "CARD_TYPE": "C",

  "SIGNATURE": "b0061784-9cf8-4c7e-9252-f415c3a33f2e",

  "CARD": "544359******0447",

  "MERCHANT": "341198210",

  "STATUS": "Authorized",

  "ACTION_DESCRIPTION": "Aprobado y completado con exito",

  "ID_UNICO": "953203170000140",

  "AMOUNT": "12.35",

  "BRAND_HOST_ID": "500190",

  "AUTHORIZATION_CODE": "007127",

  "CURRENCY": "0604",

  "TRANSACTION_DATE": "201112100902",

  "ACTION_CODE": "000",

  "CVV2_VALIDATION_RESULT": "M",

  "ECI": "07",

  "ID_RESOLUTOR": "031758787449",

  "BRAND": "mastercard",

  "ADQUIRENTE": "570002",

  "BRAND_NAME": "MC",

  "PROCESS_CODE": "000000",

  "TRANSACTION_ID": "953203170000140"

  }

 }

 


E. Códigos de Respuesta

Respuesta Descripción
200 Autorización de venta realizada con éxito
400 Error en la autorización de la venta
401 Error relacionado al acceso no autorizado
406 Error por enviar muchas solicitudes con la misma carga

API de Autorización con Alcance y Petición Cifrada #

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.


A. Endpoint

Ambiente URL de API
Testing https://apitestenv.vnforapps.com/api.authorization/v3/authorization/{product}/{merchantId}
Producción https://apiprod.vnforapps.com/api.authorization/v3/authorization/{product}/{merchantId}


B. Cifrado

En este punto se detallan los parámetros de encriptación del algoritmo AES y los elementos a codificar o encriptar.

   B.1 Parámetros de encriptación

  • Algoritmo de encriptación: AES
  • Modo de encriptación: CBC
  • Relleno: PKCS7
  • Tamaño de la llave: 256 bits
  • Tamaño de bloque: 128 bits
  • Llave: token (se obtiene del API de seguridad) se requiere convertir de string hexadecimal a byte array.
  • Vector de inicialización: iv (se obtiene del API de seguridad) se requiere convertir de string hexadecimal a byte array.

   B.2 Scope (codificación base64)

Request

{

 "scopes": [

 {

  "key": "9be588af-dd65-4ec3-a0c3-7eaff3c2642a",

  "elements": [

   "card.cardNumber",

   "card.cvv2"

  ]

 }

 ]

}


Campo Tipo Longitud Obligatorio Descripción
key text max 36 SI Token relacionado a la llave de encriptación a utilizar obtenido en la respuesta del API de Seguridad
elements array SI Referencia a los atributos encriptados en el cuerpo de la consulta


   B.3 Request original (encriptación AES)

Request

{

 "channel": "web",

 "captureType": "manual",

 "countable": true,

 "order": {

  "tokenId": "1C51C5A85F1B494D91C5A85F1B894D1D",

  "purchaseNumber": "1234567890",

  "amount": 12.35,

  "currency": "PEN"

 },

 "card": {

  "cardNumber": "rkOMvvXX71uaGVIXzow3EmNbR9i3OoDWfofV0nnrm2s=",

  "expirationMonth": 12,

  "expirationYear": 2021,

  "cvv2": "HsOBhExsr4m0sMfrVlIRwA=="

 },

 "cardHolder": {

  "email": "juan.c@latinmail.com"

 }

}


Campo Tipo Longitud Obligatorio Descripción
channel String SI Canal desde donde se originó la operación.
– web Si son operaciones realizadas con el botón de pago web
– mobile Si son operaciones realizadas con la librería de pago app
– pasarela Si son operaciones realizadas con la API de autorización para el producto comercio electrónico
– callcenter Si son operaciones realizadas con la API de autorización para el producto telepago
– recurrent Si son operaciones realizadas con la API de autorización para el producto pago programado
captureType String SI Tipo de captura en el canal. Siempre es el valor manual
countable Boolean SI Tipo de venta a realizar. Siempre es el valor true
order Json SI Entidad que representa la información del pedido
order.tokenId string max 32 NO Id del token de transacción obtenido en la respuesta a la validación antifraude o del formulario de pago
(*) No es obligatorio cuando el canal es recurrente
order.productId string max 10 NO Código del producto para la afiliación.
(*) No es obligatorio cuando el canal es recurrente
order.purchaseNumber string max 12 SI Número de pedido generado por el comercio
order.amount Number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
order.installment integer($int32) NO Número de cuotas en que se realizará el pago
order.currency String Max 3 SI Código de moneda en la que se ejecuta la transacción
– PEN
– USD
order.externalTransactionId String($uuid) NO Id único de la transacción enviado por el comercio
card json SI Entidad que representa información de la tarjeta
card.cardNumber String SI Número de la tarjeta encriptado con la llave token y vector iv obtenidos en la respuesta del API de Seguridad
card.expirationMonth Integer($int32) SI Mes de expiración
card.expirationYear Integer($int32) SI Año de expiración
card.cvv2 String SI Número de CVV2 de la tarjeta encriptado con la llave token y vector iv obtenidos en la respuesta del API de Seguridad
cardHolder Json NO Entidad que representa la información del tarjetahabiente
cardHolder.firstName String Max 25 NO Nombres del tarjetahabiente
cardHolder.lastName String Max 50 NO Apellidos del tarjetahabiente
cardHolder.email String Max 35 SI Correo electrónico del tarjetahabiente
cardHolder.phoneNumber String Max 10 NO Teléfono del tarjetahabiente
cardHolder.documentType String Max 1 NO Tipo de documento del tarjetahabiente
– 0 DNI
– 1 Carnet extranjería
– 2 Pasaporte
(*) No es obligatorio cuando el canal es recurrente
cardHolder.documentNumber String max 12 NO Número de documento del tarjetahabiente
(*) No es obligatorio cuando el canal es recurrente
sponsored json NO Entidad que representa información relacionada al comercio hijo.
(*) Es de ingreso obligatorio si se está integrando un facilitador de pagos
sponsored.merchantId string max 9 NO Código de comercio hijo
sponsored.name string max 25 NO Nombre de comercio hijo
sponsored.mcci string max 4 NO MCC internacional de comercio hijo
sponsored.address string max 50 NO Dirección de comercio hijo
sponsored.phoneNumber string max 10 NO Teléfono de comercio hijo
authentication json NO Entidad que representa información relacionada a la autenticación en Verified by Visa
(*) No es obligatorio cuando el canal es recurrente
authentication.eci string max 2 NO Valor ECI del proceso de validación de la marca
– 05 Transacción autenticada
– 06 Comercio intentó autenticación, pero TH no está participando
authentication.xid string max 20 NO Valor XID del proceso de validación de la marca
authentication.cavv string max 40 NO Valor CAVV del proceso de validación de la marca
recurrence json NO Entidad que representa información relacionada a la afiliación en el sistema recurrente
(*) No es obligatorio cuando el canal es recurrente
recurrence.beneficiaryId string max 15 NO Id del beneficiario
recurrence.beneficiaryFirstName string max 20 NO Nombres del beneficiario
recurrence.beneficiaryLastName string max 50 NO Apellidos del beneficiario
recurrence.frequency string NO Frecuencia de pago recurrente
– MONTHLY Periocidad mensual
– QUARTERLY Periocidad trimestal
– BIANNUAL Periocidad semestral
– ANNUAL Periocidad anual
recurrence.amount number($double) NO Importe del cargo para la afiliación a registrar. Precisión hasta 8 valores enteros con 2 decimales
recurrence.maxAmount number($double) NO Importe máximo para los cargos de la afiliación a registrar. Precisión hasta 8 valores enteros con 2 decimales
recurrence.type string NO Tipo de pago recurrente
– FIXED Recurrencia fija
– VARIABLE Recurrencia variable
– FIXEDINITIAL
– Recurrencia fija más pago inicial
– VARIABLEINITIAL Recurrencia variable más pago inicial
currencyConversion json NO Entidad que representa información relacionada a la conversión DCC
(*) No es obligatorio cuando el canal es recurrente
currencyConversion.accepted boolean NO Indica si en la venta se usará o no DCC
currencyConversion.eligibilityCode string max 1 NO Valor retornado en la respuesta a la consulta de elegibilidad
– 0 Requerimiento DCC ha sido aceptado – 1 El requerimiento DCC ha sido rechazado basado en un error. Verifique los códigos de error para más detalle – 2 La tarjeta no fue encontrada en la CRT por lo que no puede ser considerada para DCC – 3 DCC no está permitido para la tarjeta – 4 No se requirió el servicio DCC
currencyConversion.currencyCode string max 3 NO Código de moneda DCC. El código de moneda aplicable al PAN. Este valor se encuentra en la búsqueda CRT (ISO 4217)
currencyConversion.currencyCodeAlpha string max 3 NO Código de moneda DCC en texto. El código de moneda expresado en texto, esto ayudará a la presentación de la oferta DCC
currencyConversion.amount number($double) NO Importe en moneda DCC. El monto en la moneda extranjera en la menor unidad de la moneda extranjera
currencyConversion.exponent integer($int32) NO El exponente extranjero utilizado en dar formato al monto
currencyConversion.exchangeRate number($double) NO Factor por el que el monto local es multiplicado para obtener el monto DCC
currencyConversion.wholeSaleRate number($double) NO Tasa de conversión antes de que se aplique la comisión
currencyConversion.markup number($double) NO Margen de beneficio aplicado a toda la tasa de venta
currencyConversion.rateSource string max 12 NO Nombre del origen de las tarifas extranjeras
currencyConversion.rateDate string max 6 NO Fecha en la que se obtuvo el tipo de cambio. Expresado como yyMMdd
currencyConversion.rateTime string max 6 NO Hora en la que se obtuvo el tipo de cambio. Expresado como hhMMss
currencyConversion.status string max 15 NO Estado obtenido en la consulta de elegibilidad DCC
– Authorized
– Not Authorized
currencyConversion.signature string max 41 NO Llave generada en la consulta de elegibilidad DCC


C. Request y Casos

  C.1 Tabla de parámetros

Campo Tipo Longitud Obligatorio Descripción
HEADER
accessToken Text max 1000 SI Token generado con el API de Seguridad
scope Text max 1000 SI JSON codificado en base64 obtenido en el paso de encriptación
URL
product text max 100 SI Identificador de producto
– ecommerce
– pospc
– recurrent
merchantId text max 100 SI Código de comercio
BODY
key string max 36 SI Token obtenido en la respuesta del API de Seguridad y que está relacionado a la llave y vector de encriptación que se usará en el Request original
payload string SI Request original encriptado con la llave token y vector iv obtenidos en la respuesta del API de Seguridad


  C.2 Trama de ejemplo:

Request

POST /api.authorization/v3/authorization/ecommerce/341198210 HTTP/1.1

Host: apitestenv.vnforapps.com

Content-Type: application/json

Authorization: eyJraWQiOiJmWk1tV3pZR0RBckxHektvalNCK2w3SjFhMnNPXC9zQn NwOTlNNmNuM3F5MD0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJjNTAxNjYyOS04Zjc2L TQ1M2QtYjhlNC01MGJjZDI5YjI2NTAiLCJldmVudF9pZCI6IjQzN2NlYTg5LWZkNmMtN GFhYS1hZDViLTdhZDFlYTBjZjY5NCIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlI joiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE2MDUxO TQyMDYsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC51cy1lYXN0LTEuYW1hem9uY XdzLmNvbVwvdXMtZWFzdC0xXzJjSjFTZTFmSSIsImV4cCI6MTYwNTE5NzgwNiwiaWF0I joxNjA1MTk0MjA2LCJqdGkiOiIyYTQ2ODJkOC1lNDczLTQxOTgtODc3OC0yMTFmY2QyM zg2ZTUiLCJjbGllbnRfaWQiOiIxMGx2MDYxN281ZGljNTFlYnNucWVpaWpiNyIsInVzZ XJuYW1lIjoiaW50ZWdyYWNpb25lcy52aXNhbmV0QG5lY29tcGx1cy5jb20ifQ.dO_IHr dcdDCcQ1V_fxRUGz4tmgufWlfK6udcHpq3oaBP6l0Wwn8N5KoG1_yEnGUYIlP8wrG2KJ Qz_ULO_wGB-HBlR2GfqVwq-wS0tyw_8PwwhcmTkUerR0eSTZPq-W5CeHyrRrLW4wYPih zgDeFOVGfssELK3bXevz6yR7K-daCc7Mjwpu1t4W35fsCeevRAovjs-dOy_sMLXtGnft cAOxkHUFDTbzQGcjNPE7h4qOcFLFSmBWBum2PkN5m-n7lQJn9NPQJGg-I7juF9h4Ja9f Aif6nbNQDNud3nynCFHWsljgfVfu1yTV3op-Jz4EhlVugPvKLMnRsKB05KGm-xug


Authorization: eyJzY29wZXMiOlt7ImtleSI6ImM1NmFlNDY3LTAxN2EtNGFiYi1iMj JmLWM0MWYzMjViM2M2MyIsImVsZW1lbnRzIjpbImNhcmQuY2FyZE51bWJlciIsImNhcm QuY3Z2MiJdfV19


{

 "key": "c56ae467-017a-4abb-b22f-c41f325b3c63",

 "payload": "FYUDVC1RQEjWGzQl7Hg1r66MQJMEOaZ1dT5yxZ+p/oRJyHcq0Gvx vfDm/u3SBjebOLUS6NZMGx6EH5GdQwkwNXqHzRjgQ4E5SWXpwYfq6eq//OXSwvDH1wT5o Hv3FVISrSD1apOeaZ4xFqSrxgCsUr2bZ3UJKktIo7a+sbU9JA+x3ZTwqpWq0SEIlNoeVJ Nt4NQCZ3Bid6KhbBOFBCbBTrKEIjOyefLUwnF9eeeQ3/7Aez2l151ZHxF8eribUj6xiQh Q3qB3DBoJqyUL5VhZrXEtW4fwdwyp+9h6RHmiZfCD7v/FGqqY+nJxNSOhyHN+5QXlBffx 1NfGrvpmCwVSp3ZFre2DskVzFPJxT71Fosxh0N+PoKlOwRxEDcIAug6+/ziOkf5IefH6n E0rQOWKl/RN3GO9fa1ZG+8gIyLFdxd/HFJr0Ne+K8ApvYxB//073V/HMdk8jWIt2wbuOr qULGBdCSNmClBy4yAohb2c0R7BLjac1e24C+LBUgX6mPetkYfxyntKPDRyd3zVy7pCdaY sAQl/x4unz+y+lQRXqzlT/ZMsPdttrn2/wJU5N8tGi5QXiZaX+c8IMV/CkP8rFApWIOmg LNknSHMnCrpJlSOA+CaEtQEJBN+PoQFUAdP618XeGOU7Mdo+RLq+MWxWwCVpYSsCtKWGr Vkda+wO6QTi7Owk3XphoxAp8NI9hUOvbQhZJTGIYz9lEZ7OI2PrtN0MI9iOQQt681oOXJ EawcSoGmMTf3e1y2z5jtDc0juRz2Xivfercg3B+llnTKFOFkiqW3QYaTYIJSxuc/Bpwyk HlV2e7d/wfQJT4CGR5IzpxRomDe8/WoA8INmH+ninfeFYjB9kJlsiljMgZItJWy8="

}



  C.3 Lenguajes:

  • Node
  • JavaScript
  • Python

const request = require('request');

const options = {

 method: 'POST',

 url: 'https://apitestenv.vnforapps.com/api.authorization/v3/authorization/product/merchantId',

 headers: {

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

  'Scope': '{{scope}}',

  accept: 'application/json',

  'content-type': 'application/json'

 },

 body: {

  key: "c56ae467-017a-4abb-b22f-c41f325b3c63",

payload:"FYUDVC1RQEjWGzQl7Hg1r66MQJMEOaZ1dT5yxZ+p/oRJyHcq0GvxvfDm/ u3SBjebOLUS6NZMGx6EH5GdQwkwNXqHzRjgQ4E5SWXpwYfq6eq//OXSwvDH1wT5oHv3FVISrSD1apO eaZ4xFqSrxgCsUr2bZ3UJKktIo7a+sbU9JA+x3ZTwqpWq0SEIlNoeVJNt4NQCZ3Bid6KhbBOFBCbBT rKEIjOyefLUwnF9eeeQ3/7Aez2l151ZHxF8eribUj6xiQhQ3qB3DBoJqyUL5VhZrXEtW4fwdwyp+9h 6RHmiZfCD7v/FGqqY+nJxNSOhyHN+5QXlBffx1NfGrvpmCwVSp3ZFre2DskVzFPJxT71Fosxh0N+Po KlOwRxEDcIAug6+/ziOkf5IefH6nE0rQOWKl/RN3GO9fa1ZG+8gIyLFdxd/HFJr0Ne+K8ApvYxB//0 73V/HMdk8jWIt2wbuOrqULGBdCSNmClBy4yAohb2c0R7BLjac1e24C+LBUgX6mPetkYfxyntKPDRyd 3zVy7pCdaYsAQl/x4unz+y+lQRXqzlT/ZMsPdttrn2/wJU5N8tGi5QXiZaX+c8IMV/CkP8rFApWIOm gLNknSHMnCrpJlSOA+CaEtQEJBN+PoQFUAdP618XeGOU7Mdo+RLq+MWxWwCVpYSsCtKWGrVkda+wO6 QTi7Owk3XphoxAp8NI9hUOvbQhZJTGIYz9lEZ7OI2PrtN0MI9iOQQt681oOXJEawcSoGmMTf3e1y2z 5jtDc0juRz2Xivfercg3B+llnTKFOFkiqW3QYaTYIJSxuc/BpwykHlV2e7d/wfQJT4CGR5IzpxRomD e8/WoA8INmH+ninfeFYjB9kJlsiljMgZItJWy8="

 },

 json: true

};

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 Obligatorio Descripción
TRAMA EXITOSA: 200
header json NO Entidad que representa el encabezado de respuesta a la petición
header.ecoreTransactionUUID string($uuid) NO Identificador único de transacción para la plataforma
header.ecoreTransactionDate string NO Fecha de la operación expresada en formato UNIX TimeStamp
header.millis integer($int32) NO Tiempo de ejecución de la operación
fulfillment json SI Entidad que representa información complementaria al pedido
fulfillment.channel string SI Canal desde donde se originó la operación.
– web: Si son operaciones realizadas con el botón de pago web
– mobile: Si son operaciones realizadas con la librería de pago app
– pasarela: Si son operaciones realizadas con la API de autorización para el producto comercio electrónico
– callcenter: Si son operaciones realizadas con la API de autorización para el producto telepago
fulfillment.merchantId string max 9 SI Código de comercio
fulfillment.terminalId string max 8 SI Número de terminal asociado a la transacción
fulfillment.captureType string max 6 SI Tipo de captura en el canal. Siempre es el valor manual
fulfillment.countable boolean SI Indica si la venta es contable true o no contable false
fulfillment.fastPayment boolean SI Indica si la venta es pago rápido true o no es pago rápido false
fulfillment.signature string($uuid) SI Código único generado por el sistema al momento de la venta
order json SI Entidad que representa la información del pedido
order.tokenId string max 32 NO Id del token de transacción obtenido en la respuesta a la validación antifraude o del formulario de pago
order.productId string max 10 NO Código del producto para la afiliación
order.purchaseNumber string max 12 SI Número de pedido generado por el comercio
order.amount number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
order.installment integer($int32) SI Número de cuotas en que se realizará el pago
order.currency string max 3 SI Código de moneda en la que se ejecuta la transacción
– PEN
– USD
order.externalTransactionId string($uuid) NO Identificador único de transacción enviado por el comercio
order.authorizedAmount number($double) SI Importe del pedido confirmado. Precisión hasta 8 valores enteros con 2 decimales
order.authorizationCode string max 6 SI Código de autorización asignado a la aprobación de la transacción por la entidad resolutora
order.actionCode string max 3 SI 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.traceNumber string max 6 SI Número asignado para identificar de forma unívoca a la transacción
order.transactionDate string SI Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
order.transactionId string max 15 SI Identificador de la transacción asociado a la autorización
dataMap json SI Entidad que representa información complementaria del pedido
dataMap.CURRENCY string max 4 SI Código numérico de moneda en la que se ejecuta la transacción
dataMap.TRANSACTION_DATE string SI Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
dataMap.ACTION_CODE string max 3 SI 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 SI Código único generado por el sistema
dataMap.ECI_DESCRIPTION string max 100 NO Descripción del código ECI asociado a la autenticación de la transacción
dataMap.ECI string max 2 SI Código ECI asociado a la autenticación de la transacción
dataMap.CARD string max 16 SI Número de tarjeta enmascarado usada en la venta
dataMap.MERCHANT string max 9 SI Código de comercio al cual pertenece la transacción
dataMap.STATUS string max 20 SI Descripción del estado de la transacción
– Authorized
– Not Authorized
– Confirmed
– Not Confirmed
– Verified
– Not Verified
– Voided
– Not Voided
– Reject
– Review
dataMap.ADQUIRENTE string max 15 SI Nombre de identificación del adquirente.
dataMap.BIN string max 6 NO 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 SI Marca de la tarjeta usada en la venta
– visa
– amex
– mastercard
– dinersclub
dataMap.SETTLEMENT string max 20 NO Indica si la operación está o no está liquidada
– Not Applicable
– Pending
– Automatic
– Completed
dataMap.ACTION_DESCRIPTION string max 100 SI Texto descriptivo de la autorización o denegación
dataMap.ID_UNICO string max 15 SI Id de la transacción asociado a la autorización
dataMap.AMOUNT number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
dataMap.AUTHORIZED_AMOUNT number($double) NO Importe del pedido confirmado. Precisión hasta 8 valores enteros con 2 decimales
dataMap.TRANSACTION_ID string max 15 SI Id de la transacción asociado a la autorización
dataMap.AUTHORIZATION_CODE string max 6 SI Código de autorización asignado a la aprobación de la transacción por la entidad resolutora
dataMap.CARD_TOKEN string max 16 NO Token identificador del objeto tokenizado
dataMap.VAULT_BLOCK string max 100 NO Valor del campo por el cual se tokeniza la tarjeta
dataMap.QUOTA_NUMBER integer($int32) NO Número de cuotas en que se realizó la venta
dataMap.QUOTA_AMOUNT number($double) NO Importe aproximado del valor de cuota. Precisión hasta 8 valores enteros con 2 decimales
dataMap.QUOTA_DEFERRED integer($int32) NO Indica si el pago en cuotas debe procesarse con pagos en diferido.
– 0 no diferido
– 1 o 2 diferido
dataMap.QUOTA_NI_PROGRAM integer($int32) NO Código de programa para cuota sin intereses
dataMap.QUOTA_NI_TYPE integer($int32) NO Indicador de tipo de cobro para cuotas sin intereses.
– 0 como porcentaje
– 1 como importe
dataMap.QUOTA_NI_AMOUNT number($double) NO Valor asociado al tipo de cobro para cuotas sin intereses
dataMap.QUOTA_NI_DISCOUNT number($double) NO Porcentaje de descuento que corresponde al emisor por el programa cuota sin intereses
dataMap.QUOTA_NI_MESSAGE string max 50 NO Mensaje asociado al cobro para cuota sin intereses
TRAMA ERRONEA: 400
errorCode integer($int32) SI Código de error de la operación. Siempre es el valor 400
errorMessage string SI Mensaje de error de la operación
header json NO Entidad que representa el encabezado de respuesta a la petición
header.ecoreTransactionUUID string($uuid) NO Identificador único de transacción para la plataforma
header.ecoreTransactionDate string NO Fecha de la operación expresada en formato UNIX TimeStamp
header.millis integer($int32) NO Tiempo de ejecución de la operación
data json SI Entidad que representa información relacionada a errores en la operación realizada
dataMap.CURRENCY string max 4 SI Código numérico de moneda en la que se ejecuta la transacción
dataMap.TRANSACTION_DATE string SI Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
dataMap.ACTION_CODE string max 3 SI 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 NO Código único generado por el sistema
data.ECI_DESCRIPTION string max 100 NO Descripción del código ECI asociado a la autenticación de la transacción
data.ECI string max 2 NO Código ECI asociado a la autenticación de la transacción
data.CARD string max 16 SI Número de tarjeta enmascarado usada en la venta
data.MERCHANT string max 9 SI Código de comercio al cual pertenece la transacción
data.STATUS string max 20 SI Descripción del estado de la transacción
– Authorized
– Not Authorized
– Confirmed
– Not Confirmed
– Verified
– Not Verified
– Voided
– Not Voided
– Reject
– Review
data.ADQUIRENTE string max 15 SI Nombre de identificación del adquirente.
data.BIN string max 6 NO Número de BIN de la tarjeta usada en la venta. Son los 6 primeros dígitos de una tarjeta
data.BRAND string max 15 SI Marca de la tarjeta usada en la venta
– visa
– amex
– mastercard
– dinersclub
data.SETTLEMENT string max 20 NO Indica si la operación está o no está liquidada
– Not Applicable
– Pending
– Automatic
– Completed
data.ACTION_DESCRIPTION string max 100 NO Texto descriptivo de la autorización o denegación
data.ID_UNICO string max 15 NO Identificador de la transacción asociado a la autorización
data.AMOUNT number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
data.AUTHORIZED_AMOUNT number($double) NO Importe del pedido confirmado. Precisión hasta 8 valores enteros con 2 decimales
data.TRANSACTION_ID string max 15 NO Id de la transacción asociado a la autorización
data.AUTHORIZATION_CODE string max 6 NO Código de autorización asignado a la aprobación de la transacción por la entidad resolutora
data.QUOTA_NUMBER integer($int32) NO Número de cuotas en que se realizó la venta
data.QUOTA_AMOUNT number($double) NO Importe aproximado del valor de cuota. Precisión hasta 8 valores enteros con 2 decimales
data.QUOTA_DEFERRED integer($int32) NO Indica si el pago en cuotas debe procesarse con pagos en diferido.
– 0 no diferido
– 1 o 2 diferido
data.QUOTA_NI_PROGRAM integer($int32) NO Código de programa para cuota sin intereses
data.QUOTA_NI_TYPE integer($int32) NO Indicador de tipo de cobro para cuotas sin intereses.
– 0 como porcentaje
– 1 como importe
data.QUOTA_NI_AMOUNT number($double) NO Valor asociado al tipo de cobro para cuotas sin intereses
data.QUOTA_NI_DISCOUNT number($double) NO Porcentaje de descuento que corresponde al emisor por el programa cuota sin intereses
data.QUOTA_NI_MESSAGE string max 50 NO Mensaje asociado al cobro para cuota sin intereses
TRAMA ERRONEA: 401
description text max 1000 NO Descripción relacionada al error. Este error se presenta cuando las credenciales no son válidas
TRAMA ERRONEA: 406
description text max 1000 NO Descripción relacionada al error. Este error se presenta cuando hay muchas solicitudes con la misma carga


  D.2 Trama de ejemplo:

  • Caso 200
  • Caso 400
  • Caso 401
  • Caso 406

Status Code 200 OK

Content-Type: application/json

{

 "header": {

  "ecoreTransactionUUID": "67a551c2-b586-42da-9f31-68309e460715",

  "ecoreTransactionDate": 1605194271097,

  "millis": 7488

 },

 "fulfillment": {

  "channel": "web",

  "merchantId": "341198210",

  "terminalId": "",

  "captureType": "manual",

  "countable": true,

  "fastPayment": false,

  "signature": "67a551c2-b586-42da-9f31-68309e460715"

 },

 "order": {

  "tokenId": "447D79B0A49C47F6BD79B0A49CB7F6A5",

  "purchaseNumber": "1234567890",

  "amount": 12.35,

  "installment": 0,

  "currency": "PEN",

  "authorizedAmount": 12.35,

  "authorizationCode": "007131",

  "actionCode": "000",

  "traceNumber": "273160",

  "transactionDate": "201112101748",

  "transactionId": "953203170000168"

 },

 "dataMap": {

  "TERMINAL": "00000001",

  "BRAND_ACTION_CODE": "00",

  "BRAND_HOST_DATE_TIME": "201112101401",

  "TRACE_NUMBER": "273160",

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

  "CARD_TYPE": "C",

  "SIGNATURE": "67a551c2-b586-42da-9f31-68309e460715",

  "CARD": "544359******0447",

  "MERCHANT": "341198210",

  "STATUS": "Authorized",

  "ACTION_DESCRIPTION": "Aprobado y completado con exito",

  "ID_UNICO": "953203170000168",

  "AMOUNT": "12.35",

  "BRAND_HOST_ID": "500228",

  "AUTHORIZATION_CODE": "007131",

  "CURRENCY": "0604",

  "TRANSACTION_DATE": "201112101748",

  "ACTION_CODE": "000",

  "CVV2_VALIDATION_RESULT": "M",

  "ECI": "07",

  "ID_RESOLUTOR": "031758787729",

  "BRAND": "mastercard",

  "ADQUIRENTE": "570009",

  "BRAND_NAME": "MC",

  "PROCESS_CODE": "000000",

  "TRANSACTION_ID": "953203170000168"

  }

 }



E. Códigos de Respuesta

Respuesta Descripción
200 Autorización de venta realizada con éxito
400 Error en la autorización de la venta
401 Error relacionado al acceso no autorizado
406 Error por enviar muchas solicitudes con la misma carga

API de Antifraude con Alcance Cifrado #

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.


A. Endpoint

Ambiente URL de API
Testing ‘https://apitestenv.vnforapps.com/api.authorization/v3/authorization/{product}/{merchantId}
Producción ‘https://apiprod.vnforapps.com/api.authorization/v3/authorization/{product}/{merchantId}


B. Cifrado

En este punto se detallan los parámetros de encriptación del algoritmo AES y los elementos a codificar o encriptar.

   B.1 Parámetros de encriptación

  • Algoritmo de encriptación: AES
  • Modo de encriptación: CBC
  • Relleno: PKCS7
  • Tamaño de la llave: 256 bits
  • Tamaño de bloque: 128 bits
  • Llave: token (se obtiene del API de seguridad) se requiere convertir de string hexadecimal a byte array.
  • Vector de inicialización: iv (se obtiene del API de seguridad) se requiere convertir de string hexadecimal a byte array.

   B.2 Scope (codificación base64)

Request

{

 "scopes": [

 {

  "key": "9be588af-dd65-4ec3-a0c3-7eaff3c2642a",

  "elements": [

   "card.cardNumber",

   "card.cvv2"

  ]

 }

 ]

}


Campo Tipo Longitud Obligatorio Descripción
key text max 36 SI Token relacionado a la llave de encriptación a utilizar obtenido en la respuesta del API de Seguridad
elements array SI Referencia a los atributos encriptados en el cuerpo de la consulta


C. Request y Casos

  C.1 Tabla de Parámetros

Campo Tipo Longitud Obligatorio Descripción
HEADER
accessToken Text max 1000 SI Token generado con el API de Seguridad
scope Text max 1000 SI JSON codificado en base64 obtenido en el paso de encriptación
URL
product text max 100 SI Identificador de producto
– ecommerce
– pospc
– recurrent
merchantId text max 100 SI Código de comercio
BODY
channel String SI Canal desde donde se originó la operación.
– web Si son operaciones realizadas con el botón de pago web
– mobile Si son operaciones realizadas con la librería de pago app
– pasarela Si son operaciones realizadas con la API de autorización para el producto comercio electrónico
– callcenter Si son operaciones realizadas con la API de autorización para el producto telepago
– recurrent Si son operaciones realizadas con la API de autorización para el producto pago programado
clientIp string max 13 SI Dirección IP desde donde se originó la operación.
deviceFingerprintId string max 36 SI Id del dispositivo.
merchantDefineData string NO Entidad que representa a datos adicionales enviados por el comercio
billingAddress Json NO Entidad que representa información de dirección
billingAddress.street1 String max 30 NO Dirección número uno
billingAddress.street2 String max 30 NO Dirección número dos
billingAddress.postalCode Integer max 5 NO Código postal
billingAddress.city String max 20 NO Nombre de la ciudad
billingAddress.state String max 20 NO Nombre del departamento o estado
billingAddress.country String max 2 NO Código ISO-3166 del país
shippingAddress String NO Entidad que representa información de dirección
shippingAddress.street1 String max 30 NO Dirección número uno
shippingAddress.street2 String max 30 NO Dirección número dos
shippingAddress.postalCode Integer max 5 NO Código postal
shippingAddress.city String max 20 NO Nombre de la ciudad
shippingAddress.state String max 20 NO Nombre del departamento o estado
shippingAddress.country String max 2 NO Código ISO-3166 del país
order Json SI Entidad que representa la información del pedido
order.purchaseNumber string max 12 SI Número de pedido generado por el comercio
order.amount number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
order.currency string max 3 SI Código de moneda en la que se ejecuta la transacción
– PEN
– USD
card json SI Entidad que representa información de la tarjeta
card json SI Entidad que representa información de la tarjeta
card.cardNumber string max 16 SI Número de la tarjeta
card.expirationMonth integer($int32) SI Mes de expiración
card.expirationYear integer($int32) SI Año de expiración
card.cvv2 string max 3 NO Número de CVV2 de la tarjeta encriptado con la llave baseKey y vector iv obtenidos en la respuesta del api.security
cardHolder json NO Entidad que representa la información del tarjetahabiente
cardHolder.firstName string max 25 NO Nombres del tarjetahabiente
cardHolder.lastName string max 50 NO Apellidos del tarjetahabiente
cardHolder.email string max 35 NO Correo electrónico del tarjetahabiente
(*) Se envía obligatoriamente cuando la tarjeta es tokenizada
cardHolder.phoneNumber string max 10 NO Teléfono del tarjetahabiente
currencyConversion json NO Entidad que representa información relacionada a la conversión DCC
(*) No es obligatorio cuando el canal es recurrente
currencyConversion.accepted boolean SI Indica si en la venta se usará o no DCC
currencyConversion.eligibilityCode string max 1 SI Indica si en la venta se usará o no DCC
– 0 Requerimiento DCC ha sido aceptado
– 1 El requerimiento DCC ha sido rechazado basado en un error. Verifique los códigos de error para más detalle
– 2 La tarjeta no fue encontrada en la CRT por lo que no puede ser considerada para DCC
– 3 DCC no está permitido para la tarjeta
– 4 No se requirió el servicio DCC
currencyConversion.currencyCode string max 3 SI Código de moneda DCC. El código de moneda aplicable al PAN. Este valor se encuentra en la búsqueda CRT (ISO 4217)
currencyConversion.currencyCodeAlpha string max 3 SI Código de moneda DCC en texto. El código de moneda expresado en texto, esto ayudará a la presentación de la oferta DCC
currencyConversion.amount number($double) SI Importe en moneda DCC. El monto en la moneda extranjera en la menor unidad de la moneda extranjera
currencyConversion.exponent integer($int32) SI El exponente extranjero utilizado en dar formato al monto
currencyConversion.exchangeRate number($double) SI Factor por el que el monto local es multiplicado para obtener el monto DCC
currencyConversion.wholeSaleRate number($double) SI Tasa de conversión antes de que se aplique la comisión
currencyConversion.markup number($double) SI Margen de beneficio aplicado a toda la tasa de venta
currencyConversion.rateSource string max 12 SI Nombre del origen de las tarifas extranjeras
currencyConversion.rateDate string max 6 SI Fecha en la que se obtuvo el tipo de cambio. Expresado como yyMMdd
currencyConversion.rateTime string max 6 SI Hora en la que se obtuvo el tipo de cambio. Expresado como hhMMss
currencyConversion.status string max 15 SI Estado obtenido en la consulta de elegibilidad DCC
– Authorized
– Not Authorized
currencyConversion.signature string max 41 SI Llave generada en la consulta de elegibilidad DCC


  C.2 Trama de ejemplo:

Request

POST /api.authorization/v3/authorization/ecommerce/341198210 HTTP/1.1

Host: apitestenv.vnforapps.com

Content-Type: application/json

Authorization: eyJraWQiOiJmWk1tV3pZR0RBckxHektvalNCK2w3SjFhMnNPXC9zQn NwOTlNNmNuM3F5MD0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJjNTAxNjYyOS04Zjc2L TQ1M2QtYjhlNC01MGJjZDI5YjI2NTAiLCJldmVudF9pZCI6IjY1YWRkODk0LTFiMzYtN DFmOC1iZmEyLTQ5NWU5NzYzOTQzZSIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlI joiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE2MDUyM DU0ODksImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC51cy1lYXN0LTEuYW1hem9uY XdzLmNvbVwvdXMtZWFzdC0xXzJjSjFTZTFmSSIsImV4cCI6MTYwNTIwOTA4OSwiaWF0I joxNjA1MjA1NDg5LCJqdGkiOiJkYjU3ZDIxYi05NTRjLTQ5OTgtYjZmNC0zNzdhNjMxZ TdkY2MiLCJjbGllbnRfaWQiOiIxMGx2MDYxN281ZGljNTFlYnNucWVpaWpiNyIsInVzZ XJuYW1lIjoiaW50ZWdyYWNpb25lcy52aXNhbmV0QG5lY29tcGx1cy5jb20ifQ.BBkgv_ wg6DOu9Wh1CpbeRnlu8niNnxXOUnYB4IKdetIDBVV8ec1pyz5O2saPTdyAjdHN12k7Jl fMfVinnZlVVze8rQ-alqq1IjEvzDGp_cBbhZRE-wl5-Kgavw3gG-WWEFVJtqvz23qTom ZtsGmzxUyArQaTKNrsMWUqUgA_RRkTtwNdZNbcb_ysTsTAnHMqPP6zkGZRfaWEh8nuwo XC-SEutXwdD3XXthAoEeGIhmMrKih7gPBGUbJ9buorUQBnTEQNYq85HkLuz15wiUp91s OjDOl7OjN5LjIuZvOLFZ9kKWpuK9Bh-S-EOjXBBwKrcF_9RjrCeqHz8y3mhzXjtg


Scope: eyJzY29wZXMiOlt7ImtleSI6ImRiNTNiNDNiLTIxNjQtNDM0ZS05N2NhLTQ4Mjh lZDFiYThiMSIsImVsZW1lbnRzIjpbImNhcmQuY2FyZE51bWJlciIsImNhcmQuY3Z2MiJd fV19


{

 "channel": "web",

 "order": {

  "purchaseNumber": "1234567890",

  "amount": 12.35,

  "currency": "PEN"

 },

 "card": {

  "cardNumber": "xnEvZd9u+2jNUCiOucxI141AOy5/cCyAfYuJC/xH4eU=",

  "expirationMonth": 12,

  "expirationYear": 2021,

  "cvv2": "I4s8P1K6SrnlgfUoeRqRlw=="

 },

 "cardHolder": {

  "firstName": "Juan",

  "lastName": "Crespo",

  "email": "juan.c@latinmail.com",

  "phoneNumber": "5112223333"

 }

}



  C.3 Lenguajes:

  • Node
  • JavaScript
  • Python

const request = require('request');

const options = {

 method: 'POST',

 url: 'https://apitestenv.vnforapps.com/api.authorization/v3/authorization/ecommerce/341198210',

 headers: {

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

  'Scope': '{{scope}}',

  accept: 'application/json',

  'content-type': 'application/json'

 },

 body: {

 "channel": "web",

 "order": {

  "purchaseNumber": "1234567890",

  "amount": 12.35,

  "currency": "PEN"

 },

 "card": {

  "cardNumber": "xnEvZd9u+2jNUCiOucxI141AOy5/cCyAfYuJC/xH4eU=",

  "expirationMonth": 12,

  "expirationYear": 2021,

  "cvv2": "I4s8P1K6SrnlgfUoeRqRlw=="

 },

 "cardHolder": {

  "firstName": "Juan",

  "lastName": "Crespo",

  "email": "juan.c@latinmail.com",

  "phoneNumber": "5112223333"

 }

},

 json: true

};

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 Obligatorio Descripción
TRAMA EXITOSA: 200
header json NO Entidad que representa el encabezado de respuesta a la petición
header.ecoreTransactionUUID string($uuid) NO Identificador único de transacción para la plataforma
header.ecoreTransactionDate string NO Fecha de la operación expresada en formato UNIX TimeStamp
header.millis integer($int32) NO Tiempo de ejecución de la operación
order json SI Entidad que representa la información del pedido
order.purchaseNumber string max 12 SI Número de pedido generado por el comercio
order.amount number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
order.currency string max 3 SI Código de moneda en la que se ejecuta la transacción
– PEN
– USD
order.billingAddress json NO Entidad que representa información de dirección
order.billingAddress.street1 String max 30 NO Dirección número uno
order.billingAddress.street2 string max 30 NO Dirección número dos
order.billingAddress.postalCode integer($int32) max 5 NO Código postal
order.billingAddress.city string max 20 NO Nombre de la ciudad
order.billingAddress.state string max 20 NO Nombre del departamento o estado
order.billingAddress.country string max 2 NO Código ISO-3166 del país
order.shippingAddress json NO Entidad que representa información de dirección
order.shippingAddress.street1 string max 30 NO Dirección número uno
order.shippingAddress.street2 string max 30 NO Dirección número dos
order.shippingAddress.postalCode integer($int32) max 5 NO Código postal
order.shippingAddress.city string max 20 NO Nombre de la ciudad
order.shippingAddress.state string max 20 NO Nombre del departamento o estado
order.shippingAddress.country string max 2 NO Código ISO-3166 del país
token json NO Entidad que representa información de la tokenización para la tarjeta utilizada
(*) Solo si se usa el esquema de tokenización
token.tokenId string max 16 SI Token identificador del objeto tokenizado
(*) Solo si se usa el esquema de tokenización
token.expiration string SI Fecha de caducidad del token expresado en formato nativo yyMMddHHmmSS
(*) Solo si se usa el esquema de tokenización
redirectToVbV boolean SI Indicador de participación en verified by visa.
dataMap json SI Entidad que representa información complementaria del pedido
dataMap.TRANSACTION_DATE string NO Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
MESSAGE string max 50 NO Texto descriptivo de la calificación de la venta en el sistema antifraude
REQUEST_TOKEN string max 60 NO Firma generada por la calificación de la venta en el sistema antifraude
DECISION string max 6 SI Estado de la transacción después de la calificación de la venta en el sistema antifraude
dataMap.ACTION_CODE string max 3 NO 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
REASON_CODE string max 3 NO Código de razón obtenido en la respuesta a la calificación de la venta en el sistema antifraude
REQUEST_ID string max 25 NO Id único generado por la calificación de la venta en el sistema antifraude
TRAMA ERRONEA: 400
errorCode integer($int32) SI Código de error de la operación. Siempre es el valor 400
errorMessage string SI Mensaje de error de la operación
header json SI Entidad que representa el encabezado de respuesta a la petición
header.ecoreTransactionUUID string($uuid) SI Identificador único de transacción para la plataforma
header.ecoreTransactionDate string SI Fecha de la operación expresada en formato UNIX TimeStamp
header.millis integer($int32) SI Tiempo de ejecución de la operación
data json NO Entidad que representa información relacionada a errores en la operación realizada
dataMap.TRANSACTION_DATE string NO Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
MESSAGE string max 50 NO Texto descriptivo de la calificación de la venta en el sistema antifraude
REQUEST_TOKEN string max 60 NO Firma generada por la calificación de la venta en el sistema antifraude
DECISION string max 6 NO Estado de la transacción después de la calificación de la venta en el sistema antifraude
dataMap.ACTION_CODE string max 3 NO 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
REASON_CODE string max 3 NO Código de razón obtenido en la respuesta a la calificación de la venta en el sistema antifraude
REQUEST_ID string max 25 NO max 25
TRAMA ERRONEA: 401
description text max 1000 NO 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": "71504254-21f0-452d-afe4-92509fe07aec",

  "ecoreTransactionDate": 1605205538407,

  "millis": 1140

 },

 "order": {

  "purchaseNumber": "1234567890",

  "amount": 12.35,

  "currency": "PEN"

 },

 "token": {

  "TERMINAL": "00000001",

  "tokenId": "5865661276004069A566127600B06907",

  "expiration": 1605206138354,

  "redirectToVbV": false,

  "mpi": false,

  "dataMap": {}

 },

 "dataMap": {

  "DECISION": "Accept"

 }

}



E. Códigos de Respuesta

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

API de Antifraude con Petición Cifrada #

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.


A. Endpoint

Ambiente URL de API
Testing https://apitestenv.vnforapps.com/api.authorization/v3/authorization/{product}/{merchantId}
Producción https://apiprod.vnforapps.com/api.authorization/v3/authorization/{product}/{merchantId}


B. Cifrado

En este punto se detallan los parámetros de encriptación del algoritmo AES y los elementos a codificar o encriptar.

   B.1 Parámetros de encriptación

  • Algoritmo de encriptación: AES
  • Modo de encriptación: CBC
  • Relleno: PKCS7
  • Tamaño de la llave: 256 bits
  • Tamaño de bloque: 128 bits
  • Llave: token (se obtiene del API de seguridad) se requiere convertir de string hexadecimal a byte array.
  • Vector de inicialización: iv (se obtiene del API de seguridad) se requiere convertir de string hexadecimal a byte array.


   B.2 Request original (encriptación AES)

Request

{

 "channel": "web",

 "order": {

  "purchaseNumber": "1234567890",

  "amount": 12.35,

  "currency": "PEN"

 },

 "card": {

  "cardNumber": "xnEvZd9u+2jNUCiOucxI141AOy5/cCyAfYuJC/xH4eU=",

  "expirationMonth": 12,

  "expirationYear": 2021,

  "cvv2": "I4s8P1K6SrnlgfUoeRqRlw=="

 },

 "cardHolder": {

  "firstName": "Juan",

  "lastName": "Crespo",

  "email": "juan.c@latinmail.com",

  "phoneNumber": "5112223333"

 }

}


Campo Tipo Longitud Obligatorio Descripción
channel String SI Canal desde donde se originó la operación.
– web Si son operaciones realizadas con el botón de pago web
– mobile Si son operaciones realizadas con la librería de pago app
– pasarela Si son operaciones realizadas con la API de autorización para el producto comercio electrónico
– callcenter Si son operaciones realizadas con la API de autorización para el producto telepago
– recurrent Si son operaciones realizadas con la API de autorización para el producto pago programado
clientIp String max 13 SI Dirección IP desde donde se originó la operación.
deviceFingerprintId string max 36 SI Id del dispositivo.
merchantDefineData string NO Entidad que representa a datos adicionales enviados por el comercio
billingAddress Json NO Entidad que representa información de dirección
billingAddress.street1 string max 30 NO Dirección número uno
billingAddress.street2 string max 30 NO Dirección número dos
billingAddress.postalCode Integer max 5 NO Código postal
billingAddress.city String max 20 NO Nombre de la ciudad
billingAddress.state String max 20 NO Nombre del departamento o estado
billingAddress.country String max 2 NO Código ISO-3166 del país
shippingAddress String NO Entidad que representa información de dirección
shippingAddress.street1 String max 30 NO Dirección número uno
shippingAddress.street2 String max 30 NO Dirección número dos
shippingAddress.postalCode Integer max 5 NO Código postal
shippingAddress.city String max 20 NO Nombre de la ciudad
shippingAddress.state String max 20 NO Nombre del departamento o estado
shippingAddress.country String max 2 NO Código ISO-3166 del país
order Json SI Entidad que representa la información del pedido
order.purchaseNumber string max 12 SI Número de pedido generado por el comercio
order.amount Number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
order.currency String Max 3 SI Código de moneda en la que se ejecuta la transacción
– PEN
– USD
card json SI Entidad que representa información de la tarjeta
card.cardNumber String max 16 SI Número de la tarjeta
card.expirationMonth Integer($int32) SI Mes de expiración
card.expirationYear Integer($int32) SI Año de expiración
card.cvv2 String max 3 SI Número de CVV2 de la tarjeta encriptado con la llave baseKey y vector iv obtenidos en la respuesta del api.security
cardHolder Json NO Entidad que representa la información del tarjetahabiente
cardHolder.firstName String Max 25 NO Nombres del tarjetahabiente
cardHolder.lastName String Max 50 NO Apellidos del tarjetahabiente
cardHolder.email String Max 35 NO Correo electrónico del tarjetahabiente
(*) Se envía obligatoriamente cuando la tarjeta es tokenizada
cardHolder.phoneNumber String max 10 NO Teléfono del tarjetahabiente
currencyConversion json NO Entidad que representa información relacionada a la conversión DCC
(*) No es obligatorio cuando el canal es recurrente
currencyConversion.accepted boolean SI Indica si en la venta se usará o no DCC
currencyConversion.eligibilityCode string max 1 SI Valor retornado en la respuesta a la consulta de elegibilidad
– 0 Requerimiento DCC ha sido aceptado – 1 El requerimiento DCC ha sido rechazado basado en un error. Verifique los códigos de error para más detalle – 2 La tarjeta no fue encontrada en la CRT por lo que no puede ser considerada para DCC – 3 DCC no está permitido para la tarjeta – 4 No se requirió el servicio DCC
currencyConversion.currencyCode string max 3 SI Código de moneda DCC. El código de moneda aplicable al PAN. Este valor se encuentra en la búsqueda CRT (ISO 4217)
currencyConversion.currencyCodeAlpha string max 3 SI Código de moneda DCC en texto. El código de moneda expresado en texto, esto ayudará a la presentación de la oferta DCC
currencyConversion.amount number($double) SI Importe en moneda DCC. El monto en la moneda extranjera en la menor unidad de la moneda extranjera
currencyConversion.exponent integer($int32) SI El exponente extranjero utilizado en dar formato al monto
currencyConversion.exchangeRate number($double) SI Factor por el que el monto local es multiplicado para obtener el monto DCC
currencyConversion.wholeSaleRate number($double) SI Tasa de conversión antes de que se aplique la comisión
currencyConversion.markup number($double) SI Margen de beneficio aplicado a toda la tasa de venta
currencyConversion.rateSource string max 12 SI Nombre del origen de las tarifas extranjeras
currencyConversion.rateDate string max 6 SI Fecha en la que se obtuvo el tipo de cambio. Expresado como yyMMdd
currencyConversion.rateTime string max 6 SI Hora en la que se obtuvo el tipo de cambio. Expresado como hhMMss
currencyConversion.status string max 15 SI Estado obtenido en la consulta de elegibilidad DCC
– Authorized
– Not Authorized
currencyConversion.signature string max 41 SI Llave generada en la consulta de elegibilidad DCC


C. Request y Casos

  C.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
product text max 100 SI Identificador de producto
– ecommerce
– pospc
– recurrent
merchantId text max 100 SI Código de comercio
BODY
key string max 36 SI
payload string max 100 SI


  C.2 Trama de ejemplo:

Request

POST /api.authorization/v3/authorization/ecommerce/341198210 HTTP/1.1

Host: apitestenv.vnforapps.com

Content-Type: application/json

Authorization: eyJraWQiOiJmWk1tV3pZR0RBckxHektvalNCK2w3SjFhMnNPXC9zQn NwOTlNNmNuM3F5MD0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJjNTAxNjYyOS04Zjc2L TQ1M2QtYjhlNC01MGJjZDI5YjI2NTAiLCJldmVudF9pZCI6IjBlNDY3MTA5LWYzM2YtN GU5NS05YTlmLTIxYWU3NjhlZTEzMSIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlI joiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE2MDUyM DczMzAsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC51cy1lYXN0LTEuYW1hem9uY XdzLmNvbVwvdXMtZWFzdC0xXzJjSjFTZTFmSSIsImV4cCI6MTYwNTIxMDkzMCwiaWF0I joxNjA1MjA3MzMwLCJqdGkiOiI2ZWIyYmU2MC0yMGFiLTRjMGMtOGUyZC0zZGY3YTMxN jFmYTQiLCJjbGllbnRfaWQiOiIxMGx2MDYxN281ZGljNTFlYnNucWVpaWpiNyIsInVzZ XJuYW1lIjoiaW50ZWdyYWNpb25lcy52aXNhbmV0QG5lY29tcGx1cy5jb20ifQ.B8rZap cJgt4TZc3VxEGp9S_EW0FbCDfrJcm3ubUtAqexo7QRHzKOtaUyzlfE3Irm_a_JDE8vjj Ntk-gaWa3gxMk7smLXPb32h8QtynFtmiWtmtOE4JOcyFkquXZMoHvF07zxGuMmfKjP6Y 7yrFfyO92jSX2UeDF421Mm8WVGeYG4Sfkzc74cgIURP_gh-l70fPLaMRD92p2DYoyrpt t30c64jsvZDIR44DD98BgR3r2w4OPO0QG7_6yY5tqe0ls1p_G7a4DhSWJogkU06VbQiw Uq9DN3Dti02BSA24Wu1gI-N9B9Nrx8rZzMDnLh4HcUo0V0zvPrLxN1KkR7zPb07A

{

"key": "c007b5d7-178c-4cdf-a610-1e7802067dbc",

"payload":"lka/Tk+HDvp4rG/ioe+jd8dS/VhMYa4wv1Z1k/393zab+e3B0RlzK/cnqG ga2IXh07UA6vXyTTZz4WklmeKJMlBNmSBfGxIuY22e+XQP04UXWegxp/xvihb/9CTiDL0 Ql09WC5wwmkcTTVr4SPMuPIZ8BOHdebeh62LUzGB8ewpIOicNWZ3Ae0tGLdRUWmf9wu71 rG6ObSaVijYDmPNMXCkJu2uoRFeK9YLybUxnnuX01jrQ3m1D8xWyoUXDq7GyjIBscVMNW D9k7bK/dEHnLEDDj9Ov4yYpX0j/ajd2m0gtElZhL5c9EWAPFs+PHSLR+AeaDAUeRiAzXz wLAtbw4CjAGpXat3TmGyrTBDN8j37AVp15/qRDHhw0efSMDfY0+38bUVjmulw48aI4C0/ LgFRK2v4kI/5HaE8+WJ4nArLuM3Mc0CXYdQgUHxkzD9yMjTa9kmaI10V0Ldz6yQw0dSJy 0phoYwa2mrrPhXgPoOUUAZOfAmgI019nqwloKVd5/dSoRGqvc8KqNAOu1DOjVvFtH6UNI 3SK3LzR+DXRIIm1AGfND6w/EpJSCIwSc5aCLhBrQNOw4FCwtflVJCpCAOAvCWIAL5a0K+ b33gd1N8zgYp+h9iFM3dNn5PJXHyonorMDseJa7BeKQW5UvvO/RFDR65djEFtwyfY5XtX Z2V/P4fRe5jLaRY+N2txh4eCd0KC+djCST8bTcb3WibE3kz1F9mnIWf86xxYGYInvu1TR 35mki1ZeLRkTIaKGx4zq35zv96lExll/ARfFLb3QCdC+/U72I5SsFmzK0ID+FQTxzWJYcb9FJ/oSjjfKUhul"

}



  C.3 Lenguajes:

  • Node
  • JavaScript
  • Python

const request = require('request');

const options = {

 method: 'POST',

 url: 'https://apitestenv.vnforapps.com/api.antifraud/v1/antifraud/ecommerce/341198210',

 headers: {

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

  accept: 'application/json',

  'content-type': 'application/json'

 },

 body: {

  "key": "c007b5d7-178c-4cdf-a610-1e7802067dbc",

"payload":"lka/Tk+HDvp4rG/ioe+jd8dS/VhMYa4wv1Z1k/393zab+e3B0RlzK/cnqGga2IXh07 UA6vXyTTZz4WklmeKJMlBNmSBfGxIuY22e+XQP04UXWegxp/xvihb/9CTiDL0Ql09WC5wwmkcTTV r4SPMuPIZ8BOHdebeh62LUzGB8ewpIOicNWZ3Ae0tGLdRUWmf9wu71rG6ObSaVijYDmPNMXCkJu2 uoRFeK9YLybUxnnuX01jrQ3m1D8xWyoUXDq7GyjIBscVMNWD9k7bK/dEHnLEDDj9Ov4yYpX0j/aj d2m0gtElZhL5c9EWAPFs+PHSLR+AeaDAUeRiAzXzwLAtbw4CjAGpXat3TmGyrTBDN8j37AVp15/q RDHhw0efSMDfY0+38bUVjmulw48aI4C0/LgFRK2v4kI/5HaE8+WJ4nArLuM3Mc0CXYdQgUHxkzD9 yMjTa9kmaI10V0Ldz6yQw0dSJy0phoYwa2mrrPhXgPoOUUAZOfAmgI019nqwloKVd5/dSoRGqvc8 KqNAOu1DOjVvFtH6UNI3SK3LzR+DXRIIm1AGfND6w/EpJSCIwSc5aCLhBrQNOw4FCwtflVJCpCAO AvCWIAL5a0K+b33gd1N8zgYp+h9iFM3dNn5PJXHyonorMDseJa7BeKQW5UvvO/RFDR65djEFtwyf Y5XtXZ2V/P4fRe5jLaRY+N2txh4eCd0KC+djCST8bTcb3WibE3kz1F9mnIWf86xxYGYInvu1TR35 mki1ZeLRkTIaKGx4zq35zv96lExll/ARfFLb3QCdC+/U72I5SsFmzK0ID+FQTxzWJYcb9FJ/oSjj fKUhul"

  },

  json: true

 };

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 Obligatorio Descripción
TRAMA EXITOSA: 200
header json NO Entidad que representa el encabezado de respuesta a la petición
header.ecoreTransactionUUID string($uuid) NO Identificador único de transacción para la plataforma
header.ecoreTransactionDate string NO Fecha de la operación expresada en formato UNIX TimeStamp
header.millis integer($int32) NO Tiempo de ejecución de la operación
order json SI Entidad que representa la información del pedido
order.purchaseNumber string max 12 SI Número de pedido generado por el comercio
order.amount number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
order.currency string max 3 SI Código de moneda en la que se ejecuta la transacción
– PEN
– USD
order.billingAddress json NO Entidad que representa información de dirección
order.billingAddress.street1 string max 30 NO Dirección número uno
order.billingAddress.street2 string max 30 NO Dirección número dos
order.billingAddress.postalCode integer($int32) max 5 NO Código postal
order.billingAddress.city String max 20 NO Nombre de la ciudad
order.billingAddress.state string max 20 NO Nombre del departamento o estado
order.billingAddress.country string max 2 NO Código ISO-3166 del país
order.shippingAddress json NO Entidad que representa información de dirección
order.shippingAddress.street1 string max 30 NO Dirección número uno
order.shippingAddress.street2 string max 30 NO Dirección número dos
order.shippingAddress.postalCode integer($int32) max 5 NO Código postal
order.shippingAddress.city string max 20 NO Nombre de la ciudad
order.shippingAddress.state string max 20 NO Nombre del departamento o estado
order.shippingAddress.country string max 2 NO Código ISO-3166 del país
token json NO Entidad que representa información de la tokenización para la tarjeta utilizada
(*) Solo si se usa el esquema de tokenización
token.tokenId string max 16 SI Token identificador del objeto tokenizado
(*) Solo si se usa el esquema de tokenización
token.expiration string SI Fecha de caducidad del token expresado en formato nativo yyMMddHHmmSS
(*) Solo si se usa el esquema de tokenización
redirectToVbV boolean SI Indicador de participación en verified by visa
dataMap json SI Entidad que representa información complementaria del pedido
dataMap.TRANSACTION_DATE string NO Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
MESSAGE string max 50 NO Texto descriptivo de la calificación de la venta en el sistema antifraude
REQUEST_TOKEN string max 60 NO Firma generada por la calificación de la venta en el sistema antifraude
DECISION string max 6 SI Estado de la transacción después de la calificación de la venta en el sistema antifraude
dataMap.ACTION_CODE string max 3 NO 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
REASON_CODE string max 3 NO Código de razón obtenido en la respuesta a la calificación de la venta en el sistema antifraude
REQUEST_ID string max 25 NO Id único generado por la calificación de la venta en el sistema antifraude
TRAMA ERRONEA: 400
errorCode integer($int32) SI Código de error de la operación. Siempre es el valor 400
errorMessage string SI Mensaje de error de la operación
header json SI Entidad que representa el encabezado de respuesta a la petición
header.ecoreTransactionUUID string($uuid) SI Identificador único de transacción para la plataforma
header.ecoreTransactionDate string SI Fecha de la operación expresada en formato UNIX TimeStamp
header.millis integer($int32) SI Tiempo de ejecución de la operación
data json NO Entidad que representa información relacionada a errores en la operación realizada
dataMap.TRANSACTION_DATE string SI Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
MESSAGE string max 50 SI Texto descriptivo de la calificación de la venta en el sistema antifraude
REQUEST_TOKEN string max 60 SI Firma generada por la calificación de la venta en el sistema antifraude
DECISION string max 6 SI Estado de la transacción después de la calificación de la venta en el sistema antifraude
dataMap.ACTION_CODE string max 3 SI 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
REASON_CODE string max 3 SI Código de razón obtenido en la respuesta a la calificación de la venta en el sistema antifraude
REQUEST_ID string max 25 SI Id único generado por la calificación de la venta en el sistema antifraude
TRAMA ERRONEA: 401
description text max 1000 NO 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": "b3806e11-1fe7-4f82-b46e-b351d38ec51b",

  "ecoreTransactionDate": 1605207370805,

  "millis": 1807

 },

 "order": {

  "purchaseNumber": "1234567890",

  "amount": 12.35,

  "installment": 0,

  "currency": "PEN",

  "authorizedAmount": 0.0

 },

 "token": {

  "TERMINAL": "00000001",

  "tokenId": "A017DCBB8335406197DCBB8335806191",

  "expiration": 1605207970754,

  "redirectToVbV": false,

  "mpi": false,

  "dataMap": {},

  "dataMap": {

   "DECISION": "Accept"

 }

}

}



E. Códigos de Respuesta

Respuesta Descripción
200 Validación de antifraude realizada con éxito
400 Error en la validación de antifraude
401 Error relacionado al acceso no autorizado

API de Antifraude con Alcance y Petición Cifrada #

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.


A. Endpoint

Ambiente URL de API
Testing https://apitestenv.vnforapps.com/api.antifraud/v1/antifraud/{product}/{merchantId}
Producción https://apiprod.vnforapps.com/api.antifraud/v1/antifraud/{product}/{merchantId}


B. Cifrado

En este punto se detallan los parámetros de encriptación del algoritmo AES y los elementos a codificar o encriptar.

   B.1 Parámetros de encriptación

  • Algoritmo de encriptación: AES
  • Modo de encriptación: CBC
  • Relleno: PKCS7
  • Tamaño de la llave: 256 bits
  • Tamaño de bloque: 128 bits
  • Llave: token (se obtiene del API de seguridad) se requiere convertir de string hexadecimal a byte array.
  • Vector de inicialización: iv (se obtiene del API de seguridad) se requiere convertir de string hexadecimal a byte array.

   B.2 Scope (codificación base64)

Request

{

 "scopes": [

 {

  "key": "9be588af-dd65-4ec3-a0c3-7eaff3c2642a",

  "elements": [

   "card.cardNumber",

   "card.cvv2"

  ]

 }

}


Campo Tipo Longitud Obligatorio Descripción
key text max 36 SI Token relacionado a la llave de encriptación a utilizar obtenido en la respuesta del API de Seguridad
elements array SI Referencia a los atributos encriptados en el cuerpo de la consulta


   B.3 Request original (encriptación AES)

Request

{

 "channel": "web",

 "order": {

  "purchaseNumber": "1234567890",

  "amount": 12.35,

  "currency": "PEN"

 },

 "card": {

  "cardNumber": "xnEvZd9u+2jNUCiOucxI141AOy5/cCyAfYuJC/xH4eU=",

  "expirationMonth": 12,

  "expirationYear": 2021,

  "cvv2": "I4s8P1K6SrnlgfUoeRqRlw=="

 },

 "cardHolder": {

  "firstName": "Juan",

  "lastName": "Crespo",

  "email": "juan.c@latinmail.com",

  "phoneNumber": "5112223333"

 }

}


Campo Tipo Longitud Obligatorio Descripción
channel String SI Canal desde donde se originó la operación.
– web Si son operaciones realizadas con el botón de pago web
– mobile Si son operaciones realizadas con la librería de pago app
– pasarela Si son operaciones realizadas con la API de autorización para el producto comercio electrónico
– callcenter Si son operaciones realizadas con la API de autorización para el producto telepago
– recurrent Si son operaciones realizadas con la API de autorización para el producto pago programado
clientIp String max 13 SI Dirección IP desde donde se originó la operación.
deviceFingerprintId string max 36 SI Id del dispositivo.
merchantDefineData string NO Entidad que representa a datos adicionales enviados por el comercio
billingAddress Json NO Entidad que representa información de dirección
billingAddress.street1 string max 30 NO Dirección número uno
billingAddress.street2 string max 30 NO Dirección número dos
billingAddress.postalCode Integer max 5 NO Código postal
billingAddress.city String max 20 NO Nombre de la ciudad
billingAddress.state String max 20 NO Nombre del departamento o estado
billingAddress.country String max 2 NO Código ISO-3166 del país
shippingAddress String NO Entidad que representa información de dirección
shippingAddress.street1 String max 30 NO Dirección número uno
shippingAddress.street2 String max 30 NO Dirección número dos
shippingAddress.postalCode Integer max 5 NO Código postal
shippingAddress.city String max 20 NO Nombre de la ciudad
shippingAddress.state String max 20 NO Nombre del departamento o estado
shippingAddress.country String max 2 NO Código ISO-3166 del país
order Json SI Entidad que representa la información del pedido
order.purchaseNumber string max 12 SI Número de pedido generado por el comercio
order.amount Number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
order.currency String Max 3 SI Código de moneda en la que se ejecuta la transacción
– PEN
– USD
card json SI Entidad que representa información de la tarjeta
card.cardNumber String max 16 SI Número de la tarjeta
card.expirationMonth Integer($int32) SI Mes de expiración
card.expirationYear Integer($int32) SI Año de expiración
card.cvv2 String max 3 NO Número de CVV2 de la tarjeta encriptado con la llave baseKey y vector iv obtenidos en la respuesta del api.security
cardHolder Json NO Entidad que representa la información del tarjetahabiente
cardHolder.firstName String Max 25 NO Nombres del tarjetahabiente
cardHolder.lastName String Max 50 NO Apellidos del tarjetahabiente
cardHolder.email String Max 35 NO Correo electrónico del tarjetahabiente
(*) Se envía obligatoriamente cuando la tarjeta es tokenizada
cardHolder.phoneNumber String Max 10 NO Teléfono del tarjetahabiente
currencyConversion json NO Entidad que representa información relacionada a la conversión DCC
(*) No es obligatorio cuando el canal es recurrente
currencyConversion.accepted boolean SI Indica si en la venta se usará o no DCC
currencyConversion.eligibilityCode string max 1 SI Valor retornado en la respuesta a la consulta de elegibilidad
– 0 Requerimiento DCC ha sido aceptado – 1 El requerimiento DCC ha sido rechazado basado en un error. Verifique los códigos de error para más detalle – 2 La tarjeta no fue encontrada en la CRT por lo que no puede ser considerada para DCC – 3 DCC no está permitido para la tarjeta – 4 No se requirió el servicio DCC
currencyConversion.currencyCode string max 3 SI Código de moneda DCC. El código de moneda aplicable al PAN. Este valor se encuentra en la búsqueda CRT (ISO 4217)
currencyConversion.currencyCodeAlpha string max 3 SI Código de moneda DCC en texto. El código de moneda expresado en texto, esto ayudará a la presentación de la oferta DCC
currencyConversion.amount number($double) SI Importe en moneda DCC. El monto en la moneda extranjera en la menor unidad de la moneda extranjera
currencyConversion.exponent integer($int32) SI El exponente extranjero utilizado en dar formato al monto
currencyConversion.exchangeRate number($double) SI Factor por el que el monto local es multiplicado para obtener el monto DCC
currencyConversion.wholeSaleRate number($double) SI Tasa de conversión antes de que se aplique la comisión
currencyConversion.markup number($double) SI Margen de beneficio aplicado a toda la tasa de venta
currencyConversion.rateSource string max 12 SI Nombre del origen de las tarifas extranjeras
currencyConversion.rateDate string max 6 SI Fecha en la que se obtuvo el tipo de cambio. Expresado como yyMMdd
currencyConversion.rateTime string max 6 SI Hora en la que se obtuvo el tipo de cambio. Expresado como hhMMss
currencyConversion.status string max 15 SI Estado obtenido en la consulta de elegibilidad DCC
– Authorized
– Not Authorized
currencyConversion.signature string max 41 SI Llave generada en la consulta de elegibilidad DCC


C. Request y Casos

  C.1 Tabla de Parámetros

Campo Tipo Longitud Obligatorio Descripción
HEADER
accessToken Text max 1000 SI Token generado con el API de Seguridad
scope Text max 1000 SI JSON codificado en base64 obtenido en el paso de encriptación
URL
product text max 100 SI Identificador de producto
– ecommerce
– pospc
– recurrent
merchantId text max 100 SI Código de comercio
BODY
key string max 36 SI Acá se debe enviar el valor del atributo token obtenido en la respuesta del api.security y que está relacionado a la llave y vector de encriptación que se usará en el Request original
payload string SI Acá se debe enviar el Request original encriptado con la llave baseKey y vector iv obtenidos en la respuesta del api.security


  C.2 Trama de ejemplo:

Request

POST /api.antifraud/v1/antifraud/ecommerce/341198210 HTTP/1.1

Host: apitestenv.vnforapps.com

Content-Type: application/json

Authorization: eyJraWQiOiJmWk1tV3pZR0RBckxHektvalNCK2w3SjFhMnNPXC9zQ nNwOTlNNmNuM3F5MD0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJjNTAxNjYyOS04Zjc2L TQ1M2QtYjhlNC01MGJjZDI5YjI2NTAiLCJldmVudF9pZCI6IjBlNDY3MTA5LWYzM2YtNG U5NS05YTlmLTIxYWU3NjhlZTEzMSIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjo iYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE2MDUyMDcz MzAsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC51cy1lYXN0LTEuYW1hem9uYXdzL mNvbVwvdXMtZWFzdC0xXzJjSjFTZTFmSSIsImV4cCI6MTYwNTIxMDkzMCwiaWF0IjoxNj A1MjA3MzMwLCJqdGkiOiI2ZWIyYmU2MC0yMGFiLTRjMGMtOGUyZC0zZGY3YTMxNjFmYTQ iLCJjbGllbnRfaWQiOiIxMGx2MDYxN281ZGljNTFlYnNucWVpaWpiNyIsInVzZXJuYW1l IjoiaW50ZWdyYWNpb25lcy52aXNhbmV0QG5lY29tcGx1cy5jb20ifQ.B8rZapcJgt4TZc 3VxEGp9S_EW0FbCDfrJcm3ubUtAqexo7QRHzKOtaUyzlfE3Irm_a_JDE8vjjNtk-gaWa3 gxMk7smLXPb32h8QtynFtmiWtmtOE4JOcyFkquXZMoHvF07zxGuMmfKjP6Y7yrFfyO92j SX2UeDF421Mm8WVGeYG4Sfkzc74cgIURP_gh-l70fPLaMRD92p2DYoyrptt30c64jsvZD IR44DD98BgR3r2w4OPO0QG7_6yY5tqe0ls1p_G7a4DhSWJogkU06VbQiwUq9DN3Dti02B SA24Wu1gI-N9B9Nrx8rZzMDnLh4HcUo0V0zvPrLxN1KkR7zPb07A


Scope: eyJzY29wZXMiOlt7ImtleSI6ImQxODYwYTgxLTczZWItNDEzZC05N2EwLTdkZ jJiN2U3ZmY1MiIsImVsZW1lbnRzIjpbImNhcmQuY2FyZE51bWJlciIsImNhcmQuY3Z2Mi JdfV19


{

 "key": "c007b5d7-178c-4cdf-a610-1e7802067dbc",

"payload":"lka/Tk+HDvp4rG/ioe+jd8dS/VhMYa4wv1Z1k/393zab+e3B0R lzK/cnqGga2IXh07UA6vXyTTZz4WklmeKJMlBNmSBfGxIuY22e+XQP04UXWegxp/xvihb /9CTiDL0Ql09WC5wwmkcTTVr4SPMuPIZ8BOHdebeh62LUzGB8ewpIOicNWZ3Ae0tGLdRU Wmf9wu71rG6ObSaVijYDmPNMXCkJu2uoRFeK9YLybUxnnuX01jrQ3m1D8xWyoUXDq7Gyj IBscVMNWD9k7bK/dEHnLEDDj9Ov4yYpX0j/ajd2m0gtElZhL5c9EWAPFs+PHSLR+AeaDA UeRiAzXzwLAtbw4CjAGpXat3TmGyrTBDN8j37AVp15/qRDHhw0efSMDfY0+38bUVjmulw 48aI4C0/LgFRK2v4kI/5HaE8+WJ4nArLuM3Mc0CXYdQgUHxkzD9yMjTa9kmaI10V0Ldz6 yQw0dSJy0phoYwa2mrrPhXgPoOUUAZOfAmgI019nqwloKVd5/dSoRGqvc8KqNAOu1DOjV vFtH6UNI3SK3LzR+DXRIIm1AGfND6w/EpJSCIwSc5aCLhBrQNOw4FCwtflVJCpCAOAvCW IAL5a0K+b33gd1N8zgYp+h9iFM3dNn5PJXHyonorMDseJa7BeKQW5UvvO/RFDR65djEFt wyfY5XtXZ2V/P4fRe5jLaRY+N2txh4eCd0KC+djCST8bTcb3WibE3kz1F9mnIWf86xxYG YInvu1TR35mki1ZeLRkTIaKGx4zq35zv96lExll/ARfFLb3QCdC+/U72I5SsFmzK0ID+F QTxzWJYcb9FJ/oSjjfKUhul"

}



  C.3 Lenguajes:

  • Node
  • JavaScript
  • Python

const request = require('request');

const options = {

 method: 'POST',

 url: 'https://apitestenv.vnforapps.com/api.antifraud/v1/antifraud/ecommerce/341198210',

 headers: {

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

  'Scope': '{{scope}}',

  accept: 'application/json',

  'content-type': 'application/json'

 },

 body: {

  "key": "c007b5d7-178c-4cdf-a610-1e7802067dbc",

"payload":"lka/Tk+HDvp4rG/ioe+jd8dS/VhMYa4wv1Z1k/393zab+e3B0RlzK /cnqGga2IXh07UA6vXyTTZz4WklmeKJMlBNmSBfGxIuY22e+XQP04UXWegxp/xvihb/9CTiDL0Ql09 WC5wwmkcTTVr4SPMuPIZ8BOHdebeh62LUzGB8ewpIOicNWZ3Ae0tGLdRUWmf9wu71rG6ObSaVijYDm PNMXCkJu2uoRFeK9YLybUxnnuX01jrQ3m1D8xWyoUXDq7GyjIBscVMNWD9k7bK/dEHnLEDDj9Ov4yY pX0j/ajd2m0gtElZhL5c9EWAPFs+PHSLR+AeaDAUeRiAzXzwLAtbw4CjAGpXat3TmGyrTBDN8j37AV p15/qRDHhw0efSMDfY0+38bUVjmulw48aI4C0/LgFRK2v4kI/5HaE8+WJ4nArLuM3Mc0CXYdQgUHxk zD9yMjTa9kmaI10V0Ldz6yQw0dSJy0phoYwa2mrrPhXgPoOUUAZOfAmgI019nqwloKVd5/dSoRGqvc 8KqNAOu1DOjVvFtH6UNI3SK3LzR+DXRIIm1AGfND6w/EpJSCIwSc5aCLhBrQNOw4FCwtflVJCpCAOA vCWIAL5a0K+b33gd1N8zgYp+h9iFM3dNn5PJXHyonorMDseJa7BeKQW5UvvO/RFDR65djEFtwyfY5X tXZ2V/P4fRe5jLaRY+N2txh4eCd0KC+djCST8bTcb3WibE3kz1F9mnIWf86xxYGYInvu1TR35mki1Z eLRkTIaKGx4zq35zv96lExll/ARfFLb3QCdC+/U72I5SsFmzK0ID+FQTxzWJYcb9FJ/oSjjfKUhul"

 },

 json: true

};

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 Obligatorio Descripción
TRAMA EXITOSA: 200
header json SI Entidad que representa el encabezado de respuesta a la petición
header.ecoreTransactionUUID string($uuid) SI Identificador único de transacción para la plataforma
header.ecoreTransactionDate string SI Fecha de la operación expresada en formato UNIX TimeStamp
header.millis integer($int32) SI Tiempo de ejecución de la operación
fulfillment json NO Entidad que representa información complementaria al pedido
fulfillment.channel string NO Canal desde donde se originó la operación.
– web: Si son operaciones realizadas con el botón de pago web
– mobile: Si son operaciones realizadas con la librería de pago app
– pasarela: Si son operaciones realizadas con la API de autorización para el producto comercio electrónico
– callcenter: Si son operaciones realizadas con la API de autorización para el producto telepago
fulfillment.merchantId string max 9 NO Código de comercio
fulfillment.terminalId string max 8 NO Número de terminal asociado a la transacción
fulfillment.captureType string max 6 NO Tipo de captura en el canal. Siempre es el valor manual
fulfillment.countable boolean NO Indica si la venta es contable true o no contable false
fulfillment.fastPayment boolean NO Indica si la venta es pago rápido true o no es pago rápido false
fulfillment.signature string($uuid) NO Código único generado por el sistema al momento de la venta
order json SI Entidad que representa la información del pedido
order.tokenId string max 32 NO Id del token de transacción obtenido en la respuesta a la validación antifraude o del formulario de pago
order.productId string max 10 NO Código del producto para la afiliación
order.purchaseNumber string max 12 SI Número de pedido generado por el comercio
order.amount number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
order.installment integer($int32) SI Número de cuotas en que se realizará el pago
order.currency string max 3 SI Código de moneda en la que se ejecuta la transacción
– PEN
– USD
order.externalTransactionId string($uuid) NO Identificador único de transacción enviado por el comercio
order.authorizedAmount number($double) SI Importe del pedido confirmado. Precisión hasta 8 valores enteros con 2 decimales
order.authorizationCode string max 6 NO Código de autorización asignado a la aprobación de la transacción por la entidad resolutora
order.actionCode string max 3 NO 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.traceNumber string max 6 NO Número asignado para identificar de forma unívoca a la transacción
order.transactionDate string NO Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
order.transactionId string max 15 NO Identificador de la transacción asociado a la autorización
dataMap json NO Entidad que representa información complementaria del pedido
dataMap.CURRENCY string max 4 NO Código numérico de moneda en la que se ejecuta la transacción
dataMap.TRANSACTION_DATE string NO Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
dataMap.ACTION_CODE string max 3 NO 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 NO Código único generado por el sistema
dataMap.ECI_DESCRIPTION string max 100 NO Descripción del código ECI asociado a la autenticación de la transacción
dataMap.ECI string max 2 NO Código ECI asociado a la autenticación de la transacción
dataMap.CARD string max 16 NO Número de tarjeta enmascarado usada en la venta
dataMap.MERCHANT string max 9 NO Código de comercio al cual pertenece la transacción
dataMap.STATUS string max 20 NO Descripción del estado de la transacción
– Authorized
– Not Authorized
– Confirmed
– Not Confirmed
– Verified
– Not Verified
– Voided
– Not Voided
– Reject
– Review
dataMap.ADQUIRENTE string max 15 NO Nombre de identificación del adquirente.
dataMap.BIN string max 6 NO 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 NO Marca de la tarjeta usada en la venta
– visa
– amex
– mastercard
– dinersclub
dataMap.SETTLEMENT string max 20 NO Indica si la operación está o no está liquidada
– Not Applicable
– Pending
– Automatic
– Completed
dataMap.ACTION_DESCRIPTION string max 100 NO Texto descriptivo de la autorización o denegación
dataMap.ID_UNICO string max 15 NO Id de la transacción asociado a la autorización
dataMap.AMOUNT number($double) NO Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
dataMap.AUTHORIZED_AMOUNT number($double) NO Importe del pedido confirmado. Precisión hasta 8 valores enteros con 2 decimales
dataMap.TRANSACTION_ID string max 15 NO Id de la transacción asociado a la autorización
dataMap.AUTHORIZATION_CODE string max 6 NO Código de autorización asignado a la aprobación de la transacción por la entidad resolutora
dataMap.CARD_TOKEN string max 16 NO Token identificador del objeto tokenizado
dataMap.VAULT_BLOCK string max 100 NO Valor del campo por el cual se tokeniza la tarjeta
dataMap.QUOTA_NUMBER integer($int32) NO Número de cuotas en que se realizó la venta
dataMap.QUOTA_AMOUNT number($double) NO Importe aproximado del valor de cuota. Precisión hasta 8 valores enteros con 2 decimales
dataMap.QUOTA_DEFERRED integer($int32) NO Indica si el pago en cuotas debe procesarse con pagos en diferido.
– 0 no diferido
– 1 o 2 diferido
dataMap.QUOTA_NI_PROGRAM integer($int32) NO Código de programa para cuota sin intereses
dataMap.QUOTA_NI_TYPE integer($int32) NO Indicador de tipo de cobro para cuotas sin intereses.
– 0 como porcentaje
– 1 como importe
dataMap.QUOTA_NI_AMOUNT number($double) NO Valor asociado al tipo de cobro para cuotas sin intereses
dataMap.QUOTA_NI_DISCOUNT number($double) NO Porcentaje de descuento que corresponde al emisor por el programa cuota sin intereses
dataMap.QUOTA_NI_MESSAGE string max 50 NO Mensaje asociado al cobro para cuota sin intereses
TRAMA ERRONEA: 400
errorCode integer($int32) SI Código de error de la operación. Siempre es el valor 400
errorMessage string SI Mensaje de error de la operación
header json NO Entidad que representa el encabezado de respuesta a la petición
header.ecoreTransactionUUID string($uuid) NO Identificador único de transacción para la plataforma
header.ecoreTransactionDate string NO Fecha de la operación expresada en formato UNIX TimeStamp
header.millis integer($int32) NO Tiempo de ejecución de la operación
data json SI Entidad que representa información relacionada a errores en la operación realizada
dataMap.CURRENCY string max 4 NO Código numérico de moneda en la que se ejecuta la transacción
dataMap.TRANSACTION_DATE string NO Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
dataMap.ACTION_CODE string max 3 NO 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 NO Código único generado por el sistema
data.ECI_DESCRIPTION string max 100 NO Descripción del código ECI asociado a la autenticación de la transacción
data.ECI string max 2 NO Código ECI asociado a la autenticación de la transacción
data.CARD string max 16 NO Número de tarjeta enmascarado usada en la venta
data.MERCHANT string max 9 NO Código de comercio al cual pertenece la transacción
data.STATUS string max 20 NO Descripción del estado de la transacción
– Authorized
– Not Authorized
– Confirmed
– Not Confirmed
– Verified
– Not Verified
– Voided
– Not Voided
– Reject
– Review
data.ADQUIRENTE string max 15 NO Nombre de identificación del adquirente.
data.BIN string max 6 NO Número de BIN de la tarjeta usada en la venta. Son los 6 primeros dígitos de una tarjeta
data.BRAND string max 15 NO Marca de la tarjeta usada en la venta
– visa
– amex
– mastercard
– dinersclub
data.SETTLEMENT string max 20 NO Indica si la operación está o no está liquidada
– Not Applicable
– Pending
– Automatic
– Completed
data.ACTION_DESCRIPTION string max 100 NO Texto descriptivo de la autorización o denegación
data.ID_UNICO string max 15 NO Identificador de la transacción asociado a la autorización
data.AMOUNT number($double) NO Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
data.AUTHORIZED_AMOUNT number($double) NO Importe del pedido confirmado. Precisión hasta 8 valores enteros con 2 decimales
data.TRANSACTION_ID string max 15 NO Id de la transacción asociado a la autorización
data.AUTHORIZATION_CODE string max 6 NO Código de autorización asignado a la aprobación de la transacción por la entidad resolutora
data.QUOTA_NUMBER integer($int32) NO Número de cuotas en que se realizó la venta
data.QUOTA_AMOUNT number($double) NO Importe aproximado del valor de cuota. Precisión hasta 8 valores enteros con 2 decimales
data.QUOTA_DEFERRED integer($int32) NO Indica si el pago en cuotas debe procesarse con pagos en diferido.
– 0 no diferido
– 1 o 2 diferido
data.QUOTA_NI_PROGRAM integer($int32) NO Código de programa para cuota sin intereses
data.QUOTA_NI_TYPE integer($int32) NO Indicador de tipo de cobro para cuotas sin intereses.
– 0 como porcentaje
– 1 como importe
data.QUOTA_NI_AMOUNT number($double) NO Valor asociado al tipo de cobro para cuotas sin intereses
data.QUOTA_NI_DISCOUNT number($double) NO Porcentaje de descuento que corresponde al emisor por el programa cuota sin intereses
data.QUOTA_NI_MESSAGE string max 50 NO Mensaje asociado al cobro para cuota sin intereses
TRAMA ERRONEA: 401
description text max 1000 NO 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": "5b141988-5452-4648-a6dd-05a0195d3f78",

  "ecoreTransactionDate": 1605206364358,

  "millis": 1945

 },

 "order": {

  "purchaseNumber": "1234567890",

  "amount": 12.35,

  "installment": 0,

  "currency": "PEN",

  "authorizedAmount": 0.0

 },

 "dataMap": {

  "DECISION": "Accept"

  }

 }



E. Códigos de Respuesta

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

API de Validación de Cuenta con Alcance Cifrado #

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.


A. Endpoint

Ambiente URL de API
Testing https://apitestenv.vnforapps.com/api.validate/v1/validate/{product}/{merchantId}
Producción https://apiprod..vnforapps.com/api.validate/v1/validate/{product}/{merchantId}
Ambiente
Testing
URL de API
https://apitestenv.vnforapps.com/api.validate/v1/validate/{product}/{merchantId}
Producción
URL de API
https://apiprod..vnforapps.com/api.validate/v1/validate/{product}/{merchantId}


B. Cifrado

En este punto se detallan los parámetros de encriptación del algoritmo AES y los elementos a codificar o encriptar.

   B.1 Cifrado

  • Parámetros de encriptación:
  • Algoritmo de encriptación: AES
  • Modo de encriptación: CBC
  • Relleno: PKCS7
  • Tamaño de la llave: 256 bits
  • Tamaño de bloque: 128 bits
  • Llave: baseKey (Api de Seguridad) se requiere convertir de string hexadecimal a byte array.
  • Vector de inicialización: iv (Api de Seguridad) se requiere convertirlo de string hexadecimal a byte array.


   B.2 Scope (codificación base64)

Request

Content-Type: application/json

{

 "scopes": [

 {

  "key": "9be588af-dd65-4ec3-a0c3-7eaff3c2642a",

  "elements": [

   "card.cardNumber",

   "card.cvv2"

   ]

  }

 ]

}


Campo Tipo Longitud Obligatorio Descripción
key Text Max 36 SI Token relacionado a la llave de encriptación a utilizar obtenido en la respuesta del API de Seguridad
elements Array SI Referencia a los atributos encriptados en el cuerpo de la consulta


C. Request y casos

   C.1 Tabla de Parámetros

Campo Tipo Longitud Obligatorio Descripción
HEADER
accessToken Text Max 1000 SI Token generado con el API de Seguridad
scope Text Max 1000 SI JSON codificado en base64 obtenido en el paso de encriptación
URL
product Text Max 100 SI Identificador de producto
– ecommerce
– pospc
– recurrent
merchantId Text Max 9 SI Código de comercio
BODY
channel String SI Canal desde donde se originó la operación.
– web Si son operaciones realizadas con el botón de pago web
– mobile Si son operaciones realizadas con la librería de pago app
– pasarela Si son operaciones realizadas con la API de autorización para el producto comercio electrónico
– callcenter Si son operaciones realizadas con la API de autorización para el producto telepago
– recurrent Si son operaciones realizadas con la API de autorización para el producto pago programado
captureType String SI Tipo de captura en el canal. Siempre es el valor manual
tokenize Boolean SI Indica si la tarjeta a validar será o no tokenizada. Si es el valor true la tarjeta será tokenizada, si es el valor false la tarjeta no será tokenizada
card Json SI Entidad que representa información de la tarjeta
card.cardNumber String SI Número de la tarjeta encriptado con la llave baseKey y vector iv obtenidos en la respuesta del API de Seguridad
card.cvv2 String SI Número de CVV2 de la tarjeta encriptado con la llave baseKey y vector iv obtenidos en la respuesta del API de Seguridad
card.expirationMonth Integer($int32) SI Mes de expiración
card.expirationYear Integer($int32) SI Año de expiración
card.cardHolder Json SI Entidad que representa la información del tarjetahabiente
cardHolder.email String Max 35 SI Correo electrónico del tarjetahabiente
cardHolder.firstName String Max 25 SI Nombres del tarjetahabiente
cardHolder.lastName String Max 50 SI Apellidos del tarjetahabiente
cardHolder.phoneNumber String Max 10 SI Teléfono del tarjetahabiente
order Json SI Entidad que representa la información del pedido
order.amount Number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
order.authorizedAmount Number($double) NO Importe del pedido confirmado. Precisión hasta 8 valores enteros con 2 decimales
order.currency String Max 3 SI Código de moneda en la que se ejecuta la transacción
– PEN
– USD
order.externalTransactionId String($uuid) NO Id único de la transacción enviado por el comercio
order.installment Integer($int32) NO Número de cuotas en que se realizará el pago
order.purchaseNumber String Max 12 SI Número de pedido generado por el comercio
order.tokenId String Max 32 NO Id del token de transacción obtenido en la respuesta a la validación antifraude o del formulario de pago (*) No es obligatorio cuando el canal es recurrente
order.transactionId String Max 15 NO Identificador de la transacción asociado a la autorización


   C.2 Trama de Ejemplo

Request

POST /api.validate/v1/validate/ecommerce/341198214 HTTP/1.1

Host: apitestenv.vnforapps.com

Content-Type: application/json

Authorization:eyJraWQiOiJmWk1tV3pZR0RBckxHektvalNCK2w3SjFhMnNP XC9zQnNwOTlNNmNuM3F5MD0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJjNTAxN jYyOS04Zjc2LTQ1M2QtYjhlNC01MGJjZDI5YjI2NTAiLCJldmVudF9pZCI6IjV kMjQxZDFjLWNmMzQtNDBmOC1hZjgzLWZiYTg2NjYyMzg5YyIsInRva2VuX3VzZ SI6ImFjY2VzcyIsInNjb3BlIjoiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWR taW4iLCJhdXRoX3RpbWUiOjE2MDU3MzQ5MDYsImlzcyI6Imh0dHBzOlwvXC9jb 2duaXRvLWlkcC51cy1lYXN0LTEuYW1hem9uYXdzLmNvbVwvdXMtZWFzdC0xXzJ jSjFTZTFmSSIsImV4cCI6MTYwNTczODUwNiwiaWF0IjoxNjA1NzM0OTA2LCJqd GkiOiIyM2Q1ZjhhOS1hNWZhLTQzMzgtOWNhOS1mYjc5NjQyYTM3NjYiLCJjbGl lbnRfaWQiOiIxMGx2MDYxN281ZGljNTFlYnNucWVpaWpiNyIsInVzZXJuYW1lI joiaW50ZWdyYWNpb25lcy52aXNhbmV0QG5lY29tcGx1cy5jb20ifQ.go-iiDwCAb-bAm0esQaMBUbf9628K_-1azDNoi9XkxwAl3F28YnDaKpJc4CAFcqDN2qfbz-qUVAw-XmAlwRcrM7-sRVLhj2iY0vMux0JtUmWfrWP7jQFAvXTWTXYpV8BSk7P RwDg-2Yr__oRUJrSx_BsOxUq0oNH78ACHY1Tq96UNlvAW1fMbMlPxz7VixI7oB zA00dZSBsTO_hD3Cawk6m-ZSXFgEs33GNIpKr6GiG879qLeZN7O7L7Xu-w_Alf wND7Gs7tREcGB9TFygnB4OtNP5I4dpiqIKm2_3Ka0ti7C2NmsdL8ZSkqM9BlQjhS__T7d7RjF8HXaOJ_Y6Guxw

Scope:eyJzY29wZXMiOlt7ImtleSI6IjI3MmRhNjgyLTU5NWQtNGQxOC04NDg3L TBkMzM4ZDNkOTU5YyIsImVsZW1lbnRzIjpbImNhcmQuY2FyZE51bWJlciIsImN hcmQuY3Z2MiJdfV19

}

 "captureType": "manual",

 "tokenize": false,

 "channel": "pasarela",

 "card": {

  "cardNumber": "yc+CKbUw0zCcTDJ6P5BuwT23U2NU+QqDVJzfeyZtuG4=",

  "cvv2": "lQi1Suk5IdODxXPamnefIA==",

  "expirationMonth": 4,

  "expirationYear": 24

 },

 "cardHolder": {

  "email": "jperez@gmail.com",

  "firstName": "Juan",

  "lastName": "Perez",

  "phoneNumber": "2132300"

 },

 "order":

  "amount": 0.2,

  "authorizedAmount": 0,

  "currency": "PEN",

  "externalTransactionId": "46E8B001-153E-438E-B047-6DD8E4AEF514",

  "installment": 0,

  "purchaseNumber": "7372",

  "tokenId": null,

  "transactionId": null

 }

}



   C.3 Lenguajes

  • Node
  • JavaScript
  • Python

const request = require('request');

const options = {

 method: 'POST',

 url: 'https://apitestenv.vnforapps.com/api.validate/v1/validate/ecommerce/merchantId',

 headers: {

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

  'Scope': '{{scope}}',

  accept: 'application/json',

  'content-type': 'application/json'

 },

 body: {

  captureType: "manual",

  tokenize: "341198210",

  channel: "pasarela",

 card: {

  captureType: 'manual',

  tokenize: true,

  card: {

   cardNumber: 'yc+CKbUw0zCcTDJ6P5BuwT23U2NU+QqDVJzfeyZtuG4=',

   cvv2: 'lQi1Suk5IdODxXPamnefIA==',

   expirationMonth: 4,

   expirationYear: 24

  },

  cardHolder: {

   email: 'jperez@gmail.com',

   firstName: 'Juan',

   lastName: 'Perez',

   phoneNumber: '2132300'

  },

  order: {

   amount: 0.2,

   authorizedAmount: 0,

   currency: 'PEN',

   externalTransactionId: '46E8B001-153E-438E-B047-6DD8E4AEF514',

   installment: 0,

   purchaseNumber: '7372',

   tokenId: null,

   transactionId: null

   }

  }

 },

 json: true

};

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 Obligatorio Descripción
TRAMA EXITOSA: 200
header Json SI Entidad que representa el encabezado de respuesta a la petición
header.ecoreTransactionUUID string($uuid) SI Identificador único de transacción para la plataforma
header.ecoreTransactionDate String SI Fecha de la operación expresada en formato UNIX TimeStamp
header.millis Integer($int32) SI Tiempo de ejecución de la operación
order Json SI Entidad que representa la información del pedido
order.purchaseNumber String Max 12 SI Número de pedido generado por el comercio
order.amount Number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
order.installment Integer($int32) NO Número de cuotas en que se realizará el pago
order.currency String Max 3 SI Código de moneda en la que se ejecuta la transacción
– PEN
– USD
order.externalTransactionId String($uuid) NO Id único de la transacción enviado por el comercio
order.authorizedAmount Number($double) SI Importe del pedido confirmado. Precisión hasta 8 valores enteros con 2 decimales
order.authorizationCode String Max 6 SI Código de autorización asignado a la aprobación de la transacción por la entidad resolutora
order.traceNumber String Max 6 SI Número asignado para identificar de forma unívoca a la transacción
order.transactionDate String SI Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
order.transactionId String Max 15 SI Identificador de la transacción asociado a la autorización
token Json NO Entidad que representa información de la tokenización para la tarjeta utilizada
token.tokenId String Max 16 NO Token identificador del objeto tokenizado
token.hash String Max 6 NO Hash identificador del objeto tokenizado
token.expiration String NO Fecha de caducidad del token expresado en formato nativo yyMMddHHmmSS
dataMap Json SI Entidad que representa información complementaria del pedido
dataMap.CVV2_VALIDATION String Max 1 NO
TRAMA ERRÓNEA: 400
errorCode Integer($int32) SI Código de error de la operación. Siempre es el valor 400
errorMessage String SI Mensaje de error de la operación
header Json SI Entidad que representa el encabezado de respuesta a la petición
header.ecoreTransactionUUID String($uuid) SI Identificador único de transacción para la plataforma
header.ecoreTransactionDate String SI Fecha de la operación expresada en formato UNIX TimeStamp
header.millis Integer($int32) SI Tiempo de ejecución de la operación
data Json SI Entidad que representa información complementaria del pedido
data.CURRENCY String Max 4 NO Código numérico de moneda en la que se ejecuta la transacción
data.TRANSACTION_DATE String NO Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
data.TERMINAL String Max 8 NO Número de terminal asociado a la transacción
data.ACTION_CODE String Max 3 NO 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
data.ACTION_DESCRIPTION String Max 6 NO Texto descriptivo de la autorización o denegación
data.TRACE_NUMBER String Max 6 SI Número asignado para identificar de forma unívoca a la transacción
date.AMOUNT String($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
data.MERCHANT String Max 9 NO Código de comercio VisaNet al cual pertenece la transacción
TRAMA ERRÓNEA: 401
description Text Max 1000 NO Descripción relacionada al error. Este error se presenta cuando las credenciales no son válidas
TRAMA ERRÓNEA: 406
description Text Max 1000 NO Descripción relacionada al error. Este error se presenta cuando hay muchas solicitudes con la misma carga


   D.2 Tramas de Ejemplo

  • Caso 200
  • Caso 400
  • Caso 401

Status Code 200 OK

Content-Type: application/json

{

 "header": {

  "ecoreTransactionUUID": "345a0046-9cd9-4922-b9d8-9058710dda65",

  "ecoreTransactionDate": 1605733964971,

  "millis": 3408

 },

 "order": {

  "purchaseNumber": "7372",

  "amount": 0.2,

  "installment": 0,

  "currency": "PEN",

  "externalTransactionId": "46E8B001-153E-438E-B047-6DD8E4AEF514",

  "authorizedAmount": 1.0,

  "authorizationCode": "005574",

  "traceNumber": "197858",

  "transactionDate": "201118161241",

  "transactionId": "953203230007621"

 },

  "token": {

  "token": "7000010038739409",

  "hash": "1f65ccffc76fcb9c3588f2ff28d6ed05e1fdf9cea19b7a811116a04d9fd0df93",

  "expiration": "211118211244"

 },

 "dataMap": {

  "CVV2_VALIDATION": "M"

 }

}



E. Códigos de Respuesta

Código Descripción
200 Validación de cuenta con alance cifrado realizado con éxito
400 Error en la consulta
401 Error relacionado al acceso no autorizado

API de Validación de Cuenta con Petición Cifrada #

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.


A. Endpoint

Ambiente URL de API
Testing https://apitestenv.vnforapps.com/api.validate/v1/validate/{product}/{merchantId}
Producción https://apiprod..vnforapps.com/api.validate/v1/validate/{product}/{merchantId}
Ambiente
Testing
URL de API
https://apitestenv.vnforapps.com/api.validate/v1/validate/{product}/{merchantId}
Producción
URL de API
https://apiprod..vnforapps.com/api.validate/v1/validate/{product}/{merchantId}


B. Cifrado

En este punto se detallan los parámetros de encriptación del algoritmo AES y los elementos a codificar o encriptar.

   B.1 Cifrado

  • Parámetros de encriptación:
  • Algoritmo de encriptación: AES
  • Modo de encriptación: CBC
  • Relleno: PKCS7
  • Tamaño de la llave: 256 bits
  • Tamaño de bloque: 128 bits
  • Llave: baseKey (Api de Seguridad) se requiere convertir de string hexadecimal a byte array.
  • Vector de inicialización: iv (Api de Seguridad) se requiere convertir de string hexadecimal a byte array.


   B.2 Request original (encriptación AES)

Request

Content-Type: application/json

{

 "channel": "pasarela",

 "captureType": "manual",

 "tokenize": true,

 "card": {

  "cardNumber": "5443599980000447",

  "cvv2": "669",

  "expirationMonth": 4,

 "expirationYear": 24

 },

 "cardHolder": {

  "email": "jperez@gmail.com",

  "firstName": "Juan",

  "lastName": "Perez",

  "phoneNumber": "2132300"

 },

 "order": {

  "amount": 0.2,

  "authorizedAmount": 0,

  "currency": "PEN",

  "externalTransactionId": "46E8B001-153E-438E-B047-6DD8E4AEF514",

  "installment": 0

  "purchaseNumber": "7372",

  "tokenId": null,

  "transactionId": null

 }

}


Campo Tipo Longitud Obligatorio Descripción
channel String SI Canal desde donde se originó la operación.
– web Si son operaciones realizadas con el botón de pago web
– mobile Si son operaciones realizadas con la librería de pago app
– pasarela Si son operaciones realizadas con la API de autorización para el producto comercio electrónico
– callcenter Si son operaciones realizadas con la API de autorización para el producto telepago
– recurrent Si son operaciones realizadas con la API de autorización para el producto pago programado
captureType String SI Tipo de captura en el canal. Siempre es el valor manual
tokenize Boolean SI Indica si la tarjeta a validar será o no tokenizada. Si es el valor true la tarjeta será tokenizada, si es el valor false la tarjeta no será tokenizada
card Json SI Entidad que representa información de la tarjeta
card.cardNumber String SI Número de la tarjeta
card.cvv2 String SI Número de CVV2 de la tarjeta
card.expirationMonth Integer($int32) SI Mes de expiración
card.expirationYear Integer($int32) SI Año de expiración
cardHolder Json SI Entidad que representa la información del tarjetahabiente
cardHolder.email String Max 35 SI Correo electrónico del tarjetahabiente
cardHolder.firstName String Max 25 SI Nombres del tarjetahabiente
cardHolder.lastName String Max 50 SI Apellidos del tarjetahabiente
cardHolder.phoneNumber String Max 10 SI Teléfono del tarjetahabiente
order Json SI Entidad que representa la información del pedido
order.amount Number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
order.authorizedAmount Number($double) NO Importe del pedido confirmado. Precisión hasta 8 valores enteros con 2 decimales
order.currency String Max 3 SI Código de moneda en la que se ejecuta la transacción
– PEN
– USD
order.externalTransactionId String($uuid) NO Id único de la transacción enviado por el comercio
order.installment Integer($int32) NO Número de cuotas en que se realizará el pago
order.purchaseNumber String Max 12 SI Número de pedido generado por el comercio
order.tokenId String Max 32 NO Id del token de transacción obtenido en la respuesta a la validación antifraude o del formulario de pago (*) No es obligatorio cuando el canal es recurrente
order.transactionId String Max 15 NO Identificador de la transacción asociado a la autorización


C. Request y casos

   C.1 Tabla de Parámetros

Campo Tipo Longitud Obligatorio Descripción
HEADER
accessToken Text Max 1000 SI Token generado con el API de Seguridad
scope Text Max 1000 SI JSON codificado en base64 obtenido en el paso de encriptación
URL
product Text Max 100 SI Identificador de producto
– ecommerce
– pospc
– recurrent
merchantId Text Max 9 SI Código de comercio
BODY
key String Max 36 SI Token obtenido en la respuesta del API de Seguridad y que está relacionado a la llave y vector de encriptación que se usará en el Request original
payload String SI Request original encriptado con la llave token y vector iv obtenidos en la respuesta del API de Seguridad


   C.2 Trama de Ejemplo

Request

POST /api.validate/v1/validate/ecommerce/341198214 HTTP/1.1

Host: apitestenv.vnforapps.com

Content-Type: application/json

Authorization:eyJraWQiOiJmWk1tV3pZR0RBckxHektvalNCK2w3SjFh MnNPXC9zQnNwOTlNNmNuM3F5MD0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIi OiJjNTAxNjYyOS04Zjc2LTQ1M2QtYjhlNC01MGJjZDI5YjI2NTAiLCJld mVudF9pZCI6Ijk3ZmZjYjYxLTZlZjgtNDM0NS04MjM5LWNiNTdkODRiZW EzNCIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXdzLmNvZ25 pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE2MDU4MDA1 NDQsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC51cy1lYXN0LTEuY W1hem9uYXdzLmNvbVwvdXMtZWFzdC0xXzJjSjFTZTFmSSIsImV4cCI6MT YwNTgwNDE0NCwiaWF0IjoxNjA1ODAwNTQ0LCJqdGkiOiJjMGJmNzIzZC0 4MTU3LTRhOGEtODY3OS00YTJiNGYwYzhjNWMiLCJjbGllbnRfaWQiOiIx MGx2MDYxN281ZGljNTFlYnNucWVpaWpiNyIsInVzZXJuYW1lIjoiaW50Z WdyYWNpb25lcy52aXNhbmV0QG5lY29tcGx1cy5jb20ifQ.CytDC4U1mZf 0EtZZfb8ZrIMOlRxeQZq3cxSAzb9fRau2DEvumZyQiiAAsFXJaHpLXPapnmk1jqWkuk5p1uo9bPsyP0-c_mcKtpvz4yHpbQi5iZ_WiEPvE5lnnW2W9ql6-KAo2gP_P8rMXTuRtuMsUScnkyVZXuHJvZf9eylat_BrEFxoJLJP0fQ5QxsCQsCGyjlA8nMTaaML1lYGVhGj-kUr4a6U-Ea935rLLxJuc0I7O38 r208Rpbcl3ck7X2uI2ThJIP2WjdJuyQxcQYTho7W4AFwAHjKZMreGEeQo pGVNvK8Bzthy0i4zz5hVn6_o-m3Wve3N8qpC4lRexHGtiA

{

"key": "bc6749c2-3486-4d0d-a9ba-97dd5b5fa854",

"payload":"mQkWcpYMYLfNtI/Ado7XT2LJuqZQynYrLroU5KMZh1TusaH 6Howe03mTZR6Q9/iK/2kkMXRKrn02EsLjfJ6dZgrKE9mafLV5kYrOosNi ZczKUE7oWO1WW1ZptfugJnPutmxdGRkqrCZChRAfj6NjLG7gj25lrPIG4 nXVxUlw1PbRgAeXs1VrtmkxnLQ45Qv/A9VVAujqmH82LPQwUd62cmUEAR 3RI59+dMdJxgqlHkP9a6JTgrWpGdg07VfvqPldu4HGgB8uPB2FHvBuMvX NPdqnYg4sFIQhEfTsQuDclN/AcTKQf1wlyJuzOZgtExauvCoA/uAl6oe8 /e4YaxOcxUXv6lYuNqqvf6zoL2BvXRkqo8jelRH3i6mPI9u9BN6ulnJfv aIs7w9WI1hNqS1XwEBMcC6jp4KZUYAbqRlJpgFu+DfZCs08KOu/jjXqoL u7HNHjEQ2gIR+MkApQ4vdFyh2lEIIjDeOWBCltnZy2hTiuHj9C+6LIC/v /GELN2M5k45lPIDU4Ri/Gtnjrv7dKr66iUza8uZmUTNFJp3I7m3Qy0vT4 0aGWRanK/hxP5GHrPPB9C+fDQkrVtMQqMrr4cjQQ5k90zqhWZVtybU4YB 18="

}



   C.3 Lenguajes

  • Node
  • JavaScript
  • Python

const request = require('request');

 const options = {

  method: 'POST',

  url: 'https://apitestenv.vnforapps.com/api.validate/v1/validate/ecommerce/merchantId',

  headers: {

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

   accept: 'application/json',

   'content-type': 'application/json'

  },

 body: {

key:"bc6749c2-3486-4d0d-a9ba-97dd5b5fa854",

payload:"mQkWcpYMYLfNtI/Ado7XT2LJuqZQynYrLroU5KMZh1TusaH6Howe 03mTZR6Q9/iK/2kkMXRKrn02EsLjfJ6dZgrKE9mafLV5kYrOosNiZczKUE7oWO1WW1Zptfug JnPutmxdGRkqrCZChRAfj6NjLG7gj25lrPIG4nXVxUlw1PbRgAeXs1VrtmkxnLQ45Qv/A9VV AujqmH82LPQwUd62cmUEAR3RI59+dMdJxgqlHkP9a6JTgrWpGdg07VfvqPldu4HGgB8uPB2F HvBuMvXNPdqnYg4sFIQhEfTsQuDclN/AcTKQf1wlyJuzOZgtExauvCoA/uAl6oe8/e4YaxO cxUXv6lYuNqqvf6zoL2BvXRkqo8jelRH3i6mPI9u9BN6ulnJfvaIs7w9WI1hNqS1XwEBMcC6 jp4KZUYAbqRlJpgFu+DfZCs08KOu/jjXqoLu7HNHjEQ2gIR+MkApQ4vdFyh2lEIIjDeOWBCl tnZy2hTiuHj9C+6LIC/v/GELN2M5k45lPIDU4Ri/Gtnjrv7dKr66iUza8uZmUTNFJp3I7m3 Qy0vT40aGWRanK/hxP5GHrPPB9C+fDQkrVtMQqMrr4cjQQ5k90zqhWZVtybU4YB18=",

 },

 json: true

};

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 Obligatorio Descripción
TRAMA EXITOSA: 200
header Json SI Entidad que representa el encabezado de respuesta a la petición
header.ecoreTransactionUUID String($uuid) SI Identificador único de transacción para la plataforma
header.ecoreTransactionDate String SI Fecha de la operación expresada en formato UNIX TimeStamp
header.millis Integer($int32) SI Tiempo de ejecución de la operación
order JSON SI Entidad que representa la información del pedido
order.purchaseNumber Stringstring Max 12 SI Número de pedido generado por el comercio
order.amount Number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
order.installment Integer($int32) NO Número de cuotas en que se realizará el pago
order.currency String Max 3 SI Código de moneda en la que se ejecuta la transacción
– PEN
– USD
order.externalTransactionId String($uuid) NO Id único de la transacción enviado por el comercio
order.authorizedAmount Number($double) SI Importe del pedido confirmado. Precisión hasta 8 valores enteros con 2 decimales
order.authorizationCode String($uuid) SI Identificador único de transacción para la plataforma
header.ecoreTransactionUUID String($uuid) SI Identificador único de transacción para la plataforma
header.ecoreTransactionUUID String Max 6 SI Código de autorización asignado a la aprobación de la transacción por la entidad resolutora
order.traceNumber String Max 6 SI Número asignado para identificar de forma unívoca a la transacción
order.transactionDate String SI Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
order.transactionId String Max 15 SI Identificador de la transacción asociado a la autorización
token Json NO Entidad que representa información de la tokenización para la tarjeta utilizada
token.tokenId String Max 16 NO Token identificador del objeto tokenizado
token.hash String Max 6 NO Hash identificador del objeto tokenizado
token.expiration String NO Fecha de caducidad del token expresado en formato nativo yyMMddHHmmSS
dataMap Json SI Entidad que representa información complementaria del pedido
dataMap.CVV2_VALIDATION String Max 1 NO
TRAMA ERRÓNEA: 400
errorCode Integer($int32) SI Código de error de la operación. Siempre es el valor 400
errorMessage String SI Mensaje de error de la operación
header Json SI Entidad que representa el encabezado de respuesta a la petición
header.ecoreTransactionUUID String($uuid) SI Identificador único de transacción para la plataforma
header.ecoreTransactionDate String SI Fecha de la operación expresada en formato UNIX TimeStamp
header.millis Integer($int32) SI Tiempo de ejecución de la operación
data Json SI Entidad que representa información complementaria del pedido
data.CURRENCY String Max 4 NO Código numérico de moneda en la que se ejecuta la transacción
data.TRANSACTION_DATE String NO Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
data.TERMINAL String Max 8 NO Número de terminal asociado a la transacción
data.ACTION_CODE String Max 3 NO 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
data.ACTION_DESCRIPTION String Max 6 NO Texto descriptivo de la autorización o denegación
data.TRACE_NUMBER String Max 6 SI Número asignado para identificar de forma unívoca a la transacción
date.AMOUNT String($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
data.MERCHANT String Max 9 NO Código de comercio VisaNet al cual pertenece la transacción
TRAMA ERRÓNEA: 401
description Text Max 1000 NO Descripción relacionada al error. Este error se presenta cuando las credenciales no son válidas
TRAMA ERRÓNEA: 406
description Text Max 1000 NO Descripción relacionada al error. Este error se presenta cuando hay muchas solicitudes con la misma carga


   C.2 Trama de Ejemplo

Request

POST /api.validate/v1/validate/ecommerce/341198214 HTTP/1.1

Host: apitestenv.vnforapps.com

Content-Type: application/json

Authorization:eyJraWQiOiJmWk1tV3pZR0RBckxHektvalNCK2w3SjFhMn NPXC9zQnNwOTlNNmNuM3F5MD0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJj NTAxNjYyOS04Zjc2LTQ1M2QtYjhlNC01MGJjZDI5YjI2NTAiLCJldmVudF9 pZCI6ImQ1ZjA3ZGViLTBlOWItNGRiYy05ZmFlLTUzZjEzNzJlMzA0OCIsIn Rva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXdzLmNvZ25pdG8uc2lnb mluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE2MDU4MTU3OTcsImlzcyI6 Imh0dHBzOlwvXC9jb2duaXRvLWlkcC51cy1lYXN0LTEuYW1hem9uYXdzLmN vbVwvdXMtZWFzdC0xXzJjSjFTZTFmSSIsImV4cCI6MTYwNTgxOTM5NywiaW F0IjoxNjA1ODE1Nzk3LCJqdGkiOiI0MmY1MzI3NS0zMTBkLTQyMGMtYmQ2Z S1kNTBmNTc0ZTQxMDIiLCJjbGllbnRfaWQiOiIxMGx2MDYxN281ZGljNTFl YnNucWVpaWpiNyIsInVzZXJuYW1lIjoiaW50ZWdyYWNpb25lcy52aXNhbmV 0QG5lY29tcGx1cy5jb20ifQ.iBZboGoCJeY8R2prDaTmBoj3e04NNzJ6PQ2 9pWKM6HqFgasy9GmiLA1DJbpjxOMGkb-etUuC0ZNtJ7LZyb08mQYudWkOALd OVplxyBRMI-Z3z0NciTfWjdE11x_Zr0Az2EinQv6wHeQZKkMrtTwwSSlhij yVmiQ9754DjdFP2gErTP5ThUiDAL-z3U-s4DqrDAoYEKP5symPpW6J06DoI 66llTt_y9CvvSLmdUk6xSjl_H3_BnpCZhnLMzpR2yXYPzj4PM-kkJPdTYjV7 mg6IEMPYQuCqvCHubBzpjp6k3vjnWuf2VDHJMThqLjdGg-9r7FU966AqH17 uGTcA_ubpQ

Scope:eyJzY29wZXMiOlt7ImtleSI6IjMzNzcyNmI5LWYyZWQtNDA3NC1iYWM 2LWJmNzAxMjUxN2JiZSIsImVsZW1lbnRzIjpbImNhcmQuY2FyZE51bWJlciI sImNhcmQuY3Z2MiJdfV19

{

 "key": "337726b9-f2ed-4074-bac6-bf7012517bbe",

 "payload":"in0NJH4mFWlPYuq6mMSImA4Ov8NyR0CE+GcdrDCxodtzLw93dwU O+yi9xTMwGYPTFB4HKwebM5DuwDNIlTwQIkcz2BPZ4l4GCUpZUReao3n39r2C k/3DQYgfJ3ip5h7ekd3uYtDTH4Y16jd+xGUghoyNuJT/e9Sz2MXJctOafXJOe KCAWgwlNwLGtoElD9wDNJR4fhn5+W1sbSn8AWt03lsTamzPdSfkiDj9WmyUSX T4wszazeU7R41HdCjsba+VuPShEo9nut1UastdpbYyr9Iyqj0JsHzRxiG+tSu ChxF3tbgPu5VT+MwJrX4GT7geJKkVg3XwaCDhj465rRnzALr6/1GnbxBNc49u cUhzwevgQ7DHB3MM/Q6hQvOeYbJ4veFfBnDQ0DJjNRH2ZBZdXbiUTlaYIcpo2 ejgGgpa2rrKuoUcnasUy1hCLClBP5YL8l1G6xdWVUoK2FOO1rQyV5XpUWUX7E d2lCcDINqrDZUdM7JkrLvNI0/rin/LtPJrUpiZeFO4iPJ4gU64W0lA5B/SMht LLed2Jj5TulS2eLj84KOup0L8Sdvj+4iYl/h6hFoXJFVwNByyKlXvZhSTEj7G 0qDn/Do6qkq+3Zn3nacoos7zF/MX6VocqLQpVMioUuNSLtq7OnXT9Ywu+cTRt k2U/eQ8PB58j7hRMojvCrut+sp97a375z9bj1e4v7Gu"

}



D. Response

   D.1 Tabla de Parámetros

Campo Tipo Longitud Obligatorio Descripción
TRAMA EXITOSA: 200
header Json SI Entidad que representa el encabezado de respuesta a la petición
header.ecoreTransactionUUID string($uuid) SI Identificador único de transacción para la plataforma
header.ecoreTransactionDate String SI Fecha de la operación expresada en formato UNIX TimeStamp
header.millis Integer($int32) SI Tiempo de ejecución de la operación
order Json SI Entidad que representa la información del pedido
order.purchaseNumber String Max 12 SI Número de pedido generado por el comercio
order.amount Number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
order.installment Integer($int32) NO Número de cuotas en que se realizará el pago
order.currency String Max 3 SI Código de moneda en la que se ejecuta la transacción
– PEN
– USD
order.externalTransactionId String($uuid) NO Id único de la transacción enviado por el comercio
order.authorizedAmount Number($double) SI Importe del pedido confirmado. Precisión hasta 8 valores enteros con 2 decimales
order.authorizationCode String Max 6 SI Código de autorización asignado a la aprobación de la transacción por la entidad resolutora
order.traceNumber String Max 6 SI Número asignado para identificar de forma unívoca a la transacción
order.transactionDate String SI Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
order.transactionId String Max 15 SI Identificador de la transacción asociado a la autorización
token Json NO Entidad que representa información de la tokenización para la tarjeta utilizada
token.tokenId String Max 16 NO Token identificador del objeto tokenizado
token.hash String Max 6 NO Hash identificador del objeto tokenizado
token.expiration String NO Fecha de caducidad del token expresado en formato nativo yyMMddHHmmSS
dataMap Json SI Entidad que representa información complementaria del pedido
dataMap.CVV2_VALIDATION String Max 1 NO
TRAMA ERRÓNEA: 400
errorCode Integer($int32) SI Código de error de la operación. Siempre es el valor 400
errorMessage String SI Mensaje de error de la operación
header Json SI Entidad que representa el encabezado de respuesta a la petición
header.ecoreTransactionUUID String($uuid) SI Identificador único de transacción para la plataforma
header.ecoreTransactionDate String SI Fecha de la operación expresada en formato UNIX TimeStamp
header.millis Integer($int32) SI Tiempo de ejecución de la operación
data Json SI Entidad que representa información complementaria del pedido
data.CURRENCY String Max 4 NO Código numérico de moneda en la que se ejecuta la transacción
data.TRANSACTION_DATE String NO Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
data.TERMINAL String Max 8 NO Número de terminal asociado a la transacción
data.ACTION_CODE String Max 3 NO 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
data.ACTION_DESCRIPTION String Max 6 NO Texto descriptivo de la autorización o denegación
data.TRACE_NUMBER String Max 6 SI Número asignado para identificar de forma unívoca a la transacción
date.AMOUNT String($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
data.MERCHANT String Max 9 NO Código de comercio VisaNet al cual pertenece la transacción
TRAMA ERRÓNEA: 401
description Text Max 1000 NO Descripción relacionada al error. Este error se presenta cuando las credenciales no son válidas
TRAMA ERRÓNEA: 406
description Text Max 1000 NO Descripción relacionada al error. Este error se presenta cuando hay muchas solicitudes con la misma carga


   D.2 Tramas de Ejemplo

  • Caso 200
  • Caso 400
  • Caso 401

Status Code 200 OK

Content-Type: application/json

{

 "header": {

  "ecoreTransactionUUID": "5bbb71c7-0e48-492b-ab32-97539d8f5379",

  "ecoreTransactionDate": 1605800588142,

  "millis": 3159

 },

 "order": {

  "purchaseNumber": "4780",

  "amount": 0.2,

  "installment": 0,

  "currency": "PEN",

  "externalTransactionId": "744D6EEA-7E6B-462F-9E24-825B07F69DAE",

  "authorizedAmount": 1.0,

  "authorizationCode": "005689",

  "traceNumber": "28122",

  "transactionDate": "201119104305",

  "transactionId": "953203240008644"

 },

 "token": {

  "token": "7000010038739391",

  "hash": "1f65ccffc76fcb9c3588f2ff28d6ed05e1fdf9cea19b7a811116a04d9fd0df93",

  "expiration": "211119154308"

 },

 "dataMap": {

  "CVV2_VALIDATION": "M"

 }

}



E. Códigos de Respuesta

Código Descripción
200 Validación de cuenta con petición cifrada realizado con éxito
400 Error en la consulta
401 Error relacionado al acceso no autorizado

API de Validación de Cuenta con Alcance y Petición Cifrada #

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.


A. Endpoint

Ambiente URL de API
Testing https://apitestenv.vnforapps.com/api.validate/v1/validate/{product}/{merchantId}
Producción https://apiprod..vnforapps.com/api.validate/v1/validate/{product}/{merchantId}
Ambiente
Testing
URL de API
https://apitestenv.vnforapps.com/api.validate/v1/validate/{product}/{merchantId}
Producción
URL de API
https://apiprod..vnforapps.com/api.validate/v1/validate/{product}/{merchantId}


B. Cifrado

En este punto se detallan los parámetros de encriptación del algoritmo AES y los elementos a codificar o encriptar.

   B.1 Cifrado

  • Parámetros de encriptación:
  • Algoritmo de encriptación: AES
  • Modo de encriptación: CBC
  • Relleno: PKCS7
  • Tamaño de la llave: 256 bits
  • Tamaño de bloque: 128 bits
  • Llave: baseKey (Api de Seguridad) se requiere convertir de string hexadecimal a byte array.
  • Vector de inicialización: iv (Api de Seguridad) se requiere convertir de string hexadecimal a byte array.

   B.2 Scope (codificación base 64)

Request

"scopes": [

 {

  "key": "b7380125c6fa346a3273902a8549b008ce2e42cc8b2c47b5a3b1d67c07011eb6",

  "elements": [

   "card.cardNumber",

   "card.cvv2"

  ]

 }

]


Campo Tipo Longitud Obligatorio Descripción
key Text Max 36 SI Token relacionado a la llave de encriptación a utilizar obtenido en la respuesta del API de Seguridad
elements Array SI Referencia a los atributos encriptados en el cuerpo de la consulta


   B.3 Request original (encriptación AES)

Request

Content-Type: application/json

{

 "channel": "pasarela",

 "captureType": "manual",

 "tokenize": true,

 "card": {

  "cardNumber": "/tIuqtJNRS+uMMLdB/qeRC8B5+mdkev/HFrD4lGvbxY=",

  "cvv2": "gss3+Ah0A2fgo5q6K9/rqA==",

  "expirationMonth": 4,

  "expirationYear": 24

 },

 "cardHolder": {

  "email": "jperez@gmail.com",

  "firstName": "Juan",

  "lastName": "Perez",

  "phoneNumber": "2132300"

 },

 "order": {

  "amount": 0.2,

  "authorizedAmount": 0,

  "currency": "PEN",

  "externalTransactionId": "353C74AF-7159-467C-812C-9816F5FD4C81",

  "installment": 0,

  "purchaseNumber": "2331",

  "tokenId": null,

  "transactionId": null

 }

}


Campo Tipo Longitud Obligatorio Descripción
channel String SI Canal desde donde se originó la operación.

– web Si son operaciones realizadas con el botón de pago web


– mobile Si son operaciones realizadas con la librería de pago app


– pasarela Si son operaciones realizadas con la API de autorización para el producto comercio electrónico


– callcenter Si son operaciones realizadas con la API de autorización para el producto telepago


– recurrent Si son operaciones realizadas con la API de autorización para el producto pago programado

captureType String SI Tipo de captura en el canal. Siempre es el valor manual
tokenize Boolean SI Indica si la tarjeta a validar será o no tokenizada. Si es el valor true la tarjeta será tokenizada, si es el valor false la tarjeta no será tokenizada
card Json SI Entidad que representa información de la tarjeta
card.cardNumber String SI Número de la tarjeta encriptado con la llave key y vector iv obtenidos en la respuesta del API de Seguridad
card.cvv2 String SI Número de CVV2 de la tarjeta encriptado con la llave key y vector iv obtenidos en la respuesta del API de Seguridad
card.expirationMonth Integer($int32) SI Mes de expiración
card.expirationYear Integer($int32) SI Año de expiración
cardHolder Json SI Entidad que representa la información del tarjetahabiente
cardHolder.email String Max 35 SI Correo electrónico del tarjetahabiente
cardHolder.firstName String Max 25 SI Nombres del tarjetahabiente
cardHolder.lastName String Max 50 SI Apellidos del tarjetahabiente
cardHolder.phoneNumber String Max 10 SI Teléfono del tarjetahabiente
order Json SI Entidad que representa la información del pedido
order.amount number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
order.authorizedAmount number($double) NO Importe del pedido confirmado. Precisión hasta 8 valores enteros con 2 decimales
order.currency String Max 3 SI Código de moneda en la que se ejecuta la transacción
– PEN
– USD
order.externalTransactionId string($uuid) NO Id único de la transacción enviado por el comercio
order.installment integer($int32) NO Número de cuotas en que se realizará el pago
order.purchaseNumber String Max 12 SI Número de pedido generado por el comercio
order.tokenId String Max 32 NO Id del token de transacción obtenido en la respuesta a la validación antifraude o del formulario de pago (*) No es obligatorio cuando el canal es recurrente
order.transactionId String Max 15 NO Identificador de la transacción asociado a la autorización


C. Request y casos

   C.1 Tabla de Parámetros

Campo Tipo Longitud Obligatorio Descripción
HEADER
accessToken Text Max 1000 SI Token generado con el API de Seguridad
Scope Text Max 1000 SI JSON codificado en base64 obtenido en el paso de encriptación
URL
product Text Max 100 SI Identificador de producto
– ecommerce
– pospc
– recurrent
merchantId Text Max 9 SI Código de comercio
BODY
key String Max 36 SI Token obtenido en la respuesta del API de Seguridad y que está relacionado a la llave y vector de encriptación que se usará en el Request original
payload String SI Request original encriptado con la llave token y vector iv obtenidos en la respuesta del API de Seguridad


   C.2 Trama de Ejemplo

Request

POST /api.validate/v1/validate/ecommerce/341198214 HTTP/1.1

Host: apitestenv.vnforapps.com

Content-Type: application/json

Authorization:eyJraWQiOiJmWk1tV3pZR0RBckxHektvalNCK2w3SjFhMn NPXC9zQnNwOTlNNmNuM3F5MD0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJj NTAxNjYyOS04Zjc2LTQ1M2QtYjhlNC01MGJjZDI5YjI2NTAiLCJldmVudF9 pZCI6ImQ1ZjA3ZGViLTBlOWItNGRiYy05ZmFlLTUzZjEzNzJlMzA0OCIsIn Rva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXdzLmNvZ25pdG8uc2lnb mluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE2MDU4MTU3OTcsImlzcyI6 Imh0dHBzOlwvXC9jb2duaXRvLWlkcC51cy1lYXN0LTEuYW1hem9uYXdzLmN vbVwvdXMtZWFzdC0xXzJjSjFTZTFmSSIsImV4cCI6MTYwNTgxOTM5NywiaW F0IjoxNjA1ODE1Nzk3LCJqdGkiOiI0MmY1MzI3NS0zMTBkLTQyMGMtYmQ2Z S1kNTBmNTc0ZTQxMDIiLCJjbGllbnRfaWQiOiIxMGx2MDYxN281ZGljNTFl YnNucWVpaWpiNyIsInVzZXJuYW1lIjoiaW50ZWdyYWNpb25lcy52aXNhbmV 0QG5lY29tcGx1cy5jb20ifQ.iBZboGoCJeY8R2prDaTmBoj3e04NNzJ6PQ2 9pWKM6HqFgasy9GmiLA1DJbpjxOMGkb-etUuC0ZNtJ7LZyb08mQYudWkOALdOVplxyBRMI-Z3z0NciTfWjdE11x_Zr0Az2EinQv6wHeQZKkMrtTwwSSlhij yVmiQ9754DjdFP2gErTP5ThUiDAL-z3U-s4DqrDAoYEKP5symPpW6J06DoI 66llTt_y9CvvSLmdUk6xSjl_H3_BnpCZhnLMzpR2yXYPzj4PM-kkJPdTYjV7 mg6IEMPYQuCqvCHubBzpjp6k3vjnWuf2VDHJMThqLjdGg-9r7FU966AqH17uGTcA_ubpQ

Scope:eyJzY29wZXMiOlt7ImtleSI6IjMzNzcyNmI5LWYyZWQtNDA3NC1iYWM 2LWJmNzAxMjUxN2JiZSIsImVsZW1lbnRzIjpbImNhcmQuY2FyZE51bWJlciI sImNhcmQuY3Z2MiJdfV19

{

 "key": "337726b9-f2ed-4074-bac6-bf7012517bbe",

 "payload":"in0NJH4mFWlPYuq6mMSImA4Ov8NyR0CE+GcdrDCxodtzLw93dwU O+yi9xTMwGYPTFB4HKwebM5DuwDNIlTwQIkcz2BPZ4l4GCUpZUReao3n39r2C k/3DQYgfJ3ip5h7ekd3uYtDTH4Y16jd+xGUghoyNuJT/e9Sz2MXJctOafXJOe KCAWgwlNwLGtoElD9wDNJR4fhn5+W1sbSn8AWt03lsTamzPdSfkiDj9WmyUSX T4wszazeU7R41HdCjsba+VuPShEo9nut1UastdpbYyr9Iyqj0JsHzRxiG+tSu ChxF3tbgPu5VT+MwJrX4GT7geJKkVg3XwaCDhj465rRnzALr6/1GnbxBNc49u cUhzwevgQ7DHB3MM/Q6hQvOeYbJ4veFfBnDQ0DJjNRH2ZBZdXbiUTlaYIcpo2 ejgGgpa2rrKuoUcnasUy1hCLClBP5YL8l1G6xdWVUoK2FOO1rQyV5XpUWUX7E d2lCcDINqrDZUdM7JkrLvNI0/rin/LtPJrUpiZeFO4iPJ4gU64W0lA5B/SMht LLed2Jj5TulS2eLj84KOup0L8Sdvj+4iYl/h6hFoXJFVwNByyKlXvZhSTEj7G 0qDn/Do6qkq+3Zn3nacoos7zF/MX6VocqLQpVMioUuNSLtq7OnXT9Ywu+cTRt k2U/eQ8PB58j7hRMojvCrut+sp97a375z9bj1e4v7Gu"

}



   C.3 Lenguajes

  • Node
  • JavaScript
  • Python

const request = require('request');

const options = {

 method: 'POST',

 url: 'https://apitestenv.vnforapps.com/api.validate/v1/validate/ecommerce/merchantId',

 headers: {

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

  'Scope': '{{scope}}

  accept: 'application/json',

  'content-type': 'application/json'

 },

 body: {

  key: "337726b9-f2ed-4074-bac6-bf7012517bbe",

  payload:

"in0NJH4mFWlPYuq6mMSImA4Ov8NyR0CE+GcdrDCxodtzLw93dwUO+yi9xTMwGYP TFB4HKwebM5DuwDNIlTwQIkcz2BPZ4l4GCUpZUReao3n39r2Ck/3DQYgfJ3ip5h 7ekd3uYtDTH4Y16jd+xGUghoyNuJT/e9Sz2MXJctOafXJOeKCAWgwlNwLGtoElD 9wDNJR4fhn5+W1sbSn8AWt03lsTamzPdSfkiDj9WmyUSXT4wszazeU7R41HdCj sba+VuPShEo9nut1UastdpbYyr9Iyqj0JsHzRxiG+tSuChxF3tbgPu5VT+MwJrX 4GT7geJKkVg3XwaCDhj465rRnzALr6/1GnbxBNc49ucUhzwevgQ7DHB3MM/Q6hQ vOeYbJ4veFfBnDQ0DJjNRH2ZBZdXbiUTlaYIcpo2ejgGgpa2rrKuoUcnasUy1hC LClBP5YL8l1G6xdWVUoK2FOO1rQyV5XpUWUX7Ed2lCcDINqrDZUdM7JkrLvNI0/ rin/LtPJrUpiZeFO4iPJ4gU64W0lA5B/SMhtLLed2Jj5TulS2eLj84KOup0L8Sd vj+4iYl/h6hFoXJFVwNByyKlXvZhSTEj7G0qDn/Do6qkq+3Zn3nacoos7zF/MX6 VocqLQpVMioUuNSLtq7OnXT9Ywu+cTRtk2U/eQ8PB58j7hRMojvCrut+sp97a37 5z9bj1e4v7Gu",

 },

json: true

};

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 Obligatorio Descripción
TRAMA EXITOSA: 200
header Json SI Entidad que representa el encabezado de respuesta a la petición
header.ecoreTransactionUUID string($uuid) SI Identificador único de transacción para la plataforma
header.ecoreTransactionDate String SI Fecha de la operación expresada en formato UNIX TimeStamp
header.millis Integer($int32) SI Tiempo de ejecución de la operación
order Json SI Entidad que representa la información del pedido
order.purchaseNumber String Max 12 SI Número de pedido generado por el comercio
order.amount Number($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
order.installment Integer($int32) NO Número de cuotas en que se realizará el pago
order.currency String Max 3 SI Código de moneda en la que se ejecuta la transacción
– PEN
– USD
order.externalTransactionId String($uuid) NO Id único de la transacción enviado por el comercio
order.authorizedAmount Number($double) SI Importe del pedido confirmado. Precisión hasta 8 valores enteros con 2 decimales
order.authorizationCode String Max 6 SI Código de autorización asignado a la aprobación de la transacción por la entidad resolutora
order.traceNumber String Max 6 SI Número asignado para identificar de forma unívoca a la transacción
order.transactionDate String SI Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
order.transactionId String Max 15 SI Identificador de la transacción asociado a la autorización
token Json NO Entidad que representa información de la tokenización para la tarjeta utilizada
token.tokenId String Max 16 NO Token identificador del objeto tokenizado
token.hash String Max 6 NO Hash identificador del objeto tokenizado
token.expiration String NO Fecha de caducidad del token expresado en formato nativo yyMMddHHmmSS
dataMap Json SI Entidad que representa información complementaria del pedido
dataMap.CVV2_VALIDATION String Max 1 NO
TRAMA ERRÓNEA: 400
errorCode Integer($int32) SI Código de error de la operación. Siempre es el valor 400
errorMessage String SI Mensaje de error de la operación
header Json SI Entidad que representa el encabezado de respuesta a la petición
header.ecoreTransactionUUID String($uuid) SI Identificador único de transacción para la plataforma
header.ecoreTransactionDate String SI Fecha de la operación expresada en formato UNIX TimeStamp
header.millis Integer($int32) SI Tiempo de ejecución de la operación
data Json SI Entidad que representa información complementaria del pedido
data.CURRENCY String Max 4 NO Código numérico de moneda en la que se ejecuta la transacción
data.TRANSACTION_DATE String NO Fecha de la transacción expresada en formato nativo yyMMddHHmmSS
data.TERMINAL String Max 8 NO Número de terminal asociado a la transacción
data.ACTION_CODE String Max 3 NO 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
data.ACTION_DESCRIPTION String Max 6 NO Texto descriptivo de la autorización o denegación
data.TRACE_NUMBER String Max 6 SI Número asignado para identificar de forma unívoca a la transacción
date.AMOUNT String($double) SI Importe del pedido autorizado. Precisión hasta 8 valores enteros con 2 decimales
data.MERCHANT String Max 9 NO Código de comercio VisaNet al cual pertenece la transacción
TRAMA ERRÓNEA: 401
description Text Max 1000 NO Descripción relacionada al error. Este error se presenta cuando las credenciales no son válidas
TRAMA ERRÓNEA: 406
description Text Max 1000 NO Descripción relacionada al error. Este error se presenta cuando hay muchas solicitudes con la misma carga


   D.2 Tramas de Ejemplo

  • Caso 200
  • Caso 400
  • Caso 401

Status Code 200 OK

Content-Type: application/json

{

 "header": {

  "ecoreTransactionUUID": "9a13c806-26b7-4fbe-babc-fc4afabc065a",

  "ecoreTransactionDate": 1605815878484,

  "millis": 3038

 },

 "order": {

  "purchaseNumber": "2331",

  "amount": 0.2,

  "installment": 0,

  "currency": "PEN",

  "externalTransactionId": "353C74AF-7159-467C-812C-9816F5FD4C81",

  "authorizedAmount": 1.0,

  "authorizationCode": "005746",

  "traceNumber": "28138",

  "transactionDate": "201119145755",

  "transactionId": "953203240009196"

 },

 "dataMap": {

  "CVV2_VALIDATION": "M"

 }

}



E. Códigos de Respuesta

Código Descripción
200 Validación de cuenta con alcance y petición cifrada realizado con éxito
400 Error en la consulta
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