Batch Processing#

Work with settlement batches, the daily settle schedule, and funding.

Overview#

AuxCORE groups a merchant's card transactions into settlement batches. A batch is opened as transactions arrive and closed (settled) at the merchant's daily cut-off, or on demand.

All endpoints below are admin API routes: Authorization: Bearer <JWT> (or an API key in x-api-key). A merchant user only sees its own merchant's batches; admin callers may pass merchantId. /api/v1/batches/* is gated by the tenant's batch feature (403 SERVICE_UNAVAILABLE without it); /deposits and /settlements are not gated.

Note: There is no file-upload ("Batch Terminal") API for submitting many transactions from a CSV. The portal's Batch Terminal page redirects to the Batches list. Submit transactions individually with POST /api/v1/public/transaction.

Batch Statuses#

Status	Meaning
`open`	Accepting transactions
`pending`	Closed, waiting to be submitted
`processing`	Being submitted to the processor
`settled`	Settled
`failed`	Settlement failed
`cancelled`	Cancelled
`resubmit`	Marked for resubmission
`host_settlement_pending`	Host-capture batch (TSYS) waiting for the processor's own cut-off

List Batches#

GET/api/v1/batches

Query	Description
`merchantId`	Admin only; merchant users are always scoped to their own merchant
`status`	One of the statuses above
`dateFrom` / `dateTo`	Created date range
`page` / `limit`	Default `1` / `50`

List Batchesbash

curl "https://uat.auxcore.net/api/v1/batches?status=settled&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

List Batchesjson

