Create payment batch for run

POST/payroll/runs/{run_id}/payment-batches

Creates a new payment batch grouping employee net-pay disbursements for a specific payroll run. A single run may have multiple batches (e.g. separated by bank or department). Batches must be submitted to the payment processor via the /submit action.

Request

Path parameters

Name	Type	Required	Description
run_id	integer	Yes	The numeric ID of the approved payroll run to batch payments for.

Request body

Content type application/json (required).

Field	Type	Required	Description
name	string	Yes	Max length: 255
payment_method	string	Yes	One of: "bank_transfer", "mobile_money", "cheque", "cash"
bank_account_id	integer, nullable	No	ID of the employer bank account to disburse from.
employee_ids	array of integer	No	IDs of employees to include in this batch. Omit to include all employees in the run.

Example

{
  "name": "April 2026 — Main Bank Transfer",
  "payment_method": "bank_transfer",
  "bank_account_id": 3,
  "employee_ids": [
    42,
    43,
    44,
    45
  ]
}

Responses

201 Payment batch created

Content type application/json, object · PaymentBatchV1.

Field	Type	Required	Description
id	integer	No
run_id	integer	No
name	string	No
payment_method	string	No	One of: "bank_transfer", "mobile_money", "cheque", "cash"
status	string	No	One of: "draft", "submitted", "processing", "completed", "failed"
employee_count	integer, nullable	No
total_amount	number (float), nullable	No
currency	string	No	Max length: 3
created_at	string (date-time)	No

Example request

curl -X POST "https://{tenant}.faciotech.net/api/v1/payroll/runs/{run_id}/payment-batches" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name": "April 2026 — Main Bank Transfer", "payment_method": "bank_transfer", "bank_account_id": 3, "employee_ids": [42, 43, 44, 45]}'