Multi-Currency Account & Payments API

The Multi-Currency API allows you to enable and manage multi-currency account capabilities for entities. This feature extends entity functionality to support international payments and multi-currency operations.

Endpoints

• List Multi-Currency Features - GET /api/v1/companies/{company_id}/entities/{entity_id}/features
• Enable Multi-Currency - POST /api/v1/companies/{company_id}/entities/{entity_id}/features
• Generate Authentication Token - POST /api/v1/companies/{company_id}/entities/{entity_id}/hosted_page_tokens

---

List Multi-Currency Features

Retrieve all enabled features for a specific entity, including their current status and configuration.

Endpoint

GET /api/v1/companies/{company_id}/entities/{entity_id}/features

Headers

Authorization: Bearer {jwt_token}
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
company_id	string	Yes	ID of the company
entity_id	string	Yes	ID of the entity

Example Request

curl -X GET "https://api.treasurypath.com/api/v1/companies/Z2lkOi8vYXBwL0NvbXBhbnkvMQ/entities/Z2lkOi8vYXBwL0VudGl0eS8x/features" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json"

Success Response (200 OK)

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

Response Fields

Field	Type	Description
feature_identifier	string	Unique identifier for the feature (e.g., "multi_currency_account")
feature_name	string	Human-readable name of the feature
application_id	string	Unique identifier for this feature enablement
status	string	Current status of the feature

Feature Statuses

Status	Description
CREATED	Feature enabled, awaiting initial setup
SUBMITTED	Onboarding information submitted for review
ACTIVE	Feature is fully operational
ACTION_REQUIRED	Additional information or action needed from user

Error Responses

401 Unauthorized - Invalid Token

{
  "errors": [
    {
      "field": "token",
      "message": "Missing or invalid token"
    }
  ]
}

404 Not Found - Entity Not Found

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

---

Enable Multi-Currency

Enable multi-currency capabilities for an entity. This creates the feature application and initiates any required setup processes.

Endpoint

POST /api/v1/companies/{company_id}/entities/{entity_id}/features

Headers

Authorization: Bearer {jwt_token}
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
company_id	string	Yes	ID of the company
entity_id	string	Yes	ID of the entity

Request Body

Parameter	Type	Required	Description
feature_identifier	string	Yes	Must be "multi_currency_account"

Example Request

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

Success Response (201 Created)

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

Important: Save the application_id from this response. You'll need it to generate tokens for user onboarding.

Success Response - Already Enabled (200 OK)

If the feature is already enabled with status CREATED, the existing feature is returned:

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

Error Responses

400 Bad Request - Missing Feature Identifier

{
  "errors": [
    {
      "field": "feature_identifier",
      "message": "Feature identifier is required"
    }
  ]
}

400 Bad Request - Invalid Feature Identifier

{
  "errors": [
    {
      "field": "feature_identifier",
      "message": "Invalid feature identifier. Available features: multi_currency_account"
    }
  ]
}

401 Unauthorized - Invalid Token

{
  "errors": [
    {
      "field": "token",
      "message": "Missing or invalid token"
    }
  ]
}

404 Not Found - Entity Not Found

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

422 Unprocessable Entity - Requirements Not Met

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

422 Unprocessable Entity - Feature Already Active

{
  "errors": [
    {
      "field": "base",
      "message": "Multi-currency account already exists with status: ACTIVE. Cannot create a new account."
    }
  ]
}

---

Generate Authentication Token

Generate a secure token for feature-related user actions such as onboarding or responding to action requests. This token enables users to complete required steps for feature activation via TreasuryPath's hosted pages.

Endpoint

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

Headers

Authorization: Bearer {jwt_token}
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
company_id	string	Yes	ID of the company
entity_id	string	Yes	ID of the entity

Request Body

Parameter	Type	Required	Description
feature_identifier	string	Yes	Must be "multi_currency_account"
purpose	string	Yes	Purpose of the token (see Token Purposes)
application_id	string	Yes	Application ID received when feature was enabled
return_url	string	No	URL to redirect the user to after completing the flow. Must match a trusted domain.

Token Purposes

Purpose	Description	Required Feature Status
onboarding	Initial feature setup and verification	CREATED
pending_action	Respond to requests for additional information	ACTION_REQUIRED

Example Request - Onboarding

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

Example Request - Pending Action

curl -X POST "https://api.treasurypath.com/api/v1/companies/Z2lkOi8vYXBwL0NvbXBhbnkvMQ/entities/Z2lkOi8vYXBwL0VudGl0eS8x/hosted_page_tokens" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "feature_identifier": "multi_currency_account",
    "purpose": "pending_action",
    "application_id": "Z2lkOi8vYXBwL0FwcGxpY2F0aW9uLzEyMw",
    "return_url": "https://app.example.com/onboarding/action-complete"
  }'

Success Response (201 Created)

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

return_url in response

The return_url field is only present in the response when a valid return_url was provided in the request and passed trusted domain validation.

Response Fields

