RESUMEN: Una librería en PHP para poder incluir en tu web botones de pago REDSYS (redsys-payment-buttons). Descárgate la librería y aprende a integrarla en tu web.

Hay ocasiones en las que necesitamos poder realizar cobros en nuestra web, pero no necesitamos toda la complejidad asociada a montar una tienda on-line y un proceso de checkout completo.

Por ejemplo puede que vendas un libro, o un curso, … o que te vistas de payaso para las fiestas de cumpleaños. Necesitas una forma sencilla de poder realizar cobros, pero no necesitas montar una tienda on-line.

Para estos casos mas sencillos, te ofrezco aquí una solución –también sencilla– que te permitirá procesar pagos a través de REDSYS, la pasarela de pagos con tarjeta mejor asentada en nuestro país, sin necesidad de que montes un WooCommerce, un Prestashop o cualquier otro módulo complejo para procesar cobros.

¿Por qué REDSYS?

REDSYS es la entidad de procesamiento de pagos electrónicos líder en España. Su pasarela de pagos es prácticamente omnipresente en cualquier tienda on-line de nuestro país y en la actualidad es la responsable del procesamiento de mas de 25 millones de operaciones de pago por mes.

REDSYS permite el pago con las tarjetas de crédito o débito de tipo VISA y MasterCard que son con mucho las mas habituales en nuestro país (entre ambas suponen mas del 90% de la cuota de mercado).

Para contratar un TPV (Terminal de Punto de Venta) de REDSYS debes dirigirte a tu entidad bancaria de confianza. Prácticamente la totalidad de las que operan en España te pueden ofrecer un TPV de REDSYS (ver la lista completa).

Para operar con los botones que presento aquí debes contratar el servicio de TPV Virtual de REDSYS. Si ya dispones de un TPV físico en tu tienda bastará con que amplies el servicio para disponer de un TPV virtual. Tu banco te cobrará habitualmente una cuota anual o mensual de mantenimiento del TPV virtual, mas una comisión por cada operación procesada (tasa de descuento).

Creando nuestros primeros botones

La librería redsys-payment-buttons está escrita en PHP, por lo que se puede integrar perfectamente en cualquier web, con independencia del tipo de CMS que use (WordPress, Drupal Joomla, …). Se puede integrar incluso en aquellas webs que no usan ningún tipo de CMS.

Asumiendo que has instalado el código en la carpeta redsys-payment-buttons, la forma de crear un botón de pago es muy sencilla:

require_once( 'redsys-payment-buttons/include/functions.php' );

$orderAmmount = 14.00;
$orderNumber = '000051894416';
$orderDescription = 'Pedido 5189';
echo redsys_button($orderAmmount, 
                   $orderNumber, 
                   $orderDescription, 
                   "datos-adicionales-de-mi-pedido");

Esto genera un botón sencillo, con el texto «Realizar pago», que al pulsarlo hará aparecer el formulario de pago con tarjeta a través de REDSYS:

Los parámetros básicos para la llamada a redsys_button() son:

• La cantidad que debe ser abonada. Nótese que se usa un ‘.’ como separador de los decimales.
• El número de pedido. este número debe ser único. El mismo TPV virtual no podrá procesar dos pagos con sendos números de pedido idénticos.
  Si no tienes otro mecanismo para generar un número de pedido único, la librería te ofrece una función para generarlos:
  
  $orderNumber = redsys_ramdom_order();
• La descripción del pedido, que generalmente hará referencia al producto o servicio que estamos pagando. Este texto aparecerá en el formulario de pago.
• Los datos adicionales del pedido. Este parámetro es opcional y no se le mostrará al cliente en el formulario de pago. Sin embargo estará disponible a la vuelta de la operación de pago, por lo que podemos usarlo –por ejemplo– para incluir la dirección de correo del cliente y enviar un email de notificación cuando el pago haya sido procesado (con éxito o no).

Procesando la respuesta de la pasarela

Cuando se pulsa el botón el flujo pasará de nuestra página web a la página web del TPV Virtual de REDSYS. Una vez procesado el pago nuestra aplicación web debe enterarse de si la operación ha tenido éxito o no y continuar con su flujo visual.

