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

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

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.

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

Resultado pago

Todo resultado de pago, ya sea 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
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

Checkout (Tipo Commerce)

Checkout (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 Java que permite la integración de la pasarela de pagos INESPAY.