Payment Batches API

The Payment Batches API allows you to group multiple payment instructions into a single batch for processing. This is useful when submitting large numbers of payments (e.g., payroll, vendor disbursements) to avoid API rate limiting and receive a single completion notification instead of individual notifications per payment.

Endpoints

Create Payment Batch - POST /api/v1/companies/{company_id}/payment_batches
Get Payment Batch - GET /api/v1/companies/{company_id}/payment_batches/{id}
List Payment Batches - GET /api/v1/companies/{company_id}/payment_batches
Process Payment Batch - POST /api/v1/companies/{company_id}/payment_batches/{id}/process_batch

Create Payment Batch

Create a new payment batch. The batch starts in building status, allowing you to add payment instructions to it before processing.

Endpoint

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

Headers

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

Request Body

{
  "payment_batch": {
    "idempotency_key": "string",
    "label": "string",
    "metadata": {}
  }
}

Parameters

Parameter	Type	Required	Description
`idempotency_key`	string	No	A unique key to prevent duplicate batch creation
`label`	string	No	A human-readable label for the batch (e.g., "January Payroll")
`metadata`	object	No	Arbitrary key-value pairs for your own tracking purposes

Example Request

curl -X POST "https://api.treasurypath.com/api/v1/companies/comp_1234567890abcdef/payment_batches" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_batch": {
      "idempotency_key": "payroll-2026-01",
      "label": "January 2026 Payroll",
      "metadata": {
        "department": "engineering",
        "period": "2026-01"
      }
    }
  }'

Success Response (201 Created)

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50QmF0Y2gvMQ",
    "status": "building",
    "label": "January 2026 Payroll",
    "idempotency_key": "payroll-2026-01",
    "total_count": 0,
    "succeeded_count": 0,
    "failed_count": 0,
    "metadata": {
      "department": "engineering",
      "period": "2026-01"
    },
    "submitted_at": null,
    "completed_at": null,
    "created_at": "2026-01-15T10:30:00.000Z",
    "updated_at": "2026-01-15T10:30:00.000Z"
  }
}

Idempotent Behavior (200 OK)

If you create a batch with an idempotency_key that already exists for your company, the existing batch is returned with a 200 OK status instead of creating a duplicate.

Error Responses

422 Unprocessable Entity - Validation Error

{
  "errors": [
    {
      "field": "idempotency_key",
      "message": "has already been taken"
    }
  ]
}

Get Payment Batch

Retrieve the details of a specific payment batch.

Endpoint

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

Headers

Authorization: Bearer {jwt_token}

Example Request

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

Success Response (200 OK)

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50QmF0Y2gvMQ",
    "status": "completed",
    "label": "January 2026 Payroll",
    "idempotency_key": "payroll-2026-01",
    "total_count": 50,
    "succeeded_count": 49,
    "failed_count": 1,
    "metadata": {
      "department": "engineering",
      "period": "2026-01"
    },
    "submitted_at": "2026-01-15T11:00:00.000Z",
    "completed_at": "2026-01-15T11:05:30.000Z",
    "created_at": "2026-01-15T10:30:00.000Z",
    "updated_at": "2026-01-15T11:05:30.000Z"
  }
}

Error Response (404 Not Found)

{
  "errors": [
    {
      "field": "id",
      "message": "PaymentBatch not found"
    }
  ]
}

List Payment Batches

Retrieve a paginated list of payment batches for your company, with optional filtering.

Endpoint

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

Headers

Authorization: Bearer {jwt_token}

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by status (e.g., `building`, `completed`)
`from_date`	string	No	Filter batches created on or after this date (YYYY-MM-DD)
`to_date`	string	No	Filter batches created on or before this date (YYYY-MM-DD)
`page`	integer	No	Page number (default: 1)
`per_page`	integer	No	Items per page (default: 20)

Example Request

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

Success Response (200 OK)

