{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","openapiLink"]},"type":"markdown"},"seo":{"title":"Token Spend","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-spend","__idx":0},"children":["Token Spend"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This example explains how to create a transaction between two Tilia users using virtual tokens."]},{"$$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 scopes: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["read_payment_methods"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["write_user_tokens"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["write_invoices"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An account ID for the buyer who has a token wallet balance."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An account ID for the seller."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Depending on the terms of your agreement, sellers may be required to complete KYC before accruing a token balance. Contact Tilia with questions regarding your terms."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The process of creating a token-based transaction involves the following steps:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#step-1-set-up-the-purchase-transaction"},"children":["Step 1: Set up the purchase transaction"]}]},{"$$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":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Tokens are always deducted from the buyer's convertible wallet first, followed by the standard wallet. Received tokens are always placed in the seller's convertible wallet. For information on the token wallets, refer to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/core-concepts/virtual-tokens"},"children":["Virtual Tokens"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-set-up-the-purchase-transaction","__idx":2},"children":["Step 1: Set up the purchase transaction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once you have the user account information, you are ready to set up your purchase transaction in the form of an invoice. Tilia uses the concept of invoices to describe the detailed information required in order to process a transaction."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For this transaction type, 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 buyer's account ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invoice_type"]}," - the type of invoice. For token-based purchases, this must be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user_purchase_virtual"]}," if you are using standard invoices, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user_purchase_escrow_virtual"]}," if you are using escrow invoices"]},{"$$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 amount specified in the lowest denomination of your virtual tokens"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["line_items"]}," - an array of line items. For user-to-user transactions, the line item's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_type"]}," must be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user_to_user"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["destination_account_ID"]}," - the seller's account ID."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Additionally, you will want to provide details about the item(s) being purchased, including the seller's product description, SKU, and other transaction information. You can also include any fees you are charging."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example is for a simple invoice with a single item, where a portion of the proceeds are sent to the seller and a portion are sent to you.  More complex invoices can be built using various properties found in our invoicing API. Refer to the API reference for details."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The example below requires an API token with the scope ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["write_invoices"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl --location --request POST https://invoicing.tilia-inc.com/v2/invoice \\\n--header 'Authorization: Bearer <Access_Token>' \\\n--header 'Content-Type: application/json' \\\n","lang":"bash"},"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\": \"<buyer_account_id>\",\n    \"invoice_type\": \"user_purchase_escrow_virtual\",\n    \"reference_type\": \"product_purchase_id\",\n    \"reference_id\": \"purchase_id123\",\n    \"description\": \"A description of the invoice\",\n    \"line_items\": [\n        {\n           \"amount\": 10000,\n           \"currency\": \"VCD\",\n           \"description\": \"A description of the product\",\n            \"transaction_type\": \"user_to_user\",\n           \"recipients\": [\n                {\n                 \"amount\": 9500,\n                 \"currency\": \"VCD\",\n                 \"description\": \"A description for the seller\",\n                 \"destination_account_id\": \"<seller_account_id>\"\n                },\n                {\n                 \"amount\": 500,\n                 \"currency\": \"VCD\",\n                 \"description\": \"Fees charged to the seller\",\n                 \"integrator_revenue\": true // This optional value tells Tilia to allocate a portion of the proceeds to your publisher account. This is useful if you are charging the seller a fee for the transaction.\n                }\n           ]\n          }\n         ],\n     \"payment_methods\": [\n          {\n           \"amount\": 0\n          }\n     ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful request returns the HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}," status code along with a JSON response body containing the invoice details. You will use returned the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invoice_id"]}," field value in the next step."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-post-the-invoice-for-processing","__idx":4},"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 and payment."," ","To submit the invoice for processing, POST the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invoice_id"]}," to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/pay"]}," endpoint."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl --location --request POST https://invoicing.tilia-inc.com/v2/invoice/{invoice_id}/pay \\\n--header 'Authorization: Bearer <Access_Token>' \\\n--header 'Content-Type: application/json' \\\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful request returns the HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]}," status code along with a JSON response body containing the invoice details. The value for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["state"]}," will be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processing"]}," until the invoice is processed, at which time 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 invoice has been successfully paid."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]},", indicating the invoice could not be paid. 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 an invoice by calling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET https://invoicing.tilia-inc.com/v2/invoice/{invoice_id}"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-handle-the-completion-event","__idx":5},"children":["Step 3: Handle the completion event"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Although this step is not mandatory, we recommend implementing a webhook to notify you about changes to the transaction's status."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The webhook request body will be the same as the response body from create or pay invoice, but with a state of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]},". See the ",{"$$mdtype":"Tag","name":"OpenapiLink","attributes":{"link":"invoicing/openapi/payout/payoutcomplete","text":"Payout Completion webhook"},"children":[]},"  documentation for complete details."]},{"$$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 Spend","id":"token-spend","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Step 1: Set up the purchase transaction","id":"step-1-set-up-the-purchase-transaction","depth":2},{"value":"Request Body","id":"request-body","depth":4},{"value":"Step 2: Post the invoice for processing","id":"step-2-post-the-invoice-for-processing","depth":2},{"value":"Step 3: Handle the completion event","id":"step-3-handle-the-completion-event","depth":2}],"frontmatter":{"seo":{"title":"Token Spend"}},"lastModified":"2026-02-05T18:12:30.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/virtual_tokens/spend","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}