# 3DS - Init Authentication

**POST** `/dpm/security-gwproxy/v2/enrolments-initial`

Base URL: `https://api.pre.globalgetnet.com`

__Initiate 3DS Authentication__<br><br>

3D Secure (3DS) is an authentication protocol designed to enhance the security of online transactions by verifying the identity of cardholders before a payment is processed. This endpoint initiates the enrolment flow for 3DS authentication, beginning the authentication process for a payment transaction.<br><br>

**Usage Scenarios:**<br>
- Adding an extra layer of security to card payments and reducing fraud risk.<br>
- Complying with Strong Customer Authentication (SCA) requirements for transactions in the European Economic Area (EEA).<br>

**Notes:**<br>

- The authentication flow is dynamically determined by factors such as card brand, issuing bank, and risk assessment.<br>
- Your integration must handle all possible authentication scenarios returned by the API.<br><br>

The Data Share Only option shares transaction information from merchants with issuers, allowing for informed authorization decisions without full authentication, thus providing a frictionless experience. For Visa and Mastercard, use "requestor_challenge_indicator=06".<br>

For detailed information about 3DS authentication, including how it works, available scenarios, and implementation guidance, see the [3DS Authentication documentation](/core-concepts/3dSecure).<br><br>

## Body

Content type: `application/json`

- `currency` (string)
- `md` (string)
  ID defined by the merchant to identify the enrolment response
- `term_url` (string)
- `amount` (integer<int32>)
- `payment_method` (object)
  - `number_token` (string, required)
  - `security_code` (string, required)
  - `expiration_month` (string, required)
  - `expiration_year` (string, required)
