Recipients API

The Recipients API allows you to manage recipient records and their associated bank accounts. Recipients represent entities that receive payments from your company.

Endpoints

List Recipients - GET /api/v1/companies/{company_id}/recipients
Get Recipient - GET /api/v1/companies/{company_id}/recipients/{id}
Create Recipient - POST /api/v1/companies/{company_id}/recipients
Delete Recipient - DELETE /api/v1/companies/{company_id}/recipients/{id}
Create Recipient Bank Account - POST /api/v1/companies/{company_id}/recipients/{recipient_id}/bank_accounts
Generate Bank Account Token - POST /api/v1/companies/{company_id}/entities/{entity_id}/hosted_page_tokens

List Recipients

Retrieve all active recipients for a company, including their associated bank accounts and payment profiles.

Endpoint

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

Headers

Authorization: Bearer {jwt_token}
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
`company_id`	string	Yes	Global ID of the company

Example Request

curl -X GET "https://api.treasurypath.com/api/v1/companies/Z2lkOi8vYXBwL0NvbXBhbnkvMQ/recipients" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json"

Success Response (200 OK)

{
  "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",
          "current_balance": "0.0",
          "currency": "USD",
          "last_synced_at": null,
          "owner_type": "Counterparty",
          "owner_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ",
          "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",
              "routing_number": "011401533",
              "routing_number_type": "aba",
              "bank_name": "Chase Bank",
              "payment_method": "ach",
              "created_at": "2025-01-15T11:00:00Z",
              "updated_at": "2025-01-15T11:00:00Z"
            }
          ],
          "party_address": null,
          "payment_profiles": [
            {
              "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS80NTY",
              "status": "active",
              "payment_method": "ach",
              "currency": "USD",
              "usage_type": "credit",
              "created_at": "2025-01-15T11:00:00Z",
              "updated_at": "2025-01-15T11:00:00Z"
            }
          ]
        }
      ]
    }
  ]
}

Response Fields

Field	Type	Description
`id`	string	Global ID of the recipient
`name`	string	Recipient's name
`email`	string	Recipient's email address (optional)
`created_at`	string	ISO 8601 timestamp of creation
`updated_at`	string	ISO 8601 timestamp of last update
`bank_accounts`	array	Array of bank account objects associated with this recipient

Bank Account Fields

Field	Type	Description
`id`	string	Global ID of the bank account
`current_balance`	string	Current balance as decimal string
`currency`	string	ISO 4217 currency code
`last_synced_at`	string	ISO 8601 timestamp of last sync (null if never synced)
`owner_type`	string	Type of the account owner (e.g., "Counterparty")
`owner_id`	string	Global ID of the account owner
`account_details`	array	Array of account detail objects
`routing_details`	array	Array of routing detail objects
`party_address`	object	Address information (null if not set)
`payment_profiles`	array	Array of payment profile objects

Account Detail Fields

Field	Type	Description
`id`	string	Global ID of the account detail
`account_number_mask`	string	Masked account number (e.g., "**0000")
`account_number_type`	string	Account number type (e.g., "other", "iban")

Routing Detail Fields

Field	Type	Description
`id`	string	Global ID of the routing detail
`routing_number`	string	Routing number for the payment method
`routing_number_type`	string	Type of routing number (e.g., "aba", "swift")
`bank_name`	string	Name of the bank
`payment_method`	string	Payment method for this routing (e.g., "ach", "swift")

Payment Profile Fields

Field	Type	Description
`id`	string	Global ID of the payment profile
`status`	string	Profile status (active, inactive, draft, failed)
`payment_method`	string	Payment method (ach, swift, sepa, etc.)
`currency`	string	ISO 4217 currency code
`usage_type`	string	Usage type (credit, debit, balance)

Error Responses

401 Unauthorized

{
  "errors": [
    {
      "field": "token",
      "message": "Missing or invalid token"
    }
  ]
}

404 Not Found - Company Not Found

{
  "errors": [
    {
      "field": "id",
      "message": "Company not found or not accessible in this workspace"
    }
  ]
}

Get Recipient

Retrieve detailed information about a specific recipient, including all associated bank accounts and payment profiles.

Endpoint

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

Headers

Authorization: Bearer {jwt_token}
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
`company_id`	string	Yes	Global ID of the company
`id`	string	Yes	Global ID of the recipient

Example Request

curl -X GET "https://api.treasurypath.com/api/v1/companies/Z2lkOi8vYXBwL0NvbXBhbnkvMQ/recipients/Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json"

Success Response (200 OK)

