Tutorial: Make standard transactions

In this tutorial, you create an invoice and complete a transaction between users using tokens.

Allow about 10 minutes to complete this tutorial.

Transactions made in your application are described by invoices. Just as in a real-world transaction, Tilia's invoices contain information about the goods or services being exchanged and the participants in the transaction.

The following diagram shows the process of a transaction between users using tokens.

User-to-user transaction process

The exercises in this tutorial start after the user selects an item in the application. The application takes the necessary information about the payer, the recipient, and the details from the payer's catalog selections to create the transaction's invoice.

A new invoice for a user-to-user, transaction that's using tokens needs at least the following information:

Product information that describes what's being exchanged for tokens
Payer's account_id : from the paying user's account information
source_wallet_id : the wallet ID of the payer's wallet
destination_account_id : the recipient's account ID, retrieved from the recipient or catalog.
destination_wallet_id : the recipient's wallet to receive the tokens from the sale.

In an actual implementation, the application provides this information; so it's simulated in this tutorial.

API operations in this tutorial

Tutorial interaction	Tilia APIs used	Scope
Create a user-to-user invoice	Create a new invoice	`write_invoices`
Pay a user-to-user-invoice	Pay invoice	`write_invoices`

To complete this tutorial

This tutorial uses the Explore Tilia transactions collection from the shared Postman workspace.

To complete this tutorial successfully:

Make sure the software described in Get started with the tutorials has been installed on your system and configured.
Make sure that you have initialized the Tilia Client Info environment variables by running the User account tutorials .
In Postman:
1. Open the Tilia tutorial workspace you created in Get started with the tutorials for this tutorial.
2. Make sure you have the Explore Tilia transactions collection forked to your Tilia tutorial workspace .
3. Make sure that you've selected the Tilia Client Info environment and confirmed that it has:
  1. Your Tilia developer credentials.
  2. All of the user-related environment variables with Current values defined.
4. In your Tilia tutorial workspace , open the list of Collections .
5. In the list of Collections , expand the Explore Tilia transactions collection.
6. If it's been more than an hour since you last got an access token for this collection, get a new one as described in Tutorial: Transactions overview , and then return to continue here.

Create a user-to-user invoice

This exercise creates an invoice for one user to sell something to another.

To create a user-to-user invoice, collect or create the following information:

A summary description of the invoice
The product information
payer's account_id : from the paying user's account information
source_wallet_id : the wallet ID of the payer's wallet. If omitted, the default wallet for the account_id is used.
destination_account_id : the recipient's account ID, retrieved from the recipient or catalog. If this property is used, the default wallet is used. If destination_account_id is used, destination_wallet_id can be omitted.
destination_wallet_id : the recipient's wallet to receive the tokens from the sale. This is the value used in this exercise. If destination_wallet_id is used, destination_account_id can be omitted.

Copy

Copied

{
   "account_id": "{{payers_account_id}}",
   "description": "Digital product order",
   "line_items": [
     {
       "amount": 200000,
       "currency": "TIL",
       "transaction_type": "user_to_user",
       "description": "In-game digital bundle",
       "recipients": [
         {
           "source_wallet_id": "{{payers_wallet_id}}",
           "destination_wallet_id": "{{recipients_wallet_id}}"
         }
       ]
     }
   ]
}

To send this information and create a new user-to-user invoice, in Postman:

In the Explore Tilia transactions collection, in the Standard transaction folder, open the Create a user-to-user invoice request.
In the request Body field, notice the invoice information described previously.
In the Create a user-to-user invoice request, choose Send .
After the response returns, open the response Body tab below the request to review the response body details.

A typical response body looks like the following.

Show a typical response body with the transaction info.

Copy

Copied

{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "invoice_id": "57592e8c-df91-4c7d-aa5e-c62eabe32a83",
        "account_id": "acct_2Ym84qq2ieeaZkOHUM1xeF8uJtu",
        "invoice_type": "user_purchase_virtual",
        "reference_type": "",
        "reference_id": "",
        "state": "OPEN",
        "description": "Digital product order",
        "metadata": {},
        "summary": {
            "total_amount": 200000,
            "total_amount_usd": 2000,
            "currency": "TIL",
            "display_amount": "TIL 200000",
            "subtotal": {
                "total_amount": 200000,
                "total_amount_usd": 2000,
                "currency": "TIL",
                "display_amount": "TIL 200000"
            },
            "tax": {
                "total_amount": 0,
                "total_amount_usd": 0,
                "currency": "TIL",
                "display_amount": "TIL 0.00"
            },
            "payment_breakdown": [],
            "tax_calculation": ""
        },
        "failure_code": "",
        "failure_reason": "",
        "created": "0001-01-01T00:00:00Z",
        "updated": "0001-01-01T00:00:00Z",
        "payment_methods": {
            "41a64965-f990-4323-8781-ec56c5e365fc": {
                "provider": "wallet",
                "payment_method_id": "41a64965-f990-4323-8781-ec56c5e365fc",
                "authorized_amount": 200000,
                "currency": "TIL",
                "display_string": "Standard TIL wallet",
                "display_amount": "TIL 200000",
                "tags": {
                    "standard": {
                        "tag_id": "",
                        "tag": ""
                    }
                },
                "subitems": {}
            }
        },
        "line_items": {
            "3fa9fc37-33c8-4126-be80-42b50f3dacfb": {
                "line_item_id": "3fa9fc37-33c8-4126-be80-42b50f3dacfb",
                "product_sku": "",
                "product_code": "",
                "amount": 200000,
                "currency": "TIL",
                "display_amount": "TIL 200000",
                "reference_type": "",
                "reference_id": "",
                "transaction_type": "user_to_user_virtual",
                "description": "In-game digital bundle",
                "metadata": null,
                "tags": null,
                "sort_order": 0,
                "subitems": {
                    "914d1f91-0c6b-4c82-8ef9-d646e7977686": {
                        "subitem_id": "914d1f91-0c6b-4c82-8ef9-d646e7977686",
                        "amount": 200000,
                        "currency": "TIL",
                        "display_amount": "TIL 200000",
                        "reference_type": "invoicing.invoice_line_item_v2.line_item_id",
                        "reference_id": "3fa9fc37-33c8-4126-be80-42b50f3dacfb",
                        "subitem_type": "user_recipient_virtual",
                        "description": "",
                        "metadata": null,
                        "source_account_id": "75452177-cad5-42bd-8530-4fb86ecc6fa9",
                        "source_payment_method_id": "",
                        "source_wallet_id": "41f5e46b-76ef-4bf8-b661-d5fb30159713",
                        "destination_account_id": "acct_2Ym85jZvz2HNx9q2LuouUymkFz3",
                        "destination_payment_method_id": "",
                        "destination_wallet_id": "36dfbb98-2551-40c8-a60c-617e29bdbb48",
                        "tags": null
                    }
                }
            }
        },
        "subitems": {},
        "tags": null
    }
}

