Pago Programado

#


Flujo Pago Web Flujo Pago Web

Recibe puntualmente el pago de tus clientes! Usa nuestra solución Pago Programado.
Para comenzar a disfrutar los beneficios de Pago Programado, sigue los siguientes pasos:


Pasos que debes seguir Detalle de cada paso
Paso 1. ¿Recibes cobros recurrentes de tus clientes? Asegúrate de contar con nuestra solución de Pago Programado.
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. Solicita tu afiliación Si no estás afiliado; es decir, no cuentas con un código de comercio en producción Niubiz, puedes afiliarte a través de https://contactos.niubiz.com.pe/afiliateniubiz/pos/
Paso 4. 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!

Descripción y flujos de solución #

A. Descripción y Flujos de solución

Este documento provee la información de cómo se debe realizar la integración de los comercios con el respectivo formulario de registro de afiliación de cargos recurrentes de Niubiz. A continuación, se presenta el flujo de la solución.

Flujo Pago Web Flujo Pago Web
  • Para invocar el formulario de afiliación recurrente (1a) hay que enviar los parámetros de códigoComercio, etiqueta, producto, maxAmount posteriormente se invocará el formulario de solicitud de afiliación (1b).


Requisitos y restricciones #

Como parte de los requisitos y restricciones considerar los siguientes puntos.


  • El comercio debe estar afiliado en la plataforma de cargos recurrentes de Niubiz.

  • El Comercio debe conocer su código de comercio(merchantId).

  • mismo, para comenzar la integración primero se debe verificar los siguientes requisitos.

  • El Landing de Afiliación REC funciona en los siguientes navegadores actualizados al protocolo TLS versión 1.2:

    • IE 11+
    • Chrome 30+
    • Firefox 27+
    • Safari 7+
    • Opera 12+
  • El formulario Landing de Afiliación REC se adapta a todos los dispositivos móviles (smartphones y tablets) con los siguientes sistemas operativos:

    • Android
    • iOS
  • Ten en cuenta los lineamientos para configurar visualmente tu web aquí.

  • Recuerda que debes considerar los requisitos y restricciones que aplican a la solución que estás integrando, debes revisar esta sección.

Pasos para integrarse #

Paso 1. Invocación del formulario de la Landing de afiliación



A. Descripción y Consideraciones

El comercio que realiza la integración debe realizar una invocación “post” hacia la url de la Landing de afiliación REC. La manera más común (y sugerida) es realizarlo a través de un formulario.



B. Endpoint

Ambiente URL API
Testing http://afiliacionrecurrentes-test.us-east-1.elasticbeanstalk.com/Afiliacion
Producción https://pago-programado.niubiz.com.pe/Afiliacion
Ambiente
Testing
URL API
http://afiliacionrecurrentes-test.us-east-1.elasticbeanstalk.com/Afiliacion
Producción
URL API
https://pago-programado.niubiz.com.pe/Afiliacion


C. Request y casos

   C.1 Tabla de parámetros


Campo Tipo Longitud Obligatorio Descripción
Invocación al formulario
codigoComercio Texto Max 9 SI Es el código del comercio generado por Visanet. Es un parámetro obligatorio. Consta de 9 caracteres numéricos. Es un parámetro obligatorio. Ejm.: “123456789”
etiqueta Texto SI Es el nombre de la etiqueta personalizada cuyo valor se mostrará en el formulario de afiliación. Este indicará al usuario el dato y tipo de dato que ingresará. Es un parámetro obligatorio. Ejm: “Teléfono”.
productos Texto NO Es el listado de códigos de productos que se desea mostrar en el listado de productos del Landing de afiliación REC. Es un parámetro opcional. Los códigos de productos enviados en este parámetro deben estar separados por comas. Ejm.: “1000001,100002”. Cuando no se envía este parámetro o este se envía sin ningún valor, el formulario del Landing de afiliación mostrará todos los productos registrados para el código de comercio enviado.
maxAmount Numerico NO Cuando este parámetro viaja con el valor de “Si” entonces el formulario del Landing de recurrentes mostrará el campo “Monto Máximo”. Este campo es opcional para el usuario, es decir, puede dejarlo vacío.


  C.2 Trama ejemplo:

Request

<form method="post" action="url">

 <input type="text" id="codigoComercio" name="codigoComercio" maxlength="9" required/>

 <input type="text" id="etiqueta" name="etiqueta" required/>

 <select id="productos" name="productos">

 <option value="">Seleccione</option>

 </select>

 <input type="submit" value="Invocar Afiliacion">

</form>


Donde:

  • method: se debe utilizar el método “post”
  • action: se debe indicar la URL de destino de la invocación según el ambiente con el cual se esté realizando la integración.


D. Response

  D.1 Tabla de Parámetros