{
  "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",
        "current_balance": "0.0",
        "currency": "USD",
        "last_synced_at": null,
        "owner_type": "Counterparty",
        "owner_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ",
        "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",
            "routing_number": "011401533",
            "routing_number_type": "aba",
            "bank_name": "Chase Bank",
            "payment_method": "ach",
            "created_at": "2025-01-15T11:00:00Z",
            "updated_at": "2025-01-15T11:00:00Z"
          }
        ],
        "party_address": null,
        "payment_profiles": [
          {
            "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS80NTY",
            "status": "active",
            "payment_method": "ach",
            "currency": "USD",
            "usage_type": "credit",
            "created_at": "2025-01-15T11:00:00Z",
            "updated_at": "2025-01-15T11:00:00Z"
          }
        ]
      }
    ]
  }
}

Error Responses

401 Unauthorized

{
  "errors": [
    {
      "field": "token",
      "message": "Missing or invalid token"
    }
  ]
}

404 Not Found - Recipient Not Found

{
  "errors": [
    {
      "field": "id",
      "message": "Recipient not found or not accessible in this workspace"
    }
  ]
}

Note: This error is also returned if the recipient has been deleted or belongs to a different company.

Create Recipient

Create a new recipient record for your company.

Endpoint

POST /api/v1/companies/{company_id}/recipients

Headers

Authorization: Bearer {jwt_token}
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
`company_id`	string	Yes	Global ID of the company

Request Body

Parameter	Type	Required	Description
`name`	string	Yes	Recipient's name
`email`	string	No	Recipient's email address

Example Request

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

Success Response (201 Created)

{
  "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": []
  }
}

Error Responses

400 Bad Request - Missing Name

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

400 Bad Request - Blank Name

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

401 Unauthorized

{
  "errors": [
    {
      "field": "token",
      "message": "Missing or invalid token"
    }
  ]
}

404 Not Found - Company Not Found

{
  "errors": [
    {
      "field": "id",
      "message": "Company not found or not accessible in this workspace"
    }
  ]
}

Delete Recipient

Delete a recipient. The recipient will be marked as deleted and will no longer appear in recipient lists or be available for new payments. Historical payment data is preserved.

Endpoint

DELETE /api/v1/companies/{company_id}/recipients/{id}

Headers

Authorization: Bearer {jwt_token}

Path Parameters

Parameter	Type	Required	Description
`company_id`	string	Yes	Global ID of the company
`id`	string	Yes	Global ID of the recipient

Example Request

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

Success Response (204 No Content)

No response body. The recipient has been successfully deleted.

Error Responses

401 Unauthorized

{
  "errors": [
    {
      "field": "token",
      "message": "Missing or invalid token"
    }
  ]
}

404 Not Found - Recipient Not Found

{
  "errors": [
    {
      "field": "id",
      "message": "Recipient not found or not accessible in this workspace"
    }
  ]
}

Note: This error is also returned if: - The recipient has already been deleted - The recipient belongs to a different company - The recipient ID is invalid

Create Recipient Bank Account

Create a bank account for a recipient by providing bank details directly via the API, without using the hosted page. This is useful when you want to build your own bank account collection form.

Dynamic Form Fields

The fields required in beneficiary_details vary by country, currency, and transfer method. Use the Payment Methods API and Bank Account Requirements API to determine the required fields before calling this endpoint.

Endpoint

POST /api/v1/companies/{company_id}/recipients/{recipient_id}/bank_accounts

Headers

Authorization: Bearer {jwt_token}
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
`company_id`	string	Yes	Global ID of the company
`recipient_id`	string	Yes	Global ID of the recipient

Request Body

Parameter	Type	Required	Description
`entity_id`	string	Yes	Global ID of the entity (determines which Airwallex account is used)
`beneficiary_details`	object	Yes	Bank account details structured according to the form schema

The beneficiary_details object structure is determined by the Bank Account Requirements API. Each field's path property in the schema maps to the JSON structure of this object.

Example Request

curl -X POST "https://api.treasurypath.com/api/v1/companies/{company_id}/recipients/{recipient_id}/bank_accounts" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "{entity_id}",
    "beneficiary_details": {
      "beneficiary": {
        "entity_type": "COMPANY",
        "bank_details": {
          "account_name": "Acme Corp",
          "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"]
    }
  }'

Success Response (201 Created)

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9CYW5rQWNjb3VudC8xMjM",
    "current_balance": "0.0",
    "currency": "USD",
    "last_synced_at": null,
    "owner_type": "Counterparty",
    "owner_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ",
    "created_at": "2025-01-15T11:00:00Z",
    "updated_at": "2025-01-15T11:00:00Z",
    "account_details": [
      {
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9BY2NvdW50RGV0YWlsLzE",
        "account_number_mask": "************9012",
        "account_number_type": "other",
        "created_at": "2025-01-15T11:00:00Z",
        "updated_at": "2025-01-15T11:00:00Z"
      }
    ],
    "routing_details": [
      {
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9Sb3V0aW5nRGV0YWlsLzE",
        "routing_number": "021000021",
        "routing_number_type": "aba",
        "bank_name": null,
        "payment_method": "ach",
        "created_at": "2025-01-15T11:00:00Z",
        "updated_at": "2025-01-15T11:00:00Z"
      }
    ],
    "party_address": {
      "country_code": "US",
      "street_address": "123 Main Street",
      "city": "New York",
      "state": "NY",
      "postcode": "10001"
    },
    "payment_profiles": [
      {
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS80NTY",
        "status": "active",
        "payment_method": "ach",
        "currency": "USD",
        "usage_type": "credit",
        "created_at": "2025-01-15T11:00:00Z",
        "updated_at": "2025-01-15T11:00:00Z"
      }
    ]
  }
}

