Payment Gateway Integration (ONB03US01)

1. Problem Statement

Tenant Admin / Utility Admin:

• Many consumers prefer paying bills in cash.
• Consumers living far from collection centers avoid traveling, causing revenue loss.
• Counting and reconciling cash payments is a time-consuming and error-prone process.

CSO Admin / CSO Executive

• High cash payments make it difficult for CSO Executives / CSO Admins to manually count and reconcile payments with bills.
• Manual reconciliation increases the risk of errors, discrepancies, and delays in financial reporting.
• To access online payments, CSO teams must manually log into bank portals, download transaction reports, and cross-check payments with system records.
• The lack of automation in payment reconciliation results in time-consuming processes and inefficiencies.
• Delays in reconciling payments affect financial transparency and make reporting to higher management slower and less accurate.

Consumers:

• Consumers have to travel long distances to pay bills in cash.
• Those living in other cities or countries face difficulties in making payments.
• Lack of easy online payment options causes delays and missed payments.

Core Problem:

• The current system is slow, manual, and error-prone.
• Consumers struggle to make payments easily.
• Utility and CSO admins face challenges in tracking and reconciling payments.
• Inefficiencies lead to revenue loss and increased administrative work.

2. Who Are the Users Facing the Problem?

Users Facing the Problem

1. Tenant Admin / Utility Admin
   • Responsible for smooth utility operation.
2. CSO Admin / CSO Executive
   • Backoffice user at utility responsible for handling all consumer related issues, payments, complaints and more.
3. Consumers
   • End consumer who uses the utilities
4. Only mentioned roles should be given access to the feature and process.

3. Jobs To Be Done

For Tenant Admin / Utility Admin:

• When I need access to accurate and timely payment data,
• But I receive delayed reports because utility workers take too long to manually count and reconcile cash payments,
• Help me streamline the payment collection and reconciliation process,
• So that I can ensure timely financial tracking, maintain systematic records, and make informed business decisions.

For CSO Admin / CSO Executive

• When I need to reconcile payments and report to higher management,
• But I have to manually count cash, download bank transactions, and cross-check them with system records, which is time-consuming and error-prone,
• Help me automate payment reconciliation and reduce reliance on manual processes,
• So that I can ensure accurate financial records, save time, and provide timely reports.

For Consumers:

• When I need to pay my utility bills,
• But I have to travel long distances or struggle to pay from another city or country,
• Help me access an easy and secure online payment option,
• So that I can pay my bills conveniently without delays or extra effort.

4. Solution

The Smart360 Online Payment System will transform the utility payment experience through a comprehensive, integrated solution:

• Payment Options
  • Supports Stripe and Doku as payment gateways.
  • Enables multiple payment methods (Credit/Debit Cards, Bank Transfers, Digital Wallets).
• Consumer Convenience
  • Eliminates the need for physical travel to pay bills.
  • Allows remote payments for consumers in different cities/countries.
  • Provides instant payment confirmation and downloadable receipts.
• Bill & Service Payments
  • Supports payments for multiple utilities (Water, Wastewater, Electricity).
  • Allows consumers to pay multiple bills/services together or separately.
• Transaction Status & Tracking
  • Displays real-time payment status (Completed, Successful, Failed).
  • Sends notifications (SMS/Email/App) for transaction updates.
  • Enables consumers to view and download payment receipt.
• Automated Reconciliation
  • Automatically fetches and matches payments with system records.
  • Reduces manual reconciliation work for back-office staff.
  • Provides real-time transaction reports for utility admins.
• Revenue & Financial Management
  • Eliminates revenue leakage caused by cash handling inefficiencies.
  • Speeds up revenue tracking and reporting for utility admins.
  • Improves financial accuracy by reducing human errors.
• Security & Compliance
  • Ensures secure transactions through trusted payment gateways.
  • Reduces fraud risks associated with cash handling.
  • Maintains systematic financial records for audits.
• Scalability & Future Expansion
  • Supports integration with additional payment providers if needed.
  • Can handle large volumes of transactions without manual intervention.
  • Adaptable to different regulatory and financial requirements.

5. Major Steps Involved

For Tenant Admin:

