Learning Objectives

Build electricity payment with meter verification
Create cable TV subscription flow
Handle verification before purchase
Display tokens and confirmation

1. Electricity Payment Page

The electricity payment page is an async server component that pre-fetches the list of electricity distribution companies before rendering. This ensures users see the provider dropdown immediately without waiting for a client-side fetch.

// app/(dashboard)/services/electricity/page.tsx
import { getElectricityProviders } from '@/lib/rizpay/services'
import ElectricityForm from '@/components/services/ElectricityForm'

export const metadata = {
  title: 'Pay Electricity Bill | RizPay',
}

export default async function ElectricityPage() {
  const providers = await getElectricityProviders()

  return (
    <div className="max-w-lg mx-auto">
      <h1 className="text-2xl font-bold mb-6">Pay Electricity Bill</h1>
      <div className="bg-white rounded-xl shadow-card p-6">
        <ElectricityForm providers={providers} />
      </div>
    </div>
  )
}

2. Electricity Form Component

The ElectricityForm component implements a three-step flow for electricity payments: meter details entry, verification display with amount input, and final confirmation. This multi-step approach is essential for electricity payments because meter numbers must be verified before payment to ensure the funds go to the correct account.

The verifyMeter function calls the API to validate the meter number and retrieve customer information. The component maintains state for all form fields and uses conditional rendering to display the appropriate step based on the current state.

// components/services/ElectricityForm.tsx
'use client'

import { useState } from 'react'
import { useActionState } from 'react'
import { purchaseElectricityAction } from '@/actions/services'
import { Button, Input, Select } from '@/components/ui'
import { formatCurrency } from '@/lib/utils'

interface Provider {
  id: string
  name: string
}

interface MeterInfo {
  customerName: string
  address: string
  meterNumber: string
  meterType: string
}

interface ElectricityFormProps {
  providers: Provider[]
}

