Entity Feature

An Entity Feature represents the enablement and status of a specific feature for an entity. Features extend entity functionality to support additional capabilities like multi-currency operations.

Entity Feature Object

{
  "feature_identifier": "multi_currency_account",
  "feature_name": "Multi-Currency Account",
  "application_id": "Z2lkOi8vYXBwL0FwcGxpY2F0aW9uLzEyMw",
  "status": "ACTIVE"
}

Attributes

Attribute	Type	Description
`feature_identifier`	string	Unique identifier for the feature type
`feature_name`	string	Human-readable name of the feature
`application_id`	string	Unique identifier for this feature enablement instance. Each entity can have exactly one application per feature. This ID is consistent across webhooks, API responses, and back office tools.
`status`	string	Current status of the feature application

Available Features

Feature Identifier	Feature Name	Description
`multi_currency_account`	Multi-Currency Account	Enables multi-currency account capabilities and international payment support

Availability

Multi-Currency Account feature is only available for US entities.

Feature Statuses

Entity features progress through different statuses during their lifecycle:

Status	Description
`CREATED`	Feature enabled, awaiting initial setup or onboarding
`SUBMITTED`	Onboarding information submitted and under review
`ACTIVE`	Feature is fully operational and ready to use
`ACTION_REQUIRED`	Additional information or action needed from the user

Feature Lifecycle

The following diagram illustrates how entity features progress through different statuses:

Allowed Status Transitions:

CREATED → SUBMITTED (when user completes onboarding)
SUBMITTED → ACTIVE (when application is approved)
SUBMITTED → ACTION_REQUIRED (when additional information is needed)
ACTION_REQUIRED → SUBMITTED (when user provides required information)

Lifecycle Steps

The following sequence diagram shows the interaction flow for enabling and activating a feature:

Step-by-step breakdown:

Enable Feature - Client application creates the feature with status CREATED
Generate Token - Generate onboarding token for user authentication
User Onboarding - User completes onboarding via hosted page (status becomes SUBMITTED)
Review Process - Feature application is reviewed
May transition to ACTION_REQUIRED if additional information needed
User provides required information (returns to SUBMITTED)
Activation - Feature becomes ACTIVE after approval

Available Operations

List Entity Features - Returns all enabled features for a specific entity
Enable Feature - Enable a new feature for an entity (creates feature with status CREATED)
Generate Hosted Page Token - Create authentication token for hosted page access

Token Purposes

When generating tokens for the hosted page, different purposes are used depending on the feature lifecycle stage:

Purpose	When to Use	Description
`onboarding`	Feature status is `CREATED`	Used for initial feature setup and onboarding. Grants access to complete the onboarding form on the hosted page.
`pending_action`	Feature status is `ACTION_REQUIRED`	Used when additional information is needed. Grants access to provide missing or corrected information on the hosted page.

Token Purpose Validation

The token purpose must match the current application status. For example, attempting to generate an onboarding token when the feature status is ACTION_REQUIRED will return an error. Always ensure the purpose aligns with the current status before generating a token.

Token Generation Examples

Both token purposes follow the same endpoint but with different request bodies:

Initial Onboarding (status: CREATED)

POST /companies/{company_id}/entities/{entity_id}/hosted_page_tokens

{
  "feature_identifier": "multi_currency_account",
  "purpose": "onboarding",
  "application_id": "Z2lkOi8vYXBwL0FwcGxpY2F0aW9uLzEyMw"
}

Pending Action (status: ACTION_REQUIRED)

POST /companies/{company_id}/entities/{entity_id}/hosted_page_tokens

{
  "feature_identifier": "multi_currency_account",
  "purpose": "pending_action",
  "application_id": "Z2lkOi8vYXBwL0FwcGxpY2F0aW9uLzEyMw"
}

Both tokens redirect users to the same hosted page, which displays the appropriate form based on the token's purpose.

Using Hosted Pages

The hosted page provides a secure, pre-built interface for users to complete feature onboarding and provide additional information when needed.

Integration Flow

Generate Token - Call the token generation endpoint with the appropriate purpose
Receive Token - The API returns a token in the response
Construct URL - Build the hosted page URL: {TREASURYPATH_HOSTED_URL}/entity-feature?token={token}
Redirect User - Redirect your end user to the constructed URL
User Completes Form - User fills out the required information on the hosted page
Automatic Submission - Form data is submitted directly to TreasuryPath API
Webhook Notification - Your application receives a webhook when the status changes