• Tenant Admin logs into Smart360 platform using their credentials.
• Navigates to System Configuration section through the main dashboard.
• Selects "Payment Integrations" from the configuration menu.
• Views available payment gateway options (Stripe, DOKU) with current status indicators.
• Activates desired gateway by toggling the activation switch.
• Completes gateway-specific configuration form with required credentials and settings.
• Saves the configuration which triggers automatic validation of provided credentials.
• Initiates a 1 (Currency set in Onboarding) test transaction through the "Pay 1 (Currency set in Onboarding) " function which is refundable.
• Reviews transaction results showing detailed response from the live payment gateway.
• Configures webhook settings to ensure real-time transaction updates.
• Save the configuration options to make them available to utility consumers.

For CSO Admin / CSO Executive:

• Automatic Addition of Online Payments
  • The system detects any payment initiation from CX Web or CX App.
  • Online payments are automatically added to the payments list.
• User Login & Navigation
  • The user logs into SMART360.
  • Navigates to the CX module.
  • Accesses Account Services > Payments to view the list of registered payments.
• Viewing Payment Status
  • The user can view the status of online payments in the payments list.
  • Status updates dynamically based on payment progress (e.g., Completed, Successful, Failed).

For End Consumer:

1. Bill and Service Selection

• User logs into the system and navigates to the "Bill Pay" section.
• The system displays available bills and services.
• The user can search for specific bills or services using the search bar.
• Filtering options allow users to view:
  • All items
  • Bills only
  • Services only
• Each bill/service displays key details:
  • Bill Number
  • Billing Period
  • Amount Due
  • Service Name & Duration (for services)
• The user selects one or multiple items for payment using checkboxes.
• A "Select All" option allows bulk selection of all bills or services.

2. Payment Method Selection

• Once items are selected, available payment methods (Stripe, Doku) are displayed.
• Each payment method is shown with its logo and name.
• The user must select a payment method before proceeding.
• The total amount of selected items is displayed in a sticky footer.
• The "Pay Now" button remains disabled until a payment method is selected.

3. Payment Summary

• The selected payment method and total amount are displayed in a confirmation section.
• Users review transaction details before proceeding.
• Clicking "Pay Now" redirects the user to the selected payment gateway.

4. Payment Processing

• The system redirects the user to the external payment gateway (Stripe/Doku).
• The user completes the payment using the chosen method.
• The system receives payment confirmation and updates the status accordingly.
• The user is redirected back to the platform after payment.

Wireframes

• Tenant Admin (Onboarding) : smartpay-hub
• Consumer (CX App and Web) : billflicks

6. Flow Diagram

Tenant Admin

CSO Admin / CSO Executive

Consumer (Web and App)

7. Business Rules

General Rules:

1. Payment Gateway Activation:
   • System must support multiple active payment gateways simultaneously.
   • At least one payment gateway must be active before the payment system can be used.
   • Gateway activation status must be clearly indicated in the UI through:
     • Each gateway card must display a prominent toggle switch on the right side
     • Active gateways must display the toggle in blue/highlighted state
     • Inactive gateways must display the toggle in gray/unhighlighted state
   • When toggled from inactive to active, the system must immediately display the configuration form
   • The system must visually distinguish between configured and unconfigured gateways
   • Once completed the test transaction connect button should be converted to connected and disabled to click
   • If the details are changed or edited later on, then the connect button should be active again.
   • Once connected payment gateway handshake should be checked everyday and if any error occurs an email should be send to the tenant admin regarding the error.
2. Configuration Management:
   • All sensitive credentials must be stored in encrypted format, specifically:
     • DOKU Gateway: Shared Key, Secret Key, API Key
     • Stripe Gateway: API Key, Secret Key, Webhook Secret
   • System must validate all configuration inputs before saving.
3. Testing Requirements:
   • Users must complete a minimal value of 1 unit (Currency set in Onboarding) in the live environment by clicking the connect button.
   • A successful transaction is required before completing gateway setup.
   • When click on Pay 1 unit (Currency set in Onboarding) user should be navigated to the payment gateway to make the transaction.
   • Once transaction is completed user should be returned to the platform screen form which he navigated to the gateway
   • User should be able to view the transaction result on the screen,
     • Payment Completed → Settlement received successfully.
     • Payment Successful → Payment initiated, awaiting settlement.
     • Failed → Payment not initiated due to:
       • Network error
       • Insufficient funds
       • Technical issue
     • Refund → Amount successfully refunded to the bank account
