Payment Scenarios - Example

Payment Gateway Integration Scenarios with Examples

Technical Integration Scenarios

Gateway Configuration & Setup

Scenario: Multiple Client Tenants with Different DOKU Configurations

Example: City Water Authority uses DOKU merchant ID "CWA001" with 2.5% transaction fee, while Metro Electric uses "MET002" with 2.8% fee and different settlement terms (T+1 vs T+3)
Test Case: Ensure payment from City Water customer routes to correct merchant account and Metro Electric payment doesn't cross-contaminate

Scenario: Sandbox to Production Migration

Example: During UAT, payments work fine with DOKU sandbox API (api-sandbox.doku.com), but production deployment fails because production keys weren't updated in configuration
Test Case: Automated deployment should validate API connectivity before going live

Scenario: API Rate Limiting

Example: During month-end billing (30th-1st), 10,000 customers try to pay simultaneously, hitting DOKU's 100 requests/minute limit
Test Case: Implement queue system with graceful degradation and user messaging

Authentication & Security

Scenario: Token Expiration Mid-Payment

Example: Customer starts payment at 11:58 PM, token expires at 12:00 AM while they're entering card details
Test Case: Auto-refresh token and allow payment to continue without user re-authentication

Scenario: Webhook Signature Verification Failure

Example: DOKU sends payment confirmation webhook, but signature doesn't match due to clock skew between servers
Test Case: Implement signature validation with time tolerance and fallback verification methods

Payment Flow Scenarios

Successful Payment Journeys

Scenario: Standard Utility Bill Payment

Example: John pays his $150 electricity bill using his credit card through the mobile app
Flow: App → Your API → DOKU → Bank → Success webhook → Balance update → SMS confirmation
Test Case: Verify end-to-end flow completes within 30 seconds

Scenario: Multiple Bill Payment

Example: Sarah has overdue electricity ($200), water ($80), and current month electricity ($150). She pays $430 total in one transaction
Test Case: Verify payment allocation: oldest bills first, correct account updates, single transaction fee

Scenario: Recurring Payment Setup

Example: Corporate client ABC Corp sets up auto-pay for monthly $5,000 utility bill on 15th of each month
Test Case: First payment succeeds, creates recurring schedule, subsequent months auto-process

Payment Failure Scenarios

Scenario: Insufficient Funds

Example: Customer attempts $300 payment but bank account has only $250
Expected: DOKU returns error code "INSUFFICIENT_FUNDS", customer sees friendly message: "Payment failed due to insufficient balance. Please try another payment method."
Test Case: Verify error handling, no partial charges, proper user messaging

Scenario: Network Timeout During Processing

Example: Customer hits "Pay Now" but network drops for 45 seconds during DOKU API call
Expected: System shows "Processing..." message, retries 3 times, then shows option to check payment status
Test Case: Ensure no duplicate charges, proper status tracking

Scenario: Card Declined by Bank

Example: International customer's card gets flagged by fraud detection during $1,200 payment
Expected: Clear message about contacting bank, option to try different payment method
Test Case: Verify transaction isn't stuck in pending state

Edge Cases in Payment Processing

Scenario: Duplicate Payment Prevention

Example: Impatient customer taps "Pay" button 5 times rapidly due to slow response
Expected: Only one payment processes, others show "Payment already in progress"
Test Case: Implement transaction deduplication using request IDs
If button is clicked then disable it for 10 sec

Scenario: Payment Processing During Bill Generation

Example: Customer pays outstanding $200 balance at 11:59 PM, but new $150 bill generates at 12:00 AM
Expected: Payment applies to old balance, new bill remains separate
Test Case: Verify payment allocation logic with concurrent bill updates

User Experience Scenarios

End User Mobile App Experience

Scenario: Payment on Low-End Android Device

Example: Customer using 3-year-old Android phone with 2GB RAM tries to pay $89 water bill
Expected: App remains responsive, payment completes despite device limitations
Test Case: Performance testing on minimum supported hardware specifications

Scenario: Offline Payment Initiation

Example: Customer in subway with poor connectivity initiates $125 payment, then loses signal completely
Expected: App queues payment request, processes when connectivity returns, shows appropriate status messages
Test Case: Verify offline queue functionality and sync behavior

Scenario: Payment Receipt Generation

Example: Customer pays $345.67 for combined services and needs receipt for expense reporting
Expected: Immediate PDF receipt generation with all required details, email/SMS delivery options
Test Case: Verify receipt format, accuracy, and delivery mechanisms

Client Backoffice Management

Scenario: Real-time Payment Monitoring Dashboard

Example: During peak hours (6-8 PM), utility manager watches live payment dashboard showing 50 payments/minute success rate
Expected: Live metrics, failure alerts, drill-down capability to specific transactions
Test Case: Dashboard updates within 5 seconds of payment events

Scenario: Monthly Reconciliation Process

Example: Finance team reconciles 45,000 payments totaling $2.3M against DOKU settlement reports
Expected: Automated matching, exception reporting, discrepancy alerts
Test Case: 99.9% auto-reconciliation rate, clear reporting of unmatched items

