Tutorial: Get info about transactions

In this tutorial, you get information about a user's transaction history and specific transactions by using the Tilia API and Tilia UI widgets.

Allow about 15 minutes to complete this tutorial, if you run all the exercises.

You can repeat this tutorial as often as you'd like. For example, after completing a transaction tutorial, you can run this tutorial to review the transactions as they appear in the user's account.

If you are looking for the wallet balances of the accounts that were involved in a transaction, you can review the wallet balances from the _Manage user accounts collection and the requests in the View wallet balances folder.

API operations in this tutorial

To complete this tutorial

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

To complete this tutorial successfully:

1. Make sure the software described in Get started with the tutorials has been installed on your system and configured.
2. Make sure that you have initialized the Tilia Client Info environment variables by running the User account tutorials .
3. The default invoice ID used is that of the most recently created invoice. If you'd like to look up any other invoice, you must provide a valid invoice number, or look up the invoice in the user's transaction history.
4. 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.

View transaction history

This exercise demonstrates two different ways to view a user's transaction history:

• Transaction history UI widget
• Transaction history API

The tasks in this exercise display information about a user's transactions. The requests are found in the Explore Tilia transactions collection, in the Transaction history folder.

After a user-to-user invoice is paid, the transaction appears in both the payer's and the recipient's transaction history.

A user's transaction history and details about a single transaction can be retrieved by using the UI widget or the API.

Get user's transaction history (UI)

The following images are screenshots taken after a user-to-user transaction. Notice that the payer's transaction history shows a purchase; while the recipient's transaction history shows a sale.

Payer's transaction history showing purchases.

Recipient’s transaction history showing sales.

To display these screens, use the Tilia UI Sandbox.

Before you start, make sure you have:

• Your Tilia developer credentials.
• The user's account ID from the environment variables.

To display a user's transaction history in the UI widget:

1. Open a browser window with the Tilia UI Sandbox and continue in the UI Sandbox.
2. Enter your Tilia developer credentials, if necessary. They should be retained if you've entered them recently.
3. Enter the user's account ID.
4. Choose the TRANSACTION HISTORY option, and then select the "W" icon.
5. View the Transaction history widget.
6. After you review the widget, close the widget.

Repeat these steps with another user's account ID to review their transaction history.

For information about how to integrate this widget into your application, visit Transaction History.

Get user's transaction history (API)

This exercise describes these three requests from the Transaction history folder in the Explore Tilia transactions collection.

• Get payer's transaction history
• Get recipient's transaction history
• Get creator's transaction history

When text refers to the user's transaction history, refer to the request that represents the user in which you are intersted.

To get a user's transaction history:

1. In the Explore Tilia transactions collection, in the Transaction history folder, open the request for that user.
2. In the URL field, notice that the wallet_id field of the URL uses wallet ID value for that user from the environment variables.
3. In the request, choose Send .
4. After the response returns, open the response Body tab below the request to review the response body details.

A typical response body with a history of only one transaction looks like the following. The response body for users with more transactions will be longer.

Notice that the data returned by the API contains information about the transaction amount and also the wallet balance after the transaction in denominations of tokens and USD. The Transaction Details UI does not display this information.

{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "transactions": [
            {
                "invoice_id": "2869053b-ca70-4380-9aea-38ba66515690",
                "wallet_id": "6e4dc9f9-b3d7-4752-866e-367d9c67b56b",
                "date": "2023-12-08T21:45:53.932539Z",
                "balance_after": 10302750,
                "amount": -200000,
                "currency": "TIL",
                "amount_usd": -2000,
                "balance_after_usd": 103027.5,
                "transaction_status": "processed",
                "transaction_id": "2869053b-ca70-4380-9aea-38ba66515690",
                "transaction_type": "user_purchase",
                "transaction_subtype": ""
            }
        ],
        "total": 1
    }
}

View transaction details

This exercise demonstrates two different ways to view the details of a specific transaction or invoice:

• Transaction detail UI widget (shown below)
• Transaction detail API

Transaction details of a purchase made by the payer.

Transaction details of a sale made by the recipient.

Get transaction details (UI)

The tasks in this exercise display information about specific transactions. The requests are found in the Explore Tilia transactions collection, in the Transaction details folder.

After a user-to-user invoice is paid, the transaction appears in both the payer's and the recipient's transaction history. The details about a single transaction can be retrieved by using the UI widget or the API.

The following procedure describes how to display only the details of a specific transaction without viewing the user's transaction history.

To display the details of a specific transaction, use the Tilia UI Sandbox.

Before you start, make sure you have:

• Your Tilia developer credentials.
• The user's account ID from the environment variables.
• The invoice ID of the transaction.

To display a specific transaction in the UI widget:

1. Open a browser window with the Tilia UI Sandbox and continue in the UI Sandbox.
2. Enter your Tilia developer credentials, if necessary. They should be retained if you've entered them recently.
3. Enter the user's account ID.
4. Choose the TRANSACTION DETAILS option, and then select the "W" icon.
5. In the Widget space, in the TRANSACTION ID field, enter the transaction or invoice ID. Be careful not to include any additional white space or other extra characters in this field.
6. Choose UPDATE to refresh the widget.
7. After you review transaction details in the widget, close the widget.

Repeat these steps with another user's account ID and transaction ID to review the details of another transaction.

For information about how to integrate this widget into your application, visit Transaction Details.

Get transaction details (API)

This exercise demonstrates how to recall the details of a transaction by using the Tilia API. The method for recalling transaction details depends on whether the transaction was a normal transaction or an escrow transaction. This exercise contains examples of each method.

The examples in the Explore Tilia transactions collection from the shared Postman workspace recall the transaction ID from the most recent transaction.

To use the Tilia API to get the details of the most recent standard transaction:

1. In the Explore Tilia transactions collection, in the Transaction details folder, open the Get transaction details request.
2. In the URL field, notice that the invoice_id field of the URL uses invoice ID of the most recent normal transaction from the environment variables.
3. In the request, choose Send .
4. After the response returns, open the response Body tab below the request to review the response body details.

{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "invoice_id": "5eec237c-9298-4dc7-8a88-adfeb48fb0e0",
        "account_id": "acct_2bJm9BOjrgzkiFRi85KYbKBhBdm",
        "invoice_type": "user_purchase_virtual",
        "reference_type": "",
        "reference_id": "",
        "state": "SUCCESS",
        "description": "Digital product order",
        "metadata": {},
        "summary": {
            "total_amount": 20000,
            "total_amount_usd": 200,
            "currency": "TIL",
            "display_amount": "TIL20000",
            "subtotal": {
                "total_amount": 20000,
                "total_amount_usd": 200,
                "currency": "TIL",
                "display_amount": "TIL20000"
            },
            "tax": {
                "total_amount": 0,
                "total_amount_usd": 0,
                "currency": "",
                "display_amount": ""
            },
            "payment_breakdown": [],
            "tax_calculation": "",
            "is_tax_exempt": false
        },
        "failure_code": "",
        "failure_reason": "",
        "created": "2024-01-24T23:36:56Z",
        "updated": "2024-01-24T23:36:57Z",
        "payment_methods": {
            "b75f1879-297d-4812-8973-23929184cc82": {
                "provider": "wallet",
                "payment_method_id": "b75f1879-297d-4812-8973-23929184cc82",
                "authorized_amount": 20000,
                "currency": "TIL",
                "display_string": "",
                "display_amount": "TIL20000",
                "tags": {},
                "subitems": {
                    "02848718-e9ff-41e0-90e5-acf790faa334": {
                        "subitem_id": "02848718-e9ff-41e0-90e5-acf790faa334",
                        "amount": 20000,
                        "currency": "TIL",
                        "display_amount": "TIL20000",
                        "reference_type": "payments.payment.id",
                        "reference_id": "271865ed-a506-4afa-ba5a-7886213f588e",
                        "subitem_type": "standard_virtual_payment",
                        "description": "",
                        "metadata": {
                            "pm_display_string": "Standard TIL Ledger"
                        },
                        "source_account_id": "acct_2bJm9BOjrgzkiFRi85KYbKBhBdm",
                        "source_payment_method_id": "b75f1879-297d-4812-8973-23929184cc82",
                        "source_wallet_id": "a6166373-494b-4ad4-a0e2-3eb1ee968e5e",
                        "destination_account_id": "75452177-cad5-42bd-8530-4fb86ecc6fa9",
                        "destination_payment_method_id": "",
                        "destination_wallet_id": "87a494bc-f648-4dcd-b0fc-e59106e0598f",
                        "tags": {}
                    }
                }
            }
        },
        "line_items": {
            "45b89587-b1aa-4c93-be0f-3b9c4fcc97c2": {
                "line_item_id": "45b89587-b1aa-4c93-be0f-3b9c4fcc97c2",
                "product_sku": "",
                "product_code": "",
                "amount": 20000,
                "currency": "TIL",
                "display_amount": "TIL20000",
                "reference_type": "",
                "reference_id": "",
                "transaction_type": "user_to_user_virtual",
                "description": "In-game digital bundle",
                "metadata": null,
                "tags": {},
                "sort_order": 0,
                "subitems": {
                    "01fd3d01-9200-4249-8aea-cc22d4fb1e05": {
                        "subitem_id": "01fd3d01-9200-4249-8aea-cc22d4fb1e05",
                        "amount": 2000,
                        "currency": "TIL",
                        "display_amount": "TIL2000",
                        "reference_type": "invoicing.invoice_line_item_v2.line_item_id",
                        "reference_id": "45b89587-b1aa-4c93-be0f-3b9c4fcc97c2",
                        "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_2bJm9EMqDaqdcFE5dzd0Jps0tRw",
                        "destination_payment_method_id": "",
                        "destination_wallet_id": "f2805af0-1713-42fe-b241-4a25d155b4cf",
                        "tags": {}
                    },
                    "262908b4-0d39-4ae1-8afe-c11519a87778": {
                        "subitem_id": "262908b4-0d39-4ae1-8afe-c11519a87778",
                        "amount": 18000,
                        "currency": "TIL",
                        "display_amount": "TIL18000",
                        "reference_type": "invoicing.invoice_line_item_v2.line_item_id",
                        "reference_id": "45b89587-b1aa-4c93-be0f-3b9c4fcc97c2",
                        "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_2bJm9FHNNfjZ9BFR0qkcOGSltX3",
                        "destination_payment_method_id": "",
                        "destination_wallet_id": "ee862876-e5ac-412b-8e7d-6e86e496182e",
                        "tags": {}
                    }
                }
            }
        },
        "subitems": {},
        "tags": {}
    }
}

To use the Tilia API to get the details of the most recent escrow transaction:

1. In the Explore Tilia transactions collection, in the Transaction details folder, open the Get escrow transaction details request.
2. In the URL field, notice that the invoice_id field of the URL uses the escrow invoice ID of the most recent escrow transaction from the environment variables.
3. In the request, choose Send .
4. After the response returns, open the response Body tab below the request to review the response body details.

A typical response body with escrow transaction details looks like the following.

{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "id": "esc_2bQFVIL962R0vkUsxiZrAmB8nvZ",
        "account_id": "acct_2bJm9BOjrgzkiFRi85KYbKBhBdm",
        "escrow_invoice_id": "b55ec1c1-e291-49cb-a0b6-8961100d4548",
        "commit_invoice_id": "4c3adfbc-3b36-44dc-955a-d9d039b1badc",
        "cancel_invoice_id": "",
        "status": "COMMITTED",
        "integrator": "tilia-test",
        "created": "2024-01-24T23:36:57Z",
        "updated": "2024-01-24T23:37:03Z"
    }
}

Notice these invoice IDs in the response:

• escrow_invoice_id
• commit_invoice_id
• cancel_invoice_id

Those invoice IDs, where present, identify the complete invoices that describe each of the stages of the escrow transaction. These invoices can be recalled by using the normal transaction detail procedure described earlier.

Next steps

After you review the invoices, you can review the wallet balances from the _Manage user accounts collection and the requests in the View wallet balances folder.

You can also return to the Transaction tutorials overview and find another transaction tutorial.