[Proposal]: Add payment processing policy and reporting

[paulcarey-stripe]

Summary

Add an extension for selecting capture behavior before Checkout completion, and reporting payment-provider activity on the resulting Order. The proposed capability name is dev.ucp.common.payment.processing, subject to Tech Council approval.

The extension records Buyer approvals separately from provider processing attempts. This allows an existing authorization to continue when the Buyer later approves an Order change. Attempts contain append-only entries for authorization, authorization adjustment, capture, capture reversal, release, and expiry, together with current summary fields. Refunds continue to be reported as Order adjustments. This proposal is not intended to cover all payment processing history.

Motivation

UCP can select a payment instrument and complete a Checkout, but it does not state whether capture should begin automatically or later, or whether more than one capture is planned. A Platform needs that information before completion so it can explain when payment will be taken.

UCP also lacks a standard way to report provider authorization and capture activity on an Order. Instrument summaries show the current authorization and gross capture, but not retries, incremental authorization, capture reversal, or an unresolved provider request.

Goals

• Let a Platform request, and a Business select, capture timing and sequence before Checkout completion.
• Record the selected capture policy on the resulting Order.
• Keep Buyer approvals distinct from provider processing attempts.
• Support more than one attempt for an Order instrument and allow one attempt to span later Buyer approvals.
• Report current authorization, gross capture, and provider-reported capture capacity without deriving one from another.
• Record pending and completed provider activity without changing earlier entries.
• Cover authorization increases and decreases, multiple capture, voiding a capture before it settles, release, and expiry.
• Keep the extension additive and active only when negotiated.

Non-Goals

• Defining payment operations for the Platform to call.
• Defining provider authentication outcomes or the EMV 3DS protocol.
• Reporting settlement, payout, provider-side refund processing, or disputes. Business-issued refunds remain Order adjustments.
• Defining how Split Payments allocates a later approved increase across instruments.
• Providing a paginated archive of discarded processing entries, or handling pagination of entries in general.
• Defining detailed reconciliation in a provider currency.
• Changing the Core Checkout, Order, or payment-instrument schemas. The extension depends on the separate Core payment-consent proposal.

Detailed Design

Capability and dependencies

The extension composes onto dev.ucp.shopping.checkout and dev.ucp.shopping.order. Its requires constraints must name the release that contains Checkout amount finality, payment.maximum_amount, and the Order payment-instrument summaries.

The proposed dev.ucp.common.payment.processing name identifies this as a UCP extension.

Capture configuration

Business and Platform configuration advertise supported capture modes and sequences. The initial well-known values are:

• mode: automatic or manual;
• sequence: single or multiple.

These are open string values. Participants ignore unsupported values during negotiation and select only values they understand. An optional max_captures indicates a known limit on successful captures for one attempt.

Checkout policy

On Create or Update Checkout, the Platform may request a supported capture policy. The Business returns the selected policy in each Checkout response so the response is a complete statement of what will apply. The policy is omitted from Complete Checkout requests and cannot be changed during completion.

automatic means that the Business starts capture as part of completion, but does not promise that the result is available in the completion response.
manual means that the Business starts capture later through its own workflow.

Buyer approvals

order.payment.processing.approvals[] records the commercial approval obtained from the Buyer through the UCP flow. It is orthogonal to a payment provider's authorization decision.

The first approval has type: "checkout". Its maximum_amount equals order.payment.maximum_amount, and its capture policy matches the completed Checkout. A later order_change approval references the corresponding order.adjustments entry and records the new total ceiling, not the amount of the increase. Approval entries are immutable and remain in the order they were given.

Processing attempts

order.payment.processing.attempts[] contains provider payment lifecycles. An attempt refers to one Order instrument. Transport retries and changes to an existing authorization remain in the same attempt; a replacement authorization or a new provider lifecycle uses another attempt.

Attempts are separate from approvals because their lifecycles can differ. If an Order change permits an existing authorization to increase, the Business adds a Buyer approval and appends an authorization-adjustment entry to the existing attempt.

Each attempt may report:

• authorized_amount: authorization currently in effect;
• captured_amount: gross successful capture before refunds or capture reversals;
• capturable_amount: current capacity reported by the provider;
• expires_at: current provider-reported authorization expiry;
• status: the Business's current view of the attempt.

