Credential on File y Tokenización

Una operación Credential-On-File (COF) es una transacción en la que el comercio está haciendo uso de los datos del titular de la tarjeta (PAN o PAN tokenizado y fecha de caducidad), de los cuales el titular ha dado autorización explícita al comercio para almacenarlos y para utilizarlos en esta 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.

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.

Operativas COF

Es necesario saber si es la primera operación COF (almacenamiento de credenciales) o es posterior (uso de credenciales), y el tipo de COF que desea usarse:

Operativas principales de COF

  • Installments: Pago aplazado. Siempre referido a una compra INDIVIDUAL, el importe de las diferentes transacciones es fijo, y con un intervalo de tiempo definido
  • Recurring: Pago recurrente. El importe de las transacciones puede ser fijo o variable, y con un intervalo de tiempo definido

Operativas especiales de COF

  • Reauthorization: Normalmente ante envíos parciales. También cuando el cliente amplía la estancia en hotel / alquiler del vehículo o cuando habiendo una autorización estimada, se solicita el importe final (“remate”)
  • Resubmission: Original denegada por “saldo”; solo para ciertos sectores de actividad (para más detalle revisar la normativa de las marcas) y con un máximo de días desde la compra. Ejemplo relevante: “Transporte”
  • Delayed: los que suceden con posterioridad a la operación por servicios prestados / usados desconocidos al principio. (Minibar, daños vehículo, multas, ...)
  • Incremental: cuando durante el periodo de contrato se incurren en servicios adicionales
  • No Show: cuando el comercio cobra servicios a los que el titular se comprometió, pero luego no cumplió con los términos acordados. Ejemplo relevante: reservas en hoteles no atendidas sin cancelar.

Tokenización

La Tokenización es un tipo concreto de 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 éste modo, Redsys genera una referencia asociada (Token) a la tarjeta y almacenará todos los datos necesarios para posteriores operaciones. En futuros pagos, el comercio solo deberá indicar la referencia generada para realizar el pago, sin necesidad de enviar los datos de tarjeta.

Los pasos a seguir para realizar una referencia son los siguientes:

  1. El comercio solicita un pago, junto con los datos necesarios y el parámetro "Ds_Merchant_Identifier", de esta forma se genera una "referencia" asociada a los datos de tarjeta.
  2. El SIS procesa la solicitud de pago y almacena los datos de tarjeta (sólo Tarjeta y Caducidad, nunca CVV2) asociados a una referencia generada internamente. Sólo se generará la referencia si el pago es autorizado.
  3. El SIS devuelve la referencia y la fecha de caducidad (aunque el comercio no esté configurado para ello) junto con la respuesta del pago para que el comercio pueda utilizarla con posterioridad.

Las peticiones deben ser mandadas a: https://sis.redsys.es/sis/rest/trataPeticionREST.


Primera operación

Para la primera operación es posible el envío de dos nuevos parámetros:

  • DS_MERCHANT_COF_INI: parámetro que indica que es la primera transacción. Para marcar que es la primera operación es necesario enviar "DS_MERCHANT_COF_INI"= "S". Si en la petición se envía el Ds_Merchant_Identifier=”REQUIRED”, el parámetro "DS_MERCHANT_COF_INI" es opcional.
  • DS_MERCHANT_COF_TYPE: Este parámetro es opcional, e indica el tipo de operativa COF que desea usarse en sucesivas operaciones. Si no se envía se registrará como operativa COF tipo “C” (Otras). No obstante, para obtener los mejores resultados de autorización se recomienda incluir este campo para informar al emisor con la mayor precisión del motivo del almacenamiento de credenciales, y es de especial importancia con la PSD2 en los casos que en los que se enviaran MIT sin autenticar de forma posterior.

    Tipo de COF Valor DS_MERCHANT_COF_TYPE
    Installments I
    Recurring R
    Reauthorization H
    Resubmission E
    Delayed D
    Incremental M
    No Show N
    Otras C

Modalidad REST

