Tutorial: Buy tokens

In this tutorial, you use Tilia services to purchase tokens for the payer's user account. The user accounts referenced in this tutorial are those that you created in Manage new user accounts.

Allow about 15 minutes to complete this tutorial.

The following diagram shows the process to purchase tokens.

Token purchase flow

Exercises that end in (UI) use the Tilia UI Sandbox to perform the task. For information about the Tilia UI Sandbox, visit Tilia UI Sandbox.

Interactions in this tutorial

The interactions in this tutorial take place after the user selects the tokens to purchase from a user interface that the publisher provides.

Tutorial interaction	API operations used	Scope	Environment variables initialized
Add a payment method (UI)	Add Payment Method widget	None	None
Get payer's payment methods	Get payment methods	`read_payment_methods`	`payers_pm` `payers_pm_id`
Start token purchase	Initiate token purchase	`write_tokens`	None
Finish token purchase	Execute token purchase	`write_tokens`	None

To complete this tutorial

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

To complete this tutorial successfully:

Make sure the software described in Get started with the tutorials has been installed on your system and configured.
Complete Manage new user accounts , if you haven't already. The exercises in this tutorial use the user accounts that you create in that tutorial.
In a separate browser window, open the Tilia UI Sandbox to have it ready for when you add a payment method later in the tutorial.
In Postman:
1. Open the Tilia tutorial workspace you created in Get started with the tutorials for this tutorial.
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, emails, and account IDs for your users: payer, recipient, and creator.
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.
7. If you're payer has an account with an external payment platform , skip to the Get payer's payment methods exercise.

Add a payment method (UI)

This exercise adds a payment card to the payer's account by using the UI Sandbox. While a user can enter a card at the time of purchase, adding a card to the user's account makes it possible to process payments that use the card more quickly.

If you are recalling an existing user that already has a payment card, you can skip this exercise and run the exercises in the next section to recall the existing payment method and update the payers_pm_id environment variable.

To complete this task, use the Tilia UI Sandbox to add a new payment method to the user's account.

Before you start, make sure you have:

Your Tilia developer credentials
The payer's account ID from the Postman environment variables.
The account number of an approved test credit card listed in Test payment methods .

To add a payment method:

Open or switch to a browser window that has the Tilia UI Sandbox running in it.
In the UI Sandbox:
1. Enter your Tilia developer credentials, if necessary.
2. Enter the payer's account ID from the environment variables.
3. Choose the PAYMENT SELECTION option from the left column,and click the "W" to open the PAYMENT SELECTION widget. You might be asked to accept Tilia's Terms of Service and then, if you haven't added any payment methods for the user, the following interface is displayed into which you can add a new payment method.
4. In the add card interface, enter the card info from Test payment methods .
  Note
  The card number that you use must be one that will produce an approved transaction for the remaining requests in the Postman collection to work.
5. Add the card.

When the STATE object in the Sandbox is displayed, the widget is complete and the card has been added as a payment method. The following code example shows the response body of the PAYMENT SELECTION widget. Note that the response contains a paymentMethods array, which contains an array of payment_method_id and amount properties.

Copy

Copied

{
  "source": "tilia",
  "event": "tilia.payment-selection.complete",
  "state": "complete",
  "paymentMethods": [
    {
      "payment_method_id": "8206df07-a503-4fdb-9b06-022a3be9fbfa",
      "amount": 0
    }
  ]
}

An application that displays the PAYMENT SELECTION widget would normally use the values from the paymentMethods array in the subsequent requests that complete the transaction.

To simulate using the paymentMethods array value returned by the widget in these tutorials:

From the UI Sandbox, copy the payment_method_id value returned by the PAYMENT SELECTION widget.
In Postman, paste the payment_method_id value in the payers_pm_id environment variable.
Skip the next section and continue in the Start token purchase section.

If you are recalling an existing user that already has added payment methods, or you don't want to copy and paste the value, run the exercises in the next section to recall the payment method ID and update the payers_pm_id environment variable.

Get payer's payment methods

This exercise looks for a payment method that's a credit card and saves the payment method object and its payment method ID as environment variables.

To get the payer's payment methods, in Postman:

Open the _Manage user accounts collection, and the Add payment method to payer folder.
Open the Get payer's payment methods request.
In the URL field, notice that the account_id parameter uses the payers_account_id environment variable.
In the Get payer's payment methods request, choose Send .
After the response returns, open the response Body tab below the request to review the response body details.

To get the payer's payment methods for payers from external payment platforms, in Postman:

