Tilia Hosted Widget

This style of integration involves sending the user to the Tilia flow via a full page navigation from your domain to Tilia’s, where Tilia wraps the widget.


Please refer to the Tilia Hosted Checkout guide for steps to integrate the checkout flow using this method.

This integration method involves the following steps:

  1. User authorization
  2. Optionally, return the user to your UI

User Authorization

To generate a link for the user so that they can access the Tilia flow UI, first you will need to authorize them. POST a request to authorize the user by using an access token with the scope write_user_tokens.

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

Request Body

    "account_id": "<ACCOUNT_ID>",
    "mechanism": "tilia_hosted",
    "flow": "<FLOW_NAME>"

Where <FLOW_NAME> can be kyc, payout, txnhistory, or addcard

Example Response

    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "nonce_auth_id": "133fafce-80ab-42f6-82b1-7266d9bab91d",
        "redirect": "https://pub.tilia-inc.com/testpublisher/txnhistory/133fafce-80ab-42f6-82b1-7266d9bab91d"

Return URL

You can optionally redirect users back to your UI upon completion of the flow by appending “?returnUrl=<RETURN_URL>” to the end of the redirect link.

Redirect Example


Upon completing the flow, the user is redirected to <RETURN_URL>, with flow-specific parameters appended.

Return Example


Refer to the flow-specific documentation for details on the parameters returned.


The appearance of the page that hosts the widget can be customized with:

  • A background color
  • A primary color
  • Your brand logo
  • Preview text
  • Message on complete
  • Message on user-cancellation

Contact us for help with the customization of the Tilia Hosted Widget page.