3DS Authentication

Validates the card's participation in a 3DS authentication program and confirms transaction data. If the transaction qualifies for a frictionless flow, the response will return the 3DS authentication result and complete the authentication process. If a challenge flow is required, the response will include the necessary parameters to initiate and execute the 3DS challenge.

Authentication Types

The 3DS flow can occur with challenge or without challenge/friction (frictionless). In the challenge flow, additional confirmation from the cardholder is required, such as validation via banking app or selfie, for example, with this step being the issuer's responsibility. The frictionless flow authenticates the user without the need for a challenge, directly returning the authentication data.

Frictionless Authentication

The setup endpoint receives the card number, expiration date, and cardholder name, returning an authentication waiting code, an access token, and a device data collection.

This data, along with the reference_id and request_id, is used in the authentication endpoint, which requires detailed information such as billing address, browser data, and purchase information.

Authentication return example:

HTTP Response

  {
    "code": "ACCEPTED",
    "access_token": "string",
    "device_data_collection_url": "https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect",
    "reference_id": "963341e8-b4d9-405c-9f59-80065c339563",
    "request_id": "42C46CD74D1845D698107DAAD84875DF20240222154543979"
  }

Challenge Authentication

If the authentication indicates the need for a challenge, the authentication endpoint will return WAITING_3DS_AUTHENTICATION, and the client will need to provide browser data via device information.

The process involves a callback to a client URL (return_url), where the challenge response is received from a third-party provider.

We suggest using a webhook so that the callback URL receives the 3DS response. This URL does not need to be previously registered, just informed in the return_url.

After the challenge is completed, the data received via webhook should be used to call the /v1/card_payments/threeds_challenge_result endpoint, which will return the final 3DS data for use in the sale, which should be passed in the three_ds_data object.

Making a Request

The call should be made using the POST method.

POST/v1/card_payments/threeds_authentication

Request Fields

Field	Type	Description	Required
card_number	string	The card number to be authenticated. Required only in transactions without slug_token and slug_stored_card.	Yes
card_expiration_date	string	Card expiration date. Required only in transactions without slug_token and slug_stored_card.	Yes
card_holder_name	string	Cardholder name as printed on the card. Required only in transactions without slug_token and slug_stored_card.	Yes
slug_token	string	A 32-character alphanumeric string representing a card tokenized by the /v1/card_payments/tokenize_card endpoint. Can be used instead of card_number, card_expiration_date and card_holder_name.	Partial
slug_stored_card	string	A 32-character alphanumeric string representing a card tokenized by the /v1/card_payments/tokenize_card endpoint. Can be used instead of card_number, card_expiration_date and card_holder_name.	Partial
request_id	string	Request ID for the authentication transaction.	Yes
reference_id	string	Reference value for the authentication transaction.	Yes
sale_type	string	Specifies which type of account the transaction should be processed with. Allowed: CREDIT or DEBIT	Yes
amount	string	The total transaction amount.	Yes
currency	string	Transaction currency. Allowed: BRL	Yes
street	string	Street	Yes
neighborhood	string	Neighborhood	Yes
state	string	State	Yes
country	string	Country abbreviation. Example: BR, USA	Yes
city	string	City	Yes
zip_code	string	ZIP code	Yes
first_name	string	Card owner's first name	Yes
last_name	string	Card owner's last name	Yes
phone_number	string	Cardholder's mobile number with country and area code. Example: +5511989999999	Yes
email	string	Card owner's email	Yes
transaction_mode	string	Identifies the channel from which the transaction originates. Allowed: M: MOTO (Mail Order Telephone Order), R: Retail, S: eCommerce, P: Mobile Device, T: Tablet	No
acs_window_size	string	Define the challenge window size to be displayed to the final cardholder. Allowed: 01 for 250x400, 02 for 390x400, 03 for 500x600, 04 for 500x600, 05 for Full Page	No
device_channel	string	Determines the channel through which the transaction occurred. Allowed: SDK, Browser, 3RI	Yes
http_browser_java_enabled	boolean	Whether Java is enabled in the browser.	Yes
http_browser_language	string	Browser language.	Yes
http_browser_color_depth	string	Browser color depth.	Yes
http_browser_screen_height	string	Browser screen height.	Yes
http_browser_screen_width	string	Browser screen width.	Yes
http_browser_time_difference	string	Time difference between UTC time and the cardholder's browser local time, in minutes.	Yes
user_agent_browser	string	User-Agent header value sent by the client's browser.	Yes
http_accept_content	string	The user's browser HTTP 'Accept' header, indicating supported content types.	Yes
merchant_url	string	Company website address provided by the merchant.	Yes
return_url	string	URL to retrieve the TransactionId after challenge completion. This information will be necessary to retrieve the challenge result.	Yes

