introduce some kind of action primitive; still a wip

[raginpirate]

Description

Category (Required)

Please select one or more categories that apply to this change.

• Core Protocol: Changes to the base communication layer, global context, or breaking refactors. (Requires Technical Council approval)
• Governance/Contributing: Updates to GOVERNANCE.md, CONTRIBUTING.md, or CODEOWNERS. (Requires Governance Council approval)
• Capability: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
• Documentation: Updates to README, or documentations regarding schema or capabilities. (Requires Maintainer approval)
• Infrastructure: CI/CD, Linters, or build scripts. (Requires DevOps Maintainer approval)
• Maintenance: Version bumps, lockfile updates, or minor bug fixes. (Requires DevOps Maintainer approval)
• SDK: Language-specific SDK updates and releases. (Requires DevOps Maintainer approval)
• Samples / Conformance: Maintaining samples and the conformance suite. (Requires Maintainer approval)
• UCP Schema: Changes to the ucp-schema tool (resolver, linter, validator). (Requires Maintainer approval)
• Community Health (.github): Updates to templates, workflows, or org-level configs. (Requires DevOps Maintainer approval)

Related Issues

Checklist

• I have followed the Contributing Guide (including Conventional Commits title requirements and ! for breaking changes).
• I have updated the documentation (if applicable).
• My changes pass all local linting and formatting checks.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• (For Core/Capability) I have included/updated the relevant JSON schemas.
• I have regenerated Python Pydantic models by running generate_models.sh under python_sdk.

Screenshots / Logs (if applicable)

[aneeshali]

Thanks a lot @raginpirate for this PR. Added a few comments based on the last discussion.

[aneeshali]

The current proposal simplifies the action object by only providing a url (which implies a standard HTTP GET), and relies on the business/PSP to host a same-origin "relay" page if they need to perform a POST or carry rich payloads (like EMVCo's creq or threeDSMethodData). While this keeps the UCP platform implementation simple, it forces the business/PSP to host intermediate relay pages for common flows like 3DS. It might be more robust to allow UCP to transport the request configuration directly.

Please consider expanding the action object to support rich request payloads natively with http method, body, headers, encoding etc.

[raginpirate]

👍 yeah this base shape needed work. I just pushed an update to simplify actions to their core: a rev-dns code + severity + config and opened up some 3ds as an example implementation of an action, with a defined transport mechanism and config in isolation. This is still heavily a WIP but hopefully the rough direction is making sense, and I'm happy to keep gathering this very early feedback!

[aneeshali]

The introduction of the actions primitive significantly alters the Checkout lifecycle and state transition flows. Instead of a single terminal complete_checkout call, we now have multi-step loops. We should explicitly document and visualize these flows where a complete can be followed by an update and a subsequent complete. It might be better to have a dedicated state diagram to capture this variant when actions are involved.

Also wondering if we need to call out any checkout state transitions when actions are involved.

[aneeshali]

I was wondering how we should be documenting the nuances of 3DS challenges so the PSPs have clarity on the exact communication for the following:

• DDC step and its optimization using updateCheckout.
• Passing additional signals to complement the DDC step.
  Should any of these mentioned in the UCP and provided as a guide? OR should it be treated more of the payment handler responsibility, so they can have their own documentation?

[aneeshali]

Thanks a lot @raginpirate for a productive discussion. Left a couple minor comments.

[aneeshali]

Hey @raginpirate while defining only a "pa.done" without any extra payload simplifies the work for the platform, please confirm if there are any security implications with this approach.

[aneeshali]

IIRC, there was a suggestion to also keep a non-3ds example to validate that the solution works more broadly. Student/military discounts and account verification were brought up as examples. It would be great if we could illustrate one such example as well.