NAV

API INESPAY

La API INESPAY proporciona al cliente/integrador el servicio de iniciación de pagos supervisado por Banco de España Transferencia Bancaria PSD2, regulado en la Directiva de Servicios de Pago europea PSD2 (Payment Services Directive 2).

La API INESPAY está basada en arquitectura de desarrollo web REST y, al ser independiente del tipo de sintaxis o lenguaje utilizado, puede ser integrada en cualquier plataforma.

Estructura Payflow

Seguridad

La API INESPAY requiere un proceso de autenticación mediante claves API-KEY y API-TOKEN, que se obtienen en el Dashboard INESPAY. Estas claves deben ser enviadas en cada llamada API en la cabecera (Header). Para obtenerlas, el cliente/integrador debe registrarse previamente en el Dashboard INESPAY mediante una dirección de email y una contraseña Registro INESPAY

Se utiliza el protocolo seguro HTTPS para el cifrado e intercambio de datos y el formato JSON para todas las peticiones y respuestas de la API.

NOTA: Nunca se deben exponer las claves de INESPAY en sitios públicos o en lenguajes de lado cliente, ya que supone un riesgo de seguridad.

Entornos

Con el objetivo de facilitar la integración, se ha habilitado un entorno SANDBOX idéntico al de PRODUCCIÓN que permitirá al cliente/integrador confirmar el correcto funcionamiento del servicio, antes de ser expuesto en PRODUCCIÓN. Las claves API del entorno SANDBOX se proporcionan automáticamente en el Dashboard INESPAY (sección Desarrollador/Claves API). Sin embargo, para acceder a las claves API del entorno de PRODUCCIÓN es necesario haber formalizado el contrato de prestación del servicio y solicitar a INESPAY el pase a PRODUCCIÓN, a través de su gestor personal o la dirección [sales@inespay.com].

Para realizar peticiones a uno u otro entorno (SANDBOX o PRODUCCIÓN), simplemente se deben utilizar las claves API-KEY y API-TOKEN correspondientes a cada entorno y cambiar la URL base de la API de la API INESPAY. Características:

País: España Usuario: user1 Contraseña: 1234 Clave de validación: 123456

País: Portugal Banco: SANTANDER Login: OBATPP05 Password: 9639639 OTP: 12345678

Una vez finalizado el pago se le mostrará la página de éxito con el texto Orden de pago completada. En caso de haber informado el parámetro urlOK en la llamada API, aparecerá automáticamente el botón CONTINUAR, cuya pulsación le redireccionará a la URL informada. Para una correcta integración, se debe comprobar la recepción del estado del pago vía notificación callback, cuyo proceso se explica en el apartado Notificación de pagos (Callback).

NOTA: Para comprobar el comportamiento de un flujo de pago KO (bancos españoles) inicie un pago por importe de 12 o 15 euros (también puede utilizar decimales) y complételo. INESPAY le mostrará un modal de error que le permitirá salir del proceso y redireccionarle automáticamente a la url informada en el parámetro urlError, en el caso de haberse informado en la petición a la API.

Soporte Técnico

Para cualquier duda relacionada con aspectos técnicos o con la integración del servicio, INESPAY pone a disposición del cliente/integrador la siguiente dirección de email: [support@inespay.com].

Iniciación de Pagos

El servicio de iniciación de pagos Transferencia Bancaria PSD2 dispone de dos modalidades de pago:

- Pago simple (unitario) (Modalidad estándar) Para pagos puntuales o específicos de compras o facturas. Siempre requiere la interacción del usuario/pagador para autorizar cada pago.

- Pago periódico o recurrente Para pagos por suscripción o compras fraccionadas. El usuario/pagador interactúa con el servicio una sola vez para autorizar el alta de una orden de pago con periodicidad, importe y concepto preestablecidos, no modificables a posteriori.

Independientemente de la tipología de pago, el servicio proporciona URLs de pago que redireccionan al usuario/pagador a la pasarela INESPAY, desde la que se le redirigirá a su interfaz bancaria para autorizar el pago.

Las URLs de pago pueden ser empleadas de dos formas diferentes, dependiendo de las necesidades del cliente/integrador:

Botón de pago para pagos en plataformas online basadas en web o app en las que las URLs se generan en tiempo real en base a la interacción del usuario/pagador con la plataforma del cliente/integrador. (P.ej.: Tienda o plataforma online en la que el importe y el concepto del pago dependen de los productos o servicios que seleccione el usuario/pagador en tiempo real).

Enlaces de pago para generar URLs de pago con los detalles de pago preestablecidos, con el objetivo de ser incorporadas a documentos físicos o digitales o enviarse posteriormente al usuario/pagador por cualquier canal. (P.ej.: Para reclamar un pago con importe y concepto de pago preestablecidos mediante un enlace de pago vía email, SMS, factura digital o física).

Pagos Simples