Open the _Manage user accounts collection, and the Payer from external platform folder.
Open the Get payer's external payment method request.
In the URL field, notice that the account_id parameter uses the payers_account_id environment variable.
In the Get payer's external payment method request, choose Send .
After the response returns, open the response Body tab below the request to review the response body details.

Show a typical response body with the user's payment methods.

Copy

Copied

{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": [
        {
            "id": "52013d9f-d7d4-4c39-b0a9-27c924d157b1",
            "account_id": "acct_2ZB8jw5SS0NATzMDvn7NcG4XtVT",
            "method_class": "convertible",
            "display_string": "Convertible TIL wallet",
            "provider": "wallet",
            "psp_reference": "2c6be416-5949-4f6b-9ec3-86a9a02c2f08",
            "psp_hash_code": "",
            "processing_currency": "TIL",
            "pm_state": "ACTIVE",
            "integrator": "tilia-test",
            "created": "2023-12-06 17:37:31",
            "updated": "2023-12-06 17:37:31",
            "tags": [
                {
                    "tag_id": "paytag_2ZB8juEbcgav2yqQWH9ANdLregK",
                    "resource_type": "payments.payment_method.id",
                    "resource_id": "52013d9f-d7d4-4c39-b0a9-27c924d157b1",
                    "account_id": "acct_2ZB8jw5SS0NATzMDvn7NcG4XtVT",
                    "namespace": "payment_method",
                    "tag": "virtual",
                    "status": "ACTIVE",
                    "integrator": "tilia-test",
                    "created": "2023-12-06T17:37:30.610318Z",
                    "updated": "2023-12-06T17:37:30.610318Z"
                },
                {
                    "tag_id": "paytag_2ZB8jwQXwdnAzz7rsA0CJe3Iav0",
                    "resource_type": "payments.payment_method.id",
                    "resource_id": "52013d9f-d7d4-4c39-b0a9-27c924d157b1",
                    "account_id": "acct_2ZB8jw5SS0NATzMDvn7NcG4XtVT",
                    "namespace": "payment_method",
                    "tag": "publisher_funds",
                    "status": "ACTIVE",
                    "integrator": "tilia-test",
                    "created": "2023-12-06T17:37:30.634036Z",
                    "updated": "2023-12-06T17:37:30.634036Z"
                },
                {
                    "tag_id": "paytag_2ZB8k0nDB1kOOIMtA1de72kDNCK",
                    "resource_type": "payments.payment_method.id",
                    "resource_id": "52013d9f-d7d4-4c39-b0a9-27c924d157b1",
                    "account_id": "acct_2ZB8jw5SS0NATzMDvn7NcG4XtVT",
                    "namespace": "payment_method",
                    "tag": "convertible",
                    "status": "ACTIVE",
                    "integrator": "tilia-test",
                    "created": "2023-12-06T17:37:30.620859Z",
                    "updated": "2023-12-06T17:37:30.620859Z"
                }
            ],
            "wallet_balance": "0",
            "payment_method_id": "",
            "provider_data": {
                "wallet_id": "2c6be416-5949-4f6b-9ec3-86a9a02c2f08",
                "wallet_balance": "0",
                "balance": 0
            }
        },
        {
            "id": "6e5eff03-af40-44cb-b462-c368267b25c4",
            "account_id": "acct_2ZB8jw5SS0NATzMDvn7NcG4XtVT",
            "method_class": "registration",
            "display_string": "Default USD Wallet",
            "provider": "wallet",
            "psp_reference": "8251c4e0-2f7a-4bce-9978-e1371eb68656",
            "psp_hash_code": "",
            "processing_currency": "USD",
            "pm_state": "ACTIVE",
            "integrator": "tilia-test",
            "created": "2023-12-06 17:37:31",
            "updated": "2023-12-06 17:37:31",
            "tags": [
                {
                    "tag_id": "paytag_2ZB8jupPj3bRARd8Sj4TCtcV8IJ",
                    "resource_type": "payments.payment_method.id",
                    "resource_id": "6e5eff03-af40-44cb-b462-c368267b25c4",
                    "account_id": "acct_2ZB8jw5SS0NATzMDvn7NcG4XtVT",
                    "namespace": "payment_method",
                    "tag": "publisher_funds",
                    "status": "ACTIVE",
                    "integrator": "tilia-test",
                    "created": "2023-12-06T17:37:30.597788Z",
                    "updated": "2023-12-06T17:37:30.597788Z"
                },
                {
                    "tag_id": "paytag_2ZB8jv14jzlmuhcyQ6TASWrLiqB",
                    "resource_type": "payments.payment_method.id",
                    "resource_id": "6e5eff03-af40-44cb-b462-c368267b25c4",
                    "account_id": "acct_2ZB8jw5SS0NATzMDvn7NcG4XtVT",
                    "namespace": "payment_method",
                    "tag": "registration",
                    "status": "ACTIVE",
                    "integrator": "tilia-test",
                    "created": "2023-12-06T17:37:30.586961Z",
                    "updated": "2023-12-06T17:37:30.586961Z"
                }
            ],
            "wallet_balance": "0",
            "payment_method_id": "",
            "provider_data": {
                "wallet_id": "8251c4e0-2f7a-4bce-9978-e1371eb68656",
                "wallet_balance": "0",
                "balance": 0
            }
        },
        {
            "id": "d994e912-c983-4b3a-8f05-0ff482d2be06",
            "account_id": "acct_2ZB8jw5SS0NATzMDvn7NcG4XtVT",
            "method_class": "standard",
            "display_string": "Standard TIL wallet",
            "provider": "wallet",
            "psp_reference": "485d68b6-97a4-4d64-89ff-508c6a9df9b0",
            "psp_hash_code": "",
            "processing_currency": "TIL",
            "pm_state": "ACTIVE",
            "integrator": "tilia-test",
            "created": "2023-12-06 17:37:31",
            "updated": "2023-12-06 17:37:31",
            "tags": [
                {
                    "tag_id": "paytag_2ZB8jw4EUUvEsUK9eekl6ODvkcE",
                    "resource_type": "payments.payment_method.id",
                    "resource_id": "d994e912-c983-4b3a-8f05-0ff482d2be06",
                    "account_id": "acct_2ZB8jw5SS0NATzMDvn7NcG4XtVT",
                    "namespace": "payment_method",
                    "tag": "virtual",
                    "status": "ACTIVE",
                    "integrator": "tilia-test",
                    "created": "2023-12-06T17:37:30.646479Z",
                    "updated": "2023-12-06T17:37:30.646479Z"
                },
                {
                    "tag_id": "paytag_2ZB8k0W7nBxVfeYJR7gz1I6zN80",
                    "resource_type": "payments.payment_method.id",
                    "resource_id": "d994e912-c983-4b3a-8f05-0ff482d2be06",
                    "account_id": "acct_2ZB8jw5SS0NATzMDvn7NcG4XtVT",
                    "namespace": "payment_method",
                    "tag": "standard",
                    "status": "ACTIVE",
                    "integrator": "tilia-test",
                    "created": "2023-12-06T17:37:30.656175Z",
                    "updated": "2023-12-06T17:37:30.656175Z"
                }
            ],
            "wallet_balance": "0",
            "payment_method_id": "",
            "provider_data": {
                "wallet_id": "485d68b6-97a4-4d64-89ff-508c6a9df9b0",
                "wallet_balance": "0",
                "balance": 0
            }
        },
        {
            "id": "fe3f6807-6fde-48ac-91c4-8df3a3dd8750",
            "account_id": "acct_2ZB8jw5SS0NATzMDvn7NcG4XtVT",
            "method_class": "visa",
            "display_string": "Visa ending in 1111",
            "provider": "rebilly",
            "psp_reference": "inst_01HH0Q93KR854JC2G4A6YH0Z84",
            "psp_hash_code": "",
            "processing_currency": "USD",
            "pm_state": "ACTIVE",
            "integrator": "tilia-test",
            "created": "2023-12-06 23:26:48",
            "updated": "2023-12-06 23:27:14",
            "tags": [],
            "payment_method_id": "fe3f6807-6fde-48ac-91c4-8df3a3dd8750",
            "psp_provided_email": "card.holder@example.com"
        }
    ]
}

