Changelog

Release notes for the Donations Embed — covering the API, the browser embed bundle, and the server SDKs in TypeScript / Node, Python, and Go.

The three artifacts version independently, but their initial GA releases ship together as v1.0.0. Future entries will note which artifact a change applies to.

Documentation correction — 2026-10-18

The status page these notes announced with v1.0.0 (status.1stflock.com/donations-embed) never went live, and the links to it are removed. Report an outage to support@1stflock.com, 24/7.

v1.6.2

Fixed

• Give frame: a live-stream gift is named only with the name the form previewed. The confirm sends that name (shown_name) and the API names the gift only when its own name for the donor is exactly it -- and only when the first and last names are the name the donation is saved under. The preview is cleaned exactly as the live room cleans a name, and a name the room would not show (one that mixes alphabets) is not previewed: the form says the gift will show its amount only. (@1st-flock/donations 2.5.2.)

v1.6.1

Fixed

• Give frame: the confirm sends the donor's first and last names apart, so a live-stream gift shown with its giver's name is the name the form previewed ("Jane van der Berg" is Jane V. on both); the notice says a gift's line stays in the stream's chat. (@1st-flock/donations 2.5.1.)

v1.6.0

Added

• Give frame: a gift given inside a live stream's player may show who gave it. The form offers "Show my name on screen" -- unticked unless the donor ticks it -- with a notice that gifts during the stream show their amount briefly over the video and in the chat, a preview of the name ("Ada L."), and an "On screen" line in the summary. An anonymous gift is never named: the box goes and the notice says the amount shows without a name. The form offers the choice only when the session's /v1/embed/config answer carries live_stream: {name_on_screen: true}.
• API: /v1/embed/config carries live_stream (null outside a give session); the confirm accepts show_name_on_screen.

Changed

• Give frame: Back / Next stay pinned to the bottom of the panel while the step scrolls above them, so the way on is always in view in a short panel; a one-option "Donation Type" selector (one-time only) is no longer shown.
• The summary no longer shows an empty donor and email above "Anonymous" for an anonymous guest.

v1.5.0 — unreleased

Added

• Browser embed: the give frame, https://payments.1stflock.com/v1/give (and https://sandbox.payments.1stflock.com/v1/give; pinned: /vX.Y.Z/give). It is the donation form as a page of its own, for a giving panel inside a live-stream player: the player frames it, and card details stay in the form's own secure fields inside it. It shows the church's name and colour and nothing else, and links nowhere but to the two Google pages reCAPTCHA's notice must name (the frame shows that notice in place of reCAPTCHA's floating badge, which covered the Pay button in a narrow panel).
• The give frame is served with a strict Content-Security-Policy: nothing loads by default; its one script of ours runs by a per-response nonce and its integrity hash; only the payment and bank-linking providers' own addresses are allowed besides; no inline script, no eval; it may be framed only from https pages. The page is never cached.
• The SRI manifest (/sri/vX.Y.Z.json) gains inline_style_hashes, the hashes the give frame's policy allows for the constant inline styles in the bundle. A version without a valid manifest has no give frame.
• Browser embed: BackendClient accepts a give session (giveSession) in place of a publishable key, for that frame. A give session is made by the platform for one live broadcast; the church a gift goes to comes from it, on the server.

Changed

• Nothing for existing integrations: <flock-donate> and publishable keys work exactly as before.

Fixed

