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.

note

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:

User authorization
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.

Copy

Copied

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

Copy

Copied

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

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

Example Response

Copy

Copied

{
    "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.

note

If you wish to provide a return URL, please contact Tilia to help you configure your Allowed Domain Origin List. Any URL provided will fail to redirect unless the domain is provided in the whitelist.

Redirect Example

Copy

Copied

https://pub.tilia-inc.com/testpublisher/txnhistory/133fafce-80ab-42f6-82b1-7266d9bab91d?returnUrl=https://acme.com

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

Return Example

Copy

Copied

https://acme.com/?source=tilia&event=tilia.txnhistory.complete&state=complete&trigger=header-close-button

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

Customization

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