# Payments and Dunning / OPOS — official documentation notes

Verified 2026-10-12. Production references use `/reference/`; preview references use `/v2-preview/reference/` and may show a stage host. Do not silently present preview schemas as production guarantees.

## Payments

- A Customer Payment Account (CPA) stores provider references used to charge, refund or pay out a customer. PSP methods use tokens/external references. `paymentMethod` is informational; the provider references select the actual method. Stripe maps `cus_…` to payment provider reference and `pm_…` to payment method reference. [Customer Payment Accounts](https://docs.instellix.io/docs/add-payment-accounts)
- Charging success does not establish settlement: payment reporting processes provider/bank reports and assigns payments to invoices; a successful charge may still be cancelled or disputed before settlement. Full-service includes charging/reporting/accounting; hybrid delegates charging externally and imports reports; self-managed delegates all three. [Payment Management](https://docs.instellix.io/docs/payment-management)

| Method / route | Use / identifier | Source |
| --- | --- | --- |
| `POST /v2/customer-payment-accounts` | Create CPA for `debtorIdent`; requires `merchantPaymentGatewayIdent` and `paymentProviderReference`; `ident` generated if omitted. `displayName` must not contain full card/IBAN data. | [Production CPA create](https://docs.instellix.io/reference/createcustomerpaymentaccount) |
| `GET /v2/payment-intents` | Paged PaymentIntent query with RSQL `search`. Production crawl displays old `api.nitrobox.io` hostname, so do not copy that host blindly. | [Production query](https://docs.instellix.io/reference/searchpaymentintents) |
| `POST /v2/payment-intents` | Create an intent. Production route verified; full schema available in preview (see below). | [Production create](https://docs.instellix.io/reference/createpaymentintent) |
| `POST /v2/payment-intents/{paymentIntentIdent}/actions/retry` | Retry only in `FAILED` status. | [Production retry](https://docs.instellix.io/reference/retrypaymentintent) |
| `POST /v2/payment-intents/{paymentIntentIdent}/actions/cancel` | Cancel only in `FAILED` status. | [Production cancel](https://docs.instellix.io/reference/cancelpaymentintent) |

**Preview-only schema details:** create requires `amount` (amount/currency object), `billingGroupIdent`, `customerPaymentAccountIdent`, `ident`, and `type` (`CHARGING`, `REFUND`, `PAYOUT`). Optional `referenceIdent` / `referenceType`; deprecated `businessSegmentIdent` → `billingGroupIdent`, `referenceKey` → `referenceType`. [Preview create](https://docs.instellix.io/v2-preview/reference/createpaymentintent)

**Preview-only query details:** `GET /v2/payment-intents?search=ident==client123&page=0&size=10`; size max 100, default 10; page zero-based; `sort` default `id`, property optionally followed by asc/desc. [Preview query](https://docs.instellix.io/v2-preview/reference/searchpaymentintents)

**Preview-only routes:** `GET /v2/payment-intents/{paymentIntentIdent}` retrieves intent; `GET /v2/payments/{ident}` retrieves payment transaction. [Preview intent](https://docs.instellix.io/v2-preview/reference/getpaymentintentdetailsbyident), [Preview payment](https://docs.instellix.io/v2-preview/reference/getpaymenttransactionbyident)

**Preview-only CPA action:** `?action=replaceFailedPaymentIntents` replaces failed intents for the debtor using the new CPA. Omitting action does not cancel/create intents; unknown action → 400. [Preview CPA create](https://docs.instellix.io/v2-preview/reference/createcustomerpaymentaccount)

## Dunning / OPOS

- Dunning begins from receivable due date plus first level interval, provided amount due > 0, dunning active/unblocked, and no collection or automatic retry remains running. Failed intent alone does not trigger it. Due date priority: order/contract payment term (`periodInDays`), configured fallback, otherwise 30 days. Later levels count from previous level start. Existing plans retain their initial snapshot after configuration changes. A dunning block does not cancel a running intent; intent cancellation does not settle the open item. [When Dunning Starts](https://docs.instellix.io/docs/when-dunning-starts)

| Method / route | Semantics | Source |
| --- | --- | --- |
| `GET /v2/opos-cases` | Tenant cases; RSQL `search`; `page` default 0, `size` default 20 (≥1), `sort` default `initialDocumentIdent,ASC`; supports multiple sort criteria. | [Production query](https://docs.instellix.io/reference/getoposcases-1) |
| `PUT /v2/opos-cases/{oposCaseIdent}/dunning-block` | Body `{"active":true,"note":"Review pending"}`; required non-null `active`; note optional, max 100 chars. | [Production block](https://docs.instellix.io/reference/oposcasedunning) |
| `POST /v2/opos-cases/{oposCaseIdent}/decisions` | Required unique decision `ident` and `type`; optional note ≤255. `amount` ≥0, mandatory if active prebooked item exists, otherwise case balance used. | [Production decision](https://docs.instellix.io/reference/addoposcasedecision-1) |
| `GET /v2/opos-cases/{oposCaseIdent}/decisions` | RSQL query, e.g. `search=type==OTHER_REVENUE`; page default 0, size default 100, sort default `ident,ASC`. | [Production decisions](https://docs.instellix.io/reference/getoposcasedecisions-1) |
| `GET /v2/opos-cases/{oposCaseIdent}/decisions/{decisionIdent}` | Retrieve individual decision. Both idents 1–100 chars, regex `^[a-zA-Z0-9_.~-]*$`. | [Production retrieve](https://docs.instellix.io/reference/getoposcasedecision-1) |

Decision types by balance: DEBIT → `UNCOLLECTABLE_RECEIVABLE`, `DOUBTFUL_RECEIVABLE`, `DISCOUNT`, `CASH_DISCOUNT`, `BANK_FEE`, `EXTERNAL_CLOSED`; CREDIT → `OTHER_REVENUE`, `EXTERNAL_CLOSED`. [Production decision](https://docs.instellix.io/reference/addoposcasedecision-1)

**Preview-only:** `GET /v2/opos-cases/{oposCaseIdent}/dunning-plan` retrieves plan. [Preview dunning plan](https://docs.instellix.io/v2-preview/reference/getdunningplan)

Example read: `GET https://api.instellix.io/v2/opos-cases?page=0&size=20&sort=initialDocumentIdent%2CASC` (documented query shape). [Production query](https://docs.instellix.io/reference/getoposcases-1)