publ Reference

settlement_get — Read settlement screens and document references

Use this to inspect one selected channel's settlement history, masked account details, base balance or current source availability. Connect as OWNER or a delegate with MANAGE_SETTLEMENT. Resolve channelCode through channels_list/channel_context_get. Hosted source admission is selected-channel only and requires its exact code; this is not deployed authorization evidence.

Inputs and selection

All objects are strict. channelCode is a required 1–512 character string, excluding dot/double dot, slash, backslash, ASCII controls and DEL. Optional currency is KRW or USD, defaulting to the observed base currency. An alternate choice must be observed and active; unknown or inactive choices never silently fall back. Availability must omit currency, including the base value: that behavioral constraint is additional to the exported schema.

Field	Required here	Contract
`currency`	No	`KRW`, `USD`
`view`	No	one of: `monthly`, `operations`, `account-info`, `balance`, `availability` (by `kind`); default `{"kind":"monthly","page":1,"limit":15}`
`view.page`	No	When `view.kind` is `monthly`: integer; maximum 1000000; greater than 0; default `1`
`view.limit`	No	When `view.kind` is `monthly`: `15` or `30` or `50` or `100`; default `15`
`view.document`	No	When `view.kind` is `monthly`: object
`view.document.distinctId`	Yes	When `view.kind` is `monthly`: string; min length 1; max length 128; pattern `^[A-Za-z0-9_-]+$`
`view.document.type`	Yes	When `view.kind` is `monthly`: `revenue`, `expense`, `transactions`
`view.page`	No	When `view.kind` is `operations`: integer; maximum 1000000; greater than 0; default `1`
`view.limit`	No	When `view.kind` is `operations`: `15` or `30` or `50` or `100`; default `15`
`view.delegatedAction`	No	When `view.kind` is `operations`: `SETTLEMENT`, `PAYMENT`
`view.document`	No	When `view.kind` is `operations`: object
`view.document.distinctId`	Yes	When `view.kind` is `operations`: string; min length 1; max length 128; pattern `^[A-Za-z0-9_-]+$`

Omitting view defaults to monthly/page 1/limit 15. Page is a positive safe integer at most 1,000,000; allowed limits are 15/30/50/100. Document IDs must be observed on the requested parent page and match 1–128 ASCII letters/digits/underscore/hyphen. No raw document URL, bank payload, date range, automatic traversal, export destination, requestId, dryRun or task identifier is accepted.

{"channelCode":"selected-channel-code"}

{"channelCode":"selected-channel-code","currency":"KRW","view":{"kind":"monthly","page":1,"limit":15}}

{"channelCode":"selected-channel-code","view":{"kind":"monthly","document":{"distinctId":"observed-month-id","type":"revenue"}}}

{"channelCode":"selected-channel-code","view":{"kind":"monthly","document":{"distinctId":"observed-month-id","type":"expense"}}}

{"channelCode":"selected-channel-code","view":{"kind":"monthly","document":{"distinctId":"observed-month-id","type":"transactions"}}}

{"channelCode":"selected-channel-code","view":{"kind":"operations","page":1,"limit":15,"delegatedAction":"SETTLEMENT","document":{"distinctId":"observed-operation-id"}}}

{"channelCode":"selected-channel-code","view":{"kind":"account-info"}}

{"channelCode":"selected-channel-code","view":{"kind":"balance"}}

{"channelCode":"selected-channel-code","view":{"kind":"availability"}}

Prerequisites and bounded observations

The workflow observes channel identity, plan and currency definitions, business readiness and current public manual-visibility configuration in order. FREE_TRIAL/ENTERPRISE_TRIAL stop before business-readiness or public-config/financial requests. Missing SETTLEMENT_READY stops before visibility and financial reads. Hidden settlement stops all views except account-info. It repeats prerequisite/selected-context observations before return; changed context fails rather than combining states.

A gate returns action_required / SETTLEMENT_PREREQUISITE with reason plan, business-documents or hidden, requiredAction to open the exact console screen, verification.confirmed:false, prerequisitesObserved:true and financialActionPerformed:false. Do not launch, purchase a plan, register an account or request settlement merely to bypass a gate. Hidden-history guidance points to base-currency account-info.

