Getnet DocsGetnet Docs

3DS - Init Authentication

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

__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 application/json

currencystring
mdstring

ID defined by the merchant to identify the enrolment response

term_urlstring
amountinteger<int32>
payment_methodobject
Show payment_method properties
number_tokenstringrequired
security_codestringrequired
expiration_monthstringrequired
expiration_yearstringrequired
descriptionstring
operationstring
extra_fieldsobject
Show extra_fields properties
billing_addressobject

Data structure containing shipping address details

Show billing_address properties
streetstringrequired

Name of a street or thoroughfare

numberstringrequired

Number that identifies the position of a building on a street

complementstring

Additional address information

districtstring

Name of a district, for example, a part of a town or region

citystring

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.

statestring

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.

countrystringrequired

Country code. The value is based on the ISO 3166-1 alpha-2 (https://www.iso.org/obp/ui/#search/code/).

postal_codestringrequired

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.

referencestring

Reference point details that can be used to help locate the address

shipping_addressobject

Data structure containing shipping address details

Show shipping_address properties
streetstringrequired

Name of a street or thoroughfare

numberstringrequired

Number that identifies the position of a building on a street

complementstring

Additional address information

districtstring

Name of a district, for example, a part of a town or region

citystring

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.

statestring

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.

countrystringrequired

Country code. The value is based on the ISO 3166-1 alpha-2 (https://www.iso.org/obp/ui/#search/code/).

postal_codestringrequired

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.

referencestring

Reference point details that can be used to help locate the address

data_onlyobject

Data structure used to request a data_share_only 3DS flow, without a challenge

Show data_only properties
requestor_challenge_indicatorstring

3DS requestor challenge preference (EMV 3DS threeDSRequestorChallengeInd). Set to "06" to request no challenge and share cardholder data only.

Response

OK

transaction_idstring
mdstring

ID defined by the merchant to identify the enrolment response

tx_idinteger<int32>
xidstring

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.

protocolstring

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_contentstring

Complete HTML fragment that needs to be rendered in customer's browser

redirect_html_templatestring

HTML template for redirecting the customer to the card issuer's authentication flow

acs_redirect_formobject

Object containing the details for the ACS redirect form

Show acs_redirect_form properties
action_urlstring

URL to which the form should be submitted

methodstring

HTTP method to be used for the form submission

creqstring

Challenge Request message

threeDSSessionDatastring

3DS Session Data

extra_fieldsobject
Show extra_fields properties
billing_addressobject

Data structure containing shipping address details

Show billing_address properties
streetstring

Name of a street or thoroughfare

numberstring

Number that identifies the position of a building on a street

complementstring

Additional address information

districtstring

Name of a district, for example, a part of a town or region

citystring

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.

statestring

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.

countrystring

Country code. The value is based on the ISO 3166-1 alpha-2 (https://www.iso.org/obp/ui/#search/code/).

postal_codestring

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.

referencestring

Reference point details that can be used to help locate the address

shipping_addressobject

Data structure containing shipping address details

Show shipping_address properties
streetstring

Name of a street or thoroughfare

numberstring

Number that identifies the position of a building on a street

complementstring

Additional address information

districtstring

Name of a district, for example, a part of a town or region

citystring

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.

statestring

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.

countrystring

Country code. The value is based on the ISO 3166-1 alpha-2 (https://www.iso.org/obp/ui/#search/code/).

postal_codestring

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.

referencestring

Reference point details that can be used to help locate the address

data_onlyobject

Data structure used to request a data_share_only 3DS flow, without a challenge

Show data_only properties
requestor_challenge_indicatorstring

3DS requestor challenge preference (EMV 3DS threeDSRequestorChallengeInd). Set to "06" to request no challenge and share cardholder data only.

Bad Request

messagestring

Detailed error message.

namestring

Name of the module or system in which the error occurred.

status_codeinteger<int32>

HTTP status code of the error.

detailsobject[]

Error details.

Show details properties
statusstring

Error situation.

error_codestring

Error code.

descriptionstring

Description of the error.

description_detailstring

Detailed description of the error.

brandstring

Brand.

payment_idstring

payment_id.

seller_idstring

seller_id.

amountstring

amount.

currencystring

currency.

order_idstring

order_id.

credit_cancelobject

credit_cancel.

Show credit_cancel properties
canceled_atstring

canceledAt.

messagestring

message.

payment_tagstring

payment_tag.

status_codestring

statusCode.

messagestring

message.

namestring

name.

acquirer_transaction_idstring

acquirer_transaction_id.

authorization_codestring

authorization_code.

transaction_idstring

transaction_id.

reason_codestring

reason_code.

reason_messagestring

reason_message.

merchant_advice_codestring

merchant_advice_code.

paymentsobject[]

Error details.

Show payments properties
statusstring

Error situation.

error_codestring

Error code.

descriptionstring

Description of the error.

description_detailstring

Detailed description of the error.

brandstring

Brand.

payment_idstring

payment_id.

seller_idstring

seller_id.

amountstring

amount.

currencystring

currency.

order_idstring

order_id.

credit_cancelobject

credit_cancel.

Show credit_cancel properties
canceled_atstring

canceledAt.

messagestring

message.

payment_tagstring

payment_tag.

status_codestring

statusCode.

messagestring

message.

namestring

name.

acquirer_transaction_idstring

acquirer_transaction_id.

authorization_codestring

authorization_code.

transaction_idstring

transaction_id.

reason_codestring

reason_code.

reason_messagestring

reason_message.

merchant_advice_codestring

merchant_advice_code.

combined_idstring

combinedId.

order_idstring

orderId.

seller_idstring

sellerId.

Internal Server Error

messagestring

Detailed error message.

namestring

Name of the module or system in which the error occurred.

status_codeinteger<int32>

HTTP status code of the error.

detailsobject[]

Error details.

Show details properties
statusstring

Error situation.

error_codestring

Error code.

descriptionstring

Description of the error.

description_detailstring

Detailed description of the error.

brandstring

Brand.

payment_idstring

payment_id.

seller_idstring

seller_id.

amountstring

amount.

currencystring

currency.

order_idstring

order_id.

credit_cancelobject

credit_cancel.

Show credit_cancel properties
canceled_atstring

canceledAt.

messagestring

message.

payment_tagstring

payment_tag.

status_codestring

statusCode.

messagestring

message.

namestring

name.

acquirer_transaction_idstring

acquirer_transaction_id.

authorization_codestring

authorization_code.

transaction_idstring

transaction_id.

reason_codestring

reason_code.

reason_messagestring

reason_message.

merchant_advice_codestring

merchant_advice_code.

paymentsobject[]

Error details.

Show payments properties
statusstring

Error situation.

error_codestring

Error code.

descriptionstring

Description of the error.

description_detailstring

Detailed description of the error.

brandstring

Brand.

payment_idstring

payment_id.

seller_idstring

seller_id.

amountstring

amount.

currencystring

currency.

order_idstring

order_id.

credit_cancelobject

credit_cancel.

Show credit_cancel properties
canceled_atstring

canceledAt.

messagestring

message.

payment_tagstring

payment_tag.

status_codestring

statusCode.

messagestring

message.

namestring

name.

acquirer_transaction_idstring

acquirer_transaction_id.

authorization_codestring

authorization_code.

transaction_idstring

transaction_id.

reason_codestring

reason_code.

reason_messagestring

reason_message.

merchant_advice_codestring

merchant_advice_code.

combined_idstring

combinedId.

order_idstring

orderId.

seller_idstring

sellerId.

Request
curl -X POST "https://api.pre.globalgetnet.com/dpm/security-gwproxy/v2/enrolments-initial" \
  -H "Content-Type: application/json" \
  -d '{
  "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"
    }
  }
}'
Response
{
  "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"
    }
  }
}