Integrate GivePay into your Next.js or React application with the React component

Installation

Install the GivePay React package via npm:

npm install givepay-js

Quick Start: Global Configuration

The recommended way to use GivePay in Next.js/React applications is to configure the SDK globally and use the component without props. This approach is cleaner and allows you to manage payment configuration in a central place.

1. Configure the SDK

You can configure the SDK imperatively using the GivePay object. This is typically done in your component or a layout file.

import { GivePay } from 'givepay-js/react';

// Configure SDK globally
GivePay.configure('gp_test_pk_your_key_here');
GivePay.setText('Donate Now'); // Optional: Customize button text
GivePay.setPaymentOptions({
    payment_type: 'one_time',
    currency: 'GBP',
    line_items: [
        {
            quantity: 1,
            amount: 200, // £2.00
            country_iso: 'GB',
            intention: 'General Donation',
            project: 'Winter Appeal 2024'
        }
    ],
    payer: {
        email: 'donor@example.com',
        billing_address: {
            country: 'GB',
            city: 'London',
            line1: '123 Main St',
            postcode: 'SW1A 1AA',
            state: 'London'
        },
        first_name: 'John',
        last_name: 'Doe',
        phone: '+447700900123'
    },
    return_url: 'https://yourcharity.org/success'
});

2. Use with Next.js Dynamic Import

To prevent hydration errors in Next.js (since the SDK interacts with the window object), use next/dynamic with ssr: false to import the button component.

'use client';

import dynamic from 'next/dynamic';
import { GivePay } from 'givepay-js/react';

// ... configuration code ...

// Import GivePayButton with SSR disabled
const GivePayButton = dynamic(
    () => import('givepay-js/react'),
    { ssr: false }
);

export default function CheckoutPage() {
    return (
        <div>
            <h1>Checkout</h1>
            {/* Button uses global defaults */}
            <GivePayButton />
        </div>
    );
}

Complete Example

Here is a complete example of a checkout page using the Global Configuration pattern:

'use client';

import dynamic from 'next/dynamic';
import { GivePay } from 'givepay-js/react';

// Configure SDK globally
GivePay.configure('gp_test_pk_your_key_here');
GivePay.setText('Donate Now');
GivePay.setPaymentOptions({
    payment_type: 'one_time',
    currency: 'GBP',
    line_items: [
        {
            quantity: 1,
            amount: 200,
            country_iso: 'GB',
            intention: 'General Donation',
            project: 'Gaza Winter Appeal 2024'
        }
    ],
    payer: {
        email: 'test@example.com',
        billing_address: {
            country: 'GB',
            city: 'Anytown',
            line1: '123 Main St',
            postcode: '12345',
            state: 'CA'
        },
        first_name: 'John',
        last_name: 'Doe',
        phone: '123-456-7890'
    },
    return_url: 'https://example.com/success'
});

// Import GivePayButton with SSR disabled to prevent hydration errors
const GivePayButton = dynamic(
    () => import('givepay-js/react'),
    { ssr: false }
);

export default function CheckoutPage() {
    return (
        <div className="min-h-screen bg-gray-50 py-12 px-4 sm:px-6 lg:px-8">
            <div className="max-w-md mx-auto bg-white rounded-lg shadow-md p-8">
                <h1 className="text-2xl font-bold text-gray-900 mb-6">
                    Checkout
                </h1>

                <div className="mb-6">
                    <h2 className="text-lg font-semibold text-gray-700 mb-2">
                        Gaza Winter Appeal 2024
                    </h2>
                    <p className="text-gray-600">
                        Amount: £2.00
                    </p>
                </div>

                <div className="border-t border-gray-200 pt-6">
                    {/* Button uses global defaults */}
                    <GivePayButton />
                </div>
            </div>
        </div>
    );
}

Payment Types

GivePay supports multiple payment session types:

One-Time Payments (payment_type: "one_time"): Single transactions for donations, purchases, or one-time fees
Subscriptions (payment_type: "subscription"): Recurring payments for monthly giving, sponsorships, or memberships
Mixed (subscription + one_time_items): Subscriptions with additional one-time items (e.g., setup fees)

Subscription Example

GivePay.setPaymentOptions({
    payment_type: 'subscription',
    currency: 'GBP',
    subscription: {
        interval: 'month',
        interval_count: 1,
        name: 'Monthly Child Sponsorship'
    },
    line_items: [
        {
            quantity: 1,
            amount: 3000, // £30.00/month
            intention: 'Child Sponsorship'
        }
    ],
    payer: {
        email: 'sponsor@example.com'
    },
    return_url: 'https://yourcharity.org/subscription/success'
});

Mixed Payment Example (Subscription + One-Time Fee)

