JavaScript SDK Installation

The JavaScript SDK provides an imperative API for adding PPP discounts to any JavaScript application — vanilla JS, Vue, Svelte, WordPress, or any framework.

Install

npm

npm install @gopaylocal/js

pnpm

pnpm add @gopaylocal/js

yarn

yarn add @gopaylocal/js

bun

bun add @gopaylocal/js

Quick Start

1. Create a client instance

   import { GoPayLocal } from '@gopaylocal/js';
   
   const gpl = new GoPayLocal({
     apiKey: 'gpl_pk_live_abc123',
   });

2. Initialize and fetch PPP data

   const data = await gpl.init();
   
   if (data?.show) {
     console.log(`${data.countryName}: ${data.discount}% off`);
     console.log(`Coupon: ${data.code}`);
   }

3. Get localized prices

   const pricing = gpl.getPrice(99.99);
   console.log(pricing.formatted);         // "₹4,999"
   console.log(pricing.formattedOriginal); // "$99.99"
   console.log(pricing.hasDiscount);       // true

Configuration

const gpl = new GoPayLocal({
  // Required
  apiKey: 'gpl_pk_live_abc123',

  // Optional
  apiBase: 'https://api.gopaylocal.com',    // Custom API URL
  environment: 'production',                 // 'production' | 'sandbox'
  baseCurrencyCode: 'USD',                   // Your base currency
  baseCurrencySymbol: '$',                   // Your base currency symbol
  cacheTtl: 5 * 60 * 1000,                  // Cache TTL in ms (default: 5 min)

  // Callbacks
  onLoad: (data) => console.log('Loaded:', data),
  onError: (error) => console.error('Error:', error),
});

Option	Type	Default	Description
apiKey	string	(required)	Public API key (starts with gpl_pk_)
apiBase	string	'https://api.gopaylocal.com'	API base URL
environment	'production' | 'sandbox'	'production'	Target environment
baseCurrencyCode	string	'USD'	Base currency code
baseCurrencySymbol	string	'$'	Base currency symbol
cacheTtl	number	300000 (5 min)	Cache TTL in milliseconds
onLoad	(data: PPPData) => void	—	Called when data loads
onError	(error: Error) => void	—	Called on error

What’s Included

import { GoPayLocal, formatCurrency, countryToFlag, splitPrice } from '@gopaylocal/js';

Export	Description
GoPayLocal	Main SDK class
formatCurrency	Format a number as currency
countryToFlag	Convert country code to flag emoji
splitPrice	Split formatted price into integer/decimal parts

TypeScript

Full type definitions are included:

import type { GoPayLocalConfig, PPPData, PricingResult, BannerOptions } from '@gopaylocal/js';

When to Use JS SDK vs. Banner Script

	Banner Script	JavaScript SDK
Setup	One <script> tag	npm install + code
Control	Dashboard only	Full programmatic control
Custom UI	No	Yes — build any UI
Data access	No	Full access to PPP data
Framework	Any (HTML)	Any (JS runtime)
Best for	Quick setup	Custom pricing displays

Tip

For React apps, consider the React SDK instead — it provides hooks and components that integrate directly with React’s rendering model.