Servicio para iniciar una sesión en el flujo de autenticación de 3DS Server.

Los siguientes pasos le darán una guía en la utilización del mismo:

1. Cree una solicitud HTTP de tipo POST en su servidor y con el endpoint /sessions

2. En el encabezado de la petición, ingrese el bearer token, el cual le permitirá registrarse como un usuario autorizado. Este encabezado es obligatorio.

3. El encabezado deberá contener también, en el Content-Type, el valor de "application/json".

4. Ingrese en el cuerpo de la petición los campos mínimos requeridos, los cuales son:

acctNumber
cardExpiryDate
purchaseAmount
redirectURI
purchaseCurrency

La descripción de los campos de las peticiones y de las respuestas, el tipo de dato, longitud y demás especificaciones, puede visualizarse en el apartado de respuestas, en el esquema de datos.

5. Envíe la petición y obtenga una respuesta.

6. Puede visualizar el estado de la autenticación, redirigiéndose a la "redirectURI", dato arrojado en una respuesta exitosa o con estado "Y".

Para obtener estados en la autenticación diferentes al "Y", puede modificar el campo "acctNumber" de la petición, con los números de tarjetas de prueba dados en esta documentación.

Implementación del Contrato v2x

Se recomienda la implementación de un nuevo contrato que proporciona el siguiente conjunto de resultados:

Canal	Indicador del Canal	Acción	Categoría de Mensaje	Información
APP	“01”	continue	PA, NPA	Esta nueva acción permite retornar el resultado de la transacción y no necesita intervención del usuario para ser completada.
BRW	“02”	redirect	PA, NPA	Esta acción se ejecuta en los flujos para dispositivos BRW, en el cual retornamos una URL `redirectURL`, para iniciar el flujo de autenticación.
3RI	“03”	continue	PA, NPA	Esta nueva acción permite retornar el resultado de la transacción y no necesita intervención del usuario para ser completada.

Para más detalles sobre la acción "redirect" y su implementación, puedes consultar la documentación específica del flujo de autenticación de BRW.

Mejora la tasa de autenticaciones con datos adicionales

Nos complace invitarles a visitar el apartado de Adicional Data en nuestra documentación del API. Este apartado ofrece información crucial para optimizar el proceso de autenticación 3DS.

La inclusión de estos datos adicionales en sus solicitudes permite a los emisores realizar una evaluación más precisa, lo que puede mejorar considerablemente la tasa de autenticaciones exitosas.

Les recomendamos revisar estas pautas para aprovechar al máximo las funcionalidades del API y así ofrecer una experiencia más segura y eficiente a sus usuarios.

Para el flujo 3RI, se devuelve el mismo contrato de respuesta que en el Show Transaction de la versión 2.x. Valores devueltos en la respuesta API

POST/threeds/v2x/sessions

Crear una sesión BRW o RI

Este endpoint te permite crear una nueva sesión para la autenticación del titular de la tarjeta.

Solicitud

