NAV

API INESPAY PAYFLOW

La API INESPAY PAYFLOW proporciona un servicio de pasarela de pagos basado en la transferencia bancaria, utilizando las credenciales de la banca online de los Clientes Finales. Puede ser integrada tanto como checkout en tiendas online (tipo Commerce) como mediante generación de URLs (links) que se adjuntan a facturas o emails. En este último caso (generación de URLs), la API INESPAY PAYFLOW facilita URLs firmadas que dan acceso a la pasarela de pagos INESPAY para emitir un pago vía transferencia bancaria a un beneficiario.

La API INESPAY PAYFLOW 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 PAYFLOW requiere un proceso de autenticación mediante una API-KEY y una API-TOKEN, que pueden ser obtenidas desde el Dashboard INESPAY. Estas claves son de envío obligatorio en cada llamada y deben ser proporcionadas en la cabecera (Header) de cada petición.

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 distinguen dos entornos con las siguientes características:

Cada entorno tiene asociados una API-KEY y una API-TOKEN diferentes, además de una URL distinta. Una vez realizadas todas las pruebas de integración, el equipo INESPAY facilitará las claves de entorno REAL.

Servicios

Generación URLs (Tipo Commerce)

Este servicio permite generar órdenes de pago en tiempo real con una cuenta bancaria de destino fija, asociada al cliente de la API (generalmente una tienda online). El pago emitido presenta una validez máxima de 10 minutos desde que ha sido generado en la plataforma.

Orientada a las siguientes plataformas:

Petición

