Skip to content

Hosted Page Customization

TreasuryPath hosted pages can be customized with your brand identity and configured with security controls. This page covers branding, trusted domains, and return URL support.

Overview

Feature Description
Branding Customize hosted pages with your logo and favicon
Trusted Domains Restrict return URLs to approved domains
Return URL Redirect users back to your application after completing a hosted page flow

All configuration is workspace-scoped — settings apply to every company within the workspace.

Branding

Customize the appearance of TreasuryPath hosted pages with your organization's logo and favicon. When configured, hosted pages display your branding instead of the default TreasuryPath branding.

Branding Object

{
  "logo_url": "https://example.com/logo.png",
  "favicon_url": "https://example.com/favicon.ico"
}

Attributes

Attribute Type Required Description
logo_url string No HTTP(S) URL to your logo image. Displayed on hosted pages.
favicon_url string No HTTP(S) URL to your favicon. Replaces the default browser tab icon.

Validation Rules

  • Both fields are optional — you can set one without the other
  • URLs must use http:// or https:// scheme
  • Other schemes (javascript:, data:, ftp:, etc.) are rejected

How It Works

  1. Configure branding via the TreasuryPath dashboard (Settings > Hosted Pages)
  2. When a hosted page token is generated, the workspace's branding configuration is associated with the token
  3. The hosted page fetches branding on load and applies your logo and favicon
  4. If no branding is configured, the default TreasuryPath branding is used

Trusted Domains

Trusted domains define an allowlist of domains that can be used as return URLs in hosted page tokens. This prevents open redirect attacks by ensuring users can only be redirected to domains you control.

Trusted Domain Config Object

{
  "domains": [
    "app.example.com",
    "*.example.com",
    "dashboard.myapp.io"
  ]
}

Attributes

Attribute Type Required Description
domains array Yes Array of trusted domain strings (max 50)

Domain Format

Domains support exact matches and single-level wildcard subdomains:

Pattern Matches Does Not Match
app.example.com app.example.com other.example.com, example.com
*.example.com app.example.com, dashboard.example.com example.com, deep.sub.example.com
myapp.io myapp.io sub.myapp.io

Validation Rules

  • Maximum 50 domains per workspace
  • Domains must be valid hostnames (alphanumeric characters, hyphens, dots)
  • Wildcard prefix *. matches exactly one subdomain level
  • Duplicate domains (case-insensitive) are not allowed
  • Domain matching is case-insensitive

Configuring Trusted Domains

Configure trusted domains via the TreasuryPath dashboard (Settings > Hosted Pages > Trusted Domains).

Required for Return URLs

Return URLs in hosted page tokens are only accepted when trusted domains are configured. If no trusted domain configuration exists, the return_url parameter is silently ignored.

Return URL

The return URL feature allows you to redirect users back to your application after they complete a hosted page flow (e.g., adding a recipient bank account, linking a funding account, or completing entity onboarding).

How It Works

  1. Configure trusted domains for your workspace (required prerequisite)
  2. Include return_url when generating a hosted page token
  3. TreasuryPath validates the URL domain against your trusted domains
  4. The token is generated with the return URL encoded in the JWT payload
  5. After the user completes the hosted page flow, they see a "Return to Application" button that navigates to the provided URL

Using Return URL with Token Generation

The return_url parameter is supported on all hosted page token generation endpoints:

Example: Recipient Bank Account Token with Return URL

curl -X POST "https://api.treasurypath.com/api/v1/companies/{company_id}/entities/{entity_id}/hosted_page_tokens" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "recipient_add_bank_account",
    "recipient_id": "{recipient_id}",
    "return_url": "https://app.example.com/recipients/123/complete"
  }'

Example: Funding Account Token with Return URL

curl -X POST "https://api.treasurypath.com/api/v1/hosted_page_tokens" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "{entity_id}",
    "purpose": "funding_accounts",
    "return_url": "https://app.example.com/accounts/linked"
  }'

Return URL Parameter

Parameter Type Required Description
return_url string No Full URL to redirect the user to after completing the hosted page flow. Must match a configured trusted domain.

Validation

  • The URL must use http or https scheme
  • The URL's host must match one of the workspace's trusted domains (exact or wildcard match)
  • If no trusted domain configuration exists, the return_url is silently ignored (no error is returned)
  • If trusted domains are configured but the URL doesn't match, a validation error is returned

Error Response — Untrusted Domain

{
  "errors": [
    {
      "field": "return_url",
      "message": "URL domain is not in the trusted domains list"
    }
  ]
}

Security

  • Open Redirect Prevention — Return URLs are validated against trusted domains to prevent attackers from crafting malicious redirect URLs
  • JWT Encoded — The validated return URL is securely encoded in the hosted page JWT token
  • No Client-Side Override — The return URL cannot be modified after token generation

Integration Guide

Setting Up Branded Hosted Pages with Return URLs

Step 1: Configure Branding

Upload your logo and favicon through the TreasuryPath dashboard under Settings > Hosted Pages.

Step 2: Configure Trusted Domains

Add your application domains to the trusted domains list. For example:

  • app.yourcompany.com — your main application
  • *.yourcompany.com — all subdomains (if needed)

Step 3: Generate Tokens with Return URL

When generating hosted page tokens, include the return_url parameter:

// Backend: Generate token with return URL
async function generateRecipientToken(companyId, entityId, recipientId) {
  const response = await fetch(
    `https://api.treasurypath.com/api/v1/companies/${companyId}/entities/${entityId}/hosted_page_tokens`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        purpose: 'recipient_add_bank_account',
        recipient_id: recipientId,
        return_url: 'https://app.yourcompany.com/recipients/complete'
      })
    }
  );

  const data = await response.json();
  return data.data.token;
}

// Frontend: Redirect user to hosted page
function redirectToHostedPage(token) {
  window.location.href =
    `${TREASURYPATH_HOSTED_URL}/hosted/recipient/add-bank-account?token=${token}`;
}

Step 4: Handle the Return

After the user completes the hosted page flow and clicks "Return to Application", they are redirected to your return URL. Use webhooks to confirm the operation completed successfully.

// Your return URL handler
app.get('/recipients/complete', async (req, res) => {
  // The hosted page flow is complete
  // Use webhooks (BankAccountEvents::CreatedEvent) to confirm
  // the bank account was created successfully
  res.render('recipient-bank-account-added');
});

Use Webhooks for Confirmation

The return URL redirect indicates the user completed the flow, but you should rely on webhooks to confirm the operation was successful before updating your application state.