Payments API

The Payments API allows you to create, retrieve, and manage payment instructions. Payment instructions represent requests to transfer money between payment profiles.

Endpoints

Create Payment - POST /api/v1/companies/{company_id}/payments
Get Payment - GET /api/v1/companies/{company_id}/payments/{id}
List Payments - GET /api/v1/companies/{company_id}/payments

Create Payment

Create a new payment instruction.

Endpoint

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

Headers

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

Request Body

{
  "payment_instruction": {
    "payment_quote_id": "string",
    "reason": "string",
    "idempotency_key": "string",
    "credit_note": "string",
    "debit_note": "string",
    "payment_batch_id": "string"
  }
}

Parameters

Parameter	Type	Required	Description
`payment_quote_id`	string	Yes	ID of the payment quote to execute
`reason`	string	Yes	Reason for the payment
`idempotency_key`	string	Yes	A unique key to prevent duplicate payment submissions
`credit_note`	string	No	Note or reference for the credit side of the payment
`debit_note`	string	No	Note or reference for the debit side of the payment
`payment_batch_id`	string	No	ID of a payment batch to add this payment to (see Payment Batches). The batch must be in `building` status and not exceed 500 payments. When set, the payment is held until the batch is processed. Expired quotes are refreshed automatically during batch processing.

Example Request

curl -X POST "https://api.treasurypath.com/api/v1/companies/comp_1234567890abcdef/payments" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_instruction": {
      "payment_quote_id": "quote_abc123def456",
      "reason": "Invoice payment",
      "idempotency_key": "unique-payment-12345-abcdef",
      "credit_note": "Invoice INV-2025-001 payment",
      "debit_note": "Payment to Supplier ABC Corp"
    }
  }'

Success Response (201 Created)

{
  "data": {
    "created_at": "2025-09-05T00:08:34.382Z",
    "from_profile": {
      "created_at": "2025-08-29T23:57:21.855Z",
      "currency": "USD",
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8x",
      "payment_method": "ach",
      "status": "active",
      "updated_at": "2025-08-29T23:57:21.855Z",
      "usage_type": "debit"
    },
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50SW5zdHJ1Y3Rpb24vOQ",
    "instructed_amount": "1000.0",
    "instructed_amount_currency": "USD",
    "quote_id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UXVvdGUvMTA",
    "reason": "transfer_to_own_account",
    "status": "pending",
    "credit_note": "Invoice INV-2025-001 payment",
    "debit_note": "Payment to Supplier ABC Corp",
    "to_profile": {
      "created_at": "2025-08-29T23:57:21.915Z",
      "currency": "USD",
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8z",
      "payment_method": "balance",
      "status": "active",
      "updated_at": "2025-08-29T23:57:21.915Z",
      "usage_type": "internal_account"
    },
    "updated_at": "2025-09-05T00:08:34.382Z"
  }
}

Error Responses

400 Bad Request - Missing company_id

{
  "errors": [
    {
      "field": "company_id",
      "message": "Company ID is required"
    }
  ]
}

422 Unprocessable Entity - Missing Idempotency Key

{
  "errors": [
    {
      "field": "idempotency_key",
      "message": "Idempotency key is required"
    }
  ]
}

422 Unprocessable Entity - Validation Error

{
  "errors": [
    {
      "field": "instructed_amount",
      "message": "Instructed amount must be greater than zero"
    }
  ]
}

Get Payment

Retrieve a specific payment instruction.

Endpoint

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

Headers

Authorization: Bearer {jwt_token}

Example Request

curl -X GET "https://api.treasurypath.com/api/v1/companies/comp_1234567890abcdef/payments/pi_1234567890abcdef" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "data": {
    "created_at": "2025-09-05T00:08:34.382Z",
    "from_profile": {
      "created_at": "2025-08-29T23:57:21.855Z",
      "currency": "USD",
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8x",
      "payment_method": "ach",
      "status": "active",
      "updated_at": "2025-08-29T23:57:21.855Z",
      "usage_type": "debit"
    },
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50SW5zdHJ1Y3Rpb24vOQ",
    "idempotency_key": "1",
    "instructed_amount": "1000.0",
    "instructed_amount_currency": "USD",
    "quote_id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UXVvdGUvMTA",
    "reason": "transfer_to_own_account",
    "status": "pending",
    "credit_note": "Invoice INV-2025-001 payment",
    "debit_note": "Payment to Supplier ABC Corp",
    "to_profile": {
      "created_at": "2025-08-29T23:57:21.915Z",
      "currency": "USD",
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8z",
      "payment_method": "balance",
      "status": "active",
      "updated_at": "2025-08-29T23:57:21.915Z",
      "usage_type": "internal_account"
    },
    "updated_at": "2025-09-05T00:08:34.382Z"
  }
}

