Setup 3DS

3D Secure or 3DS is an authentication protocol used to confirm whether the buyer is actually the cardholder of the credit or debit card. The purpose of this protocol is to prevent fraud in card not present (CNP) transactions. When 3DS is approved, a liability shift occurs, transferring the responsibility for fraud chargebacks to the issuer.

Attention

The shift only happens when 3DS is implemented correctly and the transaction follows the criteria required by the card brand (e.g.: approved authentication, valid attempt even without issuer support, etc.).

The setup stage focuses on collecting and validating the customer's payment data. In practice, this stage verifies the accuracy of the card information and provides the essential parameters needed to initiate the next stage: 3D Secure (3DS) authentication.

Making Request

The call should be made using the POST method.

POST/v1/card_payments/threeds_authentication_setup

Request Fields

Attribute	Type	Description	Required
card_number	string	Card number, without spaces or dashes	Partial
card_expiration_date	string	Card expiration date, in MMyyyy format (e.g.: 012029)	Partial
card_holder_name	string	Cardholder name printed on the card	Partial
slug_token	string	A 32-character alphanumeric string representing a tokenized card from the /v1/tokenize_card endpoint. Can be used instead of card_number, card_expiration_date and card_security_code.	No
slug_stored_card	string	A 32-character alphanumeric string representing a card stored in the card vault by the /v1/tokenize_card endpoint. Can be used instead of card_number, card_expiration_date and card_security_code.	No

Request Example - Card Data

HTTP Request Body - Card Data

  {
    "card_number": "4100000000000000",
    "card_expiration_date": "102033",
    "card_holder_name": "João da Silva"
  }

Request Example - Slug Token

HTTP Request Body - Slug token

  {
    "slug_token": "string"
  }

Request Example - Slug Stored Card

HTTP Request Body - Slug stored card

  {
    "slug_stored_card": "string"
  }

Success

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

HTTP 200 Response Body - Example

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

Errors

In case of errors, a JSON with the error attribute will be returned 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"
}