- Pautas de integración
- Características soportadas (seguridad)
- Autenticación 3-D Secure
- Preguntas frecuentes sobre la autenticación
Preguntas frecuentes sobre la autenticación
Preguntas frecuentes sobre 3-D Secure
Puede ver los detalles de autenticación para las autenticaciones individuales y las autenticaciones que continuaron con el pago en el portal de Merchant Administration. Busque el pedido o la transacción en la página de búsqueda y vea los detalles de autenticación.
Si desea ver los detalles de autenticación para una autenticación 3DS1, por ejemplo, para ver datos de campos como PARes, PAReq, use la opción de búsqueda de autenticaciones en el portal de Merchant Administration.
Si usa la API de autenticación, puede ver los detalles de autenticación en el portal de Merchant Administration cuando se completa la autenticación del pagador. Si la autenticación del pagador aún no está completa, es posible que experimente un retraso en la transacción de autenticación que se muestra al buscar un pedido o una transacción en el portal de Merchant Administration. Por ejemplo, pasar por un flujo de desafío.
Mientras tanto, puede recuperar el estado actual de la autenticación mediante la operación Retrieve Order o Retrieve Transaction.
Si desea recuperar los resultados de autenticación en cualquier etapa, utilice la operación Retrieve Transaction. Tenga en cuenta que los campos que solo se usan durante la autenticación, por ejemplo, authentication.redirect.html, no se conservan en el motor de pagos y, por lo tanto, no se devuelven.
Si ha usado un MPI 3DS externo para autenticar al pagador, entonces debe transmitir la información sobre la autenticación en el grupo de parámetros de autenticación de la operación Authorize o Pay.
Todos los campos son opcionales, si le fueron proporcionados o no por el MPI 3DS externo depende de la versión de autenticación (3DS1 o 3DS2) y el estado de la transacción. Sin embargo, si tiene los datos, se recomienda que los proporcione.
authentication.3ds.acsEci: el indicador de comercio electrónico que se le puede devolver en el mensaje de respuesta de autenticación.authentication.3ds.authenticationToken: el valor codificado base64 generado por el emisor de la tarjeta que se le puede devolver en el mensaje de respuesta de autenticación.authentication.3ds.transactionId: un identificador de transacción único generado por el motor de pagos para la autenticación 3DS.
Para 3DS1, este campo corresponde a XID, que es un identificador de transacción único generado por el motor de pagos en nombre del negocio. Un XID enviado en este campo debe estar en formato base64.
Para 3DS2, este campo corresponde al identificador asignado por el servidor de directorio del esquema.authentication.3ds2.protocolVersion: la versión del protocolo EMV 3-D Secure utilizada para realizar la autenticación 3-D Secure, en el formato especificado por EMVCo. Por ejemplo, 2.1.0authentication.3ds2.transactionStatus: indica el resultado de la autenticación del pagador con el emisor.authentication.3ds2.statusReasonCode: un código que indica el motivo del estado de la transacción devuelto enauthentication.3ds2.transactionStatus. Debe proporcionar esto cuandoauthentication.3ds2.transactionStatusdevuelve N, U o R.authentication.amount: este es un campo opcional. Indica el monto de la autenticación. Debe proporcionar valores en este campo cuando el monto de autenticación difiera deorder.amount. Antes de proporcionar valores en este campo, consulte a su proveedor de servicios de pago.authentication.time: este es un campo opcional. Indica la fecha y hora de autenticación del pagador. Antes de proporcionar valores en este campo, consulte a su proveedor de servicios de pago.
authentication.3ds.authenticationToken.Si el suyo es un negocio de comercio electrónico con un vínculo de adquirente de mada en el Reino de Arabia Saudita y un pagador completamente autenticado en 3DS fuera del motor de pagos, debe estar integrado a la API de servicios web versión 76 o posterior y proporcionar los siguientes detalles de autenticación en la operación Authorize o Pay para enviar correctamente una transacción con una tarjeta mada de marca compartida, una tarjeta mada de marca única o una tarjeta internacional:
authentication.3ds2.acsReference: especifica un número de referencia que EMVCo asigna al servidor de control de acceso (ACS) del emisor tras la aprobación del ACS. Este campo corresponde al campo acsReferenceNumber de EMVCo.authentication.3ds2.dsReference: especifica un número de referencia que EMVCo asigna al servidor de directorio (DS) tras la aprobación del DS. Este campo corresponde al campo dsReferenceNumber de EMVCo.authentication.3ds2.acsTransactionId: especifica un identificador de transacción único que el servidor de control de acceso asigna para identificar la transacción 3DS.authentication.time: especifica la fecha y hora de autenticación del pagador. Este campo corresponde al campo purchaseDate de EMVCo.authentication.3ds.acsEci: especifica el valor del indicador de comercio electrónico (ECI) que el servidor de control de acceso (ACS) proporciona para indicar los resultados del intento de autenticar al pagador.authentication.3ds.authenticationToken: especifica el valor codificado en base64 que genera el emisor. Este campo corresponde al Valor de autenticación.authentication.3ds.transactionId: corresponde al ID de transacción de DS.authentication.3ds2.protocolVersion: especifica la versión del protocolo EMV 3-D Secure que se utiliza para realizar la autenticación 3-D Secure. Por ejemplo, 2.1.0.authentication.3ds2.transactionStatus: corresponde al campo transStatus de EMVCo.authentication.3ds2.authenticationScheme: para transacciones mada de marca compartida autenticadas de manera externa, debe proporcionar MADA, MASTERCARD o VISA para especificar el Servidor de directorio 3DS a través del cual se autenticó la transacción. Para transacciones mada de marca única autenticadas de manera externa, puede proporcionar MADA o no enviar este campo. Para otras tarjetas, puede proporcionar el esquema de autenticación respectivo o no enviar este campo.
Si desea realizar la autenticación para verificar únicamente la identidad del pagador sin proceder al pago, debe indicar el propósito de la autenticación en la solicitud Initiate Authentication. Por ejemplo, es posible que desee autenticar al pagador cuando el pagador ingrese los detalles de su tarjeta para su uso posterior durante el registro del cliente o la creación de una cuenta en su sitio web. La capacidad de completar el proceso de autenticación en un entorno que no sea de pago mejora la experiencia del pagador y reduce los índices de abandono del pagador.
Para realizar una autenticación sin pago, proporcione los siguientes campos en la solicitud Initiate Authentication:
- order.currency: cualquier moneda admitida en los vínculos de adquirente.
- authentication.purpose: indica el contexto en el que se solicita la autenticación del pagador. Puede especificar una de las siguientes opciones:
- ADD_CARD: la autenticación se realiza antes de que usted almacene directamente la tarjeta de un pagador en el archivo o de que la tarjeta se almacene mediante la característica de tokenización del motor de pagos. No se está procesando un pago.
- MAINTAIN_CARD: la autenticación se realiza antes de que usted directamente actualice los detalles de la tarjeta de un pagador en el archivo o de que la tarjeta se almacene mediante la característica de tokenización del motor de pagos. No se está procesando un pago.
Si el esquema de autenticación no es compatible con la finalidad que solicitó, el motor de pagos devuelve
AUTHENTICATION_NOT_SUPPORTEDen la respuesta. Tenga en cuenta que, de forma predeterminada, el motor de pagos establece este campo enPAYMENT_TRANSACTIONpara permitir que la autenticación se utilice para una transacción de pago.
Los negocios agregadores pueden habilitar a sus subnegocios para que utilicen la API de autenticación en el motor de pagos. Los subnegocios no están obligados a tener una relación contractual con el adquirente ni con el motor de pagos. El negocio agregador puede enviar los detalles del subnegocio necesarios para iniciar la autenticación a través de la operación Initiate Authentication. Para obtener más información, consulte Soporte del agregador.
La API de autenticación registra los detalles de la autenticación del pagador utilizando 3DS2 como transacción AUTHENTICATION en el pedido.
Cuando se recupera un pedido mediante la operación Retrieve Order o recibe una respuesta de API de Reporting, puede contener una transacción AUTHENTICATION adicional. Además, cuando se utilizan Notificaciones de webhook, puede recibir una notificación adicional para la transacción AUTHENTICATION.
Para obtener detalles sobre las transacciones AUTHENTICATION, consulte la lista de parámetros de respuesta para la operación Authenticate Payer.
Puede usar tokens de red para la autenticación del pagador desde <<webServicesIntegration>> v57 en adelante. QNB ALAHLI actualmente admite el procesamiento de tokens de red obtenidos de los siguientes proveedores de servicios de tokenización: Mastercard Digital Enablement Service (MDES), Visa Token Service (VTS).
Si obtuvo un token de red mediante la integración directa en el proveedor de servicios de tokenización de red, deberá proporcionar los detalles del token utilizando los siguientes campos:
sourceOfFunds.type=SCHEME_TOKEN: permite al motor de pagos identificar la fuente de fondos proporcionada en la solicitud como token de red. MDES y VTS son compatibles a partir de <<webServicesIntegration>> v51 y v53, respectivamente.sourceOfFunds.provided.card.number: el token de red. Proporcione el valor para el "PAN de token" de MDES o el "Token" de VTS.sourceOfFunds.provided.card.expiry: (opcional) el vencimiento del token de red.
Si su proveedor de servicios de pago le habilitó la tokenización de red, cualquier solicitud al motor de pagos para un token del motor de pagos también intentará generar un token de red correspondiente para los esquemas habilitados, cuando esto sea compatible con el emisor de la tarjeta. El motor de pagos también intentará la tokenización de red para cualquier tarjeta aplicable que ya esté almacenada en el depósito de tokens del motor de pagos. La solicitud Initiate Authentication utilizará el token de red si está disponible; de lo contrario, se utilizará el PAN de financiamiento (FPAN) almacenado en el token del motor de pagos. Este modelo actualmente solo admite tokens MDES.
Si utilizó una sesión de pago (ID de sesión) para almacenar los detalles de autenticación, la solicitud POST enviada por el explorador del pagador a su sitio web al completar la solicitud de Authenticate Payer se parametrizará para permitirle determinar el resultado de la autenticación. Los parámetros de autenticación individuales, por ejemplo, authentication.3ds2.transactionStatus.data, pueden resultar útiles en una integración avanzada o si tiene la necesidad de proporcionar los datos de autenticación en un pago procesado a través de otro motor de pagos. Para hacerlo, puede enviar una solicitud de Retrieve Transaction, o bien optar por descifrar los datos de autenticación cifrados (consulte los pasos siguientes):
- Cree una sesión mediante la operación Create Session.
- Agregue datos relevantes al ID de sesión (devuelto en la respuesta de Create Session) utilizando la solicitud Update Session.
- Utilice este ID de sesión en las solicitudes Initiate Authentication y Authenticate Payer.
- La redirección del explorador del pagador a su sitio web contendrá detalles de autenticación del pagador en el campo
encryptedData. Es un objeto JSON cifrado que contiene los datos de autenticación obtenidos durante el proceso de autenticación. Contiene los siguientes campos:encryptedData.ciphertextauthentication.3ds.acsEciauthentication.3ds.authenticationTokenauthentication.3ds.transactionIdauthentication.3ds1.veResEnrolledauthentication.3ds1.paResStatusauthentication.3ds2.transactionStatusauthentication.3ds2.dsTransactionIdtransaction.authenticationStatusauthentication.3ds2.statusReasonCodesourceOfFunds.provided.card.numbersourceOfFunds.provided.card.expiry.monthsourceOfFunds.provided.card.expiry.yearsourceOfFunds.tokenorder.idtransaction.idencryptedData.nonceencryptedData.tag
- Para descifrar el contenido devuelto en el campo encryptedData.ciphertext, utilice session.aes256Key (devuelto en la respuesta de Create Session) en el modo GCM. La clave codificada Base64 es secreta y solo usted debe conocerla.
public final class SessionDataDecrypter {
/**
* The algorithm used for encryption/decryption
*/
private static final String SYMMETRIC_ALGORITHM = "AES/GCM/NoPadding";
/**
* The algorithm to be associated with the secret key material
*/
private static final String SYMMETRIC_KEY_TYPE = "AES";
/**
* The secret key associated with the session, as returned in the session.aes256Key in a Create Session response.
*/
private final byte[] key;
/**
* Constructs a new object with the given key. The key is Base64 encoded, as returned in the session.aes256Key
* field in a Create Session response. This key must be kept secret, as it may be used to encrypt, decrypt and
* authenticate data for that session.
*
* @param encodedKey Key to be used for decryption.
*/
public SessionDataDecrypter(String encodedKey) {
key = Base64.getDecoder().decode(encodedKey);
}
/**
* Performs decryption of the given ciphertext, using the key passed in the constructor and the associated nonce.
* The tag is used to authenticate the ciphertext.
*
* @param ciphertext Encrypted and authenticated session data
* @param nonce Nonce/Initialization vector associated with the ciphertext
* @param tag Authentication tag
* @return The decrypted session data
* @throws AEADBadTagException if the data cannot be authenticated with the given tag
* @throws InvalidKeyException if the key cannot be constructed properly. This may indicate that it has not been
* correctly retrieved from the response field
* @throws GeneralSecurityException other than {@link AEADBadTagException} and {@link InvalidKeyException}, should
* not be thrown in a correctly set up environment
*/
public String decrypt(String ciphertext, String nonce, String tag)
throws GeneralSecurityException {
Key keySpec = new SecretKeySpec(key, SYMMETRIC_KEY_TYPE);
// The Java crypto classes expect the ciphertext and tag to be a single input, so they need to be concatenated
byte[] encryptedBytes = Base64.getDecoder().decode(ciphertext);
byte[] tagBytes = Base64.getDecoder().decode(tag);
byte[] input = new byte[encryptedBytes.length + tagBytes.length];
System.arraycopy(encryptedBytes, 0, input, 0, encryptedBytes.length);
System.arraycopy(tagBytes, 0, input, encryptedBytes.length, tagBytes.length);
// Configure the cipher with AES, using GCM parameter specifying the nonce/initialization vector
byte[] iv = Base64.getDecoder().decode(nonce);
GCMParameterSpec parameterSpec = new GCMParameterSpec(tagBytes.length * Byte.SIZE, iv);
final Cipher decrypter = Cipher.getInstance(SYMMETRIC_ALGORITHM);
decrypter.init(Cipher.DECRYPT_MODE, keySpec, parameterSpec);
// Perform the decryption and return the value.
byte[] decryptedBytes = decrypter.doFinal(input);
return new String(decryptedBytes, StandardCharsets.UTF_8);
}
}
La solicitud Authenticate Payer puede obtener un gran volumen de información sobre el pagador y la transacción. Por ejemplo, usted puede proporcionar los datos siguientes en la solicitud utilizando los campos del grupo de parámetros customer.account, lo que ayuda al ACS del emisor a evaluar el nivel de riesgo asociado con la actividad. Esto significa que, en el caso de pagos legítimos, ayuda al ACS a confirmar que el pagador probablemente sea en realidad el titular de la tarjeta.
- ¿El pagador está usando una cuenta existente?
customer.account.history.creationDate
- ¿Desde cuándo existe la cuenta?
customer.account.history.lastUpdatedcustomer.account.history.passwordLastChanged
- ¿Con qué frecuencia ha comprado el pagador con usted?
customer.account.history.addCardAttemptscustomer.account.history.annualActivitycustomer.account.history.recentActivitycustomer.account.history.shippingAddressDate
- ¿Le ha pedido estos artículos a usted anteriormente?
customer.account.history.issuerAuthentication.acsTransactionIdcustomer.account.history.issuerAuthentication.timecustomer.account.history.issuerAuthentication.type
- ¿Ha notado alguna actividad sospechosa (por ejemplo, intentos fallidos de inicio de sesión) en la cuenta?
customer.account.history.suspiciousActivitycustomer.account.authentication.methodcustomer.account.authentication.time
También puede proporcionar los siguientes campos recomendados para cada esquema de tarjeta en la solicitud Authenticate Payer. Tenga en cuenta que esta lista no es definitiva y puede estar sujeta a cambios.
| Campo | Mastercard | Visa | American Express | Notas |
|---|---|---|---|---|
| shipping.contact.email | - | - | Y | Obligatorio para calcular el riesgo del negocio |
| shipping.method | - | - | Y | Obligatorio para calcular el riesgo del negocio |
| order.valueTransfer.amount | - | - | Y | Obligatorio para calcular el riesgo del negocio. Aplicable solo a tarjetas de regalo. |
| order.valueTransfer.numberOfCards | - | - | Y | Obligatorio para calcular el riesgo del negocio. Aplicable solo a tarjetas de regalo. |
| order.valueTransfer.currency | - | - | Y | Obligatorio para calcular el riesgo del negocio. Aplicable solo a tarjetas de regalo. |
| order.supply.preorderAvailabilityDate | - | - | Y | Obligatorio para calcular el riesgo del negocio |
| order.supply.preorder | - | - | Y | Obligatorio para calcular el riesgo del negocio |
| order.supply.reorder | - | - | Y | Obligatorio para calcular el riesgo del negocio |
| order.valueTransfer.accountType | - | Y | - | Obligatorio para Visa y para otros esquemas en ciertos mercados (por ejemplo, Brasil). No es aplicable si order.valueTransfer.accountType=NOT_A_TRANSFER |
El motor de pagos proporciona el estado de autenticación en el campo transaction.authenticationStatus. Este campo puede devolver uno de los siguientes valores según la etapa de autenticación:
AUTHENTICATION_ATTEMPTED: se intentó la autenticación del pagador y se obtuvo una prueba de intento de autenticación.AUTHENTICATION_AVAILABLE: la autenticación del pagador está disponible para el método de pago proporcionado.AUTHENTICATION_FAILED: el pagador no se autenticó. No debe continuar con esta transacción.AUTHENTICATION_NOT_SUPPORTED: el método de autenticación solicitado no es compatible con este método de pago.AUTHENTICATION_NOT_IN_EFFECT: no hay información de autenticación asociada con esta transacción.AUTHENTICATION_PENDING: la autenticación del pagador está pendiente de completar un proceso de desafío.AUTHENTICATION_REJECTED: el emisor rechazó la solicitud de autenticación y le solicitó a usted que no intente la autorización de un pago.AUTHENTICATION_REQUIRED: se requiere autenticación del pagador para este pago, pero no se proporcionó.AUTHENTICATION_SUCCESSFUL: el pagador se autenticó exitosamente.AUTHENTICATION_UNAVAILABLE: el pagador no se pudo autenticar debido a un problema técnico o de otro tipo.
El período de validez de los datos de autenticación de pago puede depender de su caso de uso. Comuníquese con your payment service provider si necesita alguna aclaración.
Para usar transacciones recurrentes con autenticación, consulte Credencial en archivo, titular de la tarjeta y transacciones iniciadas por el negocio.
Puede usar tokens de pago mediante dispositivo para la autenticación del pagador, de <<webServicesIntegration>> v55 en adelante. Solo se admiten tokens de pago obtenidos del SDK de Google Pay. Puede proporcionar un token de pago cifrado o el "pan" obtenido de un token de pago descifrado para la autenticación del pagador. El motor de pagos solo acepta solicitudes de autenticación con FPAN, las solicitudes con DPAN rechazarán. Para proporcionar detalles de la tarjeta por medio del token de pago, proporcione el siguiente campo:
order.walletProvider=GOOGLE_PAYsourceOfFunds.provided.card.devicePayment.paymentToken: solo es aplicable si el motor de pagos descifra el token de pago. Es el token de pago cifrado obtenido del SDK de Google Pay.sourceOfFunds.provided.card.number: solo es aplicable si usted descifra el token de pago. El valor correspondiente a la clave JSON de Google Pay "pan".
Antes de iniciar la autenticación del pagador, puede obtener una cotización de tasa de conversión dinámica de moneda (DCC) del proveedor de DCC, mediante el envío de la solicitud Payment Options Inquiry.
Si el proveedor de DCC realizó una oferta, usted le hizo llegar esta oferta al pagador y el pagador la aceptó, debe incluir lo siguiente en la solicitud Initiate Authentication:
- currencyConversion.requestId como se devolvió en la respuesta de Payment Options Inquiry
- currencyConversion.uptake=ACCEPTED
Si el pagador rechazó la oferta, en la solicitud Initiate Authentication, indique:
- currencyConversion.requestId como se devolvió en la respuesta de Payment Options Inquiry
- currencyConversion.uptake=DECLINED
Si no se requiere DCC para esta transacción, envíe la solicitud Initiate Authentication con:
- currencyConversion.uptake=NOT_REQUIRED
Si está configurado para usar DCC y no proporciona currencyConversion.uptake en la solicitud Initiate Authentication, la respuesta de Initiate Authentication indica currencyConversion.uptake=NOT_REQUIRED.
Si el pagador acepta la oferta de DCC, el proceso de autenticación del pagador usa la moneda del pagador y el monto del pagador. En todos los demás casos, el proceso de autenticación del pagador utiliza el monto del pedido y la moneda del pedido.
Puede utilizar la información de DCC que se proporciona en la solicitud Initiate Authentication en la solicitud de pago posterior, haciendo referencia a la transacción de autenticación, es decir, authentication.transactionId. La información de DCC que se envió durante la autenticación del pagador se aplicará a su transacción de pago.
También puede optar por enviar la misma información de DCC para la autenticación, así como en la transacción de pago posterior.
Si la transacción de pago posterior, que hace referencia a la transacción de autenticación, contiene información de DCC diferente, se rechaza la transacción de pago.
- la autenticación del pagador que tenga como resultado el uso alternativo de 3DS1;
- las autenticaciones iniciadas por el negocio, incluida la actualización de la autenticación del pagador.
Referencia de API de DCC en Initiate Authentication[REST][NVP]