Skip to content

Payment

A Payment represents a request to transfer money between two payment profiles. Payments are created based on quotes and include information about the amount, source, destination, and payment reason.

Payment Object

{
  "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50SW5zdHJ1Y3Rpb24vMQ",
  "created_at": "2025-01-17T10:30:00.286Z",
  "updated_at": "2025-01-17T10:30:00.286Z",
  "instructed_amount": "1000.0",
  "instructed_amount_currency": "USD",
  "quote_id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UXVvdGUvMQ",
  "reason": "bill_payment",
  "status": "pending",
  "idempotency_key": "c8bc0fca-d5dd-44ba-a9e1-af4951d89eae",
  "from_profile": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS81",
    "status": "active",
    "currency": "USD",
    "payment_method": "ach",
    "usage_type": "debit",
    "created_at": "2025-01-15T10:00:00.104Z",
    "updated_at": "2025-01-15T10:00:00.104Z"
  },
  "to_profile": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS83",
    "status": "active",
    "currency": "USD",
    "payment_method": "ach",
    "usage_type": "credit",
    "created_at": "2025-01-15T12:00:00.835Z",
    "updated_at": "2025-01-15T12:00:00.835Z"
  }
}

Attributes

Attribute Type Description
id string Unique identifier for the payment
created_at string ISO 8601 timestamp when the payment was created
updated_at string ISO 8601 timestamp when the payment was last updated
instructed_amount string Payment amount as decimal string
instructed_amount_currency string ISO 4217 three-letter currency code of the payment
quote_id string ID of the quote used to create this payment (see Quote)
reason string Payment reason code (see Payment Reason Codes)
status string Current status of the payment (see Payment Statuses)
idempotency_key string Unique key to prevent duplicate payment submissions
from_profile object Source payment profile details (see Payment Profile)
to_profile object Destination payment profile details (see Payment Profile)

Payment Statuses

Payments progress through different statuses during their lifecycle:

Status Description
pending Payment has been created but not yet processed
processing Payment is being processed by the payment network
completed Payment has been successfully completed
failed Payment has failed and will not be processed

Terminal Statuses

completed and failed are terminal statuses. Payments in these statuses cannot change state.

Payment Lifecycle

Payments follow a defined lifecycle from creation to completion:

  1. Creation - Payment is created based on a valid quote
  2. Pending - Payment is queued for processing
  3. Processing - Payment is being processed by the payment network
  4. Terminal State - Payment reaches a final status (completed or failed)

Payment Reasons

When creating a payment, you must specify a reason code. This is a regulatory requirement from banking partners and helps categorize the purpose of the payment.

Common reason codes include:

  • bill_payment - Utilities, rent, subscriptions
  • business_expenses - General operational costs
  • goods_purchased - Inventory and product purchases
  • professional_business_services - Legal, accounting, consulting
  • transfer_to_own_account - Internal transfers
  • wages_salary - Employee compensation

For the complete list of payment reason codes and usage guidelines, see Payment Reason Codes.

Idempotency

The idempotency_key parameter ensures that duplicate payment submissions are prevented. If you submit multiple payment requests with the same idempotency key:

  • The first request creates the payment
  • Subsequent requests with the same key return the existing payment
  • Idempotency keys are scoped to your company

Idempotency Requirement

The idempotency_key is required when creating payments. Always use a unique, random value for each distinct payment to prevent accidental duplicates.

Available Operations

  • Create Payment - Create a new payment based on a quote
  • Get Payment - Retrieve details of a specific payment
  • List Payments - Retrieve all payments for a company with optional filtering

Read-Only After Creation

Payments cannot be updated after creation.

Webhook Notifications

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

Available Payment Events

Event Name Description Trigger
PaymentEvents::CompletedEvent Triggered when a payment is completed Payment successfully processed and funds transferred
PaymentEvents::FailedEvent Triggered when a payment fails Payment processing failed due to insufficient funds, invalid account, or other errors
PaymentEvents::DebitInitiatedEvent Triggered when a debit payment order is initiated Payment order with debit direction begins processing

Webhook Payload

All payment webhooks follow the standard TreasuryPath webhook payload format:

{
  "event": "PaymentEvents::CompletedEvent",
  "timestamp": "2025-01-17T14:30:00.000Z",
  "company_id": "Z2lkOi8vYXBwL0NvbXBhbnkvMTIz",
  "resource_id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50SW5zdHJ1Y3Rpb24vNDU2",
  "actor_id": "Z2lkOi8vYXBwL1VzZXIvNzg5"
}

Payload Fields

Field Type Description
event string Event type identifier (e.g., PaymentEvents::CompletedEvent)
timestamp string ISO 8601 timestamp when the event occurred
company_id string ID of the company that owns the payment
resource_id string ID of the payment 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 Completed

Sent when a payment successfully completes.

Webhook payload includes: "event": "PaymentEvents::CompletedEvent"

Recommended action:

  1. Fetch the full payment details to confirm completion
  2. Update your internal records to reflect successful payment
  3. Notify relevant parties (e.g., send confirmation email)
  4. Update invoice or order status to paid

Scenario 2: Payment Failed

Sent when a payment fails to process.

Webhook payload includes: "event": "PaymentEvents::FailedEvent"

Common causes:

  • Insufficient funds in source account
  • Invalid or closed destination account
  • Payment network errors
  • Compliance or fraud checks

Recommended action:

  1. Fetch the payment details to understand failure reason
  2. Notify the payer about the failure
  3. Provide guidance on resolving the issue
  4. Consider creating a new payment if needed

Scenario 3: Debit Initiated

Sent when a debit payment order begins processing.

Webhook payload includes: "event": "PaymentEvents::DebitInitiatedEvent"

Recommended action:

  1. Record the debit initiation
  2. Update payment tracking status
  3. Prepare for completion or failure webhooks

Fetching Payment Details

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

GET /api/v1/companies/{company_id}/payments/{resource_id}

The response includes the full payment object with all details including payment profiles, quote information, and current status.

Webhook Best Practices

  • Always Fetch Full Details - Webhook payloads are intentionally minimal. Fetch the complete payment 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 Failed Payments - Payment failures may require customer action. Implement monitoring and alerting for PaymentEvents::FailedEvent

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

Usage Notes

  • Quote Required - All payments must be created from a valid quote. The quote must not be expired (15 minute validity)
  • Idempotency Key Required - Always provide a unique idempotency_key to prevent duplicate payments
  • Reason Code Required - A valid payment reason code must be specified
  • Profile Status - Both source and destination payment profiles must have active status
  • Single Use Quote - Each quote can only be used once to create a payment
  • Read-Only - Payments cannot be updated after creation
  • Terminal States - Payments in completed or failed status cannot change state

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