> ## 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.

# SDK reference

> Public SDK methods, donation options, result types, and Payframes field handles.

This reference covers the customer integration surface in SDK `0.1.0`. Load it
using the [installation guide](/external/onboarding/wegive-pay/sdk-installation).
The version's [TypeScript declarations](https://sdk.pay.wegive.com/v0.1.0/index.d.ts)
provide the exported types; download the companion declaration files with them.

## Initialize

```js theme={null}
const pay = WeGive.Pay.init({
  publishableKey: 'pk_test_REPLACE_WITH_YOUR_KEY',
});
```

For ES modules, import `WeGivePay` and call `WeGivePay.init()` instead.
`publishableKey` is required. It must be a key issued to your organization,
beginning with `pk_test_` or `pk_live_`. Initialization can throw for an invalid
configuration; successful construction alone does not prove the key is active
or the current origin is approved.

Use the default service configuration. Your integration does not need API-host,
processor, or verification-site-key overrides. Never pass a secret key here.

## Methods

| Method | Return value | Purpose |
| - | - | - |
| `pay.mountButton(target, options)` | Object with `unmount(): void` | Render a branded checkout button into a selector or element |
| `pay.open(options)` | `Promise<OpenResult>` | Open checkout directly from a user click |
| `pay.fetchBranding()` | `Promise<OrgBranding>` | Retrieve organization branding for your own UI |
| `pay.createFraudSession(options?)` | `Promise<FraudSession>` | Establish fresh browser verification context for a new payment attempt |
| `pay.getAttribution(explicit?)` | UTM object | Resolve explicit UTM values or those in the current page URL |
| `pay.payframes.mount(options)` | `Promise<PayframeFields>` | Mount secure card fields |

`mountButton()` requires an existing target element. It returns immediately and
loads branding asynchronously. It does not expose an update method: unmount and
remount for new options, or use `open()` with your form's current values.

`open()` resolves for checkout outcomes, including `cancel` and `error`.
Configuration or setup errors can also throw; use `try/catch` around the call.
Other asynchronous methods reject on failure. The ESM export `WeGivePayError`
extends `Error` and includes an HTTP `status` when available. Do not rely on exact
error wording for business logic or expose raw diagnostic payloads to donors.

### Branding

`fetchBranding()` returns organization information including `uuid`, `name`, and
optional `currency`, `primaryColor`, `foregroundColor`, `logoUrl`, and `avatarUrl`.
Use fallbacks for optional values. Branding is presentation data, not donor
authentication or proof that a payment succeeded.

### Fraud session

`createFraudSession()` returns an object with string `id` and `expiresAt` fields.
Its optional argument is `{ checkoutAttemptId: 'YOUR_SERVER_ATTEMPT_ID' }`.
Use a server-issued attempt identifier if correlating your own checkout records.
This identifier does not replace the processing API's `Idempotency-Key` header.
See [session lifetime](/external/onboarding/wegive-pay/versions-and-lifecycle#payframes-and-fraud-session-lifecycle).

### Attribution

`getAttribution(explicit?)` returns supported UTM keys with usable values. A
nonempty explicit set takes precedence over the current URL as a complete set;
the two sets are not merged. Supported keys are `utm_source`, `utm_medium`,
`utm_campaign`, `utm_term`, `utm_content`, and `utm_id`. This helper does not
persist attribution or access cookies.

## Donation options

Both `mountButton()` and `open()` accept these options:

| Option | Type | Meaning |
| - | - | - |
| `amount` | Required integer | Donation amount in minor units |
| `label` | Required nonempty string | Launch-button text |
| `currency` | String | Organization's ISO currency code; omitted uses its configured currency |
| `frequency` | `once` or `recurring` | Defaults to `once` |
| `email` | String | Prefill donor email; does not authenticate the donor |
| `organizationBrandId` | Number | Financial brand for the donation |
| `designationId` | Number | Designation identifier |
| `campaignId` | Number | Campaign identifier |
| `campaignFundraiserId` | Number | Campaign-fundraiser identifier |
| `fundraiserId` | Number | Fundraiser identifier |
| `checkoutId` | Number | Checkout identifier |
| `campaignEventId` | Number | Campaign-event identifier |
| `messageId`, `messageDonorId` | Strings | Messaging attribution identifiers, when supplied by your integration |
| `trackingUrl` | String URL | Source page; defaults to the embedding page URL |
| `utmParams` | UTM object | Explicit attribution values |
| `coverFees` | Boolean | Request the fee-coverage choice |
| `taxDeductible` | Boolean | Tax-deductibility setting for the donation |
| `tribute` | Object | Required `name`, optional `email` and `message` |
| `recurringFrequency` | String | Required schedule selection for a recurring integration |
| `recurringStartDate`, `recurringEndDate` | Date strings | `YYYY-MM-DD`; omitted start defaults to today |

Recurring cadences: `daily`, `weekly`, `1_and_15`, `bimonthly`, `monthly`,
`quarterly`, `semiannual`, and `yearly`. Confirm the displayed schedule with the
donor before opening checkout.

Button presentation options are `logo`, `hideLogo`, `className`, `brand`, and
`theme`. See the [complete theme reference](/external/onboarding/wegive-pay/customization)
for color tokens, shape, fonts, languages, string overrides, and form settings.

## Result and callbacks

```ts theme={null}
type TransactionResult = {
  id: number;
  amount: number;
  status: string;
};

type OpenResult = {
  status: 'success' | 'pending' | 'scheduled' | 'error' | 'cancel';
  error?: string;
  transaction?: TransactionResult;
  scheduledDonationId?: number;
};
```

| Callback | Argument |
| - | - |
| `onSuccess` | Successful `TransactionResult` |
| `onPending` | Pending `TransactionResult` |
| `onScheduled` | Numeric scheduled-donation ID; no initial transaction |
| `onCancel` | None |
| `onError` | `Error` |

Results are browser notifications. Validate recorded payment state before
server-side fulfillment. See [result semantics](/external/onboarding/wegive-pay/popup-checkout#understand-the-result).

## Payframes mount options

| Option | Type | Meaning |
| - | - | - |
| `cardNumber` | Required selector or `HTMLElement` | Card-number field container |
| `cardExpiry` | Required selector or `HTMLElement` | Expiration field container |
| `cardCvv` | Required selector or `HTMLElement` | Security-code field container |
| `style` | Object | CSS overrides inside the fields; use CSS property names such as `font-size` |
| `checkoutAttemptId` | String | Optional server-issued attempt identifier for correlation |

Use separate, empty containers with a visible height. There are no bank or
wallet mount methods on the Payframes SDK surface.

| Field method | Behavior |
| - | - |
| `await fields.ready()` | Wait for the mounted fields; this does not mean the donor has entered valid data |
| `fields.isValid()` | Whether all three fields report valid values |
| `await fields.tokenize()` | Return payment values; this does not charge the donor |
| `fields.destroy()` | Remove the mounted field elements when leaving the form |

`tokenize()` returns:

```ts theme={null}
type TokenizeResult = {
  cardNumber: string;       // Opaque tokenized card number.
  cardExpiration: string;   // Expiration in MMYY form.
  cardCvv: string;          // Opaque tokenized security code.
  fraudSessionId?: string;  // Pass a valid handle to your backend.
};
```

Send these values only to your backend over HTTPS. Do not log them, put them in
URLs, or store them in browser storage. Treat `cardNumber` and `cardCvv` as opaque;
do not parse or transform them. Follow the
[Payframes guide](/external/onboarding/wegive-pay/payframes-api) for processing
and long-lived form handling.


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