Skip to content

Payment Profile

A Payment Profile represents a payment capability associated with a bank account. Payment profiles define how a bank account can be used for sending or receiving payments, including the payment method, currency, and usage type.

Payment Profile Object

{
  "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8x",
  "status": "active",
  "currency": "USD",
  "payment_method": "ach",
  "usage_type": "debit",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

Attributes

Attribute Type Description
id string Unique identifier for the payment profile
status string Status of the payment profile: draft, active, inactive, failed, deleted
currency string ISO 4217 three-letter currency code (e.g., "USD", "EUR")
payment_method string Payment method (see Payment Methods)
usage_type string How the profile can be used: debit, credit, internal_account
created_at string ISO 8601 timestamp when the profile was created
updated_at string ISO 8601 timestamp when the profile was last updated

Payment Profile Status

Payment profiles can have the following statuses:

Status Description Can Be Used for Payments?
draft Payment profile is created but not yet active (pending verification) ❌ No
active Payment profile is fully operational and ready to use ✅ Yes
inactive Payment profile is temporarily inactive but can be reactivated by customer ❌ No
failed Payment profile verification failed (hard failure, cannot be activated) ❌ No
deleted Payment profile has been deleted or removed ❌ No

Status Transitions

  • draft → active: Verification successful
  • draft → failed: Verification failed
  • active → inactive: Customer deactivated or temporary restriction
  • active/inactive → deleted: Profile deleted

Usage Types

Payment profiles indicate how a bank account can be used:

Usage Type Description Use Case
debit Can be used to send payments Debit funds from this account to pay recipients
credit Can be used to receive payments Credit funds to this account from payers
internal_account Internal account for balance management Used for internal transfers and balance operations

Usage Type Combinations

A single bank account may have multiple payment profiles with different usage types. For example, a bank account might have both a debit profile for sending payments and a credit profile for receiving payments.

Relationship to Bank Accounts

Payment profiles are always associated with a bank account and are returned as part of the bank account object. They cannot be created, updated, or deleted independently—they are managed through bank account operations and integrations.

To view payment profiles: - Use the List Bank Accounts endpoint - Use the Get Bank Account endpoint

The response will include a payment_profiles array containing all payment profiles for that bank account.

Webhook Notifications

TreasuryPath sends webhook notifications when payment profile events occur. Subscribe to these events to receive real-time updates about payment profile changes.

Available Payment Profile Events

Event Name Description Trigger
PaymentProfileEvents::CreatedEvent Triggered when a payment profile is created A new payment capability is added to a bank account
PaymentProfileEvents::FailedEvent Triggered when a payment profile fails A payment profile becomes unable to be used for payments

Webhook Payload

All payment profile webhooks follow the standard TreasuryPath webhook payload format:

{
  "event": "PaymentProfileEvents::CreatedEvent",
  "timestamp": "2025-01-17T14:30:00.000Z",
  "company_id": "Z2lkOi8vYXBwL0NvbXBhbnkvMTIz",
  "resource_id": "Z2lkOi8vYXBwL1BheW1lbnRQcm9maWxlLzQ1Ng",
  "actor_id": null
}

Payload Fields

Field Type Description
event string Event type identifier (e.g., PaymentProfileEvents::CreatedEvent)
timestamp string ISO 8601 timestamp when the event occurred
company_id string ID of the company that owns the bank account
resource_id string ID of the payment profile that triggered the event
actor_id string/null ID of the user or API credential that triggered the action, or null for system-triggered events

Handling Webhook Events

Scenario 1: Payment Profile Created

Sent when a new payment capability is added to a bank account.

Webhook payload includes: "event": "PaymentProfileEvents::CreatedEvent"

When this occurs:

  • Multi-currency account activation completes
  • New payment method becomes available for the account
  • Payment capability is verified and activated

Recommended action:

  1. Fetch the parent bank account details to see the new payment profile
  2. Update available payment methods for this account
  3. Enable payment features in your UI

Scenario 2: Payment Profile Failed

Sent when a payment profile becomes unusable.

Webhook payload includes: "event": "PaymentProfileEvents::FailedEvent"

Common causes:

  • Verification failure
  • Account restrictions imposed by provider
  • Compliance issues

Recommended action:

  1. Disable payment features for this profile
  2. Notify the customer to resolve the issue
  3. Provide guidance on re-activating the profile

Fetching Payment Profile Details

Webhook payloads contain minimal information. Payment profiles are nested within bank accounts, so you need to fetch the parent bank account to get complete payment profile details:

GET /api/v1/companies/{company_id}/bank_accounts/{bank_account_id}

The response includes the full bank account object with all payment profiles in the payment_profiles array.

Webhook Best Practices

  • Always Fetch Full Details - Webhook payloads are intentionally minimal. Fetch the parent bank account to see complete payment profile information
  • 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 Failed Profiles - Payment profile failures may require customer action. Implement monitoring and alerting for PaymentProfileEvents::FailedEvent

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

Usage Notes

  • Read-Only - Payment profiles cannot be created, updated, or deleted directly via the API
  • Automatic Creation - Payment profiles are automatically created when:
    • Multi-currency account is activated
    • Bank account is connected via integration
    • Payment capabilities are verified by the payment provider
  • Status-Based Availability - Only active payment profiles can be used for creating payments
  • Multiple Profiles - A bank account may have multiple payment profiles to support different payment methods and usage types
  • Terminal Failed State - Payment profiles in failed status cannot be reactivated and require a new payment profile to be created

For information about the bank accounts that contain payment profiles, see Bank Account.