3D Secure (3DS)

This guide explains the integration process for the 3D Secure feature, including the necessary endpoints and webhooks you need to integrate into your solution.

Introduction

What is 3DS?

3D Secure (3DS) (also known as payer authentication) is a security protocol that adds an additional layer of protection to online credit and debit card payments. "3DS" refers to three domains which interact using the protocol: the merchant/acquirer domain, the issuer domain, and the interoperability domain.

How does 3DS work?

3DS requires customers to complete an additional verification step with their card issuer during the final stage of checkout in an e-commerce transaction. Typically, customers get forwarded to their bank to authenticate the payment by entering a one-time SMS code, biometrics, bank app, or other authentication methods. Some common examples of 3DS include Verified by Visa, Mastercard SecureCode, and American Express SafeKey.

3DS reduces the risk of fraud and increases protection for both the seller (merchants) and the cardholder (customers). As 3DS payments are considered secure, the customer's bank becomes liable for any fraud, which makes it a powerful tool for online sellers.

European PSD2 and Strong Customer Authentication (SCA) regulations require the use of 3DS for online card payments. PSD2 requires all issuers to apply Strong Customer Authentication (SCA) for 3DS online payments, which includes two-factor authentication (2FA). For more information about how to implement SCA in your solution, see the Strong Customer Authentication guide.

3DS with Solaris cards

Solaris offers the following authentication methods for 3DS:

• In-app method: a biometric factor inside a mobile banking app (in-app push notifications, i.e., device signing), or
• SMS OTP: where the customer enters a one-time password (OTP) received via SMS on their verified mobile number.

3DS In-app implementation

This section describes the authentication flow for the 3DS in-app method. This authentication method integrates a possession and an inherence authentication factor. The customer authenticates the online card transaction within your application using a registered device (possession) and biometrics (inherence).

The customer receives a push notification on their registered device from your app during the checkout process, prompting them to approve or decline the transaction. After approving the transaction in your app, the customer returns to the merchant's app to complete the purchase.

Requirements

To implement the 3DS in-app feature, your solution must meet the following technical prerequisites:

1. Your customers must be successfully onboarded and identified with an active Solaris account and card.
2. Your customers must have a registered device. For more information about how to implement device binding, see the device binding guide.
3. Implement the change request process in your solution. For more information, check the dedicated Strong Customer Authentication guide.
4. Subscribe to the SCA_CHALLENGE and DELEGATE_SCA_CANCEL webhook events. For more information on subscribing to webhook events, check the dedicated guide.

Authentication steps

1. The cardholder initiates the process when paying by card on an e-commerce website.
2. The Access Control Server (ACS) receives the 3DS transaction via the card scheme (e.g., Visa or Mastercard).
3. The ACS checks if authentication is required for the transaction and determines which authentication method to use (in this case, the in-app method).
4. Solaris sends you a notification on the webhook event SCA_CHALLENGE. The webhook payload includes the authenticate_change_request_id attribute, which is the change_request_id value you need to pass to the change request endpoints.
5. Send a push notification to the cardholder's mobile app informing them that they must authorize the 3DS challenge.
6. The customer should log into your application to either accept or decline the 3DS challenge.
7. Once the customer accepts to authorize the 3DS challenge, trigger the authentication process by calling POST Authorize change request.
8. The customer then authorizes the transaction using the unrestricted key.
9. Confirm the authentication by sending the customer's signature on the 3DS challenge to Solaris using POST Confirm change request.
10. Solaris sends the cardholder's authentication response to the online merchant via the ACS.
11. The merchant sends the transaction to the Card Processor (CP) for a final confirmed/declined authorization.

Webhook notification

When customers initiate an online card payment and the ACS receives the transaction and notifies Solaris, you'll receive a notification on the webhook event SCA_CHALLENGE. The payload includes the details of the transaction and the authenticate_change_request_id, which is the change_request_id required in the following steps.

Click here to view a sample SCA_CHALLENGE webhook payload.

POST Authorize change request

After receiving the webhook notification, trigger the change request process by calling the following endpoint. Supply the value of the authenticate_change_request_id property from the webhook payload as the change_request_id in the request URL. Additionally, add the following properties in the request body:

Request URL

POST /v1/change_requests/{change_request_id}/authorize

Request body example

{
  "delivery_method": "device_signing",
  "device_id": "c05b122b-b069-451c-afdd-18fc72c1379b"
}

Example response

The API returns a change request object with a unique ID, which you must use in the next API call.