El servicio de iniciación de pagos simples proporciona al cliente/integrador una URL que incorporará los datos necesarios para iniciar una orden puntual de pago. Dicha URL redirigirá automáticamente al usuario/pagador a la pasarela INESPAY, donde se le mostrará un selector de bancos, junto a los detalles de la transacción y las Condiciones Generales del servicio. Desde el dashboard INESPAY el cliente/intgrador puede discriminar los bancos que se mostrarán a los usuarios/pagadores en el selector de bancos en el caso de que solo quiera trabajar con un grupo reducido de bancos.

Petición de inicio de pago simple

Entorno Tipo Url
SANDBOX (Pruebas) POST https://apiflow.inespay.com/san/url/signer
PRODUCCIÓN POST https://apiflow.inespay.com/pro/url/signer

Header

Parámetro Descripción
X-Api-Key API-KEY proporcionada por INESPAY
Authorization API-TOKEN proporcionado por INESPAY
Content-Type application/json

Body

Parámetro Requerido Tipo Descripción
subject String Concepto que aparecerá en el extracto bancario tanto del usuario/pagador como del cliente/integrador. Tamaño máximo: 160 caracteres
amount Number Importe del pago mutiplicado por 100, sin decimales. Por ejemplo: 35598 = 355,98 Euros
reference String Identificador único interno del pago, gracias al cual el cliente/integrador puede identificar una orden de pago en sus sistemas. Tamaño máximo: 100 caracteres
urlOk No String URL de retorno a la que se redirige el usuario/pagador cuando el pago se ha realizado con éxito. Este parámetro es esencial cuando el usuario/pagador proviene de una tienda o cualquier otro tipo de plataforma online. INESPAY envía los datos de la transacción a esta url vía POST para que el cliente/integrador pueda mostrar al usuario/pagador una página dinámica de éxito
urlError No String URL de retorno a la que se redirige al usuario/pagador cuando ha decidido salir de la pasarela de pago. INESPAY envía los datos de la transacción a esta url vía POST para que el cliente/integrador pueda mostrar al usuario/pagador una página dinámica de error
urlNotif No String URL a la que se notifica el éxito de una transacción (ver Notificación de pagos). Debe tenerse en cuenta que, tanto para el entorno de SANDBOX como para el de PRODUCCIÓN se debe informar una urlNotif de un entorno diferente al Local. En caso contrario, el proceso de notificación no se podrá llevar a cabo ya que la url informada debe ser accesible por INESPAY.
expireMinutes No Number Tiempo de validez de la URL de pago. En caso de no informarse, la validez de la URL será de 30 minutos. El máximo tiempo posible será de 259200 minutos (180 días)
paymentProduct No String Tipo de transferencia SEPA. Valores posibles: 0 = SEPA Ordinaria; 1 = SEPA Instantánea
accountDestiny No String IBAN de destino de la orden de pago. Sólo es necesario informar este parámetro en aquellos proyectos que dispongan de varias cuentas corrientes y se necesite destinar los fondos de cada orden de pago a una cuenta específica de dicho proyecto. En caso de que el proyecto disponga de una sola cuenta de destino o tenga activado el servicio de Balanceo de bancos, no es necesario informar este parámetro. Cualquier IBAN informado en este parámetro debe estar previamente validado en el proyecto, a través del Dashboard INESPAY (sección Mi Proyecto/Bancos). En caso contrario, la API devolverá un error
customRecipient No String Datos identificativos (nombre comercial, denominación social, dirección, etc…) del beneficiario de una orden de pago que aparecerá en la pasarela INESPAY. Sólo debe utilizarse este parámetro por aquellos clientes/integradores que necesiten destinar el importe de cada orden de pago a un NIF/CIF diferente dentro del mismo proyecto. Es utilizado por plataformas de facturación o ERPs que permiten a sus clientes la creación de órdenes de pago a través de un servicio de creación de facturas o similar y necesiten informar de un beneficiario diferente en cada orden de pago. Para utilizar este parámetro es necesario solicitar a INESPAY el servicio de Beneficiarios dinámicos ([sales@inespay.com]). Tamaño máximo: 200 caracteres (ver Ejemplo)
customData No String Campo personalizable que puede ser utilizado por el cliente/integrador para persistir cualquier tipo de dato que requiera recibir posteriormente a través del parámetro urlNotif (ver Notificación de pagos). Tamaño máximo: 4000 caracteres
partnerId No String Identificador único de partner facilitado por INESPAY. Sólo disponible para integradores específicos que hayan establecido previamente una relación de partenariado con INESPAY

Ejemplo de información del parámetro customRecipient Se utiliza el caracter “;” para indicar diferentes datos, indicando siempre como mínimo el identificador principal del beneficiario (nombre comercial o legal). Por Ejemplo: INDUVASA; Industrias Valencianas, SA; Calle del Sitio, 1; Valencia). Una vez completado el pago, INESPAY devolverá esta información al cliente/integrador a través del parámetro urlNotif (ver Notificación de pagos).