{
  "data": [
    {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50QmF0Y2gvMg",
      "status": "completed",
      "label": "February 2026 Payroll",
      "idempotency_key": "payroll-2026-02",
      "total_count": 48,
      "succeeded_count": 48,
      "failed_count": 0,
      "metadata": {},
      "submitted_at": "2026-02-15T11:00:00.000Z",
      "completed_at": "2026-02-15T11:04:15.000Z",
      "created_at": "2026-02-15T10:30:00.000Z",
      "updated_at": "2026-02-15T11:04:15.000Z"
    },
    {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50QmF0Y2gvMQ",
      "status": "completed",
      "label": "January 2026 Payroll",
      "idempotency_key": "payroll-2026-01",
      "total_count": 50,
      "succeeded_count": 49,
      "failed_count": 1,
      "metadata": {
        "department": "engineering",
        "period": "2026-01"
      },
      "submitted_at": "2026-01-15T11:00:00.000Z",
      "completed_at": "2026-01-15T11:05:30.000Z",
      "created_at": "2026-01-15T10:30:00.000Z",
      "updated_at": "2026-01-15T11:05:30.000Z"
    }
  ],
  "meta": {
    "total_records": 2,
    "total_pages": 1,
    "current_page": 1,
    "per_page": 20
  },
  "links": {
    "first": "https://api.tpathdemo.com/api/v1/companies/comp_1234567890abcdef/payment_batches?page=1&per_page=20",
    "prev": null,
    "next": null,
    "last": "https://api.tpathdemo.com/api/v1/companies/comp_1234567890abcdef/payment_batches?page=1&per_page=20"
  }
}

Process Payment Batch

Submit a batch for processing. This transitions the batch from building to processing status and begins executing all payment instructions in the batch with rate-limited concurrency.

Endpoint

POST /api/v1/companies/{company_id}/payment_batches/{id}/process_batch

Headers

Authorization: Bearer {jwt_token}

Prerequisites

The batch must meet all of the following conditions:

Status is building
Contains at least one payment instruction
Contains no more than 500 payment instructions

Example Request

curl -X POST "https://api.treasurypath.com/api/v1/companies/comp_1234567890abcdef/payment_batches/Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50QmF0Y2gvMQ/process_batch" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (202 Accepted)

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50QmF0Y2gvMQ",
    "status": "processing",
    "label": "January 2026 Payroll",
    "idempotency_key": "payroll-2026-01",
    "total_count": 50,
    "succeeded_count": 0,
    "failed_count": 0,
    "metadata": {
      "department": "engineering",
      "period": "2026-01"
    },
    "submitted_at": "2026-01-15T11:00:00.000Z",
    "completed_at": null,
    "created_at": "2026-01-15T10:30:00.000Z",
    "updated_at": "2026-01-15T11:00:00.000Z"
  }
}

Error Responses

422 Unprocessable Entity - Not in Building Status

{
  "errors": [
    {
      "field": "status",
      "message": "Batch is not in building status"
    }
  ]
}

422 Unprocessable Entity - Empty Batch

{
  "errors": [
    {
      "field": "status",
      "message": "Batch has no payment instructions"
    }
  ]
}

422 Unprocessable Entity - Exceeds Maximum

{
  "errors": [
    {
      "field": "status",
      "message": "Batch exceeds maximum of 500 payments"
    }
  ]
}

409 Conflict - Already Being Processed

{
  "errors": [
    {
      "field": "status",
      "message": "Batch is already being processed"
    }
  ]
}

Batch Lifecycle

The typical workflow for using payment batches:

Create a batch — POST /payment_batches with an optional label and idempotency key
Add payments — POST /payments with payment_batch_id set to the batch ID (repeat for each payment)
Submit the batch — POST /payment_batches/{id}/process_batch to begin processing
Monitor progress — GET /payment_batches/{id} to check status and counts
Receive notification — A single digest notification is sent when all payments in the batch complete

Batched Payments

When creating payments with a payment_batch_id, the payment is not executed immediately. Instead, it is held in the batch until the batch is processed. Expired quotes are automatically refreshed during batch processing.

Batch Expiry

Batches left in building status for more than 7 days are automatically expired by the system cleanup process.

Error Handling

All endpoints return consistent error responses. Common error scenarios:

400 Bad Request: Invalid date format in filter parameters
401 Unauthorized: Invalid or missing JWT token
404 Not Found: Payment batch not found or not accessible
409 Conflict: Concurrent processing attempt
422 Unprocessable Entity: Validation errors
500 Internal Server Error: Server error