A script in the Tests tab reads the response buffer and saves the payment method object and ID of the first payment method that uses a credit card.

Start token purchase

This request starts a token purchase transaction using the payment method that was added earlier in this tutorial.

To start a token purchase transaction, in Postman:

In the _Manage user accounts collection, in the Buy tokens for payer folder, open the Start token purchase request.
The request body contains information about the purchase that would have been collected by the publisher's UI that started the transaction. In the Body tab, notice:
1. The payment_method_id property is using the payers_pm_id environment variable.
2. The destination_account_id property is using the payers_account_id environment variable.
3. The amount and currency properties describe what is being purchased.
  In this case, it's 15,000.00 TIL tokens.
4. Together, these properties make up the request body.
  Copy
  
  Copied
```
{
    "payment_method_id": "{{payers_pm_id}}",
    "amount": 1500000,
    "currency": "TIL",
    "destination_account_id": "{{payers_account_id}}"
}
```
In the Start token purchase request, choose Send .
After the response returns, open the response Body tab below the request to review the response body details.

A typical response body looks similar to the following.

Copy

Copied

{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "token_exchange_id": "vtok_2ZBrTrJGoHzxnlQNsxMKFXniLXk",
        "account_id": "acct_2ZB8jw5SS0NATzMDvn7NcG4XtVT",
        "direction": "token_purchase",
        "invoice_id": "inv_2ZBrTqk0UUGaMY7Mc1CiWnoHSue",
        "user_paid_amount": 15000,
        "user_paid_currency": "USD",
        "user_received_amount": 1500000,
        "user_received_currency": "TIL",
        "exchange_rate": 100,
        "exchange_rate_direction": "usd_to_virtual",
        "tilia_fee_amount": 0,
        "integrator_fee_amount": 0,
        "fee_currency": "USD",
        "destination_wallet_id": "485d68b6-97a4-4d64-89ff-508c6a9df9b0",
        "status": "OPEN",
        "tags": null,
        "created": "",
        "updated": "",
        "amount_usd": 15000,
        "virtual_amount": 1500000,
        "virtual_currency": "TIL",
        "summary": {
            "total_amount": 15000,
            "total_amount_usd": 15000,
            "currency": "USD",
            "display_amount": "USD 150.00",
            "subtotal": {
                "total_amount": 15000,
                "total_amount_usd": 15000,
                "currency": "USD",
                "display_amount": "USD 150.00"
            },
            "tax": {
                "total_amount": 0,
                "total_amount_usd": 0,
                "currency": "USD",
                "display_amount": "USD 0.00"
            },
            "payment_breakdown": null,
            "tax_calculation": ""
        }
    }
}

