How to Integrate Sage Pay with V0

Start in the V0 chat interface and describe the payment form you need. V0 will generate a React component with the appropriate form fields for collecting payment information. For Opayo Pi integration, the recommended approach is to render a standard form first and then layer in Opayo's card tokenization JavaScript. Ask V0 to create a clean checkout form with fields for cardholder name, card number, expiry date, and CVV, along with billing address fields required for UK AVS/CV2 checks. V0 will use Tailwind CSS to style the form and create a submit handler that posts the data to your Next.js API route. Make sure the form uses controlled React state so you can clear sensitive fields after submission. The component should also handle loading and error states — showing a spinner while the payment processes and displaying friendly error messages if the transaction is declined. Once V0 generates the component, review it in the preview to confirm the layout looks right before moving on to the API route.

Create a Next.js App Router route handler at app/api/payment/route.ts. This file will receive the payment data from your frontend, construct an Opayo Pi merchant session, and then submit the payment authorisation. The Opayo Pi REST API uses Basic Auth where the username is your Integration Key and the password is your Integration Password. You first call the /merchant-session-keys endpoint to get a short-lived session key, which the browser uses to tokenize the card. For a server-to-server integration (where you handle card data on your server), you call the /transactions endpoint directly with the card details. The API route must POST to https://pi-test.sagepay.com/api/v1/transactions for sandbox or https://pi-live.sagepay.com/api/v1/transactions for production. Always read credentials from process.env — never hardcode them. Return a structured JSON response to the frontend with the transaction status, reference, and any error details so the UI can display appropriate feedback. Add proper error handling for network failures and Opayo API errors.

