SDK reference - WeGive Documentation

This reference covers the customer integration surface in SDK 0.1.0. Load it using the installation guide. The version’s TypeScript declarations provide the exported types; download the companion declaration files with them.

Initialize

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.

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 for color tokens, shape, fonts, languages, string overrides, and form settings.

Result and callbacks

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.

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:

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 for processing and long-lived form handling.

​Initialize

​Methods

​Branding

​Fraud session

​Attribution

​Donation options

​Result and callbacks

​Payframes mount options