Field	Type	Description
token	string	Authentication token valid for 2 hours. Pass this as a URL parameter to TreasuryPath's hosted page.
purpose	string	Purpose of the token (matches request)
feature_identifier	string	Feature identifier (matches request)
application_id	string	Application identifier (matches request)
return_url	string	(Optional) The validated return URL. Only present when a valid return_url was provided.

Token Properties

• Expiration: Tokens expire 2 hours after generation
• Format: Secure JWT token
• Usage: Pass as URL parameter to {TREASURYPATH_HOSTED_URL}/entity-feature?token={token}

Error Responses

400 Bad Request - Missing Field

{
  "errors": [
    {
      "field": "purpose",
      "message": "Purpose is required"
    }
  ]
}

400 Bad Request - Invalid Purpose

{
  "errors": [
    {
      "field": "purpose",
      "message": "Invalid purpose"
    }
  ]
}

401 Unauthorized - Invalid Token

{
  "errors": [
    {
      "field": "token",
      "message": "Missing or invalid token"
    }
  ]
}

404 Not Found - Application Not Found

{
  "errors": [
    {
      "field": "application_id",
      "message": "Application not found"
    }
  ]
}

422 Unprocessable Entity - Untrusted Return URL Domain

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

Resolution: Add the return URL's domain to your workspace's trusted domains configuration. See Trusted Domains.

422 Unprocessable Entity - Invalid Application Type

{
  "errors": [
    {
      "field": "application_id",
      "message": "Invalid application type for this feature"
    }
  ]
}

422 Unprocessable Entity - Application Not Owned by Entity

{
  "errors": [
    {
      "field": "application_id",
      "message": "Application does not belong to this entity"
    }
  ]
}

422 Unprocessable Entity - Wrong Status for Purpose

{
  "errors": [
    {
      "field": "base",
      "message": "Cannot create token. Application status must be CREATED, current status is ACTIVE"
    }
  ]
}

Common Causes: - Using onboarding purpose when status is not CREATED - Using pending_action purpose when status is not ACTION_REQUIRED

Solution: Check the feature status first, then use the appropriate purpose for token generation.

422 Unprocessable Entity - Untrusted Return URL

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

Resolution: Add the return URL's domain to your workspace's trusted domains. If no trusted domains are configured, return_url is silently ignored.

---

Object Schemas

Feature Object

Represents an enabled feature for an entity.

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

Field	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 specific feature enablement
status	string	Current operational status of the feature

Token Object

Represents a generated authentication token for user actions.

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

Field	Type	Description
token	string	Authentication token (valid for 2 hours)
purpose	string	Purpose of the token
feature_identifier	string	Feature this token is for
application_id	string	Application this token is associated with
return_url	string	(Optional) The validated return URL. Only present when provided and trusted.

---

Status Workflow

Multi-Currency Account Status Flow

CREATED
   ↓ (User completes onboarding)
SUBMITTED
   ↓ (Under review)
   ↓ (Approved)                    ↓ (More info needed)
ACTIVE                        ACTION_REQUIRED
                                    ↓ (User provides info)
                                 SUBMITTED
                                    ↓
                                 ACTIVE

Status Transitions

From Status	To Status	Trigger
CREATED	SUBMITTED	User completes onboarding
SUBMITTED	ACTIVE	Approval granted
SUBMITTED	ACTION_REQUIRED	Additional information needed
ACTION_REQUIRED	SUBMITTED	User provides required information

---

Rate Limits

All Multi-Currency API endpoints are subject to standard rate limiting:

• Rate Limit: 100 requests per minute per API key
• Headers: Rate limit information included in response headers
• X-RateLimit-Limit: Total requests allowed per window
• X-RateLimit-Remaining: Requests remaining in current window
• X-RateLimit-Reset: Time when the rate limit resets (Unix timestamp)

---

Best Practices

Feature Enablement

1. Check Requirements First: Verify entity meets feature requirements before enabling
2. Store Application ID: Save the application_id for future token generation
3. Handle Existing Features: Check if feature is already enabled before calling enable endpoint

Token Generation

1. Validate Status: Check feature status matches the required status for your purpose
2. Generate Fresh Tokens: Create new tokens for each user session rather than reusing
3. Handle Expiration: Tokens expire after 2 hours; generate new tokens as needed
4. Secure Transmission: Always transmit tokens over HTTPS

Error Handling

1. Check Status Codes: Handle different HTTP status codes appropriately
2. Parse Error Messages: Extract field-specific error messages for better UX
3. Implement Retry Logic: Use exponential backoff for 5xx server errors
4. Validate Inputs: Validate inputs client-side before making API calls

Monitoring

1. Use Webhooks: Implement webhook listeners for real-time status change notifications
2. Check When Required: Use GET /features endpoint when needed to verify current status
3. Handle ACTION_REQUIRED: Implement workflows to notify users when action is required
4. Track Application IDs: Maintain mapping between features and application IDs

---

See Also

• Enable Multi-Currency - Comprehensive guide with use cases and examples
• Entities API - API documentation for entity management
• Error Handling Guide - Common errors and solutions
• Authentication - API authentication documentation