# UPI Flow in Version V2

## Overview

The UPI V2 implementation provides a native integration with the Mercury API for UPI QR code payments. It is designed to standardize the QR code generation, payment notification, and status handling, decoupling from the legacy V1 provider. The flow involves generating a QR code, handling payment notifications (webhooks), and updating transaction status.

---

## 1. QR Code Generation

- The client initiates a payment by calling the middle layer controller (`QRMiddleLayerController`) with transaction details.
- The controller validates the request and calls the UPI V2 provider (`UpiV2`) to generate a QR code.
- The `UpiV2` module:
  - Validates required fields.
  - Selects the appropriate Mercury API endpoint based on whether the QR is dynamic (amount specified) or static.
  - Builds and sends a request to the Mercury API.
  - Cleans and processes the QR string received, extracting relevant parameters (e.g., `pa`).
  - Returns a standardized response with QR code data.

- The transaction reference number is cached in `LatestTransactionCache` for later correlation with the webhook.

---

## 2. Payment Notification (Webhook)

- After the customer completes the payment using the QR code, the UPI system sends an XML notification (webhook) to the `/notify_payment` endpoint handled by `UpiWebhookController`.
- The controller:
  - Reads and parses the raw XML to extract attributes like `api` and `reqMsgId`.
  - If the `api` is `"ReqPay"`, it:
    - Retrieves the cached transaction reference.
    - Looks up the transaction in the database using the reference.
    - Logs the notification event.
    - Notifies external systems asynchronously if needed.
    - Clears the cached reference to prevent reuse.
    - Responds with a JSON success message.

---

## 3. Transaction Status Update

- The webhook handler updates the transaction status in the database based on the notification.
- It logs both the receipt and the response of the notification for auditing.
- If the transaction is found and pending, its status is updated to reflect the payment result.

---

## 4. External Notification

- Upon successful payment, the system can notify external systems (e.g., YSP) asynchronously with payment details.

---

## 5. Error Handling

- The system handles missing or invalid attributes in the webhook gracefully, logging errors and returning appropriate HTTP responses.
- All major steps are logged for traceability.

---

## Key Modules

- `DaProductApp.QRProvidersV2.Providers.UpiV2`: Handles QR code generation and provider integration.
- `DaProductAppWeb.UpiWebhookController`: Handles incoming UPI payment notifications.
- `DaProductApp.LatestTransactionCache`: Caches the latest transaction reference for webhook correlation.

---

## Configuration

- UPI provider and Mercury API details are configured in `config.exs` and `dev.exs` under the `:upi_config` key.

---

## Summary

The UPI V2 flow is designed for reliability, traceability, and easy integration with external systems, leveraging a clean separation of concerns and robust logging throughout the process.