In the payload.summary property of the response, you can review a summary of the token purchase that you started. To purchase 15,000 tokens the VISA card is charged $150.00.

The payload.token_exchange_id value is saved in the token_exchange_id collection variable to use in the next task.

Finish token purchase

This requst completes the purchase started by the previous request.

To finish a token purchase transaction, in Postman:

In the _Manage user accounts collection, in the Buy tokens for payer folder, open the Finish token purchase request.
In the URL field, notice the token_exchange_id collection variable is used to identify the token purchase to finish.
In the Finish token purchase request, choose Send .
After the response returns, open the response Body tab below the request to review the response body details.

A typical response body looks similar to the following.

Copy

Copied

{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "token_exchange_id": "vtok_2ZBrTrJGoHzxnlQNsxMKFXniLXk",
        "account_id": "acct_2ZB8jw5SS0NATzMDvn7NcG4XtVT",
        "direction": "token_purchase",
        "invoice_id": "inv_2ZBrTqk0UUGaMY7Mc1CiWnoHSue",
        "user_paid_amount": 15000,
        "user_paid_currency": "USD",
        "user_received_amount": 1500000,
        "user_received_currency": "TIL",
        "exchange_rate": 100,
        "exchange_rate_direction": "usd_to_virtual",
        "tilia_fee_amount": 0,
        "integrator_fee_amount": 0,
        "fee_currency": "USD",
        "destination_wallet_id": "485d68b6-97a4-4d64-89ff-508c6a9df9b0",
        "status": "SUCCESS",
        "tags": null,
        "created": "2023-12-06T23:45:24.637951Z",
        "updated": "2023-12-06T23:45:24.637951Z",
        "amount_usd": 15000,
        "virtual_amount": 1500000,
        "virtual_currency": "TIL",
        "summary": {
            "total_amount": 15000,
            "total_amount_usd": 15000,
            "currency": "USD",
            "display_amount": "USD 150.00",
            "subtotal": {
                "total_amount": 15000,
                "total_amount_usd": 15000,
                "currency": "USD",
                "display_amount": "USD 150.00"
            },
            "tax": {
                "total_amount": 0,
                "total_amount_usd": 0,
                "currency": "USD",
                "display_amount": "USD 0.00"
            },
            "payment_breakdown": null,
            "tax_calculation": ""
        }
    }
}

Next steps

After purchasing tokens, your next step is to get info about the users' wallets and to view their current balances in View user account wallets.