Desarrollador de OneSpan: Punto final de validación de transacciones

Hakim Aldaoub, 9 de Diciembre de 2020

OneSpan Developer: Transaction Validation Endpoint

OneSpan Intelligent Adaptive Authentication (IAA) ofrece el punto final de Validación de Transacciones para manejar los eventos monetarios de manera adaptativa. Cada vez que se lanza una solicitud hacia Transactions/Validate API, Risk Analytics (RA) responderá para capturar el método de autenticación apropiado del usuario final, basado en el riesgo asociado a la transacción. En el blog de hoy, explicaremos cómo preparar la solicitud de una transacción monetaria utilizando la API interactiva del Sandbox y mostraremos las posibles respuestas de RA a ese evento

Antes de empezar

Antes de explorar el punto final de Validación de Transacciones, primero debe ser miembro de la Comunidad OneSpan y registrarse para obtener una cuenta gratuita de sandbox de Autenticación Adaptativa Inteligente, aquí hay instrucciones paso a paso sobre cómo hacerlo.

También debes asegurarte de tener al menos un usuario registrado antes de intentar esta llamada. Para saber cómo registrar un usuario, consulte este blog detallado sobre el registro de usuarios.

URL del punto final

La URL de solicitud para esta llamada a la API se parecerá al ejemplo siguiente:

https://{su_identificación_de_arrendatario}.sdb.tid.onespan.cloud/v1/usuarios/{identificación de [email protected]}/transacciones/validación

No necesitarás proporcionar esta URL durante el tutorial. Es sólo para mostrar la estructura de la URL. La URL se asignará automáticamente en la API interactiva cuando se llame al servicio web

Pruébalo

Para experimentar con la API de Validación de Transacciones, navegue hasta el documento de la API Interactiva IAA Sandbox en su cuenta de la Comunidad OneSpan. En el editor de Open API Swagger, expanda el recurso "Transacciones". A continuación, encontrará una entrada para el método Transactions/Validate HTTP Post como se muestra en la imagen siguiente

Parámetros de la ruta URL:

A efectos de la llamada a la API de Transacción/Validación, hay un parámetro de ruta requerido para el identificador único de usuario. Se formateará como [email protected] Un ejemplo de userID es "iaa_user". Es el ID de usuario que se ha activado en el dispositivo de confianza. La parte del parámetro que sigue al signo "@" es el dominio del usuario. Esta entrada debe sustituirse por la cadena "Usuario del entorno de pruebas" que se muestra a continuación, que está presente en la sección de detalles del entorno de pruebas en la pestaña "Autenticación adaptativa inteligente" de la página de inicio del entorno de pruebas.

Cuerpo de la solicitud de validación de la transacción

En la sección "Request Body" del endpoint Transaction/Validate, seleccione el tipo de objeto "AdaptiveTransactionValidationInput" en el menú desplegable como se muestra a continuación. A continuación, obtendrá un ejemplo de la carga útil de la solicitud JSON requerida por el punto final de validación de transacciones

El cuerpo de la solicitud se parecerá al ejemplo siguiente de los campos obligatorios del punto final Transaction/Validate.

