Enable Multi-Currency Feature

This guide walks you through enabling multi-currency capabilities for your entity, allowing you to hold balances in multiple currencies and make cross-border payments seamlessly.

What You'll Learn

• How to enable the multi-currency feature for your entity
• How to generate authentication tokens for user onboarding
• How to direct users to complete the KYC process
• How to monitor feature activation status via webhooks
• How to handle action required scenarios

Prerequisites

Before enabling multi-currency capabilities:

• ✅ Company and entity already created (see Setup Your Organization)
• ✅ Entity must be located in the United States (country_alpha2: "US")
• ✅ A valid JWT token (see Authentication)
• ✅ Company ID and Entity ID from your organization setup

US Entities Only

Currently, multi-currency features are only available for entities located in the United States.

Understanding the Enablement Process

The multi-currency enablement process involves several steps and actors. Here's how the flow works:

Feature Status Flow

Step 1: Enable Multi-Currency Feature

First, enable the multi-currency feature for your entity.

curl -X POST "https://api.treasurypath.com/api/v1/companies/{company_id}/entities/{entity_id}/features" \
  -H "Authorization: Bearer {your_jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "feature_identifier": "multi_currency_account"
  }'

Replace:

• {company_id} - Your company ID
• {entity_id} - Your entity ID
• {your_jwt_token} - Your JWT authentication token

Success Response

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

Save the Application ID

Copy and save the application_id from the data object - you'll need it to generate onboarding tokens in the next step. This ID remains consistent across all webhooks and API responses for this feature.

What This Means

• Status: CREATED - The feature has been enabled but requires user onboarding
• Application ID - Unique identifier for this feature enablement (one application per entity per feature)
• Next Step - Generate an onboarding token for your user to complete KYC

Step 2: Generate Onboarding Token

Create a secure authentication token that allows your end user to complete the KYC onboarding process.

curl -X POST "https://api.treasurypath.com/api/v1/companies/{company_id}/entities/{entity_id}/hosted_page_tokens" \
  -H "Authorization: Bearer {your_jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "feature_identifier": "multi_currency_account",
    "purpose": "onboarding",
    "application_id": "Z2lkOi8vYXBwL0FwcGxpY2F0aW9uLzEyMw",
    "return_url": "https://yourapp.com/onboarding/complete"
  }'

Replace application_id with the ID you received in Step 1. The return_url parameter is optional — see the tip below.

Return URL (Optional)

You can include an optional return_url parameter to redirect users back to your application after they complete the hosted page flow. The URL's domain must be listed in your workspace's trusted domains configuration. If no trusted domain config exists, the parameter is silently ignored.

Success Response

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "purpose": "onboarding",
    "feature_identifier": "multi_currency_account",
    "application_id": "Z2lkOi8vYXBwL0FwcGxpY2F0aW9uLzEyMw",
    "return_url": "https://yourapp.com/onboarding/complete"
  }
}

Token Expiration

The onboarding token is valid for 2 hours. If it expires before the user completes onboarding, you can generate a new token using the same request.

Step 3: Direct User to Complete Onboarding

Now direct your end user to TreasuryPath's hosted onboarding page with the generated token.

Construct the Onboarding URL

{TREASURYPATH_HOSTED_URL}/entity-feature?token={token}

Environment URLs:

Environment	Hosted URL
Sandbox	https://app.tpathdemo.com/hosted
Production	https://app.treasurypath.com/hosted

Example URLs

Sandbox:

https://app.tpathdemo.com/hosted/entity-feature?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Production:

https://app.treasurypath.com/hosted/entity-feature?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

What Happens During Onboarding

The end user will be guided through:

1. Identity Verification - KYC (Know Your Customer) requirements
2. Business Information - Additional company/entity details
3. Compliance Documentation - Required regulatory documents

Once the user submits all required information, the feature status automatically changes to SUBMITTED and you'll receive a webhook notification.

Step 4: Monitor Feature Status via Webhooks

TreasuryPath sends webhook notifications when the feature status changes. Set up webhooks to receive real-time updates without polling the API.

Webhook Event

Event Name: MultiCurrencyAccountEvents::StatusChangedEvent

This webhook is triggered whenever the multi-currency account feature changes status.

Example Webhook Payload

{
  "event": "MultiCurrencyAccountEvents::StatusChangedEvent",
  "data": {
    "feature_identifier": "multi_currency_account",
    "feature_name": "Multi-Currency Account",
    "application_id": "Z2lkOi8vYXBwL0FwcGxpY2F0aW9uLzEyMw",
    "status": "SUBMITTED",
    "entity_id": "Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHkvMQ",
    "company_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE"
  },
  "timestamp": "2025-11-17T10:45:00.000Z"
}

Status Changes You'll Receive

Status	Description	Action Required
CREATED	Feature enabled via API	Generate onboarding token
SUBMITTED	User completed onboarding	Wait for review
ACTIVE	Feature fully operational	Start using multi-currency
ACTION_REQUIRED	Additional information needed	Generate pending action token