Hay que diferenciar entre procesar la respuesta de la pasarela de pago (qué hacemos si el pago es correcto) y procesar la vuelta de la pasarela de pago (qué contenido le presentamos al usuario si el pago ha sido correcto, y qué otro contenido cuando haya errores).

Para el primer cometido tienes que editar el módulo return.php y completar los dos TODO’s que se documentan:

<?php

/**
 * Procesa la respuesta de un pago de REDSYS.
 * 
 * No debe generar salida HTML pues este resultado no es mostrado a nadie.
 */

require_once( 'include/functions.php' );

$response = redsys_process_response();

if ( $response['correctPayment'] ) {
	// TODO: Operaciones de la aplicación tras un pago correcto.
} else {
	// TODO: Operaciones de la aplicación tras un pago incorrecto.
}

En el caso mas simple, te puedes enviar un correo electrónico con los detalles de la operación. En un caso un poco mas robusto puedes grabar en una base de datos un registro con los detalles. En ambos casos te será de mucha utilidad poder rescatar los datos adicionales del pedido que típicamente identificarán al cliente que está realizando el pago.

Cuando crees este código debes tener en cuenta que el array asociativo  $response tiene los siguientes campos:

• genuine: true/false Indica si la llamada a tu módulo para procesar una confirmación de pago se considera genuina de REDSYS.
• correctPayment: true/false Indica si la operación de pago ha sido correcta (aprobada).
• code: string Código de respuesta de la autorización. Detalla el motivo por el que se aprueba o deniega la operación.
• date: string Fecha de la operación.
• hour: string Hora de la operación.
• amount: string Importe solicitado.
• currency: string Código de moneda.
• order: string Código del pedido (único).
• merchantCode: string Código FUC del comercio.
• terminal: string Número de terminal TPV.
• transactionType: string Tipo de transacción.
• autorisation: string Número de autorización de la operación.
• secure: string Indica si la operación ha usado 3D secure.
• data: string Datos adicionales enviados por el comercio.
• consumerLang: string Idioma del cliente.
• cardCountry: string Pais de emisión de la tarjeta.
• cardNumber: string Número de tarjeta (ofuscado).
• cardType: string Tipo de tarjeta (Débito o Crédito).
• cardBrand: string Marca de la tarjeta.

Algunos datos pueden aparecer como Unknown o Not set, en función de la operación y la configuración del comercio en REDSYS.

Consultar la documentación de REDSYS y del banco o la entidad de pagos para detalles sobre los códigos de respuesta, divisas, paises, …

A la vuelta de la pasarela de pago

A la vuelta de una operación de pago, la aplicación volverá a recibir el control en una de las dos URLs configuradas en el botón de pago:

• $urlOK: Si el pago ha sido considerado correcto.
• $urlKO: Si el pago ha sido considerado erróneo.

El propósito de estas URLS es simplemente continuar la navegación del usuario y es posible que ambas se dirijan hacia el mismo destino. Dependiendo de cómo esté configurada la pasarela estas URLS podrían recibir por parámetros el resultado de la operación, pero se desaconseja trabajar de esta manera, y en su lugar procesar la respuesta en la URL configurada en REDSYS_URL_MERCHANT (donde no se permite mostrar salida HTML).

Si estos parámetros no se indican en la creación del botón, se usaran los valores por defecto configurados en config.php para REDSYS_URL_OK y REDSYS_URL_KO respectivamente.

Para un caso sencillo crea dos páginas en tu web, una que confirme que el pago se ha realizado de forma correcta y otra que informe de que ha habido un error, y no olvides indicar las URLs de estas paginas en tu fichero config.php

Configurando la pasarela

Para que los botones funcionen, debes modificar el fichero config.php de acuerdo a la configuración de tu web y de tu pasarela.

Los seis primeros parámetros son datos que te dará tu entidad bancaria cuando contrates el TPV virtual. El banco te dará dos juegos de configuraciones, una para acceder al entorno de prueba y otra para el entorno real. Ni que decir tiene que debes usar la configuración del entorno de prueba hasta que hayas comprobado que las operaciones de pago se procesan de forma correcta y recibes y procesas las respuestas de la pasarela.