export default function ElectricityForm({ providers }: ElectricityFormProps) {
  const [disco, setDisco] = useState('')
  const [meterNumber, setMeterNumber] = useState('')
  const [meterType, setMeterType] = useState<'prepaid' | 'postpaid'>('prepaid')
  const [phone, setPhone] = useState('')
  const [amount, setAmount] = useState('')
  const [meterInfo, setMeterInfo] = useState<MeterInfo | null>(null)
  const [verifying, setVerifying] = useState(false)
  const [step, setStep] = useState<'form' | 'verify' | 'confirm'>('form')

  const [state, formAction, isPending] = useActionState(
    purchaseElectricityAction,
    { success: false, message: '', token: '' }
  )

  const verifyMeter = async () => {
    if (!disco || !meterNumber) return

    setVerifying(true)
    try {
      const response = await fetch('/api/services/verify-meter', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ disco, meterNumber, meterType }),
      })

      if (!response.ok) {
        throw new Error('Meter verification failed')
      }

      const data = await response.json()
      setMeterInfo(data)
      setStep('verify')
    } catch (error) {
      alert('Could not verify meter. Please check the details.')
    } finally {
      setVerifying(false)
    }
  }

  // Step 1: Enter details
  if (step === 'form') {
    return (
      <div className="space-y-6">
        <Select
          label="Distribution Company"
          name="disco"
          value={disco}
          onChange={(e) => setDisco(e.target.value)}
          options={providers.map(p => ({ value: p.id, label: p.name }))}
          placeholder="Select your electricity provider"
          required
        />

        <div>
          <label className="block text-sm font-medium text-gray-700 mb-2">
            Meter Type
          </label>
          <div className="grid grid-cols-2 gap-4">
            {(['prepaid', 'postpaid'] as const).map((type) => (
              <button
                key={type}
                type="button"
                onClick={() => setMeterType(type)}
                className={`py-3 rounded-lg border-2 font-medium capitalize transition ${
                  meterType === type
                    ? 'border-primary bg-primary/5 text-primary'
                    : 'border-gray-200 hover:border-gray-300'
                }`}
              >
                {type}
              </button>
            ))}
          </div>
        </div>

        <Input
          label="Meter Number"
          name="meterNumber"
          value={meterNumber}
          onChange={(e) => setMeterNumber(e.target.value)}
          placeholder="Enter your meter number"
          required
        />

        <Button
          type="button"
          onClick={verifyMeter}
          loading={verifying}
          className="w-full"
          disabled={!disco || !meterNumber}
        >
          Verify Meter
        </Button>
      </div>
    )
  }

  // Step 2: Confirm meter and enter amount
  if (step === 'verify' && meterInfo) {
    return (
      <div className="space-y-6">
        <div className="bg-green-50 border border-green-200 rounded-lg p-4">
          <p className="text-sm text-green-600 font-medium mb-2">
            Meter Verified Successfully
          </p>
          <div className="space-y-1 text-sm">
            <p><span className="text-gray-600">Name:</span> {meterInfo.customerName}</p>
            <p><span className="text-gray-600">Address:</span> {meterInfo.address}</p>
            <p><span className="text-gray-600">Meter:</span> {meterInfo.meterNumber}</p>
          </div>
        </div>

        <Input
          label="Phone Number"
          name="phone"
          type="tel"
          value={phone}
          onChange={(e) => setPhone(e.target.value)}
          placeholder="08012345678"
          hint="For token delivery"
          required
        />

        <Input
          label="Amount"
          name="amount"
          type="number"
          value={amount}
          onChange={(e) => setAmount(e.target.value)}
          placeholder="Enter amount"
          min={1000}
          max={500000}
          required
        />

        <div className="flex gap-4">
          <Button
            type="button"
            variant="outline"
            onClick={() => {
              setStep('form')
              setMeterInfo(null)
            }}
            className="flex-1"
          >
            Back
          </Button>
          <Button
            type="button"
            onClick={() => setStep('confirm')}
            className="flex-1"
            disabled={!phone || !amount}
          >
            Continue
          </Button>
        </div>
      </div>
    )
  }

  // Step 3: Confirm and pay
  if (step === 'confirm' && meterInfo) {
    return (
      <div className="space-y-6">
        <h2 className="text-lg font-semibold">Confirm Payment</h2>

        <div className="bg-gray-50 rounded-lg p-4 space-y-3">
          <div className="flex justify-between">
            <span className="text-gray-600">Customer</span>
            <span className="font-medium">{meterInfo.customerName}</span>
          </div>
          <div className="flex justify-between">
            <span className="text-gray-600">Meter Number</span>
            <span className="font-medium">{meterNumber}</span>
          </div>
          <div className="flex justify-between">
            <span className="text-gray-600">Type</span>
            <span className="font-medium capitalize">{meterType}</span>
          </div>
          <div className="flex justify-between">
            <span className="text-gray-600">Phone</span>
            <span className="font-medium">{phone}</span>
          </div>
          <div className="border-t pt-3 flex justify-between">
            <span className="font-semibold">Amount</span>
            <span className="font-bold text-lg">
              {formatCurrency(Number(amount))}
            </span>
          </div>
        </div>

        {state.message && (
          <div className={`p-4 rounded-lg ${
            state.success ? 'bg-green-50 text-green-700' : 'bg-red-50 text-red-700'
          }`}>
            {state.message}
            {state.token && (
              <div className="mt-2 p-3 bg-white rounded font-mono text-lg">
                Token: {state.token}
              </div>
            )}
          </div>
        )}

        <form action={formAction}>
          <input type="hidden" name="disco" value={disco} />
          <input type="hidden" name="meterNumber" value={meterNumber} />
          <input type="hidden" name="meterType" value={meterType} />
          <input type="hidden" name="phone" value={phone} />
          <input type="hidden" name="amount" value={amount} />
          <input type="hidden" name="customerName" value={meterInfo.customerName} />

          <div className="flex gap-4">
            <Button
              type="button"
              variant="outline"
              onClick={() => setStep('verify')}
              className="flex-1"
            >
              Back
            </Button>
            <Button type="submit" loading={isPending} className="flex-1">
              Pay {formatCurrency(Number(amount))}
            </Button>
          </div>
        </form>
      </div>
    )
  }

  return null
}

3. Cable TV Payment Page

The cable TV payment page defines the available providers statically since the list of cable TV providers changes infrequently. Each provider includes an id, name, and logo emoji for visual representation in the selection grid.

// app/(dashboard)/services/cable/page.tsx
import CableForm from '@/components/services/CableForm'

export const metadata = {
  title: 'Pay Cable TV | RizPay',
}

const providers = [
  { id: 'dstv', name: 'DSTV', logo: '📡' },
  { id: 'gotv', name: 'GOtv', logo: '📺' },
  { id: 'startimes', name: 'StarTimes', logo: '⭐' },
]

export default function CablePage() {
  return (
    <div className="max-w-lg mx-auto">
      <h1 className="text-2xl font-bold mb-6">Cable TV Subscription</h1>
      <div className="bg-white rounded-xl shadow-card p-6">
        <CableForm providers={providers} />
      </div>
    </div>
  )
}

