PayrollBatches

Create Payroll Batches

Submit a batch of payouts to multiple recipients. Mazad atomically reserves the total amount and processes each transfer individually.

Create a batch

Submit a new payroll batch with a list of recipients and amounts.

POST/payroll/batches

Create and submit a new payroll batch. The total amount is reserved atomically from your merchant wallet.

Request body

Name	Type	Required	Description
currency	string	required	ISO 4217 currency code for all payouts in this batch.
description	string	optional	Internal description for this batch (e.g., "March 2025 Salaries").
recipients	array	required	Array of recipient objects. Minimum 1, maximum 500 per batch.
recipients[].customer_id	string	required	The Mazad customer ID of the recipient.
recipients[].amount	integer	required	Payout amount in smallest currency unit.
recipients[].note	string	optional	Optional note visible to the recipient in their transaction history.

curl -X POST https://wallet.e-mazad.store/api/v1/payroll/batches \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "IQD",
    "description": "March 2025 Salaries",
    "recipients": [
      {
        "customer_id": "cust_emp001",
        "amount": 500000,
        "note": "March salary - Engineering"
      },
      {
        "customer_id": "cust_emp002",
        "amount": 750000,
        "note": "March salary - Management"
      },
      {
        "customer_id": "cust_emp003",
        "amount": 600000,
        "note": "March salary - Design"
      }
    ]
  }'

Atomic reservation

When you submit a batch, Mazad performs an atomic reservation of the total payout amount from your merchant wallet. This is an all-or-nothing operation.

Sufficient balance

Merchant balance: 2,000,000 IQD. Batch total: 1,850,000 IQD.

Available: 2,000,000 → 150,000

Reserved: 0 → 1,850,000

Status: processing

Insufficient balance

Merchant balance: 1,000,000 IQD. Batch total: 1,850,000 IQD.

Available: 1,000,000 (unchanged)

Reserved: 0 (unchanged)

Status: 402 error — batch rejected

No partial batches

Either the full batch amount is reserved or the entire request is rejected. You will never end up with a partially-funded batch.

CSV to JSON conversion

If your payroll data is in CSV format, convert it to the API's JSON format before submitting. Here is the expected CSV structure and a conversion example.

customer_id,amount,note
cust_emp001,500000,March salary - Engineering
cust_emp002,750000,March salary - Management
cust_emp003,600000,March salary - Design

Batch size limit

Each batch supports a maximum of 500 recipients. For larger payrolls, split your CSV into multiple batches and submit them sequentially.

Payroll Overview Tracking