The parent instrument summaries equal the sums of the corresponding current attempt summaries. Consumers do not derive capturable_amount by subtracting the other fields.

Processing entries

Entries are append-only records of provider activity. Known entry types are authorization, authorization_adjustment, capture, capture_reversal, authorization_release, and authorization_expiry. Type and status remain open strings for forward compatibility.

Authorization, authorization-adjustment, and capture entries reference the Buyer approval in force when the request was made. A successful provider authorization is represented by status: "succeeded" and its approved amount; it is distinct from the Buyer approval.

requested_amount records what the Business requested. A successful amount records the provider result. For an authorization adjustment, both are new authorization totals rather than deltas. For capture, final: true records that the Business submitted it as the last planned capture for the attempt. A failed or reversed final capture may still be retried.

observed_at records when the Business initiated or learned about an entry. occurred_at records the provider's event time when supplied. This preserves both timelines when provider results arrive late or out of order.

When the Business cannot determine the provider outcome - for example, after a provider request times out - it reports the entry as pending. Its later result is appended as a new entry with resolves_entry_id; the pending entry does not change. Failed entries include a Business-defined failure_code and may include a safe explanation.

Retention

The Business may remove older terminal entries from the beginning of an attempt's history. It must retain pending entries and any entries needed by retained references. After removing an entry, it reports
entries_complete: false. Current attempt and instrument summaries remain available when history is incomplete.

All reported amounts use the Order currency.

Risks and Mitigations

• Governance and adoption: The contribution guide normally expects a new extension to establish vendor adoption before entering dev.ucp.*. Mitigation: treat the namespace as proposed and seek Tech Council direction at the Proposal stage.
• Sensitive-data exposure: Provider references and failure messages could expose credentials or raw provider data. Mitigation: limit references to opaque identifiers, prohibit sensitive payment data, and require the Business to sanitize failure messages.
• Payload growth: Append-only entry history can make Orders larger. Mitigation: allow older terminal entries to be discarded and expose entries_complete so consumers know when the retained history is partial.
• Inconsistent summaries: Attempt and instrument summaries duplicate current state and could disagree. Mitigation: define exact reconciliation rules and add conformance cases covering multiple attempts, releases, and capture reversals.
• Approval linkage: JSON Schema cannot verify that an approval_id or adjustment_id resolves within the same Order, or enforce the approved maximum arithmetically. Mitigation: state these as normative requirements and test them in semantic conformance tooling.
• Forward compatibility: Closed enums would make new provider behavior a breaking change. Mitigation: use open strings with well-known values and require implementations to tolerate values they do not understand.
• Backward compatibility: The extension depends on proposed Core fields not present in the current stable release. Mitigation: merge and release the Core proposal first, set accurate requires versions, and activate this extension only through capability negotiation.

Test Plan

• Verify the extension composes correctly with Checkout and Order for each affected request and response.
• Validate examples for automatic and manual capture, single and multiple capture, partial authorization, incremental authorization, release, expiry, reversal, failure, and pending resolution.
• Add negative cases for a missing Checkout approval, an Order-change approval without an adjustment, authorization or capture without approval_id, and a failed entry without failure_code.
• Verify that an existing attempt can continue after an Order-change approval, including incremental authorization and final capture.
• Test summary reconciliation across multiple attempts and incomplete retained history.
• Verify capability authority binding, version requirements, generated schema tables, documentation links, and the full example corpus.

Graduation Criteria

Working Draft → Candidate:

• Schema merged and documented (with Working Draft disclaimer).
• Unit and integration tests are passing.
• Initial documentation is written.
• TC majority vote to advance.

Candidate → Stable:

• Adoption feedback has been collected and addressed.
• Full documentation and migration guides are published.
• TC majority vote to advance.

Implementation History

• [2026-09-10]: Proposal submitted.
• [YYYY-MM-DD]: TC approved "Provisional"; capability enters "Working Draft".
• [YYYY-MM-DD]: TC approved advancement to "Candidate".
• [YYYY-MM-DD]: TC approved "Implemented"; capability enters "Stable".

Code of Conduct

• I agree to follow this project's Code of Conduct

[paulcarey-stripe]

As this proposal is intended to build on #584 and #815, if their corresponding PRs land first, the PR for this proposal would be equivalent to
paulcarey-stripe/ucp@feat/checkout-payment-finality...feat/payment-processing-reporting