{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Tilia Hosted Widget","description":"Tilia Wallet Developer Documentation","siteUrl":"https://thunes-tilia-docs.redocly.app/","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"tilia-hosted-widget","__idx":0},"children":["Tilia Hosted Widget"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Please refer to the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/web-uis/tilia-hosted-checkout"},"children":["Tilia Hosted Checkout"]}," guide for steps to integrate the checkout flow using this method."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This integration method involves the following steps:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["User authorization"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Optionally, return the user to your UI"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"user-authorization","__idx":1},"children":["User Authorization"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["write_user_tokens"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"curl --location --request POST 'https://auth.tilia-inc.com/authorize/user' \\\n--header 'Authorization: Bearer CLIENT_CREDENTIALS_ACCESS_TOKEN' \\\n--header 'Content-Type: application/json' \\\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"request-body","__idx":2},"children":["Request Body"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"account_id\": \"<ACCOUNT_ID>\",\n    \"mechanism\": \"tilia_hosted\",\n    \"flow\": \"<FLOW_NAME>\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Where ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<FLOW_NAME>"]}," can be  ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kyc"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payout"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["txnhistory"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addcard"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-response","__idx":3},"children":["Example Response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"status\": \"Success\",\n    \"message\": [],\n    \"codes\": [],\n    \"payload\": {\n        \"nonce_auth_id\": \"133fafce-80ab-42f6-82b1-7266d9bab91d\",\n        \"redirect\": \"https://pub.tilia-inc.com/testpublisher/txnhistory/133fafce-80ab-42f6-82b1-7266d9bab91d\"\n    }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"return-url","__idx":4},"children":["Return URL"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can optionally redirect users back to your UI upon completion of the flow by appending ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["“?returnUrl=<RETURN_URL>”"]}," to the end of the redirect link."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"redirect-example","__idx":5},"children":["Redirect Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"https://pub.tilia-inc.com/testpublisher/txnhistory/133fafce-80ab-42f6-82b1-7266d9bab91d?returnUrl=https://acme.com\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Upon completing the flow, the user is redirected to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<RETURN_URL>"]},", with flow-specific parameters appended."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"return-example","__idx":6},"children":["Return Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"https://acme.com/?source=tilia&event=tilia.txnhistory.complete&state=complete&trigger=header-close-button\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Refer to the flow-specific documentation for details on the parameters returned."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"customization","__idx":7},"children":["Customization"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The appearance of the page that hosts the widget can be customized with:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A background color"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A primary color"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your brand logo"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Preview text"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Message on complete"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Message on user-cancellation"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Contact us for help with the customization of the Tilia Hosted Widget page."]}]},"headings":[{"value":"Tilia Hosted Widget","id":"tilia-hosted-widget","depth":1},{"value":"User Authorization","id":"user-authorization","depth":2},{"value":"Request Body","id":"request-body","depth":3},{"value":"Example Response","id":"example-response","depth":3},{"value":"Return URL","id":"return-url","depth":2},{"value":"Redirect Example","id":"redirect-example","depth":3},{"value":"Return Example","id":"return-example","depth":3},{"value":"Customization","id":"customization","depth":2}],"frontmatter":{"seo":{"title":"Tilia Hosted Widget"}},"lastModified":"2026-02-05T18:12:30.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/web-uis/tilia-hosted-widget","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}