4. Error Handling:
   • System must provide clear, actionable error messages for failed configurations.
     • Tenant Admin (Connect), Payment gateway connection "Please review all the details entered above and retry to connect"
     • Tenant Admin (Connect), Payment Failed: "Display error description form payment gateway payload and display it to the user"
   • Integration errors must be logged with detailed diagnostic information.
   • Tenant Admins must be notified of persistent connection issues.
   • If no gateway is configured end consumer shouldn't be able to view bill pay option in both CX Web and CX App.
   • When user clicks on pay now and doesn't make any payment and returns back to the platform a failed transaction log should be entered.
   • When end user using the payment gateway to make a payment and failed transaction then consumer should be displayed the exact error that occurred in the payment gateway in the platform too.

End Consumer Payment Rules:

1. Payment Options:
   • Only online payment mode is available for self-service.
   • Both Bill and Service payments must be supported.
   • Bill and Service details must be clearly displayed and fetched form the consumer account details.
2. Payment Gateway Selection:
   • Consumer must be able to select from available payment gateways.
   • Redirect to gateway must maintain session security.
   • Return from gateway must display clear success/failure messages.
3. Transaction Processing:
   • Transactions must be logged in account records.
   • Payable and Outstanding amounts must be updated in real-time.
   • Dashboard summary must reflect new payment totals.
   • Once the payment is successful,
     • System logs transaction in CX > Account Services > Accounts > Specific account > View > Transactions > Payments, with mode as online and status based on the status mentioned below.
     • System logs transaction in CX > Account Services > Payments List, with dynamically updating status.
     • A payment receipt should be available to the respective consumer to download in the payments of History tab of web or app.
     • System should also log failed transactions including with the reason for failure in above mentioned flows.
     • Receipts are only available after the payment is settled which is the status payment completed, until then show payment successful and it will take 2 days to complete the process.

Gateway-Specific Requirements:

Stripe Integration:

• Required Fields:
  • API Key: Valid Stripe API key format (sk_live_*)
  • Secret Key: Valid Stripe secret key format (rk_live_*)
  • Webhook URL: Auto-generated by system, must be copied to Stripe dashboard
  • Webhook Secret: Valid Stripe webhook secret format (whsec_*)
  • Public Key: Valid Stripe public key format (pk_live_*)
  • Currency Support: Must match tenant's configured currency
• Validation Rules:
  • API Key must be validated against Stripe API before saving
  • System must verify webhook functionality during setup

DOKU Integration:

• Required Fields:
  • Mall ID: Numeric identifier provided by DOKU
  • Shared Key: Alphanumeric security key
  • Chain Merchant ID: Numeric identifier for merchant group
  • API Key: DOKU-provided API access key
  • Secret Key: DOKU-provided secret for signature generation
  • Webhook URL: Auto-generated by system
  • Currency Support: Must match tenant's configured currency
• Validation Rules:
  • Mall ID must be numeric and 8 characters long
  • System must validate credentials with DOKU API call
  • Chain Merchant ID must be associated with the provided Mall ID

Transaction Processing Rules:

1. Bill & Service Selection Rules

• Users must be authenticated to access bill and service selection.
• The system should display only the bills and services belonging to the logged-in user.
• Selection of at least one bill or service is mandatory for proceeding to payment.

2. Payment Method Selection Rules

• Only supported payment methods (Stripe, Doku) should be displayed.
• The "Pay Now" button remains disabled until a payment method is selected.
• The total amount must be recalculated dynamically based on selected items.

3. Payment Processing Rules

• Payment initiation should redirect the user to the selected gateway securely.
• Users should be redirected back to the platform after payment completion.
• If the payment fails, the system should display an error message with retry options.
• A payment timeout should trigger a failed status if the gateway does not respond within a specified time.

4. Transaction Status Rules

The system should update the transaction status in real time based on payment outcomes:

• Payment Completed → Settlement received successfully.
• Payment Successful → Payment initiated, awaiting settlement.
• Failed → Payment not initiated due to:
  • Network error
  • Insufficient funds
  • Technical issue
• Once the payment is successful the payment record should be logged into the following with the correct statuses
  • CX > Account Services > Accounts > Particular Consumer > View > Tranasctions > Payments
  • CX > Account Services > Payments
  • CX Web > History > Payments
  • CX App > History > Payments
  • Status of the payment can be tracked here in the status column
