Payment-provider observations
The provider input/projection stays unchanged, while the combined inventory is 104 business tools.
Select view:payment-gateway to read providers. Omit view, or use overview, for activation. Select consoleAction:payment-gateway for human setup/inquiry without a provider read. Do not combine the provider view with consoleAction; the runtime Zod refinement rejects this before business work even though exported JSON Schema lists both properties. No API key, issuer token, account ID, raw URL, provider selection, amount or requestId belongs in MCP input. OWNER or DELEGATEE with MANAGE_MONETIZATION for the selected channel is required; a unified connection also needs that channel in its approved target.
Observation sequence
| Step | Request and constraint |
|---|---|
| Context | Read the selected channel and check identity, role, permissions and channel credential. There is no account-bearer fallback. |
| Authorize | POST /profitable/authorize at the configured core origin, with selected-channel bearer and body fields role:ISSUER and channelId. |
| Providers | GET /api/v1/checkout/payment-methods/individual at the separate configured PAY origin, with only the returned issuer bearer. |
| Recheck | Check the selected credential before and after each payment-service request; re-read the channel/operator/permission/credential context and require an exact match before returning providers. |
Both payment-service URLs carry the configured apiKey query parameter, following the source wrapper. They carry no channel/consumer header, account bearer or cookie. Paths and destinations are fixed by the operator; redirects are rejected, each fetch has a 30-second timeout and no automatic retry occurs. Authorization requires JSON HTTP 200 or 201; the provider read requires HTTP 200. Both require a data object and no non-null application error. The successful token is used only within this call and is neither persisted nor returned. No expiry or reusable session lifetime is inferred.
This is a read of business data with an authorization POST. writesPerformed:false does not mean that every HTTP request is GET. No payment, provider enrollment, invoice, purchase, refund, bank update, withdrawal or settlement is submitted; no mutation journal or task is created. A concurrent call can be rejected with CONNECTION_BUSY by the existing connection-file lock without a second issuer authorization.
Returned data
The result is success / PAYMENT_PROVIDERS with channel and paymentProviders containing status:observed, providers and hasProviderRecords. The single console destination is this channel's monetization/payment-gateway path under the configured business console. Demo omits real destinations. A human setup recipe uses monetization_get with consoleAction:payment-gateway.
| Projection | Accepted values |
|---|---|
| providers | Array of at most 100 rows. Empty is a valid observation. |
| pgProvider | TOSS, PL_DOMESTIC or PL_GLOBAL. TOSS remains a source enum even where source screen branding is commented out. |
| methods | Array of at most 1,000 methods per row, retaining order. |
| pgcode | Nonempty string, at most 256 characters. |
| deploymentType | TEST or LIVE; no inferred successful checkout. |
| currency | Nonempty source string, at most 32 characters; not inferred from the channel's base currency. |
| isRecurring | Boolean observation; not recurring-charge eligibility. |
| activatedAt | Required ISO datetime with offset support. |
| deprecatedAt | Required nullable ISO datetime with offset support. Deprecated rows remain present without inferred usability. |
Each payment-service response is bounded to 2 MiB. Client keys and all unknown fields are removed by the projection. Missing/wrong fields or unsupported enum values fail; they do not become an empty list. hasProviderRecords is exactly whether the observed provider array is nonempty, even when a row's methods array is empty. It is not an active-provider, approval or eligibility flag.
verification.confirmed covers validated provider fields and matching context. atomicSnapshot, financialActionCompleted, visitorCheckoutVerified and settlementEligibilityVerified remain false; paymentProvidersRead is true. Separate sequential reads are not an atomic snapshot. Activation, revenue, orders, refunds and settlement are not read in this view. No provider inquiry form or email is opened or sent.
Operator configuration
Both stdio and the packaged hosted adapter use the same private startup settings. Configure PUBL_PAY_API_ORIGIN together with exactly one of PUBL_PAY_API_KEY or PUBL_PAY_API_KEY_FILE. A file reference must be an absolute path; its contents are trimmed. The key must be nonempty printable ASCII without spaces, at most 4,096 characters. This is operator configuration, never a request to send secret values through conversation or MCP arguments.
The PAY origin corresponds to the original application's separate PAY host; the merchant/core origin remains PUBL_API_ORIGIN. No PAY origin or key is inferred from another environment. Userinfo, non-root paths, query and fragment are rejected. Settings JSON is not a PAY-key input route. Connection metadata and MCP results do not expose these private runtime settings. Operators must redact the apiKey query parameter in outbound proxy/access logs.
If both origin and key are absent, other workflows remain available and explicit provider and sales reads fail with PAY_SERVICE_UNCONFIGURED. A partial/invalid pair, both key sources, relative/unreadable key file or invalid origin fails startup with PAY_SERVICE_CONFIGURATION_INVALID. Human payment-gateway guidance remains available without PAY configuration.
Failures and rereads
| Code or category | Meaning |
|---|---|
| PAY_SERVICE_UNCONFIGURED | The provider read lacks its operator configuration; no provider list is inferred. |
| AUTH_REQUIRED / PERMISSION_DENIED | Payment-service HTTP 401/403; restore the authorized connection or permission before an explicit reread. |
| UPSTREAM_HTTP_<status> | Other unsuccessful HTTP status; upstream error bodies and request URLs are not copied into the MCP error. |
| PAY_SERVICE_UNREACHABLE | Fetch, timeout or redirect failure; no automatic retry. |
| PAY_RESPONSE_UNVERIFIED / PAY_RESPONSE_TOO_LARGE | Unsupported successful status, missing/malformed JSON/data envelope or response bound exceeded. |
| PAY_SERVICE_REJECTED | The response has a non-null application error. |
| PAY_AUTHORIZATION_UNVERIFIED | Missing or invalid issuer access token. |
| PAYMENT_PROVIDERS_UNVERIFIED | Invalid provider/method projection. |
| Context/credential or connection-lock failure | Do not return partial records or reuse a token for another channel; resolve the failure before a new call. |
SDK input rejection may return MCP isError without a structured business code. Body-stream and other unexpected failures remain failures; they do not imply that no authorization was attempted. Provider read errors do not silently turn into a human destination or successful empty state. Select the separate consoleAction deliberately if the person wants guidance. There is no task_status/task_resume path for this read.
Actual PAY origin/status/body behavior, approved dev configuration, current user permissions, populated records, browser/visitor checkout, autonomous LLM/native-client use and deployed hosted operation require their own evidence.
Commerce transport extension
Numeric-lexeme preservation is enabled only for commerce PAY bodies; it does not widen sales amount parsing or provider fields. The shared PAY reader retains its 2 MiB cap and rejects non-null application errors. PAY safeguards and core safeguards are separate contracts.
Scoped financial-read recipes
Provider inputs, authorization sequence, projection, confirmation and error behavior retain their earlier contract.