Servicio de autentificación
Una vez creada la transacción, debe llamar al servicio de autenticación para continuar el flujo. Si se devuelve el estado AUC, debe iniciarse una impugnación. Para el estado AUD, se debe seguir el flujo "desacoplado". En todos los demás casos, no es necesario realizar más llamadas.
Detalles de la llamada#
- Recurso:
/v2/authentication/{ID da transação 3DS Server} - Método HTTP:
PUT - Formato de la solicitud:
JSON - Formato de la resposta:
JSON - Parámetros de encabezado:
| Parámetro | Descripción | Formato | Obligatorio |
|---|---|---|---|
merchant_id | Código de la tienda en el 3DS Server. Los códigos de producción y certificación serán diferentes. | < 15 AN | SI |
merchant_key | Clave de autentificación de la tienda en el 3DS Server. Las claves de produción y certificación seran diferentes. | < 80 AN | SI |
Content-Type | Debe ser enviado con el valor application/json. | = 15 AN | SI |
carat_merchant_id | El código de la tienda Carat debe enviarse solo si el campo token se envía en la solicitud | < 15 AN | COND. |
carat_merchant_key | La clave de autenticación de la tienda Carat debe enviarse solo si el campo token se envía en la solicitud | < 80 AN | COND. |
Ejemplos#
A continuación estan algunos ejemplos de llamada al servicio de autentificación utilizando la herramienta cURL.
Flujo Frictionless#
Solicitud con número de tarjeta:
Para usar este ejemplo, no olvide definir la variable {{url}} con el valor
esitef-homologacao.softwareexpress.com.br
Respuesta:
Solicitud con token:
Para usar este ejemplo, no olvide definir la variable {{url}} con el valor
esitef-homologacao.softwareexpress.com.br
Respuesta:
Flujo Challenge#
Solicitud:
Para usar este ejemplo, no olvide definir la variable {{url}} con el valor
esitef-homologacao.softwareexpress.com.br
Respuesta:
Respuesta:
Parámetros de solicitud#
En la siguiente tabla está la descripción de los parámetros de solicitud del servicio de autentificación:
| Parámetro | Descripción | Formato | Obligatorio |
|---|---|---|---|
device_channel | Canal de dispositivos. Valor estandar 02corresponde a Navegador (BRW). Más información | = 2 N | NO |
three_ri_ind | Indica el tipo de solicitud 3RI.
device_channel = 03. | = 2 N | COND. |
three_ds_comp_ind | Indica se el 3DS Method fue ejecutado con éxito.
device_channel = 02. | = 1 A | COND. |
pay_token_ind | El valor true indica que la transacción fue "destokenizada" antes de recibir del ACS. | < 5 AN | NO |
pay_token_source | Indica donde se produjo la "destokenização".
| = 2 N | NO |
notification_url | URL completa del 3DS Requestor para recibir la mensaje CRes. Campo obligatorio para device_channel = 02. | < 256 AN | COND. |
trans_type | Identifica el tipo de transacción siendo autentificada.
| = 2 N | SI |
broad_info | Información no-estructurada enviada entre 3DS Server, DS e ACS. | Object | NO |
| three_ds_requestor | |||
authentication_ind | Indica el tipo de solicitud de autentificación.
| = 2 N | SI |
challenge_ind | Este campo señala la preferencia del comercio para llevar a cabo (o no) el desafío, pero a menos que las partes estén alineadas, el emisor puede optar por no cumplir con esta solicitud. En caso de que este campo no sea enviado, se interpretará como "01 = Sin preferencia".
| = 2 N | NÃO |
id | Identificador del 3DS Requestor designado por el DS. | < 35 AN | SI |
name | Nombre del 3DS Requestor designado por el DS. | < 40 AN | SI |
url | URL completa del sitio web del solicitante de 3DS o del sitio web del servicio de atención al cliente. | < 2048 AN | SI |
| three_ds_requestor. authentication_info | Información sobre cómo el 3DS Requestor autentificó al titular de la tarjeta antes o durante la transacción. | ||
data | Datos que documentan y ayudan a un proceso de autentificación específico. | < 20000 AN | NO |
method | Mecanismo utilizado por el titular de la tarjeta para autenticarse en el 3DS Requestor.
| = 2 N | NO |
timestamp | Fech e hora UTC de la autentificación del titular en formato AAAAMMDDHHMM. | = 12 N | NO |
| three_ds_requestor. prior_authentication_info | Información sobre cómo el solicitante 3DS autenticó al titular de la tarjeta como parte de una transacción 3DS anterior. | ||
data | Dato que documenta y asiste a un proceso de autentificación específico. | < 2048 AN | NO |
method | Mecanismo utilizado previamente por el portador para autenticarse en el 3DS Requestor.
| = 2 N | NO |
timestamp | Fecha y hora UTC de la aunteificación de autentificación previa del titular en formato AAAAMMDDHHMM. | = 12 N | NO |
reference | Este elemento proporciona información adicional para que el ACS determine la mejor manera de gestionar una solicitud. | < 36 AN | NO |
| acquirer | |||
bin | Código de la red adquirente según la definición de la DS. | < 11 AN | SI |
merchant_id | Identificador de la tienda asignado por el comprador. | < 35 AN | SI |
| browser | Estos parámetros son obligatorios si device_channel = 02. | ||
accept_header | Contenido exacto de la cabecera HTTP "Accept" tal y como lo envía el navegador del comprador al solicitante de 3DS. | < 2048 AN | COND. |
ip | Dirección IP del comprador. | < 45 AN | COND. |
java_enabled | Valor booleano que representa la capacidad del navegador del comprador para ejecutar Java.Este valor es devuelto por la propiedad navigator.javaEnabled. | < 5 AN | COND. |
javascript_enabled | Valor booleano que representa la capacidad del navegador del portador para ejecutar JavaScript. | < 5 AN | COND. |
language | Valor que representa el lenguaje del navegador tal y como se define en IETF BCP47. Devuelto por la propiedad navigator.language. | < 8 AN | COND. |
color_depth | Valor que representa la cantidad de bits de color para la visualización de imágenes, en bits por píxel. Valor obtenido por la propiedad screen.colorDepth.
Ejemplo: 30 se elegirá como 24. | < 2 N | COND. |
screen_height | Altura de la pantalla del titular. Valor devuelto por la propiedad screen.height. | < 6 N | COND. |
screen_width | Longitud de la pantalla del portador. Valor devuelto por la propiedad screen.width. | < 6 AN | COND. |
tz | Huso horario en minutos entre UTC y la hora del navegador del comprador. Valor devuelto por el método getTimezoneOffset(). | < 5 AN | COND. |
user_agent | User agent do comprador. | < 2048 AN | COND. |
| cardholder | |||
card_expiry_date | Fecha de caducidad de la tarjeta en el formato YAMM. | = 4 N | SI |
addr_match | Indica si la dirección de entrega y de facturación del portador son las mismas.
| = 1 AN | NO |
email | Aunque no es obligatorio, se recomienda enviar este campo, ya que ayuda en la evaluación de riesgos, aumentando las posibilidades de obtener una autenticación silenciosa. | < 256 AN | SI |
name | Nombre del titular. | < 45 AN | SI |
| cardholder. home_phone | Número de teléfono del domicilio del titular. | ||
cc | DDI | < 3 N | SI |
subscriber | DDD + Teléfono | < 15 N | SI |
| cardholder. mobile_phone | Es recomendable enviar este campo, ya que contribuye a la evaluación de riesgos, aumentando las posibilidades de obtener una autenticación silenciosa. | ||
cc | DDI | < 3 N | SI |
subscriber | DDD + Teléfono | < 15 N | SIM |
| cardholder. work_phone | Número de telefono comercial del titular. | ||
cc | DDI | < 3 N | SI |
subscriber | DDD + Teléfono | < 15 N | SI |
| cardholder. acct | |||
type | Indica el tipo de cuenta. Por ejemplo, para una tarjeta múltiple.
| = 2 N | SI |
number | Número de tarjeta del comprador, el campo number o token siempre debe enviarse en la solicitud | < 19 N | COND |
token | HASH de una tarjeta almacenada en Carat, siempre se debe enviar el campo number o token en la solicitud | = 88 AN | COND |
id | Información adicional de la cuenta proporcionada opcionalmente por el 3DS Requestor. | < 64 AN | NO |
| cardholder. acct. info | |||
ch_acc_age_ind | Periodo de tiempo que el titular ha tenido una cuenta con 3DS Requestor.
| = 2 N | NO |
ch_acc_change | Fecha de la última modificación de la cuenta del comprador en el formato "AAAAMMDD". | = 8 N | NO |
ch_acc_change_ind | Periodo de tiempo desde el último cambio en la cuenta del portador.
| = 2 N | NO |
ch_acc_date | Fecha en que el titular de la tarjeta abrió la cuenta en 3DS Requestor en el formato AAAAMMDD. | = 8 N | NÃO |
ch_acc_pw_change | Data em que o comprador alterou sua senha no formato AAAAMMDD. | = 8 N | NO |
ch_acc_pw_change_ind | Indica el período de tiempo transcurrido desde el último cambio de contraseña del titular.
| = 2 N | NO |
nb_purchase_account | Número de compras con esta cuenta durante los últimos 6 meses. | < 4 N | NO |
provision_attempts_day | Número de tentativas de adición de tarjetas en las últimas 24 horas. | < 3 N | NO |
txn_activity_day | Número de transacciones (confirmadas y abandonadas) para este titular de tarjeta con 3DS Requestor en las últimas 24 horas. | < 3 N | NO |
txn_activity_year | Número de transacciones (confirmadas y abandonadas) para este titular de la tarjeta con 3DS Requestor en el último año. | 3 N | NOT |
payment_acc_age | Fecha en la que la cuenta de pago fue registrada en la cuenta del titular con 3DS Requestor en el formato YYYMMDD. | = 8 N | NO |
payment_acc_ind | Indica el período de tiempo que la cuenta de pago fue registrada en el 3DS Requestor.
| = 2 N | NO |
ship_address_usage | Fecha de la primera utilización de la dirección de entrega en el formato AAAAMMDD. | = 8 N | NO |
ship_address_usage_ind | Indica cuándo se utilizó por primera vez la dirección de entrega.
| = 2 N | NO |
ship_name_indicator | Indica si el nombre del titular de la tarjeta es idéntico al nombre de la entrega utilizado para esta transacción.
| = 2 N | NO |
suspicious_acc_activity | Indica si el 3DS Requestor tuvo experiencias sospechosas (incluyendo fraudes anteriores) con la cuenta del comprador.
| = 2 N | NO |
| cardholder. bill_addr | Dirección de facturación del yiyular. | ||
city | Cidade. | < 50 AN | SI |
country | Código numérico ISO 3166-1 de tres dígitos del país. | = 3 N | SI |
line1 | Primera línea de la dirección. | < 50 AN | SI |
line2 | Segunda línea de la dirección. | < 50 AN | SI |
line3 | Tercera línea de la dirección. | < 50 AN | SI |
post_code | CEP. | < 16 AN | SI |
state | Sigla del estado. | < 3 AN | SI |
| cardholder. ship_addr | Dirección de entrega del titular. | ||
city | Ciudad. | < 50 AN | SI |
country | Código numérico ISO 3166-1 de tres dígitos del país. | = 3 N | SI |
line1 | Primera línea de la dirección. | < 50 AN | SI |
line2 | Segunda línea de la dirección. | < 50 AN | SI |
line3 | Tercera línea de la dirección. | < 50 AN | SI |
post_code | CEP. | < 16 AN | SI |
state | Sigla del estado. | < 3 AN | SI |
| merchant | |||
mcc | Código específico DS que describe el tipo de negocio/producto/servicio de la tienda. Antes de enviar la solicitud a la DS, la 3DS verifica automáticamente el tamaño del campo mcc ingresado. Si la longitud es inferior a 4 caracteres, la 3DS agregará ceros a la izquierda hasta que el campo alcance una longitud total de 4 caracteres. | = 4 AN | SI |
country_code | Código numérico de tres dígitos ISO 3166-1 del país de la tienda. | = 3 N | SI |
name | Nombre de la tienda designada por la entidad adquirente o el sistema de pago. | < 40 AN | SI |
| merchant. risk_indicator | Evaluación en la tienda del nivel de riesgo de fraude para la autenticación específica del portador y la autenticación que se realiza. | ||
delivery_email_address | En el caso de la entrega electrónica, la dirección de correo electrónico a la que se ha entregado la mercancía. | < 254 AN | NO |
delivery_timeframe | Indica el plazo de entrega de la mercancía.
| = 2 N | NO |
gift_card_amount | Para las compras con tarjeta regalo o de prepago, el importe total de la compra en números enteros (por ejemplo, 123.45 es 123). | < 15 N | NO |
gift_card_count | Para la compra de tarjetas de regalo o prepago, recuento de tarjetas de prepago/regalo compradas. | 2 N | NO |
gift_card_curr | Para la compra de tarjetas de regalo o prepago, código de moneda ISO 4217 de tres dígitos de la tarjeta de regalo. | = 3 N | NO |
pre_order_date | Para una preventa, la fecha prevista de disponibilidad de la mercancía en el formato YYYMMDD. | = 8 N | NO |
pre_order_purchase_ind | Indica si el titular está realizando un pedido de mercancía con disponibilidad futura.
| = 2 N | NO |
reorder_items_ind | Indica si el portador está pidiendo una mercancía previamente comprada.
| = 2 N | NO |
ship_indicator | Indica la forma de entrega elegida para la transacción.
| = 2 N | NO |
| message | |||
category | Identifica la categoría de mensaje para un caso de uso específico.
| = 2 N | YES |
| mensaje. extensión[] | Los datos necesarios para ayudar a los requisitos no definidos en el mensaje 3DS se cargan en una extensión del mensaje. | ||
criticality_indicator | Un valor booleano que indica si el destinatario debe entender el contenido de la extensión para interpretar el mensaje completo. | < 5 AN | NO |
data | Datos cargados en la extensión. | Object | NO |
id | Identificador único de la extensión. | < 64 AN | NO |
name | Nombre de la extensión. | < 64 AN | NO |
| purchase | |||
amount | Importe total de la compra en centavos. | < 48 N | SI |
currency | Código de moneda de tres dígitos ISO 4217 de la compra. | = 3 N | SI |
exponent | Número de decimales de la moneda según la norma ISO 4217. | = 1 N | SI |
date | Fecha e hora UTC de la compra en el formato AAAAMMDDHHMMSS. | = 12 N | SI |
instal_data | Número máximo de cuotas de la compra. El valor debe ser mayor que 1. | < 3 N | NO |
| recurring | Datos para transacciónes recurentes. | ||
expiry | Fecha en que no se haran más autorizaciones en el formato AAAAMMDD. Obligatorio cuando three_ds_requestor. authentication_ind = 02 o 03. | = 8 N | COND. |
frequency | Indica el número mínimo de días entre autorizaciones. Obligatorio cuando three_ds_requestor. authentication_ind = 02 o 03. | < 4 N | COND. |
| sdk | Estos campos son necesarios para 3DS SDKs (device_channel = 01). | ||
app_id | GUID creado para todas las instalaciones de la aplicación 3DS Requestor en un dispositivo de consumo. Esto será generado y almacenado por el SDK de 3DS para cada instalación. | = 36 AN | COND. |
enc_data | Objeto JWE (representado como una string) que contiene datos cifrados por el SDK para que el DS los descifre. | < 64000 AN | COND. |
ephem_pub_key | Clave pública generada por el 3DS SDK para comunicarse con el ACS. | Object | COND. |
max_timeout | Indica el máximo de tempo (en minutos) para cada intercambio de mensaje. | < 2 N | COND. |
trans_id | GUID de la transacción del 3DS SDK. | = 36 AN | COND. |
iface | Lista todos los tipos de interface SDK soportadas por el dispositivo para la visualización de las interfaces específicas de desafío.
| = 2 N | COND. |
ui_type[] | Lista todos los tipos de interface de usuário que el dispositivo soporta para visualización de las interfaces específicas de desafío dentro de la SDK.
| = 2 N[] | COND. |
| white_list | |||
status | Permite a comunicação de status de lista branca entre ACS, DS e 3DS Requestor.
| = 1 AN | NO |
status_source | Este campo sera completado por el que configura o status de la lista blanca.
| = 2 N | NO |
Parámetros de respuesta#
En caso de éxito, el código de respuesta HTTP será 200. Cualquier otro código debe ser interpretado como un error. En la tabla siguiente está la descripción de los parámetros de respuesta del servicio de autenticación:
| Parámetro | Descripción | Formato |
|---|---|---|
eci | Electronic Commerce Indicator | = 2 N |
broad_info | Información no-estructurada enviada entre 3DS Server, DS y ACS. | Object |
device_channel | Canal del dispositivo. Más información. | = 2 N |
message_version | Versión de transacción (esta versión debe usarse en la solicitud de CRes) | < 8 AN |
| three_ds_server | ||
trans_id | ID de la transacción 3DS Server | = 36 AN |
status | Status en el 3DS Server. Más información. | = 3 AN |
| acs | ||
challenge_mandated | Indicación de si el desafío es necesario para que la transacción sea autorizada.
| = 1 AN |
operator_id | Identificador del ACS designado por el DS. | < 32 AN |
reference_number | Identificador único designado por la EMVCo. | < 32 AN |
trans_id | ID de la transacción en el ACS. | = 36 AN |
url | URL completa de desafío del ACS. | < 2048 AN |
decoupled_confirmation_ind | Indica si el ACS confirma el uso de la autenticación disociada y acepta su uso para autenticar al comprador.
| = 1 AN |
signed_content | Contiene el objeto JWS creado por el ACS para el mensaje ARes. | var. AN |
iface | Esta es la interfaz de ACS donde se presentará el reto al titular.
| = 2 N |
ui_template | Identifica el formato de la interfaz de usuario que el ACS presenta por primera vez al consumidor.
| = 2 N |
| authentication | ||
type | Indica el tipo de forma de autenticación que el emisor utilizará para desafiar al portador.
| = 2 N |
value | Valor específico del sistema de pago proporcionado por el ACS o el SD utilizando un algoritmo definido por el sistema de pago. Valor de autentificación que se utilizará para proporcionar una prueba de autentificación (CAVV). | = 28 AN |
| cardholder | ||
info | Texto proporcionado por el ACS/Emisor al titular de la tarjeta durante una transacción frictionless ou decoupled. | < 128 AN |
| ds | ||
reference_number | Identificador único del DS designado por la EMVCo. | < 32 AN |
trans_id | ID de la transacción en el DS. | = 36 AN |
| message. extension[] | DLos datos necesarios para asistir a los requisitos no definidos en el mensaje 3DS se cargan en una extensión del mensaje. | |
criticality_indicator | UUn valor booleano que indica si el destinatario debe entender el contenido de la extensión para interpretar el mensaje completo. | < 5 AN |
data | Datos cargados en la extensión. | Object |
id | Identificador único de la extensión. | < 64 AN |
name | Nombre de la extensión. | < 64 AN |
| transaction | ||
status | Estado de la transacción según el protocolo 3DS 2.0.
| = 1 AN |
status_reason | Proporciona información sobre por qué el valor de transaction.status.
| = 2 N |
| white_list | ||
status | Permite la comunicación del estado de la lista blanca entre ACS, DS y 3DS Requestor.
| = 1 AN |
status_source | Este campo será completado por el sistema que configura el estado de la lista blanca.
| = 2 N |
| sdk | ||
trans_id | ID de transacción del SDK de 3DS. | = 36 AN |
| error | ||
code | Código de error. [Más información.] (3ds-server-api-codes.md # error-codes) | < 3 N |
componente | Indica qué componente identificó el error.
| = 1 AN |
description | Descripción del error | < 2048 AN |
detalle | Detalle del error | < 28 AN |