Install the SDK from a URL - WeGive Documentation

WeGive Pay does not require an npm package. This guide uses SDK 0.1.0. Keep the version in the URL so a release does not silently change your installed JavaScript. Test and live credentials use the same SDK file.

Option 1: Add a script tag

Load the browser bundle before your integration code:

<script
  src="https://sdk.pay.wegive.com/v0.1.0/wegive-pay.iife.js"
  integrity="sha384-FpXrJhUXBouGVVeqCRCgBlpMiJZdasKl+jVqJ+Li//qXB1nkAIQrAseifHBXlj+3"
  crossorigin="anonymous"
></script>
<script>
  const pay = WeGive.Pay.init({
    publishableKey: 'pk_test_REPLACE_WITH_YOUR_KEY',
  });
</script>

The script exposes window.WeGive.Pay. The integrity value pins the file’s contents as well as its URL. Change both together when upgrading. Do not add async unless your application explicitly waits for the SDK to load before calling it. If your site forbids inline scripts, put initialization in an allowed external script or use your site’s nonce-based script policy.

Option 2: Import the ES module from its URL

<script type="module">
  import { WeGivePay } from 'https://sdk.pay.wegive.com/v0.1.0/wegive-pay.js';

  const pay = WeGivePay.init({
    publishableKey: 'pk_test_REPLACE_WITH_YOUR_KEY',
  });

  pay.mountButton('#donate', {
    amount: 5000,
    label: 'Donate',
  });
</script>
<div id="donate"></div>

Use this in browsers that support ES modules. The module loads companion code when needed for Payframes. A bundler may require local files instead of HTTPS module imports; use the next option in that case.

Option 3: Download and vendor a release

For a script-tag integration, download wegive-pay.iife.js, verify its checksum, and serve it from your application’s static assets. Keep the version in your local path, for example /vendor/wegive-pay/v0.1.0/wegive-pay.iife.js. For an ES module or bundled integration, download every runtime .js file listed in release.json, preserving their filenames and relative paths. Download the .d.ts files too if you use TypeScript. Downloading only wegive-pay.js leaves out the Payframes companion module. This Node.js script downloads and verifies the runtime files and type declarations into a local vendor directory. Save it as download-wegive-pay.mjs and run node download-wegive-pay.mjs:

import { createHash } from 'node:crypto';
import { mkdir, writeFile } from 'node:fs/promises';

const version = '0.1.0';
const base = `https://sdk.pay.wegive.com/v${version}/`;
const destination = new URL(`./vendor/wegive-pay/v${version}/`, import.meta.url);

const manifestResponse = await fetch(`${base}release.json`);
if (!manifestResponse.ok) throw new Error('Could not download SDK manifest');
const manifest = await manifestResponse.json();
if (manifest.version !== version) throw new Error('Unexpected SDK version');

await mkdir(destination, { recursive: true });
for (const [name, expectedHash] of Object.entries(manifest.files)) {
  if (!name.endsWith('.js') && !name.endsWith('.d.ts')) continue;
  if (!/^[A-Za-z0-9._-]+$/.test(name)) throw new Error('Unexpected file path');

  const response = await fetch(`${base}${name}`);
  if (!response.ok) throw new Error(`Could not download ${name}`);
  const bytes = Buffer.from(await response.arrayBuffer());
  const actualHash = `sha384-${createHash('sha384').update(bytes).digest('base64')}`;
  if (actualHash !== expectedHash) throw new Error(`Checksum mismatch: ${name}`);
  await writeFile(new URL(name, destination), bytes);
}
await writeFile(new URL('release.json', destination), JSON.stringify(manifest, null, 2));

Import the local module from your client-side application code, adjusting the relative path to your project:

import { WeGivePay } from './vendor/wegive-pay/v0.1.0/wegive-pay.js';

const pay = WeGivePay.init({ publishableKey: 'pk_test_REPLACE_WITH_YOUR_KEY' });

For TypeScript, the release’s index.d.ts exports the public declarations. You can import types from that file while importing runtime code from wegive-pay.js:

import type { ButtonOptions, OpenResult } from './vendor/wegive-pay/v0.1.0/index';

const options: ButtonOptions = { amount: 5000, label: 'Donate' };
function isCompleted(result: OpenResult): boolean {
  return result.status === 'success';
}

If your compiler requires a declaration beside the JavaScript entry, add a local wegive-pay.d.ts adapter that re-exports the release’s declarations:

export * from './index';
export { default } from './index';

Vendoring the SDK hosts the browser library on your domain. Checkout, tokenization, and processing still use WeGive’s hosted services; the SDK is not an offline payment processor.

Available release files

File	Purpose
`wegive-pay.iife.js`	Browser script; exposes `WeGive.Pay`
`wegive-pay.js`	ES module; exports the SDK runtime
Companion `.js` files	Runtime code used by the ES module; retain the manifest’s filenames
`index.d.ts` and the other `.d.ts` files	TypeScript declarations; keep them together
`release.json`	Version and per-file SHA-384 hashes
`SRI.txt`	Human-readable integrity hashes

Frameworks and browser policies

Initialize the SDK in browser code after the mount elements exist. In applications with server rendering, use a client component or browser-only lifecycle hook. Create one instance per active key configuration; do not reinitialize on every render. Mount once and clean up on route or component removal using button.unmount() or fields.destroy(). Allow the SDK origin in your content security policy, along with the WeGive API, secure-field, and verification resources required by your enabled integration. Tokenization loads third-party frames and scripts in addition to the SDK file; ask WeGive for the applicable allowlist if your site uses a restrictive policy. Do not disable verification scripts or use a policy that severs the checkout window’s connection to its opener. Test browser isolation policies with your actual integration. Continue with hosted checkout or Payframes.

​Option 1: Add a script tag

​Option 2: Import the ES module from its URL

​Option 3: Download and vendor a release

​Available release files

​Frameworks and browser policies

Option 1: Add a script tag

Option 2: Import the ES module from its URL

Option 3: Download and vendor a release

Available release files

Frameworks and browser policies