Ejemplo de pago COF vía REST.


  • IMPORTANTE: En la petición, el valor del parámetro Ds_Merchant_Identifier debe ser "REQUIRED", y debe ser enviado junto a los datos de la tarjeta.
  • Para realizar una operativa COF vía REST, es necesario envíar el parámetro "Ds_MerchantParameters" del siguiente modo:

					
{
  "DS_MERCHANT_MERCHANTCODE": "999008881",
  "DS_MERCHANT_TRANSACTIONTYPE": "0",
  "DS_MERCHANT_EXPIRYDATE": "3412",
  "DS_MERCHANT_COF_INI": "S",
  "DS_MERCHANT_ORDER": "9722vBXOv5O",
  "DS_MERCHANT_CVV2": "***",
  "DS_MERCHANT_TERMINAL": "49",
  "DS_MERCHANT_CURRENCY": "978",
  "DS_MERCHANT_IDENTIFIER": "REQUIRED",
  "DS_MERCHANT_AMOUNT": "145",
  "DS_MERCHANT_PAN": "454**********003"
}
					
				

Una vez realizada esta petición, se recibe una respuesta que puede contener un error, o un elemento "Ds_MerchantParameters", el cual debemos decodificar en BASE64. De esta forma obtenemos el parámetro "Ds_Response", si su valor es "0000" el pago ha sido autorizado

					
{
  "Ds_Amount": "145",
  "Ds_Currency": "978",
  "Ds_Order": "9722vBXOv5O",
  "Ds_MerchantCode": "999008881",
  "Ds_Terminal": "49",
  "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"
}
						    
						

Modalidad Redirección

Ejemplo de pago con autorización vía Redirección.


  • IMPORTANTE: En la petición, el valor del parámetro Ds_Merchant_Identifier debe ser "REQUIRED", y debe ser enviado junto a los datos de la tarjeta.
  • Para realizar una operativa COF vía Redirección, es necesario envíar el parámetro "Ds_MerchantParameters" del siguiente modo:

					
{
  "DS_MERCHANT_MERCHANTCODE": "999008881",
  "DS_MERCHANT_TRANSACTIONTYPE": "0",
  "DS_MERCHANT_COF_INI": "S",
  "DS_MERCHANT_COF_TYPE": "R",
  "DS_MERCHANT_ORDER": "9722vBXOv5O",
  "DS_MERCHANT_TERMINAL": "49",
  "DS_MERCHANT_CURRENCY": "978",
  "DS_MERCHANT_IDENTIFIER": "REQUIRED",
  "DS_MERCHANT_AMOUNT": "145",
  "DS_MERCHANT_MERCHANTURL":"http://www.prueba.com/urlNotificacion.php",
  "DS_MERCHANT_URLOK":"http://www.prueba.com/urlOK.php",
  "DS_MERCHANT_URLKO":"http://www.prueba.com/urlKO.php"
}					
					
				

Una vez realizada esta petición, se recibe una respuesta que puede contener un error, o un elemento "Ds_MerchantParameters", el cual debemos decodificar en BASE64. De esta forma obtenemos el parámetro "Ds_Response", si su valor es "0000" el pago ha sido autorizado

					
{
  "Ds_Amount": "145",
  "Ds_Currency": "978",
  "Ds_Order": "9722vBXOv5O",
  "Ds_MerchantCode": "999008881",
  "Ds_Terminal": "49",
  "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"
}
						    
						

Modalidad InSite

Ejemplo de pago con autorización vía InSite.


  • IMPORTANTE: En la petición, el valor del parámetro Ds_Merchant_Identifier debe ser "REQUIRED", y debe ser enviado junto a los datos de la tarjeta.
  • Para realizar una autorización vía insite, es necesario envíar el parámetro "DS_MERCHANT_IDOPER" en el elemento "Ds_MerchantParameters":

					
{
  "DS_MERCHANT_AMOUNT": "145",
  "DS_MERCHANT_CURRENCY": "978",
  "DS_MERCHANT_COF_INI": "S",
  "DS_MERCHANT_COF_TYPE": "R",
  "DS_MERCHANT_IDENTIFIER": "REQUIRED",
  "DS_MERCHANT_MERCHANTCODE": "999008881",
  "DS_MERCHANT_ORDER": "1446068581",
  "DS_MERCHANT_IDOPER": "9c75f357629acb672e0f5444401d138f02e834ad ",
  "DS_MERCHANT_TERMINAL": "49",
  "DS_MERCHANT_TRANSACTIONTYPE": "0"
}
					
				