{ "objectType": "AdaptiveTransactionValidationInput", "accountRef": "ACC123", "amount": "1064.99", "cddc": { "browserCDDC": { "fingerprintRaw": "{browser:{\"userAgent\":Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36},support:{\"ajax\":true,\"boxModel\":undefined,\"changeBubbles\":undefined,\"checkClone\":true,\"checkOn\":true,\"cors\":true,\"cssFloat\":undefined,\"hrefNormalized\":undefined,\"htmlSerialize\":undefined,\"leadingWhitespace\":undefined,\"noCloneChecked\":true,\"noCloneEvent\":undefined,\"opacity\":undefined,\"optDisabled\":undefined,\"style\":undefined,\"submitBubbles\":undefined,\"tbody\":undefined},computer:{\"screenWidth\":2560,\"screenHeight\":1440,\"OS\":\"Microsoft Windows\",\"platform\":\"Win32\"},additional:{}}", "fingerprintHash": "e96dadc9651f5fe8f071110eb174fe8e7a17a9d7a96b3b1980c13e5b4af3a4d7" } }, "currency": "EUR", "data": { "transactionMessage": { "dataFields": [

Solicitud de carga útil

Contiene dos objetos JSON obligatorios que se muestran en la tabla:

Campos de datos obligatorios JSON	Descripción	Campo Tipo de datos
objetoTipo*	Esto es para declarar el tipo de objeto para la transacción en la carga útil de la solicitud es para el propósito de la solución de Autenticación Adaptativa Inteligente.	Tipo: Enum Ejemplo: "[ AdaptiveTransactionValidationInput]"
cuentaRef*	Referencia a la cuenta bancaria del cliente que realiza la transacción	Tipo: objeto anidado JSON minLength: 1 maxLength: 250 Ejemplo: Checking_Account_CH53
cantidad*	El valor del importe de la transacción	Tipo: cadena patrón: ^-?[0-9]{1,10}(\.[0-9]{1,2})?$ ejemplo: 999.99
cddc*	Metadatos del recolector de datos del dispositivo del cliente. Los dos campos browserCDDC y mobileCDDC son mutuamente excluyentes y colectivamente exhaustivos.	Tipo: cadena Ejemplo: "browserCDDC" o "mobileCDDC"
relaciónRef*	La referencia de la relación del ID del usuario.	Tipo: cadena minLength: 1 maxLength: 150 Ejemplo: iaa_user
staticPassword*	La contraseña estática inicial asignada al usuario.	Tipo: cadena minLength: 8 maxLength: 255 ejemplo: Test1234
sessionID*	Identificador de sesión de la aplicación formateado como una cadena hexadecimal; común para todas las transacciones relacionadas con la misma sesión	Tipo: cadena patrón: ^[0-9a-fA-F]+$ minLength: 2 maxLength: 100 ejemplo: 4ed23ea44f23
transactionType*	Este campo crucial especifica el tipo de transacción que se enviará en la solicitud. La definición del tipo de transacción permitirá la flexibilidad para que las diferentes transacciones se manejen de manera única desde el lado de Risk Analytics	Tipo: cadena Ejemplo: ExternalTransferBillPayments, MobileInternalTransfer

Llamada al punto final

Llegados a este punto, estamos preparados para realizar una llamada RESTful al punto final de Transacción/Validación utilizando la API interactiva del Sandbox de la IAA. Para realizar la llamada, haga clic en el botón "Probar" que se muestra en la siguiente captura de pantalla y que se encuentra a la derecha de la sección del método HTTP POST. Una vez solicitado, recibirá el cuerpo de la respuesta en formato JSON. Será similar a la carga útil de respuesta descrita en la siguiente sección.

Carga útil de la respuesta

A continuación se muestra un ejemplo del cuerpo de respuesta devuelto con un código de respuesta 200 que indica una transacción exitosa.

{"requestID": "413b2c39-2d67-4293-9adb-25601731b062", "riskResponseCode": 0, "sessionStatus": "accepted", "requestMessage": "0000F8B81D" }

Descripción de los campos del cuerpo de la respuesta

El "requestID" es el primer campo de la respuesta, es una cadena de 36 caracteres que se utiliza para mantener una referencia de la llamada anterior a la API. Este ID podría ser útil para depurar y referenciar.

El campo "riskResponseCode" es el código de respuesta de Risk Analytics. El valor "0" en la respuesta anterior indica que la solicitud fue aceptada y el usuario se autenticó con éxito sin necesidad de tomar medidas adicionales. A continuación se muestra una lista de otros posibles valores que puede devolver Risk Analytics. Además, se pueden configurar valores adicionales a través del Servicio de Presentación de Análisis de Riesgos.

Comportamiento del análisis de riesgos	Código de respuesta al riesgo (entero)
Aceptar	0
Declinación	1
Desafío	2
DesafíoSMS	3
DesafíoDispositivo2FA	5
DesafíoCorreo electrónico	8
DesafíoCronto	11
ChallengeNoPIN	21
ChallengePIN	22
DesafíoHuellas dactilares	23
ChallengeFace	24

El campo "sessionStatus" en la respuesta JSON representa el estado actual de la sesión tras el envío de la solicitud, la tabla siguiente lista los posibles valores de estado.

Estado de la sesión	Descripción del estado
desconocido	El estado es desconocido y la respuesta se está gestionando externamente
pendiente	A la espera de una acción del usuario final
aceptado	Completado con éxito
rechazado	Rechazado por el usuario final
tiempo de espera	Se ha agotado el tiempo tras no recibirse ninguna respuesta en el plazo establecido
falló	El fallo de validación de la OTP

El campo "requestMessage" es de tipo String. Se utiliza para transmitir un comando de orquestación al dispositivo de confianza del usuario final.

En este blog, cubrimos cómo hacer una transacción monetaria a través de la API de OneSpan Interactive. En las próximas semanas, veremos otros blogs relacionados con el punto final Transaction/Validate. Mientras tanto, si tiene alguna pregunta, no dude en ponerse en contacto con nosotros en los foros del portal de la comunidad de OneSpan.

OneSpan Blog