Options

Example

PybaraDonate.init({
  target: '#pybara-donate',
  recipientPrincipal: 'xxxxx-xxxxx-...',
  siteUrl: 'https://example.com',
  siteName: 'Example Charity',
  primaryColor: '#e11d48',
  currency: 'EUR',
  locale: 'fr',
  presetAmounts: [5, 10, 25],
  tokens: ['ckUSDC', 'ICP'],
  buttonLabel: 'Soutenir',
});

Options reference

PybaraDonate.init() takes one options object. The four options without ? are required; everything else falls back to the default shown.

PybaraDonate.init({

  // ── Required ──

  target: string | HTMLElement;  // CSS selector or element to render into
  recipientPrincipal: string;    // your Pybara Wallet principal — the one the site's DNS record lists
  siteUrl: string;               // the site's origin, e.g. 'https://example.com' — must match the verified site
  siteName: string;              // the name donors see

  // ── Donations ──

  presetAmounts?: number[];      // default [5, 10, 25, 50] — up to 6, in the display currency, each ≥ 0.50
  allowCustom?: boolean;         // default true — let donors enter their own amount
  currency?: string;             // default 'USD' — ISO 4217, e.g. 'EUR'; converted to USD for payment
  tokens?: string[];             // default all — 'ckUSDC', 'ckUSDT', 'ckBTC', 'ckETH', 'ICP'

  // ── Recurring ──

  allowRecurring?: boolean;          // default true — offer recurring donations
  defaultFrequency?: Frequency;      // default 'monthly' — 'weekly', 'monthly', 'yearly' ('every2min' is for testing)
  defaultDurationInMonths?: number | null;  // default 12 — 3, 6, 12 or 24 months, or null for no end date; donors can change it

  // ── Text and appearance ──

  title?: string;                 // shown above the amounts
  description?: string;           // shown below the title
  buttonLabel?: string;           // default 'Donate', in the widget's language
  thankYouMessage?: string;       // replaces the success screen's title, otherwise in the donor's language
  thankYouRedirectUrl?: string;   // where to send donors afterwards
  primaryColor?: string;          // default '#7c3aed' — accent colour (hex); match your site's
  theme?: 'light' | 'dark' | 'auto';  // default 'light' — 'auto' follows the page's background and theme switcher
  fontUrl?: string;               // a .woff2 font of your own; none is loaded otherwise

  // ── Language and behaviour ──

  locale?: string;   // default the browser's — 'en', 'fr', 'de', 'es', 'it', 'pt', 'nl', 'pl', 'ro', 'ja', 'ko' or 'zh-CN'
  staging?: boolean; // default false — Pybara's staging environment; never on a live site
  debug?: boolean;   // default false — log details to the console

  onSuccess?: (data: DonationResult) => void;  // called once the donation is made
  onError?: (error: Error) => void;            // called on an error
  onClose?: () => void;                        // called when the checkout is closed without donating

  // ── Donor fields ──
  // Prefill for donors you already know; every one is sanitized server-side.

  siteCountry?: string;    // your site's base country (ISO 3166-1 alpha-2)
  donorIsAnonymous?: boolean;  // hide the donor's name/details from recipient-facing displays
  donorMessage?: string;       // free-text message from donor to recipient
  donorFirstName?: string;
  donorLastName?: string;
  donorCompany?: string;
  donorEmail?: string;     // stored for the receipt feature; never publicly displayed
  donorCountry?: string;
  donorAddressLine1?: string;  // the address fields count as provided only as a complete set
  donorAddressLine2?: string;
  donorAddressCity?: string;
  donorAddressState?: string;
  donorAddressPostalCode?: string;
  donorAddressCountry?: string;
  donorTosVersion?: string;       // terms version the donor accepted, e.g. '1-0'
  donorTosAcceptedAt?: string;    // its ISO 8601 UTC timestamp
  recipientTosVersion?: string;   // terms version you accepted, as site operator
  recipientTosAcceptedAt?: string;
  pluginVersion?: string;         // the integration forwarding the donation, e.g. '1.2.0'
});

For agents and editors

The same options are published as a JSON Schema at /donate-widget/options.schema.json — an agent or an editor with schema support can validate a config object against it before it is written.