Skip to content

Recipient

A Recipient represents a counterparty (payee) that receives payments from your company. Recipients can be vendors, contractors, service providers, or any entity to which your company makes payments.

Recipient Object

{
  "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_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ",
      "owner_type": "Counterparty",
      "last_synced_at": null,
      "party_address": null,
      "created_at": "2025-01-15T11:00:00Z",
      "updated_at": "2025-01-15T11:00:00Z",
      "account_details": [
        {
          "id": "Z2lkOi8vd2FsbGV0LWFwcC9BY2NvdW50RGV0YWlsLzE",
          "account_number_mask": "************0000",
          "account_number_type": "other",
          "created_at": "2025-01-15T11:00:00Z",
          "updated_at": "2025-01-15T11:00:00Z"
        }
      ],
      "routing_details": [
        {
          "id": "Z2lkOi8vd2FsbGV0LWFwcC9Sb3V0aW5nRGV0YWlsLzE",
          "bank_name": "Chase Bank",
          "routing_number": "011401533",
          "routing_number_type": "aba",
          "payment_method": "ach",
          "created_at": "2025-01-15T11:00:00Z",
          "updated_at": "2025-01-15T11:00:00Z"
        }
      ],
      "payment_profiles": [
        {
          "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS80NTY",
          "status": "active",
          "currency": "USD",
          "payment_method": "ach",
          "usage_type": "credit",
          "created_at": "2025-01-15T11:00:00Z",
          "updated_at": "2025-01-15T11:00:00Z"
        }
      ]
    }
  ]
}

Attributes

Attribute Type Description
id string Unique identifier for the recipient
name string Recipient's name (required)
email string/null Recipient's email address (optional, can be reused across recipients)
created_at string ISO 8601 timestamp when the recipient was created
updated_at string ISO 8601 timestamp when the recipient was last updated
bank_accounts array Array of bank account objects associated with this recipient (see Bank Account)

Bank Accounts

Recipients can have multiple bank accounts associated with their profile. Each bank account includes:

  • Account Details - Masked account numbers and account types
  • Routing Details - Bank routing information for payment processing
  • Payment Profiles - Payment capabilities for sending payments to the recipient

For complete details on bank account structure, see Bank Account.

Available Operations

  • List Recipients - Returns all active recipients for a company
  • Get Recipient - Retrieve details of a specific recipient by ID
  • Create Recipient - Create a new recipient record
  • Delete Recipient - Mark a recipient as deleted
  • Generate Bank Account Token - Create authentication token for hosted page access to add recipient bank accounts

Using Hosted Pages

The hosted page provides a secure, pre-built interface for adding recipient bank account information. Your users can add bank account details for recipients through this interface, ensuring sensitive banking data never touches your servers while providing automatic validation and compliance.

Integration Flow

The following sequence diagram shows the interaction flow for adding a recipient's bank account:

ClientApplicationTreasuryPathAPIEndUserTreasuryPathHosted Page Create Recipient (POST /recipients) Recipient created Generate bank account token Return authentication token Redirect to hosted page Enter recipient's bank account info Submit bank account data Webhook (BankAccountEvents::CreatedEvent) Webhook (PaymentProfileEvents::CreatedEvent)
ClientApplicationTreasuryPathAPIEndUserTreasuryPathHosted Page Create Recipient (POST /recipients) Recipient created Generate bank account token Return authentication token Redirect to hosted page Enter recipient's bank account info Submit bank account data Webhook (BankAccountEvents::CreatedEvent) Webhook (PaymentProfileEvents::CreatedEvent)

Step-by-step breakdown:

  1. Create Recipient - Client application creates the recipient record
  2. Generate Token - Generate bank account token for hosted page authentication
  3. User Adds Bank Account - User enters recipient's bank account information via hosted page
  4. Webhooks - Bank account and payment profile are created, triggering webhook notifications

Token Generation

To generate a token for adding recipient bank account information:

Endpoint: 

POST /api/v1/companies/{company_id}/entities/{entity_id}/hosted_page_tokens

Request Body: 

{
  "purpose": "recipient_add_bank_account",
  "recipient_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ"
}

Response: 

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

Direct your user to: {TREASURYPATH_HOSTED_URL}/hosted/recipient/add-bank-account?token={token}

Note: {TREASURYPATH_HOSTED_URL} is the hosted page URL for your environment. See Introduction for environment URLs.

Token Properties

  • Validity: Tokens expire after 2 hours
  • One-Time Use: Generate fresh tokens for each bank account addition session
  • Secure: Tokens securely encode company, entity, and recipient information
  • HTTPS Only: Always transmit tokens over secure connections

Hosted Page Features

  • Secure Data Collection - Banking information never touches your servers
  • Automatic Validation - Form validation and error handling built-in
  • Responsive Design - Works across desktop and mobile devices
  • Compliance - Built-in compliance with banking regulations
  • Automatic Payment Method Selection - TreasuryPath determines the best payment method based on bank account details

Webhook Notifications

TreasuryPath sends webhook notifications when recipient-related events occur. This allows your application to respond to changes in real-time without polling the API.

Available Events

When a recipient's bank account is added through the hosted page, the following webhooks are triggered:

Event Name Description Trigger
BankAccountEvents::CreatedEvent Triggered when a bank account is created Bank account successfully added via hosted page
PaymentProfileEvents::CreatedEvent Triggered when a payment profile is created Payment capabilities are activated for the bank account

Webhook Payload

Bank account and payment profile webhooks follow the standard TreasuryPath webhook payload format. For detailed webhook payload structure and handling instructions, see:

Handling Webhook Events

Scenario 1: Bank Account Added

Sent when a recipient's bank account is successfully added via the hosted page.

Webhook received: BankAccountEvents::CreatedEvent

Recommended action:

  1. Fetch the updated recipient details to see the new bank account
  2. Update your local database with the bank account information
  3. Enable payment features for this recipient

Scenario 2: Payment Profile Created

Sent when payment capabilities are activated for the recipient's bank account.

Webhook received: PaymentProfileEvents::CreatedEvent

Recommended action:

  1. Verify the payment profile status is active
  2. Store the payment profile ID for creating payments
  3. Enable payment creation in your UI

Fetching Recipient Details

Webhook payloads contain minimal information. To get complete recipient details after receiving a webhook:

GET /api/v1/companies/{company_id}/recipients/{recipient_id}

The response includes the full recipient object with all bank accounts and payment profiles.

Webhook Best Practices

  • Always Fetch Full Details - Webhook payloads are intentionally minimal. Fetch the complete recipient details using the API
  • Handle Idempotency - Use the combination of event + resource_id + timestamp to detect duplicate webhooks
  • Respond Quickly - Return a 200 OK response within 30 seconds
  • Verify Signatures - Always verify the TreasuryPath-Signature header to ensure webhook authenticity
  • Monitor Bank Account Creation - Implement monitoring for successful bank account additions

For webhook setup, security, and signature verification, see Webhooks.

Usage Notes

  • Email Optional - Email addresses are not required and can be reused across multiple recipients
  • Read-Only Bank Accounts - Bank accounts cannot be created or modified directly via API. They are created through the hosted page flow
  • Active Status Only - Deleted recipients will not appear in list endpoints and cannot be used for new payments
  • Historical Data Preserved - Deleting a recipient preserves historical payment data for record-keeping
  • Multiple Bank Accounts - Recipients can have multiple bank accounts, each with their own payment profiles
  • Automatic Payment Method Selection - TreasuryPath automatically determines the best payment method based on bank account routing information

For detailed API endpoints and request/response examples, see the Recipients API Reference.