# 3D Secure (3DS)

This guide explains the integration process for the 3D Secure feature, including the necessary endpoints and webhooks you must 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 the three domains that 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 an e-commerce transaction. Typically, the application forwards customers to their bank to authenticate the payment by entering a one-time SMS code, using biometrics, or using a bank app. 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](/guides/authentication/strong-customer-authentication).

Not all transactions require SCA. To find out more about SCA use cases and their associated authentication methods, see [SCA use cases](/guides/authentication/strong-customer-authentication#use-cases-that-require-2fa).

**3DS with Solaris cards**

Solaris offers the following authentication methods for 3DS. You must access both methods through your application:

* **In-app method:** A biometric factor inside a mobile banking app (in-app push notifications, i.e., device signing).
* **SMS OTP:** A one-time password (OTP) sent to customers via SMS on their verified mobile number.


You must provide both options to your customers. Additionally, you must display the merchant name and the amount to the cardholder during the authentication process.

## Requirements

You must implement the following features in your solution before you can implement 3DS:

1. [Customer onboarding with Digital Banking & Cards](/guides/get-started) (debit, credit, or decoupled)
2. [Device binding](/guides/authentication/device-binding)
3. [Strong Customer Authentication](/guides/authentication/strong-customer-authentication)
4. [Device monitoring](/guides/kyc/device-monitoring)


Only customers who have been successfully onboarded and identified with an active Solaris account and card (debit, credit, or decoupled) can use 3DS.

Additionally, you must subscribe to the following **webhook events**:

* [SCA_CHALLENGE](/api-reference/onboarding/webhooks/webhook-events/paths/sca_challenge/post)
* [DELEGATE_SCA_CANCEL](/api-reference/onboarding/webhooks/webhook-events/paths/delegate_sca_cancel/post)


For more information on subscribing to webhook events, check the [Webhooks guide](/api-reference/webhooks).

## 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 sends a notification to Solaris to authenticate the user.
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 logs into your application to accept the 3DS challenge.
7. Once the customer decides to accept the 3DS challenge, present them with the option in your frontend to authorize via in-app device signing or SMS OTP.
8. Trigger the authentication process by calling **POST Authorize change request** (see below). Use the `delivery_method` requested by the customer.
9. The customer authorizes the transaction by signing the challenge with the device's unrestricted key or the SMS OTP received from Solaris.
10. Confirm the authentication by sending the customer's device signature or SMS OTP to Solaris using **POST Confirm change request** (see below).
11. Solaris sends the cardholder's authentication response to the online merchant via the ACS.
12. The merchant sends the transaction to the Card Processor (CP) for a final confirmed/declined authorization.
13. (**Decline without change request**) If the customer wants to decline the 3DS challenge, call the `POST /v1/cards/3ds/{challenge_id}/decline` endpoint using the `challenge_id` provided in the `SCA_CHALLENGE` webhook payload. This endpoint does not use the change request process.


## Step 1: Webhook notification

When customers initiate an online card payment and the ACS receives the transaction and notifies Solaris, you will 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.

[View the SCA_CHALLENGE webhook payload](/api-reference/onboarding/webhooks/webhook-events/paths/sca_challenge/post)

## Step 2: Authorize change request

### 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:

| Parameter | Description |
|  --- | --- |
| `delivery_method` | The method to deliver the authorization challenge. |
| `device_id` | The ID of the customer's registered device approving the transaction. Only include this property if the `delivery_method` is `device_signing`. |
| `person_id` | The person to whom the SMS OTP should be sent. Only include this property if the `delivery_method` is `mobile_number`. |
| `device_data` | Base64-encoded device data collected using the Seon SDK. Details about how to integrate the Seon SDK can be found in the [Device monitoring guide](/guides/kyc/device-monitoring). |


**Request URL**


```shell
POST /v1/change_requests/{change_request_id}/authorize
```

**Response**

The API returns a change request object with a unique `id`, which you must use in the next API call. If you used **device signing**, then the API will also return the string for the customer's device to sign in the `string_to_sign` property.

[View full API reference](/api-reference/onboarding/device-management#tag/Change-requests/paths/~1v1~1change_requests~1%7Bchange_request_id%7D~1authorize/post)

## Step 3: Notify customer & solve challenge

Send a push notification to the customer informing them that a transaction requires their approval.

When they open your app, offer them an interface for resolving the open 3DS challenge:

* For **device signing**, prompt them to sign the challenge using their device.
* For **SMS OTP**, prompt them to enter the six-digit code they received from Solaris.


### (Device signing only) Collecting the customer's signature

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.

**How to sign:**

1. Create a hash (SHA256) with the `string_to_sign`.
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

Pass the signature string or the six-digit SMS OTP to Solaris by calling the following endpoint. You must add the `change_request_id` to the request URL and supply the following properties in the request body:

| Parameter | Description |
|  --- | --- |
| `device_id` | (If the `delivery_method` was `device_signing`) The ID of the customer's bound device used for authorization. |
| `signature` | (If the `delivery_method` was `device_signing`) The hex-encoded signature generated by signing the `text_to_sign` with the device's public key. |
| `person_id` | (If the `delivery_method` was `mobile_number`) The ID of the person who received the SMS OTP for authorization. |
| `tan` | (If the `delivery_method` was `mobile_number`) The six-digit OTP value that the person received via SMS. |
| `device_data` | Base64-encoded device data collected using the Seon SDK. Details about how to integrate the Seon SDK can be found in the [Device monitoring guide](/guides/kyc/device-monitoring). |


**Request URL**


```shell
POST /v1/change_requests/{change_request_id}/confirm
```

[View full API reference](/api-reference/onboarding/device-management#tag/Change-requests/paths/~1v1~1change_requests~1%7Bchange_request_id%7D~1confirm/post)

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.

## Step 4: Decline a 3DS challenge without change request

If the customer wants to decline the 3DS challenge, you can call the following endpoint to decline the challenge without using the change request process.

### POST Decline a 3DS authentication

Call this endpoint to decline a 3DS challenge and add the `challenge_id` returned in the `SCA_CHALLENGE` webhook payload in the request URL.

**Request example**


```shell
POST /v1/cards/3ds/{challenge_id}/decline
```

[View full API reference](/api-reference/digital-banking/cards#tag/Card-transactions/paths/~1v1~1cards~13ds~1%7Bchallenge_id%7D~1decline/post)

## Testing

Solaris offers several endpoints for testing different 3DS scenarios. These endpoints are only available on **Sandbox**.

### Create test 3DS transaction

This endpoint creates a test 3DS transaction for a card. The API will return a JSON schema containing the HTML for the 3DS challenge screen.

**URL:**


```shell
POST /v1/cards/{card_id}/test_3ds_authentication
```

[View full API reference](/api-reference/digital-banking/cards#tag/Card-transactions-simulation/paths/~1v1~1cards~1%7Bcard_id%7D~1test_3ds_authentication/post)

### Simulate an authorization

This endpoint creates a simulated card authorization for the purpose of testing approval and denial flows.

**URL:**


```shell
POST /v1/cards/{card_id}/simulator/transactions/authorization
```

[View full API reference](/api-reference/digital-banking/cards#tag/Card-transactions-simulation/paths/~1v1~1cards~1%7Bcard_id%7D~1simulator~1transactions~1authorization/post)

### Simulate the settlement of an authorization

This endpoint executes a test card authorization settlement for the given card and `transaction_key` (retrieved from the endpoint described above).

**URL:**


```shell
POST /v1/cards/{card_id}/simulator/transactions/{transaction_key}/settle
```

[View full API reference](/api-reference/digital-banking/cards#tag/Card-transactions-simulation/paths/~1v1~1cards~1%7Bcard_id%7D~1simulator~1transactions~1%7Btransaction_key%7D~1settle/post)

### Simulate an unauthorized settlement

This endpoint creates a simulated unauthorized settlement. It returns a `transaction_key` that corresponds with the settlement.

**URL:**


```shell
POST /v1/cards/{card_id}/simulator/transactions/settle
```

[View full API reference](/api-reference/digital-banking/cards#tag/Card-transactions-simulation/paths/~1v1~1cards~1%7Bcard_id%7D~1simulator~1transactions~1settle/post)

### Simulate an expired card authorization

Use this endpoint to mark a test authorization (created using the [Simulate an authorization endpoint](#simulate-an-authorization)) as expired.

**URL:**


```shell
POST /v1/cards/simulator/authorization/{transaction_key}/expire
```

[View full API reference](/api-reference/digital-banking/cards#tag/Card-transactions-simulation/paths/~1v1~1cards~1simulator~1authorization~1%7Btransaction_key%7D~1expire/post)

## Appendix I: Glossary

* **3DS:** 3D Secure
* **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