Tilia Hosted Checkout

The quickest way to start accepting payments is to use the Tilia Hosted Checkout experience. Using this method, a redirect link will be shared with you, so you can link the end user to a webpage that hosts the Tilia checkout widget. This flow presents the purchasing user the details of the invoice. It allows them to add and select the payment method they wish to use, and then to pay the invoice in a seamless experience.

This guide will walk you through the steps to set up this experience, so you can begin processing invoices.

Prerequisites

• An Access Token with the requisite scopes: read_invoice , write_invoice , write_payment_method , and read_payment_method . Refer to Quickstart for information on getting access to Tilia’s APIs
• An account ID for the purchasing user. Refer to Registering Users for information on creating user accounts.
• Details of the line items to be included in this payment.

To use the Tilia Hosted Checkout flow, follow these steps:

Step 1: Call the hosted checkout flow to obtain redirect link

Step 2: Handle the completion event

Download the Example Server

Step 1: Call the hosted checkout flow to obtain redirect link

To initiate the Tilia Hosted Checkout flow, submit a POST request with a request body containing the required information. Refer to the Authorize Invoice API reference for more information.

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

Request body

{
    "account_id": "<buyer_account_id>",
    "is_escrow": false,
    "invoice_mechanism": "tilia_hosted",
    "reference_type": "product_purchase_id",
    "reference_id": "purchase_id123",
    "line_items": [
        {
            "description": "your_product_description",
            "product_sku": "your_SKU",
            "transaction_type": "user_to_integrator",
            "currency": "USD",
            "amount": 1
        }
    ]
}

Sample Response

A successful request returns the HTTP 200 status code and a JSON response body containing the redirect link, that you can now pass over to the end user.

{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "authorized_invoice_id": "9f9ae80b-9f19-407d-8a10-7f6158f9b2c7",
        "redirect": "https://pub.tilia-inc.com/<PUBLISHER_ID>/checkout/<NONCE_ID>/?line_items_payload_id=<LINE_ITEMS_ID>&escrow=false"
    }
}

Provide this redirect link to the end user to route them to the Tilia Hosted Checkout. The widget takes it from here, allowing the user to add and select their payment method of choice, and to pay the invoice. They will receive a success message when the payment has been completed.

The appearance of this page can be customized with a background color, primary color, your brand logo, and some preview text. Contact us for help with this customization.

Step 2: 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.

For more information about developing and registering webhook handlers, visit Webhooks.

Download the Example Server

You can download the example server here to get started.