- `description` (string)
- `operation` (string)
- `extra_fields` (object)
  - `billing_address` (object)
    Data structure containing shipping address details
    - `street` (string, required)
      Name of a street or thoroughfare
    - `number` (string, required)
      Number that identifies the position of a building on a street
    - `complement` (string)
      Additional address information
    - `district` (string)
      Name of a district, for example, a part of a town or region
    - `city` (string)
      Name of a built-up area with defined boundaries and a local government.

      The value is based on the ISO 3166-2, according to the country defined within the address details.
    - `state` (string)
      Name of an organized political community or area forming a part of a federation.

      The value is based on the ISO 3166-2, according to the country defined within the address details.
    - `country` (string, required)
      Country code.

      The value is based on the ISO 3166-1 alpha-2 (https://www.iso.org/obp/ui/#search/code/).
    - `postal_code` (string, required)
      Postal or ZIP code.

      The value consists of a group of letters and/or numbers that is added to a postal address to assist in sorting the mail.
    - `reference` (string)
      Reference point details that can be used to help locate the address
  - `shipping_address` (object)
    Data structure containing shipping address details
    - `street` (string, required)
      Name of a street or thoroughfare
    - `number` (string, required)
      Number that identifies the position of a building on a street
    - `complement` (string)
      Additional address information
    - `district` (string)
      Name of a district, for example, a part of a town or region
    - `city` (string)
      Name of a built-up area with defined boundaries and a local government.

      The value is based on the ISO 3166-2, according to the country defined within the address details.
    - `state` (string)
      Name of an organized political community or area forming a part of a federation.

      The value is based on the ISO 3166-2, according to the country defined within the address details.
    - `country` (string, required)
      Country code.

      The value is based on the ISO 3166-1 alpha-2 (https://www.iso.org/obp/ui/#search/code/).
    - `postal_code` (string, required)
      Postal or ZIP code.

      The value consists of a group of letters and/or numbers that is added to a postal address to assist in sorting the mail.
    - `reference` (string)
      Reference point details that can be used to help locate the address
  - `data_only` (object)
    Data structure used to request a data_share_only 3DS flow, without a challenge
    - `requestor_challenge_indicator` (string)
      3DS requestor challenge preference (EMV 3DS threeDSRequestorChallengeInd). Set to "06" to request no challenge and share cardholder data only.

Example:

```json
{
  "currency": "string",
  "md": "NmQyZTQzODAtZDhhMy00Y2NiLTkxMzgtYzI4OTE4MjgxOGE0",
  "term_url": "string",
  "amount": 0,
  "payment_method": {
    "number_token": "string",
    "security_code": "string",
    "expiration_month": "string",
    "expiration_year": "string"
  },
  "description": "string",
  "operation": "string",
  "extra_fields": {
    "billing_address": {
      "street": "Av. Brasil",
      "number": "1000",
      "complement": "Sala 1",
      "district": "São Geraldo",
      "city": "Porto Alegre",
      "state": "RS",
      "country": "BR",
      "postal_code": "90230060",
      "reference": "Near the hospital"
    },
    "shipping_address": {
      "street": "Av. Brasil",
      "number": "1000",
      "complement": "Sala 1",
      "district": "São Geraldo",
      "city": "Porto Alegre",
      "state": "RS",
      "country": "BR",
      "postal_code": "90230060",
      "reference": "Near the hospital"
    },
    "data_only": {
      "requestor_challenge_indicator": "06"
    }
  }
}
```

## Responses

### 200

OK

- `transaction_id` (string)
- `md` (string)
  ID defined by the merchant to identify the enrolment response
- `tx_id` (integer<int32>)
- `xid` (string)
  Field available from version 2.0 onwards. MPI identifier for each authenticated transaction. The field content can be a HEXA or Base64 value, according to the MPI used.
- `protocol` (string)
  3DS protocol used during processing
- `status` ("Authenticated" | "Denied" | "Pending" | "Pending Challenge" | "Pending Enrolment Continue")
  Status of the transactions generated by the enrolment process
- `operation` ("CREDIT" | "DEBIT")
  Card operation type
- `tds_method_content` (string)
  Complete HTML fragment that needs to be rendered in customer's browser
- `redirect_html_template` (string)
  HTML template for redirecting the customer to the card issuer's authentication flow
- `acs_redirect_form` (object)
  Object containing the details for the ACS redirect form
  - `action_url` (string)
    URL to which the form should be submitted
  - `method` (string)
    HTTP method to be used for the form submission
  - `creq` (string)
    Challenge Request message
  - `threeDSSessionData` (string)
    3DS Session Data
- `extra_fields` (object)
  - `billing_address` (object)
    Data structure containing shipping address details
    - `street` (string, required)
      Name of a street or thoroughfare
    - `number` (string, required)
      Number that identifies the position of a building on a street
    - `complement` (string)
      Additional address information
    - `district` (string)
      Name of a district, for example, a part of a town or region
    - `city` (string)
      Name of a built-up area with defined boundaries and a local government.

      The value is based on the ISO 3166-2, according to the country defined within the address details.
    - `state` (string)
      Name of an organized political community or area forming a part of a federation.

      The value is based on the ISO 3166-2, according to the country defined within the address details.
    - `country` (string, required)
      Country code.

      The value is based on the ISO 3166-1 alpha-2 (https://www.iso.org/obp/ui/#search/code/).
    - `postal_code` (string, required)
      Postal or ZIP code.

      The value consists of a group of letters and/or numbers that is added to a postal address to assist in sorting the mail.
    - `reference` (string)
      Reference point details that can be used to help locate the address
  - `shipping_address` (object)
    Data structure containing shipping address details
    - `street` (string, required)
      Name of a street or thoroughfare
    - `number` (string, required)
      Number that identifies the position of a building on a street
    - `complement` (string)
      Additional address information
    - `district` (string)
      Name of a district, for example, a part of a town or region
    - `city` (string)
      Name of a built-up area with defined boundaries and a local government.

      The value is based on the ISO 3166-2, according to the country defined within the address details.
    - `state` (string)
      Name of an organized political community or area forming a part of a federation.

      The value is based on the ISO 3166-2, according to the country defined within the address details.
    - `country` (string, required)
      Country code.

      The value is based on the ISO 3166-1 alpha-2 (https://www.iso.org/obp/ui/#search/code/).
    - `postal_code` (string, required)
      Postal or ZIP code.

      The value consists of a group of letters and/or numbers that is added to a postal address to assist in sorting the mail.
    - `reference` (string)
      Reference point details that can be used to help locate the address
  - `data_only` (object)
    Data structure used to request a data_share_only 3DS flow, without a challenge
    - `requestor_challenge_indicator` (string)
      3DS requestor challenge preference (EMV 3DS threeDSRequestorChallengeInd). Set to "06" to request no challenge and share cardholder data only.

Example:

```json
{
  "transaction_id": "string",
  "md": "NmQyZTQzODAtZDhhMy00Y2NiLTkxMzgtYzI4OTE4MjgxOGE0",
  "tx_id": 0,
  "xid": "VDdnR0kyU1g4ZXlxMkhWTlp0VnA=",
  "protocol": "3DS2.2.0",
  "status": "Pending",
  "operation": "CREDIT",
  "tds_method_content": "<html></html>",
  "redirect_html_template": "<html class=\"no-js\" lang=\"en\" xmlns=\"http://www.w3.org/1999/xhtml\">\n<head>\n<META http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\n<meta charset=\"utf-8\">\n<title>3D Secure Processing</title>\n<link href=\"https://3ds2-mpi.test.modirum.com/mdpaympi/static/mpi.css\" rel=\"stylesheet\" type=\"text/css\">\n</head>\n<body>\n<div id=\"main\">\n<div id=\"content\">\n<div id=\"order\">\n<h2>3D Secure Processing</h2>\n<script src=\"https://3ds2-mpi.test.modirum.com/mdpaympi/static/red.js\" defer>/* needed for xsl to xhtml */</script>\n<div id=\"spinner\">\n<img src=\"https://3ds2-mpi.test.modirum.com/mdpaympi/static/preloader.gif\" alt=\"Please wait..\"></div>\n<img src=\"https://3ds2-mpi.test.modirum.com/mdpaympi/static/mc_idcheck_hrz_ltd_pos_103px.png\" alt=\"MasterCard ID Check\"><div id=\"formdiv\">\n<div>\n<form id=\"webform0\" name=\"red2ACSv1\" method=\"POST\" action=\"https://3ds-acs.test.modirum.com/mdpayacs/pareq\" accept_charset=\"UTF-8\">\n<input type=\"hidden\" name=\"PaReq\" value=\"eJxVUctuwjAQ/JWIe7GdBwK0WKJNpXIAUUop6s1ytiQiccB2Kvj72iEprU8zsw/vzsI214jpG8pGI4clGiMOGBTZbLDevE6ieMISNuCwnm/wzOEbtSlqxdmQDkMgPXV1WuZCWQ5Cnh8XKx63D0hHoUK9SDmjlAK5YVCiQp4+78IocmLLQNaNsvrK47Gr7Qk0uuS5tSczZaSspSjz2tiHL3HEoawrID4O5D7DuvHIuH6XIuO7NFMbery+s0P8uS8vy2P+sS1PdKfmMyA+AzJhkYc0ZCyk44DF0zCZshGQVgdR+UH4cr8K3N5u1k6Ak/9nfiPMB/4K4BzVqGS/TM8AL6daoctwBv5iyNBIHqVvAdsHWy2UEdI6a90MPgDkvtPTi3dZWu/nKB4lk2TMvNGt4rsXzrMwYbRt7wkQX0O6G5LuyA79O/4Pb++sPw==\"><input type=\"hidden\" name=\"MD\" value=\"eyJzZWxsZXJfaWQiOiIwNmYyNTZjOC0xYmJmLTQyYmYtOTNiNC1jZTIwNDFiZmI4N2EiLCJ0cmFuc2FjdGlvbl9pZCI6ImRjYjU4NzJlLWYxYjYtNDkyMi1hMGFlLWZiMGYyODg2MTM5YiIsImNvdW50cnkiOiJNWCIsInRlbmFudCI6InNhbnRhbmRlciJ9\"><input type=\"hidden\" name=\"TermUrl\" value=\"http://localhost:4000/api/modirum/token\"><input type=\"submit\" name=\"submitBtn\" value=\"Please click here to continue\">\n</form>\n</div>\n</div>\n<noscript>\n<div align=\"center\">\n<b>Javascript is turned off or not supported!</b>\n<br>\n</div>\n</noscript>\n</div>\n<div id=\"content-footer\"></div>\n</div>\n</div>\n</body>\n</html>\n",
  "acs_redirect_form": {
    "action_url": "https://test.getnet.com",
    "method": "POST",
    "creq": "ewogICAgImF",
    "threeDSSessionData": "NmQyZTQzODA"
  },
  "extra_fields": {
    "billing_address": {
      "street": "Av. Brasil",
      "number": "1000",
      "complement": "Sala 1",
      "district": "São Geraldo",
      "city": "Porto Alegre",
      "state": "RS",
      "country": "BR",
      "postal_code": "90230060",
      "reference": "Near the hospital"
    },
    "shipping_address": {
      "street": "Av. Brasil",
      "number": "1000",
      "complement": "Sala 1",
      "district": "São Geraldo",
      "city": "Porto Alegre",
      "state": "RS",
      "country": "BR",
      "postal_code": "90230060",
      "reference": "Near the hospital"
    },
    "data_only": {
      "requestor_challenge_indicator": "06"
    }
  }
}
```

### 400

Bad Request

- `message` (string)
  Detailed error message.
- `name` (string)
  Name of the module or system in which the error occurred.
- `status_code` (integer<int32>)
  HTTP status code of the error.
- `details` (object[])
  Error details.
  - `status` (string)
    Error situation.
  - `error_code` (string)
    Error code.
  - `description` (string)
    Description of the error.
  - `description_detail` (string)
    Detailed description of the error.
  - `brand` (string)
    Brand.
  - `payment_id` (string)
    payment_id.
  - `seller_id` (string)
    seller_id.
  - `amount` (string)
    amount.
  - `currency` (string)
    currency.
  - `order_id` (string)
    order_id.
  - `credit_cancel` (object)
    credit_cancel.
    - `canceled_at` (string)
      canceledAt.
    - `message` (string)
      message.
  - `payment_tag` (string)
    payment_tag.
  - `status_code` (string)
    statusCode.
  - `message` (string)
    message.
  - `name` (string)
    name.
  - `acquirer_transaction_id` (string)
    acquirer_transaction_id.
  - `authorization_code` (string)
    authorization_code.
  - `transaction_id` (string)
    transaction_id.
  - `reason_code` (string)
    reason_code.
  - `reason_message` (string)
    reason_message.
  - `merchant_advice_code` (string)
    merchant_advice_code.
- `payments` (object[])
  Error details.
  - `status` (string)
    Error situation.
  - `error_code` (string)
    Error code.
  - `description` (string)
    Description of the error.
  - `description_detail` (string)
    Detailed description of the error.
  - `brand` (string)
    Brand.
  - `payment_id` (string)
    payment_id.
  - `seller_id` (string)
    seller_id.
  - `amount` (string)
    amount.
  - `currency` (string)
    currency.
  - `order_id` (string)
    order_id.
  - `credit_cancel` (object)
    credit_cancel.
    - `canceled_at` (string)
      canceledAt.
    - `message` (string)
      message.
  - `payment_tag` (string)
    payment_tag.
  - `status_code` (string)
    statusCode.
  - `message` (string)
    message.
  - `name` (string)
    name.
  - `acquirer_transaction_id` (string)
    acquirer_transaction_id.
  - `authorization_code` (string)
    authorization_code.
  - `transaction_id` (string)
    transaction_id.
  - `reason_code` (string)
    reason_code.
  - `reason_message` (string)
    reason_message.
  - `merchant_advice_code` (string)
    merchant_advice_code.
- `combined_id` (string)
  combinedId.
- `order_id` (string)
  orderId.
- `seller_id` (string)
  sellerId.

Example:

```json
{
  "message": "string",
  "name": "string",
  "status_code": 0,
  "details": [
    {
      "status": "string",
      "error_code": "string",
      "description": "string",
      "description_detail": "string",
      "brand": "string",
      "payment_id": "string",
      "seller_id": "string",
      "amount": "string",
      "currency": "string",
      "order_id": "string",
      "credit_cancel": {
        "canceled_at": "string",
        "message": "string"
      },
      "payment_tag": "string",
      "status_code": "string",
      "message": "string",
      "name": "string",
      "acquirer_transaction_id": "string",
      "authorization_code": "string",
      "transaction_id": "string",
      "reason_code": "string",
      "reason_message": "string",
      "merchant_advice_code": "string"
    }
  ],
  "payments": [
    {
      "status": "string",
      "error_code": "string",
      "description": "string",
      "description_detail": "string",
      "brand": "string",
      "payment_id": "string",
      "seller_id": "string",
      "amount": "string",
      "currency": "string",
      "order_id": "string",
      "credit_cancel": {
        "canceled_at": "string",
        "message": "string"
      },
      "payment_tag": "string",
      "status_code": "string",
      "message": "string",
      "name": "string",
      "acquirer_transaction_id": "string",
      "authorization_code": "string",
      "transaction_id": "string",
      "reason_code": "string",
      "reason_message": "string",
      "merchant_advice_code": "string"
    }
  ],
  "combined_id": "string",
  "order_id": "string",
  "seller_id": "string"
}
```

### 500

Internal Server Error

- `message` (string)
  Detailed error message.
- `name` (string)
  Name of the module or system in which the error occurred.
- `status_code` (integer<int32>)
  HTTP status code of the error.
- `details` (object[])
  Error details.
  - `status` (string)
    Error situation.
  - `error_code` (string)
    Error code.
  - `description` (string)
    Description of the error.
  - `description_detail` (string)
    Detailed description of the error.
  - `brand` (string)
    Brand.
  - `payment_id` (string)
    payment_id.
  - `seller_id` (string)
    seller_id.
  - `amount` (string)
    amount.
  - `currency` (string)
    currency.
  - `order_id` (string)
    order_id.
  - `credit_cancel` (object)
    credit_cancel.
    - `canceled_at` (string)
      canceledAt.
    - `message` (string)
      message.
  - `payment_tag` (string)
    payment_tag.
  - `status_code` (string)
    statusCode.
  - `message` (string)
    message.
  - `name` (string)
    name.
  - `acquirer_transaction_id` (string)
    acquirer_transaction_id.
  - `authorization_code` (string)
    authorization_code.
  - `transaction_id` (string)
    transaction_id.
  - `reason_code` (string)
    reason_code.
  - `reason_message` (string)
    reason_message.
  - `merchant_advice_code` (string)
    merchant_advice_code.
- `payments` (object[])
  Error details.
  - `status` (string)
    Error situation.
  - `error_code` (string)
    Error code.
  - `description` (string)
    Description of the error.
  - `description_detail` (string)
    Detailed description of the error.
  - `brand` (string)
    Brand.
  - `payment_id` (string)
    payment_id.
  - `seller_id` (string)
    seller_id.
  - `amount` (string)
    amount.
  - `currency` (string)
    currency.
  - `order_id` (string)
    order_id.
  - `credit_cancel` (object)
    credit_cancel.
    - `canceled_at` (string)
      canceledAt.
    - `message` (string)
      message.
  - `payment_tag` (string)
    payment_tag.
  - `status_code` (string)
    statusCode.
  - `message` (string)
    message.
  - `name` (string)
    name.
  - `acquirer_transaction_id` (string)
    acquirer_transaction_id.
  - `authorization_code` (string)
    authorization_code.
  - `transaction_id` (string)
    transaction_id.
  - `reason_code` (string)
    reason_code.
  - `reason_message` (string)
    reason_message.
  - `merchant_advice_code` (string)
    merchant_advice_code.
- `combined_id` (string)
  combinedId.
- `order_id` (string)
  orderId.
- `seller_id` (string)
  sellerId.

Example:

```json
{
  "message": "string",
  "name": "string",
  "status_code": 0,
  "details": [
    {
      "status": "string",
      "error_code": "string",
      "description": "string",
      "description_detail": "string",
      "brand": "string",
      "payment_id": "string",
      "seller_id": "string",
      "amount": "string",
      "currency": "string",
      "order_id": "string",
      "credit_cancel": {
        "canceled_at": "string",
        "message": "string"
      },
      "payment_tag": "string",
      "status_code": "string",
      "message": "string",
      "name": "string",
      "acquirer_transaction_id": "string",
      "authorization_code": "string",
      "transaction_id": "string",
      "reason_code": "string",
      "reason_message": "string",
      "merchant_advice_code": "string"
    }
  ],
  "payments": [
    {
      "status": "string",
      "error_code": "string",
      "description": "string",
      "description_detail": "string",
      "brand": "string",
      "payment_id": "string",
      "seller_id": "string",
      "amount": "string",
      "currency": "string",
      "order_id": "string",
      "credit_cancel": {
        "canceled_at": "string",
        "message": "string"
      },
      "payment_tag": "string",
      "status_code": "string",
      "message": "string",
      "name": "string",
      "acquirer_transaction_id": "string",
      "authorization_code": "string",
      "transaction_id": "string",
      "reason_code": "string",
      "reason_message": "string",
      "merchant_advice_code": "string"
    }
  ],
  "combined_id": "string",
  "order_id": "string",
  "seller_id": "string"
}
```