Tokenización, Pago 1-clic y operativa COF

En este apartado verás tres conceptos ligados entre sí pero que pueden tener diferentes ámbitos de uso en función de la operativa que quieras hacer, por ello es imprescindible que conozcas bien cada uno de ellos. Empezarás viendo qué es la operativa COF, cómo solicitar la tokenización de una tarjeta y cómo aplicar todo esto para realizar operativas de pago 1-clic.

Credential on File

Una operación COF, denominada Credential on File o Card on File, es una transacción en la que el comercio está haciendo uso de los datos de la tarjeta del titular (PAN o PAN tokenizado y fecha de caducidad), habiendo dicho titular dado autorización explícita al comercio para almacenarlos y para utilizarlos en esa transacción y posteriores. Una transacción COF puede ser iniciada por el titular o iniciada por el comercio como resultado de un acuerdo entre titular y comercio. A la hora de realizar operativa COF, debes identificar en qué casuística quieres operar:

• Quieres que la referencia la genere y gestione Redsýs: En ese caso, deberás solicitar en la llamada al TPV Virtual que se genere una referencia, que se guardará en los servidores de Redsýs. En este caso, no tendrás que preocuparte de cumplir PCI-DSS para almacenar las referencias en una base de datos de tu comercio. Estas referencias estarán ligadas a tu comercio, tal y como se explica más adelante en el apartado de «consideraciones sobre la tokenización». En las operaciones sucesivas, enviarás la referencia que generó el TPV Virtual en la operación inicial.
• Quieres guardar los datos de tarjeta y gestionar la operativa COF tú mismo: Para ello no hará falta que solicites al TPV Virtual que genere referencia, pero tendrás que cumplir rigurosamente la normativa PCI-DSS para almacenar los datos de la tarjeta de tus clientes. En las operaciones sucesivas, no enviarás la referencia, sino los datos de la tarjeta guardados previamente en el servidor de tu comercio tras la primera operación.

Esta operativa y su correcta identificación cobra especial importancia con la aplicación de la PSD2 para todos los pagos iniciados por el comercio sin participación del titular (Merchant Initiated Transaccions – MIT), ya que son operaciones que no se pueden autenticar y, si no se identifican correctamente, pueden ser denegadas por los emisores de tarjetas.

Tipos de operativas COF

Es necesario tener en cuenta si la operación se trata de la primera operación COF, es decir, de la solicitud y almacenamiento de credenciales; o es posterior, es decir, que vas a usar dichas credenciales guardadas anteriormente. Además, debes saber qué tipo de operación vas a realizar:

Afectación de PSD2 a la operativa COF

Con motivo de la entrada en vigor de la directiva Europea de pagos PSD2, se indicaron nuevas características que puede afectar a la funcionalidad de operaciones COF. Se trata de describir las posibilidades que hay combinando la operativa COF con otras operativas existentes en el TPV Virtual de forma que se garantice el cumplimiento de PSD2.

Para comprender esta normativa, te definimos dos conceptos, en los que se engloban todas las operaciones que puedes realizar en tu TPV Virtual:

• Operaciones CIT – Cardholder Initiated Transaction: Son todas las operaciones que ha iniciado o en las que está implicado activamente el titular de la tarjeta.
• Operaciones MIT – Merchant Initiated Transaction: Son aquellas que han sido iniciadas por el comercio y que no tienen por qué tener intervención alguna del titular de la tarjeta.

Con esto presente, las consideraciones que hay que tener en cuenta son las siguientes:

• Operaciones autenticadas: Todas las operaciones CIT deben ser autenticadas. Esto implica que todas las transacciones en las que se piden los datos de tarjeta al titular para su almacenaje (COF iniciales) deberán ser autenticadas, a excepción de las realizadas en entornos remotos no electrónicos, como las operaciones manuales MO/TO, las cuales no requieren autenticación.
• Obligatoriedad de enviar el identificador de la transacción original en COF sucesivas: Será obligatorio enviar el TID (dentro del parámetro DS_MECHANT_COF_TXNID) de la COF inicial en todas las operaciones COF sucesivas. Esto es necesario para probar ante el emisor de la tarjeta que se está aplicando PSD2 correctamente y no se deniegue las operaciones sucesivas por no estar autenticadas. La vinculación de una transacción sucesiva generada por el comercio (MIT) con su operación original (CIT) que sí fue autenticada en su momento, permite al emisor de la tarjeta verificar que se está haciendo un uso correcto de las credenciales de pago y autorizar las operaciones sin incumplir la normativa PSD2. Para ello Redsys devolverá al comercio siempre el valor del TID en la respuesta de la COF inicial, de forma que el comercio pueda incorporarlo en las transacciones COF sucesivas.
  • Es posible que algunas operaciones COF iniciales realizadas antes de la entrada en vigor de PSD2 no dispongan de TID (porque no se generó o porque el comercio no lo guardó), en estos casos debe enviarse el parámetro Ds_Merchant_COF_TXNID con el valor comodín «999999999999999» para identificar de dicha situación al emisor. No obstante, este valor no deberá usarse en transacciones para hacer referencia a operativas ya realizadas dentro del marco temporal de aplicación de la PSD2 y en el futuro será invalidado su uso para algunas marcas. Si en la respuesta a una transacción englobada en esta casuística recibes un nuevo valor de Ds_Merchant_COF_TXNID, deberás actualizar en tu sistema este valor y no volver a enviar el valor comodín.