Name
acctNumber
Type
string
is Required
REQUIRED
Description
Número de cuenta que se utilizará en la solicitud de autorización para transacciones de pago. Debe pasar la validación del Algoritmo de Luhn Valores aceptados: Ver formato ISO 7812
Ejemplo:4005580000000040
Longitud máxima:19
Longitud mínima:13
Name
cardExpiryDate
Type
string
is Required
REQUIRED
Description
Fecha de vencimiento de la tarjeta suministrado por el titular. Formato: ym Ejemplo: 2506
Ejemplo:2506
Longitud máxima:4
Longitud mínima:4
Name
purchaseAmount
Type
string
is Required
REQUIRED
Description
Monto de la transacción. Ejemplo: 20.5
Ejemplo:20.5
Name
purchaseCurrency
Type
string
is Required
REQUIRED
Description
El código alfabético de 3 letras de la moneda en la que se expresa el monto de la compra Valores: Ver formato ISO 4217
Ejemplo:USD
Longitud máxima:3
Longitud mínima:3
Name
redirectURI
Type
string
is Required
REQUIRED
Description
URL del sistema donde el titular de la tarjeta será redirigido después de completar una transacción de autenticación.
Ejemplo:https://www.placetopay.com
Formato:uri
Longitud máxima:256
Name
threeDSAuthenticationInd
Type
string
is optional
Description
Indica el tipo de solicitud de autenticación. Valores:
- PAYMENT_TRANSACTION (01) - Transacción de pago
- RECURRING_TRANSACTION (02) - Transacción recurrente
- INSTALMENT_TRANSACTION (03) - Transacción a plazos
- ADD_CARD (04) - Agregar una tarjeta
- MAINTAIN_CARD (05) - Mantener una tarjeta
- CARDHOLDER_VERIFICATION_AS_PART_OF_EMV_TOKEN_IDV (06) - Verificación del tarjetahabiente como parte del EMV token ID&V
- BILLING_AGREEMENT (07) - Acuerdo de facturación
- MASTERCARD_THE_PAYMENT_REQUEST_IS_FOR_AN_AGENT_PAYMENT_TRANSACTION (85) - Transacción de pago de agente para Mastercard
- MASTERCARD_FOR_UNKNOWN_OR_UNDEFINED_FINAL_AMOUNT_BEFORE_PURCHASE_TRANSACTION (86) - Transacción para Mastercard con monto final desconocido o indefinido antes de la compra
Ejemplo:01
Longitud máxima:2
Longitud mínima:2
Name
reference
Type
string
is optional
Description
Referencia de la transacción.
Longitud máxima:32
Name
recurringFrequency
Type
string
is optional
Description
Indica el número mínimo de días entre autorizaciones. Requerido sí threeDSAuthenticationInd es igual a RECURRING_TRANSACTION (02) o INSTALMENT_TRANSACTION (03) Debe estar presente siempre que se envíe recurringExpiry Ejemplos de valores: 31, 031, 0031
Longitud máxima:4
Longitud mínima:1
Name
recurringExpiry
Type
string
is optional
Description
Fecha después de la cual no se realizarán más autorizaciones. Requerido sí threeDSAuthenticationInd es igual a RECURRING_TRANSACTION (02) o INSTALMENT_TRANSACTION (03) Debe estar presente siempre que se envíe recurringFrequency Formato: Ymd Ejemplo: 20250601
Longitud máxima:8
Longitud mínima:8
Name
purchaseInstalData
Type
string
is optional
Description
Indica el número máximo de autorizaciones permitidas para pagos a plazos. El valor debe ser mayor que 1. Se requiere sí el comerciante y el titular de la tarjeta han acordado pagos a plazos, es decir, si threeDSAuthenticationInd = 03. Se omite sí no se trata de una autenticación de pago a plazos. Ejemplos de valores: 2, 02, 002
Longitud máxima:3
Longitud mínima:1
Name
threeDSAuthenticationInfo
Type
threeDSAuthenticationInfo
is optional
Description
Información sobre cómo el 3DS Requestor autenticó al titular de la tarjeta antes o durante la transacción.
Name
threeDSChallengeInd
Type
string
is optional
Description
Indica si se solicita un desafío para esta transacción. Si este parámetro no se envía en la petición, se asumirá NO_PREFERENCE (01) como valor por defecto. Valores:
- NO_PREFERENCE (01) - Sin preferencia
- NO_CHALLENGE_REQUESTED (02) - No se solicitó desafío
- CHALLENGE_REQUESTED_REQUESTOR_PREFERENCE (03) - Desafío solicitado (preferencia del solicitante)
- CHALLENGE_REQUESTED_MANDATE (04) - Desafío solicitado (mandato)
- NO_CHALLENGE_REQUESTED_RISK_PERFORMED (05) - No se solicitó desafío (análisis de riesgo realizado)
- NO_CHALLENGE_REQUESTED_DATA_SHARED_ONLY (06) - No se solicitó desafío (solo datos compartidos)
- NO_CHALLENGE_REQUESTED_CONSUMER_AUTH_PERFORMED (07) - No se solicitó desafío (autenticación del consumidor realizada)
- NO_CHALLENGE_REQUESTED_WHITELIST_EXEMPTION (08) - No se solicitó desafío (exención de lista blanca)
- NO_CHALLENGE_REQUESTED_WHITELIST_PROMPT_REQUESTED (09) - No se solicitó desafío (solicitud de lista blanca)
- VISA_RESERVED (82) - Reservado para VISA
Longitud máxima:2
Longitud mínima:2
Name
threeDSRequestorID
Type
string
is optional
Description
Identificador asociado por el DS al Solicitante 3DS. Cada Directory Server puede imponer requisitos específicos de formato y caracteres en el contenido de este campo.
Longitud máxima:35
Name
acctInfo
Type
acctInfo
is optional
Description
Información adicional sobre la cuenta del titular de la tarjeta.
Name
acctID
Type
string
is optional
Description
Información adicional sobre la cuenta proporcionada por 3DS Requestor.
Longitud máxima:64
Name
billAddrCity
Type
string
is optional
Description
El nombre de la ciudad de la dirección de facturación del Titular de la tarjeta asociada con la tarjeta utilizada para esta compra.
Longitud máxima:50
Name
billAddrCountry
Type
string
is optional
Description
El código alfabético de tres letras que relaciona al país de la dirección de facturación del Titular de la tarjeta asociada con la tarjeta utilizada para esta compra. Valores aceptados: Ver formato ISO 3166-1
Longitud máxima:3
Name
billAddrLine1
Type
string
is optional
Description
Primera línea de la dirección postal o parte local equivalente de la dirección de facturación del titular de la tarjeta asociada con la tarjeta utilizada para esta compra.
Longitud máxima:50
Name
billAddrLine2
Type
string
is optional
Description
Segunda línea de la dirección postal o parte local equivalente de la dirección de facturación del titular de la tarjeta asociada con la tarjeta utilizada para esta compra.
Longitud máxima:50
Name
billAddrLine3
Type
string
is optional
Description
Tercera línea de la dirección postal o parte local equivalente de la dirección de facturación del titular de la tarjeta asociada con la tarjeta utilizada para esta compra.
Longitud máxima:50
Name
billAddrPostCode
Type
string
is optional
Description
ZIP u otro código postal de la dirección de facturación del titular de la tarjeta asociada con la tarjeta utilizada para esta compra.
Longitud máxima:16
Name
billAddrState
Type
string
is optional
Description
Código alfabético de 3 letras de la subdivisión del país que representa el estado o provincia de la dirección de facturación del titular de la tarjeta asociada con la tarjeta utilizada para esta compra. Valores: Ver formato ISO 3166-2
Longitud máxima:3
Name
email
Type
string
is optional
Description
La dirección de correo electrónico asociada con la cuenta que ingresó el Titular de la tarjeta o que está archivada con el Solicitante de 3DS.
Formato:email
Longitud máxima:254
Name
homePhone
Type
PhoneProperties
is optional
Description
Valores aceptados según especificación Ver formato ITU-E.164
Name
mobilePhone
Type
PhoneProperties
is optional
Description
Valores aceptados según especificación Ver formato ITU-E.164
Name
cardholderName
Type
string
is optional
Description
Nombre del titular de la tarjeta.
Longitud máxima:45
Longitud mínima:2
Name
shipAddrCity
Type
string
is optional
Description
Nombre completo o parcial de la ciudad de la dirección de envío proporcionado por el titular de la tarjeta.
Longitud máxima:50
Name
shipAddrCountry
Type
string
is optional
Description
El código alfabético de tres letras que relaciona al país de la dirección de envío proporcionado por el Titular de la tarjeta. Valores: Ver formato ISO 3166-1
Longitud máxima:3
Longitud mínima:3
Name
shipAddrLine1
Type
string
is optional
Description
Primera línea de la dirección postal o parte local equivalente de la dirección de envío proporcionado por el titular de la tarjeta.
Longitud máxima:50
Name
shipAddrLine2
Type
string
is optional
Description
Segunda línea de la dirección postal o parte local equivalente de la dirección de envío proporcionado por el titular de la tarjeta.
Longitud máxima:50
Name
shipAddrLine3
Type
string
is optional
Description
Tercera línea de la dirección postal o parte local equivalente de la dirección de envío proporcionado por el titular de la tarjeta.
Longitud máxima:50
Name
shipAddrPostCode
Type
string
is optional
Description
ZIP u otro código postal de la dirección de envío proporcionado por el titular de la tarjeta
Longitud máxima:16
Name
shipAddrState
Type
string
is optional
Description
Código alfabético de 3 letras de la subdivisión del país que representa el estado o provincia de la dirección de envío proporcionado por el titular de la tarjeta. Valores: Ver formato ISO 3166-2
Longitud máxima:3
Name
workPhone
Type
PhoneProperties
is optional
Description
Valores aceptados según especificación Ver formato ITU-E.164
Name
merchantRiskIndicator
Type
merchantRiskIndicator
is optional
Description
Evaluación del comerciante sobre el nivel de riesgo de fraude en la autenticación específica.
Name
addPriorInformation
Type
string
is optional
Description
Indica el tipo de solicitud de autenticación.

