SCA and 3DS 2

The information provided in this topic is intended for pre-release informational purposes only and should be used to understand the potential scope of implementation work needed to support 3DS 2 in your PaymentsOS transaction flows. All functionality described in this document is currently in the design phase of the development lifecycle and may thus be changed or updated without notice.

Availability Information

Support for 3DS 2 through PaymentsOS will be available soon. Meanwhile, you may use the information below to familiarize yourself with 3DS 2 at a high-level and get ready for transitioning your implementation to support 3DS 2 in your transaction flow. You can also read our blog post for a more in-depth overview of Strong Customer Authentication (SCA) and 3DS 2.

Introducing Strong Customer Authentication and 3DS 2

Strong Customer Authentication (SCA) is part of the PSD2 (Payment Services Directive) regulation in Europe. SCA aims to increase the security of electronic payments by requiring customers to authenticate themselves based on the use of elements categorized as knowledge (i.e. something only the user knows), possession (i.e. something only the user possesses) and inherence (i.e. something the user is).

One of the solutions for providing SCA, is 3DS 2 (also known as EMV 3D Secure). As the successor to 3DS 1, it has been designed to provide for a more secure and user-friendly authentication experience. With 3DS 2, data (such as device information) transmitted in the background is mostly enough to authenticate without an extra step for the customer. It’s only when the provided information does not suffice to determine the risk-level of the transaction that an extra authentication step may be required.

Where 3DS 1 Fell Short

