> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wegive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install the SDK from a URL

> Load a versioned script, import an ES module, or vendor the WeGive Pay SDK into your application.

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:

```html theme={null}
<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

```html theme={null}
<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](https://sdk.pay.wegive.com/v0.1.0/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`:

```js theme={null}
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:

```js theme={null}
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`:

```ts theme={null}
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:

```ts theme={null}
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](/external/onboarding/wegive-pay/popup-checkout)
or [Payframes](/external/onboarding/wegive-pay/payframes-api).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.