Valores:
- Y - Solicita a 3DSS Agregar información del PRIOR
- N - Solicita No Agregar información del PRIOR
Ejemplo:Y
Longitud máxima:1
Longitud mínima:1
Name
threeDSRequestorPriorAuthenticationInfo
Type
threeDSRequestorPriorAuthenticationInfo
is optional
Description
Información sobre cómo el 3DS Requestor autenticó al titular de la tarjeta antes o durante la transacción.
Name
threeDSReqPriorAuthMethod
Type
string
is optional
Description
Método que fue usado por el tarjetahabiente para la autenticación previa. Valores:
- FRICTIONLESS_AUTHENTICATION (01) sin fricción
- CARDHOLDER_CHALLENGE_OCCURRED (02) con fricción
Ejemplo:FRICTIONLESS_AUTHENTICATION
Name
threeDSReqPriorAuthTimestamp
Type
string
is optional
Description
Fecha y hora en formato UTC de la autenticación previa. El formato es C, por ejemplo 2024-07-15T10:00:00Z.
Ejemplo:2024-07-15T10:00:00Z
Name
threeDSReqPriorRef
Type
string
is optional
Description
El ID otorgado por el ACS en la transacción previa (primera autenticación).
Ejemplo:abc123
Name
threeDSReqPriorAuthData
Type
string
is optional
Description
El ID otorgado por el DS en la transacción previa (primera autenticación). Si este dato no es enviado, 3DSS lo asigna. Consulta la sesión
Ejemplo:xyz789
Name
threeRIInd
Type
string
is optional
Description
Indica si la transacción es recurrente. Valores:
- RECURRING_TRANSACTION (01) - Transacción recurrente
- INSTALMENT_TRANSACTION (02) - Transacción a plazos
- ADD_CARD (03) - Agregar tarjeta
- MAINTAIN_CARD_INFORMATION (04) - Mantener información de tarjeta
- ACCOUNT_VERIFICATION (05) - Verificación de cuenta
- SPLIT_OR_DELAYED_SHIPMENT (06) - Envío dividido o retrasado
- TOP_UP (07) - Recarga
- MAIL_ORDER (08) - Pedido por correo
- TELEPHONE_ORDER (09) - Pedido por teléfono
- WHITELIST_STATUS_CHECK (10) - Verificación del estado de la lista blanca
- OTHER_PAYMENT (11) - Otro tipo de pago
- BILLING_AGREEMENT (12) - Acuerdo de facturación
- MASTERCARD_3RI_IS_FOR_AN_AGENT_PAYMENT_TRANSACTION (85) - Transacción de pago de agente para Mastercard
- MASTERCARD_3RI_FOR_UNKNOWN_OR_UNDEFINED_FINAL_AMOUNT_BEFORE_PURCHASE_TRANSACTION (86) - Transacción para Mastercard con monto final desconocido o indefinido antes de la compra
- VISA_UNSCHEDULED_CREDENTIAL_ON_FILE (81) - Credencial no programada en archivo (Visa)

Solicitud

POST

/threeds/v2x/sessions

curl -X "POST" https://3dss-test.placetopay.com/threeds/v2x/sessions \
-H "Content-Type: application/json" \
-d '{
     "acctNumber": "4005580000000040",
     "cardExpiryDate": "2506",
     "purchaseAmount": "20.5",
     "purchaseCurrency": "USD",
     "redirectURI": "https://www.placetopay.com",
     "threeDSAuthenticationInd": "PAYMENT_TRANSACTION",
     "reference": "12345"
  }'

Respuesta

Respuesta recibida: 200 Ok

Para continuar con el proceso de autenticación, se debe redirigir al usuario a la url recibida en el campo (redirectURL). Allí se le informará el resultado de la autenticación y posteriormente, se redirigirá al comercio.

Name
sessionToken
Type
string
is Required
REQUIRED
Description
Token de autenticación.
Ejemplo:8e580eb1948ae1b13e614aac04c75ad31d6431ef2ea7b1a85573979b7ec4e656
Longitud máxima:64
Longitud mínima:64
Name
redirectURL
Type
string
is Required
REQUIRED
Description
URL de redirección para continuar el proceso de autenticación.
Ejemplo:https://3dss-test.placetopay.com/threeds/v2x/sessions/8e580eb1948ae1b13e614aac04c75ad31d6431ef2ea7b1a85573979b7ec4e656
Longitud máxima:256
Longitud mínima:1
Name
transactionID
Type
integer
is Required
REQUIRED
Description
Indicador de la transacción.
Ejemplo:9099

Respuesta

{
  "action":"redirect",
  "sessionToken": "8e580eb1948ae1b13e614aac04c75ad31d6431ef2ea7b1a85573979b7ec4e656",
  "redirectURL": "https://3dss-test.placetopay.com/threeds/v2x/sessions/8e580eb1948ae1b13e614aac04c75ad31d6431ef2ea7b1a85573979b7ec4e656",
  "transactionID": 9099
}