• Once the payment is completed the bill must be cleared

5. Navigation & Error Handling Rules

• Users can navigate back to previous steps without losing selections.
• If an error occurs during payment processing, the system should display an appropriate error message with retry options.

6. User Interface Requirements:

1. Gateway Selection:
   • Available gateways must be displayed with clear visual indicators
   • Active/inactive status must be immediately apparent through toggle switch color (blue for active, gray for inactive)
   • Configuration forms must be hidden until gateway is toggled on
2. Form Validation:
   • All fields must validate in real-time with clear error messages
   • Required fields must be visually indicated
   • Form submission must be prevented if validation fails
3. Connect:
   • Connect button must be prominently displayed
   • Results must show detailed gateway response
   • Success/failure status must be clearly indicated with appropriate colors

7. Sample Data

• Tenant Admin
• • Configuration Fields (For Stripe):
    • API Key: sk_live_12hdiw7xg8sd8sd
    • Secret Key: rk_live_98hsd72hsj6sda2
    • Webhook Secret: whsec_182gs627hsbd8
    • Public Key: pk_live_gs6dg3g672gq
    • Currency: Auto fetched from onboarding
  • Configuration Fields (For Doku):
    • Mall ID: 12345678
    • Shared Key: abcd1234xyz
    • Chain Merchant ID: 87654321
    • API Key: doku_key_190sd72hshd
    • Secret Key: doku_secret_ks7291bdka
    • Currency: Auto fetched from onboarding
• End Consumer
  • Bill & Service Selection Page:
    • Bill Number: BILL7890
    • Billing Period: March 2025
    • Amount Due: $120.50
    • Service Name: Water Supply
  • Payment Options:
    • Stripe (Selected by Default)
    • Doku
  • Payment Summary:
    • Selected Bill(s): BILL7890
    • Total Amount: $120.50
    • Selected Payment Method: Stripe
  • "Pay Now" Button (Disabled Until Payment Method is Selected)
• CSO Admin / Executive
  • Account No: CRN29391
  • Name: Isidro Garcia
  • Type: Services
  • Amount: $120.50
  • Mode: Online
  • TXN ID: TXN12345
  • TXN Date: 2025-03-26
  • Created On: Same as TXN Date
  • Created By: Same as Name
  • Status: Payment Completed

8. Acceptance Criteria

• The system must allow multiple payment gateways to be active at the same time.
• At least one payment gateway must be active before any payments can be processed.
• Each payment gateway must have a toggle switch: blue for active, gray for inactive.
• When a gateway is toggled on, the system must display the configuration form.
• Users must enter valid credentials before they can activate a gateway.
• The system must store sensitive credentials in encrypted format.
• All configuration inputs must be validated before saving.
• Users must complete a 1-unit payment transaction to verify a gateway before activation.
• If the test transaction fails, users must retry before proceeding.
• Transactions must be logged in account records and update outstanding amounts in real time.
• The dashboard summary must reflect updated payment totals.
• Payment receipts must be generated only for successfully completed transactions.
• The system must update transaction statuses in real time: Completed, Successful, Failed.
• If a session expires, users must be prompted to reinitiate the process.
• Clear error messages must be displayed for failed payments.
• The Connect button must be prominently displayed.
• Success messages must be shown in green, and failure messages in red.
• When a payment is initiated from CX Web or CX App, the system must automatically detect and add it to the payments list.
• Online payments must appear in the payments list without requiring manual entry.
• Users must be able to view the status of each payment in the list.
• The system must dynamically update payment status through all stages (Completed, Successful, Failed).

9. Process Changes

1. Payment Collection:
   • From: Manual tracking of payments through spreadsheets and emails
   • To: Automated real-time tracking through integrated payment gateways
   • Impact: Reduces payment processing time and eliminates manual errors
2. Reconciliation:
   • From: Manual matching of payments to invoices on a weekly basis
   • To: Automated real-time reconciliation as payments are processed
   • Impact: Improves financial accuracy and provides daily financial clarity
3. Reporting:
   • From: Manual compilation of payment reports from multiple sources
   • To: Automated consolidated reporting with real-time data
   • Impact: Reduces reporting time from days to minutes and improves data consistency
