Token Spend

This example explains how to create a transaction between two Tilia users using virtual tokens.

Prerequisites

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

• An Access Token with the requisite scopes: read_payment_methods , write_user_tokens and write_invoices
• An account ID for the buyer who has a token wallet balance.
• An account ID for the seller.

The process of creating a token-based transaction involves the following steps:

Step 1: Set up the purchase transaction

Step 2: POST the invoice for processing

Step 3: Handle the completion event

Step 1: Set up the purchase transaction

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.

For this transaction type, you need to provide the following values:

• account_id - the buyer's account ID
• invoice_type - the type of invoice. For token-based purchases, this must be user_purchase_virtual if you are using standard invoices, or user_purchase_escrow_virtual if you are using escrow invoices
• currency - the 3-character code associated with your virtual tokens
• amount - the amount specified in the lowest denomination of your virtual tokens
• line_items - an array of line items. For user-to-user transactions, the line item's transaction_type must be user_to_user .
• destination_account_ID - the seller's account ID.

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.

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.

The example below requires an API token with the scope write_invoices.

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

Request Body

{
    "account_id": "<buyer_account_id>",
    "invoice_type": "user_purchase_escrow_virtual",
    "reference_type": "product_purchase_id",
    "reference_id": "purchase_id123",
    "description": "A description of the invoice",
    "line_items": [
        {
           "amount": 10000,
           "currency": "VCD",
           "description": "A description of the product",
            "transaction_type": "user_to_user",
           "recipients": [
                {
                 "amount": 9500,
                 "currency": "VCD",
                 "description": "A description for the seller",
                 "destination_account_id": "<seller_account_id>"
                },
                {
                 "amount": 500,
                 "currency": "VCD",
                 "description": "Fees charged to the seller",
                 "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.  
                }
           ]
          }
         ],
     "payment_methods": [
          {
           "amount": 0
          }
     ]
}

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

Step 2: Post the invoice for processing

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 invoice_id to the /pay endpoint.

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

A successful request returns the HTTP 200 OK status code along with a JSON response body containing the invoice details. The value for state will be processing until the invoice is processed, at which time the state will update to either:

• success , indicating the invoice has been successfully paid.
• failed , indicating the invoice could not be paid. In this case, the failure_reason field returns additional information describing the failure.

You can check the status of an invoice by calling GET https://invoicing.tilia-inc.com/v2/invoice/{invoice_id}.

Step 3: Handle the completion event

Although this step is not mandatory, we recommend implementing a webhook to notify you about changes to the transaction's status.

The webhook request body will be the same as the response body from create or pay invoice, but with a state of success or failed. See the Invoice Completion webhook documentation for complete details.

For more information about developing and registering webhook handlers, visit Webhooks.