Entorno Tipo Url
TEST (Pruebas) POST https://apiflow.inespay.com/san/url/signer
REAL (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
amount Number Importe del pago mutiplicado por 100 sin decimales
reference String Identificador interno del pago (personalizable por la plataforma)
urlOk No String URL de retorno donde vuelve el Cliente Final cuando el pago se ha realizado con éxito.
urlError No String URL de retorno donde vuelve el Cliente Final cuando el pago se ha realizado con error.
urlNotif No String URL donde se notifica que el pago se ha realizado correctamente, transparente al Cliente Final que realiza el pago.
partnerId No String Identificador único del partner facilitado por INESPAY, sólo disponible para integradores específicos.

Respuesta

Parámetro Tipo Descripción
url String URL firmada de acceso a la pasarela de de pagos
status String Código de éxito (200) o error
description String Descripción del código status

Generación URLs (Tipo Business)

Este servicio permite generar URLs de pago en tiempo real con una cuenta bancaria destino personalizable para cada petición. Además, permite establecer el tiempo de validez de la URL hasta un máximo de 180 días.

Orientada a las siguientes plataformas:

Petición

Entorno Tipo Url
TEST (Pruebas) POST https://apiflow.inespay.com/san/url/signer
REAL (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 proporcionada por INESPAY
Content-Type application/json

Body

Parámetro Requerido Tipo Descripción
subject String Concepto que aparecerá en el detalle del pago
amount Number Importe del pago mutiplicado por 100, sin decimales
reference String Identificador interno del pago (personalizable por la plataforma)
urlOk No String URL de retorno donde vuelve el Cliente Final cuando el pago se ha realizado con éxito.
urlError No String URL de retorno donde vuelve el Cliente Final cuando el pago se ha realizado con error.
urlNotif No String URL donde se notifica que el pago se ha realizado correctamente, transparente al Cliente Final que realiza el pago.
customRecipient String Campo informativo personalizable que permite incorporar los datos del beneficiario del pago. Por ejemplo: nombre comercial; razón social; dirección … Se utiliza el caracter “;” para indicar saltos de línea.
holderDestiny String Nombre completo del titular de la cuenta destino (beneficiario)
accountDestiny String Número de cuenta del beneficiario de la transferencia (IBAN)
expireMinutes No Number Validez de la URL generada, por defecto 180 días
customData No String Campo personalizable que puede ser utilizado para persistir cualquier tipo de dato que se requiera. Si se utiliza el formato JSON serializado como tipo String, todos los campos son procesados y visibles desde el dashboard de INESPAY, en la sección de Enlaces de pago.
partnerId No String Identificador único del partner facilitado por INESPAY, 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

Parámetro Tipo Descripción
url String URL firmada de acceso a la pasarela de pagos INESPAY
status String Código de éxito (200) o error
description String Descripción del código status

Consulta URLs generadas

Este servicio permite obtener la información detallada de las URLs de pago previamente generadas mediante el servicio signer, su integración es opcional ya que toda la información sobre las URLs de pago generadas se puede encontrar directamente en el Dashboard INESPAY

Petición

Entorno Tipo Url
TEST (Pruebas) POST https://apiflow.inespay.com/san/info/debts
REAL (Producción) POST https://apiflow.inespay.com/pro/info/debts
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
dateTo No Number Fecha en formato milisegundos, sino se específica la búsqueda se realiza 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, sino se especifica el tamaño de página por defecto es de 50 elementos.
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 (Debts) devueltos en la página actual
currentPage Number Número de página actual
totalItems Number Número total de elementos (Debts), es la suma de todos los elementos de todas las páginas
totalPages Number Número total de páginas existentes
listDebts Array (Debt) Array de elementos (Debts)
status String Código de éxito (200) o error
description String Descripción del código status

Debt

Parámetro Tipo Descripción
debtLongId
 String Identificador único de la deuda
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
enabled
 Boolean Indica si la deuda se encuentra activa
partialsEnabled Boolean Indica si se permiten pagos parciales, sólo disponible para determinados tipos de clientes.

amount Number Importe de la deuda mutiplicado por 100 sin decimales

subject
 String Concepto
customRecipient
 String Campo informativo personalizable que permite incorporar los datos del beneficiario del pago.
customReference
 String Identificador interno del pago
holderDestiny
 String Nombre del titular de la cuenta destino (beneficiario)
accountDestiny
 String Número de cuenta destino de la transferencia (formato IBAN)
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
listUrlShort Array (UrlShort) Listado de urls cortas, que redirigen de forma automática la url larga (urlLong)
listTransactions Array (Transaction) Listado de transacciones asociadas a la deuda.

UrlShort

Parámetro Tipo Descripción

urlShortName
 String Identificador, necesario para construir url corta completa = https://secure.inespay.com/ENV/?s=URL_SHORT_NAME",
clicks
 Number Número de clicks realizados en la url corta
createAt Number Fecha de creación en formato milisegundos

updateAt

 Number Fecha de actualización en formato milisegundos

Transaction

Parámetro Tipo Descripción
transactionLongId String Identificador único de la transacción asociada a la deuda
typeTransaction Number Tipo de transacción: 1=Transferencia bancaria por Inespay, 2=TPV externo

amount Number Importe de la transacción
holderOrigin String Titular de la transacción sólo disponible para typeTransaction=1
accountOrigin String Cuenta origen de la transacción sólo disponible para typeTransaction=1
reference String Referencia de la transacción
subject String Concepto banca Online sólo disponible para typeTransaction=1
codStatus String Código del estado de la transacción. 200=Éxito, resto de códigos Error
descStatus String Descripción del código de la transacción
createAt Number Fecha de creación en formato milisegundos
updateAt Number Fecha de actualización en formato milisegundos

Activar/Desactivar URLs

Este servicio permite desactivar/activar URLs de pago previamente generadas mediante el servicio signer, su integración es opcional.

Petición

Entorno Tipo Url
TEST (Pruebas) POST https://apiflow.inespay.com/san/update/enable-disable-url
REAL (Producción) POST https://apiflow.inespay.com/pro/update/enable-disable-url
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
idInespay String Identificador de la url de INESPAY devuelto por el servicio signer
enable Boolean true = url activada, false = url desactivada

Respuesta

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

Resultado transacción

Todas las transacciones de pago, ya sean de éxito o de error, cuenta con dos posibilidades para informar a la plataforma que realiza la integración:

En ambos casos 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 del pago 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 enviado el dinero
signatureDataReturn String Firma de dataReturn calculada con el algoritmo HmacSHA256, utilizando como clave la APIKEY proporcionada por INESPAY y codificada en base64.

Forzar error en el proceso de pago

Es importante contemplar todos los escenarios posibles que se pueden dar durante el proceso de pago. Para facilitar la integración, existe la posibildad de forzar un error en el entorno de TEST. Para ello, en el momento de la validación de la transacción debemos insertar el valor “0000”, lo cual provocará que falle la validación e informará al usuario ofreciéndole la posibilidad de salir de la pasarela. Si el usuario selecciona “SALIR” de la pasarela Inespay notificará al integrador, con el código de error correspondiente, a través de las URLs informadas en urlNotif y urlError.

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 este forma aseguramos 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 sobre dataReturn que se encuentra codificado en Base64 utilizando como clave la API-KEY proporcionada por INESPAY. De forma que 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).

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 PAYFLOW, se proporciona una librería que facilita y simplifica la integración de la misma, de forma que solo es necesario copiar y pegar unas sencillas líneas de código.

PHP

Descargar SDK PHP API PAYFLOW v1.0.5

Generación de URLs (Tipo Commerce)

Generación de URLs (Tipo Commerce)
----------------------------------
<?php
require_once('payflow_sdk_php_vXXXX/InespayApiPublic.php');

$environmentApiInespay = InespayApiPublic::ENV_SAN; //Sandbox pagos ficticios
//$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);
$apiInespay->setTypeClient('1');

//Campos a rellenar dinámicamente
$apiInespay->setSubject('Prueba INESPAY');   //Concepto del pago
$apiInespay->setAmount(1.10);                //Importe 2 decimales separados por .
$apiInespay->setReference('ID_2017_AX');     //Identificador interno del pago           
$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

$response = $apiInespay->createUrlSigned(); //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
}
?>