Hosted Page Features

Single Page, Multiple Forms - The same hosted page displays different forms based on:
Token purpose (onboarding vs pending_action)
Feature identifier
Current application status
Secure Authentication - Each token is single-use and time-limited
Automatic Validation - Form validation and error handling built-in
Responsive Design - Works across desktop and mobile devices
Session Management - User progress is saved during the session

Example Response

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "purpose": "pending_action",
    "feature_identifier": "multi_currency_account",
    "application_id": "Z2lkOi8vd2FsbGV0LWFwcC9Bd3hBY2NvdW50Lzk"
  }
}

Direct your user to: {TREASURYPATH_HOSTED_URL}/entity-feature?token={token}

Note: {TREASURYPATH_HOSTED_URL} is the hosted page URL for your environment. See Introduction for environment URLs.

Webhook Notifications

TreasuryPath sends webhook notifications when an entity feature's status changes. This allows your application to respond to status changes in real-time without polling the API.

Status Change Event

Event Name: MultiCurrencyAccountEvents::StatusChangedEvent

This webhook is triggered whenever a multi-currency account feature changes status. The event is always system-triggered (actor_id is null) as status changes are managed by the underlying payment provider.

When Webhooks Are Triggered

Webhooks are sent for the following status changes:

Status	When It Occurs
`CREATED`	Feature enabled via API, awaiting initial setup
`SUBMITTED`	User completed onboarding form via hosted page
`ACTIVE`	Application approved and account is fully operational
`ACTION_REQUIRED`	Additional information needed from the customer

Webhook Payload

Standard Payload:

{
  "event": "MultiCurrencyAccountEvents::StatusChangedEvent",
  "timestamp": "2025-01-17T14:30:00.000Z",
  "company_id": "Z2lkOi8vYXBwL0NvbXBhbnkvMTIz",
  "resource_id": "Z2lkOi8vYXBwL0F3eEFjY291bnQvNDU2",
  "actor_id": null,
  "entity_id": "Z2lkOi8vYXBwL0VudGl0eS83ODk",
  "feature_identifier": "multi_currency_account",
  "status": "ACTIVE"
}

With Additional Information Required:

When status is ACTION_REQUIRED, an additional rfi_id field is included:

{
  "event": "MultiCurrencyAccountEvents::StatusChangedEvent",
  "timestamp": "2025-01-17T14:30:00.000Z",
  "company_id": "Z2lkOi8vYXBwL0NvbXBhbnkvMTIz",
  "resource_id": "Z2lkOi8vYXBwL0F3eEFjY291bnQvNDU2",
  "actor_id": null,
  "entity_id": "Z2lkOi8vYXBwL0VudGl0eS83ODk",
  "feature_identifier": "multi_currency_account",
  "status": "ACTION_REQUIRED",
  "rfi_id": "rfi_verification_2025"
}

Payload Fields

Field	Type	Description
`event`	string	Event type identifier
`timestamp`	string	ISO 8601 timestamp when the event occurred
`company_id`	string	ID of the company that owns the entity
`resource_id`	string	ID of the multi-currency account (same as `application_id`)
`actor_id`	null	Always `null` (system-triggered event)
`entity_id`	string	ID of the entity that has the feature enabled
`feature_identifier`	string	Feature type identifier (e.g., `multi_currency_account`)
`status`	string	Current status of the feature (`CREATED`, `SUBMITTED`, `ACTIVE`, `ACTION_REQUIRED`)
`rfi_id`	string	Request for Information ID (only present when `status` is `ACTION_REQUIRED`)

Handling Status Changes

Scenario 1: Account Activated

When a multi-currency account becomes active:

Webhook payload includes: "status": "ACTIVE"

Recommended action:

The multi-currency account is ready to use. Enable multi-currency features in your application.

Scenario 2: Additional Information Required

When the system needs more information:

Webhook payload includes: "status": "ACTION_REQUIRED" and "rfi_id": "rfi_verification_2025"

Recommended action:

Generate a hosted page token with purpose: "pending_action"
Direct the customer to the hosted page to provide required information

Webhook Best Practices

Always verify the TreasuryPath-Signature header to ensure webhook authenticity
Return a 200 status code as soon as possible
Process events asynchronously to avoid timeouts
Use resource_id and timestamp for idempotent processing
For full feature details, call the List Entity Features endpoint

For webhook setup, security, and signature verification, see Webhooks.

For detailed API endpoints and request/response examples, see the Multi-Currency Enablement API Reference.