Una vez realizada esta petición, se recibe una respuesta que puede contener un error, o un elemento "Ds_MerchantParameters", el cual debemos decodificar en BASE64. De esta forma obtenemos el parámetro "Ds_Response", si su valor es "0000" el pago ha sido autorizado

					
{
  "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": "49",
  "Ds_Merchant_Cof_Txnid": "2006031152000"
}
				    
				

Operaciones sucesivas

  • DS_MERCHANT_COF_TYPE: Tipo de COF a enviar. Si no se envía, el sistema recupera el utilizado en la operación de registro
  • DS_MERCHANT_COF_TXNID: Identificador generado por el emisor en la operación de registro de COF
Nota: Estos parámetros no será necesario enviarlos en la peticiones ucesivas en las que se envía un DS_MERCHANT_IDENTIFIER válido.

Modalidad REST

Ejemplo de pago sucesivo COF vía REST.


Para realizar un pago sucesivo COF utilizando una referencia ya generada, es necesario envíar el parámetro "Ds_MerchantParameters" del siguiente modo:

					
{
    "DS_MERCHANT_IDENTIFIER": "120c14ed9f7264383434fc1154559f1e2bcc2b1c",
    "DS_MERCHANT_MERCHANTCODE": "999008881",
    "DS_MERCHANT_TRANSACTIONTYPE": "0",
    "DS_MERCHANT_DIRECTPAYMENT": "true",
    "DS_MERCHANT_ORDER": "4986Qpqx",
    "DS_MERCHANT_TERMINAL": "49",
    "DS_MERCHANT_CURRENCY": "978",
    "DS_MERCHANT_AMOUNT": "145",
}
					
				

Para realizar un pago sucesivo COF enviando directamente los datos de tarjeta (si se permite), es necesario envíar el parámetro "Ds_MerchantParameters" del siguiente modo:

					
{
    "DS_MERCHANT_PAN": "4548**********03",
    "DS_MERCHANT_EXPIRYDATE": "4912",
    "DS_MERCHANT_COF_INI": "N",
    "DS_MERCHANT_COF_TXNID": "2006031152000",
    "DS_MERCHANT_MERCHANTCODE": "999008881",
    "DS_MERCHANT_TRANSACTIONTYPE": "0",
    "DS_MERCHANT_DIRECTPAYMENT": "true",
    "DS_MERCHANT_ORDER": "4986Qpqx",
    "DS_MERCHANT_TERMINAL": "49",
    "DS_MERCHANT_CURRENCY": "978",
    "DS_MERCHANT_AMOUNT": "145",
}
					
				

Una vez realizada esta petición, se recibe una respuesta que puede contener un error, o un elemento "Ds_MerchantParameters", el cual debemos decodificar en BASE64. De esta forma obtenemos el parámetro "Ds_Response", si su valor es "0000" el pago ha sido autorizado

					
{
    "Ds_Amount": "145",
    "Ds_Currency": "978",
    "Ds_Order": "4986Qpqx",
    "Ds_MerchantCode": "999008881",
    "Ds_Terminal": "49",
    "Ds_Response": "0000",
    "Ds_AuthorisationCode": "382041",
    "Ds_TransactionType": "0",
    "Ds_SecurePayment": "0",
    "Ds_Language": "1",
    "Ds_CardNumber": "454881******0003",
    "Ds_MerchantData": "",
    "Ds_Card_Country": "724",
    "Ds_Card_Brand": "1",
    "Ds_Merchant_Cof_Txnid": "2006031152000"
}
						    
						

Modalidad Redirección

Ejemplo de pago con autorización vía Redirección.


Para realizar una autorización mediante redirección, es necesario envíar el parámetro "Ds_MerchantParameters" del siguiente modo:

										
{
  "DS_MERCHANT_IDENTIFIER": "120c14ed9f7264383434fc1154559f1e2bcc2b1c",	
  "DS_MERCHANT_MERCHANTCODE": "999008881",
  "DS_MERCHANT_TRANSACTIONTYPE": "0",
  "DS_MERCHANT_DIRECTPAYMENT": "true",
  "DS_MERCHANT_ORDER": "4986Qpqx",
  "DS_MERCHANT_TERMINAL": "49"
  "DS_MERCHANT_CURRENCY": "978",
  "DS_MERCHANT_AMOUNT": "145",
  "DS_MERCHANT_MERCHANTURL":"http://www.prueba.com/urlNotificacion.php",
  "DS_MERCHANT_URLOK":"http://www.prueba.com/urlOK.php",
  "DS_MERCHANT_URLKO":"http://www.prueba.com/urlKO.php"
}					
					
				