Business Logic Scenarios

Billing & Account Management

Scenario: Partial Payment Allocation

Example: Customer owes $500 (three bills: $200, $150, $150) but only pays $300
Expected: Payment allocated to oldest bill first ($200 fully paid, $100 to second bill)
Test Case: Verify payment allocation rules, account balance updates, remaining due amounts

Scenario: Advance Payment Handling

Example: Customer pays $600 when current balance is only $400
Expected: $400 clears current balance, $200 creates credit for future bills
Test Case: Credit balance tracking, application to future charges

Scenario: Service Reconnection After Payment

Example: Electricity service disconnected for non-payment, customer pays $850 outstanding balance
Expected: Automatic reconnection request triggered within 2 hours
Test Case: Integration with field service management system

Multi-tenant Considerations

Scenario: Custom Branding Per Client

Example: Metro Electric wants blue theme with their logo, City Water wants green theme with different payment terms display
Expected: Payment pages dynamically styled per client configuration
Test Case: Verify branding isolation, no cross-client style bleeding

Scenario: Different Commission Structures

Example: Client A pays 2.5% transaction fee, Client B negotiated 2.0% for volumes >10K/month
Expected: Correct fee calculation and reporting per client agreement
Test Case: Verify fee calculations in monthly client invoicing

Operational Scenarios

Monitoring & Alerting

Scenario: Payment Gateway Performance Degradation

Example: DOKU response times increase from 2 seconds to 15 seconds during maintenance
Expected: Automatic alerts to operations team, customer messaging about delays
Test Case: SLA monitoring triggers appropriate escalation procedures

Scenario: High Failure Rate Detection

Example: Payment success rate drops from 95% to 70% over 30-minute period
Expected: Immediate alert to technical team, investigation dashboard with failure reasons
Test Case: Automated anomaly detection and notification systems

Scenario: Daily Reconciliation Failures

Example: End-of-day settlement report from DOKU shows $5,000 discrepancy vs internal records
Expected: Automated investigation workflow, transaction-level comparison reporting
Test Case: Discrepancy resolution procedures and escalation paths

Data Management & Reporting

Example: EU customer requests deletion of all payment history data under GDPR Article 17
Expected: Secure deletion across all systems while maintaining financial audit requirements
Test Case: Data anonymization vs deletion procedures, compliance verification

Scenario: Payment Analytics for Business Intelligence

Example: Utility manager wants to analyze payment patterns: peak hours, preferred methods, failure reasons
Expected: Rich analytics dashboard with customizable date ranges and filters
Test Case: Data accuracy in analytics vs transactional systems

Regulatory & Compliance Scenarios

Financial Compliance

Scenario: Large Transaction AML Screening

Example: Corporate customer attempts $50,000 payment triggering anti-money laundering review
Expected: Transaction held pending, compliance workflow initiated, customer notified of delay
Test Case: AML workflow integration, regulatory reporting capabilities

Scenario: Tax Calculation on Payment Fees

Example: Customer in California pays $200 bill with $5 convenience fee requiring sales tax calculation
Expected: Correct tax calculation based on jurisdiction, proper tax reporting
Test Case: Multi-state tax rule engine accuracy

Integration Scenarios

Consumer Information System Sync

Scenario: Account Balance Real-time Updates

Example: Customer pays $300, balance should immediately reflect in customer service system
Expected: Near real-time sync (within 30 seconds), eventual consistency guaranteed
Test Case: Cross-system data consistency verification

Scenario: Service Usage Impact on Payment

Example: High usage month increases bill from typical $150 to $400, payment amount validation
Expected: Dynamic payment amount validation against current billing system data
Test Case: Bill amount consistency across systems

Performance & Scalability Scenarios

Peak Load Handling

Scenario: Month-End Payment Rush

Example: Last day of month, 25,000 customers pay within 4-hour window (6 PM - 10 PM)
Expected: System maintains sub-5 second response times, 99.5% success rate
Test Case: Load testing with realistic user behavior patterns

Scenario: Database Performance Under Load

Example: Payment history queries slow down during high-transaction periods
Expected: Query response times remain under 2 seconds even during peak load
Test Case: Database optimization and indexing strategies

Error Handling & Recovery Scenarios

System Recovery Procedures

Scenario: Payment Status Synchronization After Outage

Example: 2-hour system outage affects 500 in-flight payments, status unknown
Expected: Automated reconciliation process determines actual payment outcomes
Test Case: Payment status recovery procedures, customer communication

Scenario: Orphaned Transaction Handling

Example: Customer charged by DOKU but webhook failed to update your system
Expected: Automated detection and correction within 24 hours
Test Case: Orphan transaction identification and resolution workflows

Scenario: Manual Intervention for Complex Issues

Example: Payment shows successful in DOKU but failed in your system due to data corruption
Expected: Customer service tools for manual payment status correction
Test Case: Admin interface functionality, audit trail maintenance