Mock Paystack DVA Repayment Flow for Driver Hire Purchase (#24)

[mimijuwonlo-commits]

Mock Paystack DVA Repayment Flow for Driver Hire Purchase (#24)

Summary

This PR introduces a mock Paystack Dedicated Virtual Account (DVA) repayment flow to support local development and testing without requiring live Paystack credentials or API access.

When ENABLE_MOCK_PAYMENTS=true, DVA provisioning bypasses Paystack entirely and returns deterministic, clearly identifiable test account details. The Driver Repayment Center also exposes a local-only simulator that allows developers and QA to create mock repayments using the existing repayment processing workflow.

Changes

New Files

• lib/services/paystack-mock.service.ts

  • isMockPaymentsEnabled()

  • isMockPaymentsRuntimeAllowed()

  • createMockDriverDvaDetails()

  • createMockDvaRepaymentReference()

  • buildMockDedicatedNubanWebhookPayload()

• app/api/driver/payments/mock-repay/route.ts

  • Development/test-only endpoint for simulating incoming DVA transfers

  • Disabled in production

• components/dashboard/driver-hire-purchase/mock-repayment-simulator.tsx

  • UI component for triggering mock repayments from the Repayment Center

• lib/services/__tests__/paystack-mock.service.test.ts

  • Unit tests covering mock account generation, references, runtime guards, and webhook payload creation

Updated Files

• lib/services/paystack-dva.service.ts

  • Short-circuits to mock DVA provisioning when mock payments are enabled

  • Adds isMock and mockReference metadata to account snapshots

• app/api/driver/virtual-account/route.ts

  • Returns mock metadata in API responses

• app/dashboard/driver/repayment/page.tsx

  • Displays mock account indicators and simulator UI

• driver-virtual-account-card.tsx

  • Adds mock account badges and test-only messaging

• .env.example

  • Documents ENABLE_MOCK_PAYMENTS

• CONTRIBUTING.md

  • Adds setup and usage instructions for mock payment testing

How It Works

Mock DVA Provisioning

When:

ENABLE_MOCK_PAYMENTS=true

the application:

• Skips all Paystack DVA provisioning requests

• Does not require PAYSTACK_SECRET_KEY

• Returns deterministic mock account details

• Marks generated accounts as mock/test-only

Example:

• Bank: Mock Test Bank

• Provider: mock-paystack

• Account Number: 0000xxxxxx

Mock Repayment Simulation

The Repayment Center displays:

• Mock Test Account badge

• Mock account details

• Test-only alert messaging

• Simulate Mock Transfer action

Submitting a simulated repayment processes the payment through the existing repayment workflow:

• createAndConfirmDriverTransferPayment()

• confirmDriverPayment()

This ensures repayment behavior remains consistent with production processing logic.

Security

Mock functionality is restricted through multiple safeguards:

• Mock repayment endpoint requires:

  • ENABLE_MOCK_PAYMENTS=true

  • NODE_ENV !== "production"

• Mock account payloads are explicitly tagged:

{
  mock: true,
  testOnly: true
}

• Production Paystack behavior remains unchanged when the feature flag is disabled.

Testing

Unit Tests

Added 5 unit tests covering:

• Mock enablement checks

• Runtime restrictions

• Deterministic account generation

• Reference generation

• Webhook payload creation

All new tests are passing.

Manual Testing

1. Add to .env.local:

ENABLE_MOCK_PAYMENTS=true

2. Start the application.

3. Navigate to:

Driver → Repayment Center

4. Verify:

   • Mock Test Account badge is displayed

   • Bank name is Mock Test Bank

   • Account number begins with 0000

   • Simulate Mock Transfer button is visible

5. Submit a mock repayment and verify the repayment is recorded and applied to the contract balance.

Acceptance Criteria

Criterion | Status -- | -- Driver repayment account works in mock mode | ✅ No real Paystack API calls when mock mode is enabled | ✅ Mock account details are clearly identifiable | ✅ Existing Paystack flow unchanged when mock mode is disabled | ✅

Notes

• New files are lint-clean.

• Unit tests pass.

• Existing repository lint/typecheck/build issues are pre-existing and unrelated to this change.

close #24

[Obiajulu-gif]

@mimijuwonlo-commits great work, can you show the output of your changes