Tutorial: Make NFT purchase transactions

In this tutorial, you create a transaction in your application for a user to purchase an NFT (non-fungible token) from the publisher.

Allow about 10 minutes to complete this tutorial.

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. 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, and then open the Buy NFT from publisher with escrow folder.
   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 the escrow transaction

The request starts after the necessary information about the payer has been collected. That information can be added to the product information to create the invoice .

Creating an invoice starts with collecting the required information, and then sending it to Tilia to create the complete invoice. The data is assembled into the following object to send in the request body.

An escrow invoice needs the following information:

• A summary description of the invoice
• The product information
• payer's account_id : from the paying user's account information
• payer's payment method: the payment_method_id of the payment method the payer is using for this transaction (shown in the example as payers_pm_id )

This request body shows how this information is collected to create the escrow invoice and start the transaction.

{
    "account_id": "{{payers_account_id}}",
    "payment_methods": [
        {
            "payment_method_id":  "{{payers_pm_id}}"
        }
    ],
    "description": "NFT product order",
    "line_items": [
      {
        "amount": 1500,
        "currency": "USD",
        "transaction_type": "user_to_integrator",
        "description": "Crazy cactus NFT"
      }
    ]
}

To create the escrow transaction for an NFT, in Postman:

1. In the Explore Tilia transactions collection, in the Buy NFT from publisher with escrow folder, open the Create USD escrow transaction request.
2. Choose the request Body tab to see the request body with the transaction information.
3. In the Create USD escrow transaction request, choose Send to create the escrow invoice.

When the response returns, the response body contains the escrow invoice.

{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "id": "esc_2c05IhpbqMSl2UgUEl6AQFQUtBg",
        "account_id": "acct_2bJm9BOjrgzkiFRi85KYbKBhBdm",
        "escrow_invoice_id": "0c3c16cc-bb45-401c-902d-0d1b32d92be5",
        "commit_invoice_id": "",
        "cancel_invoice_id": "",
        "status": "OPEN",
        "integrator": "tilia-test",
        "created": "2024-02-06T16:06:17Z",
        "updated": "2024-02-06T16:06:17Z",
        "escrow_invoice": {
            "invoice_id": "0c3c16cc-bb45-401c-902d-0d1b32d92be5",
            "summary": {
                "total_amount": 1500,
                "total_amount_usd": 1500,
                "currency": "USD",
                "display_amount": "USD 15.00",
                "subtotal": {
                    "total_amount": 1500,
                    "total_amount_usd": 1500,
                    "currency": "USD",
                    "display_amount": "USD 15.00"
                },
                "tax": {
                    "total_amount": 0,
                    "total_amount_usd": 0,
                    "currency": "USD",
                    "display_amount": "USD 0.00"
                },
                "payment_breakdown": [
                    {
                        "total_amount": 1500,
                        "currency": "USD",
                        "display_amount": "USD 15.00",
                        "display_string": "MasterCard ending in 4444"
                    }
                ],
                "tax_calculation": "",
                "is_tax_exempt": false
            }
        }
    }
}

After creating the transaction, the payload.status value is OPEN. 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 an escrow transaction.

Pay escrow transaction

The preceding task only created an invoice in Tilila's e-commerce system. No funds have changed accounts, yet. This task finishes the purchase process, collects the funds from the payer, and holds them in escrow.

To pay the escrow transaction, in Postman:

1. In the Explore Tilia transactions collection, in the Buy NFT from publisher with escrow folder, open the Pay escrow transaction request.
2. In the URL field, notice that the invoice_id returned by the preceding request is used to identify the invoice to pay.
3. In the Pay escrow transaction 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": {
        "id": "esc_2c05IhpbqMSl2UgUEl6AQFQUtBg",
        "account_id": "acct_2bJm9BOjrgzkiFRi85KYbKBhBdm",
        "escrow_invoice_id": "0c3c16cc-bb45-401c-902d-0d1b32d92be5",
        "commit_invoice_id": "",
        "cancel_invoice_id": "",
        "status": "ESCROWED",
        "integrator": "tilia-test",
        "created": "2024-02-06T16:06:17Z",
        "updated": "2024-02-06T16:06:17Z",
        "escrow_invoice": {
            "invoice_id": "0c3c16cc-bb45-401c-902d-0d1b32d92be5",
            "summary": {
                "total_amount": 1500,
                "total_amount_usd": 1500,
                "currency": "USD",
                "display_amount": "USD 15.00",
                "subtotal": {
                    "total_amount": 1500,
                    "total_amount_usd": 1500,
                    "currency": "USD",
                    "display_amount": "USD 15.00"
                },
                "tax": {
                    "total_amount": 0,
                    "total_amount_usd": 0,
                    "currency": "USD",
                    "display_amount": "USD 0.00"
                },
                "payment_breakdown": [
                    {
                        "total_amount": 1500,
                        "currency": "USD",
                        "display_amount": "USD 15.00",
                        "display_string": "MasterCard ending in 4444"
                    }
                ],
                "tax_calculation": "",
                "is_tax_exempt": false
            }
        }
    }
}

The invoice returned in the response buffer shows the current state of the invoice in the value of payload.status, which is now ESCROWED.

Commit escrow transaction

The preceding task collected payment from the payer to hold them in escrow. After ownership of the NFT has been transferred to the payer, this request completes the purchase process and transfers the payment to the publisher.

To commit the escrow transaction, in Postman:

1. In the Explore Tilia transactions collection, in the Buy NFT from publisher with escrow folder, open the Commit escrow transaction request.
2. In the URL field, notice that the invoice_id returned by the create request is used to identify the invoice to commit.
3. In the Commit escrow transaction 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 looks like the following.

{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "id": "esc_2c05IhpbqMSl2UgUEl6AQFQUtBg",
        "account_id": "acct_2bJm9BOjrgzkiFRi85KYbKBhBdm",
        "escrow_invoice_id": "0c3c16cc-bb45-401c-902d-0d1b32d92be5",
        "commit_invoice_id": "6c4ff611-9de7-42bf-b042-d1ac902aaf82",
        "cancel_invoice_id": "",
        "status": "COMMITTED",
        "integrator": "tilia-test",
        "created": "2024-02-06T16:06:17Z",
        "updated": "2024-02-06T16:18:22Z"
    }
}

The payload.status value is now COMMITTED showing that the payer has paid the invoice identified in the response buffer and the recipient has received the payment.

Next steps

The exercises in this tutorial used Postman to call the Tilia APIs. For a similar example of how to integrate the escrow transaction demonstrated in this tutorial into a web page, see Escrow transaction.

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.