# Strong Customer Authentication

## Introduction

Strong Customer Authentication (SCA) is a regulatory requirement imposed by the [PSD2 guidelines](https://www.eba.europa.eu/regulation-and-policy/payment-services-and-electronic-money/guidelines-on-authorisation-and-registration-under-psd2) on all payment service providers in the European Economic Area (EEA).

PSD2 mandates multi-factor authentication (MFA) to reduce fraud and secure online payments. SCA requires at least **two** of the following three factors:

* **Knowledge (Something you know):** Password, PIN, security question.
* **Possession (Something you have):** Smartphone, hardware token, paired device.
* **Inherence (Something you are):** Fingerprint, FaceID, voiceprint.


### When is SCA required?

You must implement SCA for the following scenarios:

#### 1. Login (Access to Account)

According to PSD2, you must enforce 2FA when the customer logs in. You must also re-authenticate the customer via SCA in the following specific scenarios:

* Accessing the account online for the first time.
* Accessing the account balance without disclosing sensitive payment data.
* Accessing transaction records executed in the last 90 days.
* Accessing transaction records **older than 90 days**.
* Every **180 days** since the last time the customer was authenticated using SCA.


#### 2. Sensitive Data Changes

Any modification to customer data (e.g., changing an address, updating a mobile number) requires 2FA to prevent account takeover fraud.

#### 3. Transaction Authorization

Initiating payments or transfers requires SCA to ensure the customer explicitly authorized the movement of funds.

## Authentication methods & Platform strategy

Solaris offers two methods for 2FA. You must choose the correct method based on your platform.

### 1. SMS OTP (Web)

Solaris sends a 6-digit code via SMS to the customer's verified mobile number.

* **Target Platform:** **Web Applications** (Primary Option).
* **Pros:** Works on any device with a SIM card; no app installation required.
* **Cons:** Higher cost; dependency on mobile network signal.


### 2. Device Signing (Mobile)

Solaris creates a cryptographic challenge that must be signed by a private key stored in the secure hardware of the customer's smartphone.

* **Target Platform:** **Mobile Apps** (Mandatory).
* **Pros:** Highest security; lower cost (no SMS fees); better UX (Biometrics); works offline (signing happens locally).
* **Cons:** Requires the customer to have [bound their device](/guides/authentication/device-binding) first.
* **Binding Options:** Customers can bind their device using a traditional SMS flow or by scanning a provided **QR Code (Activation Code)**.


Platform Requirement
* **Web Interfaces:** **SMS OTP** is an option.
* **Mobile Apps:** You **should** use **Device Binding** (Device Signing) as the primary SCA method.


## Use cases and key requirements

Different actions require different levels of security. You must use the correct **Key Type** (Restricted vs. Unrestricted) based on the risk level of the action.

Customers authorize actions using one of two key types:

* **Unrestricted keys:** Do not require specific user authentication to sign a request. These are typically used for background processes or low-risk actions.
* **Restricted keys:** Require user authentication via biometrics (e.g., Touch ID, Face ID) to access the private key.
  * **iOS:** Combine `privateKeyUsageflag` with `userPresence` or `touchIDAny`.
  * **Android:** Use `setUserAuthenticationParameters()`.


### Requirement matrix

The table below lists all use cases requiring SCA and the supported methods.

| Use case | Device Signing Key Type | SMS OTP Supported? |
|  --- | --- | --- |
| **Login** | Unrestricted | Yes |
| **Device Binding** | N/A | Yes |
| **Mobile Number Verification** | N/A | Yes |
| **Change Data:** Add/Change Mobile Number | N/A | Yes |
| **Change Data:** Personal details (Address, Name) | Restricted | Yes |
| **Change Data:** Delete Mobile Number | Restricted | Yes |
| **Business:** Update business details | Restricted | Yes |
| **Business:** Add/Delete Authorized Person | Restricted | Yes |
| **Cards:** 3D Secure | Unrestricted | Yes |
| **Cards:** Push Provisioning | Restricted | Yes |
| **Cards:** Secure View (PIN/PAN) | Unrestricted | **No** |
| **Payments:** SEPA Credit Transfer | Restricted | Yes |
| **Payments:** Standing Order (create, update, cancel) | Restricted | Yes |
| **Payments:** Timed Order (create, cancel) | Restricted | Yes |
| **Payments:** Trusted IBAN (add, delete) | Restricted | Yes |
| **Payments:** Batch Orders | Restricted | Yes |
| **Cash:** Viacash operations | Restricted | Yes |
| **Clearing:** Credit/Debit Transactions* | Restricted | Yes |


**If the Clearing Profile has `customer_authentication: true`*

## Implement SMS OTP

### Prerequisites

* The customer must have a verified mobile number.
* See: [Verify mobile number](/guides/get-started/digital-banking/onboard-person#step-2-verify-mobile-number).


### Login via SMS OTP

**Step 1: Create SMS challenge**
Call the endpoint to send an SMS to the customer's verified number.


```shell
POST /v1/mfa/challenges/sms
```

**Payload:**


```json
{
  "person_id": "ec3d16cbc106f481b72d881d90c89cc5cper"
}
```

**Step 2: Verify OTP**
The customer enters the 6-digit code in your UI. Send it to Solaris to verify.


```shell
PUT /v1/mfa/challenges/sms/{sms_id}
```

* [API Reference: SMS Challenges](/api-reference/onboarding/device-management/#tag/SMS-challenges)


## Implement Device Signing

Device signing uses the cryptographic keys generated during [Device Binding](/guides/authentication/device-binding).

### Login via device signing

**Security Requirement:** `Unrestricted` Key.


```mermaid
sequenceDiagram
    participant C as Customer
    participant App as Your Solution
    participant S as Solaris API

    Note over C, App: Initiate Login
    App->>S: POST /mfa/challenges/devices (device_id)
    S-->>App: Challenge String (string_to_sign)
    
    Note over C, App: Sign with UNRESTRICTED Key
    App->>App: Hash(string_to_sign) + Sign
    
    App->>S: PUT /mfa/challenges/devices/{id} (signature)
    
    alt Signature Valid
        S-->>App: 204 Success (Login Approved)
        App->>C: User Logged In
    else Invalid
        S-->>App: 400 Error (Login Failed)
    end
```

**Step 1: Create challenge**
Request a challenge for a specific bound device (`device_id`).


```shell
POST /v1/mfa/challenges/devices
```

**Payload:**


```json
{
  "device_id": "6642d15e-8f6b-4d28-9186-cdd61d80032a"
}
```

**Response:** Returns a `string_to_sign` and a challenge `id`.

**Step 2: Sign and verify**
Your app must:

1. Calculate `SHA256` hash of the `string_to_sign`.
2. Sign the hash using the **Unrestricted** private key on the device.
3. Submit the signature to the verification endpoint.



```shell
PUT /v1/mfa/challenges/devices/6642d15e-8f6b-4d28-9186-cdd61d80032a
```

* [API Reference: Device Signing](/api-reference/onboarding/device-management/#tag/Device-signing-challenges)


## The Change Request process

Solaris uses a standard **Change Request** flow for sensitive actions (e.g., updating personal data, making a payment). This ensures that a resource is not modified until the customer explicitly authorizes it via SCA.

### Generic Authorization Flow


```mermaid
sequenceDiagram
    participant C as Customer
    participant App as Your Solution
    participant S as Solaris API

    Note over C, App: 1. Request Action (e.g. Payment)
    App->>S: POST /resource (e.g. /sepa_credit_transfers)
    S-->>App: 202 Accepted (Status: AUTHORIZATION_REQUIRED)
    Note right of S: Returns "change_request_id"

    Note over App, S: 2. Trigger Authorization
    App->>S: POST /change_requests/{id}/authorize
    Note right of App: Method: SMS or Device Signing
    S-->>App: 200 OK (Status: CONFIRMATION_REQUIRED)
    S-->>C: Send Challenge (SMS or Device)

    Note over App, S: 3. Confirm Challenge
    C->>App: Input OTP or Approve on Device
    App->>S: POST /change_requests/{id}/confirm
    
    alt Valid SCA
        S-->>App: 200 OK (Status: COMPLETED)
        S-->>S: Execute Resource Change
        App->>S: GET /resource (Verify update)
    else Invalid
        S-->>App: 400 Error
    end
```

### Data Change via Device Signing

If you are using Device Signing for sensitive data changes, you must use the **Restricted Key** and enforce **Biometric Approval**.


```mermaid
sequenceDiagram
    participant C as Customer
    participant App as Your Solution
    participant S as Solaris API

    Note over C, App: Initiate Data Change
    App->>S: PATCH /v1/persons/{id}
    S-->>App: 202 Accepted (Status: AUTHORIZATION_REQUIRED)
    Note over S: Returns "change_request_id" & "string_to_sign"

    Note over C, App: Request Biometric Approval
    C->>App: Approve via Biometrics (FaceID/TouchID)
    
    Note over App: Sign "string_to_sign" with RESTRICTED Key
    App->>App: Hash(string_to_sign) + Sign

    App->>S: POST /change_requests/{id}/confirm (signature)
    
    Note over S: Verify Signature with RESTRICTED Public Key

    alt Signature Valid
        S-->>App: 200 OK (Change Succeeds)
        S-->>S: Execute Data Update
    else Invalid
        S-->>App: 400 Error (Change Failed)
    end
```

### Step 1: Initial request

When you call a sensitive endpoint (e.g., `PATCH /v1/persons/{id}`), Solaris does not update the resource immediately. Instead, it returns a **202 Accepted** response containing a Change Request ID.

**Example Response:**


```json
{
  "id": "b520ce9090c44a989149fe7f2f94a785",
  "status": "AUTHORIZATION_REQUIRED",
  "url": ":env/v1/change_requests/b520ce9090c44a989149fe7f2f94a785/authorize"
}
```

### Step 2: Authorize (Trigger SCA)

Call the authorize endpoint to select the 2FA method.


```shell
POST /v1/change_requests/b520ce9090c44a989149fe7f2f94a785/authorize
```

**Payload for SMS:**


```json
{
  "person_id": "ec3d16cbc106f481b72d881d90c89cc5cper",
  "delivery_method": "mobile_number"
}
```

**Payload for Device Signing:**


```json
{
  "person_id": "ec3d16cbc106f481b72d881d90c89cc5cper",
  "delivery_method": "device_signing",
  "device_id": "6642d15e-8f6b-4d28-9186-cdd61d80032a"
}
```

### Step 3: Confirm

Submit the customer's input to finalize the change.


```shell
POST /v1/change_requests/b520ce9090c44a989149fe7f2f94a785/confirm
```

**Payload for SMS:**


```json
{
  "person_id": "ec3d16cbc106f481b72d881d90c89cc5cper",
  "tan": "123456"
}
```

**Payload for Device Signing:**


```json
{
  "device_id": "6642d15e-8f6b-4d28-9186-cdd61d80032a",
  "signature": "3045022100bdbebd8ba5e4ea23a4ab3d852cbf0968cbc7319c7c4388e0c54bf34e896d19d802205880fca38bf5450bff73d41c675e1444b8e3c75dc8bf764d5c0e9282bd150ade"
}
```

Once confirmed successfully, the resource (e.g., the address change or the payment) is executed immediately.

## What's next?

Now that you have implemented Strong Customer Authentication, you are ready to use the core banking features that require it.

**Start building:**

* **[Accounts & Balances](/guides/digital-banking/account-management/):** Open accounts and retrieve transaction history.
* **[SEPA Transfers](/guides/digital-banking/sepa-transfers/):** Execute payments (requires SCA).
* **[Cards](/guides/cards/creation-and-servicing/):** Issue and manage cards.