Error Response (404 Not Found)

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

List Payments

Retrieve a list of payment instructions with optional filtering.

Endpoint

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

Headers

Authorization: Bearer {jwt_token}

Path Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`per_page`	integer	No	Items per page (default: 25)

Example Request

curl -X GET "https://api.treasurypath.com/api/v1/companies/comp_1234567890abcdef/payments?status=completed&page=1&per_page=10" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "data": [
    {
      "created_at": "2025-09-05T00:08:34.382Z",
      "from_profile": {
        "created_at": "2025-08-29T23:57:21.855Z",
        "currency": "USD",
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8x",
        "payment_method": "ach",
        "status": "active",
        "updated_at": "2025-08-29T23:57:21.855Z",
        "usage_type": "debit"
      },
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50SW5zdHJ1Y3Rpb24vOQ",
      "idempotency_key": "1",
      "instructed_amount": "1000.0",
      "instructed_amount_currency": "USD",
      "quote_id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UXVvdGUvMTA",
      "reason": "transfer_to_own_account",
      "status": "pending",
      "credit_note": "Invoice INV-2025-001 payment",
      "debit_note": "Payment to Supplier ABC Corp",
      "to_profile": {
        "created_at": "2025-08-29T23:57:21.915Z",
        "currency": "USD",
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8z",
        "payment_method": "balance",
        "status": "active",
        "updated_at": "2025-08-29T23:57:21.915Z",
        "usage_type": "internal_account"
      },
      "updated_at": "2025-09-05T00:08:34.382Z"
    },
    {
      "created_at": "2025-09-05T00:04:55.740Z",
      "from_profile": {
        "created_at": "2025-08-29T23:57:21.855Z",
        "currency": "USD",
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8x",
        "payment_method": "ach",
        "status": "active",
        "updated_at": "2025-08-29T23:57:21.855Z",
        "usage_type": "debit"
      },
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50SW5zdHJ1Y3Rpb24vNw",
      "idempotency_key": null,
      "instructed_amount": "1000.0",
      "instructed_amount_currency": "USD",
      "quote_id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UXVvdGUvOQ",
      "reason": "transfer_to_own_account",
      "status": "pending",
      "to_profile": {
        "created_at": "2025-08-29T23:57:21.915Z",
        "currency": "USD",
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8z",
        "payment_method": "balance",
        "status": "active",
        "updated_at": "2025-08-29T23:57:21.915Z",
        "usage_type": "internal_account"
      },
      "updated_at": "2025-09-05T00:04:55.740Z"
    },
    {
      "created_at": "2025-09-05T00:04:54.031Z",
      "from_profile": {
        "created_at": "2025-08-29T23:57:21.855Z",
        "currency": "USD",
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8x",
        "payment_method": "ach",
        "status": "active",
        "updated_at": "2025-08-29T23:57:21.855Z",
        "usage_type": "debit"
      },
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50SW5zdHJ1Y3Rpb24vNg",
      "idempotency_key": null,
      "instructed_amount": "1000.0",
      "instructed_amount_currency": "USD",
      "quote_id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UXVvdGUvOQ",
      "reason": "transfer_to_own_account",
      "status": "pending",
      "to_profile": {
        "created_at": "2025-08-29T23:57:21.915Z",
        "currency": "USD",
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8z",
        "payment_method": "balance",
        "status": "active",
        "updated_at": "2025-08-29T23:57:21.915Z",
        "usage_type": "internal_account"
      },
      "updated_at": "2025-09-05T00:04:54.031Z"
    },
    {
      "created_at": "2025-09-04T23:59:08.326Z",
      "from_profile": {
        "created_at": "2025-08-29T23:57:21.855Z",
        "currency": "USD",
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8x",
        "payment_method": "ach",
        "status": "active",
        "updated_at": "2025-08-29T23:57:21.855Z",
        "usage_type": "debit"
      },
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50SW5zdHJ1Y3Rpb24vNQ",
      "idempotency_key": null,
      "instructed_amount": "1000.0",
      "instructed_amount_currency": "USD",
      "quote_id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UXVvdGUvOQ",
      "reason": "transfer_to_own_account",
      "status": "pending",
      "to_profile": {
        "created_at": "2025-08-29T23:57:21.915Z",
        "currency": "USD",
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8z",
        "payment_method": "balance",
        "status": "active",
        "updated_at": "2025-08-29T23:57:21.915Z",
        "usage_type": "internal_account"
      },
      "updated_at": "2025-09-04T23:59:08.326Z"
    },
    {
      "created_at": "2025-09-04T23:51:11.286Z",
      "from_profile": {
        "created_at": "2025-08-29T23:57:21.855Z",
        "currency": "USD",
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8x",
        "payment_method": "ach",
        "status": "active",
        "updated_at": "2025-08-29T23:57:21.855Z",
        "usage_type": "debit"
      },
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50SW5zdHJ1Y3Rpb24vNA",
      "idempotency_key": null,
      "instructed_amount": "1000.0",
      "instructed_amount_currency": "USD",
      "quote_id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UXVvdGUvOQ",
      "reason": "transfer_to_own_account",
      "status": "pending",
      "to_profile": {
        "created_at": "2025-08-29T23:57:21.915Z",
        "currency": "USD",
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8z",
        "payment_method": "balance",
        "status": "active",
        "updated_at": "2025-08-29T23:57:21.915Z",
        "usage_type": "internal_account"
      },
      "updated_at": "2025-09-04T23:51:11.286Z"
    },
    {
      "created_at": "2025-09-04T21:46:20.282Z",
      "from_profile": {
        "created_at": "2025-08-29T23:57:21.855Z",
        "currency": "USD",
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8x",
        "payment_method": "ach",
        "status": "active",
        "updated_at": "2025-08-29T23:57:21.855Z",
        "usage_type": "debit"
      },
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50SW5zdHJ1Y3Rpb24vMg",
      "idempotency_key": null,
      "instructed_amount": "1000.0",
      "instructed_amount_currency": "USD",
      "quote_id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UXVvdGUvMg",
      "reason": "transfer_to_own_account",
      "status": "pending",
      "to_profile": {
        "created_at": "2025-08-29T23:57:21.915Z",
        "currency": "USD",
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8z",
        "payment_method": "balance",
        "status": "active",
        "updated_at": "2025-08-29T23:57:21.915Z",
        "usage_type": "internal_account"
      },
      "updated_at": "2025-09-04T21:46:20.282Z"
    },
    {
      "created_at": "2025-09-03T19:25:16.907Z",
      "from_profile": {
        "created_at": "2025-08-29T23:57:21.855Z",
        "currency": "USD",
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8x",
        "payment_method": "ach",
        "status": "active",
        "updated_at": "2025-08-29T23:57:21.855Z",
        "usage_type": "debit"
      },
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50SW5zdHJ1Y3Rpb24vMQ",
      "idempotency_key": null,
      "instructed_amount": "1.0",
      "instructed_amount_currency": "USD",
      "quote_id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UXVvdGUvMQ",
      "reason": "transfer_to_own_account",
      "status": "pending",
      "to_profile": {
        "created_at": "2025-08-29T23:57:21.915Z",
        "currency": "USD",
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8z",
        "payment_method": "balance",
        "status": "active",
        "updated_at": "2025-08-29T23:57:21.915Z",
        "usage_type": "internal_account"
      },
      "updated_at": "2025-09-03T19:25:16.907Z"
    }
  ],
  "meta": {
    "total_records": 7,
    "total_pages": 1,
    "current_page": 1,
    "per_page": 20
  },
  "links": {
    "first": "https://api.tpathdemo.com/api/v1/companies/comp_1234567890abcdef/payments?page=1&per_page=20",
    "prev": null,
    "next": null,
    "last": "https://api.tpathdemo.com/api/v1/companies/comp_1234567890abcdef/payments?page=1&per_page=20"
  }
}

