{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["openapiLink","admonition"]},"type":"markdown"},"seo":{"title":"Checkout Flow","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":"checkout-flow","__idx":0},"children":["Checkout Flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This flow presents a user with a summary of their invoice, allows them to add new payment methods, select the payment method they wish to use to pay their invoice, and then provides them with a success message once their payment has been successful. The flow starts with a check for a signed Terms of Service and, if necessary, presents the user with a ToS screen before allowing them to proceed to the checkout page."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/checkout.40e184b8bbf4999ec86a758801ff4a0d5675ef45f8e40bd4388f1dea347088b3.9c1bb791.png","alt":"checkout flow widget"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"call-authorize-invoice","__idx":1},"children":["Call Authorize Invoice"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To initiate the checkout flow, you will need to make a call to the Authorize Invoice API. An authorized invoice enables the widget to make calls to create and pay the invoice on the user's behalf. This request that you make at transaction time, will return the following:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authorized_invoice_id"]}," you'll need to reference the invoice"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A redirect link you can use to open this flow in the widget"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The user authentication ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["password_token"]}," that will authorize the widget to take the invoice from there"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Refer to the ",{"$$mdtype":"Tag","name":"OpenapiLink","attributes":{"link":"invoicing/openapi/invoice/authorizeinvoice","text":"Authorize Invoice API reference"},"children":[]}," for more information."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"curl --location --request POST 'https://invoicing.tilia-inc.com/v2/authorize/invoice' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer CLIENT_CREDENTIALS_ACCESS_TOKEN' \\\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"request-body","__idx":2},"children":["Request body"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"account_id\": \"<buyer_account_id>\",\n    \"is_escrow\": false,\n    \"invoice_mechanism\": \"widget\",\n    \"reference_type\": \"product_purchase_id\",\n    \"reference_id\": \"purchase_id123\",\n    \"line_items\": [\n        {\n            \"description\": \"your_product_description\",\n            \"product_sku\": \"your_SKU\",\n            \"transaction_type\": \"user_to_integrator\",\n            \"currency\": \"USD\",\n            \"amount\": 1\n        }\n    ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"sample-response","__idx":3},"children":["Sample Response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful request returns the HTTP 200 status code and a JSON response body containing the redirect link, that you can now pass into the widget flow."]},{"$$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\": \"c287608d-d77c-4d64-8cc0-b81fbe8add00\",\n        \"authorized_invoice_id\": \"a8611571-a5d6-4bc4-9047-9722fa1f8fc2\",\n        \"redirect\": \"https://web.tilia-inc.com/ui/appauth/c287608d-d77c-4d64-8cc0-b81fbe8add00?authorized_invoice_id=a8611571-a5d6-4bc4-9047-9722fa1f8fc2&integrator=tilia-sdks&is_escrow=false&is_virtual=false\"\n    }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"supported-flowconfig-options","__idx":4},"children":["Supported flowConfig Options"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Keys (all optional)"},"children":["Keys (all optional)"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Values"},"children":["Values"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["hideUserWallets"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean (defaults to false)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Hides wallet funds in the UI."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["hideSKUs"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean (defaults to false)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Hides line item 'product_sku' information from the UI."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["showInvoiceReferenceInfo"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean (defaults to false)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Shows ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference_type"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference_id"]}," info in the invoice UI."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["selectButton.label"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Allows customizing the message on the 'Use this Payment Method' button.  Any passed in value should respect the user's localization preferences."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["postOAuthURLOverride"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["url (string)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Only relevant to native applications where a user needs to be redirected to a browser for OAuth validation (i.e. Paypal).  To allow the native application to be opened after validation (through a universal link, or custom url scheme) you can supply the url string here.  For this to work though, we have to add the url domain pattern to an allowed list of redirect patterns (please see your account rep to set this up)."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"widget-flow","__idx":5},"children":["Widget Flow"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"window.Tilia.execute({\n  rootId: \"#tilia-widget\",\n  flow: \"checkout\",\n  redirect: \"redirect-url-from-authorize-invoice\",\n  onComplete: handleComplete,\n  theme: {\n    backgroundColor: \"#323232\",\n    primaryColor: \"#47CC00\"\n  },\n  flowConfig: {} // see supported flowConfig options above\n});\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The appearance of the checkout widget can be customized by adjusting the values in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["theme"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the user cancels anywhere in the flow:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"{\n    source: \"tilia\",\n    event: \"tilia.checkout.complete\",\n    state: \"cancel\",\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the user completes the flow, by clicking the “Done” button after a successful checkout, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onComplete"]}," will be called:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"{\n  source: \"tilia\",\n  event: \"tilia.checkout.complete\",\n  state: \"complete\",\n  trigger: \"done-button\"\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the user faces a full screen error and closes the flow by clicking the “Close” button, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onComplete"]}," with be called:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"{\n  source: \"tilia\",\n  event: \"tilia.checkout.complete\",\n  state: \"error\",\n  trigger: \"close-button\"\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handle-the-completion-event","__idx":6},"children":["Handle the completion event"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Although this step is not mandatory, we recommend implementing a webhook to notify you about changes to the transaction's status."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The webhook request body will be the same as the response body from create or pay invoice, but with a state of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]},". See the ",{"$$mdtype":"Tag","name":"OpenapiLink","attributes":{"link":"invoicing/openapi/payout/payoutcomplete","text":"Payout Completion webhook"},"children":[]},"  documentation for complete details."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you would instead like to send the user to a Tilia-hosted page to complete the transaction, follow these steps to implement ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/web-uis/tilia-hosted-checkout"},"children":["Tilia’s Hosted Checkout"]}," experience."]}]}]},"headings":[{"value":"Checkout Flow","id":"checkout-flow","depth":1},{"value":"Call Authorize Invoice","id":"call-authorize-invoice","depth":3},{"value":"Request body","id":"request-body","depth":4},{"value":"Sample Response","id":"sample-response","depth":4},{"value":"Supported flowConfig Options","id":"supported-flowconfig-options","depth":2},{"value":"Widget Flow","id":"widget-flow","depth":3},{"value":"Handle the completion event","id":"handle-the-completion-event","depth":2}],"frontmatter":{"seo":{"title":"Checkout Flow"}},"lastModified":"2026-02-05T18:12:30.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/web-uis/checkout-flow","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}