4. Cable Form Component

The CableForm component implements a three-step flow: provider selection, smart card verification with package selection, and confirmation. It uses useEffect to fetch available packages when the provider changes, and includes smart card verification to display customer information before payment.

The provider selection step uses a visual grid layout with icons, making it easy for users to identify their cable TV service. After verification, users select their desired subscription package from a dynamically loaded list.

// components/services/CableForm.tsx
'use client'

import { useState, useEffect } from 'react'
import { useActionState } from 'react'
import { purchaseCableAction } from '@/actions/services'
import { Button, Input, Select } from '@/components/ui'
import { formatCurrency } from '@/lib/utils'
import { cn } from '@/lib/utils'

interface Provider {
  id: string
  name: string
  logo: string
}

interface Package {
  code: string
  name: string
  amount: number
}

interface SmartCardInfo {
  customerName: string
  currentBouquet: string
  dueDate: string
}

interface CableFormProps {
  providers: Provider[]
}

export default function CableForm({ providers }: CableFormProps) {
  const [provider, setProvider] = useState('')
  const [smartCardNumber, setSmartCardNumber] = useState('')
  const [packageCode, setPackageCode] = useState('')
  const [phone, setPhone] = useState('')
  const [packages, setPackages] = useState<Package[]>([])
  const [cardInfo, setCardInfo] = useState<SmartCardInfo | null>(null)
  const [loading, setLoading] = useState(false)
  const [verifying, setVerifying] = useState(false)
  const [step, setStep] = useState<'provider' | 'details' | 'confirm'>('provider')

  const [state, formAction, isPending] = useActionState(
    purchaseCableAction,
    { success: false, message: '' }
  )

  const selectedPackage = packages.find(p => p.code === packageCode)

  // Fetch packages when provider changes
  useEffect(() => {
    if (!provider) return

    async function fetchPackages() {
      setLoading(true)
      try {
        const response = await fetch(`/api/services/cable-packages?provider=${provider}`)
        const data = await response.json()
        setPackages(data.packages || [])
      } catch (error) {
        console.error('Failed to fetch packages:', error)
      } finally {
        setLoading(false)
      }
    }

    fetchPackages()
  }, [provider])

  const verifySmartCard = async () => {
    if (!smartCardNumber) return

    setVerifying(true)
    try {
      const response = await fetch('/api/services/verify-smartcard', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ provider, smartCardNumber }),
      })

      if (!response.ok) {
        throw new Error('Smart card verification failed')
      }

      const data = await response.json()
      setCardInfo(data)
    } catch (error) {
      alert('Could not verify smart card. Please check the number.')
    } finally {
      setVerifying(false)
    }
  }

  // Step 1: Select provider
  if (step === 'provider') {
    return (
      <div className="space-y-6">
        <label className="block text-sm font-medium text-gray-700">
          Select Provider
        </label>
        <div className="grid grid-cols-3 gap-4">
          {providers.map((p) => (
            <button
              key={p.id}
              type="button"
              onClick={() => {
                setProvider(p.id)
                setStep('details')
              }}
              className={cn(
                'flex flex-col items-center p-6 rounded-xl border-2 transition',
                provider === p.id
                  ? 'border-primary bg-primary/5'
                  : 'border-gray-200 hover:border-gray-300'
              )}
            >
              <span className="text-4xl">{p.logo}</span>
              <span className="mt-2 font-medium">{p.name}</span>
            </button>
          ))}
        </div>
      </div>
    )
  }

  // Step 2: Enter details
  if (step === 'details') {
    return (
      <div className="space-y-6">
        <button
          type="button"
          onClick={() => setStep('provider')}
          className="flex items-center gap-2 text-gray-600 hover:text-gray-900"
        >
          ← Back to providers
        </button>

        <Input
          label="Smart Card / IUC Number"
          name="smartCardNumber"
          value={smartCardNumber}
          onChange={(e) => {
            setSmartCardNumber(e.target.value)
            setCardInfo(null)
          }}
          placeholder="Enter your smart card number"
          required
        />

        {!cardInfo && (
          <Button
            type="button"
            variant="outline"
            onClick={verifySmartCard}
            loading={verifying}
            className="w-full"
            disabled={!smartCardNumber}
          >
            Verify Smart Card
          </Button>
        )}

        {cardInfo && (
          <>
            <div className="bg-green-50 border border-green-200 rounded-lg p-4">
              <p className="text-sm text-green-600 font-medium mb-2">
                Smart Card Verified
              </p>
              <div className="space-y-1 text-sm">
                <p><span className="text-gray-600">Name:</span> {cardInfo.customerName}</p>
                <p><span className="text-gray-600">Current:</span> {cardInfo.currentBouquet}</p>
                <p><span className="text-gray-600">Due Date:</span> {cardInfo.dueDate}</p>
              </div>
            </div>

            <div>
              <label className="block text-sm font-medium text-gray-700 mb-2">
                Select Package
              </label>
              {loading ? (
                <div className="h-12 bg-gray-100 animate-pulse rounded-lg" />
              ) : (
                <Select
                  name="package"
                  value={packageCode}
                  onChange={(e) => setPackageCode(e.target.value)}
                  options={packages.map(pkg => ({
                    value: pkg.code,
                    label: `${pkg.name} - ${formatCurrency(pkg.amount)}`,
                  }))}
                  placeholder="Select a package"
                  required
                />
              )}
            </div>

            <Input
              label="Phone Number"
              name="phone"
              type="tel"
              value={phone}
              onChange={(e) => setPhone(e.target.value)}
              placeholder="08012345678"
              required
            />

            <Button
              type="button"
              onClick={() => setStep('confirm')}
              className="w-full"
              disabled={!packageCode || !phone}
            >
              Continue
            </Button>
          </>
        )}
      </div>
    )
  }

  // Step 3: Confirm
  if (step === 'confirm' && cardInfo && selectedPackage) {
    return (
      <div className="space-y-6">
        <h2 className="text-lg font-semibold">Confirm Subscription</h2>

        <div className="bg-gray-50 rounded-lg p-4 space-y-3">
          <div className="flex justify-between">
            <span className="text-gray-600">Provider</span>
            <span className="font-medium uppercase">{provider}</span>
          </div>
          <div className="flex justify-between">
            <span className="text-gray-600">Customer</span>
            <span className="font-medium">{cardInfo.customerName}</span>
          </div>
          <div className="flex justify-between">
            <span className="text-gray-600">Smart Card</span>
            <span className="font-medium">{smartCardNumber}</span>
          </div>
          <div className="flex justify-between">
            <span className="text-gray-600">Package</span>
            <span className="font-medium">{selectedPackage.name}</span>
          </div>
          <div className="border-t pt-3 flex justify-between">
            <span className="font-semibold">Amount</span>
            <span className="font-bold text-lg">
              {formatCurrency(selectedPackage.amount)}
            </span>
          </div>
        </div>

        {state.message && (
          <div className={`p-4 rounded-lg ${
            state.success ? 'bg-green-50 text-green-700' : 'bg-red-50 text-red-700'
          }`}>
            {state.message}
          </div>
        )}

        <form action={formAction}>
          <input type="hidden" name="provider" value={provider} />
          <input type="hidden" name="smartCardNumber" value={smartCardNumber} />
          <input type="hidden" name="packageCode" value={packageCode} />
          <input type="hidden" name="phone" value={phone} />
          <input type="hidden" name="amount" value={selectedPackage.amount} />

          <div className="flex gap-4">
            <Button
              type="button"
              variant="outline"
              onClick={() => setStep('details')}
              className="flex-1"
            >
              Back
            </Button>
            <Button type="submit" loading={isPending} className="flex-1">
              Pay {formatCurrency(selectedPackage.amount)}
            </Button>
          </div>
        </form>
      </div>
    )
  }

  return null
}