Reason Values

When creating payments, you must specify a reason value. This is a requirement from our banking partners.

For detailed guidance on choosing the right reason code, see the Payment Reason Codes Reference.

Code	Description
`audio_visual_services`	Audio visual services
`bill_payment`	Bill payment
`business_expenses`	Business expenses
`construction`	Construction
`donation_charitable_contribution`	Donation or charitable contribution
`education_training`	Education or training
`freight`	Freight
`goods_purchased`	Goods purchased
`investment_capital`	Investment capital
`investment_proceeds`	Investment proceeds
`living_expenses`	Living expenses
`loan_credit_repayment`	Loan or credit repayment
`medical_services`	Medical services
`pension`	Pension
`professional_business_services`	Professional business services
`real_estate`	Real estate
`taxes`	Taxes
`technical_services`	Technical services
`transfer_to_own_account`	Transfer to own account
`travel`	Travel
`wages_salary`	Wages or salary
`other_services`	Other services

Status Values

Payment instructions can have the following statuses:

pending: Payment has been created but not yet processed
processing: Payment is being processed
completed: Payment has been successfully completed
failed: Payment has failed
cancelled: Payment has been cancelled

Error Handling

All endpoints return consistent error responses. Common error scenarios:

401 Unauthorized: Invalid or missing JWT token
403 Forbidden: Insufficient permissions
404 Not Found: Payment instruction not found
422 Unprocessable Entity: Validation errors
500 Internal Server Error: Server error

Rate Limiting

Payment creation is subject to rate limiting to prevent abuse. If you exceed the rate limit, you'll receive a 429 Too Many Requests response.