NAV

API INESPAY

La API INESPAY se puede integrar tanto como botón de pago o como un servicio de generación de enlaces o URLs de pago. En este último caso (generación de enlaces o URLs de pago), la API INESPAY envía al cliente/integrador los enlaces que posteriormente podrá reenviar al usuario/pagador por cualquier canal para que inice el proceso de pago.

La API INESPAY está construida como un servicio REST, por lo que puede ser integrada en cualquier plataforma, independientemente del lenguaje de programación utilizado.

Estructura Payflow

Seguridad

La API INESPAY requiere un proceso de autenticación mediante las claves API-KEY y una API-TOKEN, que pueden ser obtenidas desde el Dashboard INESPAY. Estas claves son de envío obligatorio en cada llamada API y deben ser proporcionadas en la cabecera (Header) de cada petición. Para acceder al Dashboard INESPAY, el cliente/integrador debe de registrarse previamente: 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 de SANDBOX idéntico al de PRODUCCIÓN que permitirá al cliente/integrador confirmar la correcta puesta en marcha del servicio. Las claves API del entorno de SANDBOX se proporcionan automáticamente en el Dashboard INESPAY (sección Claves API), las cuales permiten iniciar pagos ficticios en las interfaces bancarias de Sandbox con las credenciales que se proporcionan en este mismo apartado. Sin embargo, para acceder a las claves API del entorno de PRODUCCIÓN es necesario ponerse en contacto con el equipo de de INESPAY, solicitando el pase a PRODUCCIÓN. Para ello, el cliente/integrador debe enviar un correo a su gestor personal de INESPAY o a la dirección soporte@inespay.com. El equipo de INESPAY verificará que se han realizado las pruebas oportunas y comprobará que se dispone de la información necesaria para formalizar el contrato.

Al tratarse de 2 entornos idénticos (SANDBOX y PRODUCCIÓN), para realizar peticiones a uno u otro entorno, simplemente se deben cambiar las claves API-KEY y API-TOKEN en la llamada a la API INESPAY. Características:

En caso de que la interfaz bancaria solicite alguna clave adicional en el proceso de Login, utilice el valor user1. Para finalizar el pago la interfaz bancaria solicitará una clave adicional de validación. Utilice cualquier combinación de caraceteres numéricos o alfanuméricos. El resultado OK se muestra en una página del navegador con el texto Operación de pago realizada correctamente.

Servicios de Iniciación de Pagos

La API INESPAY proporciona un servicio de pasarela de pago por transferencia bancaria basado en la normativa europea PSD2 (Payment Service Directive 2), denominado Servicio de Iniciación de Pagos. El Servicio proporciona URLs de pago que redirigen al usuario/pagador a una interfaz dedicada de su entidad financiera, en la que deberá introducir las mismas claves que utiliza en su banca online. Todo el flujo se realizará en un entorno seguro de la interfaz bancaria, a la que sólo el usuario/pagador tiene acceso. Las citadas interfaces bancarias pertenecen exclusivamente a las entidades financieras que las han desarrollado y, por tanto, las claves de acceso y autorización de la transacción sólo se informan en ellas. INESPAY, como Entidad de pago regulada no tiene acceso o contacto alguno con las claves bancarias del usuario/pagador, eliminando cualquier posibilidad o riesgo de fraude.

Inicio de Pagos Simples

Este servicio proporciona al cliente/integrador una URL que incorporará los datos necesarios para iniciar una orden puntual de pago. Para facilitar al usuario/pagador el acceso a su interfaz bancaria, se contemplan dos posibilidades:

Acceso al selector de entidades de la Pasarela INESPAY (solución estándar)

La URL de pago redirigirá al usuario/pagador a la página de selección de bancos proporcionada por INESPAY.

Petición de inicio de pago

