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.

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.

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.

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

Request Body

{
  "account_id": "string"
}

Sample response

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

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:

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

If the user completes the flow:

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

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

Request Body

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

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

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.

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