• Marcaje MIT en COF sucesivas: Debes tener en cuenta la manera correcta de marcar las operaciones COF sucesivas:
  • Operaciones CIT: Se marcan como COF sucesivas y requerirán autenticación del titular (o una exención válida), ya que el titular está participando activamente en la transacción.
  • Operaciones MIT: Para asegurar que no se deniegan por el emisor se deben marcar como COF sucesivas y, además, enviar la exención MIT dentro del parámetro Ds_Merchant_EXCEP_SCA que tendrá el valor «MIT». En estas operaciones, además, se incorporará el parámetro Ds_Merchant_DirectPayment con valor TRUE para indicar que son pagos en los que el titular no está presente y, por extensión, no se puede realizar la autenticación de los mismos.
• Operación COF inicial usando pagos manuales MO/TO: En este caso en particular, no será necesario autenticar al estar fuera del alcance de PSD2. Las operaciones COF subsiguientes cuando la inicial ha sido MO/TO pueden ser:
  • CIT por TPV Virtual: Se debe marcar la operación COF sucesiva, requerirá autenticación o exención.
  • CIT por canal telefónico: La operación por tanto es considerada MO/TO.
  • MIT: COF sucesivas con el TID obtenido en la operación MO/TO inicial (COF inicial).

Tokenización y Pago 1-clic

La tokenización es un tipo concreto de operativa COF. Con este tipo de operación, el comercio no tiene que almacenar los datos de tarjeta de sus clientes para poder realizar pagos posteriores. De este modo, Redsys genera una referencia asociada a la tarjeta y almacenará los datos necesarios para posteriores operaciones. Esta referencia se denomina Token.

En futuros pagos, el comercio sólo deberá indicar la referencia generada para realizar el pago, sin necesidad de que envíe los datos de la tarjeta. Esto es útil si quieres que tus clientes puedan guardar las tarjetas para futuros pagos y pagar de manera más cómoda. Te recomendamos que solicites a BBVA que, cuando te active esta funcionalidad, también te active la posibilidad de recibir la tarjeta asteriscada en la notificación. Esto es porque así podrás mostrar los cuatro últimos dígitos de su tarjeta a tu cliente cuando vaya a pagar para que sepa, en operaciones sucesivas, con qué tarjeta va a realizar el pago una vez ha sido guardada. Además, al recibir también la fecha de caducidad de la tarjeta, tú mismo podrás gestionar la renovación del Token una vez se acerque dicha fecha para que el cliente siempre tenga su token actualizado y disponible para pagar.

Consideraciones sobre la tokenización

Para que un comercio utilice tokenización, debe tener en cuenta una serie de puntos para realizar correctamente las operaciones que involucran el uso de referencias:

• BBVA debe configurar el comercio con los permisos necesarios, de lo contrario, en ningún caso se generará la referencia.
• El número de referencia se asociará también al número de comercio (FUC) que ha usado la solicitud. Es decir, sólo el FUC que ha solicitado la referencia podrá utilizar dicha referencia en operaciones sucesivas. Si deseas que varios FUC puedan utilizar la misma referencia, se deberá configurar un grupo que debes solicitar a BBVA.
• Los datos de la tarjeta se mantendrán almacenados hasta la fecha de validez de su caducidad, momento en el que pasará a ser inválida.
• En la notificación donde se recoja la referencia, también se incluirá la validez de la tarjeta, para que puedas controlar hasta que día debes mostrar la referencia a tu cliente.
• Para generar la referencia, el pago debe ser autorizado; es decir, que el proceso de pago debe completarse.
• Se permite la generación de referencias en operaciones de importe 0 y, por supuesto, su uso para dicha operativa.
• Las operaciones serán autenticadas o no en función del tipo de operación: todas las CIT, es decir, las que ha iniciado el titular, deberán ser autenticadas; las MIT pueden ser enviadas con el parámetro Ds_Merchant_DirectPayment con el valor TRUE para que no se envíen a autenticar. Deberás solicitar a BBVA que active los métodos de pago Tradicionales para poder usar dicho parámetro.
  • Esto sólo lo tienes que tener en cuenta en las integraciones REST, ya que en Redirección, nosotros nos ocupamos de todo.

