NAV

API INESPAY

La API INESPAY proporciona al cliente/integrador el servicio de iniciación de pagos licenciado y 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 acceder al Dashboard INESPAY, el cliente/integrador debe registrarse previamente en el servicio 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 soporte@inespay.com.

Al tratarse de 2 entornos idénticos (SANDBOX y PRODUCCIÓN), para realizar peticiones a uno u otro entorno, simplemente se deben utilizar las claves API-KEY y API-TOKEN correspondientes 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 para autorizar el pago. Utilice cualquier combinación de caracteres numéricos o alfanuméricos. El resultado OK será mostrado en una página del navegador con el texto Operación de pago realizada correctamente.

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 al entorno de Inespay.

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 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 incorporados 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 e-mail, SMS, factura digital o física.)

Independientemente de la modalidad de pago (simple o periódico) e independientemente del uso que se le dé a las URL de pago (botón de pago o enlace de pago), una vez el proceso de pago se haya concluido de forma satisfactoria, se redirigirá automáticamente al usuario/pagador a la urlOK informada en la llamada API. En caso de que el usuario/pagador decida voluntariamente salir del proceso, será redirigido a la urlError informada en los parámetros API.

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.

Previamente a redirigir al usuario/pagador a su interfaz bancaria, la URL de pago le redirigirá al entorno de INESPAY, donde se le mostrarán los detalles de la entidad de pago prestataria del servicio (INESPAY) y las Condiciones Generales del servicio.

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 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
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 se visualiza en el resumen mostrado dentro de la pasarela. 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
holderDestiny No String Nombre completo del titular de la cuenta destino (beneficiario). Sólo disponible para integradores específicos.
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. Sólo disponible para integradores específicos.

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

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

Respuesta a la petición de inicio de pago simple

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

Pagos Periódicos

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

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 periódica de pago. 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. Ello requiere realizar una primera petición a la API INESPAY para obtener el listado de bancos. 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 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 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: Utilizar los Grupos de bancos permite reducir considerablemente el listado de bancos 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 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 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)
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 a la petición de pago periódico

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

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 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 a la petición de cancelación de un pago periódico

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 un Pago Periódico: 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 de pagos (Callback)

La notificación de un pago OK se realiza mediante una petición de tipo POST HTTP a la urlNotif en formato JSON. Este parámetro debe incorporarse por el cliente/integrador en cada llamada API de inicio de pago. Es altamente recomendable dedicar exclusivamente la urlNotif para recibir el resultado OK de la transacción.

NOTA 1

El parámetro opcional urlOK no debe ser utilizado como Callback. INESPAY utiliza el parámetro urlOk únicamente para redirigir al usuario/pagador hacia la página web de éxito del cliente. Para permitir al cliente/integrador configurar una página de éxito dinámica, INESPAY realiza igualmente una petición tipo POST HTTP a la urlOk incorporando los mismos parámetros que se envían a la urlNotif.

NOTA 2 En caso de que el usuario/pagador cancele el pago INESPAY lo redirigirá al parámetro urlError informado por el cliente/integrador en la petición de inicio de pago. Para permitir al cliente/integrador configurar una página de error dinámica, INESPAY realiza una petición tipo POST HTTP a la urlError incorporando los mismos parámetros que se envían a la urlNotif.

La petición de notificación del pago incorpora 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 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, ideado 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, 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 se visualizará en el resumen mostrado dentro de la pasarela
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
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, ideada 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 2 decimales separados por un punto
$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 (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 2 decimales separados por un punto
$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 (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
}
?>