Banner API

The banner API endpoints are public and use a public API key. No secret key or authentication is needed.

Get Banner Config

Returns PPP data and banner configuration for the current visitor.

GET /v1/banner/config/:publicKey

curl

curl -X GET https://api.gopaylocal.com/v1/banner/config/gpl_pk_live_abc123 \
  -H "Accept: application/json"

JavaScript

const res = await fetch(
  'https://api.gopaylocal.com/v1/banner/config/gpl_pk_live_abc123',
  { headers: { 'Accept': 'application/json' } }
);
const data = await res.json();

Response (discount available):

{
  "show": true,
  "country": "IN",
  "countryName": "India",
  "discount": 30,
  "code": "PPP-INDIA-30",
  "currencyCode": "INR",
  "currencySymbol": "₹",
  "fxRate": 83.12,
  "banner": {
    "position": "bottom-right",
    "messageTemplate": "Hey! It looks like you're visiting from {{countryName}}. We support PPP! Use code {{code}} for {{discount}} off.",
    "ctaText": "Copy Code",
    "backgroundColor": "#1a1a2e",
    "textColor": "#ffffff",
    "ctaColor": "#e94560",
    "ctaTextColor": "#ffffff",
    "showFlag": true,
    "showCloseBtn": true
  }
}

Response (no discount — Tier 1 country):

{
  "show": false,
  "country": "US",
  "countryName": "United States",
  "reason": "no_discount"
}

Response (no discount — VPN detected):

{
  "show": false,
  "country": "IN",
  "countryName": "India",
  "reason": "vpn_detected"
}

Response Fields

Field	Type	Description
show	boolean	Whether to display a discount
country	string	ISO 3166-1 alpha-2 country code
countryName	string	Full country name
discount	number	Discount percentage (0-100). Only present when show: true
code	string | null	Coupon code. Only present when show: true
currencyCode	string	Visitor’s local currency code
currencySymbol	string	Visitor’s local currency symbol
fxRate	number	FX rate from base currency to local currency
banner	object	Banner display configuration. Only present when show: true
reason	string	Why no discount is shown. Only present when show: false

Possible Reasons for show: false

Reason	Description
no_discount	Visitor’s country is in Tier 1 (no discount)
vpn_detected	VPN or proxy detected
domain_not_allowed	Request came from a domain not in the allowed list
campaign_paused	The campaign is currently paused
rate_limited	API rate limit exceeded

Get Banner Script

Returns a JavaScript file that renders the PPP banner.

GET /v1/banner/script.js?key=:publicKey

<script src="https://api.gopaylocal.com/v1/banner/script.js?key=gpl_pk_live_abc123" async></script>

This is an IIFE (Immediately Invoked Function Expression) script that:

1. Fetches banner config from the API
2. Creates a Shadow DOM element
3. Renders the banner with the visitor’s PPP data
4. Handles CTA clicks (copy to clipboard)
5. Handles close button (dismiss)
6. Sends analytics events via sendBeacon

Note

The banner script is the recommended approach for most sites. The banner config endpoint is used internally by the script and the SDKs. You typically don’t need to call it directly unless you’re building a custom integration.

CORS

The banner API endpoints support CORS from any origin. The Access-Control-Allow-Origin header is set to *.

If you’ve configured allowed domains on your campaign, the API still responds to requests from other domains but returns show: false with reason: "domain_not_allowed".

Caching

The API response includes cache headers:

Cache-Control: public, max-age=300

The SDKs also cache responses in sessionStorage for 5 minutes.