Entorno Tipo Url
SANDBOX (Pruebas) POST https://apiflow.inespay.com/san/url/signer
PRODUCCIÓN POST https://apiflow.inespay.com/pro/url/signer
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 detalle del pago y en el extracto bancario tanto del usuario/pagador como del cliente
amount Number Importe del pago mutiplicado por 100, sin decimales. Por ejemplo: 35598 = 355,98 Euros
reference String Identificador interno del pago del cliente, con el que puede identificar una orden de pago en sus sistemas
urlOk No String URL de retorno (URL Redirect) donde vuelve el usuario/pagador cuando el pago se ha realizado con éxito. Este dato es esencial cuando el usuario/pagador proviene de una tienda o cualquier otro tipo de plataforma online y debe volver al mismo entorno del que procede, donde se le puede mostrar el estado de su pedido/compra/factura o simplemente el resultado del pago
urlError No String URL de retorno (URL Redirect) donde se redirige al usuario/pagador cuando el pago no se ha podido completar. Es recomendable facilitar la misma URL de la plataforma de la que procede, donde se le muestre un mensaje de KO. De esta manera el usuario/pagador puede reintentar el pago nuevamente o seleccionar otro método de pago
urlNotif No String URL donde se notifica el resultado de la transacción a los sistemas del cliente/integrador, sin repercusión para el usuario/pagador. 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, la notificación generará un error
holderDestiny No String Nombre completo del titular de la cuenta destino (beneficiario)
accountDestiny No String Número de cuenta del beneficiario de la transferencia (formato IBAN). Cualquier IBAN informado en este parámetro debe estar previamente validado en el Dashboard INESPAY. En caso contrario, se producirá un error al realizar la llamada
expireMinutes No Number Tiempo de validez del pago generado. En caso de no informarse, la validez del pago será de 30 minutos. El máximo tiempo posible será de 259200 minutos (180 días)
customRecipient No String Campo informativo personalizable que permite incorporar los datos de un beneficiario. Este campo se utiliza por plataformas de facturación o similares que necesitan informar un destinatario diferente en cada pago. Dentro de este parámetro se pueden informar, por ejemplo, los siguientes datos del beneficiario del pago: nombre comercial; razón social; dirección … Se utiliza el caracter “;” para indicar saltos de línea. Una vez completado el pago, INESPAY devolverá esta información al cliente/integrador vía urlNotif
customData No String Campo personalizable que puede ser utilizado para persistir cualquier tipo de dato que se requiera por el integrador con un tamaño máximo de 4000 caracteres. En caso de indicarse será informado en el resultado transacción
partnerId No String Identificador único de partner facilitado por INESPAY. Sólo disponible para integradores específicos que hayan establecido previamente esta relación con INESPAY

A continuación mostramos un ejemplo de uso del campo customData en formato JSON serialiazado como String

customData = {“name”:“Bruce Wayne”, “numDoc”:“11111112L”}

Respuesta

Parámetro Tipo Descripción
url String URL firmada de acceso 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

Integración del selector de entidades en la plataforma del cliente/integrador

La URL de pago redirigirá al usuario/pagador directamente a su interfaz bancaria. Una vez finalizado el proceso de pago, se redirigirá automáticamente al usuario/pagador a la urlOk o urlError informada en los parámetros API.

La apertura automática de la interfaz bancaria requiere realizar una primera petición a la API INESPAY para obtener el listado de bancos disponibles para iniciar una orden de pago. Gracias a este listado, el cliente/integrador debe configurar y presentar al usuario/pagador un selector de entidades financieras en su propia plataforma online. La posterior petición de inicio de pago a la API INESPAY incorporará el parámetro bankIdSelected, lo que permitirá redirigir automáticamente al usuario/pagardor a la interfaz bancaria correspondiente.

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
Parámetro Descripción
X-Api-Key API-KEY proporcionada por INESPAY
Authorization API-TOKEN proporcionado por INESPAY
Content-Type application/json

Respuesta

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

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 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 pertenezca a un grupo bancario. En caso de que la entidad financiera pertenezca a un grupo de bancos, se recomienda mostrar al usuario/pagador el nombre del grupo bancario y cargar un nuevo selector con las entidades financieras que conforman dicho grupo
bankGroupName String Nombre del grupo bancario en caso de que el banco pertenezca a un grupo bancario

