# Remittance and Settlement

Clearing Service is the post-payment fund-flow record for NPS. It does not capture the original payment. It consumes processor settlement, ACH remittance, and payout data, correlates it back to payments, and exposes query APIs plus optional ledger and webhook events.

The implementing service is **Clearing Service** (`/clearing`). "Remittance" in the page title means merchant funding, especially ACH. It is not a second product beside Clearing Service.

## What Clearing Service Is (and Is Not)

**Clearing Service is responsible for:**

- Ingesting settlement, ACH remittance, ACH return, and related post-payment files from processors
- Correlating those records to original payments
- Tracking clearings (funds to merchant), payouts (PayPal-style funding), deposits, reversals, and adjustments
- Publishing ledger events to Billing & Ledger when the merchant has ledger integration enabled
- Emitting `clearing.*` events through NPS Push Notifications
- Providing operational query APIs for support and partner reconciliation


**Clearing Service is not responsible for:**

- Authorizing or capturing the original payment (Payments)
- Rendering invoices or receipts (Invoice Service, Receipt Service)
- Client-facing reports, CSV exports, or scheduled finance packs (NPS Reporting API, fed by replicated clearing tables)
- Sending payout instructions to banks (future). ACH remittance today is ingested after Direct already paid the merchant.


## Terms (Required Mental Model)

These words collide in payments. Use them as Clearing Service uses them.

| Term | Meaning here |
|  --- | --- |
| **Processed payment** | Authorization, capture, or ACH submission has already occurred upstream. Clearing only correlates after the fact. |
| **Settlement** | Processor or acquirer settled the captured transaction (funds movement from the payer side). This is **not** the moment the merchant is paid. |
| **Clearing (card industry)** | Card brands fund the acquirer. NPS does not see that step directly. |
| **Clearing Service** | This product. The name is broader than the card-industry step. |
| **Remittance** | ACH merchant funding: the batch job that pays merchants for collected ACH. Ingested from Direct `ACH_REMITTANCE`. Event names keep `clearing.remittance.*` for compatibility. |
| **Payout** | Funding with no separate settlement/clearing pair (PayPal). |
| **Merchant funding** | When the merchant actually receives money: ACH remittance, card acquirer payout, or PayPal settlement to the merchant. |


```mermaid
flowchart LR
  Pay[Payments capture or ACH submit] --> Proc[Processor or Direct]
  Proc --> Ingest[CDC and file ingestion]
  Ingest --> CS[Clearing Service]
  CS --> Query[Query APIs]
  CS --> Ledger[Optional Kafka ledger events]
  CS --> Events[Push notification events]
```

## How Data Arrives

Partners do not POST settlement files into Clearing Service. Ingestion is internal:

- **Debezium CDC** from Direct (CryptPay) tables such as `PAYMENT_TRANSACTION_SETTLEMENT`, `ACH_REMITTANCE`, `ACH_REMITTANCE_RETURN`, `ACH_REMITTANCE_ADJUSTMENT`
- **File-processor DDF** rows (TSYS today; Axia code exists but is not enabled)
- **PayPal webhooks** at `POST /clearing/webhooks/paypal` (PayPal signature, not a merchant JWT)
- **PayPal PSR** over SFTP for settlement date (not present on the webhook)


If a merchant ID on an acquirer row cannot be mapped to an NPS `entityId`, the row is added to the exceptions list rather than being silently dropped.

## How It Fits Your Workflow

1. A payment succeeds in Payments.
2. Hours or days later, the processor or ACH remittance job produces settlement or funding data.
3. Clearing Service stores settlement, clearing, payout, and related records and matches them to the payment when it can.
4. If `ledgerIntegrationEnabled` is true on `GET/PUT /clearing/config`, Billing & Ledger consumes Kafka events and posts journal lines.
5. You query by date range (or subscribe to webhooks) instead of polling a single `paymentId` until a file arrives.


Responses use the NPS envelope. HTTP status is typically 200. Branch on `responseCode`.

All paths below are relative to `https://api.nelnetpay.com/clearing`.

## Core Domain Concepts

| Concept | What it is | Why it matters | Key IDs |
|  --- | --- | --- | --- |
| **Transaction record** | Minimal payment correlation stored by Clearing | Enough to match processor data back to Payments | `transactionId`, `paymentId` |
| **Settlement** | Processor settlement of captured volume | Gross, fees, net, transaction count, status | `settlementId` |
| **Clearing** | Merchant funding record (ACH remittance path) | When funds were sent to the merchant | `clearingId` |
| **Payout** | PayPal-style funding | No separate settlement plus clearing pair | `payoutId` |
| **Deposit** | Grouping of remittance/funding | Ops view of a funding batch | `depositId` |
| **Reversal** | ACH return, chargeback, or processor reversal | Money moving against the merchant | reversal id |
| **Adjustment** | HOLD, CREDIT, or CORRECTION to fund flow | Exceptions to the normal funding path | `adjustmentId` |