Respuesta a la petición de inicio de pago simple

Parámetro Tipo Descripción
url String URL de pago que accederá directamente a la pasarela INESPAY
idDebt String Identificador único de la orden de pago
status String Código de éxito (200) o error
description String Descripción del código status

Pagos Periódicos

El servicio de iniciación de pagos periódicos está basado en dos subservicios: Alta y Cancelación.

Alta de un Pago Periódico

Este servicio proporciona al cliente/integrador una URL que incorporará los datos necesarios para permitir al usuario/pagador iniciar una orden periódica de pago. El usuario/pagador accederá directamente a la interfaz de su entidad financiera para autorizar la orden. Previo a la petición de inicio de pago, el cliente/integrador debe mostrar al usuario/pagador el listado de bancos que incorporan este servicio, con sus frecuencias específicas (varían según cada banco). Ello requiere realizar una primera petición a la API INESPAY para obtener el listado de bancos. La posterior petición de inicio de pago a la API INESPAY incorporará el parámetro bankIdSelected y la frecuencia solicitada.

Petición del listado de bancos

Entorno Tipo Url
SANDBOX (Pruebas) GET https://apiflow.inespay.com/san/banks
PRODUCCIÓN GET https://apiflow.inespay.com/pro/banks

Header

Parámetro Descripción
X-Api-Key API-KEY proporcionada por INESPAY
Authorization API-TOKEN proporcionado por INESPAY
Content-Type application/json

Respuesta a la petición del listado de bancos

Parámetro Tipo Descripción
total Integer Número de elementos devueltos en data
data Array (Bank) Array de bancos
status String Código de éxito (200) o error
description String Descripción del código status

Array (Bank)

Parámetro Tipo Descripción
bankId String Identificador único del banco asignado por INESPAY
name String Nombre de la entidad
bankCodes Array (String) Array que contiene el código de entidad financiera
country String País al que pertenece la entidad financiera
enabled Integer Indica si el banco se encuentra activado (valor = 1) o desactivado (valor = 0) en la pasarela INESPAY. En caso de que la entidad financiera se encuentre desactivada (0) significa que, por razones técnicas o puntuales, no se encuentra operativa en el momento de realizar la llamada
enabledPeriodicPayment Integer Indica si el banco permite el inicio de pagos periódicos (1)
frequencyPeriodicPayment Array(String) Periodicidades admitidas (parámetro frequency) en caso de que el banco admita pagos periódicos
bankGroupId Integer Identificador del grupo en caso de que el banco se pueda agrupar en un nivel superior. En este caso se recomienda mostrar al usuario/pagador el nombre del nivel superior y presentar un nuevo selector con las entidades financieras que conforman el grupo
bankGroupName String Nombre del grupo bancario en caso de que el banco se pueda agrupar (P. Ej: Ruralvía - Grupo Caja Rural)

NOTA: La utilización del parámetro bankGroupId permite reducir considerablemente el listado de bancos para mostrar al usuario/pagador en un primer selector. En lugar de mostrar el nombre de todas las entidades que se reciben en la petición del listado de bancos, se recomienda agrupar aquellas que vengan informadas con el parámetro bankGroupId y mostrar únicamente el nombre del mismo (bankGroupName). En caso de que el usuario/pagador seleccione el grupo en el primer selector, se le deberá presentar un segundo selector que contenga el bankIdSelected del banco seleccionado.

Es posible realizar consultas filtradas sobre el listado de bancos, a continuación se describen los filtros disponibles:

Bancos activos por país

Consulta de los bancos activos por país:

Entorno Tipo Url
SANDBOX (Pruebas) GET https://apiflow.inespay.com/san/banks?enabled=1&country=ES
PRODUCCIÓN GET https://apiflow.inespay.com/pro/banks?enabled=1&country=ES

Bancos con la funcionalidad activa de pago periódico por país

Consulta de los bancos que tienen habilitado el servicio pagos periódicos por país:

Entorno Tipo Url
SANDBOX (Pruebas) GET https://apiflow.inespay.com/san/banks?enabledPeriodicPayment=1&country=ES
PRODUCCIÓN GET https://apiflow.inespay.com/pro/banks?enabledPeriodicPayment=1&country=ES

Petición de inicio de pago periódico

Entorno Tipo Url
SANDBOX (Pruebas) POST https://apiflow.inespay.com/san/url/periodic-payment-signer
PRODUCCIÓN POST https://apiflow.inespay.com/pro/url/periodic-payment-signer

Header

Parámetro Descripción
X-Api-Key API-KEY proporcionada por INESPAY
Authorization API-TOKEN proporcionado por INESPAY
Content-Type application/json

Body