NOTA: Gracias a los grupos de bancos, es posible reducir considerablemente el listado de bancos disponibles para mostrar al usuario/pagador. Las entidades financieras que pertenecen a un grupo vienen identificadas con el parámetro bankGroupId. En lugar de mostrar el nombre de todas las entidades que se reciben en la petición del listado de bancos, se recomienda ocultar aquellas que pertenecen a un grupo y mostrar únicamente el nombre del mismo: bankGroupName. De esta manera, si el usuario/pagador selecciona el nombre del grupo, se le deberá presentar un segundo selector que contenga los bancos del grupo seleccionado, con el fin de capturar el parámetro bankIdSelected que se utilizará para realizar la petición de inicio de pago a la API INESPAY.

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

Entorno Tipo Url
SANDBOX (Pruebas) POST https://apiflow.inespay.com/san/url/signer
PRODUCCIÓN POST https://apiflow.inespay.com/pro/url/signer
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 detalle del pago y en el extracto bancario tanto del usuario/pagador como del cliente
amount Number Importe del pago mutiplicado por 100, sin decimales. Por ejemplo: 35598 = 355,98 Euros
reference String Identificador interno del pago del cliente, con el que puede identificar una orden de pago en sus sistemas
bankIdSelected No String Identificador del banco al que será redirigido automáticamente el usuario/pagador.
urlOk No String URL de retorno (URL Redirect) donde vuelve el usuario/pagador cuando el pago se ha realizado con éxito. Este dato es esencial cuando el usuario/pagador proviene de una tienda o cualquier otro tipo de plataforma online y debe volver al mismo entorno del que procede, donde se le puede mostrar el estado de su pedido/compra/factura o simplemente el resultado del pago
urlError No String URL de retorno (URL Redirect) donde se redirige al usuario/pagador cuando el pago no se ha podido completar. Es recomendable facilitar la misma URL de la plataforma de la que procede, donde se le muestre un mensaje de KO. De esta manera el usuario/pagador puede reintentar el pago nuevamente o seleccionar otro método de pago
urlNotif No String URL donde se notifica el resultado de la transacción a los sistemas del cliente/integrador, sin repercusión para el usuario/pagador. 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, la notificación generará un error
holderDestiny No String Nombre completo del titular de la cuenta destino (beneficiario)
accountDestiny No String Número de cuenta del beneficiario de la transferencia (formato IBAN). Cualquier IBAN informado en este parámetro debe estar previamente validado en el Dashboard INESPAY. En caso contrario, se producirá un error al realizar la llamada
expireMinutes No Number Tiempo de validez del pago generado. En caso de no informarse, la validez del pago será de 30 minutos. El máximo tiempo posible será de 259200 minutos (180 días)
customRecipient No String Campo informativo personalizable que permite incorporar los datos de un beneficiario. Este campo se utiliza por plataformas de facturación o similares que necesitan informar un destinatario diferente en cada pago. Dentro de este parámetro se pueden informar, por ejemplo, los siguientes datos del beneficiario del pago: nombre comercial; razón social; dirección … Se utiliza el caracter “;” para indicar saltos de línea. Una vez completado el pago, INESPAY devolverá esta información al cliente/integrador vía urlNotif
customData No String Campo personalizable que puede ser utilizado para persistir cualquier tipo de dato que se requiera por el integrador con un tamaño máximo de 4000 caracteres. En caso de indicarse será informado en el resultado transacción
partnerId No String Identificador único de partner facilitado por INESPAY. Sólo disponible para integradores específicos que hayan establecido previamente esta relación con INESPAY

A continuación mostramos un ejemplo de uso del campo customData en formato JSON serialiazado como String

customData = {“name”:“Bruce Wayne”, “numDoc”:“11111112L”}

Respuesta

Parámetro Tipo Descripción
url String URL firmada de acceso a la interfaz bancaria informada con el parámetro bankIdSelected
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

Inicio de Pagos Periódicos

El servicio de Inicio de Pagos Periódicos está basado en tres subservicios: Alta, Cancelación y Consulta.

Alta de Pago Periódico

Este servicio proporciona al cliente/integrador una URL que incorporará los datos necesarios para iniciar una orden periódica de pago. El usuario/pagador accederá directamente a la interfaz de su entidad financiera para autorizar la orden periódica de pago.