Campo Tipo Longitud Obligatorio Descripción
RESPUESTA OK: Formulario de solicitud de afiliación
Datos del servicio a afiliar
Prueba Texto Max 24 SI Etiqueta que se envía al formulario de afiliación REC
Nombres Texto Max 50 SI Nombre del beneficiario
Apellido Paterno Texto Max 50 SI Apellido paterno del beneficiario
Datos del titular de la tarjeta
Número de Tarjeta Numeric Max 19 SI Número de tarjeta del titular
Fecha de expiración Date Max 50 SI Fecha de expiración de la tarjeta del titular
Nombres Texto Max 50 SI Nombre del titular
Apellido Paterno Texto Max 50 SI Apellido paterno del titular
Tipo de Doc.
Identidad del TH
Option SI Tipo de documento de identidad del Tarjetahabiente
Número Doc.
Identidad del TH
Texto Max 8 SI Número de documento de identidad del Tarjetahabiente
Teléfono Texto Max 15 SI Número telefónico del titular
Email Texto Max 75 SI Correo electrónico del titular
RESPUESTA NO OK: Error
Message Texto SI Ocurrió un inconveniente. Por favor, vuelva a intentarlo.


E. Formulario de solicitud de afiliación

  • Caso OK
  • Caso No OK

¡Felicitaciones! Has terminado con todos los pasos para integrarte. Ahora puedes ir a las siguientes secciones:

Comportamiento de la solución #


  • Escasez de datos.





  • Error en alguno de los campos.





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
456879853 Dólares Liquidación automática

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.

Para coordinar tu fecha de certificación envía un correo al equipo de integraciones: integraciones.nubiz@necomplus.com, indicando lo siguiente:

  • 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 tener en tu página web:


Requisitos y Restricciones Generales
Página Principal y de Pago
  • Solicitud de afiliación exitosa
  • Debes revisar el back office de la solución (https://190.119.232.55/comercio/login) y confirmar que se haya registrado la solicitud de afiliación.
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:


Requisitos y Restricciones Generales
Solicitud de afiliación exitosa
  • Debes revisar el back office de la solución (https://pagoprogramado.niubiz.com.pe/comercio/login) y confirmar que se haya registrado la solicitud de afiliación.

#

Descripción y flujo de la solución #

El flujo del botón de pago web se describe a continuación:  


Flujo Pago Web Flujo Pago Web  

  • El Comercio haciendo uso de sus credenciales genera un token de acceso (1a) y haciendo uso del token de acceso genera un token de sesión (2a). El Comercio con el token de sesión y otros parámetros (canal, importe, número de pedido, etc.) invoca al botón de pago web (3a).

  • El Tarjetahabiente ingresa la información de su tarjeta en el formulario de pagos y presiona el botón “Pagar” (4a), entonces el botón de pago web devolverá al Comercio un token de transacción (4c) como respuesta a la validación de la transacción. Finalmente, el Comercio envía un token de acceso, el token de transacción del punto anterior y otros parámetros (canal, importe, número de pedido, etc.) para realizar la autorización de la transacción (5a).

  • Se recomienda tener un flujo de extorno automático para el pago (5c) . Actualmente manejamos un tiempo de espera de 60 segundos para todas las API del flujo, por lo que si pasa de este tiempo se retornará un código 504. El comercio puede cortar la comunicación en la cantidad de tiempo que considere (< 60 seg) , y posteriormente consumir el API de consulta (para saber el estado de la venta) y el API de Anulación por Extorno que están en APIs Complementarias..

Requisitos y restricciones #

Para comenzar la integración, primero verifica los siguientes requisitos:


  • El comercio afiliado recibirá un Usuario y una Contraseña (Credenciales) para poder invocar al API de Seguridad y crear un token de acceso, el cual se utilizará en siguientes llamadas a APIs funcionales.

  • El comercio es responsable de custodiar sus credenciales de acceso, por ende, estas no deben estar dentro del código fuente de su aplicación o publicadas en algún repositorio público (Github, Bitbucket, etc.), dado que se trata de información sensible.

  • El botón de pago web funciona en los siguientes navegadores actualizados al protocolo TLS versión 1.2:

    • Microsoft Edge 80+
    • Chrome 30+
    • Firefox 27+
    • Safari 7+
  • El botón de pago web se adapta a todos los dispositivos móviles (smartphones y tablets) con los siguientes sistemas operativos:

    • Android
    • iOS
  • El botón de pago web puede integrarse en el componente Android “WebView” (El cual se basa en Chromium). Se recomienda implementar el “WebView” a partir de la versión 33.

  • El botón de pago web puede integrarse en el componente iOS “WKWebView” (El cual se basa en Chromium). Este componente tiene soporte a partir de la versión iOS 8.0 y OS 10.10.

  • En el botón “Pagar” dentro del formulario de pagos no se debe utilizar un color hexadecimal bajo, dado que el color del texto del botón “Pagar” será siempre blanco.

  • Se recomienda tener un flujo de extorno automático para el pago. Actualmente manejamos un tiempo de espera de 60 segundos para todas las API del flujo, por lo que si pasa de este tiempo se retornará un código 504. El comercio puede cortar la comunicación en la cantidad de tiempo que considere (< 60 seg), y posteriormente consumir el API de consulta (para saber el estado de la venta) y el API de Anulación por Extorno que están en APIs Complementarias.

  • Para que un pago se pueda efectuar se deben seguir todos los pasos del flujo descrito (Pasos para integrarse) , desde el paso 1 hasta el paso 4, en caso contrario saldrá denegado. Para efectos de un nuevo intento de pago aplica lo mismo, ya que se necesitan nuevos valores de sesión para realizar otro pago.

Pasos para integrarse #

Paso 1. Crear un token de acceso (Seguridad).



A. Descripción y consideraciones

Para poder insertar el botón de pago web en el sitio del comercio es necesario crear un token de acceso, el cual permitirá la comunicación con las diferentes APIs funcionales. Cabe indicar que este token de acceso tiene un tiempo de vigencia para poder ser utilizado. Si el token de acceso llega a caducar se debe generar uno nuevo.

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

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



B. Endpoint

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


C. Request y casos

   C.1 Tabla de campos

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


  C.2 Trama ejemplo:

Request

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

Host: apisandbox.vnforappstest.com

Authorization: Basic Z2lhbmNhZ2FsbGFyZG9AZ21haWwuY29tOkF2MyR0cnV6

(*) Authorization: Basic EncodeBase64("userName" + ":" + "password")


D. Response

  D.1 Tabla de campos

Campo Tipo Longitud Obligatorio Descripción
TRAMA EXITOSA: 201
accessToken Texto Max 1000 SI Token de acceso generado con la API
TRAMA ERROR: 401
description Texto Max 1000 SI Descripción relacionada al error

  D.1 Trama de ejemplo

  • Caso 201
  • Caso 401

Status Code 201 Created

Content-Type: text/plain

eyJraWQiOiJmWk1tV3pZR0RBckxHektvalNCK2w3SjFhMnNPXC9zQnNwOT lNNmNuM3F5MD0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJkMTlhM2I0Zi0 1NzYxLTRlYTEtYjBmYS1iNWNiNjU5OWQ5NWQiLCJjb2duaXRvOmdyb3Vwc yI6WyJjdXN0b2RpbyJdLCJldmVudF9pZCI6ImM2OTZmZjVkLTZjOTctNDE 4NC05MGIxLTA5NjM2MWY4M2E2ZSIsInRva2VuX3VzZSI6ImFjY2VzcyIsI nNjb3BlIjoiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXR oX3RpbWUiOjE2MDIxMTM4NzksImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLW lkcC51cy1lYXN0LTEuYW1hem9uYXdzLmNvbVwvdXMtZWFzdC0xXzJjSjFT ZTFmSSIsImV4cCI6MTYwMjExNzQ3OSwiaWF0IjoxNjAyMTEzODc5LCJqd GkiOiJiOTVmOGU0ZS1kZGE4LTRkZmUtOTc0NC1kOGQwZGEyMDFlMzMiL CJjbGllbnRfaWQiOiIxMGx2MDYxN281ZGljNTFlYnNucWVpaWpiNyIsInV zZXJuYW1lIjoiZ2lhbmNhZ2FsbGFyZG9AZ21haWwuY29tIn0.GrO2XLoM nChN3Dg6H8G7LC3ZY4O_c1-DwvRYHCx8iiDqprFMK7jU43vo6W4ILNqP_Q A1sDoEQaD9HJJ7iLfVBojh1tgiFyzFzkX4T3m63eHRSFfIZAToTGYOQo eZchsYb3UAffvrzR1JlUPjwf3U1YRfBEu8ueIR6_OUMZdXC8TLS3pqEpX nPr6S-_bndpFRs5wZpt0BPSJ4OnhM2AYh6pqFucjL9nsPmIaujJQVwdR8 oNcrfeFuIv5t55H_DRDpQCSYstac1nFSm00P3EMdbOX6Lh8dTU5dBOXe1 7Bfh7mDEP-FnF_J47COVFB_sYh7JXyePfK6kKTlSeV0Ev0pew

Comportamiento de la solución #


  • Comportamiento del formulario ante errores.

    Si faltase completar algún campo del formulario de pagos, al momento de dar clic en “Pagar”, el formulario vibrará y resaltará el(los) campo(s) en rojo.





  • Comportamiento del formulario cuando está procesando la transacción.

    Cuando el formulario de pagos está procesando una transacción, se taparán los campos input y se mostrará una imagen de procesando.





  • Comportamiento del formulario para mostrar íconos de las marcas

    El formulario de pagos con tarjeta mostrará, según el prefijo de la tarjeta (42=Visa, 54=Mastercard, 37=Amex, 36=Diners), el logo de la marca de tarjeta ingresada en el input “Número de Tarjeta”.





  • Comportamiento del formulario para modo oscuro

    El formulario de pagos emerge sobre la tienda virtual, la cual oscurece levemente.





  • Comportamiento del formulario de dimensión en la pantalla, de como se ve el popup en web y móvil

    El formulario de pagos emerge sobre la tienda virtual, la cual oscurece levemente.





  • Comportamiento del formulario validación del campo mes y año de la tarjeta

    Cuando en el input “MM/AA” se ingresa una fecha de vencimiento no válida, el formulario de pagos con tarjeta pondrá un marco rojo al input al no haberse ingresado un dato válido.





Data de pruebas #

Te dejamos aquí lo que necesitas para realizar tus pruebas. También encontrarás en la parte inferior una demo de la solución.

Códigos de comercio

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

Las credenciales que debes utilizar serán las siguientes:

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

Casos Exitosos

 

Casos denegados

  • Escenario Número Mes/año CVV Codigo de Acción
    Tarjeta Vencida 5455450920104193 04/2019 111 101
    Monto no permitido 5101641510088022 03/2023 111 102
    Fondos insuficientes 5115422225052734 04/2023 111 113
    Tarjeta no registrada 5109616945811695 04/2023 111 116
    Tarjeta no operativa (error de CVV) 5111053459429167 04/2023 111 118
    Tarjeta inválida 5243798112895755 04/2023 111 129
    Tarjeta perdida 5102851705613406 04/2023 111 180
    Tarjeta robada 5105291169837406 04/2023 111 208
    Problemas de comunicación 5110556146550527 04/2023 111 209
    Problemas de comunicación con antifraude 5103216920074983 04/2203 111 666
    Transacción denegada por posible fraude 5106248239975235 04/2023 111 670
    Error en autenticación 5110109669996279 04/2023 111 678
    Comercio no válido 5111886224425808 04/2023 111 754
    Contactar emisor 5100538637530152 04/2023 111 191
    Afiliación a REC no exitosa 5105724434046726 04/2023 111 0

  • Escenario Número Mes/año CVV Codigo de Acción
    Tarjeta Vencida 371160951393498 01/2019 111 101
    Fondos insuficientes 371327381068590 01/2024 111 116
    Tarjeta no registrada 370374318198760 01/2024 111 118
    Tarjeta no operativa (error de CVV) 371045592151431 01/2024 111 129
    Tarjeta inválida 311111111111111 01/2024 111 180
    Transacción inválida 371448663683011 01/2024 111 190
    Tarjeta perdida 371540506350103 01/2024 111 207
    Tarjeta robada 371631798378041 01/2024 111 207
    Tienda inhabilitada 371032217060171 01/2024 111 401
    La operación ya se encuentra en un depósito 371950721798434 01/2024 111 476
    Código de comercio no existe o es inválido 371143974183930 01/2024 111 479
    Problemas de comunicación 349999481735341 01/2024 111 666
    Problemas de comunicación con antifraude 371912610030071 01/2024 111 668
    Transacción denegada por posible fraude 340010734769274 01/2024 111 670
    Error en autenticación 371461600047737 01/2024 111 678

  • Escenario Número Mes/año CVV Codigo de Acción
    Tarjeta Vencida 36953865709495 04/2019 111 101
    Fondos insuficientes 36344311372031 05/2024 111 116
    Tarjeta no registrada 36165277401757 05/2024 111 118
    Tarjeta no operativa (error de CVV) 36161915044570 05/2024 111 129
    Tarjeta inválida 32222222222222 05/2024 111 180
    Transacción inválida 36552045187919 05/2024 111 190
    Tarjeta perdida 36174837286856 05/2024 111 207
    Tarjeta robada 36482193207873 05/2024 111 207
    Tienda inhabilitada 36445590978511 05/2024 111 401
    La operación ya se encuentra en un depósito 36346782517671 05/2024 111 476
    Código de comercio no existe o es inválido 36344465159135 05/2024 111 479
    Problemas de comunicación 36484318063264 05/2024 111 666
    Problemas de comunicación con antifraude 36124375262074 05/2024 111 668
    Transacción denegada por posible fraude 36165181797514 05/2024 111 670
    Error en autenticación 36006973925121 05/2024 111 678

 

Demo

A continuación te mostramos una demo de esta solución para que puedas probarla.


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