Parámetro Requerido Tipo Descripción
subject String Concepto que aparecerá en el extracto bancario tanto del usuario/pagador como del cliente/integrador. Tamaño máximo: 160 caracteres
amount Number Importe del pago mutiplicado por 100, sin decimales. Por ejemplo: 35598 = 355,98 Euros
reference String Identificador único interno del pago, gracias al cual el cliente/integrador puede identificar una orden de pago en sus sistemas. Tamaño máximo: 100 caracteres
frequency String Periodicidad de ejecución del pago periódico. La frecuencia informada debe de estar admitida por el banco seleccionado por el usuario/pagador
debtorAccount String IBAN del usuario/pagador que va a autorizar la orden periódica de pago (cuenta del ordenante)
startDate String Fecha a partir de la cual se inician los pagos periódicos en formato YYYY-MM-DD. La fecha informada en este parámetro debe ser siempre posterior a la fecha presente. En caso de venir informado el valor Monthly en el parámetro frequency, el día del mes informado en este parámetro se considerará como “día de ejecución”. Ejemplo: El valor 2021-10-18 significará que el primer pago se llevará a cabo el 18 de octubre de 2021 y los siguientes pagos se llevarán a cabo los días 18 de los sucesivos meses
endDate No String Fecha final de la orden del pago periódico en formato YYYY-MM-DD. Si no viene informado este parámetro se considerará un pago periódico indefinido en el tiempo
urlOk No String URL de retorno a la que se redirige el usuario/pagador cuando el pago se ha realizado con éxito. Este parámetro es esencial cuando el usuario/pagador proviene de una tienda o cualquier otro tipo de plataforma online. INESPAY envía los datos de la transacción a esta url vía POST para que el cliente/integrador pueda mostrar al usuario/pagador una página dinámica de éxito
urlError No String URL de retorno a la que se redirige al usuario/pagador cuando ha decidido salir de la pasarela de pago. INESPAY envía los datos de la transacción a esta url vía POST para que el cliente/integrador pueda mostrar al usuario/pagador una página dinámica de error
urlNotif No String URL a la que se notifica el éxito de una transacción (ver Notificación de pagos). Debe tenerse en cuenta que, tanto para el entorno de SANDBOX como para el de PRODUCCIÓN se debe informar una urlNotif de un entorno diferente al Local. En caso contrario, el proceso de notificación no se podrá llevar a cabo ya que la url informada debe ser accesible por INESPAY.
expireMinutes No Number Tiempo de validez de la URL de pago. En caso de no informarse, la validez de la URL será de 30 minutos. El máximo tiempo posible será de 259200 minutos (180 días)
accountDestiny No String IBAN de destino de la orden de pago. Sólo es necesario informar este parámetro en aquellos proyectos que dispongan de varias cuentas corrientes y se necesite destinar los fondos de cada orden de pago a una cuenta específica de dicho proyecto. En caso de que el proyecto disponga de una sola cuenta de destino o tenga activado el servicio de Balanceo de bancos, no es necesario informar este parámetro. Cualquier IBAN informado en este parámetro debe estar previamente validado en el proyecto, a través del Dashboard INESPAY (sección Mi Proyecto/Bancos). En caso contrario, la API devolverá un error
customRecipient No String Datos identificativos (nombre comercial, denominación social, dirección, etc…) del beneficiario de una orden de pago que aparecerá en la pasarela INESPAY. Sólo debe utilizarse este parámetro por aquellos clientes/integradores que necesiten destinar el importe de cada orden de pago a un NIF/CIF diferente dentro del mismo proyecto. Es utilizado por plataformas de facturación o ERPs que permiten a sus clientes la creación de órdenes de pago a través de un servicio de creación de facturas o similar y necesiten informar de un beneficiario diferente en cada orden de pago. Para utilizar este parámetro es necesario solicitar a INESPAY el servicio de Beneficiarios dinámicos ([sales@inespay.com]). Tamaño máximo: 200 caracteres (ver Ejemplo)
customData No String Campo personalizable que puede ser utilizado por el cliente/integrador para persistir cualquier tipo de dato que requiera recibir posteriormente a través del parámetro urlNotif (ver Notificación de pagos). Tamaño máximo: 4000 caracteres
partnerId No String Identificador único de partner facilitado por INESPAY. Sólo disponible para integradores específicos que hayan establecido previamente una relación de partenariado con INESPAY

Ejemplo de información del parámetro customRecipient Se utiliza el caracter “;” para indicar diferentes datos, indicando siempre como mínimo el identificador principal del beneficiario (nombre comercial o legal). Por Ejemplo: INDUVASA; Industrias Valencianas, SA; Calle del Sitio, 1; Valencia). Una vez completado el pago, INESPAY devolverá esta información al cliente/integrador a través del parámetro urlNotif (ver Notificación de pagos).

Respuesta a la petición de pago periódico

Parámetro Tipo Descripción
url String URL del pago periódico que accederá directamente a la interfaz bancaria, según el IBAN informado en el parámetro debtorAccount
idDebt String Identificador único de la orden de pago
status String Código de éxito (200) o error
description String Descripción del código status

Cancelación de un pago periódico

