Token Purchase

A token purchase is a special transaction type that is used for your customers to purchase virtual tokens from you. This transaction consists of collecting payment information, creating an invoice, and submitting the invoice to Tilia for processing. See Virtual Tokens Overview for information about the special features of Tilia tokens.

This guide explains how to complete a token purchase.

Another version of this information is available

If you're new to Tilia services, a newer version of this example is available in the User Account Tutorials 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 scopes: read_payment_methods , write_tokens and write_invoices
  • An account ID for the buyer. Refer to Registering Users for information on creating user accounts.
  • A web page containing the Tilia widget script. Refer to Widget Integration for instructions on setting this up.
  • A payment method. Refer to Test Payments for payment methods you can use in testing.
attention

Your publisher account must be configured to process token purchases.

attention

Purchased tokens are always deposited to the buyer's standard token wallet. For information on token wallets, refer to Virtual Tokens.

The process of creating a transaction involves the following steps:

Step 1: Create a secure redirect URL for the buyer

Step 2: Call the payment selection flow to obtain payment details

Step 3: Set up the purchase transaction

Step 4: POST the invoice for processing

Step 5: Handle the completion event

Step 1: Create a secure redirect URL

To complete a purchase, you'll need to obtain the buyer's payment information. To start, you'll pass the buyer's account ID to create a redirect URL. This URL creates a secure user session, forming the basis for calling the Tilia Purchase flow.

Copy
Copied
curl --location --request POST https://auth.tilia-inc.com/authorize/user \
--header 'Authorization: Bearer <Access_Token>' \
--header 'Content-Type: application/json' \

Request Body

Copy
Copied
{
  "account_id": "string"
}

Sample response

Copy
Copied
{
  "status": "Success",
  "message": [],
  "codes": [],
  "payload": {
    "redirect": "https://web.tilia-inc.com/ui/appauth/19a4a2b0-364c-4cad-a895-14c57bcd4e7c"
  }
}

Included in the response is a redirect URL used in the next step.

Step 2: Call the payment selection flow to obtain payment details

The Payment Selection flow is a web UI that allows the purchasing user to choose a payment method. If the user does not have a stored payment method, they will be able to add one. Upon completion of the flow, an array of IDs for the user's payment method(s) is passed back to you for use in creating the transaction.

Users must have a signed copy of the most recent Tilia Terms of Service (TOS) on file. If the user has not accepted the TOS, or if there is an updated version available, they are presented with a TOS screen which must be accepted before they can select a payment method.

From the widget page, call the following JavaScript to execute the purchase flow.

Copy
Copied
window.Tilia.execute({
	rootId: "< YOUR-ELEMENT-ID >",
	flow: "payment-selection",
	flowConfig: {
            // Optionally include transactionDetails to allow the user the key functionality
            // of choosing their remaining wallet balance before a second payment method.
            transactionDetails: {
                transaction_amount: "< TRANSACTION-AMOUNT >",
                currency: "USD"
            }
        },
	redirect: "< WIDGET-REDIRECT-URL >",
	onComplete: handleComplete,
	onError: handleError,
});

The widget invokes the handleComplete callback with the result of the flow.

If the user cancels anywhere in the flow:

Copy
Copied
{
	"source": “tilia”,
	"event": “tilia.payment-selection.complete”,
	"state": “cancel”,
}

If the user completes the flow:

Copy
Copied
{
    "source": "tilia",
    "event": "tilia.payment-selection.complete",
    "state": "complete"
    "paymentMethods": [
        {
            "payment_method_id": "a787923c-4b82-4400-81e4-34f7baa849b3",
            "amount": 5000
        },
        {
            "payment_method_id": "5ee85a7a-8319-4a53-837c-5d909d184442",
            "amount": 0
        }
    ]
}

You will be able to pass in the paymentMethods array into the next step.

Step 3: Set up the purchase transaction

Once you have the user's payment_method_id, you are ready to set up your token purchase invoice.

You need to provide the following values:

  • payment_method_id - the buyer's payment method id returned by the payment flow
  • currency - the 3-character code associated with your virtual tokens
  • amount - the number of virtual tokens to purchase, specified in the lowest denomination of your virtual tokens
  • source_wallet_id - your publisher wallet to be used in processing the transfer of funds. Leave this value blank to use the default (appropriate in most cases)
  • destination_account_id - an optional account ID for the recipient of the tokens. If omitted, the tokens will go to the account associated with the payment method.

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

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

Request Body

Copy
Copied
{
  "payment_method_id": "d3da84e7-a203-4453-a016-407e91eeeeee",
  "amount": 250,
  "currency": "VCD",
  "destination_account_id": "4ba04731-9f66-4123-a8a1-7ef815444444"
}

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.

Copy
Copied
  {
    "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_purchase",
      "invoice_id": "81eab454-81c0-4d33-b9e8-310fc0e1a828",
      "virtual_amount": 250,
      "virtual_currency": "VCD",
      "amount_usd": 250,
      "exchange_rate": 100.01,
      "exchange_rate_direction": "usd_to_virtual",
      "fee_amount": 25,
      "fee_currency": "VCD",
      "status": "OPEN",
      "created": "2006-01-02T15:04:05Z07:00",
      "updated": "2006-01-02T15:04:05Z07:00"
    }
  }

Step 4: 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 token_exchange_id to the /token/purchase/ endpoint.

Copy
Copied
curl --location --request POST https://invoicing.tilia-inc.com/v2/token/purchase/{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.

Copy
Copied
{
  "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_purchase",
    "invoice_id": "81eab454-81c0-4d33-b9e8-310fc0e1a828",
    "virtual_amount": 250,
    "virtual_currency": "VCD",
    "amount_usd": 250,
    "exchange_rate": 100.01,
    "exchange_rate_direction": "usd_to_virtual",
    "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 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 virtual token transaction by calling GET https://invoicing.tilia-inc.com/v2/token/{token_exchange_id}.

Step 5: 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.