Las Librerías de Integración están diseñadas para simplificar al máximo la integración con el TPV Virtual, eliminando la necesidad de implementaciones manuales más técnicas de los procesos de definición de parámetros, peticiones o firmado de las mismas.
En la librería también se elimina la necesidad del integrador de conocer las URL a las que tiene que enviar las operaciones según en que entorno esté operando, ya que se incorpora un nuevo elemento: el API Key. Este elemento incluye toda la información sobre el comercio, el terminal y el entorno de operación, así como también de la clave del propio terminal; todo en un único valor que aglutina la información del terminal y el entorno donde se está operando.
Con el uso de la librería y simplificando el proceso de uso del TPV Virtual, ya no necesitarás tener una visión completa de las partes más técnicas de la integración y sólo deberás comprender el flujo funcional de la integración. Recuerda que siempre tienes a tu disposición tanto la documentación de la integración como la documentación de todos los tipos de integración por si necesitaras profundizar en los métodos utilizados.
Versión 2.0.0 · Documentación
Versión 2.0.0 · Documentación
Uso y obtención del API Key
El API Key para el funcionamiento de la librería puede obtenerse directamente desde el Portal de Administración del TPV Virtual, en el mismo apartado donde tradicionalmente se han gestionado las claves de firma del comercio.
Este API Key es igual de sensible que la clave de firma de tu terminal (ya que, de facto, la incorpora) por lo que debes almacenar esta clave en tu servidor de la manera más segura posible para evitar un uso fraudulento de la misma. Eres la única persona responsable de la adecuada custodia y mantenimiento en secreto de dicha clave. Si en algún momento crees que tu clave ha podido estar comprometida, ponte en contacto con tu entidad bancaria inmediatamente.
Integración de la biblioteca
La biblioteca se distribuye en la carpeta lib y puede integrarse tanto en entornos Java como PHP.
Java
En proyectos Java, la integración se realiza incorporando los ficheros de la biblioteca al classpath de la aplicación, ya sea de forma manual desde el entorno de desarrollo o mediante la herramienta de construcción utilizada en el proyecto.
Una vez añadida la dependencia, las clases de la biblioteca podrán utilizarse importando los paquetes correspondientes. Es importante verificar que todas las dependencias necesarias estén disponibles y que la versión de Java empleada sea compatible con la biblioteca.
PHP
En PHP, la biblioteca puede utilizarse tanto con Composer como sin él.
Si el proyecto utiliza Composer, la integración recomendada consiste en registrar la biblioteca en el sistema de autoload y cargarla a través del autoloader del proyecto. Para ello, debe respetarse la estructura de namespaces definida por la propia biblioteca.
Si no se utiliza Composer, la biblioteca puede integrarse igualmente mediante carga manual de clases o mediante un mecanismo de autoload propio. En ese caso, es necesario conocer la ubicación de los ficheros, el nombre de las clases y el namespace asociado para resolver correctamente su uso dentro de la aplicación.
Consideraciones generales
La integración debe realizarse respetando la estructura interna de paquetes o namespaces proporcionada por la biblioteca. En PHP, el uso de Composer es una opción recomendada, pero no obligatoria, siempre que la resolución de clases se gestione correctamente. En Java, la biblioteca debe formar parte del classpath en tiempo de compilación y ejecución.
Utilización de la librería
La librería está compuesta por varias clases principales que el integrador deberá conocer para trabajar con ella de forma efectiva. Existe también un conjunto de clases auxiliares que no forman parte del uso habitual pero se incorporan para facilitar el uso en funcionalidades avanzadas.
Se recomienda utilizar la librería de manera íntegra, ya que los flujos que no estén gestionados por la librería no podrán contar con soporte al quedar fuera del funcionamiento previsto y validado.
Clase Merchant
En esta clase se inicializan todas las variables necesarias para identificar correctamente a qué comercio corresponde la operación. Almacena el FUC, el terminal, la clave de firma y el entorno al que apunta el terminal.
Se puede inicializar utilizando el API Key del terminal, obtenido en el Portal de Administración del TPV Virtual, aunque también podría utilizarse la asignación por cada uno de los parámetros tras iniciar la clase. Para estos ejemplos, usaremos TEST_OTk5MDA4ODgxXzAwMV9zcTdIanJVT0JmS21DNTc2SUxnc2tENXNyVTg3MGdKNw, que es el API Key para el terminal 001 del comercio de pruebas 999008881. De cualquier forma, te animamos a usar nuestra funcionalidad de creación de comercios de prueba sin necesidad de contrato con BBVA.
Te enseñamos cómo hacerlo en PHP:
$merchant = \Redsys\Merchant::initWithApiKey("TEST_OTk5MDA4ODgxXzAwMV9zcTdIanJVT0JmS21DNTc2SUxnc2tENXNyVTg3MGdKNw");
$merchant->fuc = "999008881"; $merchant->terminal = "1"; $merchant->kc = "sq7HjrUOBfKmC576ILgskD5srU870gJ7"; $merchant->env = "TEST";
Y en JAVA:
final Merchant merchant = Merchant.initWithApiKey("TEST_OTk5MDA4ODgxXzAwMV9zcTdIanJVT0JmS21DNTc2SUxnc2tENXNyVTg3MGdKNw");
final Merchant merchant = new Merchant();
merchant.setFuc("999008881");
merchant.setTerminal("1");
merhcant.setKc("sq7HjrUOBfKmC576ILgskD5srU870gJ7");
merchant.setEnv(Environment.TEST.getValue());
Clase Parameters
En esta clase se concentran la mayoría de los parámetros necesarios para la integración con el TPV Virtual. Los valores se asignan directamente sobre la instancia de la clase, utilizando propiedades equivalentes a los campos estándar del TPV Virtual. Los valores deben insertarse de acuerdo a nuestra guía de Parámetros y Respuestas del TPV Virtual.
En el caso de desconocer el nombre de algún parámetro, usar los nombres técnicos del parámetro en sí también es válido. Por ejemplo, si desconoces que para el importe el campo se llama ‘amount’, podrías usar el nombre técnico del campo ‘DS_MERCHANT_AMOUNT’, especificado en nuestra guía de Parámetros y Respuestas del TPV Virtual.
Tienes más información sobre la correspondencia de los nombres técnicos y los parámetros de la librería en la Guía de Integración de la Librería disponible en la parte superior de esta página.
$params = new \Redsys\Parameters(); $params->amount = "249"; $params->DS_MERCHANT_ORDER = "ABCD1234";
final Parameters params = new Parameters();
params.setAmount("249");
params.setParam("DS_MERCHANT_ORDER", "ABCD1234");
La posibilidad de utilizar tanto el nombre del campo de la clase como el nombre técnico del parámetro para poder operar tiene asociado un inconveniente: en el caso de parámetros que son un array de datos, como por ejemplo el campo DS_MERCHANT_EMV3DS, no se podrán alterar los atributos del array directamente desde el parámetro, sino que tendrá que extraerse el array a una variable auxiliar, realizar los cambios necesarios, y luego volverlo a asignar.
Clase PaymentMethod
Esta clase incorpora los métodos de pago admitidos por el TPV Virtual.
$params->paymethod = \Redsys\PaymentMethod::$bizum
params.setPayMethod(PaymentMethod.BIZUM);
En el caso de que se quiera utilizar un método de pago que no esté registrado en la biblioteca, se puede especificar el mismo método sin necesidad de usar la variable integrada, sino asignándolo como cualquier otro parámetro.
Clase Redirect
Es la clase principal utilizada para las operaciones de redirección. Sus funciones reciben la variable inicializada de la clase Merchant y la variable completada con los parámetros requeridos para operar de la clase Parameters.
Todas las funciones deben ser llamada de forma estática y realizan la redirección de forma automática. Cada una de las funciones corresponden a un tipo de operación distinto, aunque existe una función genérica para realizar cualquier tipo de transacción no soportado de manera nativa por la biblioteca.
\Redsys\Redirect::generic($merchant, $parameters, \Redsys\TransactionType::$authentication);
GenerateRedirectForm.generic(merchant, parameters, TransactionType.AUTHENTICATION);
También podrías asignar el tipo de transacción durante la recogida de parámetros y no especificar nada en la llamada a la función genérica.
Clase Rest
Es la clase principal utilizada para las operaciones a través de peticiones REST. Sus funciones, al igual que en la clase Redirect, reciben la variable inicializada de la clase Merchant y la variable completada con los parémtros requeridos para operar de la clase Parameters.
Del mismo modo que en la clase Redirect, estas funciones deben ser llamadas de manera estática, y si no se contemplase una operativa en concreto en la biblioteca, podrá utilizarse una función genérica para realizar la transacción.
$response = \Redsys\Rest::genericInit($merchant, $parameters, "3");
response = Rest.genericInit(merchant, params, "3");
Nótese que en este caso, en vez de utilizar un literal para el tipo de transacción, hemos incluido directamente el tipo de transacción que queremos utilizar, lo cual también es válido.
Clase Response
En este Wrapper, se incorporarán todos los parámetros que se devuelven en las respuestas del TPV Virtual cuando se realizan comunicaciones vía REST.
TABLA
Integración por redirección simple
En el siguiente bloque de código vas a ver la manera más simple de llegar al TPV Virtual para realizar un pago de 2,49€ utilizando la biblioteca. Recuerda que siempre puedes luego añadir todos los métodos necesarios para ajustarlo a la lógica de tu flujo de compra, así como todos los parámetros que creas oportunos que soporte el TPV Virtual.
require_once "lib/autoload.php"; $token = "TEST_OTk5MDA4ODgxXzAwMV9zcTdIanJVT0JmS21DNTc2SUxnc2tENXNyVTg3MGdKNw"; $merchant = \Redsys\Merchant::initWithApiKey($token); $params = new \Redsys\Parameters(); $params->amount = 249; $params->order = \Redsys\Utils::randomString(); \Redsys\Redirect::authorisation($merchant, $params);
package demo.examples.redirect;
import es.redsys.lib.*;
public class AuthorisationRedirectExample {
public static void main() {
final String token = "TEST_OTk5MDA4ODgxXzAwMV9zcTdIanJVT0JmS21DNTc2SUxnc2tENXNyVTg3MGdKNw";
final Merchant merchant = Merchant.initWithApiKey(token);
final Parameters params = new Parameters();
params.setAmount("249");
params.setOrder(Utils.randomString(12));
final string redirectForm = GenerateRedirectForm.authorisation(merchant, params);
//Rederizar redirectForm.
}
}
Como has podido comprobar, los únicos parámetros necesarios son la cantidad a pagar en céntimos y el número de pedido. Los valores identificativos del comercio vienen integrados dentro del API Key, la moneda en caso de no especificar ninguna será Euro y el tipo de transacción se infiere de la llamada a la función authorisation().
Al ejecutar el código, serás redirigido automáticamente a la página de pago de tu TPV Virtual.
Cuando formes la llamada al TPV Virtual, recuerda que puedes introducir los parámetros merchantUrl, urlOk y urlKo para poder gestionar el retorno de navegación del cliente y la notificación HTTP con el resultado de la operación, ya que si no procesas esta notificación, nunca sabrás el resultado de esta al haberse procesado en una página externa.
Un ejemplo de endpoint donde se reciba la notificación puede ser el siguiente:
require_once "lib/autoload.php";
$merchant = \Redsys\Merchant::initWithApiKey("TEST_OTk5MDA4ODgxXzAwMV9zcTdIanJVT0JmS21DNTc2SUxnc2tENXNyVTg3MGdKNw");
$params = \Redsys\Parameters::digest($merchant, $POST_data);
if(intval($params->codResponse) == 0) {
//Lógica cuando la operación es correcta.
} else {
//Lógica cuando la operación no es correcta.
}
package demo.examples.redirect;
import es.redsys.lib.*;
public class AuthorisationNotificationExample {
public static void handle(HttpExchange exchange) throws Exception {
final Merchant merchant = Merchant.initWithApiKey("TEST_OTk5MDA4ODgxXzAwMV9zcTdIanJVT0JmS21DNTc2SUxnc2tENXNyVTg3MGdKNw");
final Map<String, Object> receivedParams = Server.getFormParams(exchange);
final Parameters params = Parameters.digest(merchant, receivedParams);
if(Interger.parseInt(params.getCodResponse()) == 0) {
//Lógica cuando la operación es correcta.
} else {
//Lógica cuando la operación no es correcta.
}
}
}
Para poder procesar correcamente la notifiación, podemos utilizar la función Parameters::digest(), que recibe el Merchant inicializado junto con la notificación recibida, comprobando durante el proceso la integración de la misma. Esto quiere decir que no tienes que preocuparte por evaluar las firmas de la respuesta, ya que la biblioteca lo hará por ti.
Si la firma es incorrecta y falla la verificación, digest() lanzará una excepción. En caso contrario, cargará en el objeto al que se iguale la función toda la información de la notificación.
Otros tipos de integración
Con ánimos de no extender demasiado la información técnica contenida en este resumen de la librería, te animamos a consultar la documentación oficial de la librería de integración para obtener información de otros tipos de integraciones y funcionalidades, como el manejo de confirmaciones para preautorizaciones o autenticaciones o la funcionalidad REST.
Dispones además de un conjunto de ejemplos incluidos junto a las librerías de integración para que puedas consultarlos y te sirvan de guía a la hora de incorporar esta biblioteca a tu flujo de pagos.
Igual que te recomendamos en nuestros apartados técnicos cada vez que se opera vía REST, debes tener en cuenta que para este tipo de integración, podrías necesitar cumplir con la normativa PCI-DSS, así como realizar ajustes en la configuración de tu terminal de TPV Virtual para poder capturar la tarjeta del cliente.