Nothing Found

User-to-User Purchase

A typical purchase transaction consists of collecting payment information, creating an invoice, and submitting the invoice for processing. This example explains how to create a transaction for a purchase between two Tilia users.

Prerequisites

To complete this example, you'll need the following:

  • An Access Token with the requisite scopes: read_payment_methods, write_user_tokens and write_invoices
  • An account ID for the buyer. Refer to Registering Users for information on creating user accounts.
  • An account ID for the seller.
  • A web page containing the Tilia widget script. Refer to Widget Integration for instructions on setting this up.
  • A payment method. Refer to Test Payments for payment methods you can use in testing.

The process of creating a transaction involves the following steps:

Step 1: Retrieve seller wallet details

Step 2: Create a secure redirect URL for the buyer

Step 3: Call the purchase flow to obtain payment details

Step 4: Set up the purchase transaction

Step 5: POST the invoice for processing

Step 6: Handle the completion event

Step 1: Retrieve seller wallet details

Sellers receive payments in their Tilia wallets. Each wallet has a unique ID that can be used in building transactions. To retrieve the seller's wallet ID, submit a GET request with the seller's' account_id to the /payment_methods endpoint.

curl --location --request GET https://payments.tilia-inc.com/v1/{account_id}/payment_methods \
--header 'Authorization: Bearer <Access_Token>' \
--header 'Content-Type: application/json' \

This returns all of the payment methods associated with the seller's account, including purchase-only payment methods such as credit cards. To locate the wallet, look for the payment method in which provider has a value of wallet, and the currency matches that of the transaction you are creating.

In this example, we are creating a USD transaction, so will be using the seller's USD wallet.

Copy
Copied
{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": [
        {
			"id": "fce464b4-cf9f-49c2-bdb1-2db3275d6284",
			"account_id": "7f938c50-0225-4fbe-b465-81d70934064a",
			"method_class": "registration",
			"display_string": "USD Wallet",
			"provider": "wallet",
			"psp_reference": "a900281d-5d01-4784-a412-f447389929f8",
			"psp_hash_code": "",
			"processing_currency": "USD",
			"pm_state": "ACTIVE",
			"integrator": "acme",
			"created": "2020-08-14 10:59:59",
			"updated": "2020-08-14 10:59:59",
			"wallet_balance": "2457",
			"payment_method_id": "",
			"provider_data": {
				"wallet_id": "a900281d-5d01-4784-a412-f447389929f8",
				"wallet_balance": "2457"
			}
		}
	]
}

The wallet_id is used in setting up the purchase transaction in step 4.

Step 2: Create a secure redirect URL

To complete a purchase, you'll need to obtain the buyer's payment information. To start, you'll pass the buyer's account ID to create a redirect URL. This URL creates a secure user session, forming the basis for calling the Tilia Purchase flow.

curl --location --request POST https://auth.tilia-inc.com/authorize/user \
--header 'Authorization: Bearer <Access_Token>' \
--header 'Content-Type: application/json' \

Request Body

{
  "account_id": "string"
}

Sample response

{
  "status": "Success",
  "message": [],
  "codes": [],
  "payload": {
    "redirect": "https://web.tilia-inc.com/ui/appauth/19a4a2b0-364c-4cad-a895-14c57bcd4e7c"
  }
}

Step 3: Call the purchase flow to obtain payment details

The Purchase flow is a web UI that allows the purchasing user to choose a payment method. If the user does not have a stored payment method, they will be able to add one. Upon completion of the flow, an ID for the user's payment method is passed back to you for use in creating the transaction.

Users must have a signed copy of the most recent Tilia Terms of Service (TOS) on file. If the user has not accepted the TOS, or if there is an updated version available, they are presented with a TOS screen which must be accepted before they can select a payment method.

From the widget page, call the following JavaScript to execute the purchase flow.

window.Tilia.execute({
	rootId: <your.element.id>,
	flow: purchase,
	redirect: https://web.tilia-inc.com/ui/appauth/ed8ff1e9-9256-4205-918a-b9ca23ec00ec,
	onComplete: handleComplete,
});

The widget invokes the handleComplete callback with the result of the flow.

If the user cancels anywhere in the flow:

{
	source: “tilia”,
	event: “tilia.pm.complete”,
	state: “cancel”,
}

If the user completes the flow:

{
	source: “tilia”,
	event: “tilia.pm.complete”,
	id: <payment.method.id>,
	psp_reference: <psp.reference>,
	pm_state: <payment.method.state>
}

The value for id is the payment_method_id used in the next step.

Step 4: Set up the purchase transaction

Once you have the user's payment_method_id, you are ready to set up your purchase transaction, in the form of an invoice. Tilia uses the concept of invoices to describe the detailed information required in order to process a transaction.

For a user-to-user purchase, the value for transaction_type must be user_to_user.