### Custodial vs. Non-Custodial (Ledger)

When ledger integration is on, settlement journal shape depends on who holds funds:

- **Custodial:** NPS holds funds. Settlement typically `DR CLEARING` / `CR AR`, fees `DR FEE_EXPENSE` / `CR CLEARING`.
- **Non-custodial:** Funds go to the merchant bank. Settlement typically `DR BANK` / `CR AR`, fees `DR FEE_EXPENSE` / `CR BANK`.


If ledger integration is off, Clearing still stores the operational records. It just does not emit ledger events.

## Query APIs (What Partners Call)

These are operational lookups. For finance packs and exports, use the Reporting API.

| Method | Path | Purpose |
|  --- | --- | --- |
| GET | `/settlements` | List settlements (date range, processor, status) |
| GET | `/settlements/{settlementId}` | One settlement |
| GET | `/settlements/{settlementId}/transactions` | Transactions inside a settlement |
| POST | `/settlements/{settlementId}/process` | Reprocess a failed settlement |
| GET | `/clearings` | List ACH/merchant-funding clearings |
| GET | `/clearings/{clearingId}` | One clearing |
| GET | `/clearings/{clearingId}/settlements` | Settlements under a clearing |
| GET | `/payouts` | List payouts |
| GET | `/payouts/{payoutId}` | One payout |
| GET | `/transactions` | List correlation records |
| GET | `/transactions/{transactionId}` | One correlation record |
| GET | `/deposits` | Deposit / remittance grouping |
| GET | `/deposits/{depositId}` | One deposit |
| GET | `/reversals` | ACH returns, chargebacks, processor reversals |
| GET | `/reconciliation/summary` | Discrepancy summary |
| POST | `/reconciliation/settlements/{settlementId}` | Reconcile one settlement |
| GET | `/config` | Per-merchant clearing config |
| PUT | `/config` | Update processors, ledger flag, event batching |


Tags use the same shape on settlements, clearings, payouts, and transactions: `GET|PUT|PATCH|DELETE /{resource}/{id}/tags`.

**Query by date range instead of repeatedly checking whether a single payment has been added to the file.** Card settlement can lag capture by one to three days. ACH remittance follows the remittance job. A `GET` by `transactionId` returns empty until the processor data exists. Subscribe to events if you need to react when it arrives.

## Events

Merchants subscribe through NPS Push Notifications. High-volume sources (TSYS files, PayPal payout bursts) can be batched.

| Event | When |
|  --- | --- |
| `clearing.settlement.processed` | Settlement ingested and processed |
| `clearing.settlement.failed` | Settlement processing failed |
| `clearing.remittance.processed` | Clearing / ACH remittance processed |
| `clearing.remittance.failed` | Clearing processing failed |
| `clearing.payout.processed` | Payout processed |
| `clearing.payout.failed` | Payout processing failed |
| `clearing.reversal.ingested` | Return or chargeback ingested |
| `clearing.adjustment.created` | Fund-flow adjustment captured |
| `clearing.exception.created` | Unmatched or unresolvable ingest row |


## Configuration

`GET /clearing/config` and `PUT /clearing/config` are stored by Clearing Service. OSI Config is only enablement and hierarchy flags.

| Setting | Role |
|  --- | --- |
| `enabled` | Clearing enabled for the merchant |
| `ledgerIntegrationEnabled` | Emit Kafka events for Billing & Ledger |
| `processorSettings.sources` | `TSYS`, `PAYPAL`, `AXIA`, `OTHER` |
| `eventEmissionConfig` | Enable events, batching window, max batch size |
| `dataRetentionDays` | Default 2555 (7 years) |


Axia ingestion is implemented in code but not turned on in current environments. Treat TSYS (cards/ACH via Direct) and PayPal as the live processor sources unless your merchant config says otherwise.

## Typical Partner Patterns

### Pattern 1: Daily Funding Check

- Query `GET /clearings` or `GET /deposits` for yesterday's remittance date.
- Match net amounts to your bank deposit.
- Use `GET /reversals` for the same window to explain short pays.


### Pattern 2: Card Settlement vs. ACH Remittance

- Cards: `GET /settlements` by `settlementDate`.
- ACH: `GET /clearings` by clearing/remittance date.
- Do not expect the same record shape for both.


### Pattern 3: PayPal

- Capture lifecycle arrives as PayPal webhooks.
- Settlement date for a PayPal payment comes from the PSR file, not from the capture webhook.
- Payout bursts are batched before `clearing.payout.processed` is delivered.