How UBC Works

API: discover BAP → CDS

The user opens their EV app and either scans a QR code on a charger or searches for nearby chargers. The BAP sends a discover request to the CDS.

QR-Scan Discovery

"message": {
  "filters": {
    "type": "jsonpath",
    "expression": "$[?(@.beckn:itemAttributes.qrIdentifier == 'https://charge.ecopower.in/cs01-ccs2')]"
  }
}

Geographic Discovery

Filters by vehicleType, connectorType, availabilityWindow time range, and spatial geo filter (s_dwithin with Point + distanceMeters).

API: on_discover CDS → BAP

The CDS responds with a catalog of available connectors. If cached data exists, it responds immediately. Otherwise, it fans out to non-caching BPPs who respond individually.

Catalog contents:

• Items (connectors) with: connectorType (CCS2, Type2, CHAdeMO), maxPowerKW/minPowerKW, GPS coordinates, amenityFeature[] (RESTROOM, RESTAURANT, WI-FI), evseId, chargingSpeed (FAST/ULTRAFAST/NORMAL), vehicleType, rating (ratingValue + ratingCount), availabilityWindow
• Offers (tariffs) with: tariffModel (PER_KWH), price (₹45/kWh), idleFeePolicy (₹2 per 10 min idle), acceptedPaymentMethod[] (UPI, CREDIT_CARD, WALLET), validity date range

API: select BAP → BPP

The user selects a charger. The BAP sends select to the BPP that owns that connector.

Payload:

• orderStatus: CREATED
• buyer — id, role, displayName, telephone, email, taxID/GSTIN
• orderItems[] — connector ID + estimated quantity (e.g., 2.5 kWh) + accepted offer
• orderAttributes.buyerFinderFee — {feeType: PERCENTAGE, feeValue: 2.5}
• For reservations: preferences.startTime / endTime

API: on_select BPP → BAP

The BPP returns a pricing quote. orderValue contains exactly 4 component types:

• UNIT — base energy cost (kWh × price)
• SURCHARGE — surge pricing, demand charges
• DISCOUNT — promotions, loyalty
• FEE — service fee, buyer finder fee

If the slot is already booked: orderStatus: REJECTED, error code 40000.

"orderValue": {
  "value": "143.95", "currency": "INR",
  "components": [
    {"type": "UNIT", "value": "112.50"},
    {"type": "SURCHARGE", "value": "40.00"},
    {"type": "DISCOUNT", "value": "-15.00"},
    {"type": "FEE", "value": "6.45"}
  ]
}

API: init BAP → BPP

The user confirms the quote and enters payment details. The BAP sends init with billing information and the buyer's UPI ID.

Payload:

• buyer.buyerAttributes — BuyerUPI extension with vpa field (e.g., ravikumar@upi) — used for refunds
• payment object:
  • amount — pre-authorized amount (e.g., ₹143.95)
  • beneficiary — BPP or BAP (who collects payment — negotiable)
  • paymentStatus: INITIATED
  • paymentAttributes — UBCPaymentAttributes with upiTransactionId and settlementAccounts[]

BAP-Led Payment: If beneficiary: BAP is set, the BAP collects payment directly. The BPP's on_init response is authoritative — if the BPP echoes BAP, BAP collects; if BPP, the BPP retains collection rights.

API: on_init BPP → BAP

The BPP assigns an order.id and returns payment details:

• payment.id, paymentURL, txnRef
• acceptedPaymentMethod[] — UPI, BANK_TRANSFER, WALLET
• settlementAccounts[] — both BAP and BPP beneficiary accounts (accountHolderName, accountNumber, ifscCode, vpa)

UPI-Native Flow: The BPP retrieves a dynamic UPI intent link from the CPO's payment gateway. This is redirection-less — the payment gateway verifies credit in real-time with the UPI network. No browser redirects, no separate payment app switching.

API: on_status (unsolicited) BPP → BAP

Once the payment gateway confirms the UPI transaction, the BPP sends an unsolicited on_status to the BAP:

• paymentStatus: COMPLETED
• paidAt — timestamp of payment confirmation
• paymentAttributes.upiTransactionId — UPI reference number
• orderStatus → PENDING — order is now ready for confirmation

API: confirm BAP → BPP

The BAP confirms the order with orderStatus: PENDING and the COMPLETED payment reference. The BPP locks the connector and prepares for the charging session.

API: on_confirm BPP → BAP

The BPP confirms the booking with orderStatus: CONFIRMED and returns fulfillment details:

• fulfillment.id
• fulfillment.mode: RESERVATION
• deliveryAttributes (@type ChargingSession):
  • connectorType — CCS2, Type2, etc.
  • maxPowerKW — maximum power output
  • sessionStatus: PENDING — waiting for user to plug in

API: status / on_status — Connector Check

Before starting, the BAP can check if the connector gun has been physically connected:

• BAP sends status (order in CONFIRMED state)
• BPP responds with deliveryAttributes.connectorStatus: PREPARING (OCPP status — gun is connected, ready to charge)

API: update BAP → BPP

The user plugs in the connector and taps "Start Charging" in the app. The BAP sends update to begin the session.

API: on_update BPP → BAP

The BPP starts the physical charging session:

• orderStatus: INPROGRESS
• sessionStatus: ACTIVE

API: track / on_track — Live Telemetry

During charging, the BAP can request real-time state-of-charge:

• BAP sends track (order INPROGRESS)
• BPP responds with fulfillment.trackingAction.target.url (session tracking URL) and deliveryAttributes.chargingTelemetry[]

Telemetry metrics:

API: on_update (async/unsolicited) BPP → BAP

The charging session stops when: the battery reaches the cost limit, 100% state-of-charge, or the user manually stops. The BPP sends an unsolicited on_update:

• orderStatus: COMPLETED
• sessionStatus: COMPLETED
• A digital invoice with session summary is issued (invoiceAttributes.invoiceUrl)
• Auto-reconciliation occurs if actual energy consumed differs from the pre-authorized amount

User-Initiated Stop

If the user stops early, the BAP sends update with fulfillment.deliveryAttributes.sessionStatus: STOP. The BPP responds with on_update containing the finalized Charge Detail Record (CDR) reflecting actual energy consumed.

API: rating / on_rating

After the session, the user rates the charging experience:

• ratingValue (1–5 scale, bestRating: 5, worstRating: 1)
• category: FULFILLMENT
• feedback.comments — free-text review
• feedback.tags[] — categorization tags

The BPP responds with received: true and a feedbackForm URL + submission_id for extended feedback.

API: support / on_support

If the user needs help, a structured support flow opens:

• refId (order id), refType: ORDER
• feedback — SupportFeedback extension with comments, tags[] (e.g., ["charging-interrupted", "billing-dispute"])
• supportStatus lifecycle: OPEN → ACKNOWLEDGED → IN_PROGRESS → RESOLVED → CLOSED (or ESCALATED)

API: cancel / on_cancel

Cancellation is only possible while sessionStatus is PENDING (before charging starts). Once ACTIVE, use update with sessionStatus: STOP instead.

• orderStatus: CANCELLED
• payment.beneficiary: BUYER
• paymentStatus: REFUNDED — refund processed to buyer's VPA

Both user-initiated (cancel) and provider-initiated (unsolicited on_cancel) are supported.