Tutorial: Manage new user accounts

This tutorial demonstrates how to create and locate user accounts. It also creates or recalls the user account IDs that the tutorials use to demonstrate other Tilia services.

Allow about 15 minutes to complete this tutorial.

API operations in this tutorial

This tutorial uses the _Manage user accounts collection from the shared workspace.

To complete this tutorial successfully:

1. Make sure the software described in Get started with the tutorials has been installed on your system and configured.
2. In Postman:
   1. Open the Tilia tutorial workspace you created in Get started with the tutorials .
   2. Make sure you have the _Manage user accounts collection forked to your Tilia tutorial workspace .
   3. Make sure that you've selected the Tilia Client Info environment and confirmed that it has:
      1. Your Tilia developer credentials.
      2. The usernames and email addresses for your users: payer, recipient, and creator, if you're creating new users; or usernames for your users if you are recalling existing accounts.
   4. In your Tilia tutorial workspace , open the list of Collections .
   5. In the list of Collections , expand the _Manage user accounts collection.
   6. If it's been more than an hour since you last got an access token for this collection, get a new one as described in Tutorial: User accounts overview , and then return to continue here.

Create new users

This exercise creates new user accounts for the users described in the environment variables.

These requests create new user accounts and are found in the _Manage user accounts collection, in the Create new users folder:

• Add payer's user account
• Add recipient's user account
• Add creator's user account

The requests are identical with the exception of the request body, which is specific to the user being added.

Repeat this procedure for each user account to add.

For each user account to add, in Postman:

1. In the _Manage user accounts collection, in the Create new users folder, open the request to add the user, and then choose the Body tab.
2. In the request Body tab, shown here, notice that the username and email.address properties use the environment variables you edited when getting started.
   Copy

   Copied

   {
       "username": "{{users_username}}",
       "email": { 
           "address": "{{users_email}}"
       }
   }

3. Choose Send to create a new user account. A typical response body looks like the following.
   Copy

   Copied

   {
       "status": "Success",
      "message":[],
      "codes":[],
      "payload": {
           "account_id": "acct_2ZB8jw5SS0NATzMDvn7NcG4XtVT",
           "username": "user_602"
       }
   }

   If successful, the Current value of the user's account ID environment variable is updated with the account_id from the payload of the response body.

Create the payer's account from an external payment platform

This exercise demonstrates how to add a user account for the payer when the payer is a user from one of Tilia's supported external payment platforms.

Tilia can collect funds from external payment platforms to use in Tilia transactions. This gives your users access to Tilia transactions from apps that must process payments through a vendor's app store.

Such user accounts must provide the user account information from the external payment platform when their Tilia user account is created.

To create the payer's account from an external payment platform:

1. In the _Manage user accounts collection, in the Payer from external platform folder, open the Add payer from external platform request, and then choose the Body tab.
2. In the request Body tab, shown here, notice that the username and external_platforms properties use the environment variables you edited when getting started. Also notice that instead of an email , the external_platforms property is used to identify the user. For this exercise, the payers_email is used as the user's ID in the external payment platform.
   Copy

   Copied

   {
       "username": "{{payers_username}}",
       "external_platforms": {
           "apple": {
               "user_id": "{{payers_email}}"
           }
       }
   }

3. Choose Send to create a new user account. A typical response body looks like the following.
   Copy

   Copied

   {
       "status": "Success",
      "message":[],
      "codes":[],
      "payload": {
           "account_id": "acct_2ZB8jw5SS0NATzMDvn7NcG4XtVT",
           "username": "user_602"
       }
   }

   If successful, the Current value of the user's account ID environment variable is updated with the account_id from the payload of the response body.

The payer already has a payment method defined that uses the external payment platform. With this, you can skip to the Get payer's payment method procedure and run the procedure for payers from external platforms.

Recall existing users

This exercise recalls existing user accounts whose usernames are described in the environment variables.

If you just added the users in the previous exercise, this exercise is not required. However, you still run it to see how the Search by username operation works without any problems.

These requests search for existing user accounts by looking up the username, and are found in the _Manage user accounts collection, in the Recall existing users folder.

• Recall payer's user account
• Recall recipient's user account
• Recall creator's user account

Each request is identical to the other, with the exception of the username parameter, which is specific to the user being recalled.

Repeat this procedure for each user request in the Recall existing users folder.

For each existing user to look up by using the user's username, in Postman:

1. In the _Manage user accounts collection, in the Recall existing users folder, open the request to add the user, and then choose the Params tab.
2. In the Params tab, notice that the username parameter uses the environment variable with the user's username.
3. In the request, choose Send .
4. After the response returns, below the request, open the response Body tab to review details of the response body.

A typical response body looks like the following.

{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "account_id": "acct_2ZB8jw5SS0NATzMDvn7NcG4XtVT",
        "username": "payer_602",
        "email": "payer_602@example.com",
        "is_blocked": false,
        "blocked_capabilities": {},
        "integrator": "tilia-test",
        "tags": [],
        "created": "2023-12-06T17:37:30.68692Z"
    }
}

If successful, a script runs after the response returns to save the account_id in the user's account ID environment variable.

A status of 404 and a response body similar to this one means that an account wasn't found with the username you entered in the environment variables for that user.

{
    "status": "Failure",
    "message": [
        "failed to get account"
    ],
    "codes": [
        "ACCOUNT_GET_ERROR"
    ],
    "payload": null
}

To correct this, correct the username in the environment variables or create a new user.

Next steps

To get information about a user's account when you already have their account ID, the Get account profile operation returns the same payload as the Search by username operation.

With the user accounts initialized, your next step is Buy tokens so the payer has tokens to use in future transactions.