GoPayLocalProvider

The GoPayLocalProvider wraps your app (or the part of your app that needs PPP pricing) and provides PPP data to all descendant hooks and components.

Usage

import { GoPayLocalProvider } from '@gopaylocal/react';

function App() {
  return (
    <GoPayLocalProvider apiKey="gpl_pk_live_abc123">
      <PricingPage />
    </GoPayLocalProvider>
  );
}

Props

Prop	Type	Default	Description
apiKey	string	(required)	Your GoPayLocal public API key (starts with gpl_pk_).
apiBase	string	'https://api.gopaylocal.com'	Override the API base URL.
environment	'production' | 'sandbox'	'production'	Target environment. Sandbox uses api.sandbox.gopaylocal.com.
baseCurrencyCode	string	'USD'	The base currency code used in your pricing.
baseCurrencySymbol	string	'$'	The base currency symbol used in your pricing.
onLoad	(data: PPPResponse) => void	—	Callback invoked when PPP data loads successfully.
onError	(error: Error) => void	—	Callback invoked when the API request fails.
children	ReactNode	(required)	Child components that need access to PPP data.

Environment

When environment is set to 'sandbox', the provider uses https://api.sandbox.gopaylocal.com as the API base (unless apiBase is explicitly set). Use this for testing with sandbox API keys.

<GoPayLocalProvider
  apiKey="gpl_pk_test_xyz789"
  environment="sandbox"
>
  <App />
</GoPayLocalProvider>

Callbacks

onLoad

Called when the API response is received and parsed. The callback receives the full PPPResponse object:

<GoPayLocalProvider
  apiKey="gpl_pk_live_abc123"
  onLoad={(data) => {
    console.log('PPP data loaded:', data.country, data.discount);
    // Track in your analytics
    analytics.track('ppp_loaded', {
      country: data.country,
      discount: data.discount,
    });
  }}
>
  <App />
</GoPayLocalProvider>

onError

Called when the API request fails. The provider continues to render children with no discount applied.

<GoPayLocalProvider
  apiKey="gpl_pk_live_abc123"
  onError={(error) => {
    console.error('GoPayLocal error:', error.message);
    // Report to error tracking
    Sentry.captureException(error);
  }}
>
  <App />
</GoPayLocalProvider>

Note

Errors are non-fatal. If the API request fails, all PPP components render with the base currency and no discount. Your app continues to work normally.

Context Value

The provider creates a React context with the following shape:

interface PPPContextValue {
  /** Raw API response data, or null if not yet loaded. */
  data: PPPResponse | null;
  /** Whether the API request is in-flight. */
  isLoading: boolean;
  /** Error from the API request, if any. */
  error: Error | null;
  /** ISO 3166-1 alpha-2 country code (e.g., 'IN'). */
  country: string | null;
  /** Discount percentage (0-100). */
  discount: number;
  /** Coupon code, if available. */
  code: string | null;
  /** Local currency code (e.g., 'INR'). */
  currencyCode: string;
  /** Local currency symbol (e.g., '₹'). */
  currencySymbol: string;
  /** FX rate from base currency to visitor's currency. */
  fxRate: number;
  /** Convert a base price to the visitor's local discounted price. */
  localPrice: (basePrice: number) => number;
  /** Format a price in the visitor's local currency. */
  formatPrice: (price: number, options?: Intl.NumberFormatOptions) => string;
  /** Country flag emoji (e.g., '🇮🇳'). */
  flag: string;
}

Access this context via the usePPP() hook.

Caching

The provider caches the API response in sessionStorage for 5 minutes using the key gpl_react_{apiKey}. This means:

• The first page load makes an API call
• Subsequent page loads within the session use cached data
• The cache is automatically invalidated after 5 minutes
• The cache is cleared when the browser tab is closed

Multiple Providers

You can have multiple providers for different products, each with their own API key:

<GoPayLocalProvider apiKey="gpl_pk_live_product1">
  <ProductOnePricing />
</GoPayLocalProvider>

<GoPayLocalProvider apiKey="gpl_pk_live_product2">
  <ProductTwoPricing />
</GoPayLocalProvider>

Caution

Do not nest providers. Each provider creates its own context, and nested providers will shadow the outer one.