Este servicio proporciona al cliente/integrador una URL que incorporará los datos necesarios para cancelar una orden periódica de pago previamente autorizada. El usuario/pagador accederá directamente a la interfaz de su entidad financiera para autorizar la cancelación de la orden periódica de pago. Debe tenerse en cuenta que un pago periódico no puede modificarse por lo que, en caso de requerir la modificacion de algún dato, es necesario cancelar la orden periódica original y generar una nueva.

Petición de cancelación de pago periódico

Entorno Tipo Url
SANDBOX (Pruebas) POST https://apiflow.inespay.com/san/url/cancel-periodic-payment-signer
PRODUCCIÓN POST https://apiflow.inespay.com/pro/url/cancel-periodic-payment-signer

Header

Parámetro Descripción
X-Api-Key API-KEY proporcionada por INESPAY
Authorization API-TOKEN proporcionado por INESPAY
Content-Type application/json

Body

Parámetro Requerido Tipo Descripción
transactionId String Parámetro devuelto en la notificación recibida en el alta de un pago periódico Notificación de pagos
reference String Identificador interno del pago del cliente/integrador con el que puede identificar la orden de cancelación de pago. Tamaño máximo: 100 caracteres
urlOk No String URL de retorno a la que se redirige el usuario/pagador cuando la cancelación del pago se ha realizado con éxito. Este parámetro es esencial cuando el usuario/pagador proviene de una plataforma online. INESPAY envía los datos de la orden a este parámetro para que el cliente/integrador pueda mostrar al usuario/pagador una página dinámica de éxito
urlError No String URL de retorno a la que se redirige al usuario/pagador cuando ha decidido salir de la pasarela de pago sin cancelar el pago periódico. INESPAY envía los datos de la orden a este parámetro para que el cliente/integrador pueda mostrar al usuario/pagador una página dinámica de error
urlNotif No String URL a la que se notifica el éxito de la cancelación del pago periódico (ver Notificación de pagos). Debe tenerse en cuenta que, tanto para el entorno de SANDBOX como para el de PRODUCCIÓN se debe informar una urlNotif de un entorno diferente al Local. En caso contrario, el proceso de notificación no se podrá llevar a cabo
expireMinutes No Number Tiempo de validez de la URL generada. En caso de no informarse, la validez de la URL será de 30 minutos. El máximo tiempo posible será de 259200 minutos (180 días)
customData No String Campo personalizable que puede ser utilizado por el cliente/integrador para persistir cualquier tipo de dato que requiera recibir posteriormente a través del parámetro urlNotif (ver Notificación de pagos) (P. Ej: {“name”:“Bruce Wayne”, “numDoc”:“11111112L”}). Tamaño máximo: 4000 caracteres
partnerId No String Identificador único de partner facilitado por INESPAY. Sólo disponible para integradores específicos que hayan establecido previamente una relación de partenariado con INESPAY

Respuesta a la petición de cancelación de un pago periódico

Parámetro Tipo Descripción
url String URL de cancelación del pago periódico que accederá directamente a la interfaz bancaria, según el parámetro transactionId informado en la petición de cancelación de pago periódico
idDebt String Identificador único de la orden de pago
status String Código de éxito (200) o error
description String Descripción del código status

Notificación de pagos (Callback)

INESPAY realiza la notificación de un pago (Callback) en el preciso instante en el que un usuario/pagador ha ejecutado con éxito una orden de pago. Dicha notificación se realiza mediante una petición de tipo POST HTTP en formato JSON a la url informada en el parámetro urlNotif indicada en la llamada API de inicio de pago. Esta petición POST es invisible para el usuario/pagador. Las transacciones no finalizadas con éxito o los abandonos no se notifican nunca a través de este parámetro urlNotif.

IP La dirección IP fija del sistema notificaciones de INESPAY es 52.209.221.251.

NOTA 1 El parámetro opcional urlOK no debe ser utilizado como Callback. INESPAY recomienda utilizar el parámetro urlOk únicamente para redirigir al usuario/pagador hacia la página web de éxito del cliente. Con el fin de permitir al cliente/integrador configurar una página de éxito dinámica, INESPAY incorpora los mismos parámetros vía POST que se envían a la urlNotif.

NOTA 2 En caso de que el usuario/pagador se salga del proceso de pago, INESPAY lo redirigirá al parámetro urlError informado por el cliente/integrador en la petición de inicio de pago. Con el fin de permitir al cliente/integrador configurar una página de error dinámica, INESPAY incorpora los mismos parámetros vía POST que se envían a la urlNotif.

La notificación del pago OK incorpora los siguientes parámetros:

Parámetro Tipo Descripción
dataReturn String (JSON) Contiene los parámetros del pago:
    status String Código de éxito (200)
    description String Descripción del código status
    transactionId String Identificador único del pago en los sistemas INESPAY
    amount Number Importe del pago mutiplicado por 100 sin decimales
    reference String Identificador interno de la orden de pago asignado por el cliente/integrador
    dateInitPayment Number Timestamp en milisegundos. Zona horaria UTC
    accountDestiny String IBAN de la cuenta destino donde se han transferido los fondos de la orden de pago
    holderOrigin String Titular de la cuenta origen desde la que se ha realizado el pago. En caso de que la entidad bancaría no proporcione dicha información este parámetro presentará el valor null. Para comprobar la recepción de este parámetro en modo SANDBOX, seleccione BANKINTER en la pasarela INESPAY
    accountOrigin String IBAN de la cuenta origen desde la que se ha realizado el pago. En caso de que la entidad bancaría no proporcione dicha información este parámetro presentará el valor null. Para comprobar la recepción de este parámetro en modo SANDBOX, seleccione BANKINTER en la pasarela INESPAY
    customData String Campo personalizable que puede ser utilizado por el cliente/integrador para persistir datos y que le sean devueltos en la notificación.
signatureDataReturn String Firma de dataReturn calculada con el algoritmo HmacSHA256, utilizando como clave la APIKEY proporcionada por INESPAY y codificada en base64

Verificación respuesta (Firma)

Se debe calcular la firma de los datos devueltos en dataReturn y compararla con la firma devuelta por INESPAY en signatureDataReturn. De esta forma se asegura que la respuesta procede de INESPAY. A continuación detallamos el proceso para realizar el cálculo de la firma:

  1. Aplicamos el algoritmo HmacSHA256 directamente sobre dataReturn que se encuentra codificado en Base64, utilizando como clave la API-KEY proporcionada por INESPAY. De esta forma obtenemos el hash de dataReturn
  2. Convertimos el hash obtenido en una cadena de texto hexadecimal en minúsculas.
  3. Codificamos el resultado del punto anterior en Base64 y obtenemos la firma calculada.
  4. Comparamos la firma calculada con el parámetro signatureDataReturn devuelto en el Callback:
    • Si firma calculada == signatureDataReturn, aseguramos que la respuesta procede de INESPAY (OK).
    • Si firma calculada != signatureDataReturn, los datos han sido alterados por un tercero y no son válidos (KO).

Servicios Adicionales

Consulta de órdenes de pago generadas

Este servicio opcional es una herramienta de consulta detallada de URLs de pago generadas en un periodo de tiempo concreto, pensada para aquellos clientes/integradores que emplean el servicio en forma de Enlaces de Pago.

Petición de consulta de órdenes de pago generadas

Entorno Tipo Url
SANDBOX (Pruebas) POST https://apiflow.inespay.com/san/info/payment-orders
PRODUCCIÓN POST https://apiflow.inespay.com/pro/info/payment-orders

Header

Parámetro Descripción
X-Api-Key API-KEY proporcionada por INESPAY
Authorization API-TOKEN proporcionada por INESPAY
Content-Type application/json

Body

Parámetro Requerido Tipo Descripción
dateFrom String Fecha en formato milisegundos UTC
dateTo No Number Fecha en formato milisegundos UTC. Si no se especifica, se realiza la búsqueda hasta la fecha actual
pageRequest String Número de página solicitada. La primera página es siempre la número 1
pageSize No String Número máximo de elementos devueltos por página. Si no se especifica, el tamaño de página por defecto es de 50 elementos. El máximo valor admitido es 300
orderAsc No Boolean Tipo de ordenación por fecha de creación: true=ASC o false=DESC

Respuesta a la petición de consulta de órdenes de pago generadas

Parámetro Tipo Descripción
itemsReturned Number Número de elementos (paymentOrders) devueltos en la página actual
currentPage Number Número de página actual
totalItems Number Número total de elementos (paymentOrders). Es la suma de todos los elementos de todas las páginas
totalPages Number Número total de páginas existentes
paymentOrders Array (PaymentOrder) Array de elementos paymentOrders
status String Código de éxito (200) o error
description String Descripción del código status

Lista de órdenes de pago (paymentOrders)

Parámetro Tipo Descripción
idDebt String Identificador único de la orden de pago
enabled Boolean Indica si la orden de pago se encuentra activa
amount Number Importe de la orden de pago mutiplicado por 100 sin decimales
subject String Concepto de la orden de pago
reference String Identificador interno de la orden de pago asignado por el cliente/integrador
holderDestiny String Nombre del titular de la cuenta destino
accountDestiny String Número de cuenta destino de la transferencia (formato IBAN)
customRecipient String Campo informativo del beneficirio del pago
customData String Campo personalizable del cliente/integrador
urlLong String URL firmada y segura de INESPAY
urlShort String URL corta generada por el servicio de generación de la orden de pago
urlShortClicks Number Número de clicks realizados sobre la url especificado en urlShort
codStatus String Código del estado de la orden de pago: OK=Éxito, ERROR=Error, PENDING=Orden de pago no iniciada por el usuario/pagador
periodicOriginAccount  String IBAN del usuario/pagador que ha aceptado el pago periódico
periodicFrequency  String Periodicidad de ejecución del pago periódico
periodicStartDate  String Fecha a partir de la cual se inician los pagos periódicos
periodicEndDate  String Fecha final de los pagos periódicos
periodicExecutionRule  String Regla ejecución pago periódico
periodicDayOfExecution  String Día de ejecución pago periódico
createAt Number Fecha de creación en formato milisegundos
updateAt Number Fecha de actualización en formato milisegundos
expireAt Number Fecha de caducidad en formato milisegundos

