Reconciliation#

Reconcile settlements against gateway data, and compare them with deposits and transactions.

All endpoints are admin API calls: send Authorization: Bearer <JWT> (or an API key in x-api-key). The tenant comes from the token or key.

Note: there is no date-based reconciliation report and no auto-reconcile endpoint. Reconciliation runs per settlement, with the endpoint below.

List Settlements#

GET/api/v1/settlements

List Settlementsbash

curl "https://uat.auxcore.net/api/v1/settlements?merchantId=3f9c2b7e-1a4d-4e8f-b6c5-2d1e0f9a8b7c&dateFrom=2026-01-01&dateTo=2026-01-31&status=discrepancy" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query param	Notes
`merchantId`	With it: that merchant's settlements, filtered by the params below. Without it: the tenant's settlements awaiting approval (other filters ignored).
`dateFrom`, `dateTo`	`YYYY-MM-DD`
`status`	`calculating`, `calculated`, `reconciling`, `reconciled`, `discrepancy`, `approved`, `payout_processing`, `paid`, `failed`

Each settlement carries id, merchantId, payPeriodId, gatewayType, status, grossAmount, transactionCount, totalFees, netAmount, reserveHeld, payoutAmount, feeBreakdown, volumeBreakdown, reconciliation (the last result, or null), hasDiscrepancy, discrepancyAmount, and the approval and reconciliation timestamps. Money fields are decimal strings. GET /api/v1/settlements/:settlementId returns one settlement (404 if not found).

Reconcile a Settlement#

POST/api/v1/settlements/:settlementId/reconcile

Compares the settlement with the gateway's settlement data for the same pay period.

Reconcile a Settlementbash

curl -X POST https://uat.auxcore.net/api/v1/settlements/c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f/reconcile \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"gatewayType": "NMI"}'

gatewayType is required; without it the response is 400 with error.code MISSING_GATEWAY_TYPE.

Response:

Reconcile a Settlementjson

{
  "success": true,
  "data": {
    "gatewayGross": "10000.00",
    "calculatedGross": "10000.00",
    "grossVariance": "0.00",
    "gatewayNet": "9700.00",
    "calculatedNet": "9700.00",
    "netVariance": "0.00",
    "transactionCountGateway": 212,
    "transactionCountLocal": 212,
    "countVariance": 0,
    "missingTransactions": [],
    "extraTransactions": [],
    "amountMismatches": [],
    "status": "matched",
    "varianceThreshold": "0.01",
    "reconciledAt": "2026-01-16T14:05:12.000Z",
    "reconciledBy": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"
  }
}

status: matched (gross and net within $0.01 and equal counts), critical_variance (gross off by more than $100 or more than 10 transactions), otherwise variance.
missingTransactions: IDs the gateway has but AuxCORE does not; extraTransactions: the reverse.
amountMismatches[]: { "transactionId", "localAmount", "gatewayAmount", "variance" }.
Any status other than matched flags the settlement (hasDiscrepancy: true) and moves it to discrepancy.

Errors (including an unknown settlement) return 500 with { "success": false, "error": "<message>" }.

Approve a Settlement#

POST/api/v1/settlements/:settlementId/approve

Body: notes (optional), overrideDiscrepancy (boolean, default false). Only settlements in calculated or reconciled status can be approved; a flagged settlement needs overrideDiscrepancy: true.

Review Discrepancies#

GET/api/v1/reports/discrepancies

Intended to list settlement discrepancies for the tenant (optional status: new, investigating, resolved, accepted; requires the reports.view permission).

Known issue: this endpoint currently returns 500 with error.code INTERNAL_ERROR (the reporting service calls a settlement route that does not exist). Until it is fixed, list flagged settlements with GET /api/v1/settlements?merchantId=<id>&status=discrepancy.

Compare with Deposits#

GET/api/v1/deposits

Lists deposits (one per settled batch) to match against your bank statement.

Compare with Depositsbash

curl "https://uat.auxcore.net/api/v1/deposits?merchantId=3f9c2b7e-1a4d-4e8f-b6c5-2d1e0f9a8b7c&dateFrom=2026-01-01&dateTo=2026-01-31" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query: merchantId (admins; merchant users always get their own), dateFrom, dateTo, limit (default 100, max 500). Each item: id, date, depositDate, amount, grossAmount, refundAmount, chargebackAmount, transactionCount, fees, net, netAmount, status (pending, processing, completed, failed), bankAccount, reference, merchantId, gateway. GET /api/v1/deposits/:id returns one deposit.

bankAccount is currently always the placeholder ****0000.

Handle Discrepancies#

If totals don't match, review the transactions settled in the period:

bash

curl "https://uat.auxcore.net/api/v1/transactions?merchantId=3f9c2b7e-1a4d-4e8f-b6c5-2d1e0f9a8b7c&dateField=settledAt&dateFrom=2026-01-15&dateTo=2026-01-15&status=settled" \
  -H "Authorization: Bearer YOUR_TOKEN"

dateField=settledAt filters on the settlement date instead of the creation date.

Need help? Contact support@auxcore.net