GivePay.setPaymentOptions({
    payment_type: 'subscription',
    currency: 'GBP',
    subscription: {
        interval: 'month',
        interval_count: 1,
        name: 'Monthly Giving Circle'
    },
    line_items: [
        {
            quantity: 1,
            amount: 2500 // £25.00/month recurring
        }
    ],
    one_time_items: [
        {
            quantity: 1,
            amount: 1000 // £10.00 enrollment fee (one-time)
        }
    ],
    payer: {
        email: 'member@example.com'
    },
    return_url: 'https://yourcharity.org/enrollment/complete'
});

API Reference

`GivePay` Object

The GivePay object provides static methods to configure the SDK.

Method	Description
`configure(publicKey: string)`	Initialize the SDK with your public key.
`setPaymentOptions(options: PaymentOptions)`	Set the payment configuration (currency, items, payer, etc.).
`setColour(color: string)`	Set the primary color of the payment button.
`setText(text: string)`	Set the text displayed on the payment button.
`setTextColor(color: string)`	Set the text color of the payment button.
`setLineItems(items: LineItem[])`	Update just the line items.
`setPayer(payer: Payer)`	Update just the payer information.
`setButtonOptions(options: ButtonOptions)`	Set advanced button styling options.

`GivePayButton` Component

The GivePayButton component renders the payment button. When used with global configuration, it requires no props.

However, you can still pass props to override global defaults if needed (Legacy/Local Mode).

Prop	Type	Required	Description
`publicKey`	`string`	No	Overrides the globally configured key.
`paymentOptions`	`PaymentOptions`	No	Overrides global payment options.
`buttonOptions`	`ButtonOptions`	No	Overrides global button options.

Advanced Usage

Hybrid Configuration

You can mix global configuration with local overrides. This is useful if you want to set common defaults (like the public key and styles) globally, but pass specific payment details locally.

// Configure common settings
GivePay.configure('gp_test_pk_your_key_here');

// ... inside component ...
<GivePayButton
  paymentOptions={{
    payment_type: "one_time",
    currency: "GBP",
    line_items: [{ quantity: 1, amount: 5000 }],
    payer: { email: "customer@example.com" },
    return_url: "https://yoursite.com/success"
  }}
/>

TypeScript Support

The package includes full TypeScript definitions.

import { GivePay } from 'givepay-js/react';
import type { PaymentOptions, LineItem, Payer } from 'givepay-js/types';

const options: PaymentOptions = {
  payment_type: 'one_time',
  currency: 'GBP',
  line_items: [
    {
      quantity: 1,
      amount: 5000,
      name: 'Donation',
      country_iso: 'GB',
      intention: 'General Donation',
      project: 'Winter Appeal'
    }
  ],
  payer: {
    email: 'donor@example.com',
    first_name: 'John',
    last_name: 'Doe',
    billing_address: {
      country: 'GB', // Required when billing_address is provided
      city: 'London',
      line1: '123 Main St',
      postcode: 'SW1A 1AA'
    }
  },
  return_url: 'https://yourcharity.org/success'
};

GivePay.setPaymentOptions(options);

PaymentOptions Type Reference

Required Fields

Field	Type	Description
`payment_type`	`"one_time"` \| `"subscription"`	Type of payment session
`currency`	`string`	Three-letter ISO currency code (e.g., "GBP", "USD")
`line_items`	`LineItem[]`	Array of items (at least one required)
`payer`	`Payer`	Payer information with email
`return_url`	`string`	HTTPS URL for post-payment redirect

Conditional Fields

Field	Type	Description
`subscription`	`SubscriptionConfig`	Required when `payment_type` is `"subscription"`
`one_time_items`	`LineItem[]`	Optional one-time items for subscriptions

LineItem Type

Field	Type	Required	Description
`quantity`	`number`	Yes	Quantity (must be > 0)
`amount`	`number`	Yes	Amount in smallest currency unit (e.g., cents)
`name`	`string`	No	Item name (recommended)
`country_iso`	`string`	No	ISO 3166-1 alpha-2 country code
`intention`	`string`	No	Purpose of payment
`project`	`string`	No	Specific project name

Payer Type

Field	Type	Required	Description
`email`	`string`	Yes	Valid email address
`first_name`	`string`	No	First name
`last_name`	`string`	No	Last name
`phone`	`string`	No	Phone number
`billing_address`	`BillingAddress`	No	Billing address details

BillingAddress Type

Field	Type	Required	Description
`country`	`string`	Yes*	ISO 3166-1 alpha-2 code - Required when billing_address is provided
`city`	`string`	No	City name
`line1`	`string`	No	Address line 1
`line2`	`string`	No	Address line 2
`postcode`	`string`	No	Postal/ZIP code
`state`	`string`	No	State or province

SubscriptionConfig Type

Field	Type	Required	Description
`interval`	`"day"` \| `"week"` \| `"month"` \| `"year"`	Yes	Billing frequency
`interval_count`	`number`	Yes	Number of intervals between billings
`name`	`string`	Yes	Product name for payment provider

Next.js / React Package