Funding Account Tokens API

The Funding Account Tokens API allows you to generate secure, short-lived JWT tokens for accessing TreasuryPath's funding accounts hosted page. These tokens enable your users to link and manage external bank accounts for debit transactions.

Endpoints

Generate Funding Account Token - POST /api/v1/hosted_page_tokens

Generate Funding Account Token

Generate a secure token that grants access to the funding accounts hosted page. Users can link bank accounts and provide mandate information through the hosted page workflow.

Endpoint

POST /api/v1/hosted_page_tokens

Headers

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

Request Body

Parameter	Type	Required	Description
`entity_id`	string	Yes	ID of the entity
`purpose`	string	Yes	Must be "funding_accounts"

Example Request

curl --request POST \
  --url https://api.treasurypath.com/api/v1/hosted_page_tokens \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "entity_id": "Z2lkOi8vYXBwL0VudGl0eS8xMjM",
    "purpose": "funding_accounts"
  }'

Success Response (201 Created)

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJjb21wYW55X2lkIjoiZ2lkOi8vYXBwL0NvbXBhbnkvMSIsImVudGl0eV9pZCI6ImdpZDovL2FwcC9FbnRpdHkvMTIzIiwicHVycG9zZSI6ImZ1bmRpbmdfYWNjb3VudHMiLCJleHAiOjE3MDk4NTEyMDB9.abc123",
    "purpose": "funding_accounts"
  }
}

Response Fields

Field	Type	Description
`token`	string	Authentication token valid for 2 hours. Pass this as a URL parameter to the funding accounts hosted page.
`purpose`	string	Purpose of the token ("funding_accounts")

Token Properties

Expiration: Tokens expire 2 hours after generation
Format: Secure JWT token
Scope: Limited to funding account operations for the specified entity
Usage: Pass as URL parameter to {TREASURYPATH_HOSTED_URL}/funding-accounts?token={token}

Error Responses

400 Bad Request - Missing Entity ID

{
  "errors": [
    {
      "field": "entity_id",
      "message": "Entity ID is required"
    }
  ]
}

400 Bad Request - Missing Purpose

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

400 Bad Request - Invalid Purpose

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

401 Unauthorized - Invalid API Key

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

403 Forbidden - Purpose Category Mismatch

{
  "errors": [
    {
      "field": "purpose",
      "message": "Purpose must be a hosted_page category"
    }
  ]
}

404 Not Found - Entity Not Found

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

422 Unprocessable Entity - Entity Does Not Belong to Company

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

422 Unprocessable Entity - Missing Multi-Currency Account

{
  "errors": [
    {
      "field": "entity_id",
      "message": "Multi-currency account not found for this entity. Please create an account first."
    }
  ]
}

Resolution: Ensure the entity has a multi-currency account enabled before generating funding account tokens. See Multi-Currency Enablement for details.

Prerequisites

Before generating funding account tokens, ensure:

Multi-Currency Account Enabled - The entity must have an active multi-currency account. See Enable Multi-Currency.
Entity Ownership - The entity must belong to your company.
Valid API Key - Your API key must have appropriate permissions.

Token Security

Best Practices

Secure Transmission
Use HTTPS for all API requests
Transmit tokens only via secure channels
Never log tokens or expose them in error messages
Fresh Tokens
Generate a new token for each user session
Don't cache or reuse tokens across sessions
Tokens automatically expire after 2 hours
Token Validation
Expired or invalid tokens will be rejected by the hosted page
Users will see an error message if token validation fails
Generate a new token if the previous one expired

Token Lifecycle

Generate Token (API)
   └─> Valid for 2 hours
       └─> Redirect user to hosted page
           └─> Hosted page validates token
               ├─> Valid: User accesses funding accounts
               └─> Invalid/Expired: Error displayed

Hosted Page Features

The funding accounts hosted page provides:

Account Linking

Secure bank account selection via Plaid
Multiple account support per entity

Mandate Collection

Email address collection
Signatory name collection
Debit authorization (US ACH Debit)

Account Management

View all linked accounts
Monitor account status

Integration Flow

Typical Implementation

User Initiates Linking
User clicks "Add Bank Account" in your application
Your backend calls the token generation endpoint
You receive a token with 2-hour expiration
Redirect to Hosted Page
Redirect user to: {TREASURYPATH_HOSTED_URL}/funding-accounts?token={token}
User completes bank account linking
User provides mandate information
Account Linked
Account is created and processed
Mandate information is stored

Code Example

// Backend: Generate token
async function generateFundingAccountToken(entityId) {
  const response = await fetch('https://api.treasurypath.com/api/v1/hosted_page_tokens', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${YOUR_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entity_id: entityId,
      purpose: 'funding_accounts'
    })
  });

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

// Frontend: Redirect user
async function linkBankAccount(entityId) {
  const token = await generateFundingAccountToken(entityId);
  window.location.href = `{TREASURYPATH_HOSTED_URL}/funding-accounts?token=${token}`;
}