HTTP Request Body

  {
    "slug_token": "abc123xyz",
    "slug_stored_card": "stored-card-789",
    "card_number": "4111111111111111",
    "card_expiration_date": "122028",
    "card_holder_name": "John Doe",
    "request_id": "42C46CD74D1845D698107DAAD84875DF20240222154543979",
    "reference_id": "963341e8-b4d9-405c-9f59-80065c339563",
    "sale_type": "CREDIT",
    "amount": 15075,
    "currency": "BRL",
    "street": "Rua A 1",
    "neighborhood": "Bairro 1",
    "state": "SP",
    "country": "BR",
    "city": "São Paulo",
    "first_name": "Jon",
    "last_name": "Doe",
    "phone_number": "+5581989999999",
    "email": "john@example.com",
    "zip_code": "00000000",
    "transaction_mode": "M: MOTO (Mail Order Telephone Order)",
    "acs_window_size": "01 for 250x400",
    "device_channel": "Browser",
    "http_browser_java_enabled": false,
    "http_browser_language": "pt-BR",
    "http_browser_color_depth": 24,
    "http_browser_screen_height": 1080,
    "http_browser_screen_width": 1920,
    "http_browser_time_difference": 300,
    "user_agent_browser": "Mozilla/5.0 (Macintosh; Intel Mac OS X 15_5)",
    "http_accept_content": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
    "merchant_url": "https://lojaexemplo.com.br/checkout",
    "return_url": "https://lojaexemplo.com.br/pagamento/retorno"
  }

Response Fields

Field	Type	Description
code	string	Transaction result response code. Examples: WAITING_3DS_AUTHENTICATION, ACCEPTED
msg	string	Transaction result response message.
access_token	string	If challenge is required, this token should be sent to initiate it.
step_up_url	string	If challenge is required, this is the URL to initiate it.
authentication_id	string	If challenge is required, this ID should be sent to initiate it.
iframe_dimensions	object	If challenge is required, these should be the iframe dimensions in which the challenge will be performed.
iframe_dimension_width	string	Iframe width
iframe_dimension_height	string	Iframe height
cavv	string	The cardholder authentication value for the 3D Secure authentication session.
xid	string	The transaction identifier assigned by the Directory Server for authentication. Only used for Visa transactions.
specification_version	string	The 3DS version used for authentication.
directory_server_transaction_id	string	The directory server transaction ID is generated by the directory server during authentication.
three_ds_server_transaction_id	string	The threeDS server transaction ID is generated by the directory server during authentication.
multiacq_id	string	An identifier for the authorizer.

Success

Response Example - Frictionless

After the call, a JSON is returned with status 200.

HTTP 200 Response Body - Example

{
  "code": "ACCEPTED",
  "xid": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
  "cavv": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
  "specification_version": "2.2.0",
  "directory_server_transaction_id": "318d16b4-f741-45f2-8f0a-026c4b79a596",
  "authentication_id": "7612476846306645104807",
  "multiacq_id": "001"
}

Response Example - Challenge

After the call, a JSON is returned with status 200.

When the transaction requires additional authentication from the cardholder (3-D Secure), the API will return a response with the following format:

HTTP 200 Response Body - Example