Proceso de integración de la operativa COF y tokenización

En este apartado, verás como integrar COF y tokenización dentro de la operativa de pagos estándar que ya tengas implementada. Como verás a continuación, la manera de obtener una referencia y un ID de transacción es muy sencilla, y sólo tendrás que ocuparte de la lógica interna de gestión de esa referencia (cómo guardarla, cuando mostrarla a tu cliente, etcétera).

Primera operación

Para la primera operación, es posible el envío de dos nuevos parámetros adicionales a los normalmente utilizados en la integración que ya tengas realizada en tu comercio. Estos son:

• Si quieres que Redsýs cree y gestione la referencia.
  • Ds_Merchant_Identifier: Se deberá enviar con el valor «REQUIRED». En este caso, el parámetro Ds_Merchant_COF_INI es opcional, ya que al solicitar una referencia, es inequívoco que quieres usar operativa COF.
• Si quieres almacenar tú mismo los datos de la tarjeta del cliente, ¡ten cuidado con las implicaciones PCI-DSS!
  • Ds_Merchant_COF_INI: Parámetro que indica que se trata de una operativa COF. Para marcar que es la primera operación es necesario enviar Ds_Merchant_COF_INI con el valor «S».
• Ds_Merchant_COF_TYPE: Este parámetro siempre es opcional pero altamente recomendable. Indica el tipo de operativa COF que quieres utilizar en las sucesivas operaciones. Si este parámetro no se enviase, se usaría como predeterminado el valor «C» (otras). Puedes ver la tabla de valores en el comienzo de esta página.

Para incluir la operativa COF dentro de tu integración, deberás agregar dos parámetros adicionales a la llamada al TPV Virtual en función de cómo quieras gestionar la operación, debidamente cumplimentados tal y como se ha explicado. Puedes usar como ejemplo de integración completa la mostrada dentro de la página Realizar un Pago, teniendo que agregar sólo los parámetros que se explican en los puntos anteriores o siguiendo los ejemplos siguientes.

"DS_MERCHANT_IDENTIFIER": "REQUIRED",
"DS_MERCHANT_COF_INI": "S",
"DS_MERCHANT_COF_TYPE": "R",

"DS_MERCHANT_COF_INI": "S",
"DS_MERCHANT_COF_TYPE": "R",

Un ejemplo de respuesta del TPV Virtual es el que se muestra a continuación:

{
  "Ds_Amount": "145",
  "Ds_Currency": "978",
  "Ds_Order": "9722vBXOv5O",
  "Ds_MerchantCode": "999008881",
  "Ds_Terminal": "1",
  "Ds_Response": "0000",
  "Ds_AuthorisationCode": "381927",
  "Ds_TransactionType": "0",
  "Ds_SecurePayment": "0",
  "Ds_Language": "1",
  "Ds_CardNumber": "454881******0003",
  "Ds_ExpiryDate": "3412",
  "Ds_Merchant_Identifier": "120c14ed9f7264383434fc1154559f1e2bcc2b1c",
  "Ds_MerchantData": "",
  "Ds_Card_Country": "724",
  "Ds_Card_Brand": "1",
  "Ds_Merchant_Cof_Txnid": "2006031152000"
}

{
  "Ds_Amount": "145",
  "Ds_Currency": "978",
  "Ds_Order": "9722vBXOv5O",
  "Ds_MerchantCode": "999008881",
  "Ds_Terminal": "1",
  "Ds_Response": "0000",
  "Ds_AuthorisationCode": "381927",
  "Ds_TransactionType": "0",
  "Ds_SecurePayment": "0",
  "Ds_Language": "1",
  "Ds_CardNumber": "454881******0003",
  "Ds_ExpiryDate": "3412",
  "Ds_MerchantData": "",
  "Ds_Card_Country": "724",
  "Ds_Card_Brand": "1",
  "Ds_Merchant_Cof_Txnid": "2006031152000"
}

