Skip to content

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 add a recipient's bank account via the API (Option A)
  • How to add a recipient's bank account via the hosted page (Option B)
  • How to receive webhook notifications when bank accounts are added
  • How to verify recipient payment profiles

Prerequisites

Before adding recipients:

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
  • Two Ways to Add Bank Accounts: Via the API with your own form, or via the 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

There are two ways to add a recipient's bank account:

Option A: Via API - You build the form, collect details, and submit directly through the API.

shape: sequence_diagram

"Your\nApplication"
"TreasuryPath\nAPI"
"User"

# Step 1: Create Recipient
"Your\nApplication" -> "TreasuryPath\nAPI": 1. Create recipient\n(POST /recipients)
"TreasuryPath\nAPI" -> "Your\nApplication": Recipient created

# Step 2: Get payment methods & schema
"Your\nApplication" -> "TreasuryPath\nAPI": 2. Get payment methods\n& form schema
"TreasuryPath\nAPI" -> "Your\nApplication": Dynamic form fields

# Step 3: Collect bank details
"Your\nApplication" -> "User": 3. Show bank account form
"User" -> "Your\nApplication": Enter bank details

# Step 4: Create bank account
"Your\nApplication" -> "TreasuryPath\nAPI": 4. Create bank account\n(POST /recipients/{id}/bank_accounts)
"TreasuryPath\nAPI" -> "Your\nApplication": Bank account created\nwith payment profiles

Option B: Via Hosted Page - TreasuryPath handles the form through a secure hosted page.

YourApplicationTreasuryPathAPIUserTreasuryPathHosted Page 1. Create recipient(POST /recipients) Recipient created 2. Generate bank account token(POST /hosted_page_tokens) Return token(valid 2 hours) 3. Redirect to hosted page Access bank account form 4. Enter recipient'sbank account details Create bank accountand payment profile 5. Webhook(BankAccount::CreatedEvent) 6. Webhook(PaymentProfile::CreatedEvent) Bank account added
YourApplicationTreasuryPathAPIUserTreasuryPathHosted Page 1. Create recipient(POST /recipients) Recipient created 2. Generate bank account token(POST /hosted_page_tokens) Return token(valid 2 hours) 3. Redirect to hosted page Access bank account form 4. Enter recipient'sbank account details Create bank accountand payment profile 5. Webhook(BankAccount::CreatedEvent) 6. Webhook(PaymentProfile::CreatedEvent) Bank account added

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 the next steps.

Adding Bank Account Details

There are two ways to collect a recipient's bank account information:

  • Option A: Via API - Build your own form using the dynamic schema from TreasuryPath
  • Option B: Via Hosted Page - Use TreasuryPath's pre-built hosted page

Option A: Add Bank Account via API

Use this approach when you want full control over the bank account collection UI.

Step A1: Get Available Payment Methods

curl -X GET "https://api.treasurypath.com/api/v1/payment_methods?country_code=US&currency_code=USD&entity_type=COMPANY" \
  -H "Authorization: Bearer {your_jwt_token}" \
  -H "Content-Type: application/json"

This returns the available transfer methods (e.g., LOCAL, SWIFT) and their clearing systems (e.g., ACH, FEDWIRE).

Step A2: Get Form Schema

Fetch the required form fields for the selected payment method:

curl -X POST "https://api.treasurypath.com/api/v1/bank_account_requirements" \
  -H "Authorization: Bearer {your_jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "US",
    "currency_code": "USD",
    "entity_type": "COMPANY",
    "transfer_method": "LOCAL",
    "local_clearing_system": "ACH"
  }'

The response contains a fields array. Each field has a path property that defines where the value should be placed in the request body. Use these fields to render your form.

Handling Dynamic Fields

Some fields have "refresh": true. When the user changes the value of a refresh field, call this endpoint again with the updated values to get the correct field set.

Step A3: Create Bank Account

After collecting form data from the user, map the values using the path from the schema and send:

curl -X POST "https://api.treasurypath.com/api/v1/companies/{company_id}/recipients/{recipient_id}/bank_accounts" \
  -H "Authorization: Bearer {your_jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "{entity_id}",
    "beneficiary_details": {
      "beneficiary": {
        "entity_type": "COMPANY",
        "bank_details": {
          "account_name": "Acme Supplies Inc.",
          "account_number": "123456789012",
          "bank_country_code": "US",
          "account_currency": "USD",
          "local_clearing_system": "ACH",
          "account_routing_type1": "aba",
          "account_routing_value1": "021000021"
        },
        "address": {
          "country_code": "US",
          "street_address": "123 Main Street",
          "city": "New York",
          "state": "NY",
          "postcode": "10001"
        }
      },
      "transfer_methods": ["LOCAL"]
    }
  }'

Replace:

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

The response returns the created bank account with its payment profiles. You can immediately use the payment profile ID to create payments.

Entity ID

The entity_id determines which Airwallex account is used to create the beneficiary. If your company has multiple entities, choose the correct one.

For detailed schema documentation, see the Bank Account Requirements API Reference.

Option B: Add Bank Account via Hosted Page

Use this approach when you prefer TreasuryPath's pre-built, secure hosted page for collecting bank details.

Step B1: 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",
    "return_url": "https://yourapp.com/recipients/bank-account/complete"
  }'

Replace:

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

Return URL (Optional)

You can include an optional return_url parameter to redirect users back to your application after they complete the hosted page flow. The URL's domain must be listed in your workspace's trusted domains configuration. If no trusted domain config exists, the parameter is silently ignored.

Success Response

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJjb21wYW55X2lkIjoiZ2lkOi8vYXBwL0NvbXBhbnkvMSIsImVudGl0eV9pZCI6ImdpZDovL2FwcC9FbnRpdHkvMTIzIiwicHVycG9zZSI6InJlY2lwaWVudF9hZGRfYmFua19hY2NvdW50IiwicmVjaXBpZW50X2lkIjoiZ2lkOi8vYXBwL0NvdW50ZXJwYXJ0eS8xIiwiZXhwIjoxNzA5ODUxMjAwfQ.abc123",
    "purpose": "recipient_add_bank_account",
    "recipient_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ",
    "return_url": "https://yourapp.com/recipients/bank-account/complete"
  }
}

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 B2: 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 B3: User Adds Recipient Bank Account

On the hosted page, users will:

  1. View a Secure Form - Pre-filled with the recipient's name and email
  2. Enter the Recipient's Bank Account Details:
  3. Submit Information - Securely stored by TreasuryPath
  4. 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 B4: 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.

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:

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

API Reference

For complete API documentation, see:

Need Help?

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