{
  "success": true,
  "data": [
    {
      "id": "6e7f8a9b-0c1d-4e2f-8a3b-4c5d6e7f8a9b",
      "merchantId": "3f2a9c1e-7b4d-4e8a-9f10-2c5d6e7f8a90",
      "batchNumber": "001",
      "batchId": "BATCH-20260222-001",
      "status": "settled",
      "gatewayName": "NMI",
      "saleCount": 45,
      "refundCount": 2,
      "voidCount": 0,
      "transactionCount": 47,
      "saleAmount": "5900.00",
      "refundAmount": "75.25",
      "netAmount": "5824.75",
      "totalAmount": "5824.75",
      "currency": "USD",
      "settledAt": "2026-02-22T23:00:00Z",
      "createdAt": "2026-02-22T08:12:00Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 89 }
}

Amount fields are decimal strings. The full object also carries authCount / captureCount / totalCount, the matching …Amount fields, gatewayBatchId, openedAt, closedAt, submittedAt, settledDate, scheduledSettleTime, resubmitCount, settlementReference, errorMessage and updatedAt.

Get Batch#

GET/api/v1/batches/:id

404 if the batch does not exist (or belongs to another merchant).

Batch Transactions#

GET/api/v1/batches/:id/transactions

Response: { "success": true, "data": { "batch": { … }, "transactions": [ … ] } }. Returns 502 UPSTREAM_ERROR if the transaction list cannot be loaded.

Export a Batch#

GET/api/v1/batches/:id/export

Export the Batch List#

GET/api/v1/batches/export

The list export takes merchantId, startDate, endDate.

Create a Batch#

POST/api/v1/batches

Create a Batchjson

{
  "merchantId": "3f2a9c1e-7b4d-4e8a-9f10-2c5d6e7f8a90",
  "scheduledSettleTime": "2026-02-24T23:00:00Z"
}

Both fields are optional for merchant users; an admin must send merchantId (400 VALIDATION_ERROR otherwise). Returns 201.

Settle a Batch Now#

POST/api/v1/batches/:id/settle

Optional body submissionConfig (gatewayType and method required when sent; https_post needs endpoint, socket needs host and port). If settlement fails the response is 422:

Settle a Batch Nowjson

{
  "success": false,
  "error": { "code": "SETTLEMENT_FAILED", "message": "Batch settlement failed" },
  "data": { "id": "6e7f8a9b-0c1d-4e2f-8a3b-4c5d6e7f8a9b", "status": "failed" }
}

Resubmit a Failed Batch#

POST/api/v1/batches/:id/resubmit

Daily Settle Schedule#

Get Schedule#

GET/api/v1/batches/schedule

Get Schedulebash

curl "https://uat.auxcore.net/api/v1/batches/schedule?merchantId=3f2a9c1e-7b4d-4e8a-9f10-2c5d6e7f8a90" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

Get Schedulejson

{
  "success": true,
  "data": { "settleTime": "23:00", "settleTimezone": "America/New_York" }
}

If nothing is saved the default 23:00 / America/New_York is returned. An admin call with no merchantId returns data: null.

Set Schedule#

POST/api/v1/batches/schedule

Set Schedulebash

curl -X POST https://uat.auxcore.net/api/v1/batches/schedule \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "3f2a9c1e-7b4d-4e8a-9f10-2c5d6e7f8a90",
    "settleTime": "23:30",
    "settleTimezone": "America/Chicago"
  }'

Field	Required	Description
`settleTime`	Yes	`HH:MM` (24-hour)
`settleTimezone`	No	IANA timezone, default `America/New_York`
`merchantId`	Admin only	Required when an admin sets the schedule

Invalid settleTime returns 400 (settleTime must be in HH:MM format).

Batch Summaries#

Settlement Summary#

GET/api/v1/batches/settlement-summary

Net Deposits#

GET/api/v1/batches/net-deposits

Both take merchantId (admin), startDate, endDate; startDate and endDate are required (400 VALIDATION_ERROR otherwise).

List Deposits#

Deposits recorded against batches.

GET/api/v1/deposits

Query: merchantId (admin), dateFrom, dateTo, limit (default 100, max 500). Response: { "success": true, "data": [ { "id", "date", "depositDate", "amount", "grossAmount", "refundAmount", "chargebackAmount", "transactionCount", "fees", "net", "netAmount", "status", "bankAccount", "reference", "merchantId", "gateway" } ] } — one row per batch; id is the batch id.

Get a Deposit#

GET/api/v1/deposits/:id

Funding and Payouts#

These live on the settlement service under /api/v1/settlements.

Funding Report#

GET/api/v1/settlements/funding-report

Funding Reportbash

curl "https://uat.auxcore.net/api/v1/settlements/funding-report?merchantId=3f2a9c1e-7b4d-4e8a-9f10-2c5d6e7f8a90&dateFrom=2026-02-01&dateTo=2026-02-28" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query: merchantId (or merchantIds, comma-separated), dateFrom, dateTo (or a single date; one of the two is required, 400 VALIDATION_ERROR otherwise), optional gatewayType, processorId, riskLevel, includeOneTimeFees. With a single merchantId that yields one report, the response is { "success": true, "msg": "Daily Summary with Fees Found Successfully", "data": { … } }; otherwise (merchantIds, all=true, or no merchant) data is an array of reports and msg is Generated N funding reports.

Export Funding Report as CSV#

GET/api/v1/settlements/funding-report/export/csv

Export Funding Report as CSVbash

curl "https://uat.auxcore.net/api/v1/settlements/funding-report/export/csv?merchantId=3f2a9c1e-7b4d-4e8a-9f10-2c5d6e7f8a90&dateFrom=2026-02-01&dateTo=2026-02-28" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o funding-report.csv

Email Funding Report#

POST/api/v1/settlements/funding-report/email

Email Funding Reportjson

{
  "merchantId": "3f2a9c1e-7b4d-4e8a-9f10-2c5d6e7f8a90",
  "dateFrom": "2026-02-01",
  "dateTo": "2026-02-28",
  "recipientEmail": "accounting@example.com"
}

dateFrom, dateTo and recipientEmail are required (400 VALIDATION_ERROR otherwise).

Initiate a Manual Payout#

POST/api/v1/settlements/payout

Initiate a Manual Payoutjson

{
  "merchantId": "3f2a9c1e-7b4d-4e8a-9f10-2c5d6e7f8a90",
  "date": "2026-02-22",
  "amount": 5824.75
}

merchantId, date and amount are required (400 VALIDATION_ERROR otherwise). Response: { "success": true, "data": { "payoutId": "PAYOUT-1771761600000-7f8a90", "merchantId", "amount", "status": "initiated", "estimatedDate": "2026-02-23" } }. This only records an initiated payout reference (billing-ledger write is best effort and its failure is ignored); it does not move money.

Settlement History#

GET/api/v1/settlements/history/:merchantId

Best Practices#

Pick a settle time after your last expected sale of the day
Check batch status after the cut-off — failed batches need resubmit
Reconcile batches against the funding report

Need help? Contact support@auxcore.net