{
  "id": "b520ce9090c44a989149fe7f2f94a785",
  "string_to_sign": "3045022100bdbebd8ba5e4ea23a4ab3d852cbf0968cbc7319c7c4388e0c54bf34e",
  "status": "AUTHORIZATION_REQUIRED",
  "updated_at": "2021-12-22T15:05:33.634+00:00"
}

Click here to view the full API reference.

Collecting the customer's signature

Next, send a push notification to the customer's device informing them that they must approve or decline a transaction.

The customer's device must sign the string contained in the string_to_sign attribute of the response from the previous API call using its unrestricted key. See the instructions below:

How to sign:

1. Create a hash(SHA256) with the stringtosign.
2. Sign the hash with the device's private key.
3. Encode the signature in ASN.1 format.
4. Hex encode the ASN.1 format signature.

POST Confirm change request

Now pass the signature string to Solaris by calling the following endpoint. You have to add the change_request_id to the request URL and supply the following properties in the request body:

Request URL

POST /v1/change_requests/{change_request_id}/confirm

Request body example

{
  "device_id": "45424a0d-9a67-403a-ab7c-bb8411a708d4",
  "signature": "3045022100bdbebd8ba5e4ea23a4ab3d852cbf0968cbc7319c7c4388e0c54bf34e896d19d802205880fca38bf5450bff73d41c675e1444b8e3c75dc8bf764d5c0e9282bd150ade"
}

Example response

{
  "id": "b520ce9090c44a989149fe7f2f94a785",
  "status": "COMPLETED",
  "updated_at": "2021-12-22T15:05:33.634+00:00",
  "response_body": {
    "id": "69c673883853eafb2da9157de2bdaa05cper"
  },
  "response_code": 202
}

Click here to view the full API reference.

Once the cardholder authorizes the transaction, Solaris sends the cardholder's authentication response to the online merchant via the ACS. Then, the merchant sends the transaction to the Card Processor (CP) for a final confirmation or rejection.

3DS SMS OTP implementation

This section describes the authentication flow for the 3DS SMS OTP method. This authentication method integrates a possession and a knowledge authentication factor. The customer authenticates the online card transaction by entering a six-digit one-time password (OTP) received via SMS on their verified mobile number (possession) on the 3DS page and then answering security questions (knowledge).

Requirements

To implement the 3DS SMS OTP feature, your customers must be successfully onboarded and identified with an active Solaris account, card, and verified mobile number.

Authentication steps

1. The cardholder initiates the process when paying by card on an e-commerce website.
2. The Access Control Server (ACS) receives the 3DS transaction via the card scheme (e.g., Visa or Mastercard).
3. The ACS checks if authentication is required for the transaction and determines the authentication method to use (in this case, the SMS OTP method).
4. The customer is redirected to the 3DS page.
5. Solaris sends an SMS OTP directly to the cardholder's verified mobile number.
6. The cardholder enters the OTP in the 3DS authentication page.
7. The cardholder answers a security question to fulfill the 2FA requirement.
8. Solaris sends the cardholder's authentication response back to the online merchant via the ACS.
9. The merchant sends the transaction to the Card Processor (CP) for a final confirmation or rejection.

First authentication factor: SMS OTP

Solaris sends a six-digit one-time password (OTP) via SMS directly to the cardholder's verified mobile number for the first-factor authentication. The OTP is randomly generated using a secure algorithm and dynamically changes for each authentication challenge.

If the cardholder does not provide a valid OTP within 5 minutes, or if they enter the wrong OTP three times, then the transaction is aborted (i.e., the payment is declined, and the cardholder is redirected back to the merchant). The merchant website will display an error message to indicate that the authentication has failed.

Second authentication factor: Security questions

To achieve the knowledge factor, the customer will then be challenged with a security question. In this challenge, the customer is presented with a list of transactions and must identify which of the transactions they really made. The possible options include:

• The customer is presented with six randomly-generated fake transactions that the cardholder shouldn't recognize.

  • In this case, there will be an "I don't recognize any of these transactions" option.
  • If the cardholder is authenticating a 3DS payment for the first time for their card, then there will be no previous transactions that can be used for validation. Therefore, all six presented transactions will be fake.
• The customer is presented with six transactions, and one of them is a real transaction retrieved from their transaction history.

After three failed verification attempts, or if the cardholder hasn't provided a valid answer within 5 minutes, the transaction will be aborted (i.e., the payment is declined, and the cardholder is redirected back to the merchant). The merchant website will display an error message to indicate that the authentication has failed.

Appendix I: Glossary

• ACS: Access Control Server (external service provider)
• CP: Card processor (external service provider)
• MPI: Merchant Plug-in (an external service provider that merchants use to connect to the servers of card schemes, e.g., Visa or Mastercard)
• OTP: One-time password
• 3DS: 3D Secure