1// app/api/payment/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4const OPAYO_BASE_URL = process.env.OPAYO_ENV === 'production'
5  ? 'https://pi-live.sagepay.com/api/v1'
6  : 'https://pi-test.sagepay.com/api/v1';
7
8function getBasicAuthHeader() {
9  const credentials = `${process.env.OPAYO_INTEGRATION_KEY}:${process.env.OPAYO_INTEGRATION_PASSWORD}`;
10  return `Basic ${Buffer.from(credentials).toString('base64')}`;
11}
12
13export async function POST(request: NextRequest) {
14  try {
15    const body = await request.json();
16    const { amount, currency = 'GBP', description, cardDetails, billingAddress } = body;
17
18    if (!amount || !cardDetails) {
19      return NextResponse.json({ error: 'Missing required payment fields' }, { status: 400 });
20    }
21
22    // Create a transaction via Opayo Pi REST API
23    const transactionPayload = {
24      transactionType: 'Payment',
25      paymentMethod: {
26        card: {
27          merchantSessionKey: process.env.OPAYO_VENDOR_NAME,
28          cardIdentifier: cardDetails.cardIdentifier,
29        },
30      },
31      vendorTxCode: `TXN-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
32      amount: Math.round(amount * 100), // Opayo expects pence
33      currency,
34      description,
35      apply3DSecure: 'UseMSPSetting',
36      billingAddress: {
37        address1: billingAddress?.address1 || '',
38        city: billingAddress?.city || '',
39        postalCode: billingAddress?.postalCode || '',
40        country: billingAddress?.country || 'GB',
41      },
42    };
43
44    const response = await fetch(`${OPAYO_BASE_URL}/transactions`, {
45      method: 'POST',
46      headers: {
47        'Authorization': getBasicAuthHeader(),
48        'Content-Type': 'application/json',
49      },
50      body: JSON.stringify(transactionPayload),
51    });
52
53    const result = await response.json();
54
55    if (!response.ok) {
56      return NextResponse.json(
57        { error: result.description || 'Payment failed', code: result.code },
58        { status: response.status }
59      );
60    }
61
62    return NextResponse.json({
63      success: true,
64      transactionId: result.transactionId,
65      status: result.status,
66      statusCode: result.statusCode,
67      statusDetail: result.statusDetail,
68    });
69  } catch (error) {
70    console.error('Opayo payment error:', error);
71    return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
72  }
73}

Opayo Pi's recommended integration flow requires obtaining a short-lived Merchant Session Key (MSK) before the browser can tokenize the card. Create a separate API route at app/api/payment/session/route.ts that calls the Opayo merchant-session-keys endpoint. The frontend calls this first when the payment form loads, receives the MSK, and then uses the Opayo.js drop-in library to convert the raw card number into a safe card identifier. This card identifier (not the raw PAN) is then sent to your main payment API route. This two-step flow is the recommended PCI-compliant pattern for Opayo Pi. The MSK is valid for 400 seconds so it is fine to fetch one per page load. Your frontend component should call /api/payment/session on mount, store the returned merchantSessionKey and merchantId in component state, and pass them to the Opayo.js library. This setup reduces your PCI DSS scope significantly because raw card data is handled by Opayo's JavaScript, not your server.

1// app/api/payment/session/route.ts
2import { NextResponse } from 'next/server';
3
4export async function GET() {
5  try {
6    const credentials = `${process.env.OPAYO_INTEGRATION_KEY}:${process.env.OPAYO_INTEGRATION_PASSWORD}`;
7    const authHeader = `Basic ${Buffer.from(credentials).toString('base64')}`;
8
9    const response = await fetch(
10      'https://pi-test.sagepay.com/api/v1/merchant-session-keys',
11      {
12        method: 'POST',
13        headers: {
14          'Authorization': authHeader,
15          'Content-Type': 'application/json',
16        },
17        body: JSON.stringify({
18          vendorName: process.env.OPAYO_VENDOR_NAME,
19        }),
20      }
21    );
22
23    const data = await response.json();
24
25    if (!response.ok) {
26      return NextResponse.json(
27        { error: 'Failed to create merchant session' },
28        { status: 500 }
29      );
30    }
31
32    return NextResponse.json({
33      merchantSessionKey: data.merchantSessionKey,
34      expiry: data.expiry,
35    });
36  } catch (error) {
37    console.error('Opayo session error:', error);
38    return NextResponse.json({ error: 'Session creation failed' }, { status: 500 });
39  }
40}

Your Opayo credentials must never be committed to your repository or exposed to the browser. In the Vercel Dashboard, go to your project, then navigate to Settings → Environment Variables. Add the following variables. OPAYO_INTEGRATION_KEY: found in the MySagePay portal under Settings → Manage Integrations → Opayo Pi. OPAYO_INTEGRATION_PASSWORD: the corresponding password shown alongside the integration key. OPAYO_VENDOR_NAME: your Sage Pay vendor name (your merchant account name used when you registered). OPAYO_ENV: set to 'sandbox' for development and 'production' when you are ready to go live. Set these for the Production, Preview, and Development environments. For the Development environment, use your sandbox credentials. After adding the variables, redeploy your Vercel project so the new environment variables take effect — Vercel inlines them at build time for Next.js, but server-side process.env reads happen at runtime in serverless functions. You can verify the variables are available by adding a temporary log in your API route during development, but remove any console.log statements that might expose credentials before going to production.

With the API route and environment variables in place, update the payment form component so the submit handler calls your /api/payment endpoint. The fetch call should POST a JSON body containing the transaction amount, currency (GBP), description, card identifier from Opayo.js, and billing address fields. Handle the response by checking for the success property: if true, display a confirmation panel with the transactionId; if false, show the error message from the API response. Add client-side validation to check that all required fields are filled before submitting, and disable the Pay Now button after first click to prevent duplicate submissions. To test in the Opayo sandbox, use the test card numbers provided in the Opayo developer documentation — for example, 4929000000006 for a successful Visa transaction and 4000000000000002 for a declined card. Check the Opayo MySagePay reporting portal to confirm test transactions appear. Once everything works in the sandbox, change OPAYO_ENV to 'production' in your Vercel environment variables and update the API route URLs from pi-test.sagepay.com to pi-live.sagepay.com to process real payments.

1// components/PaymentForm.tsx (relevant submit handler)
2async function handleSubmit(e: React.FormEvent) {
3  e.preventDefault();
4  setIsLoading(true);
5  setError('');
6
7  try {
8    const response = await fetch('/api/payment', {
9      method: 'POST',
10      headers: { 'Content-Type': 'application/json' },
11      body: JSON.stringify({
12        amount: orderTotal,
13        currency: 'GBP',
14        description: orderDescription,
15        cardDetails: {
16          cardIdentifier: cardIdentifier, // from Opayo.js
17        },
18        billingAddress: {
19          address1: formData.address1,
20          city: formData.city,
21          postalCode: formData.postcode,
22          country: 'GB',
23        },
24      }),
25    });
26
27    const result = await response.json();
28
29    if (result.success) {
30      setTransactionId(result.transactionId);
31      setPaymentComplete(true);
32    } else {
33      setError(result.error || 'Payment was declined. Please try again.');
34    }
35  } catch (err) {
36    setError('Network error. Please check your connection and try again.');
37  } finally {
38    setIsLoading(false);
39  }
40}