• Browser embed: the bundle's stylesheet is built from the form's packages as installed, in any checkout and in CI. Builds since the form moved into those packages could ship a stylesheet without the form's classes, and an unstyled form; the build now fails if the stylesheet is missing them.
• Browser embed: on "Review & Pay", a payment error is shown right after the Pay button (or the bank form's button), announced to screen readers and brought into view, instead of at the top of the step where it could be out of sight.
• Browser embed: in the dark theme, the card-number and security-code fields no longer show as white boxes; they match the form's other inputs.
• Give frame: bank linking opens over the whole frame with no policy violations.

v1.4.1 — 2026-08-05

Fixed

• Browser embed: a fund split that lands on a half dollar now shows both decimal places. An even 50/50 split of a $105.00 gift rendered as $52.5 beside the $105.00 it was derived from; it now reads $52.50. Whole-dollar splits show as $50.00 rather than $50. Suggested-amount buttons are unaffected — those are whole dollars by design.

v1.1+ — Hostname split

The browser embed bundle now ships from environment-specific hosts:

• Live mode — https://payments.1stflock.com/v1.js, paired with pk_live_… publishable keys.
• Sandbox mode — https://sandbox.payments.1stflock.com/v1.js, paired with pk_test_… publishable keys.

The legacy single-host bundle at https://embed.1stflock.com/v1.js continues to resolve and serve the same bytes — existing integrations are not broken — but new integrations should use the env-specific hosts so the SDK can enforce the key/host pairing.

Why the split

Previously, a single host served the embed for both environments and key-environment validation happened only at the API edge (a pk_test_… key paired with a live API endpoint returned 401). The split lets the SDK fail fast on the client, with a clear actionable error, before any network call.

Cross-mismatch enforcement

The SDK now refuses to mount when the key environment does not match the host:

Cross-mismatch enforcement. If you load the SDK from payments.1stflock.com but supply a pk_test_* key, the SDK throws with: Live SDK cannot use test keys. Load https://sandbox.payments.1stflock.com/v1.js instead. Same in reverse for sandbox.payments.1stflock.com + pk_live_*.

This catches an entire class of "wrong key in the wrong environment" mistakes at integration time — before any donor sees a broken flow.

Migration

If you are integrating fresh, copy the snippet from the Hub's Embed Snippet card; it always uses the env-paired host for the key environment you selected.

If you have an existing integration on the legacy host, no immediate action is required — the legacy host continues to serve. When you next touch the snippet (or rotate keys), swap to the env-paired host:

• Live integrations: change embed.1stflock.com → payments.1stflock.com in the script src.
• Sandbox integrations: change embed.1stflock.com → sandbox.payments.1stflock.com in the script src.

The bundle bytes are identical, so the SRI integrity value does not change.

CSP allowlists should be updated to include the new hosts. The full recipe is in Compliance & Security → CSP and SRI recipe.

v1.0.0 — 2026-04-25

Initial general-availability release.

What ships

API (https://api.1stflock.com/v1/embed/)

• Browser cohort — GET /v1/embed/health, GET /v1/embed/config, GET /v1/embed/funds, POST /v1/embed/sessions, POST /v1/embed/sessions/{id}/confirm. Authenticated with publishable key + browser Origin header.
• Customer SDK cohort — GET /v1/embed/donations, GET /v1/embed/donations/{id}, POST /v1/embed/donations/{id}/refund, GET /v1/embed/recurring, POST /v1/embed/recurring/{id}/cancel, POST /v1/embed/webhooks/test. Authenticated with secret key.
• Hub cohort — key pair management, theme JSON, webhook endpoint configuration, delivery history, SAQ A PDF generation, and analytics endpoints. Authenticated with the user session cookie.
• Admin cohort — platform pricing, processor cost bookkeeping, aggregate volume reporting. Restricted to super-admin RBAC scope.
• Cursor pagination on every list endpoint, with a default page size of 50 and a cap of 200.
• Idempotency on every mutating endpoint via the Idempotency-Key header. Replays return the original response without contacting the gateway.
• Vendor-neutral identifiers throughout — processor_transaction_id, processor_refund_id, processor_subscription_id. The underlying gateway is an implementation detail.
• Rate limits: 60 req/min per browser key, 1000 req/min per secret key, 1000 req/min per Hub user.
• Sandbox cluster at https://api.sandbox.1stflock.com with the same wire format and SDK code path.

Browser embed (@1st-flock/donations-embed, https://payments.1stflock.com/v1.js for live and https://sandbox.payments.1stflock.com/v1.js for sandbox)

• Web component — <flock-donate> with eighteen configurable attributes covering keys, render modes, fund and frequency restrictions, fee coverage, recurring opt-in, themes, success modes, amount limits, language, analytics opt-out (data-no-analytics), and the trust-footer toggle.
• React wrapper — <FlockDonate> from @1st-flock/donations-embed-react. Seventeen of the eighteen attributes are mapped as React props (e.g. data-no-analytics → noAnalytics); plus typed on* handlers for the five CustomEvents. The one omitted prop is trust-footer; see Browser Embed → trust-footer for a ref-based workaround pending the next minor wrapper release.
• Three render modes — inline, modal, drawer.
• Four built-in themes — modern, minimal, classic, playful. Per-organisation theming via the Hub.
• Four-layer theme precedence — built-in defaults → preset → Hub theme JSON → CSS custom properties on the element.
• Five host events — flock-donation-opened, flock-donation-step, flock-donation-complete, flock-donation-failed, flock-donation-closed. All bubbles: true, composed: true so they reach window-level analytics listeners.
• Three success modes — inline, redirect (with success-url + ?confirmation_id appended), callback.
• Card and ACH support — both payment types tokenised inside an isolated iframe before any field value crosses the iframe boundary. SAQ A scope from day one.
• Shadow DOM isolation — your site's CSS does not collide with the embed's styles.
• Mode-aware bundle delivery — single CDN-served module bundle, no polyfills shipped by default. Targets evergreen Chrome / Edge / Firefox / Safari on the last two major versions.

Server SDKs

TypeScript / Node (@1st-flock/donations-embed-node v1.0.0)

• Native fetch and crypto. Zero runtime dependencies. Ships as ESM and CJS.
• Requires Node 18.17 or newer. Runs on Bun and Deno (with Node-compat shim).
• Typed Client covering all six Customer SDK methods.
• Constant-time HMAC-SHA256 webhook verifier (verifyWebhook) returning a discriminated event union.
• Typed error hierarchy — AuthError, ForbiddenError, NotFoundError, ConflictError, GoneError, ValidationError, RateLimitError, BadGatewayError, ServiceUnavailableError, base ApiError.
• Verify-only subpath import (@1st-flock/donations-embed-node/webhooks) for consumers that want only the verifier.
• Three runnable examples under examples/: webhook verification, refund CLI, recurring schedule streamer.

Python (onefirstflock-donations-embed v1.0.0)

• httpx-based async client with Pydantic v2 models throughout.
• Requires Python 3.10 or newer.
• Async Client covering all six Customer SDK methods.
• Sync and async constant-time webhook verifier (verify_webhook, verify_webhook_async) returning a discriminated event union.
• Typed exception hierarchy mirroring the Node SDK.
• Three runnable examples under examples/: FastAPI webhook endpoint, refund CLI, recurring schedule streamer.

Go (gitlab.com/1st-flock/donations/go/donations-embed v1.0.0)

• Standard library only. Zero third-party dependencies.
• Requires Go 1.22 or newer.
• *Client covering all six Customer SDK methods.
• Constant-time HMAC-SHA256 webhook verifier (VerifyWebhook) returning a parsed envelope.
• Typed error hierarchy via errors.As.
• Three runnable examples under examples/: net/http webhook server, refund CLI, recurring schedule streamer.

Webhooks

• Nine event types — donation.created, donation.completed, donation.failed, donation.refunded, recurring.activated, recurring.payment_succeeded, recurring.payment_failed, recurring.cancelled, key.frozen.
• HMAC-SHA256 signatures with a 5-minute timestamp tolerance for replay protection.
• At-least-once delivery with eight total attempts and exponential backoff over ~43 hours.
• Per-organisation signing secret revealed once at endpoint creation; rotated by changing the URL.
• Hub-side delivery inspector — every delivery for the last 30 days surfaced under Donations Embed → Webhooks → Deliveries with replay capability.
• Cross-SDK byte-compatibility — a signature produced by the platform verifies under any SDK; a signature produced by any SDK verifies under any other SDK.

Compliance and security

• PCI DSS Level 1 Service Provider certification annual cycle.
• SAQ A pre-filled PDF generator in the Hub for customer self-assessment.
• Data Processing Addendum (DPA) pre-signed in the Hub.
• Subprocessor list under Hub privacy settings.
• CSP and SRI guidance in Compliance & Security.

Operations

• 12-month deprecation window for breaking changes. Multi-channel notification (changelog, in-Hub banner, email at announcement / 90 / 30 / 7 days, Flock-Deprecation response header).
• 24-hour rotation grace window for zero-downtime key pair rotations.
• Automatic key freezing on card-testing detection, with a key.frozen webhook for in-app notification.

Documentation

• Complete documentation set published at https://1stflock.com/docs/donations-embed:
  • Getting Started — 5-minute Quickstart.
  • Browser Embed — full attribute reference.
  • Server SDKs — three language sub-docs.
  • Webhooks — event catalogue, signing, delivery model.
  • Compliance & Security — SAQ A, CSP, customer obligations.
  • Integration Examples — six per-platform recipes.
  • API Reference — endpoint-by-endpoint reference.
  • Operations — versioning, deprecation, rate limits.

Known issues

• Python wheel onefirstflock-donations-embed==1.0.0 is unimportable. The published wheel omits donations_embed/models/webhook_test.py (the file ends with _test.py and was accidentally matched by the build's test-file exclude pattern). import donations_embed raises ModuleNotFoundError. Workaround: install the prior tagged source via pip install git+https://gitlab.com/1st-flock/donations@v1.0.0#subdirectory=python/donations-embed until v1.0.1 is published. Fix: v1.0.1 will tighten the wheel's exclude pattern to drop **/*_test.py and re-cut the release.
• Go SDK webhook errors are sentinels, not error structs. Customers using var fmtErr *donationsembed.WebhookFormatError; errors.As(err, &fmtErr) per pre-1.0 doc snippets will not compile against v1.0.0. The actual API uses sentinel errors: errors.Is(err, donationsembed.ErrSignatureMalformed) (and ErrSignatureMismatch, ErrTimestampOutOfRange). The docs in this changelog and server-sdks/go.md were corrected post-publish — re-pull them if you fetched cached copies before 2026-04-28.
• Go SDK IdempotencyKey joins prefix with -, not :. The Go function returns refund-1f2dab36-… (the TS / Python equivalents return refund:1f2dab36-…). Both forms are accepted by the platform's Idempotency-Key header. Cosmetic difference only.
• React wrapper does not expose trust-footer. The eighteenth web-component attribute lacks a first-class React prop in v1.0.0. Workaround in Browser Embed → trust-footer.

Future entries

Subsequent releases will follow this format:

## v1.x.0 — YYYY-MM-DD

### Added
- New endpoint, new SDK method, new event type, new attribute, etc.

### Changed
- Behavioural improvement (faster, broader retry coverage, better error message).

### Fixed
- Bug fix.

### Deprecated
- Surface scheduled for removal — with replacement and removal date.

### Breaking
- Behavioural change that requires customer code changes (only ships in a major-version bump).

Subscribe to release notifications via:

• The Operations page (in-Hub banner, email).
• The Flock-Deprecation response header on calls to deprecated endpoints (machine-readable for your own monitoring).