Setting Up Webhooks

See the Webhooks Guide for detailed instructions on configuring webhook endpoints and verifying signatures.

Alternative: Polling the API

If webhooks aren't set up, you can poll the features endpoint:

curl -X GET "https://api.treasurypath.com/api/v1/companies/{company_id}/entities/{entity_id}/features" \
  -H "Authorization: Bearer {your_jwt_token}"

Step 5: Handle Action Required (If Needed)

If additional information is required during the review process, the status will change to ACTION_REQUIRED and you'll receive a webhook notification.

Generate Pending Action Token

curl -X POST "https://api.treasurypath.com/api/v1/companies/{company_id}/entities/{entity_id}/hosted_page_tokens" \
  -H "Authorization: Bearer {your_jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "feature_identifier": "multi_currency_account",
    "purpose": "pending_action",
    "application_id": "Z2lkOi8vYXBwL0FwcGxpY2F0aW9uLzEyMw",
    "return_url": "https://yourapp.com/pending-action/complete"
  }'

Token Purpose Must Match Status

The purpose field must match the current application status: - Use "onboarding" when status is CREATED - Use "pending_action" when status is ACTION_REQUIRED

Attempting to use the wrong purpose will result in a validation error.

Success Response

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "purpose": "pending_action",
    "feature_identifier": "multi_currency_account",
    "application_id": "Z2lkOi8vYXBwL0FwcGxpY2F0aW9uLzEyMw",
    "return_url": "https://yourapp.com/pending-action/complete"
  }
}

Direct User to Resolve Actions

Use the same hosted page URL format with the new token:

{TREASURYPATH_HOSTED_URL}/entity-feature?token={new_token}

The hosted page will automatically display the specific actions the user needs to complete, such as:

• Uploading additional documents
• Providing clarifications
• Updating information

After the user provides the required information, the status returns to SUBMITTED for review.

Step 6: Feature Activation

Once the application is approved, the status changes to ACTIVE and you'll receive a webhook notification. At this point:

• ✅ Multi-currency feature is fully operational
• ✅ Managed bank accounts are automatically created for your entity
• ✅ You can start processing cross-currency payments

Common Errors

Feature Already Enabled

{
  "errors": [
    {
      "field": "feature_identifier",
      "message": "Feature already enabled for this entity"
    }
  ]
}

Solution: The feature is already enabled. Check its current status using the GET features endpoint. Each entity can have only one application per feature.

Entity Not in United States

{
  "errors": [
    {
      "field": "entity",
      "message": "Multi-currency account is only available for US entities"
    }
  ]
}

Solution: Ensure your entity's country_alpha2 is set to "US". Non-US entities cannot enable multi-currency at this time.

Invalid Application ID

{
  "errors": [
    {
      "field": "application_id",
      "message": "Invalid or not found application"
    }
  ]
}

Solution: Verify you're using the correct application_id from the feature enablement response. The application ID must match the feature you're generating a token for.

Wrong Token Purpose for Status

{
  "errors": [
    {
      "field": "purpose",
      "message": "Invalid purpose for current feature status"
    }
  ]
}

Solution: Use the correct purpose for the current status: - Status CREATED → Use purpose "onboarding" - Status ACTION_REQUIRED → Use purpose "pending_action"

Entity Not Found

{
  "errors": [
    {
      "field": "entity_id",
      "message": "Entity not found or not accessible in this company"
    }
  ]
}

Solution: Verify you're using the correct entity_id and that it belongs to the specified company_id. Ensure the entity exists and you have access to it.

What's Next?

Once your multi-currency feature is ACTIVE, you can:

1. Connect Funding Accounts - Link external bank accounts for payments
2. Add Recipients - Set up international recipients
3. Make Payments - Create cross-currency payments
4. View Managed Accounts - Access automatically created multi-currency accounts

Best Practices

Token Management

• ✅ Generate tokens just-in-time before directing users
• ✅ Don't store tokens long-term (they expire in 2 hours)
• ✅ Generate new tokens if users need to revisit the onboarding flow
• ✅ Track the application_id consistently across all operations

Status Monitoring

• ✅ Set up webhooks for real-time status updates (recommended)
• ✅ Don't poll the API excessively if using polling
• ✅ Handle ACTION_REQUIRED status promptly to avoid delays
• ✅ Store the application_id for tracking purposes

User Experience

• ✅ Clearly communicate onboarding requirements to users upfront
• ✅ Provide support contact information during the onboarding process
• ✅ Set realistic expectations for review timeline (typically 1-3 business days)
• ✅ Inform users when additional action is required

API Reference

For complete API documentation, see:

• Multi-Currency Enablement API Reference - Full endpoint documentation
• Entity Feature Data Model - Detailed property descriptions and lifecycle
• Webhooks Reference - Webhook event details and security

Need Help?

• Check the FAQ for common questions
• Contact support at support@treasurypath.com