In a 3DS 1 flow, you redirect the customer to an authentication page on their bank’s website, where they are prompted to enter a password associated with the card or a verification code sent to their phone. While it is a solid authentication step, this redirect flow is rather clunky (it's not supported natively in app and in web flows) and is confusing to customers. As a result, legitimate customers drop out of the payment flow thereby impacting your acceptance rates and bottom line.

Exemptions to Strong Customer Authentication

There are circumstances in which you may want to exempt a user from an SCA flow. One example would be a merchant-initiated transaction (MIT) with a user's stored card credentials (in which case the SCA flow has already been completed as part of the consent transaction). Other examples include transactions identified as low-risk or transactions with a low value.

Exempting users from an SCA flow is useful since it increases the chance that the transaction will proceed frictionless (that is, without an additional authentication step) and thus decreases user drop-outs. To exempt a user from an SCA flow, you may need to indicate your intention to do so in the Authorize or Charge request. Bear in mind that the decision of whether to grant the exemption lies with the card issuer. If granted, the chargeback liability shifts back to you (as the merchant).

Note

The provider you are transacting against may offer fraud protection services for analyzing a transaction's risk level.

3DS 2 Transaction Flows

You're most likely curious to understand the implications of 3DS 2 for your transaction flow. The required implementation depends on whether you're using an external MPI (merchant plug-in) to authorize a card using 3DS, or whether this is done during the PaymentsOS transaction flow:

  • If you use an external MPI to authorize a card using 3DS 2, then you simply pass the 3DS data returned from the external MPI in the three_d_secure_attributes.external object of an Authorize or Charge request. See 3DS External Fields for a list of fields you can pass.

  • If the 3DS 2 flow is part of the PaymentsOS transaction flow, then you can pass all relevant information in the three_d_secure_attributes.internal object of an Authorize or Charge request and handle the remainder of the 3DS 2 authentication process as explained below. Refer to 3DS Internal Fields for a list of fields you can pass.

Note

If you use an external MPI (merchant plug-in) to authorize a card using 3D Secure, then you can pass the 3DS data returned from the MPI in the object object of a Create Authorization or Create Charge request. However, not all the providers you transact against may be able to receive this data. You should thus configure a route rule to direct the request to a provider that can process data received from an external 3DS service. For more information, see Routing Transactions to a Provider Supporting External 3DS

3DS 2 Internal Transaction Flows

So let's take a closer look at the 3DS transaction flow, when 3DS is part of the PaymentsOS transaction flow. The response received from the issuer following your initial Authorization or Charge request, determines the type of flow you must invoke:

  • 3DS data collection flow: In this flow, data (such as device information) transmitted in the background is enough to authenticate without an extra step for the customer.

  • 3DS data collection and challenge flow: This flow is the complete 3DS flow. It is similar to the 3DS data collection flow but includes an additional authentication step (challenge) that will be invoked if the information provided in the data collection step does not suffice to determine the risk-level of the transaction.

  • 3DS challenge only flow: In this flow, the customer is immediately redirected to an authentication step (challenge).

Notes:

  • In some cases you may receive a synchronous response of Succeed or Failed when invoking the initial Authorize or Charge request (for instance, if the transaction was exempted from SCA). In this case, proceed with a regular transaction flow.
  • The flows above are flows that you handle yourself. However, in some cases PaymentsOS and some providers may also handle the entire 3DS flow for you. For more information, see 3DS Proxy Flow.

Let 's take a look at each of those flows in more detail.

3DS Data Collection Flow

In this flow, device data is used to authenticate the customer. This flow is frictionless, in that authentication occurs under the hood and no extra authentication step is needed for the customer.

The following image illustrates the 3DS Data Collection flow: 3DS Data Collection Flow The flow is as follows:

  1. Create a new Authorize or Charge request.

    In the three_d_secure_attributes.internalobject, pass in additional information that will help the card issuer assess the fraud risk level of the transaction. The response will include a redirection resource, indicating that data collection is required. The authorization will have a status of Pending.

  2. Initiate the data collection process and pass the data to the issuer

    To initiate the data collection process, you must create a JSON object holding a notification URL field (to which the issuer will send the completion status of the data collection process) and a 3DS transaction ID field. Then format the object using Base64 encoding and post it in a hidden iFrame to the redirection URL received in the response of the Authorize or Charge request (we will provide a code snippet to help you collect this information). Under the hood, a communication session will be opened to the issuer and the issuer will collect the browser or device information from the user. The device or browser information will be used in combination with the data passed in the three_d_secure_attributes.internal object to authorize the payment (see the next step).

  3. After receiving a notification from the card issuer indicating that the analysis of the user's device or browser information has been completed (or following a timeout) invoke the POST /payments/{payment_id}/authorizations/{authorization_id}/authentication-flows request to continue the authentication process (note that this is a new endpoint that will be added to the PaymentsOS API).

  4. When authentication is completed, we will update the status of the Authorization or Charge request.

3DS Data Collection and Challenge Flow

This flow is the complete 3DS flow. It is similar to the 3DS data collection flow but includes an additional authentication step (challenge) that will be invoked if the information provided in the data collection step does not suffice to determine the risk-level of the transaction.

The following image illustrates the 3DS Data Collection and Challenge flow:

3DS Data Collection and Challenge Flow The flow is as follows:

  1. Complete the 3DS data collection flow until step 3. The response of this step will indicate that a challenge is required and will include a challenge URL.

  2. Open the challenge URL to allow the user to complete the additional authentication step. After the user completed the step, we will redirect the user to the merchant_site_url.

3DS Challenge Only Flow

In this flow, the customer is immediately redirected to an authentication step (challenge).

The following image illustrates the 3DS Challenge Only flow:

3DS Challenge Flow

The steps in the flow are as follows:

  1. Create a new Authorize or Charge request. In the three_d_secure_attributes.internal object, pass in additional information that will help the card issuer assess the fraud risk level of the transaction. Also pass in a merchant_site_url, to which the user will be redirected when authentication is completed. The response will indicate that a challenge is required and will include a challenge URL. The authorization will have a status of Pending.

  2. Open the challenge URL to allow the user to complete the additional authentication step. After the user completed the step, we will redirect the user to the merchant_site_url.

3DS Proxy Flow

A 3DS Proxy Flow is a 3DS flow handled in full by PaymentsOS and the provider that you transact against (if supported by the provider).

Note

This flow will be supported by specific providers only.

The following image illustrates the 3DS Proxy flow: 3DS Proxy Flow

The steps in the flow are as follows:

  1. Create a new Authorize or Charge request. In the three_d_secure_attributes.internal object, pass in additional information that will help the card issuer assess the fraud risk level of the transaction. Also pass in a merchant_site_url, to which the user will be redirected when authentication is completed.

    The response will indicate that a redirect is required and will include a redirection URL. The authorization will have a status of pending.

  2. Open the redirection URL to allow the 3DS proxy to handle the 3DS flow.

After the 3DS proxy completed the 3DS flow, we will redirect the user to the merchant_site_url.

Setup and Configuration Considerations

When implementing your 3DS 2 flow, you should take the following into account:

  • PaymentsOS may not yet a support 3DS 2 flow with all providers. We thus strongly recommend you configure routing rules in your PaymentsOS account to route payments to a provider supporting 3DS 2 authentication. Refer to the relevant provider guide to determine whether 3DS 2 is supported.

  • There may be some additional fields (such as billing and shipping address) in a Create Payment request that are required for a 3DS flow.

3DS 2.0 API Fields

This section lists all fields that will be added to the PaymentsOS API for 3DS Internal (initiated as part of the PaymentsOS transaction flow) and 3DS External (from an external API) authentication flows.

Note that there may be some existing fields (such as billing and shipping address) and additional fields in a Create Payment request that are required for a 3DS flow. There may also be additional provider-specific fields that you will need to pass in a Create Authorize or Create Charge request.

3DS External Fields

Required fields: cavv, eci_flag, encoding.

Field Description
three_d_secure_version(string) Indicates the version of the 3D Secure protocol. Format: 1.x.x or 2.x.x.
xid(string) The unique identifier for the transaction. Only applicable if the three_d_secure_version is 1.x.x. You must ensure that the encoding you specify in the encoding field is applied to this field.
ds_xid(string) 3DS Dynamic Server transaction ID. Must be passed if the three_d_secure_version is 2.x.x.
encoding(string) Encoding of the authentication - 'HEX' or 'BASE64'. You must ensure that the encoding you specify is applied to the xid and cavv fields.
Enum: HEX, BASE64
cavv(string) The unique Cardholder Authentication Verification Value (CAVV) associated with the transaction, provided by the card issuer. You must ensure that the encoding you specify in the encoding field is applied to this field.
eci_flag(string) The Electronic Commerce Indicator (ECI) associated with the transaction. This indicator is returned by the card processing networks (Visa, MasterCard, and JCB) to indicate the authentication results of your customer's credit card payment on 3D Secure. Can be one of the following values:
00: Returned by MasterCard. Authentication is unsuccessful or not attempted. The credit card is either a non-3D card or card issuing bank does not handle it as a 3D transaction.
01: Returned by MasterCard. Either cardholder or card issuing bank is not 3D enrolled. 3D card authentication is unsuccessful.
02: Returned by MasterCard. Both cardholder and card issuing bank are 3D enabled. 3D card authentication is successful.
05: Returned by Visa ,JCB and Amex. Both cardholder and card issuing bank are 3D enabled. 3D card authentication is successful.
06: Returned by Visa, JCB and Amex. Either cardholder or card issuing bank is not 3D enrolled. 3D card authentication is unsuccessful.
07: Returned by Visa, JCB and Amex. Authentication is unsuccessful or not attempted. The credit card is either a non-3D card or card issuing bank does not handle it as a 3D transaction.

3DS Internal Fields

Field Description
device_channel(string) The channel through which the transaction was initiated. Can be one of the following values:
01: The transaction was initiated through the mobile SDK.
02: The transaction was initiated through a web browser.
03: 3DS Requestor Initiated. The 3DS Requestor Initiated device channel allows 3-D Secure authentication without the presence of the cardholder.
Enum: 01, 02, 03
work_phone(string) The cardholder's work phone number (without the country code).
mobile_phone(string) The cardholder's mobile phone number (without the country code).
home_phone(string) The cardholder's home phone number (without the country code).
mobile_phone_country(string) The country code of the mobile phone number. Maximum length: 3 characters.
home_phone_country(string) The country code of the home phone number. Maximum length: 3 characters.
work_phone_country(string) The country code of the work phone number. Maximum length: 3 characters.
address_match(string) Indicates whether the cardholder's shipping address and billing address are identical. Either true (shipping address matches billing address) or false (shipping address does not match billing address).
product_code(string) The product code. Can be one of the following values:
01: Goods/Service Purchase
03: Check Acceptance
10: Account Funding
11: Quasi-Cash Transaction
28: Prepaid Activation and Load
Enum: 01, 03, 10, 11, 28
shipping_method_indicator(string) The shipping method selected by the customer. Can be one of the following values:
01: Ship to cardholder billing address
02: Ship to another verified address on file with merchant
03: Ship to address that is different than billing address
04: Ship to store (store address should be populated on request)
05: Digital goods
06: Travel and event tickets, not shipped
07: Other
Enum: 01, 02, 03, 04, 05, 06, 07
delivery_time_frame(string) The delivery time frame. Can be one of the following values:
01: Electronic delivery
02: Same day shipping
03: Overnight shipping
04: Two or more days shipping
Enum: 01, 02, 03, 04
reorder_indicator(string) Indicates whether the cardholder is reordering previously purchased merchandise. Can be one of the following values:
01: First time ordered
02: Reordered
Enum: 01, 02
pre_order_indicator(string) Indicates whether the cardholder is placing an order for an item with a future availability or release date. Can be one of the following values:
01: Merchandise available
02: Future availability
Enum: 01, 02
pre_order_date(string) Expected date that a pre-ordered purchase will be available. Format: yyyymmdd.
account_age_indicator(string) Indicates how long the card holder has had the account. Can be one of the following values:
01: No Account
02: Created during transaction
03: Less than 30 days
04: 30-60 days
05: More than 60 days
Enum: 01, 02, 03, 04, 05
account_create_date(string) The date on which the cardholder opened the account. Format: yyyymmdd.
account_change_indicator(string) Indicates the amount of time passed since the last change to the cardholder account. Changes include updating the shipping address, creating a new payment account or adding a new user. Can be one of the following values:
01: Changed during transaction
02: Less than 30 days
03: 30-60 days
04: More than 60 days
Enum: 01, 02, 03, 04
account_change_date(string) The date on which the cardholder's account was last changed. Changes include updating the shipping address, creating a new payment account or adding a new user. Format: yyyymmdd.
account_pwd_change_indicator(string) Indicates the amount of time passed since the cardholder changed or reset the account password.
Can be one of the following values:
01: No change
02: Changed during transaction
03: Less than 30 days
04: 30-60 days
05: More than 60 days
Enum: 01, 02, 03, 04, 05
account_pwd_change_date(string) The date on which the cardholder's account password was last changed or reset. Format: yyyymmdd.
account_addtional_information(string) Additional information about the account.
shipping_address_usage_indicator(string) Indicates when the shipping address specified in the transaction was first used.
Can be one of the following values:
01: This transaction
02: Less than 30 days
03: 30-60 days
04: More than 60 days
Enum: 01, 02, 03, 04
shipping_address_usage_date(string) The date on which the shipping address specified in the transaction was first used. Format: yyyymmdd.
transaction_count_day(string) Number of transactions (successful or abandoned) for this cardholder account within the last 24 hours.
transaction_count_year(string) Number of transactions (successful or abandoned) for this cardholder account within the last year.
add_card_attempts_day(string) Number of add card attempts in the last 24 hours.
account_purchases_six_months(string) Number of purchases with this cardholder account during the previous six months.
fraud_activity(string) Indicates whether the merchant experienced suspicious activity (including previous fraud) on the account.
Can be one of the following values:
01: No suspicious activity
02: Suspicious activity observed
Enum: 01, 02
shipping_name_indicator(string) Indicates if the cardholder name on the account is identical to the shipping name used for the transaction. Can be one of the following values:
01: Account name identical to shipping name
02: Account name different than shipping name
Enum: 01, 02
payment_account_indicator(string) Indicates the length of time that the payment account was enrolled in the merchant account. Can be one of the following values:
01: No account (guest checkout)
02: During the transaction
03: Less than 30 days
04: 30-60 days
05: More than 60 days
Enum: 01, 02, 03, 04, 05
payment_account_agex(string) The date on which the payment account was added to the cardholder account. Format: yyyymmdd.
requestor_authentication_method(string) Mechanism used by the cardholder to authenticate to the 3DS requester. Can be one of the following values:
01: No authentication occurred (e.g. Guest Checkout)
02: Login to the cardholder account at the Merchant system using Merchant system credentials
03: Login to the cardholder account at the Merchant system using a Federated ID
04: Login to the cardholder account at the Merchant system using Issuer credentials
05: Login to the cardholder account at the Merchant system using third-party authentication
06: Login to the cardholder account at the Merchant system using FIDO Authenticator
Enum: 01, 02, 03, 04, 05, 06
requestor_authentication_timestamp(string) The date and time of the cardholder authentication. In UTC. Format: YYYYMMDDHHMM.
requestor_authentication_data(string) Data that documents and supports a specific authentication process that was sent in the requestor_authentication_method field.
prior_authentication_data(string) Data that the Access Control Server (ACS) can use to verify the authentication process.
prior_authentication_method(string) Mechanism used by the Cardholder to previously authenticate to the 3DS Requestor. Can be one of the following values:
01: Frictionless authentication occurred by ACS
02: Cardholder challenge occurred by ACS
03: AVS verified
04: Other issuer methods
Enum: 01, 02, 03, 04
prior_authentication_timestamp(string) Date and time of the prior cardholder authentication. In UTC. Format: YYYYMMDDHHMM.
prior_authentication_ref(string) This data element contains a Access Control Server (ACS) Transaction ID for a prior authenticated transaction For example, the first recurring transaction that was authenticated with the cardholder.
purchase_date_time(string) Date of original purchase. Format: YYYYMMDDHHMMSS.
recurring_end_date(string) The date after which no further recurring authorizations should be performed. Format: YYYYMMDD.
recurring_frequency(integer) Indicates the minimum number of days between recurring authorizations.
browser_header(string) The exact content of the HTTP accept headers sent from the cardholder's browser.
Note: This field is required if the 3ds channel is a browser.
browser_java_enabled(boolean) Represents the ability for the cardholder to execute Java. Either true or false.
Note: This field is required if the 3ds channel is a browser.
Enum: true, false
browser_language(string) Value represents the browser language as defined in IETF BCP47.
Note: This field is required if the 3ds channel is a browser.
browser_color_depth(string) The bit depth of the color palette for displaying images, in bits per pixel.
Note: This field is required if the 3ds channel is a browser.
browser_screen_height(string) The total height of the cardholder's screen in pixels.
Note: This field is required if the 3ds channel is a browser.
browser_screen_width(string) The total width of the cardholder's screen in pixels.
Note: This field is required if the 3ds channel is a browser.
browser_time_zone(string) The time differenece between UTC time and the cardholder's browser local time, in minutes.
Note: This field is required if the 3ds channel is a browser.
challenge_indicator(string) Expresses a preference regarding the challenge flow for a transaction. Can be one of the following values:
01: No preference
02: No challenge requested
03: Challenge requested (3DS Requestor Preference)
04: Challenge requested (Mandate)
Enum: 01, 02, 03, 04
challenge_window_size(string) An override field that you can pass in to set the challenge window size to display to the end cardholder. The Access Control Server (ACS) will reply with content that is formatted appropriately to this window size to allow for the best user experience. The sizes are width x height in pixels of the window displayed in the cardholder browser window. Can be one of the following values:
01: 250x400
02: 390x400
03: 500x600
04: 600x400
05: Full page
Enum: 01, 02, 03, 04, 05
sdk_app_id(string) Universally unique ID created upon all installations and updates of the merchant App on a customer device. This is newly generated and stored by the 3DS SDK for each installation or update. The field must have a canonical form as defined in IETF RFC 4122. Note: This field is required if the 3ds channel is a mobile SDK.
Pattern: [0-9azA-Z]
sdk_encrypted_data(string) JWE object, as a string containing data encrypted by the SDK for the DS to decrypt. The field is sent from the SDK. The data will be present when sending to DS, but not present from DS to ACS.
Note: This field is required if the 3ds channel is a mobile SDK.
Pattern: [0-9azA-Z]
sdk_max_timeout(string) The maximum amount of time (in minutes) for all exchanges. The value must be greater than or equal to 05.
Note: This field is required if the 3ds channel is a mobile SDK. Pattern: [0-9]
sdk_reference_number(string) Identifies the vendor and version of the 3DS SDK that is integrated in a merchant app, assigned by EMVCo when the 3DS SDK is approved.
Note: This field is required if the 3ds channel is a mobile SDK.
Pattern: [0-9a-z]
sdk_transaction_id(integer) Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction. The field must have a canonical form as defined in IETF RFC 4122.
Note: This field is required if the 3ds channel is a mobile SDK.
Pattern: [0-9]
sdk_interface(integer) Specifies the SDK Interface types that the device supports for displaying specific challenge user interfaces within the SDK.
Can be one of the following value:
01: Native
02: HTML
03: Both
Enum: 01, 02, 03
sdk_ui_type(integer) Contains a list of all UI types that the device supports for displaying specific challenge user interfaces within the SDK. To specify multiple values, pass as a comma-separated list.
Can be one of the following value:
01: Text
02: Single select
03: Multi select
04: OOB
05: HTML Other (valid only for HTML UI)
sdk_ephemeral_public_key(integer) Public key component of the ephemeral key pair generated by the 3DS SDK and used to establish session keys between the 3DS SDK and ACS.
Pattern: [0-9azA-Z]

results matching ""

    No results matching ""