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#

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

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

Generate Batch Payoutbash

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):

Generate Batch Payoutjson

{
  "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#

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#

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

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

Include or Exclude a Merchant#

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

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

Approve Batch#

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

Only draft or pending_review batches can be approved.

Process Batch#

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#

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

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

Export Batch#

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

Export Batchbash

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