Learning Objectives

Create network selection interface
Build airtime purchase form
Implement data plan selection
Handle purchase confirmations

1. Airtime Purchase Page

The airtime purchase page is a simple server component that renders the page layout with a title and wraps the AirtimeForm client component in a styled card. The metadata export allows Next.js to set the page title for SEO purposes.

// app/(dashboard)/services/airtime/page.tsx
import AirtimeForm from '@/components/services/AirtimeForm'

export const metadata = {
  title: 'Buy Airtime | RizPay',
}

export default function AirtimePage() {
  return (
    <div className="max-w-lg mx-auto">
      <h1 className="text-2xl font-bold mb-6">Buy Airtime</h1>
      <div className="bg-white rounded-xl shadow-card p-6">
        <AirtimeForm />
      </div>
    </div>
  )
}

2. Airtime Form Component

The AirtimeForm component implements a two-step purchase flow: first collecting user input, then showing a confirmation screen before processing the payment. This pattern helps prevent accidental purchases and gives users a chance to review their order.

The component uses useState to manage the form fields (network, phone, amount) and track the current step. The useActionState hook connects to the server action for processing the purchase, providing loading state and response handling.

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

import { useState } from 'react'
import { useActionState } from 'react'
import { purchaseAirtimeAction } from '@/actions/services'
import { Button, Input } from '@/components/ui'
import NetworkSelector from '@/components/forms/NetworkSelector'
import AmountSelector from '@/components/forms/AmountSelector'
import { formatCurrency } from '@/lib/utils'

const quickAmounts = [100, 200, 500, 1000, 2000, 5000]

export default function AirtimeForm() {
  const [network, setNetwork] = useState('')
  const [phone, setPhone] = useState('')
  const [amount, setAmount] = useState('')
  const [step, setStep] = useState<'form' | 'confirm'>('form')

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

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault()
    if (step === 'form') {
      setStep('confirm')
    }
  }

  if (step === 'confirm') {
    return (
      <div className="space-y-6">
        <h2 className="text-lg font-semibold">Confirm Purchase</h2>

        <div className="bg-gray-50 rounded-lg p-4 space-y-3">
          <div className="flex justify-between">
            <span className="text-gray-600">Network</span>
            <span className="font-medium uppercase">{network}</span>
          </div>
          <div className="flex justify-between">
            <span className="text-gray-600">Phone Number</span>
            <span className="font-medium">{phone}</span>
          </div>
          <div className="flex justify-between">
            <span className="text-gray-600">Amount</span>
            <span className="font-medium">{formatCurrency(Number(amount))}</span>
          </div>
          <div className="border-t pt-3 flex justify-between">
            <span className="font-semibold">Total</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}
          </div>
        )}

        <form action={formAction}>
          <input type="hidden" name="network" value={network} />
          <input type="hidden" name="phone" value={phone} />
          <input type="hidden" name="amount" value={amount} />

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

  return (
    <form onSubmit={handleSubmit} className="space-y-6">
      <NetworkSelector
        value={network}
        onChange={setNetwork}
      />

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

      <AmountSelector
        amounts={quickAmounts}
        value={amount}
        onChange={setAmount}
        label="Amount"
        min={50}
        max={50000}
      />

      <Button
        type="submit"
        className="w-full"
        disabled={!network || !phone || !amount}
      >
        Continue
      </Button>
    </form>
  )
}

3. Data Purchase Page

The data purchase page is an async server component that pre-fetches the default network's data plans before rendering. This improves the initial user experience by having plans ready to display immediately rather than showing a loading state on first load.

By fetching MTN plans as the default, users see available options right away. When they switch networks, the client-side component will fetch new plans dynamically.

// app/(dashboard)/services/data/page.tsx
import { getDataPlans } from '@/lib/rizpay/services'
import DataForm from '@/components/services/DataForm'

export const metadata = {
  title: 'Buy Data | RizPay',
}