Successful reads return SETTLEMENT_SCREEN, selected channel/currency/prerequisites, view-specific data, writesPerformed:false and verification.confirmed:true / atomicSnapshot:false / financialActionPerformed:false / documentContentsVerified:false. Monthly/operation pages and account/balance observations are compared across repeated reads. Page length must exactly match server pagination, IDs must be unique, and channel/currency bindings must match. Settlement page coverage.completeInventory stays false, with explicit nextPage. Request another page yourself if authorized.

Monthly rows preserve numeric id, opaque distinctId, baseDate YYYY-MM, source status, revenue/expense/balance and timestamps. Transaction-document metadata is projected only as hasTransactionHistoryDocument; requesting that document requires the indicator. Operations preserve OPEN/CLOSE, remarks and the source delegated action/amount. SETTLEMENT filters settlement-withdrawal actions; PAYMENT filters the other source payment actions. Monetary values remain source strings (1–256 characters) with KRW/USD; no numeric format, balance arithmetic, exchange rate, tax or payable-total calculation is inferred.

Account projection includes id, registered:true, bankName, bankAccountHolder, accountNumberLast4, bankbookPresent and timestamps. Full account numbers and bankbook locations are omitted. Balance preserves its source identity, accumulatedRevenue, accumulatedExpense and balance in base currency.

Availability checks base plus every observed alternate definition, including inactive definitions, and repeats the set. It returns currencyStatuses, displayStatus, readOnlyPost:true and availabilityIsReservation:false. Known source conditions map to REQUESTABLE, NO_AMOUNT, INVALID_PERIOD or UNPAID_AMOUNT. UNPAID_AMOUNT takes display priority; otherwise all-NO_AMOUNT wins, otherwise the base result is displayed. An availability POST observes the source check; it neither reserves funds nor submits settlement.

Document references and errors

A selected document requires stable observed parent-page membership; the parent is read again after the URL response. Monthly type is explicit. Operation document kind follows the observed action and OPEN/CLOSE status: settlement withdrawal uses apply-invoice/apply-receipt; other payment uses outstanding-invoice/outstanding-receipt. Transactions use the source CSV request with base-currency language selection. Returned document contains distinctId, type, downloadUrl, contentFetched:false, contentVerified:false and expiresAt:null. Only a source HTTPS URL without embedded username/password is accepted; no content download or host allowlist verification is claimed. Do not expose a signed URL beyond the intended recipient or claim document contents have been verified.

Public visibility fetches are separate from authenticated requests: no bearer, channel header, cookies or redirect following. The operator configures primary/fallback public resources; unavailable or malformed current configuration returns SETTLEMENT_VISIBILITY_UNCONFIGURED/UNVERIFIED, never an empty default. Its selected hidden state, version and digest are observations, not visitor access proof. Authenticated financial reads require exact HTTP 200 and a bounded 2 MiB data envelope; auth/permission/upstream failures retain their semantics. AUTH_REQUIRED remains action_required. Required identities, currencies and non-null fields are validated; no failed read becomes a zero balance or empty list.

Correct INVALID_INPUT, reselect unavailable currency/parent, and reread after context changes. Do not retry a financial write: none is performed here, and no settlement job or task type exists. Use settlement_handoff for human registration/removal/request actions. Console paths and HTTP mapping are in the settlement guide.

Successful monthly and operations responses include their normalized view. The single console address retains page, limit and the operations delegatedAction filter, together with the observed currency suffix where the source requires it. A document selection opens the corresponding parent list page; it does not open a preview modal or verify downloaded content.

Navigation checks the returned view, currency definition/selection, page metadata, record identities, channel/currency/filter agreement, coverage and selected document parent. Missing or contradictory evidence, extra query fields or a substituted path makes the destination unavailable. The API reads, financial handoffs, prerequisite routes and existing empty/out-of-range page policy are unchanged. Account and request handoffs do not inherit list queries.

For a verified document selection, the console navigation relation is parent, with an explicit instruction to select the document again from the matching row. This address opens the observed list; it is not the selected document or its preview. The separate temporary downloadUrl is a source-issued reference whose contents remain unfetched and unverified. Plain list reads retain target.