Error Responses

400 Bad Request - Missing Entity ID

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

400 Bad Request - Missing Beneficiary Details

{
  "errors": [
    {
      "field": "beneficiary_details",
      "message": "Beneficiary details are required"
    }
  ]
}

401 Unauthorized

{
  "errors": [
    {
      "field": "token",
      "message": "Missing or invalid token"
    }
  ]
}

404 Not Found - Recipient or Entity Not Found

{
  "errors": [
    {
      "field": "id",
      "message": "Recipient not found or not accessible in this workspace"
    }
  ]
}

Note: This error is returned if the recipient or entity does not exist, belongs to a different company, or the recipient has been deleted.

422 Unprocessable Entity - Validation Error

{
  "errors": [
    {
      "field": "base",
      "message": "Failed to create: invalid account details"
    }
  ]
}

Generate Bank Account Token

Generate a secure, time-limited token that allows a recipient to add their bank account information through TreasuryPath's hosted page.

Endpoint

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

Headers

Authorization: Bearer {jwt_token}
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
`company_id`	string	Yes	Global ID of the company
`entity_id`	string	Yes	Global ID of the entity

Request Body

Parameter	Type	Required	Description
`purpose`	string	Yes	Must be "recipient_add_bank_account"
`recipient_id`	string	Yes	Global ID of the recipient
`return_url`	string	No	URL to redirect the user to after completing the flow. Must match a trusted domain.

Example Request

curl -X POST "https://api.treasurypath.com/api/v1/companies/Z2lkOi8vYXBwL0NvbXBhbnkvMQ/entities/Z2lkOi8vYXBwL0VudGl0eS8x/hosted_page_tokens" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "recipient_add_bank_account",
    "recipient_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ",
    "return_url": "https://app.example.com/recipients/complete"
  }'

Success Response (201 Created)

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

return_url in response

The return_url field is only present in the response when a valid return_url was provided in the request and passed trusted domain validation.

Response Fields

Field	Type	Description
`token`	string	JWT token valid for 2 hours
`purpose`	string	Token purpose (recipient_add_bank_account)
`recipient_id`	string	Global ID of the recipient
`return_url`	string	(Optional) The validated return URL. Only present when a valid `return_url` was provided.

Token Usage

Direct users to the hosted page using the generated token:

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

Error Responses

400 Bad Request - Missing Purpose

{
  "errors": [
    {
      "field": "purpose",
      "message": "Purpose is required"
    }
  ]
}

400 Bad Request - Invalid Purpose

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

400 Bad Request - Wrong Purpose Category

{
  "errors": [
    {
      "field": "purpose",
      "message": "Purpose must be a recipient category"
    }
  ]
}

400 Bad Request - Missing Recipient ID

{
  "errors": [
    {
      "field": "recipient_id",
      "message": "Recipient ID is required"
    }
  ]
}

401 Unauthorized

{
  "errors": [
    {
      "field": "token",
      "message": "Missing or invalid token"
    }
  ]
}

404 Not Found - Recipient Not Found

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

422 Unprocessable Entity - Untrusted Return URL Domain

{
  "errors": [
    {
      "field": "return_url",
      "message": "URL domain is not in the trusted domains list"
    }
  ]
}

Resolution: Add the return URL's domain to your workspace's trusted domains configuration. See Trusted Domains.

422 Unprocessable Entity - Invalid Recipient ID Format

{
  "errors": [
    {
      "field": "recipient_id",
      "message": "Invalid recipient ID format"
    }
  ]
}

422 Unprocessable Entity - Recipient Doesn't Belong to Company

{
  "errors": [
    {
      "field": "recipient_id",
      "message": "Recipient does not belong to this company"
    }
  ]
}

422 Unprocessable Entity - Entity Doesn't Belong to Company

{
  "errors": [
    {
      "field": "entity",
      "message": "Entity does not belong to this company"
    }
  ]
}

422 Unprocessable Entity - Untrusted Return URL

{
  "errors": [
    {
      "field": "return_url",
      "message": "URL domain is not in the trusted domains list"
    }
  ]
}