Petición

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
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 detalle del pago y en el extracto bancario
amount Number Importe del pago mutiplicado por 100, sin decimales. Por ejemplo: 35598 = 355,98 Euros
reference String Identificador interno del pago del cliente/integrador, con el que puede identificar una orden de pago en sus sistemas
frequency String Periodicidad de ejecución del pago periódico. Es necesario consultar el parámetro frequencyPeriodicPayment del servicio Bancos para obtener los posibles valores que admite cada banco
debtorAccount String IBAN del usuario/pagador que va a autorizar la orden periódica de pago
startDate String Fecha a partir de la cual se inician los pagos periódicos (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-06-18 significará que el primer pago se llevará a cabo el 18 de junio 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 (YYYY-MM-DD). Si no viene informado este parámetro se considerará un pago indefinido en el tiempo
urlOk No String URL de retorno (URL Redirect) donde vuelve el usuario/pagador cuando la transacción se ha realizado con éxito. Este dato es esencial cuando el usuario/pagador proviene de una tienda o cualquier otro tipo de plataforma online y debe volver al mismo entorno del que procede, donde se le puede mostrar el estado de su solicitud o simplemente el resultado del proceso
urlError No String URL de retorno (URL Redirect) donde se redirige al usuario/pagador cuando la transacción no se ha podido completar. Es recomendable facilitar la misma URL de la plataforma de la que procede, donde se le muestre un mensaje de KO. De esta manera el usuario/pagador puede reintentar la operación nuevamente
urlNotif No String URL donde se notifica el resultado de la transacción, sin repercusión para el usuario/pagador. 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, la notificación generará un error
holderDestiny No String Nombre completo del titular de la cuenta destino (beneficiario)
accountDestiny No String Número de cuenta del beneficiario de la transferencia (IBAN). Cualquier IBAN informado en este parámetro debe estar previamente validado en el Dashboard INESPAY. En caso contrario, se producirá un error al realizar la llamada
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)
customRecipient No String Campo informativo personalizable que permite incorporar los datos de un beneficiario. Este campo se utiliza por plataformas de facturación o similares que necesitan informar un destinatario diferente en cada pago. Dentro de este parámetro se pueden informar, por ejemplo, los siguientes datos del beneficiario del pago: nombre comercial; razón social; dirección … Se utiliza el caracter “;” para indicar saltos de línea. Una vez completado el pago, INESPAY devolverá esta información al cliente/integrador vía urlNotif
customData No String Campo personalizable que puede ser utilizado para persistir cualquier tipo de dato que se requiera por el integrador con un tamaño máximo de 4000 caracteres. En caso de indicarse será informado en el resultado transacción
partnerId No String Identificador único de partner facilitado por INESPAY. Sólo disponible para integradores específicos que hayan establecido previamente esta relación con INESPAY

Respuesta

Parámetro Tipo Descripción
url String URL firmada de acceso 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 Pagos Periódicos

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.

Petición

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
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 resultado transacción
reference String Identificador interno del pago del cliente/integrador con el que puede identificar la orden de cancelación de pago.
urlOk No String URL de retorno (URL Redirect) donde vuelve el usuario/pagador cuando la cancelación del pago se ha realizado con éxito. Este dato es esencial cuando el usuario/pagador proviene de una plataforma online y debe volver al mismo entorno del que procede
urlError No String URL de retorno (URL Redirect) donde se redirige al usuario/pagador cuando la cancelación del pago no se ha podido completar
urlNotif No String URL donde se notifica el resultado de la transacción, sin repercusión para el usuario/pagador. 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, la notificación generará un error
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 para persistir cualquier tipo de dato que se requiera por el integrador con un tamaño máximo de 4000 caracteres. En caso de indicarse será informado en el resultado transacción.
partnerId No String Identificador único de partner facilitado por INESPAY. Sólo disponible para integradores específicos que hayan establecido previamente esta relación con INESPAY

Respuesta

Parámetro Tipo Descripción
url String URL firmada de acceso a la interfaz bancaria
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

Consulta de Pagos Periódicos: Pendiente publicación versión beta