export default async function DataPage() {
  // Pre-fetch MTN plans as default
  const mtnPlans = await getDataPlans('mtn')

  return (
    <div className="max-w-lg mx-auto">
      <h1 className="text-2xl font-bold mb-6">Buy Data Bundle</h1>
      <div className="bg-white rounded-xl shadow-card p-6">
        <DataForm initialPlans={mtnPlans} />
      </div>
    </div>
  )
}

4. Data Form Component

The DataForm component extends the airtime form pattern with plan selection. It uses useEffect to dynamically fetch data plans when the user changes the selected network, displaying a loading skeleton while the API request is in progress.

The selectedPlan variable finds the full plan object from the plans array, which is needed to display the plan name and amount in the confirmation step. Hidden form inputs pass all necessary data to the server action when the form is submitted.

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

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

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

interface DataFormProps {
  initialPlans: DataPlan[]
}

export default function DataForm({ initialPlans }: DataFormProps) {
  const [network, setNetwork] = useState('mtn')
  const [phone, setPhone] = useState('')
  const [planCode, setPlanCode] = useState('')
  const [plans, setPlans] = useState<DataPlan[]>(initialPlans)
  const [loading, setLoading] = useState(false)
  const [step, setStep] = useState<'form' | 'confirm'>('form')

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

  const selectedPlan = plans.find(p => p.code === planCode)

  // Fetch plans when network changes
  useEffect(() => {
    async function fetchPlans() {
      setLoading(true)
      setPlanCode('')
      try {
        const response = await fetch(`/api/services/data-plans?network=${network}`)
        const data = await response.json()
        setPlans(data.plans || [])
      } catch (error) {
        console.error('Failed to fetch plans:', error)
      } finally {
        setLoading(false)
      }
    }

    fetchPlans()
  }, [network])

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault()
    if (step === 'form') {
      setStep('confirm')
    }
  }

  if (step === 'confirm' && selectedPlan) {
    return (
      <div className="space-y-6">
        <h2 className="text-lg font-semibold">Confirm Purchase</h2>

        <div className="bg-gray-50 rounded-lg p-4 space-y-3">
          <div className="flex justify-between">
            <span className="text-gray-600">Network</span>
            <span className="font-medium uppercase">{network}</span>
          </div>
          <div className="flex justify-between">
            <span className="text-gray-600">Phone Number</span>
            <span className="font-medium">{phone}</span>
          </div>
          <div className="flex justify-between">
            <span className="text-gray-600">Data Plan</span>
            <span className="font-medium">{selectedPlan.name}</span>
          </div>
          <div className="border-t pt-3 flex justify-between">
            <span className="font-semibold">Total</span>
            <span className="font-bold text-lg">
              {formatCurrency(selectedPlan.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="network" value={network} />
          <input type="hidden" name="phone" value={phone} />
          <input type="hidden" name="planCode" value={planCode} />
          <input type="hidden" name="amount" value={selectedPlan.amount} />

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

  return (
    <form onSubmit={handleSubmit} className="space-y-6">
      <NetworkSelector
        value={network}
        onChange={setNetwork}
      />

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

      <div>
        <label className="block text-sm font-medium text-gray-700 mb-2">
          Data Plan
        </label>
        {loading ? (
          <div className="h-12 bg-gray-100 animate-pulse rounded-lg" />
        ) : (
          <Select
            name="plan"
            value={planCode}
            onChange={(e) => setPlanCode(e.target.value)}
            options={plans.map(plan => ({
              value: plan.code,
              label: `${plan.name} - ${formatCurrency(plan.amount)}`,
            }))}
            placeholder="Select a data plan"
            required
          />
        )}
      </div>

      <Button
        type="submit"
        className="w-full"
        disabled={!network || !phone || !planCode}
      >
        Continue
      </Button>
    </form>
  )
}

5. Amount Selector Component

The AmountSelector component provides a reusable interface for selecting monetary amounts. It displays a grid of preset quick-select buttons for common amounts, plus a custom input field for users who want to enter a specific amount.

The component uses the cn utility function (typically from tailwind-merge or clsx) to conditionally apply styles based on whether a button is selected. This visual feedback helps users see which amount they've chosen.

// components/forms/AmountSelector.tsx
'use client'

import { cn } from '@/lib/utils'
import { Input } from '@/components/ui'

interface AmountSelectorProps {
  amounts: number[]
  value: string
  onChange: (value: string) => void
  label?: string
  min?: number
  max?: number
}

export default function AmountSelector({
  amounts,
  value,
  onChange,
  label = 'Amount',
  min = 0,
  max = Infinity,
}: AmountSelectorProps) {
  return (
    <div className="space-y-3">
      <label className="block text-sm font-medium text-gray-700">
        {label}
      </label>

      <div className="grid grid-cols-3 gap-2">
        {amounts.map((amount) => (
          <button
            key={amount}
            type="button"
            onClick={() => onChange(amount.toString())}
            className={cn(
              'py-3 rounded-lg border-2 font-medium transition',
              value === amount.toString()
                ? 'border-primary bg-primary/5 text-primary'
                : 'border-gray-200 hover:border-gray-300'
            )}
          >
            ₦{amount.toLocaleString()}
          </button>
        ))}
      </div>

      <Input
        name="customAmount"
        type="number"
        value={value}
        onChange={(e) => onChange(e.target.value)}
        placeholder="Or enter custom amount"
        min={min}
        max={max}
      />
    </div>
  )
}

6. Purchase Actions

The purchase actions handle form submissions for both airtime and data purchases. Each action validates the input using Zod schemas with specific rules for Nigerian phone numbers, then calls the processTransaction service to execute the purchase.

The actions follow a consistent pattern: check for authentication, validate input data, attempt the transaction, and either redirect on success or return an error message on failure. The revalidatePath calls ensure that transaction and wallet data are refreshed after a successful purchase.

// actions/services.ts
'use server'

import { revalidatePath } from 'next/cache'
import { redirect } from 'next/navigation'
import { z } from 'zod'
import { getSession } from '@/lib/auth'
import { processTransaction } from '@/lib/services/transaction'

const AirtimeSchema = z.object({
  network: z.enum(['mtn', 'airtel', 'glo', '9mobile']),
  phone: z.string().regex(/^0[789][01]\d{8}$/, 'Invalid phone number'),
  amount: z.number().min(50).max(50000),
})

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

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

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

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

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

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

const DataSchema = z.object({
  network: z.enum(['mtn', 'airtel', 'glo', '9mobile']),
  phone: z.string().regex(/^0[789][01]\d{8}$/, 'Invalid phone number'),
  planCode: z.string().min(1, 'Please select a plan'),
  amount: z.number().positive(),
})

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

  const rawData = {
    network: formData.get('network') as string,
    phone: formData.get('phone') as string,
    planCode: formData.get('planCode') as string,
    amount: Number(formData.get('amount')),
  }

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

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

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

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

7. Data Plans API Route

This API route provides an endpoint for fetching data plans from the client side. When the user changes the selected network in the DataForm, a fetch request is made to this route to get the available plans for that network.

The route validates the user session to prevent unauthorized access, requires a network parameter, and returns the plans from the RizPay service. Error handling ensures graceful failure if the external API is unavailable.

// app/api/services/data-plans/route.ts
import { NextRequest } from 'next/server'
import { getDataPlans } 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 network = searchParams.get('network')

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

  try {
    const plans = await getDataPlans(network)
    return Response.json({ plans })
  } catch (error) {
    return Response.json(
      { error: 'Failed to fetch plans' },
      { status: 500 }
    )
  }
}

Assignment

Task: Build Complete Airtime & Data Flow

Airtime purchase with all networks
Data purchase with plan selection
Transaction confirmation modal
Success/failure pages
Recent purchases quick-buy feature

Test Scenarios

Different networks
Various amounts
Invalid phone numbers
Insufficient balance

Next Lesson: Electricity & Cable TV Payments