5. Service Actions

These server actions handle electricity and cable TV payment submissions. The ElectricitySchema validates meter details and amount ranges, while the CableSchema validates provider selection and smart card numbers.

The electricity action returns a token in the response for prepaid meters, which users need to enter into their meter to receive electricity units. The cable action redirects to a success page on completion. Both actions include proper error handling and cache revalidation.

// actions/services.ts (continued)

const ElectricitySchema = z.object({
  disco: z.string().min(1),
  meterNumber: z.string().min(11).max(15),
  meterType: z.enum(['prepaid', 'postpaid']),
  phone: z.string().regex(/^0[789][01]\d{8}$/),
  amount: z.number().min(1000).max(500000),
})

export async function purchaseElectricityAction(
  prevState: { success: boolean; message: string; token?: string },
  formData: FormData
) {
  const session = await getSession()
  if (!session) {
    return { success: false, message: 'Please login to continue' }
  }

  const rawData = {
    disco: formData.get('disco') as string,
    meterNumber: formData.get('meterNumber') as string,
    meterType: formData.get('meterType') as 'prepaid' | 'postpaid',
    phone: formData.get('phone') as string,
    amount: Number(formData.get('amount')),
  }

  const result = ElectricitySchema.safeParse(rawData)
  if (!result.success) {
    return { success: false, message: result.error.errors[0].message }
  }

  try {
    const transaction = await processTransaction({
      userId: session.user.id,
      type: 'electricity',
      amount: result.data.amount,
      metadata: {
        disco: result.data.disco,
        meterNumber: result.data.meterNumber,
        meterType: result.data.meterType,
        phone: result.data.phone,
        customerName: formData.get('customerName'),
      },
    })

    revalidatePath('/transactions')
    revalidatePath('/wallet')

    if (transaction.success) {
      return {
        success: true,
        message: 'Electricity payment successful!',
        token: transaction.token,
      }
    }

    return { success: false, message: transaction.message }
  } catch (error) {
    return {
      success: false,
      message: error instanceof Error ? error.message : 'Payment failed',
    }
  }
}

