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.

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.

The process of converting tokens involves the following steps:

Step 1: Set up the token conversion invoice

Step 2: POST the invoice for processing

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

{
  "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.

  {
    "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.

  {
    "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.