Tipos de Integración

Conexión vía REST

Toma el control de tu integración con tu TPV Virtual de BBVA e integra nuestra pasarela con total libertad, adaptando cada campo y procedimiento a tus necesidades.

Funcionamiento

La integración vía REST te proporciona la máxima libertad para realizar pagos usando los servicios de BBVA, y es que en este tipo de conexión, tú te ocupas de todo y tú eliges donde se muestra cada uno de los campos, como se recogen los datos, y cuándo se tratan para enviarse a nuestros servidores. Este tipo de conexión es muy útil si tu flujo de compra contiene alguna peculiaridad o necesitas ajustarlo en un punto en específico.

 

La integración vía REST te proporciona la máxima libertad para realizar pagos usando los servicios de BBVA, y es que en este tipo de conexión, tú te ocupas de todo y tú eliges donde se muestra cada uno de los campos, como se recogen los datos, y cuándo se tratan para enviarse a nuestros servidores. Este tipo de conexión es muy útil si tu flujo de compra contiene alguna peculiaridad o necesitas ajustarlo en un punto en específico.

Este tipo de integración es la más compleja de integrar, debido a que deberás encargarte de crear todo el flujo de recogida de datos de la tarjeta, preparado y envío de esos datos a tu TPV Virtual, y recepción de los mensajes de estado y resultado, así como de la autenticación. Además, en este tipo de integración, debes tener muy en cuenta que deberás cumplir con la normativa PCI-DSS.

Características de la integración

  • Al tratarse de una integración personalizada, requerirás más conocimientos de progrmación, pero tendrás control total de todos los pasos de la operación.
  • Capacidad de personalizar al completo todos los campos de recogida de datos y de integrar la pasarela de la manera que más te guste.

Este tipo de integración es especialmente últil para aquellas situaciones en las que el cliente no se encuentra presente para realizar la autenticación, pudiendo realizar operativas como pago MIT, devoluciones, anulaciones, confirmaciones o envío de enlaces de PayGold.

Pasos para realizar la integración

A continuación, se explicarán los pasos a seguir para poder realizar la integración de manera correcta. Se debe recordar que los ejemplos propuestos en esta guía son fragmentos de código explicativos y que bajo no se debe tomar como la forma completa de realizar la integración ya que es muy probable que los fragmentos de código presentados requieran de adaptación a su sitio web.

1

Formulario de envío de datos en la petición

Como primer paso, deberás hacer llegar al TPV Virtual una petición con todos los datos identificativos de la operación en formato JSON, con los siguientes parámetros:

  • Ds_MerchantParameters: Datos de la petición de pago.
  • Ds_SignatureVersion: Versión del algoritmo de firma.
  • Ds_Signature: Firma de los datos de la petición de pago.

Cada uno de estos ítems se explicará más adelante. Según el entorno en el que desees operar, deberás enviar este objeto al endpoint que corresponda según se estén realizando pruebas u operando en REAL.

Entorno
Pruebas
Real
URL de Conexión
https://sis-t.redsys.es:25443/sis/rest/trataPeticionREST
https://sis.redsys.es/sis/rest/trataPeticionREST

Ds_MerchantParameters

Se debe montar una cadena en formato JSON con todos los datos de la petición. El nombre de cada parámetro debe indicarse en mayúsculas (DS_MERCHANT_AMOUNT) o con estructura CamelCase (Ds_Merchant_Amount). La lista de parámetros que se pueden incluir en la petición puede consultarse en la tabla de parámetros enviados por el comercio.

Para todas las peticiones se deben enviar, como mínimo, los parámetros obligatorios para poder realizar una operación estándar. Si se desea utilizar una operativa especial, como por ejemplo un pago por referencia o pago 1-clic, se deberán incluir en la petición los parámetros relacionados con esta operativa.

A continuación, se muestran un ejemplo de como quedaría la cadena en formato JSON para una operativa estándar.

{
    "DS_MERCHANT_AMOUNT": "145",
    "DS_MERCHANT_CURRENCY": "978",
    "DS_MERCHANT_MERCHANTCODE": "999008881",
    "DS_MERCHANT_MERCHANTURL": "http://www.prueba.com/urlNotificacion.php",
    "DS_MERCHANT_ORDER": "1446068581",
    "DS_MERCHANT_TERMINAL": "1",
    "DS_MERCHANT_TRANSACTIONTYPE": "0",
    "DS_MERCHANT_URLKO": "http://www.prueba.com/urlKO.php",
    "DS_MERCHANT_URLOK": "http://www.prueba.com/urlOK.php"
}

Téngase en cuenta dos anotaciones: la primera, es que todos los parámetros son de tipo string, aunque sólo se esté enviando un número. Además, nótese que el total de la transacción, el monto, se expresa en céntimos, es decir, no se deben envíar decimales, sino que se debe de enviar el total ajustado para eliminar los decimales.

Una vez el objeto JSON está correctamente formado, se debe codificar en BASE64, y se debe comprobar que no queden espacios en blanco. La cadena resultante será el valor del parámetro Ds_MerchantParameters.