const CableSchema = z.object({
  provider: z.enum(['dstv', 'gotv', 'startimes']),
  smartCardNumber: z.string().min(10).max(15),
  packageCode: z.string().min(1),
  phone: z.string().regex(/^0[789][01]\d{8}$/),
  amount: z.number().positive(),
})

export async function purchaseCableAction(
  prevState: { success: boolean; message: string },
  formData: FormData
) {
  const session = await getSession()
  if (!session) {
    return { success: false, message: 'Please login to continue' }
  }

  const rawData = {
    provider: formData.get('provider') as string,
    smartCardNumber: formData.get('smartCardNumber') as string,
    packageCode: formData.get('packageCode') as string,
    phone: formData.get('phone') as string,
    amount: Number(formData.get('amount')),
  }

  const result = CableSchema.safeParse(rawData)
  if (!result.success) {
    return { success: false, message: result.error.errors[0].message }
  }

  try {
    const transaction = await processTransaction({
      userId: session.user.id,
      type: 'cable',
      amount: result.data.amount,
      metadata: result.data,
    })

    revalidatePath('/transactions')
    revalidatePath('/wallet')

    if (transaction.success) {
      redirect(`/transactions/${transaction.transaction.id}?success=true`)
    }

    return { success: false, message: transaction.message }
  } catch (error) {
    return {
      success: false,
      message: error instanceof Error ? error.message : 'Subscription failed',
    }
  }
}

6. Verification API Routes

These API routes provide endpoints for verifying smart cards and fetching cable TV packages. The verify-smartcard route validates the smart card number and returns customer information including their current subscription and due date.

The cable-packages route fetches available subscription packages for a specific provider, returning the package codes, names, and prices. Both routes require authentication and include proper error handling.

// app/api/services/verify-smartcard/route.ts
import { NextRequest } from 'next/server'
import { verifySmartCard } from '@/lib/rizpay/verify'
import { getSession } from '@/lib/auth'

export async function POST(request: NextRequest) {
  const session = await getSession()
  if (!session) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 })
  }

  const { provider, smartCardNumber } = await request.json()

  const cardInfo = await verifySmartCard(provider, smartCardNumber)

  if (!cardInfo) {
    return Response.json(
      { error: 'Smart card not found or invalid' },
      { status: 400 }
    )
  }

  return Response.json(cardInfo)
}

The cable-packages route extracts the provider from query parameters and returns the available subscription packages for that provider. Type casting ensures TypeScript knows the expected provider values.

// app/api/services/cable-packages/route.ts
import { NextRequest } from 'next/server'
import { getCablePackages } from '@/lib/rizpay/services'
import { getSession } from '@/lib/auth'

export async function GET(request: NextRequest) {
  const session = await getSession()
  if (!session) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 })
  }

  const { searchParams } = new URL(request.url)
  const provider = searchParams.get('provider') as 'dstv' | 'gotv' | 'startimes'

  if (!provider) {
    return Response.json({ error: 'Provider required' }, { status: 400 })
  }

  try {
    const packages = await getCablePackages(provider)
    return Response.json({ packages })
  } catch (error) {
    return Response.json(
      { error: 'Failed to fetch packages' },
      { status: 500 }
    )
  }
}

Assignment

Task: Complete Bill Payment Features

Electricity payment with meter verification
Cable TV subscription with smart card verification
Token display for prepaid electricity
Transaction receipt component
Print/Share receipt functionality

Next Lesson: Testing & Optimization