Permite generar pagos en tiempo real con una cuenta bancaria de destino fija asociada al cliente de la API. El pago emitido tiene una validez de 10 minutos desde que es generado.

Generación URLs (Tipo Business)

Generación URLs (Tipo Business)
-------------------------------
<?php
require_once('payflow_sdk_php_vXXXX/InespayApiPublic.php');

$environmentApiInespay = InespayApiPublic::ENV_SAN; //Sandbox pagos ficticios
//$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);
$apiInespay->setTypeClient('2');

//Campos a rellenar dinámicamente
$apiInespay->setSubject('Prueba INESPAY');   //Concepto del pago
$apiInespay->setAmount(1.10);                //Importe 2 decimales separados por .
$apiInespay->setReference('ID_2017_AX');     //Identificador interno del pago           
$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->setCustomRecipient('Nombre comercial');
$apiInespay->setHolderDestiny('TITULAR CUENTA');
$apiInespay->setAccountDestiny('ES9121000418450200051332');
$apiInespay->setExpireMinutes('60');    //Caducidad 1 hora

$response = $apiInespay->createUrlSigned(); //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
}
?>

Permite generar URLs de pago en tiempo real con una cuenta bancaria destino personalizable para cada petición. Además, permite establecer el tiempo de validez de la URL hasta un máximo de 180 días.

URL retorno segura y autentificada mediante firma

Verificación de la firma de los datos enviados por HTTP POST para asegurar que la respuesta procede de INESPAY. Esta verificación se debe realizar siempre por el Cliente Final en su lado de servidor.

URL retorno segura y autentificada
--------------------------------
<?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>";

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

JAVA

Próximamente publicaremos una SDK para el lenguaje Java que permite la integración de la pasarela de pagos INESPAY.