Zynka ONE - OCPI vs UPI Integration Specification

1. Introduction

Unified Payments Interface (UPI) has become the dominant digital payment method in India, providing real-time, interoperable transactions between banks and wallets. For electric vehicle (EV) charging, enabling QR-based direct payment simplifies ad-hoc access, removes the need for driver registration, and supports nationwide interoperability.

In this model, each EV charger (EVSE) displays a static QR code that links directly to the payment gateway (PG) associated with a CPO, mediated by Zynka One. Upon successful payment, Zynka One triggers an OCPI START_SESSION command to the CPO’s CMS to initiate charging. The PG is responsible only for payment capture and refunds, while Zynka One handles OCPI coordination. No charger or tariff details are shown within the UPI app—the QR sticker and charger signage provide the necessary information.

---

2. Business Use Case

As a CPO, I want to enable ad-hoc charging through QR-based UPI payments, so that drivers can start and stop charging without requiring app registration.

Actors:

• EV Driver – initiates payment by scanning QR.
• Payment Gateway (PG) – handles UPI collection, webhook notifications, and refunds.
• Zynka One – orchestrates payment confirmation, session start, and settlement via OCPI.
• CPO CMS – receives OCPI commands and reports charging session data.

Preconditions:

• QR code with encoded {tenant, location_id, evse_uid, connector_id} deployed on charger.
• Active OCPI credential exchange between Zynka and CPO.
• PG webhook URL registered in Zynka.

Postconditions:

• Payment confirmation triggers a START_SESSION via OCPI.
• Charging session is initiated, tracked, and billed.
• Refunds are issued automatically for failed or partial sessions.

---

3. Functional Use Cases

Each use case is written in backlog-ready form with actor, flow, and data references.

3.1 Assign QR Codes to Chargers (CPO)

Goal: Map each charger’s connector to a UPI QR code.

Primary Flow:

1. CPO admin uses Zynka portal/API to create mapping for each connector {evse_uid, connector_id, location_id}.
2. Zynka generates static UPI QR including a reference token qr_ref.
3. QR is printed and affixed to the charger.
4. Zynka syncs mapping {qr_ref → EVSE, connector, tenant}.

Alt-Flows: Duplicate QR detected → error returned.

Data: evse_uid, connector_id, tenant_id, qr_ref.

---

3.2 UPI Payment Webhook (PG → Zynka)

Goal: Upon successful payment, PG notifies Zynka to start a session.

Primary Flow:

1. Driver scans QR and pays using their UPI app.
2. Payment Gateway posts webhook to Zynka endpoint /payments/upi/webhook.
3. Zynka validates webhook signature (HMAC), verifies idempotency.
4. Zynka maps qr_ref to charger and creates OCPI start request.

Alt-Flows:

• Payment failed → logged only, no session started.
• Payment pending → queued retry until confirmation.

Data: pg_payment_id, order_id, status, amount, payer_vpa, signature.

---

3.3 Start Session on Payment Confirmation (Zynka → CPO)

Goal: Begin charging upon payment confirmation.

Primary Flow:

1. Webhook verified and mapped to charger.
2. Call OCPI POST /commands/START_SESSION with authorization_reference = payment_id.
3. Await callback or poll commandResponse.
4. On success, link pg_payment_id ↔ session_id.

Alt-Flows: CPO rejects start → refund triggered via PG.

Data: payment_id, evse_uid, connector_id, x-request-id.

---

3.4 Stop Session & Reconciliation (CPO → Zynka)

Goal: Complete session and reconcile energy cost with payment.

Primary Flow:

1. CPO sends OCPI PATCH /sessions → status=COMPLETED.
2. CPO pushes POST /cdrs with energy, duration, and cost.
3. Zynka compares billed cost with payment captured.
4. Refunds or settlements processed if mismatch.

Alt-Flows:

• CDR missing after timeout → alert.
• Cost mismatch → partial refund.

Data: session_id, cdr_id, total_cost, payment_id.

---

3.5 Refund Processing (Zynka → PG)

Goal: Issue refunds when session fails or energy < prepaid cap.

Primary Flow:

1. Identify eligible payment (not linked or underutilized session).
2. Compute refund amount.
3. Call PG POST /payments/upi/refunds API.
4. Record refund in audit table.

Alt-Flows:

• Refund API failure → queued retry.
• Duplicate refund detected → ignored.

Data: refund_id, payment_id, refund_amount, reason.

---

3.6 Receipt Generation (Zynka → Driver)

Goal: Provide driver with digital receipt including payment and charging details.

Primary Flow:

1. Combine PG payment data and OCPI CDR.
2. Generate receipt (PDF/URL/SMS/email).
3. Store for audit reference.

Alt-Flows: Receipt service offline → queue generation.

Data: cdr_id, payment_id, amount, energy_kwh, timestamp.

---

5. Payment Module (UPI Specific)

5.1 Endpoints

• POST /payments/upi/webhook – Receive PG webhook after payment.
• POST /payments/upi/refunds – Process refund API call.

5.2 Objects

• UpiPayment: {id, pg_payment_id, amount, status, capture_time, qr_ref}
• UpiRefund: {id, refund_id, amount, status, reason}

---

6. OCPI Adjustments

OCPI Module	Adjustments
Versions/Credentials	Standard handshake between Zynka and CPO.
Commands	Use START_SESSION and STOP_SESSION with authorization_reference = payment_id.
Sessions	Add payment_reference field to track PG linkage.
CDRs	Include payment correlation; no new fields required.
Locations/Tariffs	Unchanged; used only for signage.
Tokens	Not used in UPI flow; token type OTHER as fallback.

---

7. Traceability Matrix

Use Case	OCPI Entity	Internal API	Outcome
QR Mapping	Locations	/mappings	EVSE↔QR linked
Payment Webhook	N/A	/payments/upi/webhook	Payment verified
Start Session	Commands	/commands/START_SESSION	Charger active
Stop Session	Sessions	/sessions	Session ended
Capture CDR	CDRs	/cdrs	Billing complete
Refund	Payments	/payments/upi/refunds	Customer reimbursed
Receipt	Reports	/receipts	Confirmation delivered

---

8. Summary

This specification defines the UPI-driven ad-hoc charging workflow leveraging OCPI 2.2.1 modules. It simplifies driver experience through QR-based UPI payments while maintaining interoperability via OCPI. Zynka One serves as the eMSP orchestrator, ensuring secure payment-to-session correlation, automated reconciliation, and refund handling.