En la respuesta, puedes observar dos nuevos parámetros que deberás almacenar:

• Ds_Merchant_Identifier: Si has solicitado la generación de referencia, esta es la que debes almacenar y que enviarás en las sucesivas operaciones para que el cliente no tenga que introducir sus datos de tarjeta. Esto sólo lo recibirás si enviaste el parámetro Ds_Merchant_Identifier con el valor «REQUIRED».
• Ds_Merchant_Cof_Txnid: Es la identificador de la operación original. Puedes no guardarlo si solicitaste la creación de referencia, ya que el SIS lo incorporará automáticamente si no se especifica; pero es obligatorio en caso de que gestiones los datos de la tarjeta tú mismo. De cualquier manera, recomendamos guardarlo con la referencia y enviarlo en las operaciones sucesivas.

También se adjunta la tarjeta asteriscada si seguiste nuestro consejo de solicitarlo, por lo que podrás mostrar a tu cliente los últimos cuatro dígitos de la tarjeta que se va a utilizar para pagar si vas a operar COF usando referencias.

Operaciones sucesivas

Para la primera operación, es posible el envío de dos nuevos parámetros adicionales a los normalmente utilizados en la integración que ya tengas realizada en tu comercio. Estos son:

• Si quieres que Redsýs cree y gestione la referencia.
  • Ds_Merchant_Identifier: Deberás adjuntar la referencia que se incluyó en la respuesta del TPV Virtual en la primera operación.
• Si almacenaste tú mismo los datos de la tarjeta del cliente.
  • Ds_Merchant_COF_TXNID: Es el identificador que se incluyó en la respuesta del TPV Virtual en la primera operación.
• Ds_Merchant_COF_TYPE: Este parámetro siempre es opcional pero altamente recomendable. Indica el tipo de operativa COF que quieres utilizar en las sucesivas operaciones. Si este parámetro no se enviase, se recuperaría el utilizado en la primera operación.

Además, en las operaciones sucesivas, debes tener en cuenta quién está iniciando la operación:

• CIT: Si la operación está siendo iniciada por el cliente (has tokenizado su tarjeta para permitirle pagar usando 1-clic) no debes adjuntar nada más en la llamada al TPV.
• MIT: Si es tu comercio el que está iniciando la operación (una suscripción, por ejemplo) entonces debes incorporar el parámetro Ds_Merchant_DirectPayment con el valor «TRUE».

Puedes usar como ejemplo de integración completa la mostrada dentro de la página Realizar un Pago, teniendo que agregar sólo los parámetros que se explican en los puntos anteriores o siguiendo los ejemplos siguientes. En las operaciones sucesivas usando inSite y una referencia generada anteriormente, no tienes por qué realizar el proceso de generación del idOper, ya que la referencia actuará como tal a la hora de realizar el proceso de autorización.

"DS_MERCHANT_IDENTIFIER": "120c14ed9f7264383434fc1154559f1e2bcc2b1c",
"DS_MERCHANT_COF_TYPE": "R",

"DS_MERCHANT_PAN": "4548**********03",
"DS_MERCHANT_EXPIRYDATE": "4912",
"DS_MERCHANT_COF_TXNID": "2006031152000",
"DS_MERCHANT_COF_TYPE": "R",

Un ejemplo de respuesta del TPV Virtual es el que se muestra a continuación:

{
  "Ds_Date":"10%2F12%2F2019",
  "Ds_Hour":"09%3A41",
  "Ds_SecurePayment":"0",
  "Ds_Card_Type":"D",
  "Ds_Card_Country":"724",
  "Ds_Amount":"1000",
  "Ds_Currency":"978",
  "Ds_Merchant_Identifier": "219851688d37e3b965e41c1545a34b6f4538f9e7",
  "Ds_Order":"1575967259",
  "Ds_MerchantCode":"999008881",
  "Ds_Terminal":"1",
  "Ds_Response":"0000",
  "Ds_MerchantData":"",
  "Ds_TransactionType":"0",
  "Ds_ConsumerLanguage":"1",
  "Ds_AuthorisationCode":"372663",
  "Ds_Card_Brand":"2"
}																

{
  "Ds_Amount": "145",
  "Ds_Currency": "978",
  "Ds_Order": "9722vBXOv5O",
  "Ds_MerchantCode": "999008881",
  "Ds_Terminal": "1",
  "Ds_Response": "0000",
  "Ds_AuthorisationCode": "381927",
  "Ds_TransactionType": "0",
  "Ds_SecurePayment": "0",
  "Ds_Language": "1",
  "Ds_CardNumber": "454881******0003",
  "Ds_ExpiryDate": "3412",
  "Ds_MerchantData": "",
  "Ds_Card_Country": "724",
  "Ds_Card_Brand": "1",
  "Ds_Merchant_Cof_Txnid": "2006031152000"
}

