Add Your First Recipient

This guide walks you through adding a recipient (payee) to your TreasuryPath account and collecting their bank account information securely. Recipients represent vendors, contractors, or any entity that receives payments from your company.

What You'll Learn

How to create a recipient record
How to generate a secure token for adding bank account details
How to direct users to add recipient bank account details through the hosted page
How to receive webhook notifications when bank accounts are added
How to verify recipient payment profiles

Prerequisites

Before adding recipients:

✅ Company and entity created (see Setup Your Organization)
✅ A valid JWT token (see Authentication)
✅ Company ID and Entity ID from your organization setup

Understanding Recipients

Recipients (also called counterparties or payees) are entities that receive payments from your company.

Key Features

Recipient Records: Store basic information (name, email) about your payees
Multiple Bank Accounts: Each recipient can have multiple bank accounts
Secure Entry: Bank account details are entered through the secure hosted page
Payment Profiles: Automatically created with usage_type: "credit" for receiving payments
Webhook Notifications: Real-time updates when bank accounts are added

How It Works

Step 1: Create a Recipient

Create a recipient record in your company with basic information.

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

Replace:

{company_id} - Your company ID
{your_jwt_token} - Your JWT authentication token

Request Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Recipient's legal or display name
`email`	string	No	Recipient's contact email address

Success 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"
  }
}

Save the Recipient ID

Copy and save the id field from the data object - you'll need this recipient_id for generating the bank account token in the next step.

Step 2: Generate Bank Account Token

Generate a token to allow users to access the hosted page for adding the recipient's bank account information.

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 '{
    "purpose": "recipient_add_bank_account",
    "recipient_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ"
  }'

Replace:

{company_id} - Your company ID
{entity_id} - Your entity ID
{recipient_id} - The recipient ID from Step 1

Success Response

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

Token Expiration

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

What the Token Grants

Access: Limited to adding bank account information for the specified recipient
Scope: Users can enter the recipient's bank details securely
Security: Single-purpose token that cannot be reused for other operations

Step 3: Direct User to Hosted Page

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

Construct the URL

{TREASURYPATH_HOSTED_URL}/recipient/add-bank-account?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/recipient/add-bank-account?token=eyJhbGciOiJIUzI1NiJ9...

Production:

https://app.treasurypath.com/hosted/recipient/add-bank-account?token=eyJhbGciOiJIUzI1NiJ9...

Step 4: User Adds Recipient Bank Account

On the hosted page, users will:

View a Secure Form - Pre-filled with the recipient's name and email
Enter the Recipient's Bank Account Details:
Submit Information - Securely stored by TreasuryPath
View Confirmation - Bank account successfully added

Security

All bank account information is encrypted
Data is transmitted over HTTPS
TreasuryPath complies with financial data security standards
Account numbers are masked in API responses

Step 5: Receive Webhook Notifications

When a user successfully adds the recipient's bank account, TreasuryPath automatically creates the bank account and payment profile(s), then sends webhook notifications to your application.

Bank Account Created Webhook

Event Type: BankAccountEvents::CreatedEvent

This webhook notifies you that a new bank account has been created for the recipient.

Payment Profile Created Webhook

Event Type: PaymentProfileEvents::CreatedEvent

This webhook notifies you that payment profile(s) have been created for the bank account. These profiles have usage_type: "credit" (can receive payments).

Setting Up Webhooks

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

Step 6: Verify Recipient Bank Accounts

After receiving webhook notifications (or if webhooks aren't configured), you can verify the recipient's bank accounts and payment profiles.

Get Recipient Details

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

Example Response

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ",
    "name": "Acme Supplies Inc.",
    "email": "accounts@acmesupplies.com",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z",
    "bank_accounts": [
      {
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9CYW5rQWNjb3VudC8xMjM",
        "currency": "USD",
        "current_balance": "0.0",
        "owner_type": "Counterparty",
        "owner_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ",
        "account_details": [
          {
            "account_number_mask": "************0000",
            "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": "credit"
          }
        ]
      }
    ]
  }
}

Important Fields

bank_accounts: Array of bank accounts added for the recipient
payment_profiles: Payment profiles with usage_type: "credit" (can receive payments)
status: "active": Profile is ready to use for payments
account_number_mask: Masked account number for security (full number never exposed)

Using Recipients in Payments

When creating payment quotes, use the payment profile ID from a recipient's bank account with usage_type: "credit" as your to_profile_id.

Common Errors

Missing Recipient Name

{
  "errors": [
    {
      "field": "name",
      "message": "Name is required"
    }
  ]
}

Solution: Include the name field in your request body when creating a recipient.

Invalid Recipient ID

{
  "errors": [
    {
      "field": "recipient_id",
      "message": "Recipient not found"
    }
  ]
}

Solution: Verify you're using the correct recipient_id from the recipient creation response.

Token Expired (User-facing)

If users encounter a token expiration error on the hosted page:

Solution: Generate a new token and provide the updated link to users.

Best Practices

Recipient Management

✅ Use descriptive names for easy identification (e.g., "Acme Supplies Inc." not "Vendor 1")
✅ Use valid email addresses for communication and support
✅ Store recipient IDs in your system for future reference
✅ Keep recipient information up to date

Token Management

✅ Generate tokens just-in-time before directing users
✅ Include clear instructions and support information with the link
✅ Be prepared to regenerate tokens if they expire
✅ Never expose tokens in public channels

Communication

✅ Explain to users why recipient bank account information is needed
✅ Reassure users about security measures
✅ Provide a support contact for questions
✅ Set expectations for when payments will begin
✅ Follow up if bank accounts haven't been added

Security

✅ Verify webhook signatures to ensure authenticity
✅ Use HTTPS for all communications
✅ Never request bank account information outside the hosted page
✅ Monitor for suspicious recipient creation patterns

What's Next?

Once recipients have been added with their bank account details, you can:

Make Your First Payment - Create payments to your recipients
List Recipients - View all recipients and their bank accounts
Delete Recipients - Remove recipients that are no longer needed
Manage Multiple Bank Accounts - Recipients can add additional bank accounts

API Reference

For complete API documentation, see:

Recipients API Reference - Full endpoint documentation
Recipient Data Model - Detailed property descriptions
Payment Profiles Data Model - Understanding payment profiles

Need Help?

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