Activar/Desactivar ordenes de pago

Este servicio opcional es una herramienta de activación/desactivación de URLs de pago, pensada para aquellos clientes/integradores que emplean el servicio en forma de de Enlaces de Pago. En caso de haberse producido la caducidad de una URL de pago, es posible reactivarlo. Asimismo, el cliente/integrador puede desactivar una URL de pago antes de alcanzar su fecha de vencimiento.

Petición de activación/desactivación de órdenes de pago

Entorno Tipo Url
SANDBOX (Pruebas) POST https://apiflow.inespay.com/san/update/enable-disable-payment-order
PRODUCCIÓN POST https://apiflow.inespay.com/pro/update/enable-disable-payment-order

Header

Parámetro Descripción
X-Api-Key API-KEY proporcionada por INESPAY
Authorization API-TOKEN proporcionada por INESPAY
Content-Type application/json

Body

Parámetro Requerido Tipo Descripción
idDebt String Identificador de la orden de pago devuelto por el servicio signer
enable Boolean true = orden de pago activada, false = orden de pago desactivada

Respuesta a la petición de activación/desactivación de órdenes de pago

Parámetro Tipo Descripción
status String Código de éxito (200) o error
description String Descripción del código status

Códigos de respuesta

Listado de códigos de estado y error devuelto por la API INESPAY.

Código Descripción Información
200 OK_DEFAULT Éxito petición API (OK)
E300 ERROR_DEFAULT Error genérico (KO)
E301 INVALID_PARAMS Error parámetros incorrectos

Librerías API (SDK)

Con el objetivo de facilitar la integración de la API INESPAY, se proporciona una librería que facilita y simplifica la integración de la misma, de forma que sólo es necesario copiar y pegar unas sencillas líneas de código.

PHP

Descargar SDK PHP API PAYFLOW v1.0.6

Pago simple

Permite generar pagos en tiempo real con una cuenta bancaria de destino fija asociada al cliente/integrador, informada y validada en el Dashboard de Inespay. El enlace de pago emitido tiene una validez de 30 minutos desde que es generado.

Pago simple
------------
<?php
require_once('payflow_sdk_php_vXXXX/InespayApiPublic.php');

$environmentApiInespay = InespayApiPublic::ENV_SAN; //Sandbox (pagos fictícios)
//$environmentApiInespay = InespayApiPublic::ENV_PRO; //Producción (pagos reales)
$apiKeyInespay = 'APIKEY API INESPAY';
$tokenInespay = 'TOKEN API INESPAY';

$apiInespay = new InespayApiPublic();
$apiInespay->setEnvironmentInespay($environmentApiInespay);
$apiInespay->setApiKeyInespay($apiKeyInespay);
$apiInespay->setTokenInespay($tokenInespay);

//Campos a rellenar dinámicamente
$apiInespay->setSubject('Prueba pago simple INESPAY');   //Concepto del pago
$apiInespay->setAmount(1.10);                //Importe con 2 decimales separados por un punto
$apiInespay->setReference('ID_2021_AP');     //Identificador interno del pago personalizable por el cliente/integrador  

//Opcionales
$apiInespay->setUrlOk('https://www.example.com/ok.php'); //Url retorno éxito
$apiInespay->setUrlError('https://www.example.com/error.php'); //Url retorno error
$apiInespay->setUrlNotif('https://www.example.com/notif.php'); //Url notificación (Callback)
$apiInespay->setCustomData("Custom data personalizado");

$response = $apiInespay->generateSimplePaymentUrl(); //Llamada síncrona API Inespay

if ( $response->getStatusCode() == InespayApiPublic::STATUS_CODE_SUCCESS){
    //Éxito generación URL de pago firmada
    echo $response->getUrlSigned();
}else{
    //Error generación URL
}
?>

Notificación del Estado de la Transacción (Callback)

Verificación de la firma de los datos enviados por INESPAY para asegurar que la respuesta procede de INESPAY y no han sido alterados. Esta verificación se debe realizar siempre por el cliente/integrador de la API en su lado de servidor.

Notificación del Estado de la Transacción (Callback)
-----------------------------------------------------
<?php
require_once('InespayApiPublic_vXXXX/InespayApiPublic.php');

$apiKeyInespay = 'APIKEY API INESPAY';
$apiInespay = new InespayApiPublic();
$apiInespay->setApiKeyInespay($apiKeyInespay);

