Quick Start

This guide will walk you through the basics of using the TreasuryPath API, from authentication to making your first payment.

Payment Flow Overview

The following diagram illustrates the high-level payment flow from your application's perspective:

Prerequisites

Before you begin, you'll need:

• A TreasuryPath workspace account
• API credentials (key and secret) from your workspace settings
• A development environment capable of making HTTP requests

Step 1: Authentication

The TreasuryPath API uses JWT (JSON Web Token) authentication. You'll need to exchange your API credentials for a JWT token.

Get Your API Credentials

1. Log into your TreasuryPath workspace
2. Navigate to Settings → API Keys
3. Create a new API key if you don't have one
4. Copy your API key and secret (the secret is only shown once)

Exchange Credentials for JWT Token

curl -X POST https://api.treasurypath.com/api/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "tp_key_1234567890abcdef",
    "api_secret": "tp_secret_abcdef1234567890"
  }'

Response:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Use the JWT Token

Include the JWT token in the Authorization header for all subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Step 2: Set Up Your Company

Before you can make payments, you'll need a company in TreasuryPath. A company is the top-level organization that holds bank accounts and manages payments.

If you already have a company set up through the TreasuryPath dashboard, you can skip to Step 3: Enable Multi-Currency. Otherwise, you can create one via the API.

List Existing Companies

First, check if you already have companies in your workspace:

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

Create a Company (If Needed)

curl -X POST https://api.treasurypath.com/api/v1/companies \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "default_currency": "USD",
    "country": "US"
  }'

Response:

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE",
    "name": "Acme Corporation",
    "country": "US",
    "default_currency": "USD",
    …
  }
}

Important: Save the id from this response - you'll need it for all subsequent API calls as {company_id}.

List Existing Entities

Check if your company already has entities:

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

Create an Entity (If Needed)

Entities represent organizational units within your company (like subsidiaries or branches). Your company must have an entity to use the features provided by TreasuryPath. If your company doesn't have one yet, create it:

curl -X POST https://api.treasurypath.com/api/v1/companies/{company_id}/entities \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation LLC",
    "country_alpha2": "US"
  }'

Response:

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHkvMQ",
    "name": "Acme Corporation LLC",
    "country_alpha2": "US",
    …
  }
}

Note: Currently, each company can have only one active entity.

Step 3: Enable Multi-Currency

To make payments through TreasuryPath, you need bank accounts with payment profiles. For US entities, you can enable multi-currency.

Enable Multi-Currency Account 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 {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "feature_identifier": "multi_currency_account"
  }'

Response:

{
  "data": {
    "application_id": "Z2lkOi8vYXBwL0FwcGxpY2F0aW9uLzEyMw",
    "status": "CREATED",
    …
  }
}

Important: Save the application_id from this response - you'll need it for the next step.

Generate Onboarding Token

To complete the multi-currency account setup, generate a token that allows the account holder to complete KYC verification:

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

Response:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "purpose": "onboarding",
    …
  }
}

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

Once the user completes onboarding and the feature status becomes ACTIVE, managed bank accounts will be automatically created for your entity.

Step 4: Link Funding Accounts

To enable debit transactions from external US bank accounts, you need to link funding accounts. These are external bank accounts (like your business checking account) that can be used as funding sources for payments.

Generate Funding Account Token

Generate a token to allow users to access the funding accounts management page:

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

Response:

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

Important: The token is valid for 2 hours.

Access the Hosted Page

Direct your user to complete the linking process:

{TREASURYPATH_HOSTED_URL}/funding-accounts?token={token}

On the hosted page, users can:

• View all linked funding accounts with account details and connection status
• Add new funding accounts by connecting their bank through Plaid and providing mandate information (email and signatory name)
• Remove funding accounts that have no pending or processing payments

Note: Multiple funding accounts can be linked to provide flexibility in funding sources.

Verify Linked Accounts

After linking, the funding accounts will appear in your bank accounts list with usage_type: "debit" payment profiles:

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

You can then use these payment profiles as the from_profile_id when creating payments.

Step 5: Add a Recipient

Before making a payment, you need to create a recipient (the payee who will receive the payment) and add their bank account information.

Create Recipient Record

curl -X POST https://api.treasurypath.com/api/v1/companies/{company_id}/recipients \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Supplies Inc.",
    "email": "accounts@acmesupplies.com"
  }'

Response:

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ",
    "name": "Acme Supplies Inc.",
    "email": "accounts@acmesupplies.com",
    "bank_accounts": [],
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Important: Save the recipient id for the next step.

Add Recipient Bank Account

Generate a token to collect the recipient's bank account information through the hosted page:

curl -X POST https://api.treasurypath.com/api/v1/companies/{company_id}/entities/{entity_id}/hosted_page_tokens \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "recipient_add_bank_account",
    "recipient_id": "{recipient_id}"
  }'

Response:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "purpose": "recipient_add_bank_account",
    "recipient_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ"
  }
}

Direct your user to the hosted page to add the recipient's bank account details:

{TREASURYPATH_HOSTED_URL}/recipient/add-bank-account?token={token}

Once the bank account is added, payment profiles with usage_type: "credit" will be automatically created for the recipient.

List Bank Accounts

Now that you've set up funding accounts and recipient accounts, list all bank accounts to get the payment profile IDs you'll need for creating payments:

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

Response:

{
  "data": [
    {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9CYW5rQWNjb3VudC82NQ",
      "currency": "USD",
      "owner_id": "Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHkvMTc",
      "owner_type": "Entity",
      "account_details": […],
      "routing_details": […],
      "payment_profiles": [
        {
          "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS81",
          "status": "active",
          "currency": "USD",
          "payment_method": "ach",
          "usage_type": "debit",
          …
        }
      ],
      …
    },
    {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9CYW5rQWNjb3VudC82Ng",
      "currency": "USD",
      "owner_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ",
      "owner_type": "Counterparty",
      "account_details": […],
      "routing_details": […],
      "payment_profiles": [
        {
          "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS83",
          "status": "active",
          "currency": "USD",
          "payment_method": "ach",
          "usage_type": "credit",
          …
        }
      ],
      …
    }
  ]
}

Understanding the Response:

This response includes all bank accounts associated with your company:

• Funding accounts (from Step 4) with usage_type: "debit" - used as the source for sending payments
• Recipient accounts (from Step 5) with usage_type: "credit" - used as the destination for receiving payments
• Managed accounts (from Step 3) with usage_type: "balance" - TreasuryPath-managed accounts that can send or receive payments

Save the payment profile IDs, you'll use them in the next step to create a payment.

Step 6: Create Your First Payment

Now that you have payment profiles from both funding accounts and recipient accounts, you can create a payment.

From the bank accounts list in Step 5, you'll need: - A source payment profile ID (usage_type: "debit") from your funding account - A destination payment profile ID (usage_type: "credit") from the recipient's bank account

Get a Quote

Before creating a payment, get a quote using payment profile IDs:

curl -X POST https://api.treasurypath.com/api/v1/companies/{company_id}/quotes \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "quote": {
      "from_profile_id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS81",
      "to_profile_id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS83",
      "instructed_amount": {
        "amount": 1000.00,
        "currency": "USD"
      }
    }
  }'

Response:

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UXVvdGUvMQ",
    "expires_at": "2025-01-15T15:39:23.897Z",
    "instructed_amount": "1000.0",
    "instructed_amount_currency": "USD",
    "fee": "0.0",
    "exchange_rate": "1.0",
    "expected_completion_date": "2025-01-16",
    "from_profile": {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS81",
      "usage_type": "debit",
      …
    },
    "to_profile": {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS83",
      "usage_type": "credit",
      …
    },
    …
  }
}

Important: Store the quote id to use when creating the payment. Quotes expire after 15 minutes (see expires_at).

Create the Payment

Using the quote ID from the response, create your payment:

curl -X POST https://api.treasurypath.com/api/v1/companies/{company_id}/payments \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_instruction": {
      "payment_quote_id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UXVvdGUvMQ",
      "reason": "business_expenses",
      "idempotency_key": "unique-payment-12345-abcdef",
      "credit_note": "Invoice #1234 payment",
      "debit_note": "Payment for services"
    }
  }'

Response:

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50SW5zdHJ1Y3Rpb24vMQ",
    "quote_id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UXVvdGUvMQ",
    "status": "pending",
    "instructed_amount": "1000.0",
    "instructed_amount_currency": "USD",
    "from_profile": {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS81",
      "usage_type": "debit",
      …
    },
    "to_profile": {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS83",
      "usage_type": "credit",
      …
    },
    …
  }
}

Important: Save the payment id to track the payment status. The payment status will change from pending to processing and then to completed or failed.

The reason field is required - use business_expenses for general business payments. See the Payment Reason Codes Reference for all available options.

Step 7: Set Up Webhooks (Optional)

TreasuryPath uses webhooks to notify your application about events that happen in your account. Instead of polling the API to check for status changes, webhooks allow you to receive real-time notifications when important events occur.

Why Use Webhooks?

Webhooks eliminate the need to manually check resource statuses by automatically notifying you when:

• Payment events - Get notified about payment lifecycle changes
• Payment profile events - Receive notifications about payment profile changes
• Multi-currency account events - Get updates on account application and activation status
• Bank account events - Be notified about bank account changes and linking activities
• Additional resource events - TreasuryPath provides comprehensive webhook coverage for all platform resources

Configure Webhook Endpoints

Create a webhook endpoint to start receiving event notifications:

curl -X POST https://api.treasurypath.com/api/v1/webhook_endpoints \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/treasurypath",
    "events": [
      "PaymentEvents::CompletedEvent",
      "PaymentEvents::FailedEvent",
      "PaymentProfileEvents::CreatedEvent",
      "BankAccountEvents::CreatedEvent"
    ]
  }'

Important: Your webhook endpoint must:

• Be accessible via HTTPS
• Return a 2xx status code to acknowledge receipt
• Process events asynchronously to avoid timeouts

For detailed information on available webhook events, payload structures, and security best practices, see the Webhooks Guide.

Step 8: Track Payment Status

Get Payment Details

You can check the current status of a payment at any time:

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

Note: If you've set up webhooks in Step 7, you'll automatically receive notifications when payment statuses change, eliminating the need to poll this endpoint.

Next Steps

Now that you've completed the basic setup and made your first payment, here are some recommended next steps:

• Webhooks - Set up real-time notifications for payment status changes
• Payment Methods - Learn about ACH, Wire, and other payment options
• Error Handling - Handle API errors gracefully

Testing with Postman

Want to test the API without writing code? Use our complete Postman collection:

• Download Postman Collection - Includes all endpoints and environments (Local, Sandbox, Production)

API Reference

For detailed API documentation on the endpoints used in this guide:

• Authentication API
• Companies API
• Entities API
• Recipients API
• Payments API

Need Help?

• Check our FAQ
• Contact support at support@treasurypath.com
• Join our developer community on Discord