# 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](/tutorials/user-accounts/tutorial_user_new_users). Allow about 15 minutes to complete this tutorial. The following diagram shows the process to purchase tokens. ![Token purchase flow](/assets/tutorial-token-purchase.f1b0ee5594a0bb12110c082010f3d78ca4e68a788c5d3667ccb95cfcb3069482.9c1bb791.png) 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](/web-uis/ui-sandbox-guide/). ## 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-a-payment-method-ui) | Add Payment Method widget | None | None | | [Get payer's payment methods](#get-payers-payment-methods) | | `read_payment_methods` | `payers_pm``payers_pm_id` | | [Start token purchase](#start-token-purchase) | | `write_tokens` | None | | [Finish token purchase](#finish-token-purchase) | | `write_tokens` | None | ## To complete this tutorial This tutorial uses the **_Manage user accounts** collection from the [shared workspace](https://www.postman.com/tilia-docs-testing/workspace/get-started-using-tilia-services/overview). **To complete this tutorial successfully:** 1. Make sure the software described in [Get started with the tutorials](/tutorials/tutorial_get_started) has been installed on your system and configured. 2. Complete [Manage new user accounts](/tutorials/user-accounts/tutorial_user_new_users), if you haven't already. The exercises in this tutorial use the user accounts that you create in that tutorial. 3. In a separate browser window, open the [Tilia UI Sandbox](https://fake-integrator.staging.tilia-inc.com/ui/) to have it ready for when you add a payment method later in the tutorial. 4. In Postman: 1. Open the **Tilia tutorial workspace** you created in [Get started with the tutorials](/tutorials/tutorial_get_started) 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](/guides/external-payment-platforms), skip to the [Get payer's payment methods](#get-payers-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](#get-payers-payment-methods) to recall the existing payment method and update the **payers_pm_id** environment variable. To complete this task, use the [Tilia UI Sandbox](https://fake-integrator.staging.tilia-inc.com/ui/) 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](/guides/test-payments/). **To add a payment method:** 1. Open or switch to a browser window that has the [Tilia UI Sandbox](https://fake-integrator.staging.tilia-inc.com/ui/) running in it. 2. 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. ![Add card interface](/assets/tutorial-add-card-ui.c9b538fbc748685e70f1d3f03b86ea0270df5f75b159d706cf10f59ef0cf7f54.9c1bb791.png) 4. In the add card interface, enter the card info from [Test payment methods](/guides/test-payments/). 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. ```json { "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: 1. From the UI Sandbox, copy the `payment_method_id` value returned by the PAYMENT SELECTION widget. 2. In Postman, paste the `payment_method_id` value in the **payers_pm_id** environment variable. 3. Skip the next section and continue in the [Start token purchase](#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:** 1. Open the **_Manage user accounts** collection, and the **Add payment method to payer** folder. 2. Open the **Get payer's payment methods** request. 3. In the **URL** field, notice that the `account_id` parameter uses the **payers_account_id** environment variable. 4. In the **Get payer's payment methods** request, choose **Send**. 5. 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:** 1. Open the **_Manage user accounts** collection, and the **Payer from external platform** folder. 2. Open the **Get payer's external payment method** request. 3. In the **URL** field, notice that the `account_id` parameter uses the **payers_account_id** environment variable. 4. In the **Get payer's external payment method** request, choose **Send**. 5. After the response returns, open the response **Body** tab below the request to review the response body details. details summary Show a typical response body with the user's payment methods. ```json { "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:** 1. In the **_Manage user accounts** collection, in the **Buy tokens for payer** folder, open the **Start token purchase** request. 2. 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. ```json { "payment_method_id": "{{payers_pm_id}}", "amount": 1500000, "currency": "TIL", "destination_account_id": "{{payers_account_id}}" } ``` 3. In the **Start token purchase** request, choose **Send**. 4. 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. ```json { "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:** 1. In the **_Manage user accounts** collection, in the **Buy tokens for payer** folder, open the **Finish token purchase** request. 2. In the **URL** field, notice the **token_exchange_id** collection variable is used to identify the token purchase to finish. 3. In the **Finish token purchase** request, choose **Send**. 4. 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. ```json { "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](/tutorials/user-accounts/tutorial_user_wallets).