Tutorial: Payout to user

In this tutorial, you create a payout transaction that takes tokens that a user has earned from their convertible token wallet and pays out their equivalent value in fiat currency to an external payment method, such as PayPal.

Allow about 10 minutes to complete this tutorial.

This transaction uses the Tilia-hosted PAYOUT FULL UI widget to create a payout request, and the Tilia API to complete the payout request.

The following diagram shows the process of a payout to a user.

User payout process

API operations in this tutorial

Tutorial interaction	Tilia APIs used	Scope
Check the user's wallet balances	Get wallet balances	`read_wallets`
Complete a payout request	Get payout requests Execute payout Cancel a payout request	`read_process_credits` `write_process_credits` `write_process_credits)`

To complete this tutorial

This tutorial uses accounts created and updated by requests in the _Manage user accounts and Explore Tilia transactions collections 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.
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 and Explore Tilia transactions collections forked to your Tilia tutorial workspace .
3. Make sure that you've selected the Tilia Client Info environment and confirmed that it has your Tilia developer credentials.
4. In your Tilia tutorial workspace , open the list of Collections .

Payout to user

This exercise converts a token value to its corresponding fiat currency value and deposits the fiat currency value in the user's payment method, such as PayPal.

In these tutorials, the recipient user tends to receive the most tokens, so the recipient's user account is used in this exercise. After a seller (the recipient) has earned enough tokens, they can collect the token value as fiat currency. Generally, the seller should have convertible tokens worth USD $5.00 or more before they initiate a payout.

Check the user's wallet balances

This exercise checks the recipient's token balance to make sure they have enough tokens to pay out before starting the payout process.

To check the recipient's token balances, in Postman:

In the _Manage user accounts collection, open the Get wallet balances folder.
Open the Get recipient's wallet balances request, and then choose Send .
After the response returns, open the response Body tab below the request to review the wallet balances.

Review the token balances before continuing.

If the recipient doesn't have at least $5 USD worth of tokens (50,000 TIL) in their convertible wallet, run the Make standard transactions tutorial several times to provide convertible tokens from those sales to the payer.

If the payer runs out of tokens to make purchases in the Make standard transactions tutorial, run the Buy tokens for payer tutorial to replenish the payer's token wallet.

After you have replenished the recipient's token balance:

In Postman, open the Get recipient's wallet balances request, and then choose Send to get the updated wallet balances.
After the response returns, open the response Body tab below the request to review the wallet balances.

Confirm the recipient has at least 100,000 tokens before continuing.

Start a payout by using the Payout UI widget

To start a payout using the Payout UI widget:

In Postman:
1. open the Tilia Client Info environment.
2. In the Tilia Client Info environment, locate and copy the values of these environment variables:
  - tilia_client_id
  - tilia_client_secret
  - recipient_account_id
In another window, open the UI Sandbox
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 PAYOUT FULL option from the left column,and click the "W" to open the PAYOUT FULL widget.
4. You might be asked to accept Tilia's Terms of Service. If so, accept and continue.
5. You might be asked for tax information if you haven't already provided that for the recipient. If so, provide the information requested to continue.
6. If you don't have a payment method suitable for a payout, add a payment method to continue.
7. In the Cashout Amount field, enter the amount of tokens that you'd like to have paid out.
8. Review the fee and Cashout amount, and then choose the Cashout button to complete the payout request.

At this point, the tokens have been taken from the recipient's wallet to hold in escrow and the payout request is pending. The next exercises complete the payout request.

Complete a payout request

You can complete a payout by either paying it or canceling it. This exercise presents both options; however, for any one request, you can only pay or cancel it. For example, you can't cancel a payout after you've paid it. Likewise, you can't pay a payout after you cancel it.

To select the payout request to complete, in Postman:

Open the Postman console.
In the Explore Tilia transactions collection, open the Payout to recipient folder
Open the Get payout requests request, and choose Send .
After the response returns, review the Postman console log for messages similar to the following to confirm the ID of a pending payout was saved.
Copy

Copied
```
Updated the last_payout_in_escrow collection variable with pending payout ID: 017e8d6d-bea0-4e4b-866d-fc168cc0bcf7
```

With the ID of the pending payout saved, choose how you want to complete the payout and perform the corresponding procedure.

To pay the pending payout, in Postman:

In the Payout to recipient folder, open the Complete pending request request, and choose Send .
After the response returns, review the Postman console log for a message similar to the following to confirm that the pending payout was saved.
Copy

Copied
```
Payout ID: 6646b471-c810-4ed3-9213-f597e6352546 paid successfully.
```

This completes the payout request and deposits the payout value to the recipient's payment method.

To cancel the pending payout, in Postman:

In the Payout to recipient folder, open the Cancel pending request request, and choose Send .
After the response returns, review the Postman console log for a message similar to the following to confirm that the pending payout was saved.
Copy

Copied
```
Payout ID: 63cf2a26-d490-4555-a642-6b31374d30e5 canceled successfully.
```

This completes the payout request and returns the tokens to the recipient's wallet.

Next steps

The exercises in this tutorial used the Tilia UI Sandbox to create payout requests and Postman to call the Tilia APIs to complete those requests. For information about how to use the Tilia UI widgets to implement this feature, visit Requesting payouts.

If you're curious, you can review the wallet balances of the users involved in this transaction by using the exercises in the Get info about transactions tutorial.

You can also return to the Transaction tutorials overview and find another transaction tutorial, or just go to the next transaction tutorial.