About Alias Directory

Introduction

Alias directory is a Ledger service that allows users to send money to aliases instead of bank account numbers. Aliases are usually human readable and are therefore easier to use and remember. A couple of examples of aliases are a phone number or an e-mail address. Most people already know aliases for their friends and family and can just start using them right away.

Onboarding

For a user to be able to receive money to an alias, he first needs to be onboarded into Ledger. This is done mostly automatically by Ledger, but since in most cases money eventually ends up in a bank account, it needs to be registered with Ledger. This registration needs to be done only once and all future transfers will go through automatically. It is possible to configure this transfer redirection in many ways, for example by currency, sender and similar.

The Process

Behind the scenes, this feature uses the same Ledger concepts that are already described in other documents like wallets, routing and others. Every alias is handled by a wallet with routing configured and an internal dedicated Alias Bridge to handle the process. When a transfer targets an alias and it is not configured (alias wallet does not exist or the proper route is not configured), the Alias Bridge will send a message to the client using the alias channel. For a phone number this means sending an SMS message, for an e-mail address this means sending an e-mail. This message will direct the user to use a trusted bank channel (eg. mobile or web) to register an account to proceed with the transfer. At that point the bank bridge will need to update the alias wallet in Ledger and the transfer will be routed to the configured account and proceed as normal.

Phone Validation

It is vital that the bank validates the user’s phone number. This can be done eg. by using an OTP token or if the bank already knows the phone number, it can use that. By onboarding a phone number, it is expected that all reasonable steps were taken to ensure that the correct user is using that phone number and the bank takes full responsibility if these steps were not taken. All future transfers to that phone number, until the alias is updated, will go to the registered bank account.

Example

For example, let’s imagine that someone wants to send money to a phone number and this number is not onboarded. The target for the transfer will be something like tel:+57123456789 and the user of this phone number will get an SMS message saying that they should use their mobile banking application to onboard and receive the funds. After entering the preferred banking application, the user should be able to easily find the configuration page and be presented with a list of accounts which he can use to receive payments for each of the currencies. After selecting the accounts, the bank should update the wallet in the system with the corresponding routes.

Figure 1. Wallet onboarding example

For example, to update the phone wallet tel:123456789 to forward transfers in usd to account:987654321@bank.com, a request should be sent to PUT /v2/wallets/:handle with the following body:

{
    "hash": "...",
    "data": {
        "handle": "tel:123456789",
        "custom": {},
        "access": [ ... ],
        "routes": [
            {
                "action": "forward",
                "filter": {
                    "symbol": "usd"
                },
                "target": "account:987654321@bank.com"
            }
        ],
        "parent": "<parent-hash>" // hash of the parent record
    }
    "meta": { ... }
}