Este servicio permite obtener el estado del pago periódico en cualquier momento, pudiendo consultar en tiempo real si la transacción sigue vigente o ha sido dada de baja por el usuario/pagador.

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

El estado de la transacción (Ok / Error) se notifica mediante una petición de tipo POST HTTP a una URL facilitada por el cliente/integrador en la llamada de inicio de pago. Para recibir la información del estado de la transacción (Callback) el cliente/integrador tiene dos posibilidades:

  1. Utilización exclusiva del parámetro urlNotif para recibir el resultado OK de una transacción (solución recomendada): Cuando el usuario/pagador finaliza el pago con éxito, INESPAY realiza una petición POST a la urlNotif del cliente/integrador con los datos de la transacción en formato JSON. Dicha petición es invisible al usuario que realiza el pago. Es altamente recomendable informar la urlNotif en la llamada a INESPAY y dedicarla exclusivamente para recibir el resultado OK de la transacción. De esta manera, se utilizarán las urlOk/urlError únicamente para redirigir al usuario/pagador hacia las correspondientes páginas web, en función del resultado de la transacción y la urlNotif para enviar el resultado OK de la transacción. Tal y como se ha descrito, la urlNotif sólo se utiliza para notificar el resultado OK. Las transacciones con resultado Error no se notifican nunca a través de este parámetro, ya que podría generar errores indeseados de interpretación.

  2. Utilización de los parámetros urlOk/urlError: Dependiendo del estado de la transacción (Ok o Error), la pasarela INESPAY realizará una redirección web en el navegador del usuario/pagador hacia la URL correspondiente. En caso de éxito, la pasarela redirigirá al usuario/pagador a la urlOk y en caso de error a la urlError. Además de redirigir al usuario/pagador al finalizar el proceso de pago, estas urlOk/urlError disponen de toda la información de la transacción, por lo que pueden utilizarse para obtner el resultado de la transacción. A pesar de su doble utilidad, no recomendamos recibir la respuesta de la transacción a través de estas URLs, ya que podría darse el caso de que el usuario/pagador no llegase a redirigirse (abandona el proceso, cierra el navegador antes de ser redirigido, etc.).

En cualquier caso, la petición que se realiza a las URLs informadas es de tipo POST HTTP, con los siguientes parámetros descritos a continuación:

Parámetro Tipo Descripción
dataReturn String (JSON) Contiene los parámetros del pago:
    status String Código de éxito (200) o código de error
    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 del pago (personalizable por la plataforma)
    dateInitPayment Number Timestamp en ms zona horaria UTC
    accountDestiny String IBAN de la cuenta destino donde se ha transferido el dinero del pago
    customData String Sólo disponible si se ha indicado en la petición de incio de la orden de pago
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)

Siempre debemos 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 la respuesta del resultado del pago:
    • 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 de Backoffice

Consulta de Órdenes de Pago

Este servicio permite al cliente/integrador obtener información detallada de las órdenes de pagos que ha generado en un periodo de tiempo concreto, así como el estado de los mismos. Su integración es opcional.

Petición

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

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, correponde al campo reference especificado durante la generación de la orden de pago.
holderDestiny String Nombre del titular de la cuenta destino (beneficiario)
accountDestiny String Número de cuenta destino de la transferencia (formato IBAN)
customRecipient String Campo informativo personalizable que permite incorporar los datos del beneficiario del pago
customData String Campo personalizable que puede ser utilizado para persistir cualquier tipo de dato que se requiera
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
paymentType Number 0 = pago simple, 1 = pago periódico, 2 = cancelación de pago periódico.
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 permite activar o desactivar órdenes de pago previamente generadas. Su integración es opcional. En caso de haberse producido la caducidad de un enlace de pago, es posible reactivarlo. Asimismo, el cliente/integrador puede desactivar un enlace de pago antes de alcanzar su fecha de vencimiento.

Petición

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

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 de la API, informada y validada en el panel de control 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 2 decimales separados por .
$apiInespay->setReference('ID_2021_AP');     //Identificador interno del pago personalizable   

//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->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 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 2 decimales separados por .
$apiInespay->setReference('PE_2021_FO');     //Identificador interno del pago  
$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
$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
}
?>