Connect Funding Accounts

This guide walks you through connecting external bank accounts as funding sources for your entity. Funding accounts allow you to debit money from external US bank accounts to fund your TreasuryPath payments.

What You'll Learn

• How to generate a funding account token
• How to direct users to link their bank accounts
• How to verify linked funding accounts
• How funding accounts work with payment profiles

Prerequisites

Before connecting funding accounts:

• ✅ Company and entity created (see Setup Your Organization)
• ✅ Multi-currency feature enabled and ACTIVE (see Enable Multi-Currency)
• ✅ A valid JWT token (see Authentication)
• ✅ Entity ID from your organization setup

Multi-Currency Required

Funding accounts can only be linked to entities that have an active multi-currency account. Make sure you've completed the multi-currency enablement process first.

Understanding Funding Accounts

Funding Accounts are external US bank accounts (like your business checking account) that you link to TreasuryPath to use as funding sources for payments.

Key Features

• Multiple Accounts: Link multiple funding accounts for flexibility
• Secure Connection: Accounts are linked through secure bank connection
• Debit Mandates: Each account requires mandate information (email and signatory)
• Debit Profiles: Linked accounts appear with usage_type: "debit" payment profiles

How It Works

Step 1: Generate Funding Account Token

Create a secure, short-lived token that grants access to the funding accounts hosted page.

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

Replace:

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

Success Response

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

Token Expiration

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

What the Token Grants

• Access: Limited to funding account operations for the specified entity
• Scope: Users can view, add, and remove funding accounts
• Security: Single-purpose token that cannot be reused for other features

Step 2: Direct User to Hosted Page

Redirect your end user to TreasuryPath's hosted funding accounts page with the generated token.

Construct the URL

{TREASURYPATH_HOSTED_URL}/funding-accounts?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/funding-accounts?token=eyJhbGciOiJIUzI1NiJ9...

Production:

https://app.treasurypath.com/hosted/funding-accounts?token=eyJhbGciOiJIUzI1NiJ9...

Step 3: User Links Bank Account

On the hosted page, the user can perform several actions:

View Linked Accounts

The hosted page displays:

• All currently linked funding accounts
• Account details (masked account number, bank name)
• Connection status

Add New Funding Account

The user can link a new bank account by:

1. Click "Add Funding Account"
2. Connect Bank Account - Securely connect their bank account
3. Provide Mandate Information:
4. Email: Contact email for the account holder
5. Signatory Name: Name of the person authorizing debit transactions

Debit Mandate

The mandate information authorizes TreasuryPath to initiate debit transactions from the linked account according to your terms of service. This is required for compliance and regulatory purposes.

Remove Funding Account

Users can remove funding accounts that:

• Have no pending payments
• Have no processing payments

Accounts with active or pending payments cannot be removed until those payments are completed.

Step 4: Receive Webhook Notification

When a user successfully links a funding account, TreasuryPath automatically creates a bank account and sends a webhook notification to your application.

Bank Account Created Webhook

You'll receive a webhook event notifying you that a new bank account has been created:

Event Type: BankAccount::CreatedEvent (or similar - check your webhook documentation)

This webhook allows you to:

• Track when funding accounts are successfully linked
• Update your application's UI in real-time
• Store the bank account ID for future reference

Setting Up Webhooks

Make sure you have webhooks configured to receive these notifications. See the Webhooks Guide for setup instructions.

Step 5: Verify Linked Accounts

After receiving the webhook notification (or if webhooks aren't configured), you can verify linked accounts through the Bank Accounts API.

List Bank Accounts

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

Identify Funding Accounts

Funding accounts will have payment profiles with:

• usage_type: "debit" - Indicates the account can be used to send money
• status: "active" - Ready to use for payments
• Account details - Masked account number and routing information

Example Response

{
  "data": [
    {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9CYW5rQWNjb3VudC8xMjM",
      "account_name": "Business Checking",
      "current_balance_cents": null,
      "current_balance_currency": "USD",
      "account_details": [
        {
          "account_number_mask": "************4567",
          "account_number_type": "other"
        }
      ],
      "routing_details": [
        {
          "bank_name": "Chase Bank",
          "routing_number": "011401533",
          "routing_number_type": "aba",
          "payment_method": "ach"
        }
      ],
      "payment_profiles": [
        {
          "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS80NTY",
          "status": "active",
          "currency": "USD",
          "payment_method": "ach",
          "usage_type": "debit"
        }
      ]
    }
  ]
}

Using Funding Accounts in Payments

When creating payment quotes, use the payment profile ID from a funding account with usage_type: "debit" as your from_profile_id.

Common Errors

Multi-Currency Account Not Found

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

Solution: Complete the multi-currency enablement process and ensure the feature status is ACTIVE before attempting to link funding accounts.

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 the entity exists in your workspace.

Invalid Purpose

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

Solution: Ensure you're using "funding_accounts" exactly as the purpose value.

Missing Entity ID

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

Solution: Include the entity_id field in your request body.

Expired Token (User-facing)

If the user sees a token expiration error on the hosted page:

Solution: Generate a new token and provide the updated URL to the user.

Best Practices

Token Management

• ✅ Generate tokens just-in-time before redirecting users
• ✅ Don't store tokens long-term (they expire in 2 hours)
• ✅ Use HTTPS for all token transmissions
• ✅ Never expose tokens in logs or client-side code

User Experience

• ✅ Explain why mandate information is required (compliance and authorization)
• ✅ Allow users to link multiple funding accounts for flexibility
• ✅ Clearly indicate which accounts can be removed (no pending/processing payments)
• ✅ Provide support contact information during the linking process

Security

• ✅ Validate that the multi-currency feature is active before generating tokens
• ✅ Implement proper error handling for failed token generation
• ✅ Verify linked accounts through the API after the user completes the process
• ✅ Monitor for suspicious account linking patterns

Integration

• ✅ Save payment profile IDs with usage_type: "debit" for use in payment creation
• ✅ Allow users to view their linked accounts in your application
• ✅ Handle cases where users need to re-link accounts (e.g., after bank credential changes)

What's Next?

Once you've linked funding accounts, you can:

1. Add Recipients - Set up payment recipients
2. Make Payments - Create payments using your funding accounts
3. View Bank Accounts - Check all linked accounts and their payment profiles
4. Manage Accounts - Allow users to add or remove funding accounts as needed

API Reference

For complete API documentation, see:

• Funding Account Tokens API Reference - Full endpoint documentation
• Bank Accounts API Reference - View and manage accounts
• Payment Profiles Data Model - Understanding payment profiles

Need Help?

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