# Token Convert

Token conversion enables your sellers to convert their virtual tokens to fiat currency, which is stored as a wallet balance. Stored balances may be used for purchases or cashed out via a payout.

Another version of this information is available
If you're new to Tilia services, a newer version of this exercise is available in the [Transaction Tutorials](/tutorials/transactions) section of these docs, which might be an easier place to start.

## Prerequisites

To complete this example, you'll need the following:

- An Access Token with the requisite scope: `write_tokens`
- The account ID for the user with a convertible token balance.


Token conversion requires that the user has completed KYC. For more information, refer to our [KYC documentation](/guides/tos-and-kyc#about-know-your-customer-kyc).

The process of converting tokens involves the following steps:

[Step 1: Set up the token conversion invoice](#step-1-set-up-the-token-conversion-invoice)

[Step 2: POST the invoice for processing](#step-2-post-the-invoice-for-processing)

[Step 3: Handle the completion event](#step-3-handle-the-completion-event)

## Step 1: Set up the token conversion invoice

To convert tokens. you need to provide the following values:

- `account_id` - the user's account ID
- `currency` - the 3-character code associated with your virtual tokens
- `amount` - the number of virtual tokens to convert, specified in the lowest denomination of your virtual tokens


The example below requires an API token with the scope `write_tokens`.


```
curl --location --request POST https://invoicing.tilia-inc.com/v2/token/convert \
--header 'Authorization: Bearer <Access_Token>' \
--header 'Content-Type: application/json' \
```

#### Request Body


```json
{
  "account_id": "<user_account_id>",
  "amount": 250,
  "currency": "VCD"
}
```

#### Sample response

A successful request returns the HTTP `201 Created` status code and a JSON response body containing the invoice details. You will use the `invoice_id` field value in the next step.


```json
  {
    "status": "Success",
    "payload": {
      "token_exchange_id": "vtok_1y9CqqiLJ6s0W2hsPgQqLkvR4og",
      "account_id": "4ba04731-9f66-4123-a8a1-7ef815444444",
      "destination_wallet_id": "7453875e-9b0f-4ef1-ba2a-7b89d155fe2f",
      "direction": "token_convert",
      "invoice_id": "81eab454-81c0-4d33-b9e8-310fc0e1a828",
      "virtual_amount": 250,
      "virtual_currency": "VCD",
      "amount_usd": 250,
      "exchange_rate": 100.01,
      "exchange_rate_direction": "virtual_to_usd",
      "fee_amount": 25,
      "fee_currency": "VCD",
      "status": "OPEN",
      "created": "2006-01-02T15:04:05Z07:00",
      "updated": "2006-01-02T15:04:05Z07:00"
    }
  }
```

## Step 2: Post the invoice for processing

In the previous step, we created the invoice. Next, it needs to be submitted for processing.
To process the invoice, POST the `token_exchange_id` to the `/token/convert/` endpoint.


```
curl --location --request POST https://invoicing.tilia-inc.com/v2/token/convert/{token_exchange_id} \
--header 'Authorization: Bearer <Access_Token>' \
--header 'Content-Type: application/json' \
```

#### Sample response

A successful request returns the HTTP `200 OK` status code and a JSON response body containing the invoice details. Note that the value for `state` has updated from `open` to `success`.


```json
  {
    "status": "Success",
    "payload": {
      "token_exchange_id": "vtok_1y9CqqiLJ6s0W2hsPgQqLkvR4og",
      "account_id": "4ba04731-9f66-4123-a8a1-7ef815444444",
      "destination_wallet_id": "7453875e-9b0f-4ef1-ba2a-7b89d155fe2f",
      "direction": "token_convert",
      "invoice_id": "81eab454-81c0-4d33-b9e8-310fc0e1a828",
      "virtual_amount": 250,
      "virtual_currency": "VCD",
      "amount_usd": 250,
      "exchange_rate": 100.01,
      "exchange_rate_direction": "virtual_to_usd",
      "fee_amount": 25,
      "fee_currency": "VCD",
      "status": "SUCCESS",
      "created": "2006-01-02T15:04:05Z07:00",
      "updated": "2006-01-02T15:04:05Z07:00"
    }
  }
```

When the invoice is processed, the state will update to either:

- `success`, indicating the tokens have been converted.
- `failed`, indicating the tokens could not be converted. In this case, the `failure_reason` field returns additional information describing the failure.


You can check the status of virtual token transaction by calling `GET https://invoicing.tilia-inc.com/v2/token/{token_exchange_id}`.

## Step 3: Handle the completion event

Although this step is optional, we recommend implementing a webhook to notify you about events related to the token exchange.

For more information about developing and registering webhook handlers, visit [Webhooks](/webhooks/).