feat: Add Payment Authentication Actions

[raginpirate]

Description

Introduces dev.ucp.shopping.payment_authentication, a Checkout extension defining standard browser-surface Actions for payment authentication:

• dev.ucp.payment.device_data_collection
• dev.ucp.payment.three_ds_challenge

This PR is stacked on #582, which defines the common extension-owned Actions primitive. Payment Authentication contributes the concrete Action types, config, rendering behavior, security requirements, notification protocol, deadlines, and Checkout integration needed for DDC and 3DS challenges.

The approach

EMVCo defines the interaction between the issuer’s ACS and the merchant’s 3DS provider, mediated by the cardholder’s device and card-network Directory Server. Businesses and platforms do not have to be involved directly in this specification; often Payment Providers create an abstraction layer around the concerns of the EMVco spec. With this world view in mind, UCP attempts to standardize the abstraction layer that businesses and payment providers truly need to offer when handling 3DS and DDC on arbitrary business OR platform surfaces; a simple signal pattern to resolve or reject the action.

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

#517
#582

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.

[aneeshali]

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

[aneeshali]

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

[kmfreeman]

rather than having a separate postMessage design for UCP and our own direct integration or clientside SDK use we would likely add key:values in the postMessage for our own purposes. I would hope/assume these would be ignored by UCP?

these could be additional identifiers for support purposes or expanding on the detail of the outcome e.g. authenticated, rejected, unavailable....

[raginpirate]

Yup totally; additional properties is the supported default for any object passed over UCP. This can empower you to adhere to the subset standard while growing the superset and I'd advocate you can always push for more of that superset when it makes sense for that information to live with the platform and not just the business!

[kmfreeman]

@raginpirate sorry if this is a bit late but a few additional thoughts came up now I'm getting in to the details of feature creation:

• should method actually be result as this is the one direction postMessage?
• if you make result (or method if I'm wrong) an object the design becomes more open in terms of allowing others to use the standard jsonrpc result design e.g.

{
  "jsonrpc": "2.0",
  "result": {
    "event": "pa.done",  // used by UCP
    "outcome": "3dsAuthenticated",  // could be any key:value for use by the gateway e.g. used by clientside SDK
  },
  "id": 1
}

This is all within the context of wanting to have a single postMessage design for both direct 3ds integration (with the gateway) and extending it for UCP usage

Also means that for other postMessages we plan to omit such as when a challenge is required we can just remove the event from the result object as UCP does not need to react to this
we would probably add pa.challenged or pa.prompt instead so can be parsed reliably for the challenge case

[raginpirate]

Thanks @kmfreeman — using one postMessage design for both direct gateway integrations and UCP is definitely the goal!

I believe method is the correct JSON-RPC shape here. This is because we're expecting the frame to postMessage that event to the parent page, and result is undefined because there is no expected response to carry back to the parent page after receiving it.

Additional params such as outcome or provider correlation data can still support a direct gateway SDK. UCP Platforms only process the fields defined by the active Action contract and ignore other params.

[aneeshali]

Thanks Daniel for driving this alignment across may parties.

[aneeshali]

Really appreciate the work on this and the related discussions, @raginpirate. Left a couple of comments to fully understand the implementation specifics.

[aneeshali]

With the approach to complete the flow by calling Get Checkout rather than Complete Checkout, please confirm if the expectation is that the Platform can only perform 2 things:

• Resume the flow if further actions are needed, like proceed with challenge once DDC is complete.
• Mark the flow as completed if the Get Checkout returns a response similar to a successful non-3DS complete checkout call.

I'm wondering how will some of the failure cases be handled gracefully in this scenario. For example, if 3DS fails for whatever reason, the platform will make a subsequent Get checkout call, and the merchant may repeatedly return the same action payload as before. If the platform wants to let the user choose a different payment method or similar remedies, there may not be a way to do it in this scenario. Please share your thoughts on how such cases can be handled.

[raginpirate]

If the Business learns a terminal provider outcome, it must remove the original Action, replace it with new work under a new ID, or advance the Checkout. It must not keep returning an occurrence that can no longer be processed, and the Platform must not reopen the same occurrence.

An incomplete Checkout can still be updated to select another instrument. Once Complete Checkout has been accepted and the Checkout is complete_in_progress, Update and another Complete are intentionally unavailable. Recovery at that point follows the handler fallback, buyer handoff through continue_url, or cancellation and creation of a new checkout.

[aneeshali]

Some PSPs are adopting a slightly different approach for their merchants in the standard 3DS flows. They provide a single URL, which performs device data collection in a visible manner with some standardized loading screen. Depending on the result of DDC, they may either redirect the user to a challenge UI or just complete the flow and pass the control back to the merchant. We could either consider this as a subcase of three_ds_challenge or we could call out as a separate option. I think what the loading screen will look like is out of scope of this PR but providing clarity on that scenario will be helpful considering this is a relevant pattern.

[raginpirate]

One wrapper URL may orchestrate both provider steps. If the surface may ever become buyer-visible, the Business emits a three_ds_challenge Action, because honestly thats what they are doing as the action (ddc is simply a side-effect of their modal's purpose). A device_data_collection Action must remain invisible throughout its lifetime and should only be used by providers that do separate the steps.

[raginpirate]

👋 I’ve force-pushed now that the base Actions primitive has landed.

The update aligns with the landed Action and Checkout lifecycle contracts:

• Removed the old occurrence-level required concept; each Action type statically defines what it gates.

Additional improvements I pushed in here:

• Signal the payment instrument id so its clear which element we're acting on.
• Added an action.ready handshake for both surfaces. The frame identifies the Action and extension version, and waits for acknowledgment before beginning work. better matching how all embedded protocols work in the spec today.
• Clarified origin validation, rendering isolation, reconciliation, fallback, and handler-authoring requirements.