Use-case tutorial: Patronage

In this tutorial, you learn how to support patronage in your application. Patronage is where users pay to access items or content created by other users. Tilia services support these interactions in your application.

The processes to support patronage are very similar to those that support a marketplace. For example:

• You can create patronage transactions that support more than one creator by creating transactions with multiple recipients. These transactions are very similar to those used in paying royalties to creators ; however these invoices have more creators. Patronage to multiple creators demonstrates how this is done.
• You can create patronage transactions with delayed payment to the creators by having the patron pay the publisher and then, when it's time, the publisher pays the creators by using a balance transfer . Patronage with publisher holding the funds temporarily describes how this can be done.

API operations in this tutorial

To complete this tutorial

This tutorial builds on the Marketplace tutorial.

To complete this exercise, first complete the Marketplace tutorial, and then return to this tutorial to experiment with the different invoices.

Patronage to multiple creators

Granting access to items or content from other users of the application in this model is very similar to processing standard transactions.

This image shows the transaction processing of such a transaction.

The ability of Tilia's user-to-user transactions to support multiple recipients makes creating such transactions very straightforward.

The Make standard transactions with royalties tutorial demonstrates a transaction with multiple recipients as the following code example shows.

To create the 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.
• For each recipient:
  • 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.

{
  "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}}"
        }
      ]
    }
  ]
}

Such a transaction can be adapted to support more creators in a patronage scenario as this example shows.

{
  "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": 5000,
          "currency": "TIL",
          "source_wallet_id": "{{payers_wallet_id}}",
          "destination_wallet_id": "{{creator_1_wallet_id}}"
        },
        {
          "amount": 5000,
          "currency": "TIL",
          "source_wallet_id": "{{payers_wallet_id}}",
          "destination_wallet_id": "{{creator_2_wallet_id}}"
        },
        {
          "amount": 5000,
          "currency": "TIL",
          "source_wallet_id": "{{payers_wallet_id}}",
          "destination_wallet_id": "{{creator_3_wallet_id}}"
        },
        {
          "amount": 5000,
          "currency": "TIL",
          "source_wallet_id": "{{payers_wallet_id}}",
          "destination_wallet_id": "{{creator_4_wallet_id}}"
        }
      ]
    }
  ]
}

In this type of transaction, the creators receive the proceeds of the transaction immediately.

The next section describes how to support similar transactions while introducing a delay between the purchase and the payment to the creators.

Patronage with publisher holding the funds temporarily

This method of supporting patronage transactions with a delay between the purchase and payment to creators splits the process into two transactions.

Unlike the previous example, payment is made to the publisher first, instead of directly to the creators. The publisher then pays the creators by using balance transfers from the publisher to the creators as the Rewards use case illustrates.

This image shows the transaction processing with purchase and the payment to the creators split into a separate processes.

With this type of patronage transaction, the purchase is a user-to-integrator transaction, as this example describes.

{
  "account_id": "{{payers_account_id}}",
  "is_escrow": false,
  "invoice_mechanism": "tilia_hosted",
  "reference_type": "authorize_purchase_demo",
  "reference_id": "authorize_demo: {{$timestamp}}",
  "line_items": [
    {
      "description": "Digital product order",
      "transaction_type": "user_to_integrator",
      "currency": "TIL",
      "amount": 20000
    }
  ]
}

In this transaction, the user (payer) pays the publisher directly, as the transaction using the Checkout UI tutorial demonstrates

When it's time to pay the creators, the publisher issues a balance transfer to each of the creators.

This is an example of a balance transfer request body that would be sent to each creator.

{
    "destination_wallet_id": "{{creator_x_wallet_id}}",
    "amount": 5000,
    "currency": "TIL",
    "reason": "Creator's patronage payment for Digital product sale"
}

We can help you design custom wallets to help facilitate this type of transaction. Contact us for more information.

Conclusion

The examples in this tutorial take place in a marketplace context and describe two different ways to implement patronage in your application.

You might also consider these other options for sharing and splitting income from transactions:

• Royalties
• Commissions
• Patronage