4. Error Resolution:
   • From: Reactive troubleshooting after customer complaints
   • To: Proactive monitoring with immediate error detection and resolution
   • Impact: Reduces payment disputes and improves customer satisfaction
5. Audit Preparation:
   • From: Time-intensive gathering of payment records for audit
   • To: Instant access to comprehensive audit trails and transaction logs
   • Impact: Reduces audit preparation time and improves compliance confidence
6. Gateway Management:
   • From: IT-dependent configuration requiring technical expertise
   • To: Self-service configuration by Tenant Admins
   • Impact: Reduces implementation time from weeks to hours and empowers business users
7. In-Person Payment Collection:
   • From: Manual receipt generation and paper record-keeping
   • To: Integrated digital payment processing with automatic receipt generation
   • Impact: Reduces in-person payment processing time and eliminates paper records
8. Consumer Self-Service:
   • From: Phone or in-person payments requiring staff assistance
   • To: Self-service web and mobile payment options
   • Impact: Reduces customer support volume and improves consumer satisfaction

10. System Design Details

New Components:

1. Transaction Processing Engine:
   • Purpose: Manages the complete lifecycle of payment transactions
   • Key Features:
     • Asynchronous processing for high throughput
     • Idempotent operations to prevent duplicate transactions
     • Configurable workflow for different payment types
     • Transaction correlation for end-to-end tracing
2. Webhook Management System:
   • Purpose: Handles incoming gateway notifications and events
   • Key Features:
     • Signature verification for security
     • Event normalization across gateways
     • Retry mechanisms for failed event processing
     • Event logging for troubleshooting
3. Consumer Self-Service Portal:
   • Purpose: Provides online payment capabilities for end consumers
   • Key Features:
     • Bill and service payment options
     • Gateway selection interface
     • Payment history display
     • Real-time balance updates

Affected Components:

1. Tenant Admin Dashboard:
   • Changes: New payment management section with configuration controls
   • Integration Points: User authentication, role-based permissions
   • UI Updates: Payment gateway cards, configuration forms, test controls
2. Invoice Management System:
   • Changes: Payment status integration, automatic reconciliation
   • Integration Points: Transaction webhooks, payment status updates
   • Data Flow: Bi-directional updates between invoices and payments
3. Customer Experience Module:
   • Changes: Payment method selection, transaction status display
   • Integration Points: Payment gateway APIs, transaction status updates
   • UX Improvements: Streamlined checkout process, clear payment status
4. Reporting Engine:
   • Changes: New payment-specific reports, dashboard widgets
   • Integration Points: Transaction database, payment analytics
   • New Capabilities: Cross-gateway reporting, custom payment analytics

11. Impact from Solving This Problem

High-Level Metrics Impacted:

✅ Retention -- Improves Tenant Admin satisfaction through streamlined financial processes and reduced manual work.

✅ Adoption -- Increases platform usage as users engage more frequently with the centralized payment system.

✅ User Experience -- Reduces payment-related support tickets through intuitive interfaces and automated processes.

✅ Speed -- Decreases payment processing time and reconciliation time through automation.

✅ Accuracy -- Reduces payment errors through systematic validation and automated matching.

✅ No Silos -- Eliminates information gaps between departments by providing a single source of truth for payment data.

12. User Behavior Tracking

User Behavior Tracking Plan for Payment Gateway Integration (ONB03US01)

1) Tenant Admin / Utility Admin - User Behavior Tracking Plan

Objective: Track how Tenant Admins and Utility Admins configure and manage payment gateways.

Key Insights:

• Are Tenant Admins activating and configuring payment gateways successfully?
• How frequently do they review payment reconciliation reports?
• Are test transactions being completed before activation?

2) CSO Admin / CSO Executive - User Behavior Tracking Plan

Objective: Track how CSO Admins and Executives reconcile payments and handle consumer transactions.

Key Insights:

• How frequently do CSO Admins search for and validate payments?
• Are payments being reconciled on time?

3) Consumer (CX Web & CX App) - User Behavior Tracking Plan

Objective: Track consumer interactions with the online payment system.

Key Insights:

• How frequently do consumers initiate online payments?
• What percentage of payments are successfully completed?
• Are consumers checking payment history regularly?

This tracking plan will help analyze user interactions and improve the efficiency of the payment gateway integration