Registering Users

As an integrator, we assume you have an existing registration and user management system of your own; thus, our platform utilizes "shadow accounts". This means we expect you to perform user authentication within your application and pass us the unique Tilia Pay account ID when granting user access and performing transactions on our platform.

Registration creates the user's Tilia Pay account ID. It also creates the user's wallets.

Registration Requirements

Registering a user in Tilia Pay requires the following:

  • username
  • password
  • email

Usernames must be unique, and must be formatted as an email address (e.g. user@domain.com). In general, we recommend using the email address associated with the user in your application.

Since you are creating a shadow account, the password can be arbitrarily assigned as it is not used for user authentication. For security, passwords must:

  • contain between 6 and 16 characters
  • contain at least one alphabet character and one non-alphabet character
  • not be the same as username
  • not match the username portion of their email address
  • not be a single word found in an English dictionary, a proper noun, or a word or phrase found in a common password dictionary

Email must be a valid email address for the registered user. Tilia uses this address when sending receipts and when contacting the user about their Tilia Pay account.

In most environments, the user will not receive a verification email when their account is created. Thus it is important that you ensure the provided email address is accurate and you notify Tilia of any changes to a user's contact information.

You are required to notify Tilia of any changes to a user's email address. Contact our support team with questions or to update a user's email address.

In addition to these required fields, optional fields can be used to pass additional registration details. Refer to the API Reference for more information.

The rest of this document takes you through the process of registering a new user in the Staging Environment. To register a user in the Production Environment, update the URIs in the code below.

Step 1: Create the user's registration profile

The first step in registering a new user is to create a registration profile. The examples below require an API token with the scope write_registrations.

To register a user, submit a POST request with a request body containing the required information. You can also pass any optional registration information, including a tracking ID to track the user registration from your system.

curl --location --request POST https://registration.staging.tilia-inc.com/v2/register \
--header 'Authorization: Bearer <Access_Token>' \
--header 'Content-Type: application/json' \

Request Body

{
	"username": "jessica.pley@gmail.com",
	"password": "z+YN?L5Yt7",
	"email": "jessica.pley@gmail.com"
}

When the registration profile is created, a success response of 200 is returned, along with the following JSON:

Response Body

{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "registration_id": "a900281d-5d01-4784-a412-f447389929f8"
    }
}

The returned registration_ID is used for the next step.

Step 2: Complete the registration

To complete the process of registering a user, pass the registration_id to the /register endpoint.

curl --location --request PUT https://registration.staging.tilia-inc.com/v2/register/{registration_id} \
--header 'Authorization: Bearer <Access_Token>' \
--header 'Content-Type: application/json' \

This returns a JSON response containing the user's account_id, which is required for all operations related to this user.

{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "account_id": "ebcbc9c4-7c1b-47df-9ec4-1bcfa48e0344",
        "autologin_id": "fce464b4-cf9f-49c2-bdb1-2db3275d6284"
    }
}
The Account ID should be stored in your system and associated with your user's account. This is the only key you have to operate on the user's Tilia Pay account!

Step 3: Handle the account creation event

Although this step is optional, you may wish to implement a webhook to notify you when a new Tilia Pay account is created. See the Account Creation webhook documentation for complete details.

Currently, webhook endpoints must be configured manually by our staff. We are working on a web interface to enable you to control this directly. For now, please contact us for assistance.