{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","partial"]},"type":"markdown"},"seo":{"title":"Token Convert","description":"Tilia Wallet Developer Documentation","siteUrl":"https://thunes-tilia-docs.redocly.app/","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"token-convert","__idx":0},"children":["Token Convert"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Another version of this information is available"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you're new to Tilia services, a newer version of this exercise is available in the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/tutorials/transactions"},"children":["Transaction Tutorials"]}," section of these docs, which might be an easier place to start."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To complete this example, you'll need the following:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An Access Token with the requisite scope: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["write_tokens"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The account ID for the user with a convertible token balance."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Token conversion requires that the user has completed KYC. For more information, refer to our ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/tos-and-kyc#about-know-your-customer-kyc"},"children":["KYC documentation"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The process of converting tokens involves the following steps:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#step-1-set-up-the-token-conversion-invoice"},"children":["Step 1: Set up the token conversion invoice"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#step-2-post-the-invoice-for-processing"},"children":["Step 2: POST the invoice for processing"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#step-3-handle-the-completion-event"},"children":["Step 3: Handle the completion event"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-set-up-the-token-conversion-invoice","__idx":2},"children":["Step 1: Set up the token conversion invoice"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To convert tokens. you need to provide the following values:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account_id"]}," - the user's account ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currency"]}," - the 3-character code associated with your virtual tokens"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," - the number of virtual tokens to convert, specified in the lowest denomination of your virtual tokens"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The example below requires an API token with the scope ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["write_tokens"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"curl --location --request POST https://invoicing.tilia-inc.com/v2/token/convert \\\n--header 'Authorization: Bearer <Access_Token>' \\\n--header 'Content-Type: application/json' \\\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"request-body","__idx":3},"children":["Request Body"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"account_id\": \"<user_account_id>\",\n  \"amount\": 250,\n  \"currency\": \"VCD\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"sample-response","__idx":4},"children":["Sample response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful request returns the HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}," status code and a JSON response body containing the invoice details. You will use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invoice_id"]}," field value in the next step."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"  {\n    \"status\": \"Success\",\n    \"payload\": {\n      \"token_exchange_id\": \"vtok_1y9CqqiLJ6s0W2hsPgQqLkvR4og\",\n      \"account_id\": \"4ba04731-9f66-4123-a8a1-7ef815444444\",\n      \"destination_wallet_id\": \"7453875e-9b0f-4ef1-ba2a-7b89d155fe2f\",\n      \"direction\": \"token_convert\",\n      \"invoice_id\": \"81eab454-81c0-4d33-b9e8-310fc0e1a828\",\n      \"virtual_amount\": 250,\n      \"virtual_currency\": \"VCD\",\n      \"amount_usd\": 250,\n      \"exchange_rate\": 100.01,\n      \"exchange_rate_direction\": \"virtual_to_usd\",\n      \"fee_amount\": 25,\n      \"fee_currency\": \"VCD\",\n      \"status\": \"OPEN\",\n      \"created\": \"2006-01-02T15:04:05Z07:00\",\n      \"updated\": \"2006-01-02T15:04:05Z07:00\"\n    }\n  }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-post-the-invoice-for-processing","__idx":5},"children":["Step 2: Post the invoice for processing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the previous step, we created the invoice. Next, it needs to be submitted for processing."," ","To process the invoice, POST the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token_exchange_id"]}," to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/token/convert/"]}," endpoint."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"curl --location --request POST https://invoicing.tilia-inc.com/v2/token/convert/{token_exchange_id} \\\n--header 'Authorization: Bearer <Access_Token>' \\\n--header 'Content-Type: application/json' \\\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"sample-response-1","__idx":6},"children":["Sample response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful request returns the HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]}," status code and a JSON response body containing the invoice details. Note that the value for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["state"]}," has updated from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["open"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"  {\n    \"status\": \"Success\",\n    \"payload\": {\n      \"token_exchange_id\": \"vtok_1y9CqqiLJ6s0W2hsPgQqLkvR4og\",\n      \"account_id\": \"4ba04731-9f66-4123-a8a1-7ef815444444\",\n      \"destination_wallet_id\": \"7453875e-9b0f-4ef1-ba2a-7b89d155fe2f\",\n      \"direction\": \"token_convert\",\n      \"invoice_id\": \"81eab454-81c0-4d33-b9e8-310fc0e1a828\",\n      \"virtual_amount\": 250,\n      \"virtual_currency\": \"VCD\",\n      \"amount_usd\": 250,\n      \"exchange_rate\": 100.01,\n      \"exchange_rate_direction\": \"virtual_to_usd\",\n      \"fee_amount\": 25,\n      \"fee_currency\": \"VCD\",\n      \"status\": \"SUCCESS\",\n      \"created\": \"2006-01-02T15:04:05Z07:00\",\n      \"updated\": \"2006-01-02T15:04:05Z07:00\"\n    }\n  }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the invoice is processed, the state will update to either:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]},", indicating the tokens have been converted."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]},", indicating the tokens could not be converted. In this case, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failure_reason"]}," field returns additional information describing the failure."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can check the status of virtual token transaction by calling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET https://invoicing.tilia-inc.com/v2/token/{token_exchange_id}"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-handle-the-completion-event","__idx":7},"children":["Step 3: Handle the completion event"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Although this step is optional, we recommend implementing a webhook to notify you about events related to the token exchange."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information about developing and registering webhook handlers, visit ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/webhooks/"},"children":["Webhooks"]},"."]}]},"headings":[{"value":"Token Convert","id":"token-convert","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Step 1: Set up the token conversion invoice","id":"step-1-set-up-the-token-conversion-invoice","depth":2},{"value":"Request Body","id":"request-body","depth":4},{"value":"Sample response","id":"sample-response","depth":4},{"value":"Step 2: Post the invoice for processing","id":"step-2-post-the-invoice-for-processing","depth":2},{"value":"Sample response","id":"sample-response-1","depth":4},{"value":"Step 3: Handle the completion event","id":"step-3-handle-the-completion-event","depth":2}],"frontmatter":{"seo":{"title":"Token Convert"}},"lastModified":"2026-02-05T18:12:30.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/virtual_tokens/convert","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}