feat(payments): add UPI Collect support and core payment sync

[g-divyanshu]

Summary

Add UPI Collect as a supported payment method in A2A human-in-the-loop
scenarios. UPI is a widely used real-time payment system in India. Introduces
a mock bank server to simulate MCA flows and enables async payment completion
via status polling.

Changes (by role)

Mock Bank

• Add a mock bank server to simulate issuer-side payment behavior
• Provide a web UI to approve/reject UPI Collect requests
• Add APIs/utilities for creating transactions and syncing status

Merchant Agent

• Route UPI Collect payments to the payment processor where applicable

Shopping Agent

• Add UPI Collect as a supported payment method in checkout flows
• Construct PaymentMandates with the correct method_name/details for UPI Collect

Merchant Payment Processor Agent

• Add UPI Collect payment initiation support
• Implement sync_payment polling to resolve MCA payments asynchronously
• Handle MCA flows without OTP/credential challenge paths

Credentials Provider Agent

• Update method support/metadata as needed for UPI Collect flows

Scenarios & Docs

• Add an A2A human-present UPI Collect scenario (README + runner script)

Behavior

• UPI Collect payments remain pending until externally approved
• Uses multi-channel authentication (MCA)
• Tasks stay in working state while awaiting approval
• No OTP / requires_input / requires_auth for this flow

Flow Testing

• Run entire flow using: bash samples/python/scenarios/a2a/human-present/upi_collect/run.sh
• Approve payment via mock bank UI

Notes

• Mock bank is for development/testing only
• No breaking changes

[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.

[gemini-code-assist]

Summary of Changes

Hello @g-divyanshu, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the agent payments protocol sample by integrating UPI Collect payment functionality. It establishes a new mock bank server to simulate UPI transactions and their lifecycle, from initiation to approval. The changes also involve updating various agent roles to seamlessly handle UPI Collect payments, including managing multi-channel authentication challenges and implementing asynchronous payment status polling. This allows for a complete demonstration of UPI Collect payments in a human-present commerce flow.

Highlights

• UPI Collect Payment Support: Introduced comprehensive support for UPI Collect payments, including a new mock bank server to simulate UPI transactions and their approval process.
• Asynchronous Payment Synchronization: Implemented core payment synchronization logic for UPI Collect payments, enabling agents to poll the mock bank for transaction status updates and handle Multi-Channel Authentication (MCA) challenges.
• New Mock Bank Server: Added a dedicated Flask-based mock bank server with REST API endpoints for creating, retrieving, and updating payment transactions, along with a web-based UI for manual transaction approval/decline.
• Agent Role Updates: Modified the Credentials Provider, Merchant Agent, Merchant Payment Processor Agent, and Shopping Agent roles to integrate UPI Collect as a payment method, manage MCA challenges, and perform payment status polling.
• New Sample Scenario: Provided a new end-to-end sample scenario (human-present/upi_collect) demonstrating a human-present UPI Collect purchase flow, complete with setup scripts and interaction guides.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces support for UPI Collect payments and a core payment synchronization mechanism. The changes are comprehensive, including a new mock bank server, extensive documentation, and updates across multiple agents to handle the asynchronous UPI payment flow. My review focuses on improving documentation consistency, adhering to code style best practices, and fixing a critical import error. Overall, this is a well-executed feature with a high level of detail in both implementation and documentation.

[gemini-code-assist]

The comment // Optional section uses a C-style comment format within a Python docstring. While this doesn't break anything, the standard comment character in Python is #. For consistency with Python's style, it's better to use #. This also applies to the comment on line 48.

Suggested change

	"customer_data": { // Optional section
	"customer_data": { # Optional section