The status of the transaction is indicated by the payload.state value, which is OPEN.

Notice that the invoice data returned in the response body includes many more properties than were sent in the request. For more information about what you can include when creating an invoice, review Create a new invoice.

Pay a user-to-user-invoice

This exercise pays the invoice created in the previous exercise.

The previous exercise only creates an invoice in Tilila's system. No tokens have moved, yet. This exercise finishes the purchase process and transfers tokens from the payer and the recipient.

To pay the invoice, in Postman:

In the Explore Tilia transactions collection, in the Standard transaction folder, open the Pay a user-to-user-invoice request.
In the URL field, notice that the invoice_id returned by the preceding request is used to identify the invoice to pay.
In the Pay a user-to-user-invoice request, choose Send .
After the response returns, open the response Body tab below the request to review the response body details.

Show a typical response body with the completed transaction info.

Copy

Copied

{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "invoice_id": "57592e8c-df91-4c7d-aa5e-c62eabe32a83",
        "account_id": "acct_2Ym84qq2ieeaZkOHUM1xeF8uJtu",
        "invoice_type": "user_purchase_virtual",
        "reference_type": "",
        "reference_id": "",
        "state": "SUCCESS",
        "description": "Digital product order",
        "metadata": {},
        "summary": {
            "total_amount": 200000,
            "total_amount_usd": 2000,
            "currency": "TIL",
            "display_amount": "TIL 200000",
            "subtotal": {
                "total_amount": 200000,
                "total_amount_usd": 2000,
                "currency": "TIL",
                "display_amount": "TIL 200000"
            },
            "tax": {
                "total_amount": 0,
                "total_amount_usd": 0,
                "currency": "TIL",
                "display_amount": "TIL 0.00"
            },
            "payment_breakdown": [],
            "tax_calculation": ""
        },
        "failure_code": "",
        "failure_reason": "",
        "created": "2023-12-08T21:19:39Z",
        "updated": "2023-12-08T21:19:39Z",
        "payment_methods": {
            "41a64965-f990-4323-8781-ec56c5e365fc": {
                "provider": "wallet",
                "payment_method_id": "41a64965-f990-4323-8781-ec56c5e365fc",
                "authorized_amount": 200000,
                "currency": "TIL",
                "display_string": "",
                "display_amount": "TIL 200000",
                "tags": null,
                "subitems": {}
            }
        },
        "line_items": {
            "3fa9fc37-33c8-4126-be80-42b50f3dacfb": {
                "line_item_id": "3fa9fc37-33c8-4126-be80-42b50f3dacfb",
                "product_sku": "",
                "product_code": "",
                "amount": 200000,
                "currency": "TIL",
                "display_amount": "TIL 200000",
                "reference_type": "",
                "reference_id": "",
                "transaction_type": "user_to_user_virtual",
                "description": "In-game digital bundle",
                "metadata": null,
                "tags": null,
                "sort_order": 0,
                "subitems": {
                    "914d1f91-0c6b-4c82-8ef9-d646e7977686": {
                        "subitem_id": "914d1f91-0c6b-4c82-8ef9-d646e7977686",
                        "amount": 200000,
                        "currency": "TIL",
                        "display_amount": "TIL 200000",
                        "reference_type": "invoicing.invoice_line_item_v2.line_item_id",
                        "reference_id": "3fa9fc37-33c8-4126-be80-42b50f3dacfb",
                        "subitem_type": "user_recipient_virtual",
                        "description": "",
                        "metadata": null,
                        "source_account_id": "75452177-cad5-42bd-8530-4fb86ecc6fa9",
                        "source_payment_method_id": "",
                        "source_wallet_id": "41f5e46b-76ef-4bf8-b661-d5fb30159713",
                        "destination_account_id": "acct_2Ym85jZvz2HNx9q2LuouUymkFz3",
                        "destination_payment_method_id": "",
                        "destination_wallet_id": "36dfbb98-2551-40c8-a60c-617e29bdbb48",
                        "tags": null
                    }
                }
            }
        },
        "subitems": {},
        "tags": null
    }
}

The invoice returned in the response buffer shows the paid invoice in the value of payload.state, which is now SUCCESS.

Next steps

The exercises in this tutorial used Postman to call the Tilia APIs. For an example of how to integrate the transaction demonstrated in this tutorial into a web page, see User-to-User Purchase.

If you're curious, you can review the wallet balances of the users involved in this transaction by using the exercises in the Get info about transactions tutorial.

You can also return to the Transaction tutorials overview and find another transaction tutorial, or just go to the next transaction tutorial.