For this transaction type, you need to provide the following values:

  • account_id - the buyer's account ID
  • payment_method_id - the buyer's payment method id returned by the payment flow
  • currency - the currency for the purchase.
  • amount - the amount of the purchase
  • source_wallet_id - your integrator wallet to be used in processing the transfer of funds. Leave this value blank to use the default (appropriate in most cases).
  • destination_wallet_id - the seller's wallet ID (retrieved in step 1).

Additionally, you will want to provide details about the item(s) being purchased, including the seller's product description, SKU, and other transaction information.

The following example is for a simple invoice with a single item. More complex invoices, including multi-seller invoices, can be built using various properties found in our invoicing API. Refer to the API reference for details.

attention

This example is in USD. Therefore, all amounts are in cents. Refer to Working with Currencies for information on how currencies are used.

The example below requires an API token with the scope write_invoices.

curl --location --request POST https://invoicing.tilia-inc.com/v2/invoice \
--header 'Authorization: Bearer <Access_Token>' \
--header 'Content-Type: application/json' \

Request Body

Copy
Copied
{
  "account_id": "<buyer_account_id>",
  "reference_type": "product_purchase_id",
  "reference_id": "purchase_id123",
  "description": "A description of the product",
	"payment_methods": [
		{"payment_method_id": "<id_from_payment_flow>"}
	],
  "line_items": [
    {
      "amount": 500,
      "currency": "USD",
      "transaction_type": "user_to_user",
      "product_sku": "12345",
	  "reference_type": "seller_listing_id",
	  "reference_id": "listing123",
      "recipients": [
        {
          "amount": 500,
		  "currency": "USD",
          "source_wallet_id": "<your_merchant_wallet_id>",
          "destination_wallet_id": "<seller_wallet_id>"
        }
      ]
    }
  ]
}

Sample response

A successful request returns the HTTP 201 Created status code along with a JSON response body containing the invoice details. You will use the invoice_id field value in the next step.

View Response
Copy
Copied
{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "invoice_id": "7f31235d-93da-4f1f-80dd-8db34cc1cc6e",
        "account_id": "793fab8e-6da5-4b26-b7f9-aab9cf809f91",
        "reference_type": "product_purchase_id",
        "reference_id": "purchase_id123",
        "state": "open",
        "description": "A description of the product",
        "metadata": null,
        "summary": {
            "total_amount": 500,
            "currency": "USD",
            "display_amount": "USD 5.00"
        },
        "created": "2020-05-11T15:54:12Z",
        "updated": "2020-05-11T15:54:12Z",
        "payment_methods": {},
        "line_items": {
            "ac43aed7-b2ae-4e76-990d-25aea6832489": {
                "line_item_id": "ac43aed7-b2ae-4e76-990d-25aea6832489",
                "product_sku": "12345",
                "amount": 500,
                "currency": "USD",
                "display_amount": "USD 5.00",
                "reference_type": "seller_listing_id",
                "reference_id": "listing123",
                "transaction_type": "user_to_user",
                "description": "",
                "metadata": null,
                "subitems": {
                    "6ba69fcb-0793-4798-9466-34e189445d8f": {
                        "subitem_id": "6ba69fcb-0793-4798-9466-34e189445d8f",
                        "amount": 500,
                        "currency": "USD",
                        "display_amount": "USD 5.00",
                        "reference_type": "invoicing.invoice_line_item_v2.line_item_id",
                        "reference_id": "ac43aed7-b2ae-4e76-990d-25aea6832489",
                        "subitem_type": "user_recipient",
                        "description": "",
                        "metadata": null,
                        "source_account_id": "793fab8e-6da5-4b26-b7f9-aab9cf809f91",
                        "source_payment_method_id": "950606a3-3b89-4589-9b53-f7d39a5f96ce",
                        "source_wallet_id": "26ac23a6-7457-48f4-9e97-faee2ce37664",
                        "destination_account_id": "7f938c50-0225-4fbe-b465-81d70934064a",
                        "destination_payment_method_id": "fce464b4-cf9f-49c2-bdb1-2db3275d6284",
                        "destination_wallet_id": "a900281d-5d01-4784-a412-f447389929f8"
                    }
                }
            }
        },
        "subitems": {
            "6ba69fcb-0793-4798-9466-34e189445d8f": {
                "subitem_id": "6ba69fcb-0793-4798-9466-34e189445d8f",
                "amount": 500,
                "currency": "USD",
                "display_amount": "USD 5.00",
                "reference_type": "invoicing.invoice_line_item_v2.line_item_id",
                "reference_id": "ac43aed7-b2ae-4e76-990d-25aea6832489",
                "subitem_type": "user_recipient",
                "description": "",
                "metadata": null,
                "source_account_id": "793fab8e-6da5-4b26-b7f9-aab9cf809f91",
                "source_payment_method_id": "950606a3-3b89-4589-9b53-f7d39a5f96ce",
                "source_wallet_id": "26ac23a6-7457-48f4-9e97-faee2ce37664",
                "destination_account_id": "7f938c50-0225-4fbe-b465-81d70934064a",
                "destination_payment_method_id": "fce464b4-cf9f-49c2-bdb1-2db3275d6284",
                "destination_wallet_id": "a900281d-5d01-4784-a412-f447389929f8"
            }
        }
    }
}

