feat: add return_url for post-handoff buyer return

[sioked]

Summary

• Adds return_url as an optional request field (create/update) on checkout sessions
• Provides a platform-specified destination for the buyer after completing or exiting a hosted checkout UI reached via continue_url
• The redirecting party appends ?status=completed or ?status=canceled as a routing hint; platforms should verify actual session state independently via the checkout session API
• Includes open redirect security guidance recommending businesses validate return_url against known platform origins before redirecting

Motivation

continue_url handles the outbound handoff — business sends buyer to hosted UI. return_url closes the loop — business sends buyer back to the platform after the hosted experience ends. Without it, there is no standard mechanism for a platform to receive the buyer back after a hosted checkout or payment handler redirect.

Category

• Core Protocol: Changes to the base communication layer, global context, or breaking refactors. (Requires Technical 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)

Checklist

• I have followed the Contributing Guide.
• I have updated the documentation (if applicable).
• My changes pass all local linting and formatting checks.
• (For Core/Capability) I have included/updated the relevant JSON schemas.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[jingyli]

Thanks @sioked for raising the PR! Are there any linked issues/discussion threads that describe this issue a bit more? Personally I'm having some hard time gauging whether this concept of return_url is truly needed due to:

1. From business/user experience PoV: Through handoff via continue_url, the buyer is able to continue their actions on business site to either a success (e.g., placing the transaction, finalizing cart, etc.) or failure (e.g., cart/checkout abandonment, rejected transaction upon placement). This would mean they should've already seen some terminal screen, like an order confirmation screen, on business side. What would be the expectation for platform to render when return_url is loaded (loading a duplicated error/confirmation screen on platform side feels odd)? What would be the incentive for businesses to redirect this "concluded" session back to the platform?
2. From platform/data PoV: Buyer handoff via continue_url can occur at various points in the purchase journey - in the most extreme case, it can occur at create_checkout when an error_response is received (meaning there are no checkout resource attached). From platform perspective, there is no way to learn about the complete data expectation from business when return_url is initiated. Calling get_checkout may be one way to get this data snapshot, but it would be infeasible for the extreme case mentioned earlier. Tying back to 1), I'm unsure what will be the expectation for platforms to display as part of the UI that renders via return_url.

Also a general callout - continue_url is a very generic concept that is used by error handling, cart & checkout capabilities today whereas return_url is very checkout specific. Is this intended? Is not, how would it work with the other scenarios?