# 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](/guides/authentication/strong-customer-authentication/).

Please note that not all transactions require SCA. To find out more about SCA
use cases and their associated authentication methods, see the [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. Both methods are
accessed 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 are required to 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/#tag/Webhook-events/paths/sca_challenge/post)
- [DELEGATE_SCA_CANCEL](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/delegate_sca_cancel/post)


For more information on subscribing to webhook events, check the dedicated [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 should log 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](#post-authorize-change-request). Use the `delivery_method` requested
by the customer.
9. The customer then 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](#post-confirm-change-request).
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](/api-reference/digital-banking/cards/#tag/Card-transactions/paths/~1v1~1cards~13ds~1%7Bchallenge_id%7D~1decline/post) 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'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.](/api-reference/onboarding/webhooks/#tag/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.

[Click here to view the 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

Now you must send a push notification to the customer informing them that a
transaction requires their approval.

When they open your app, you should 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. See the instructions below:

**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

Now pass the signature string or the six-digit SMS OTP 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:

| 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
```

[Click here to view the 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
```

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

## Testing

Solaris offers a number of endpoints for testing different 3DS scenarios. Note that 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
```

[Click here to view the 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 & denial flows.

**URL:**


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

[Click here to view the 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
```

[Click here to view the 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
```

[Click here to view the 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
```

[Click here to view the 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