Ejemplo del objeto anterior codificado en BASE64
ew0KICAgICJEU19NRVJDSEFOVF9BTU9VTlQiOiAiMTQ1IiwNCiAgICAiRFNfTUVSQ0hBTlRfQ1VSUkVOQ1kiOiAiOTc4IiwNCiAgICAiRFNfTUVSQ0hBTlRfTUVSQ0hBTlRDT0RFIjogIjk5OTAwODg4MSIsDQogICAgIkRTX01FUkNIQU5UX01FUkNIQU5UVVJMIjogImh0dHA6Ly93d3cucHJ1ZWJhLmNvbS91cmxOb3RpZmljYWNpb24ucGhwIiwNCiAgICAiRFNfTUVSQ0hBTlRfT1JERVIiOiAiMTQ0NjA2ODU4MSIsDQogICAgIkRTX01FUkNIQU5UX1RFUk1JTkFMIjogIjEiLA0KICAgICJEU19NRVJDSEFOVF9UUkFOU0FDVElPTlRZUEUiOiAiMCIsDQogICAgIkRTX01FUkNIQU5UX1VSTEtPIjogImh0dHA6Ly93d3cucHJ1ZWJhLmNvbS91cmxLTy5waHAiLA0KICAgICJEU19NRVJDSEFOVF9VUkxPSyI6ICJodHRwOi8vd3d3LnBydWViYS5jb20vdXJsT0sucGhwIg0KfQ==

Ds_SignatureVersion

En la petición, se debe identificar la versión concreta del algoritmo que se está utilizando para la firma. Actualmente se utiliza el vamor HMAC_SHA256_V1 para identificar la versión de todas las peticiones, por lo que este será el valor de este parámetro.

Ds_Signature

Este parámetro es la firma de la operación, y esta se calculará utilizando el parámetro Ds_MerchantParameters ya codificado en BASE64, y la clave SHA-256 específica del terminal, la cual fue proporcionada por BBVA. El proceso a seguir puede ser fácilmente implementado usando las librerías de ayuda que se proporcionan en el área de descargas. A continuación, se detallan los pasos a seguir para la obtención de esta firma:

  1. Se codifica la clave SHA-256 en BASE64.
  2. Se diversifica la clave de firma realizando un cifrado 3DES entre esta clave codificada obtenida en el paso 1, y el valor del número de pedido de la operación Ds_Merchant_Order.
  3. Se realiza un cáclulo para obtener el HMAC-256 con el parámetro «Ds_MerchantParameters y la clave de firma diversificada obtenida en el paso 2.
  4. El resultado del paso 3, se debe codificar en BASE64. El resultado de esta operación es el valor de la firma.

Si al petición se realiza mediante cURL o usando el navegador Safari, puede que los símbolos «+» se transformen en espacios en blanco. Para que esto no ocurra, se deben sustituir los símbolos «+» por el equivalente «%2B» antes de enviarlo.

Proceso de creación de firma en PHP
function createMerchantSignature($key) {
	// Se decodifica la clave Base64
        $key = $this->decodeBase64($key);

	// Se genera el parámetro Ds_MerchantParameters
	$ent = $this->createMerchantParameters();

        // Se diversifica la clave con el Número de Pedido
        $key = $this->encrypt_3DES($this->getOrder(), $key);

        // MAC256 del parámetro Ds_MerchantParameters
        $res = $this->mac256($ent, $key);

        // Se codifican los datos Base64
        return $this->encodeBase64($res);
}
Proceso de creación de firma en JAVA
public String createMerchantSignature(final String claveComercio) throws UnsupportedEncodingException, InvalidKeyException, NoSuchAlgorithmException, IllegalStateException, NoSuchPaddingException, InvalidAlgorithmParameterException, IllegalBlockSizeException, BadPaddingException {

        String merchantParams = createMerchantParameters();

        byte [] clave = decodeB64(claveComercio.getBytes("UTF-8"));

        String secretKc = toHexadecimal(clave, clave.length);

        byte [] secretKo = encrypt_3DES(secretKc, getOrder());

        // Se hace el MAC con la clave de la operación "Ko" y se codifica en BASE64
        byte [] hash = mac256(merchantParams, secretKo);

        String res = encodeB64String(hash);
        return res;
    }

Estas funciones son extractos de las bibliotecas de ayuda que puedes encontrar en el área de descargas de Bibliotecas y SDKs.

A continuación, se muestra un ejemplo del formulario completo de petición de pago.