// URL de REDSYS con el formulario de procesamiento de pagos (TEST / REAL)
define( 'REDSYS_URL_TPV', 'https://sis-t.redsys.es:25443/sis/realizarPago' );

// Nombre del comercio
define( 'REDSYS_NAME', 'Nombre de tu comercio' );

// Número de comercio (FUC)
define( 'REDSYS_FUC_CODE', '123456789' );

// Clave secreta de encriptación (SHA-256)
define( 'REDSYS_KEYCODE', 'abcdefghijklmnopqrstuvwxyz012345' );

// Número de terminal
define( 'REDSYS_TERMINAL', '001');

// Código de divisa
define( 'REDSYS_CURRENCY', '978');

De los cuatro últimos, tres son URLs que tienen que ver con la estructura de tu web. Es muy importante que REDSYS_URL_MERCHANT apunte a donde hayas dejado instalado el fichero return.php que es el que procesa las respuestas de las operaciones de pago.

// URL para la recepción de confirmaciones de pago
define( 'REDSYS_URL_MERCHANT', 'https://misite.com/whereever-installed/redsys-payment-buttons/return.php');

// URL de vuelta en operaciones de pago con éxito (por defecto)
define( 'REDSYS_URL_OK', 'https://misite.com/whereever-installed/redsys-payment-buttons/payment-ok.php');

// URL de vuelta en operaciones de pago con errores (por defecto)
define( 'REDSYS_URL_KO', 'https://misite.com/whereever-installed/redsys-payment-buttons/payment-ko.php');

// Indica si se debe escribir información en el log sobre las operaciones de confirmación procesadas
define( 'REDSYS_LOG', true );

Personaliza tus botones

Si revisas la documentación de la función verás que además de los parámetros básicos que ya hemos comentado admite algunos adicionales.

De dos de ellos($urlOK y $urlKO), ya hemos hablado. Pero además puedes personalizar tus botones de pago usando el resto:

• $btnText: Este será el texto que se pinte en el botón de pago. Por defecto es Realizar pago.
• $btnClass: Te permite indicar una o varias clases CSS que pinten el botón con un aspecto determinado. Por defecto se asume que tienes Bootstrap y el botón se pinta como class="btn btn-primary".
• $formName: En caso de que tengas varios botones de pago en la misma página, será conveniente que cada uno reciba un nombre único a través de este parámetro. Además será el ID del formulario donde se pinta el botón, por lo que puedes usar en tu CSS para personalizar aún mas el aspecto visual de cada uno de los botones.

Veamos a continuación un ejemplo mas elaborado en el que se muestran dos botones de pago en la misma página, para realizar una donación de 5 o 10€:

<?php

require_once( 'redsys-payment-buttons/include/functions.php' );

$orderNumber = redsys_ramdom_order();
$orderDescription = 'Donación a VideosDeGatitos.com';
$orderData = htmlentities($_POST["name"], ENT_QUOTES, 'UTF-8') . '#' .
             htmlentities($_POST["email"], ENT_QUOTES, 'UTF-8'); ?>

<style>
  .my-payment-button {
     background-color: #00FFFF;
     ...
  }
</style>
...
<div class="container" align="center">
  <div class="row">
    <div class="col-sm-6">
      <?php echo redsys_button(5.0,
                               $orderNumber, 
                               $orderDescription, 
                               $orderData,
                               REDSYS_URL_OK,
                               REDSYS_URL_KO,
                               "Donar 5€",
                               "btn my-payment-button"
                               "button5"); ?>
    </div>
    <div class="col-sm-6">
      <?php echo redsys_button(10.0,
                               $orderNumber, 
                               $orderDescription, 
                               $orderData,
                               REDSYS_URL_OK,
                               REDSYS_URL_KO,
                               "Donar 10€",
                               "btn my-payment-button"
                               "button10"); ?>
    </div>
  </div>
</div>

La librería redsys-payment-buttons se entrega con licencia MIT así que eres libre de usarla en tu código sin ninguna restricción. Puedes descargarte el código de GitHub con el siguiente enlace: