Tutorial: Make standard transactions with royalties

In this tutorial, you demonstrate the interactions that support paying the creators of digital goods a royalty or a commission for purchases made in your marketplace.

Allow about 10 minutes to complete this tutorial.

Diagram of roayalty use case interactions

To pay creators a royalty or to pay a vendor a commission on a sale, you divide the line-item values between the creator or vendor and the seller (recipient) when you create the transaction's invoice.

Note

While this tutorial demonstrates a transaction that has only two recipients: the recipient and the creator, Tila transactions can have more recipients. For example, a recipient, and several creators; a recipient, a vendor, and several creators, and so on.

The exercises in this tutorial start after the user selects items in the application. The application then retrieves the account and wallet information about the recipients and the creators who receive the royalties. An application might get these details from a catalog listing, for example. The payer's account and wallet information is also retrieved from the system to combine with the other information 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 : for both users to receive the tokens from the sale: the recipient's wallet and the creator's wallet.

In an actual implementation, the application provides this information, so it's simulated in this tutorial. The product information is part of the demonstration and the users are identified by their usernames.

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

In this exercise, the invoice and line-item data is assembled into the following object to send in the request body.

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.
For each of the recipient and the creator:
- destination_account_id : the recipient or creator'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 or creator'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": 20000,
        "currency": "TIL",
        "transaction_type": "user_to_user",
        "description": "In-game digital bundle",
        "recipients": [
          {
            "amount": 18000,
            "currency": "TIL",
            "source_wallet_id": "{{payers_wallet_id}}",
            "destination_wallet_id": "{{recipients_wallet_id}}"
          },
          {
            "amount": 2000,
            "currency": "TIL",
            "source_wallet_id": "{{payers_wallet_id}}",
            "destination_wallet_id": "{{creators_wallet_id}}"
          }
        ]
      }
    ]
}

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

In the Explore Tilia transactions collection, in the Transaction with royalties 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.

Show a typical response body with the transaction info.

Copy

Copied

{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "invoice_id": "107ea48f-ef24-4b51-a954-dfc4ad6677cd",
        "account_id": "acct_2b5iunvHmd2OjEci7xFzDUGHOKF",
        "invoice_type": "user_purchase_virtual",
        "reference_type": "",
        "reference_id": "",
        "state": "OPEN",
        "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": "TIL",
                "display_amount": "TIL 0.00"
            },
            "payment_breakdown": [],
            "tax_calculation": "",
            "is_tax_exempt": false
        },
        "failure_code": "",
        "failure_reason": "",
        "created": "0001-01-01T00:00:00Z",
        "updated": "0001-01-01T00:00:00Z",
        "payment_methods": {
            "f9c7cf00-1301-4bea-ab34-980633992145": {
                "provider": "wallet",
                "payment_method_id": "f9c7cf00-1301-4bea-ab34-980633992145",
                "authorized_amount": 20000,
                "currency": "TIL",
                "display_string": "Standard TIL Ledger",
                "display_amount": "TIL20000",
                "tags": {
                    "standard": {
                        "tag_id": "",
                        "tag": ""
                    }
                },
                "subitems": {
                    "49877cd8-caa0-4a8a-b058-9061e4382410": {
                        "subitem_id": "49877cd8-caa0-4a8a-b058-9061e4382410",
                        "amount": 0,
                        "currency": "TIL",
                        "display_amount": "TIL0",
                        "reference_type": "",
                        "reference_id": "",
                        "subitem_type": "standard_virtual_payment",
                        "description": "",
                        "metadata": {
                            "pm_display_string": "Standard TIL Ledger"
                        },
                        "source_account_id": "acct_2b5iunvHmd2OjEci7xFzDUGHOKF",
                        "source_payment_method_id": "f9c7cf00-1301-4bea-ab34-980633992145",
                        "source_wallet_id": "7a2b65bf-cbcc-4157-a83c-3ecd2a6629c9",
                        "destination_account_id": "75452177-cad5-42bd-8530-4fb86ecc6fa9",
                        "destination_payment_method_id": "",
                        "destination_wallet_id": "87a494bc-f648-4dcd-b0fc-e59106e0598f",
                        "tags": null
                    }
                }
            }
        },
        "line_items": {
            "3092d703-bb42-4720-81ef-ddb6e0811945": {
                "line_item_id": "3092d703-bb42-4720-81ef-ddb6e0811945",
                "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": null,
                "sort_order": 0,
                "subitems": {
                    "cbf37961-043e-4814-b0cb-92cd5c7fd6c7": {
                        "subitem_id": "cbf37961-043e-4814-b0cb-92cd5c7fd6c7",
                        "amount": 2000,
                        "currency": "TIL",
                        "display_amount": "TIL2000",
                        "reference_type": "invoicing.invoice_line_item_v2.line_item_id",
                        "reference_id": "3092d703-bb42-4720-81ef-ddb6e0811945",
                        "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_2b5iv4wMRe6BrhMjM00SQYR70lh",
                        "destination_payment_method_id": "",
                        "destination_wallet_id": "45ae2ff6-8803-4f15-9cfa-135ba4a06dee",
                        "tags": null
                    },
                    "d571d9f3-4bc2-4913-a8ad-28e71219672d": {
                        "subitem_id": "d571d9f3-4bc2-4913-a8ad-28e71219672d",
                        "amount": 18000,
                        "currency": "TIL",
                        "display_amount": "TIL18000",
                        "reference_type": "invoicing.invoice_line_item_v2.line_item_id",
                        "reference_id": "3092d703-bb42-4720-81ef-ddb6e0811945",
                        "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_2b5iuyTGOvKOnu0q9SzlaKlco2G",
                        "destination_payment_method_id": "",
                        "destination_wallet_id": "f885a836-e9cf-409f-b24c-9318d12ca596",
                        "tags": null
                    }
                }
            }
        },
        "subitems": {},
        "tags": null
    }
}

The payload.state property, which has a value of OPEN, indicates the status of the transaction.

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

In this exercise, you pay the invoice created in the previous exercise.

The preceding exercise only creates an invoice in Tilila's system. No tokens have moved, yet. This task moves the payer's tokens to the wallets of the recipient and creator as the invoice describes.

To pay the invoice, in Postman:

In the Explore Tilia transactions collection, in the Transaction with royalties 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 payment info.

Copy

Copied

{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "invoice_id": "107ea48f-ef24-4b51-a954-dfc4ad6677cd",
        "account_id": "acct_2b5iunvHmd2OjEci7xFzDUGHOKF",
        "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": "TIL",
                "display_amount": "TIL 0.00"
            },
            "payment_breakdown": [],
            "tax_calculation": "",
            "is_tax_exempt": false
        },
        "failure_code": "",
        "failure_reason": "",
        "created": "2024-01-19T18:55:18Z",
        "updated": "2024-01-19T18:55:18Z",
        "payment_methods": {
            "f9c7cf00-1301-4bea-ab34-980633992145": {
                "provider": "wallet",
                "payment_method_id": "f9c7cf00-1301-4bea-ab34-980633992145",
                "authorized_amount": 20000,
                "currency": "TIL",
                "display_string": "",
                "display_amount": "TIL20000",
                "tags": null,
                "subitems": {
                    "49877cd8-caa0-4a8a-b058-9061e4382410": {
                        "subitem_id": "49877cd8-caa0-4a8a-b058-9061e4382410",
                        "amount": 20000,
                        "currency": "TIL",
                        "display_amount": "TIL20000",
                        "reference_type": "payments.payment.id",
                        "reference_id": "755f3307-0be7-4f06-a43e-7bd472d6b091",
                        "subitem_type": "standard_virtual_payment",
                        "description": "",
                        "metadata": {
                            "pm_display_string": "Standard TIL Ledger"
                        },
                        "source_account_id": "acct_2b5iunvHmd2OjEci7xFzDUGHOKF",
                        "source_payment_method_id": "f9c7cf00-1301-4bea-ab34-980633992145",
                        "source_wallet_id": "7a2b65bf-cbcc-4157-a83c-3ecd2a6629c9",
                        "destination_account_id": "75452177-cad5-42bd-8530-4fb86ecc6fa9",
                        "destination_payment_method_id": "",
                        "destination_wallet_id": "87a494bc-f648-4dcd-b0fc-e59106e0598f",
                        "tags": null
                    }
                }
            }
        },
        "line_items": {
            "3092d703-bb42-4720-81ef-ddb6e0811945": {
                "line_item_id": "3092d703-bb42-4720-81ef-ddb6e0811945",
                "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": null,
                "sort_order": 0,
                "subitems": {
                    "cbf37961-043e-4814-b0cb-92cd5c7fd6c7": {
                        "subitem_id": "cbf37961-043e-4814-b0cb-92cd5c7fd6c7",
                        "amount": 2000,
                        "currency": "TIL",
                        "display_amount": "TIL2000",
                        "reference_type": "invoicing.invoice_line_item_v2.line_item_id",
                        "reference_id": "3092d703-bb42-4720-81ef-ddb6e0811945",
                        "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_2b5iv4wMRe6BrhMjM00SQYR70lh",
                        "destination_payment_method_id": "",
                        "destination_wallet_id": "45ae2ff6-8803-4f15-9cfa-135ba4a06dee",
                        "tags": null
                    },
                    "d571d9f3-4bc2-4913-a8ad-28e71219672d": {
                        "subitem_id": "d571d9f3-4bc2-4913-a8ad-28e71219672d",
                        "amount": 18000,
                        "currency": "TIL",
                        "display_amount": "TIL18000",
                        "reference_type": "invoicing.invoice_line_item_v2.line_item_id",
                        "reference_id": "3092d703-bb42-4720-81ef-ddb6e0811945",
                        "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_2b5iuyTGOvKOnu0q9SzlaKlco2G",
                        "destination_payment_method_id": "",
                        "destination_wallet_id": "f885a836-e9cf-409f-b24c-9318d12ca596",
                        "tags": null
                    }
                }
            }
        },
        "subitems": {},
        "tags": null
    }
}

The invoice returned in the response buffer shows the invoice as paid 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 Multi-Seller 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.