Formulario con los datos de la petición
<form name="from" action="https://sis-t.redsys.es:25443/sis/realizarPago" method="POST">
	<input type="hidden" name="Ds_SignatureVersion" value="HMAC_SHA256_V1"/>
	<input type="hidden" name="Ds_MerchantParameters" value="eyJEU19NRVJDSEFOVF9BTU9VTlQiOiAiMTQ1IiwiRFNfTUVSQ0hBTlRfQ1VSUkVOQ1kiOiAiOTc4IiwiRFNfTUVSQ0hBTlRfTUVSQ0hBTlRDT0RFIjogIjk5OTAwODg4MSIsIkRTX01FUkNIQU5UX01FUkNIQU5UVVJMIjogImh0dHA6Ly93d3cucHJ1ZWJhLmNvbS91cmxOb3RpZmljYWNpb24ucGhwIiwiRFNfTUVSQ0hBTlRfT1JERVIiOiAiMTQ0NjA2ODU4MSIsIkRTX01FUkNIQU5UX1RFUk1JTkFMIjogIjEiLCJEU19NRVJDSEFOVF9UUkFOU0FDVElPTlRZUEUiOiAiMCIsIkRTX01FUkNIQU5UX1VSTEtPIjogImh0dHA6Ly93d3cucHJ1ZWJhLmNvbS91cmxLTy5waHAiLCJEU19NRVJDSEFOVF9VUkxPSyI6ICJodHRwOi8vd3d3LnBydWViYS5jb20vdXJsT0sucGhwIn0="/>
	<input type="hidden" name="Ds_Signature" value="PqV2+SF6asdasMjXasKJRTh3UIYya1hmU/igHkzhC+R="/>	
</form>

2

Autenticación EMV3DS

El proceso de autenticación EMV3DS es un proceso que pese a que inicialmente puede resultar complejo,  pero que te proporciona todas las garantías de seguridad de las que dispone tu TPV Virtual. 

El proceso de autenticación verifica que es el titular el que está usando su tarjeta para poder realizar la operación, empleando autenticación reforzada (SCA), que es el proceso por el que, por ejemplo, debe autenticar su operación en la aplicación del banco, o introducir un código que se envíe por SMS. Puedes ver detalladamente cómo implementar el proceso de autenticación, o aprender más sobre qué es y cómo te ayuda EMV3DS a mantener tus operaciones seguras.

3

Mensajes de respuesta

Tras el envío de la petición al TPV Virtual, recibirás una respuesta que debes capturar. Según cómo haya ido la operación, la respuesta puede ser que se ha producido un error, o que todo ha ido correctamente.

Operación rechazada

Si la operación ha sufrido algún tipo de error durante el procesamiento, se recibirá un objeto JSON que contendrá un único parámetro llamado errorCode que indicará el código de error que identifica el fallo que se ha producido. Puedes ver lo que significa cada tipo de error en la tabla de errores generales.

{
    "errorCode":"SISXXXX"
}

Operación procesada correctamente

En este caso, en la que la operación se haya procesado sin errores, recibirás un objeto con el resumen de la operación y su resultado, todo dentro del parámetro Ds_MerchantParameters, así como la versión de firma y la firma de los parámetros

{
	"Ds_SignatureVersion":"HMAC_SHA256_V1",
	"Ds_MerchantParameters":"eyJEc19BbW91bnQiOiIxNDUiLCJEc19DdXJyZW5jeSI6Ijk3OCIsIkRzX09yZGVyIjoiMTQ0NjA2ODU4MSIsIkRzX01lcmNoYW50Q29kZSI6Ijk5OTAwODg4MSIsIkRzX1Rlcm1pbmFsIjoiMSIsIkRzX1Jlc3BvbnNlIjoiMDAwMCIsIkRzX0F1dGhvcmlzYXRpb25Db2RlIjoiNTAxNjAyIiwiRHNfVHJhbnNhY3Rpb25UeXBlIjoiMCIsIkRzX1NlY3VyZVBheW1lbnQiOiIwIiwiRHNfTGFuZ3VhZ2UiOiIxIiwiRHNfQ2FyZE51bWJlciI6IjQ1NDg4MSoqKioqKioqMDQiLCJEc19NZXJjaGFudERhdGEiOiIiLCJEc19DYXJkX0NvdW50cnkiOiI3MjQiLCJEc19DYXJkX0JyYW5kIjoiMSJ9",
	"Ds_Signature":"QVxoXwwp919v7XYjyBjhr1VXozESRosHPb3PDW-rcME="
}

Es muy importante que una vez estos parámetros lleguen a tu servidor, los valides firmando estos mismos antes de procesar su contenido, para evitar cualquier posible fraude. Deberás comparar la firma que has obtenido con la que has recibido de los servidores de Redsýs: si coinciden, la notificación no se ha alterado y es veráz.

Para una autorización, deberás comprobar si el pago se ha autorizado o denegado. Para ello, debes descodificar el parámetro Ds_MerchantParameters devuelto en la respuesta, y observar el campo Ds_Response. 0000 indica que la operación ha sido autenticada con éxito, para cualquier otro código devuelto, consulte la tabla de errores generales.

{
	"Ds_Amount": "145",
	"Ds_AuthorisationCode": "501602",
	"Ds_CardNumber": "454881********04",
	"Ds_Card_Brand": "1",
	"Ds_Card_Country": "724",
	"Ds_Currency": "978",
	"Ds_Language": "1",
	"Ds_MerchantCode": "999008881",
	"Ds_MerchantData": "",
	"Ds_Order": "1446068581",
	"Ds_Response": "0000",
	"Ds_SecurePayment": "0",
	"Ds_Terminal": "1",
	"Ds_TransactionType": "0"
}
Descarga nuestros ejemplos
continúa con la integración