{
  "code": "WAITING_3DS_AUTHENTICATION",
  "msg": "CONSUMER_AUTHENTICATION_REQUIRED : The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction.",
  "access_token": "5ecCI6IkpXVJhbGciOiJIUzI1NyRiIsInCJ9.eyJqdGkiOiIyMjkxYmNhYS02NDMxNDIsImlzcyI6IjVkZDgzYmYwMGU0MjNkMTQ5OGRjYmFjYSIsImV4cCIM2ZmE0YjkzNmI5MGQ2IiwiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczovLzBtZXJjaGFudGFjc3N0YWcuY2FyZGluYWxjb21tZXJjZS5jb20vTWVyY2hhbnRBQ1NXZWIvY3JlcS5qc3AiLCJQYXlsb2FkIzNDI1LTRkMTktOTdlNy1mNDU5ZmIxNjM4MGIiLCJpYXQiOjE3NjAjoiZXlKdFp6MTc2MDY0Njc0MiwiT3JnVW5pdElkIjoiNjQ3NTA0ZmQ2NWYTnpZV2RsVkhsd1pTSTZJa05TWlhGaUxDSnRaWE56WVdkbFZtVnljMmx2YmlJNklqSXVNUzR3SWl3aWRHaHlaV1ZFVlMwMFpXUmxMVGs1TWpNdE1UbGtObUU0WldVeE1EQmlJaXdpWTJoaGJHeGxibWTFObGNuWmxjbFJ5WVc1elNVUWlPaUl3WldNM1l6YzFNeTAwWW1aaUxUUTJPVGd0WVRabVpTMWxaRGxrTVRoaU56SmxNMllpTENKaFkzTlVjbUZ1YzBsRUlqb2lZbVUxT1dKbE9URXRPVGt6TRsVjJsdVpHOTNVMmw2WlNJNklqQXlJbjAiLCJUcmFuc2FjdGlvbklkIjoiZFpzejBBWlhYNmhvWVZCSmhWazAifSwiT2JqZWN0aWZ5UGF5bG9hZCI6dHJ1ZSwiUmV0dXJuVXJsIjoiaHR0cDovL3Rlc3RlLnRocmVlZHMuY29tL2NoYWxsZW5nZSJ9._-Ocb9KJyusTaXx_gPMRSZFKEGAt5x0",
  "step_up_url": "https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp",
  "authentication_id": "7606431418396443903814",
  "iframe_dimensions": {
    "iframe_dimension_width": "390",
    "iframe_dimension_height": "400"
  },
  "multiacq_id": "001"
}

This response indicates that the card issuer has requested a 3-D Secure authentication challenge (3DS Step-Up).

The client (merchant) should use the provided data to present the authentication step to the cardholder before proceeding with transaction authorization.

The 3DS authentication screen should be displayed in a secure iframe within your environment (checkout, application, or web page), using the provided parameters.

Step-by-step (challenge):

1. Receive the response with WAITING_3DS_AUTHENTICATION.
2. Render an iframe with the informed dimensions (iframe_dimensions) and load the authentication URL (step_up_url).
3. Include the access_token in the request body or as a parameter in the call to the 3DS endpoint, according to the provider's specification.
4. Wait for the authentication result (success, failure, or cancellation).
5. Proceed with transaction authorization only after challenge completion.
6. After the challenge is successfully completed, a call will be made to the provided return_url, informing the transactionId

Errors

In case of errors, a JSON will be returned with the error attribute specifying the reason why the operation was invalidated.

HTTP 400 Response Body - Example

{
  "errors": [
    {
      "code": "MSG_NOT_SUPPORTED",
      "msg": "Not supported"
    }
  ],
  "request_token": "EE4F8B5BC25A46B080F11D34B9CFAFFF",
  "multiacq_id": "001"
}

HTTP 422 Response Body - Example

{
  "errors": [
    {
      "code": "INVALID_INPUT_CARD_METHOD",
      "msg": "request must include only slugToken, slugStoredCard, or card data. Please refer to the documentation."
    }
  ],
  "request_token": "7C2E9D3869F34F3CA5CC2C5CFAB4B6E2",
  "transaction_status": "REJECTED",
  "multiacq_id": "001"
}