Una vez realizada esta petición, se recibe una respuesta que puede contener un error, o un elemento "Ds_MerchantParameters", el cual debemos decodificar en BASE64. De esta forma obtenemos el parámetro "Ds_Response", si su valor es "0000" el pago ha sido autorizado

					
{
    "Ds_Amount": "145",
    "Ds_Currency": "978",
    "Ds_Order": "4986Qpqx",
    "Ds_MerchantCode": "999008881",
    "Ds_Terminal": "49",
    "Ds_Response": "0000",
    "Ds_AuthorisationCode": "382041",
    "Ds_TransactionType": "0",
    "Ds_SecurePayment": "0",
    "Ds_Language": "1",
    "Ds_CardNumber": "454881******0003",
    "Ds_MerchantData": "",
    "Ds_Card_Country": "724",
    "Ds_Card_Brand": "1",
    "Ds_Merchant_Cof_Txnid": "2006031152000"
}
						    
						

Gestión de referencias

Borrar referencia

A continuación se muestra la petición que hay que realizar para borrar una referencia.

  • IMPORTANTE: Si se desea borrar una referencia creada, se debe enviar el parámetro Ds_Merchant_Identifier con el valor de la referencia a borrar y el valor Ds_Merchant_TransactionType con el valor "44".

							
{
  "DS_MERCHANT_MERCHANTCODE": "999008881",
  "DS_MERCHANT_IDENTIFIER": "a091f0f9f0aaf0506930dda4a6974f1df4a0d9c1",
  "DS_MERCHANT_ORDER": "0281WjRq",
  "DS_MERCHANT_TERMINAL": "49",
  "DS_MERCHANT_TRANSACTIONTYPE": "44"
}
						
				   

															
{
  "Ds_MerchantCode": "999008881",
  "Ds_Order": "0281WjRq",
  "Ds_Response": "0000",
  "Ds_Terminal": "49",
  "Ds_TransactionType": "44"
}
					   
				  

Consideraciones PSD2

Con motivo de la entrada en vigor de la directiva de Europea de Pagos PSD2, se indican algunas 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 Get Checkout ES (3DSecure, marcaje MIT, etc.) de forma que se garantice el cumpliendo de PSD2.

  1. Operaciones autenticadas: Todas las operaciones CIT - Cardholder Initiated Transaction (aquellas donde el titular participa activamente) 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 (MO/TO – Mail Order/Telephone Order). que no requieren autenticación

  2. Obligatoriedad de enviar el identificador de la transacción original - TID en COF sucesivas: Será obligatorio enviar el TID (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 "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 MIT el comercio recibe un nuevo valor de DS_MECHANT_COF_TXNID, deberá almacenarlo para ser utilizado en las futuras transacciones sucesivas ligadas a esa transacción en lugar del valor "999999999999999"

  3. Marcaje MIT en COF sucesivas. Las COF subsiguientes podrán ser:
    • CIT (Cardholder Initiated Transaction): se marcan como COF sucesivas, y requerirán autenticación del titular (o exención) al estar el titular participando activamente en la transacción.
    • MIT (Merchant Initiated Transaction): para asegurar que no se deniegan por el emisor se deben marcar como COF sucesivas y como MIT mediante el parámetro DS_MERCHANT_EXCEP_SCA = “MIT”. De forma adicional, en las transacciones marcadas como MIT se deberá indicar el parámetro Ds_Merchant_DirectPayment=true para indicar que son pagos sin intervención del titular de la tarjeta y por lo tanto no es posible realizar la autenticación del mismo.

  4. Operación COF inicial MO/TO (Mail Order/Telephone Order): La operación COF inicial podría ser realizada en un entorno remoto no electrónico MO/TO. En este caso no será necesario autenticar al estar fuera de alcance de SCA-PSD2. Las operaciones COF subsiguientes (cuando la inicial ha sido MOTO) al igual que las descritas anteriormente, pueden ser:
    • CIT por comercio electrónico/website/app: marcar la operación COF sucesiva, requerirá autenticación o exención.
    • CIT por canal telefónico: la operación por tanto se considera MOTO.
    • MIT: COF sucesivas con el TID obtenido en la operación MOTO inicial (COF inicial).