# Funding Reports

Daily funding (settlement) reports: gross sales, fees, reserve and net deposit per merchant.

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

---

## Get Funding Report

```http
GET /api/v1/settlements/funding-report
```

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

| Query param | Notes |
|---|---|
| `date` | `YYYY-MM-DD`. Shorthand for a single day; used for `dateFrom`/`dateTo` when they are omitted. |
| `dateFrom`, `dateTo` | `YYYY-MM-DD`. Either `date` or both of these is required, else `400 VALIDATION_ERROR`. |
| `merchantId` | One merchant. Defaults to the caller's merchant. |
| `merchantIds` | Comma-separated merchant IDs (batch). |
| `all` | `true` → every merchant in the tenant (ignores `merchantId`). |
| `riskLevel` | `high`, `regular` (low + medium) or `all`. |
| `gatewayType` | Filter by gateway; `all` means no filter. |
| `processorId` | Filter by processor. |
| `includeOneTimeFees` | `true` to include one-time fees such as decline routing. |

With a single `merchantId`, `data` is one report object. Otherwise `data` is an array of reports.

**Response (single merchant):**
```json
{
  "success": true,
  "msg": "Daily Summary with Fees Found Successfully",
  "data": {
    "merchant": { "id": "3f9c2b7e-1a4d-4e8f-b6c5-2d1e0f9a8b7c", "name": "Harbor Coffee Co", "email": "owner@harborcoffee.example", "gatewayMerchantId": "800000001234" },
    "reportDate": "2026-01-31",
    "payoutPeriod": { "start": "2026-01-01", "end": "2026-01-31" },
    "period": "Daily Summary - DS",
    "summary": {
      "grossSales": 10000.0,
      "processingFees": 300.0,
      "reserveBalance": 0,
      "netBeforeUSDT": 9700.0,
      "payoutFee": 0,
      "netDeposit": 9700.0
    },
    "detailedFees": {
      "transactions": { "count": 212, "countForFees": 212, "fee": 0.1, "totalFee": 21.2 },
      "processing": { "percentage": 2.79, "amount": 278.8 }
    },
    "salesVolume": {
      "creditCards": { "count": 200, "amount": 9500.0 },
      "giftCards": { "count": 0, "amount": 0 },
      "ach": { "count": 12, "amount": 500.0 },
      "cash": { "count": 0, "amount": 0 },
      "refunds": { "count": 1, "amount": 25.0 },
      "chargebacks": { "count": 0, "amount": 0 }
    },
    "reserveAccount": { "totalReserveAmount": 0, "reserveFee": 0 },
    "payoutDestination": { "method": "ach", "walletType": null, "walletIdLast4": null, "accountLast4": "6789", "chain": null },
    "amountPaid": { "amount": 9700.0, "currency": "USD", "status": "paid" },
    "feeConfiguration": null,
    "paymentDate": "2026-02-02",
    "generatedAt": "2026-02-01T08:00:00.000Z",
    "feeSource": "legacy"
  }
}
```

- `detailedFees` also carries `declines`, `riskManagement`, `giftCardLoad`, `storedValueCard`, `refund`, `chargeback`, `declineRouting`, `payoutFee`, `nonQualified`, `statementAdjustment` and `miscellaneous` (shortened above).
- `summary.netDeposit` is what is owed; `amountPaid` is what confirmed payouts actually paid. `amountPaid.status` is `paid`, `partial`, `unpaid` or `not_verified` (the payout lookup failed — never reported as 0).
- `payoutDestination` carries last-4 values only, and is `null` when the lookup failed.
- `feeSource`: `legacy`, `v5` or `shadow` (V5 fee preview).

---

## Export Report

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

```bash
curl "https://uat.auxcore.net/api/v1/settlements/funding-report/export/csv?dateFrom=2026-01-01&dateTo=2026-01-31&all=true" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o funding-report.csv
```

Query: `dateFrom` and `dateTo` (both required — `date` is not accepted here), `merchantId`, `merchantIds`, `riskLevel`, `all`. Returns a UTF-8 CSV with one row per merchant: merchant name, report and period dates, gross sales, processing fees, reserve, net deposit, counts, volume by payment type, refunds, chargebacks, payout fee, payment date, payout method, destination last 4, amount paid and its status.

---

## Email Report

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

```bash
curl -X POST https://uat.auxcore.net/api/v1/settlements/funding-report/email \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientEmail": "accounting@example.com",
    "merchantId": "3f9c2b7e-1a4d-4e8f-b6c5-2d1e0f9a8b7c",
    "dateFrom": "2026-01-01",
    "dateTo": "2026-01-31"
  }'
```

`recipientEmail`, `dateFrom` and `dateTo` are required (`400 VALIDATION_ERROR` otherwise). Omit `merchantId` to email reports for every merchant.

**Response:**
```json
{
  "success": true,
  "msg": "Funding report email sent to accounting@example.com",
  "data": { "reportCount": 1, "recipient": "accounting@example.com" }
}
```

If the report is generated but the email cannot be sent, the response is `500` with `error.code` `EMAIL_FAILED`.

---

## Record a Payout

```http
POST /api/v1/settlements/payout
```

Body: `merchantId`, `date`, `amount` (all required, else `400 VALIDATION_ERROR`). Returns `{ "success": true, "data": { "payoutId": "PAYOUT-1769932800000-9a8b7c", "merchantId", "amount", "status": "initiated", "estimatedDate" } }` (`payoutId` ends with the last 6 characters of `merchantId`; `estimatedDate` is the next day). This only records the payout reference; no funds are moved.

---

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