Como puedes comprobar, el TPV Virtual te responderá con la referencia en el parámetro Ds_Merchant_Identifier y con el identificador COF en parámetro Ds_Merchant_Cof_Txnid. En ambos casos, estos valores deben ser idénticos a los que ya tenías guardados hasta ahora.

Gestión de referencias

En el caso de que hayas usado la generación de referencias, es posible que en algún momento desees dar de baja alguna referencia, a petición de tu cliente o por simple gestión de las mismas. Para ello, hay un tipo de operativa preparado para hacerlo.

Para realizar la operación, envía una petición REST al TPV Virtual con los datos de identificación de tu comercio (FUC – Terminal), así como la referencia que quieres dar de baja y un número de pedido. Este número de pedido será como un número de identificación de la operación y no puede ser ninguno que hayas enviado anteriormente, o recibirás un error. Recuerda además, que usarás este número de pedido para firmar la petición como en cualquier operativa REST.

La petición se enviará directamente al endpoint de trataPeticion, en función del entorno en el que estés trabajando.

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

{
    "Ds_Merchant_MerchantParameters": "eyJEU19NRVJDSEFOVF9PUkRFUiI6MTY4MTg5Nzk5OSwiRFNfTUVSQ0hBTlRfTUVSQ0hBTlRDT0RFIjoiOTk5MDA4ODgxIiwiRFNfTUVSQ0hBTlRfVEVSTUlOQUwiOiIyNDkiLCJEU19NRVJDSEFOVF9UUkFOU0FDVElPTlRZUEUiOiI0NCIsIkRTX01FUkNIQU5UX0lERU5USUZJRVIiOiIyMjNmZmRhZDhlMWJjMTNhMDFjOTQyMjQ2NjljZDFmYzA3NzViMTBiIn0==",
    "Ds_Merchant_Signature": "56BsphIx3uZYgdVufqhoQBe2obth6Tz3J2ZdHyqTjHJ7zLqxPP2myS9MMwRNinRj8/VAEWsA3bLtH7jruOBhWw==",
    "Ds_SignatureVersion": "HMAC_SHA512_V1"
}

{
	"DS_MERCHANT_ORDER": 1681897999,
	"DS_MERCHANT_MERCHANTCODE": "999008881",
	"DS_MERCHANT_TERMINAL": "249",
	"DS_MERCHANT_TRANSACTIONTYPE": "44",
	"DS_MERCHANT_IDENTIFIER": "223ffdad8e1bc13a01c94224669cd1fc0775b10b"
}

Como puedes comprobar, sólo se ha adjuntado la referencia que se quiere dar de baja junto con el número de orden. El resto de parámetros son la identificación de tu comercio y el tipo de transacción. El TPV Virtual responderá directamente con un error en caso de que la referencia no exista, esté dada de baja o hayas cometido un error en la llamada; o con unos parámetros completos en el que deberás analizar el parámetro Ds_Response.

{
    "Ds_SignatureVersion": "HMAC_SHA512_V1",
    "Ds_MerchantParameters": "eyJEc19PcmRlciI6IjE2ODE4OTc5OTkiLCJEc19NZXJjaGFudENvZGUiOiI5OTkwMDg4ODEiLCJEc19UZXJtaW5hbCI6IjI0OSIsIkRzX1Jlc3BvbnNlIjoiMDAwMCIsIkRzX1RyYW5zYWN0aW9uVHlwZSI6IjQ0IiwiRHNfQ29udHJvbF8xNjgxODk4MDAxMjYwIjoiMTY4MTg5ODAwMTI2MCJ9",
    "Ds_Signature": "4thE_dbWXdKIapGQVO2NbGhVHCOixzKT9pz42LGKPqrc5c6Le7UhVvGdGgQyfeHoXpvoCFsl_aGyUTQj_cgRvQ=="
}

{
	"Ds_Order": "1681897999",
	"Ds_MerchantCode": "999008881",
	"Ds_Terminal": "249",
	"Ds_Response": "0000",
	"Ds_TransactionType": "44",
	"Ds_Control_1681898001260": "1681898001260"
}

Si la respuesta recibida en el parámetro Ds_Response es «0000», entonces el borrado ha ido correctamente.