Resolution: Add the return URL's domain to your workspace's trusted domains. If no trusted domains are configured, return_url is silently ignored.

Webhooks

When recipients and their bank accounts are created or modified, TreasuryPath sends webhook notifications to your configured endpoints.

BankAccount Created

Sent when a user successfully adds a bank account for a recipient through the hosted page.

{
  "event": "BankAccountEvents::CreatedEvent",
  "timestamp": 1705324800,
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9CYW5rQWNjb3VudC8xMjM",
    "current_balance": "0.0",
    "currency": "USD",
    "last_synced_at": null,
    "owner_type": "Counterparty",
    "owner_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ",
    "created_at": "2025-01-15T11:00:00.000Z",
    "updated_at": "2025-01-15T11:00:00.000Z",
    "account_details": [
      {
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9BY2NvdW50RGV0YWlsLzE",
        "account_number_mask": "************0000",
        "account_number_type": "other",
        "created_at": "2025-01-15T11:00:00.000Z",
        "updated_at": "2025-01-15T11:00:00.000Z"
      }
    ],
    "routing_details": [
      {
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9Sb3V0aW5nRGV0YWlsLzE",
        "routing_number": "011401533",
        "routing_number_type": "aba",
        "bank_name": "Chase Bank",
        "payment_method": "ach",
        "created_at": "2025-01-15T11:00:00.000Z",
        "updated_at": "2025-01-15T11:00:00.000Z"
      }
    ],
    "party_address": null,
    "payment_profiles": [
      {
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS80NTY",
        "status": "active",
        "payment_method": "ach",
        "currency": "USD",
        "usage_type": "credit",
        "created_at": "2025-01-15T11:00:00.000Z",
        "updated_at": "2025-01-15T11:00:00.000Z"
      }
    ]
  }
}

PaymentProfile Created

Sent when a payment profile is created for a recipient's bank account.

{
  "event": "PaymentProfileEvents::CreatedEvent",
  "timestamp": 1705324800,
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS80NTY",
    "status": "active",
    "payment_method": "ach",
    "currency": "USD",
    "usage_type": "credit",
    "created_at": "2025-01-15T11:00:00.000Z",
    "updated_at": "2025-01-15T11:00:00.000Z"
  }
}

For more information about webhooks, see the Webhooks Reference.

Common Workflows

Option A: Collecting Bank Account via API

Use this approach when you want to build your own bank account form.

Create the recipient

POST /api/v1/companies/{company_id}/recipients

Get available payment methods

GET /api/v1/payment_methods?country_code=US&currency_code=USD&entity_type=COMPANY

Get form schema for the selected payment method
```
POST /api/v1/bank_account_requirements
```
Render form and collect bank details from user

Create the bank account

POST /api/v1/companies/{company_id}/recipients/{recipient_id}/bank_accounts

Create payments using the payment profile

POST /api/v1/companies/{company_id}/payments

Option B: Collecting Bank Account via Hosted Page

Use this approach when you prefer TreasuryPath's pre-built hosted page.

Create the recipient

POST /api/v1/companies/{company_id}/recipients

Generate a bank account token

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

Direct users to hosted page

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

Receive webhook notifications
BankAccountEvents::CreatedEvent
PaymentProfileEvents::CreatedEvent

Retrieve updated recipient details

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

Create payments using the payment profile

POST /api/v1/companies/{company_id}/payments

Deleting an Inactive Recipient

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

The recipient is marked as deleted and will no longer: - Appear in recipient lists - Be available for new payments - Be accessible via the GET endpoint

Historical payment data remains preserved for record-keeping.

Best Practices

Recipient Creation

Descriptive Names: Use clear, descriptive names for easy identification
Optional Email: Email is not required and can be reused across recipients
Store IDs: Save the recipient id returned on creation for future operations

Token Generation

Just-in-Time: Generate tokens only when needed
Short Lifespan: Tokens expire after 2 hours
One-Time Use: Generate fresh tokens for each bank account addition session
Secure Transmission: Always use HTTPS when transmitting tokens

Payment Profile Usage

Active Status: Only use payment profiles with active status
Currency Matching: Ensure payment currency matches profile currency
Usage Type: Use credit type profiles as to_profile_id when sending payments to recipients
Automatic Selection: TreasuryPath automatically determines the best payment method for each bank account

Webhook Integration

Event Handling: Implement handlers for BankAccountEvents::CreatedEvent and PaymentProfileEvents::CreatedEvent
Idempotency: Design webhook handlers to be idempotent
Signature Verification: Always verify webhook signatures
Error Handling: Implement retry logic for failed webhook processing

Add Your First Recipient - Complete guide to working with recipients
Bank Accounts Data Model - Understanding bank account structure
Payments API - Creating payments to recipients
Webhooks Reference - Setting up and handling webhooks