GoPayLocal Client

The GoPayLocal class is the core of the JavaScript SDK. It handles initialization, data fetching, price calculation, and banner rendering.

Constructor

import { GoPayLocal } from '@gopaylocal/js';

const gpl = new GoPayLocal({
  apiKey: 'gpl_pk_live_abc123',
});

See Installation for all configuration options.

Methods

init()

Initialize the SDK by fetching PPP data for the current visitor. Call this once on page load.

const data = await gpl.init();

Returns: Promise<PPPData | null>

• Returns PPPData if the visitor is eligible for a discount
• Returns null if no discount applies (e.g., US visitor, VPN detected)
• Uses sessionStorage cache if available (5-minute TTL)
• Has an 8-second request timeout

const data = await gpl.init();

if (data) {
  console.log(data.country);      // "IN"
  console.log(data.countryName);  // "India"
  console.log(data.discount);     // 30
  console.log(data.code);         // "PPP-INDIA-30"
  console.log(data.currencyCode); // "INR"
  console.log(data.currencySymbol); // "₹"
  console.log(data.fxRate);       // 83.12
  console.log(data.flag);         // "🇮🇳"
  console.log(data.show);         // true
}

getData()

Get the current PPP data without triggering a fetch. Returns null if init() has not been called or no discount applies.

const data = gpl.getData();

Returns: PPPData | null

isLoading()

Check if data is currently being fetched.

if (gpl.isLoading()) {
  showSpinner();
}

Returns: boolean

getError()

Get the last error, if any.

const error = gpl.getError();
if (error) {
  console.error('GoPayLocal failed:', error.message);
}

Returns: Error | null

getCode()

Get the coupon code.

const code = gpl.getCode();
// "PPP-INDIA-30" or null

Returns: string | null

getCountry()

Get country information for the current visitor.

const country = gpl.getCountry();
if (country) {
  console.log(country.code); // "IN"
  console.log(country.name); // "India"
  console.log(country.flag); // "🇮🇳"
}

Returns: { code: string; name: string; flag: string } | null

---

getPrice()

Calculate a localized, discounted price from a base price.

const pricing = gpl.getPrice(99.99);

Parameters:

Parameter	Type	Default	Description
basePrice	number	(required)	Price in your base currency
options.localize	boolean	true	Convert to visitor’s local currency
options.showDecimal	boolean	true	Include decimal digits

Returns: PricingResult

interface PricingResult {
  originalPrice: number;      // 99.99
  discountedPrice: number;    // 69.99 (after 30% discount)
  localPrice: number;         // 5819.27 (in visitor's currency)
  formatted: string;          // "₹5,819.27"
  formattedOriginal: string;  // "$99.99"
  integer: string;            // "5,819"
  decimal: string;            // "27"
  currencySymbol: string;     // "₹"
  currencyCode: string;       // "INR"
  hasDiscount: boolean;       // true
  discount: number;           // 30
}

Examples:

// With localization (default)
const p1 = gpl.getPrice(99.99);
console.log(p1.formatted); // "₹5,819"

// Without localization (discount only, stay in USD)
const p2 = gpl.getPrice(99.99, { localize: false });
console.log(p2.formatted); // "$69.99"

// Without decimals
const p3 = gpl.getPrice(99.99, { showDecimal: false });
console.log(p3.formatted); // "₹5,819"

formatPrice()

Format a number as currency using Intl.NumberFormat.

const formatted = gpl.formatPrice(5819.27);
// "₹5,819.27"

const formattedUsd = gpl.formatPrice(99.99, 'USD');
// "$99.99"

Parameters:

Parameter	Type	Default	Description
amount	number	(required)	Number to format
currencyCode	string	Visitor’s currency	Currency code (ISO 4217)

Returns: string

---

subscribe()

Subscribe to data changes. The listener is called whenever PPP data is loaded or cleared.

const unsubscribe = gpl.subscribe((data) => {
  if (data) {
    updatePricingUI(data);
  }
});

// Later, to stop listening:
unsubscribe();

Parameters:

Parameter	Type	Description
listener	(data: PPPData | null) => void	Callback for data changes

Returns: () => void (unsubscribe function)

This is useful for reactive frameworks like Vue or Svelte:

// Vue 3 example
import { ref, onMounted, onUnmounted } from 'vue';

const pppData = ref(null);
let unsubscribe;

onMounted(async () => {
  unsubscribe = gpl.subscribe((data) => {
    pppData.value = data;
  });
  await gpl.init();
});

onUnmounted(() => {
  unsubscribe?.();
});

---

showBanner()

Show a PPP discount banner. Returns a handle with a remove() method.

const banner = gpl.showBanner({
  position: 'bottom-right',
  backgroundColor: '#1a1a2e',
  onClose: () => console.log('Banner closed'),
});

// Later, to remove the banner:
banner.remove();

See Banner for full options.

---

Full Example

import { GoPayLocal } from '@gopaylocal/js';

const gpl = new GoPayLocal({
  apiKey: 'gpl_pk_live_abc123',
  onLoad: (data) => {
    console.log(`Loaded PPP data for ${data.countryName}`);
  },
  onError: (error) => {
    console.error('Failed to load PPP data:', error);
  },
});

async function initPricing() {
  const data = await gpl.init();

  if (!data) {
    // No discount — show original prices
    return;
  }

  // Update pricing display
  const plans = [
    { name: 'Pro', basePrice: 9 },
    { name: 'Business', basePrice: 29 },
  ];

  for (const plan of plans) {
    const pricing = gpl.getPrice(plan.basePrice);
    const el = document.querySelector(`[data-plan="${plan.name}"]`);
    if (el) {
      el.querySelector('.price').textContent = pricing.formatted;
      el.querySelector('.period').textContent = '/mo';

      if (pricing.hasDiscount) {
        el.querySelector('.original-price').textContent = pricing.formattedOriginal;
        el.querySelector('.discount-badge').textContent = `${pricing.discount}% off`;
      }
    }
  }

  // Show the discount banner
  gpl.showBanner({ position: 'bottom-right' });
}

initPricing();

Note

The GoPayLocal class is designed to be instantiated once and used throughout your app. Do not create multiple instances with the same API key.