# Batch Payouts

Generate, review, approve and export tenant-wide payout batches.

All endpoints are admin API calls under `/api/v1/settlements/batch-payouts`: send `Authorization: Bearer <JWT>` (or an API key in `x-api-key`). The tenant comes from the token or key. Errors return `{ "success": false, "message": "..." }` — `400` for validation, `404` for an unknown batch on `GET /:id`, otherwise `500`.

A batch moves through `draft` → (`pending_review`) → `approved` → `completed`, or to `cancelled`.

---

## Generate Batch Payout

```http
POST /api/v1/settlements/batch-payouts/generate
```

Builds a `draft` batch covering every merchant in the tenant with transactions in the period.

```bash
curl -X POST https://uat.auxcore.net/api/v1/settlements/batch-payouts/generate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dateFrom": "2026-01-01",
    "dateTo": "2026-01-31",
    "gatewayType": "NMI"
  }'
```

| Field | Type | Required | Notes |
|---|---|---|---|
| `dateFrom`, `dateTo` | string | yes | `YYYY-MM-DD` |
| `gatewayType` | string | no | Limit the batch to one gateway. |

If no merchant has transactions in the period the response is `500` "No merchants found with transactions in the specified period".

**Response (`201`):**
```json
{
  "success": true,
  "message": "Batch payout report generated successfully",
  "data": {
    "batchId": "e7f8a9b0-c1d2-4e3f-8a4b-5c6d7e8f9a0b",
    "batchNumber": "BATCH-20260201-K7Q2",
    "periodStart": "2026-01-01",
    "periodEnd": "2026-01-31",
    "gatewayType": "NMI",
    "summary": {
      "totalGross": 25000.0,
      "totalFees": 750.0,
      "totalReserve": 0,
      "totalNet": 24250.0,
      "merchantCount": 3,
      "transactionCount": 500
    },
    "merchants": [
      {
        "merchantId": "3f9c2b7e-1a4d-4e8f-b6c5-2d1e0f9a8b7c",
        "merchantName": "Harbor Coffee Co",
        "merchantEmail": "owner@harborcoffee.example",
        "gatewayMerchantId": "800000001234",
        "grossVolume": 10000.0,
        "totalFees": 300.0,
        "reserveAmount": 0,
        "netPayout": 9700.0,
        "transactionCount": 212,
        "isIncluded": true,
        "feeBreakdown": { },
        "volumeBreakdown": { }
      }
    ],
    "status": "draft",
    "createdAt": "2026-02-01T08:00:00.000Z"
  }
}
```

---

## List Batch Payouts

```http
GET /api/v1/settlements/batch-payouts
```

Optional `status`: `draft`, `pending_review`, `approved`, `processing`, `completed`, `cancelled`. Each batch has `id`, `batchNumber`, `periodStart`, `periodEnd`, `gatewayType`, `totalGrossVolume`, `totalFees`, `totalReserve`, `totalNetPayout` (decimal strings), `merchantCount`, `transactionCount`, `status`, the review/approval/processing/cancellation audit fields, `externalReference`, `notes` and timestamps.

---

## Get Batch Payout

```http
GET /api/v1/settlements/batch-payouts/:id
```

Returns the batch with its `items` (one per merchant).

---

## Include or Exclude a Merchant

```http
PATCH /api/v1/settlements/batch-payouts/items/:itemId/inclusion
```

Body: `isIncluded` (boolean, required), `reason` (string, optional).

---

## Approve Batch

```http
POST /api/v1/settlements/batch-payouts/:id/approve
```

Only `draft` or `pending_review` batches can be approved.

---

## Process Batch

```http
POST /api/v1/settlements/batch-payouts/:id/process
```

Marks an `approved` batch as paid. Body: `externalReference` (e.g. your bank file reference) and `notes`, both optional.

---

## Cancel Batch

```http
POST /api/v1/settlements/batch-payouts/:id/cancel
```

Body: `reason` (required). A `completed` batch cannot be cancelled.

---

## Export Batch

```http
GET /api/v1/settlements/batch-payouts/:id/export
```

```bash
curl https://uat.auxcore.net/api/v1/settlements/batch-payouts/e7f8a9b0-c1d2-4e3f-8a4b-5c6d7e8f9a0b/export \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o batch-payout.xlsx
```

Returns an Excel workbook (`.xlsx`) named `<batchNumber>_Payout_Report.xlsx`.

---

**Need help?** Contact support@auxcore.net