NAV

API PAYFLOW

La API INESPAY PAYFLOW proporciona un servicio para la generación de URLs firmadas que dan acceso a la plataforma segura de pagos INESPAY, gracias a la cual es posible recibir cobros mediante transferencia bancaria, utilizando las credenciales de la banca Online de los Clientes Finales.

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

Estructura Payflow

Seguridad

Todas las APIS requieren un proceso de autenticación mediante una API-KEY y una API-TOKEN que pueden ser obtenidas desde el Dashboard INESPAY

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

La API INESPAY utiliza dos niveles de seguridad basados en la API KEY y la API TOKEN. Estas credenciales son de envío obligatorio y deben ser proporcionadas en la cabecera (Header) de cada petición.

NOTA: Nunca se deben exponer las credenciales 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.

Servicios

Generación URL (Tipo 1)

Permite generar URLs de pago en tiempo real con una cuenta bancaria de destino fija asociada al cliente de la API. Presenta una validez de 10 minutos desde que la URL es generada.

Orientada a las siguientes plataformas:

Petición

Entorno Tipo Url
Pruebas (sandbox) 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 Si String Concepto que aparecerá en el detalle del pago
amount Si Number Importe del pago mutiplicado por 100 sin decimales
reference Si String Identificador interno del pago personalizable
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 plataforma de de pagos
status String Código de éxito (200) o error
description String Descripción del código status

Generación URL (Tipo 2)

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
Pruebas (sandbox) 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 proporcionada por INESPAY
Content-Type application/json

Body

Parámetro Requerido Tipo Descripción
subject Si String Concepto que aparecerá en el detalle del pago
amount Si Number Importe del pago mutiplicado por 100 sin decimales
reference Si String Identificador interno del pago personalizable
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 Si String Campo informativo personalizable que permite establecer 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 Si String Nombre completo del titular de la cuenta destino
accountDestiny Si String Número de cuenta destino 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 urls emitidas.

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 plataforma de de pagos
status String Código de éxito (200) o error
description String Descripción del código status

Verificación firma

Cuando se produce un pago con éxito/error en la plataforma INESPAY existen dos posibilidades para informar del resultado del pago a la plataforma que realiza la integración. Para ello se utilizan los parámetros informados en la generación de URL de pago:

En ambos casos se realiza un POST HTTP con la información del resultado de la transacción en el formato que se describe 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 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
    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.

Siempre debemos calcular la firma de los datos devueltos en dataReturn y compararla con la firma devuelta por INESPAY signatureDataReturn de este forma aseguramos que la respuesta procede de INESPAY. A continuación detallamos como realizar el cálculo de la firma:

  1. Convertimos el valor de dataReturn a una cadena de texto Hexadecimal sin guiones y en minúsculas.
  2. Codificamos el resultado del punto anterior en Base64.
  3. Aplicamos el algoritmo HmacSHA256 utilizando como clave la API-KEY proporcionada por INESPAY y obtenemos la firma calculada.
  4. Comparamos la firma calculada con el valor de signatureDataReturn, si son iguales verficamos y aseguramos que la respuesta procede de INESPAY (OK), en caso contrario la respuesta no es válida y no procede de INESPAY (KO).

Códigos de respuesta

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

Código Descripción
200 Éxito petición
E300 Internal API error
E301 Parámetros incorrectos

Librerias API (SDK)

Con el objetivo de facilitar la integración de la API PAYFLOW 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 para hacer uso del servicio proporcionado por INESPAY.

PHP

Descargar SDK PHP API PAYFLOW v1.0.5

Generación URL (Tipo 1)

Generación URL (Tipo 1)
-----------------------
<?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 URLs de pago en tiempo real con una cuenta bancaria de destino fija asociada al cliente de la API. La URL generada tiene una validez de 10 minutos desde que es generada.

Generación URL (Tipo 2)

Generación URL (Tipo 2)
-----------------------
<?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, 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 del Payflow.