# Mobile number management

## Overview

Creating and verifying a mobile number for your customer is a crucial step in
the [customer onboarding process](/guides/get-started/digital-banking/onboard-person#step-2-create-and-verify-mobile-number).
With a verified mobile number, customers can use SMS OTPs to complete
[two-factor authentication (2FA) challenges](/guides/authentication/strong-customer-authentication).

This guide explains how Solaris handles customers' mobile numbers and
contains a list of standardized SMS messages to send to your customers in
various situations.

note
Verified mobile numbers are **required** for customers in all branches.

## How Solaris stores mobile numbers

The Solaris API represents a customer's mobile number in the form of a
`mobile_number` resource, which is a **separate resource** from the `person`
resource. The `mobile_number` resource has a set of dedicated API endpoints.

The `person` resource has a `mobile_number` attribute. Note that this is not linked to the respective `mobile_number` resource. Your solution should always use the `mobile_number` resource instead of the `mobile_number` attribute on the `person` resource.

Each person may only have **one verified mobile number.** If you attempt to add
another mobile number to a person with a verified mobile number, then the API
will respond with a `409` error.

On every endpoint, Solaris' API sanitizes mobile numbers before validating
them against the [E.164 standard](https://en.wikipedia.org/wiki/E.164). You
should always use the mobile number returned by our API.

## SMS OTP lifecycle

Solaris enables customers to use SMS OTP as a method for authentication
two-factor authentication (2FA) challenges for actions such as logging in and
completing [change requests](/guides/authentication/strong-customer-authentication#change-request).

See the [Strong Customer Authentication guide](/guides/authentication/strong-customer-authentication/#sms-otp)
for information about how to implement SMS OTP in your solution.

## How to add a mobile number for a customer

To add a mobile number for your customer:

1. Collect the customer's mobile number in a text input in your frontend.
2. Call the [POST Create mobile number endpoint](/api-reference/onboarding/persons/#tag/Person-mobile-numbers/paths/~1v1~1persons~1%7Bperson_id%7D~1mobile_number/post) to create the `mobile_number` resource.
3. Call the [POST Authorize mobile number endpoint](/api-reference/onboarding/persons/#tag/Person-mobile-numbers/paths/~1v1~1persons~1%7Bperson_id%7D~1mobile_number~1authorize/post) to send an SMS OTP to the customer.
4. Collect the SMS OTP from the customer in your frontend and pass it to Solaris using the [POST Confirm mobile number endpoint](/api-reference/onboarding/persons/#tag/Person-mobile-numbers/paths/~1v1~1persons~1%7Bperson_id%7D~1mobile_number~1confirm/post).


[Click here for detailed instructions on this process.](/guides/get-started/digital-banking/onboard-person#step-2-create-and-verify-mobile-number)

## How to update a customer's mobile number

To update a customer's mobile number:

1. Call the [DELETE Remove mobile number endpoint](/api-reference/onboarding/persons/#tag/Person-mobile-numbers/paths/~1v1~1persons~1%7Bperson_id%7D~1mobile_number/delete) to remove their existing mobile number. This will trigger the **change request** process.
2. Repeat the steps described in the [get started guide](/guides/get-started/digital-banking/onboard-person#step-2-create-and-verify-mobile-number) to add a new mobile number for the customer.


note
If you customer cannot change their phone number on their own (e.g., because they lost their phone), then please contact Customer Support.

## Mobile number webhooks

Please implement the following webhooks related to mobile number events:

- [PERSON_MOBILE_NUMBER_CREATED](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/person_mobile_number_created/post): A mobile number was created for a customer, but has not yet been verified.
- [PERSON_MOBILE_NUMBER_DELETED](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/person_mobile_number_deleted/post): A customer's mobile number was deleted.


### List of SMS OTP texts

This table contains standardized texts to send to customers in SMS OTP messages.
You may not deviate from these texts without Solaris' express permission.

Note the use of `variables` throughout the text. Substitute each `variable` in
the text with a placeholder for the corresponding value (e.g., a placeholder for
the SMS OTP in each instance of `OTP`).

Solaris will automatically send the text in the customer's preferred
language if you have created a [language
preference](/api-reference/onboarding/persons/#tag/Person-language-settings/paths/~1v1~1persons~1%7Bperson_id%7D~1settings/post)
for the customer.

| Case | Text EN | Text DE | Text FR | Text IT | Text ES |
|  --- | --- | --- | --- | --- | --- |
| **Account closure** | To complete the account closure of `iban`, use the following SMS OTP: `OTP` | Um die Kontoschließung von `iban` freizugeben, nutzen Sie bitte folgende TAN: `OTP` | Afin de confirmer la fermeture du compte ayant pour IBAN `iban`, utilisez le code OTP suivant : `OTP` | Per completare il processo di chiusura per `iban` usare il seguente codice OTP: `OTP` | Para completar el cierre de la cuenta `iban`, use el siguiente SMS OTP: `OTP` |
| **Unauthorized Business Change Request** | There must be at least one legal representative person with a confirmed mobile number present | - | La présence d'au moins un représentant légal avec un numéro de téléphone mobile confirmé est requise. | - | Debe haber al menos una persona representante legal con un número de móvil confirmado. |
| **Add Legal Representative to Business Account** | To add `name` as a legal representative on your account `iban`, use the following SMS OTP: `OTP` | Um `name` als Verfügungsberechtigten zu Ihrem Konto `iban` hinzuzufügen, nutzen Sie bitte folgende TAN: `OTP` | Afin d'autoriser `name` à réaliser des opérations sur le compte `iban`, utilisez le code OTP suivant : `OTP` | Per aggiungere `name` come rappresentante legale sul tuo conto `iban` usare il seguente codice OTP: `OTP` | Para añadir `name` como representante legal en su cuenta `iban`, use el siguiente SMS OTP: `OTP` |
| **Authenticate mobile_number** | `OTP` is your OTP for authorization | `OTP` ist Ihre OTP zur Autorisierung | Voici votre code OTP `OTP` pour l'autorisation | Il codice per confermare il Suo numero di telefono è: `OTP` | `OTP` es su OTP para la autorización. |
| **Verify mobile_number** | Please verify your mobile number with the following SMS OTP: `OTP` | Bitte verifizieren Sie Ihre Handynummer mit folgender TAN: `OTP` | Veuillez confirmer votre numéro de portable avec le code OTP suivant : `OTP` | La preghiamo di verificare il Suo numero di cellulare usando il seguente SMS OTP: `OTP` | Verifique su número de móvil con el siguiente SMS OTP: `OTP` |
| **Confirm mobile_number deletion** | To verify you would like to delete the mobile number you have on file, use the following SMS OTP: `OTP` | Um die Löschung Ihrer Handynummer freizugeben, nutzen Sie bitte folgende TAN: `OTP` | Veuillez utiliser le code OTP suivant afin de confirmer la suppression de votre numéro de portable : `OTP` | Per confermare la Sua intenzione di cancellare il numero di cellulare registrato usare il seguente codice OTP: `OTP` | Para verificar que desea eliminar el número de móvil que tiene archivado, utilice el siguiente SMS OTP: `OTP` |
| **Deleted mobile_number** | Your mobile number `number` has been removed and can no longer be used for SMS OTP authentication | Ihre Handynummer `number` wurde entfernt und kann nicht mehr für das TAN-Verfahren genutzt werden | Votre numéro de portable `number` a été supprimé | Il Suo numero di cellulare `number` è stato rimosso e non puó piú essere usato per l'autentificazione codice OTP | Su número de móvil `number` ha sido eliminado y ya no puede ser utilizado para la autenticación de sms tan |
| **Changed mobile_number** | Your mobile number `old_number` has been replaced by `new_number` | Ihre Handynummer `old_number` wurde durch `new_number`s ersetzt | Votre numéro de portable `old_number`s a été remplacé par le numéro `new_number`s | Il Suo numero di cellulare `old_number`s è stato sostituito con `new_number`s | Su número de móvil `old_number` ha sido sustituido por `new_number` |
| **Person data change OTP confirmation** | To authorize the data change, please use the following SMS OTP: `OTP` | Um die Datenänderung freizugeben, nutzen sie bitte folgende TAN: `OTP` | Utilisez le code OTP suivant afin de confirmer le changement des données : `OTP` | Per autorizzare la modifica dei dati usare il seguente codice OTP: `OTP` | Para autorizar el cambio de datos, por favor use el siguiente SMS OTP: `OTP` |
| **SEPA transaction OTP confirmation** | To complete the payment for `iban` of `amount`, use the following SMS OTP: `OTP` | Um die Überweisung von `amount` auf IBAN `iban` freizugeben, nutzen Sie bitte folgende TAN: `OTP` | Afin d'activer le paiement de `amount` depuis le compte `iban`, utilisez le code OTP suivant : `OTP` | Per completare il pagamento per `iban` dell'importo di `amount` usare il seguente codice OTP: `OTP` | Para completar el pago de `iban` de `amount`, use el siguiente SMS OTP: `OTP` |
| **Batch SEPA transaction OTP confirmation** | To complete the batch transaction of `count` transactions with a cumulative value of `amount`, use the following SMS OTP: `OTP` | Um die Sammelüberweisung von `count` Transaktion über `amount` freizugeben, nutzen Sie bitte folgende TAN: `OTP` | Afin d'autoriser l'ensemble des `count` virements d'un montant total de `amount`, utilisez le code OTP suivant : `OTP` | Per completare il gruppo di transazioni per i seguenti conti `count` del valore cumulativo di `amount` usare il seguente codice OTP: `OTP` | Para completar la transacción por grupo de las transacciones `count` con un valor acumulativo de `amount`, use el siguiente SMS OTP: `OTP` |
| **Create standing order OTP confirmation** | To issue the standing order of `amount` for account `iban`, use the following SMS OTP: `OTP` | Um den Dauerauftrag von `amount` auf IBAN `iban` freizugeben, nutzen Sie bitte folgende TAN: `OTP` | Afin d'autoriser l'ordre de virement permanent d'un montant de `amount` vers le compte `iban`, utilisez le code OTP suivant : `OTP` | Per procedere con l'ordine di pagamento permanente dell'importo di `amount` per `iban` usare il seguente codice OTP: `OTP` | Para emitir la orden permanente de `amount` para la cuenta `iban`, use el siguiente SMS OTP: `OTP` |
| **Cancel standing order OTP confirmation** | To delete the standing order of `amount` for account `iban`, use the following SMS OTP: `OTP` | Um die Löschung des Dauerauftrags von `amount` auf IBAN `iban` freizugeben, nutzen Sie bitte folgende TAN: `OTP` | Afin d'autoriser l'ordre de virement permanent d'un montant de `amount` vers le compte `iban`, utilisez le code OTP suivant : `OTP` | Per annullare l'ordine di pagamento permanente dell'importo di `amount` per `iban` usare il seguente codice OTP: `OTP` | Para emitir la orden permanente de `amount` para la cuenta `iban`, use el siguiente SMS OTP: `OTP` |
| **Update standing order OTP confirmation** | To change the standing order of `amount` for account `iban`, use the following SMS OTP: `OTP` | Um die Änderung des Dauerauftrags von `amount` auf IBAN `iban` freizugeben, nutzen Sie bitte folgende TAN: `OTP` | Afin de confirmer la modification du virement permanent d'un montant de `amount` vers le compte `iban`, utilisez le code OTP suivant : `OTP` | Per modificare l'ordine di pagamento permanente dell'importo di `amount` per `iban` usare il seguente codice OTP: `OTP` | Para cambiar la orden permanente de `amount` para la cuenta `iban`, use el siguiente SMS OTP: `OTP` |
| **Timed order OTP confirmation** | To issue the timed order of `amount` for account `iban`, use the following SMS OTP: `OTP` | Um die Terminüberweisung von `amount` auf IBAN `iban` freizugeben, nutzen sie bitte folgende TAN: `OTP` | Afin d'activer l'ordre de virement d'un montant de `amount` vers le compte `iban`, utilisez le code OTP suivant : `OTP` | Per generare l'ordine di pagamento temporaneo di `amount` per `iban` usare il seguente codice OTP: `OTP` | Para emitir la transferencia programada de `amount` para la cuenta `iban`, use el siguiente SMS OTP: `OTP` |
| **Online Purchase via 3DS** | Use code `passcode` to authenticate your purchase of `amount` `currency` at `merchant` | Nutzen Sie den Code `passcode` um die Überweisung von `amount` `currency` an `merchant` zu authorisieren | Utilisez le code `passcode` pour authentifier votre achat de `amount` `currency` chez `merchant` | Usa il codice `passcode` per autenticare il tuo acquisto di `amount` `currency` presso `merchant` | Utilice el código `passcode` para autenticar su compra de `amount` `currency` en `merchant` |
| **Push Provisioning (ApplePay, GooglePay)** | Your one-time verification code to add your card to `Wallet_Name` is `code`. The code will expire in 30 minutes. | Ihr einmaliger Bestätigungscode um Ihrer Karte zu `Wallet_Name` hinzuzufügen lautet `code`. Der Code läuft in 30 Minuten ab. | Votre code de vérification à usage unique pour ajouter votre carte à `Wallet_Name` est le `code`. Ce code expirera dans 30 minutes. | Il tuo codice di verifica una tantum per aggiungere la tua carta a `Wallet_Name` è `code`. Il codice scadrà tra 30 minuti. | Su código de verificación único para agregar su tarjeta a `Wallet_Name` es `code`. El código caducará en 30 minutos. |