Verify Payments

After a customer completes a payment, you must verify the result on your server before fulfilling the order. The redirect back to your app is not proof of payment — it can be triggered by anyone who knows your callback URL. Always verify server-side.

Method 1: Callback verification

When Seev redirects the customer back to your redirect_url, your callback route should read the session reference and verify it from your backend. Use the gateway reference returned when you created the checkout session, or the corresponding session reference received after redirect.

This endpoint is the SeevPlus wrapper for the gateway session lookup. No API key or Authorization header is required for this GET request. A successful request returns the current gateway session payload, allowing clients to check payment status without calling the gateway API directly.

curl -X GET \
  "https://api.seevplus.com/api/v1/developer/payments/$SESSION_REF"

Check the returned status before fulfilling the order:

{
    "success": true,
    "data": {
        "id": "checkout_xyz",
        "reference": "PAY-20260701-abc123",
        "status": "completed",
        "amount": 10000,
        "final_amount": 10000,
        "currency": "GHS"
    }
}

Treat completed or success as paid. Treat pending, failed, or cancelled as not fulfilled.

Example callback handler

// GET /payment/callback?sessionRef=PAY-20260701-abc123
export async function GET(req: Request) {
    const url = new URL(req.url);
    const sessionRef =
        url.searchParams.get('sessionRef') ||
        url.searchParams.get('session_ref') ||
        url.searchParams.get('session_id');

    if (!sessionRef) {
        return Response.redirect('/order/failed?reason=missing_session');
    }

    const response = await fetch(
        `https://api.seevplus.com/api/v1/developer/payments/${encodeURIComponent(sessionRef)}`,
    );

    const result = await response.json();
    const status = result?.data?.status;

    if (status === 'completed' || status === 'success') {
        await fulfillOrder(result.data.reference);
        return Response.redirect('/order/confirmed');
    }

    return Response.redirect(`/order/failed?status=${status || 'unknown'}`);
}

Method 2: Transaction lookup

Use the Developer Transactions API when you need to look up a past transaction, power an order-status page, or reconcile a payment after receiving a webhook.

Transaction lookup is useful for:

• Verifying payments that came through webhooks
• Checking the status of a payment initiated elsewhere
• Building an order status page that polls for updates
• Reconciling your internal order ID with the Seev payment reference

Transaction statuses

Method 3: Webhooks (recommended for fulfilment)

For fulfilment workflows, webhooks are more reliable than callback verification alone. Seev sends a payment event to your webhook endpoint as soon as a payment is confirmed — even if the customer closes the browser before being redirected.

Use callback verification to give the customer immediate feedback in the UI, and use signed webhooks to trigger fulfilment logic.

See the Webhooks guide for endpoint setup, delivery logs, retries, and signature verification.

Which method should I use?

Using both callback verification and webhooks together is the most robust pattern — the callback handles the UI, and the webhook handles fulfilment independently.