//Params received in POST    
if (!empty( $_POST )) {

       $apiInespay->setDataReturn($_POST['dataReturn']);
       $apiInespay->setSignatureDataReturn($_POST['signatureDataReturn']);

        //Firma OK, la respuesta ha sido enviada por INESPAY
        if ($apiInespay->isDataReturnValid()){
            echo "<p>FIRMA OK, realizar tareas en el Cliente Final</p>";
            echo "<p>status=".$apiInespay->getStatusFromDataReturn()."</p>";
            echo "<p>description=".$apiInespay->getDescriptionFromDataReturn()."</p>";
            echo "<p>amount=".$apiInespay->getAmountFromDataReturn()."</p>";
            echo "<p>reference=".$apiInespay->getReferenceFromDataReturn()."</p>";
            echo "<p>transactionId=".$apiInespay->getTransactionIdFromDataReturn()."</p>";
            echo "<p>customData=".$apiInespay->getCustomDataFromDataReturn()."</p>";

        } else {
            echo "<p>FIRMA KO, firma inválida revise los parámetros</p>";
        }
    }
?>

Pago periódico

Permite generar órdenes de pago periódicas. El enlace de pago emitido tiene una validez de 30 minutos desde que es generado.

Pago periódico
---------------
<?php
require_once('payflow_sdk_php_vXXXX/InespayApiPublic.php');

$environmentApiInespay = InespayApiPublic::ENV_SAN; //Sandbox (pagos fictícios)
//$environmentApiInespay = InespayApiPublic::ENV_PRO; //Producción (pagos reales)
$apiKeyInespay = 'APIKEY API INESPAY';
$tokenInespay = 'TOKEN API INESPAY';

$apiInespay = new InespayApiPublic();
$apiInespay->setEnvironmentInespay($environmentApiInespay);
$apiInespay->setApiKeyInespay($apiKeyInespay);
$apiInespay->setTokenInespay($tokenInespay);

//Campos a rellenar dinámicamente
$apiInespay->setSubject('Prueba pago periódico INESPAY');   //Concepto del pago
$apiInespay->setAmount(1.10);                //Importe con 2 decimales separados por un punto
$apiInespay->setReference('PE_2021_FO');     //Identificador interno del pago personalizable por el cliente/integrador
$apiInespay->setFrequency('Monthly');    
$apiInespay->setDebtorAccount('ES2501822200160201933547'); //Sanbox debtorAccount
$apiInespay->setStartDate('2021-12-01');

//Opcionales
$apiInespay->setUrlOk('https://www.example.com/ok.php'); //Url retorno éxito
$apiInespay->setUrlError('https://www.example.com/error.php'); //Url retorno error
$apiInespay->setUrlNotif('https://www.example.com/notif.php'); //Url notificación (Callback)
$apiInespay->setCustomData("Custom data personalizado");
$apiInespay->setEndDate('2022-12-01');

$response = $apiInespay->generatePeriodicPaymentUrl(); //Llamada síncrona API Inespay

if ( $response->getStatusCode() == InespayApiPublic::STATUS_CODE_SUCCESS){
    //Éxito generación url de pago firmada
    echo $response->getUrlSigned();
}else{
    //Error generación url
}
?>

Cancelación pago periódico

Permite cancelar órdenes de pago periódicas que se han generado previamente con el servicio de Alta de Pagos Periódicos.

Cancelación pago periódico
---------------------------
<?php
require_once('payflow_sdk_php_vXXXX/InespayApiPublic.php');

$environmentApiInespay = InespayApiPublic::ENV_SAN; //Sandbox (pagos fictícios)
//$environmentApiInespay = InespayApiPublic::ENV_PRO; //Producción (pagos reales)
$apiKeyInespay = 'APIKEY API INESPAY';
$tokenInespay = 'TOKEN API INESPAY';

$apiInespay = new InespayApiPublic();
$apiInespay->setEnvironmentInespay($environmentApiInespay);
$apiInespay->setApiKeyInespay($apiKeyInespay);
$apiInespay->setTokenInespay($tokenInespay);

//Campos a rellenar dinámicamente
$apiInespay->setTransactionId('XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXXXXX');  //transactionId received in callback periodic payment signer
$apiInespay->setReference('CP_2021_CANCEL'); 
$response = $this->apiInespay->generateCancelPeriodicPaymentUrl(); //Llamada síncrona API Inespay

//Opcionales
$apiInespay->setUrlOk('https://www.example.com/ok.php'); //Url retorno éxito
$apiInespay->setUrlError('https://www.example.com/error.php'); //Url retorno error
$apiInespay->setUrlNotif('https://www.example.com/notif.php'); //Url notificación
$apiInespay->setCustomData("Custom data personalizado");

$response = $apiInespay->generatePeriodicPaymentUrl(); //Llamada síncrona API Inespay

if ( $response->getStatusCode() == InespayApiPublic::STATUS_CODE_SUCCESS){
    //Éxito generación url de pago firmada
    echo $response->getUrlSigned();
}else{
    //Error generación url
}
?>