Step 5: Post the invoice for processing

In the previous step, we created the invoice. Next, it needs to be submitted for processing and payment. To submit the invoice for processing, POST the invoice_id to the /pay endpoint. 

curl --location --request POST https://invoicing.tilia-inc.com/v2/invoice/{invoice_id}/pay \
--header 'Authorization: Bearer <Access_Token>' \
--header 'Content-Type: application/json' \

Sample response

A successful request returns the HTTP 200 OK status code along with a JSON response body containing the invoice details. Note that the value for state has updated from open to processing.

View Response
Copy
Copied
{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "invoice_id": "7f31235d-93da-4f1f-80dd-8db34cc1cc6e",
        "account_id": "793fab8e-6da5-4b26-b7f9-aab9cf809f91",
        "reference_type": "product_purchase_id",
        "reference_id": "purchase_id123",
        "state": "processing",
        "description": "A description of the product",
        "metadata": null,
        "summary": {
            "total_amount": 500,
            "currency": "USD",
            "display_amount": "USD 5.00"
        },
        "created": "2020-05-11T15:54:12Z",
        "updated": "2020-05-11T15:54:12Z",
        "payment_methods": {},
        "line_items": {
            "ac43aed7-b2ae-4e76-990d-25aea6832489": {
                "line_item_id": "ac43aed7-b2ae-4e76-990d-25aea6832489",
                "product_sku": "12345",
                "amount": 500,
                "currency": "USD",
                "display_amount": "USD 5.00",
                "reference_type": "seller_listing_id",
                "reference_id": "listing123",
                "transaction_type": "user_to_user",
                "description": "",
                "metadata": null,
                "subitems": {
                    "6ba69fcb-0793-4798-9466-34e189445d8f": {
                        "subitem_id": "6ba69fcb-0793-4798-9466-34e189445d8f",
                        "amount": 500,
                        "currency": "USD",
                        "display_amount": "USD 5.00",
                        "reference_type": "invoicing.invoice_line_item_v2.line_item_id",
                        "reference_id": "ac43aed7-b2ae-4e76-990d-25aea6832489",
                        "subitem_type": "user_recipient",
                        "description": "",
                        "metadata": null,
                        "source_account_id": "793fab8e-6da5-4b26-b7f9-aab9cf809f91",
                        "source_payment_method_id": "950606a3-3b89-4589-9b53-f7d39a5f96ce",
                        "source_wallet_id": "26ac23a6-7457-48f4-9e97-faee2ce37664",
                        "destination_account_id": "09c9e3ee-8af5-4206-aaa4-1a913ea855d2",
                        "destination_payment_method_id": "76691843-ac5c-4b4b-a5c6-7fd3a558f23f",
                        "destination_wallet_id": "5d3d5e51-e622-4d0f-a3c2-e6dc99e3c487"
                    }
                }
            }
        },
        "subitems": {
            "6ba69fcb-0793-4798-9466-34e189445d8f": {
                "subitem_id": "6ba69fcb-0793-4798-9466-34e189445d8f",
                "amount": 500,
                "currency": "USD",
                "display_amount": "USD 5.00",
                "reference_type": "invoicing.invoice_line_item_v2.line_item_id",
                "reference_id": "ac43aed7-b2ae-4e76-990d-25aea6832489",
                "subitem_type": "user_recipient",
                "description": "",
                "metadata": null,
                "source_account_id": "793fab8e-6da5-4b26-b7f9-aab9cf809f91",
                "source_payment_method_id": "950606a3-3b89-4589-9b53-f7d39a5f96ce",
                "source_wallet_id": "26ac23a6-7457-48f4-9e97-faee2ce37664",
                "destination_account_id": "09c9e3ee-8af5-4206-aaa4-1a913ea855d2",
                "destination_payment_method_id": "76691843-ac5c-4b4b-a5c6-7fd3a558f23f",
                "destination_wallet_id": "5d3d5e51-e622-4d0f-a3c2-e6dc99e3c487"
            }
        }
    }
}

The value for state will be processing until the invoice is processed, at which time the state will update to either:

  • success, indicating the invoice has been successfully paid.
  • failed, indicating the invoice could not be paid. In this case, the failure_reason field returns additional information describing the failure.

You can check the status of an invoice by calling GET https://invoicing.tilia-inc.com/v2/invoice/{invoice_id}.

Step 6: Handle the completion event

Although this step is not mandatory, we recommend implementing a webhook to notify you about changes to the transaction's status.

The webhook request body will be the same as the response body from create or pay invoice, but with a state of success or failed. See the Invoice Completion webhook documentation for complete details.

attention

Currently, webhook endpoints must be configured manually by Tilia staff. We are developing a web interface to enable you to control this directly. For now, please contact us for assistance.