# Repejo

> Repejo is a donation and recurring-payment platform for non-profits. This file
> points AI coding agents (e.g. Lovable, Cursor) to Repejo's machine-readable API
> specs and integration docs. The HTTP API is described with OpenAPI 3.1, which is
> the source of truth — point your tooling at the OpenAPI URL below.

## Which integration?

There are two ways to take a donation. Decide before writing front-end code, and
**ask** the integrating organisation if it is unclear which they want — the two
need different code:

- **Embedded checkout — no backend, no API token.** One script tag plus
  `<repejo-checkout short_code="…" host="…">` on your page. Repejo renders the
  amount screen, the donor form, the payment and the thank-you screen, and
  dispatches `repejo:completed` on the page. Use it when Repejo's form is
  acceptable (campaign pages, donation pages, "become a monthly donor" buttons,
  team competitions). Fixed-amount one-time Swish buttons without a backend:
  `<repejo-donate-button amount="100">`. Reference: https://test.repejo.se/docs/embed.md
- **Payment Sessions — backend required.** Your own amount buttons / donor form:
  your server calls `POST /api/v1/payment_session` with the amount, the donor
  and your `metadata`, then redirects the donor to `payment_url` or embeds
  `<repejo-checkout session-token="…">`, which skips the amount screen; reconcile
  via `payment_session.*` webhooks. Needs an organisation API token and an
  API-type checkout. Reference: https://test.repejo.se/docs/api-payment-sessions.md

The embedded element **cannot take an amount** (no attribute, no query
parameter), so a custom amount picker always means Payment Sessions. Both can
live on the same site.

## Embedded checkout (no backend)

- [Embedded checkout — Markdown](https://test.repejo.se/docs/embed.md): the script tag, `<repejo-checkout>` and its attribute contract (`short_code`, `host`, `team`, `teams-picker`, `metadata-*`, `payer-name` / `payer-email` / `payer-phone-number`, `user-has-consented-to-marketing-cookies`), the modal button `<repejo-checkout-button>`, the side tab `<repejo-sticky-checkout>`, the one-click Swish `<repejo-donate-button amount>`, the hosted page `{host}/s/{short_code}`, the `repejo:*` DOM events with the `repejo:completed` detail type, host-overridable typography variables vs branding-driven card styling, which webhook families a plain embed emits, and the test vs production host rule.
- [Website implementation — docs page](https://test.repejo.se/docs/website-implementation): the same guide, human-formatted.

## API

- [OpenAPI 3.1 spec (JSON)](https://test.repejo.se/api/v1/openapi): authoritative machine-readable API contract (operations, schemas, enums, errors).
- [Swagger UI](https://test.repejo.se/api/v1/swagger): interactive API explorer.

## Payment Sessions (Pay by Link)

- [Payment Sessions — Markdown](https://test.repejo.se/docs/api-payment-sessions.md): full reference in agent-friendly Markdown — auth, request/response, enums, errors, redirect & embedded modes (the `<repejo-checkout>` element: attribute/property binding, styling, and TypeScript/React types at https://test.repejo.se/assets/repejo-checkout.d.ts), webhooks, and the mandate document downloads (`GET /api/v1/subscriptions/:id/mandate_pdf_masked`, `GET /api/v1/subscriptions/:id/mandate_pdf_unmasked`, `GET /api/v1/mandates/:id/signature_xml` — Bearer-authenticated, urls delivered in the `documents` object of `payment_session.finalized` and `subscription.*` webhooks, `404` when a document is not available).
- [Payment Sessions — docs page](https://test.repejo.se/docs/api-payment-sessions): the same reference, human-formatted.

## Webhooks

- [Webhooks — Markdown](https://test.repejo.se/docs/api-webhooks.md): event types (`payer.*`, `subscription.*`, `transaction.*`, `receivable.*`, `payment_session.created` / `.succeeded` / `.finalized` / `.cancelled`), payload shape incl. the `documents` object, HMAC-SHA256 signing, and retry/idempotency contract in agent-friendly Markdown.
- [Webhooks reference](https://test.repejo.se/docs/api-webhooks): the same reference, human-formatted.

## Analytics (GTM / GA4)

- [GTM dataLayer — Markdown](https://test.repejo.se/docs/gtm-datalayer.md): every dataLayer event the checkout pushes — GA4 funnel events, the server-built `purchase`, and the `repejo_click` element-interaction event with its click_classes/click_id vocabulary — in agent-friendly Markdown.
- [GTM dataLayer — docs page](https://test.repejo.se/docs/gtm-events): the same reference, human-formatted.

## Embeddable elements

- [Web Component docs](https://test.repejo.se/docs/web-component): every custom element Repejo ships, including `<repejo-donation-card>` — a live stream overlay for OBS/Twitch that pops a card per new donation (attributes `short-code`, `host`, `duration`, `locale`; three styling shortcuts `background-color`, `text-color` and `show-icon` (boolean; gift for one-time, heart for recurring), plus finer control via `--donation-card-background` / `-color` / `-font` / `-font-size` CSS custom properties) — `<repejo-donation-goal>`, a standalone fundraising-goal progress bar with per-sub-goal tick marks and the raised/percent row below the bar (attributes `short-code`, `host`, `locale`, optional `team-id` — a fundraising team's `ftm_…` id; the bar then tracks that team's raised + goal instead of the checkout aggregate, falls back to the checkout goal when the team has none of its own, hides the sub-goal ticks in team mode and does not apply the stretch-goal ladder (checkout-level concepts — wrong denominator), and silently shows the checkout aggregate for an id that matches no team; two styling shortcuts `primary-color` and `border-radius`, plus finer control via `--donation-goal-background` / `-color` / `-font` / `-font-size` / `-bar-color` / `-bar-background` / `-bar-height` / `-tick-color` / `-tick-width` / `-padding` / `-border-radius` CSS custom properties; no built-in heading — introduce it yourself) — `<repejo-leaderboard>`, a standalone live leaderboard with a `mode` picker of three flavours (`teams`, `onetime` (default), or `recurring`) that ranks by amount raised / one-time donation amount / monthly signup amount, with a `limit` attribute clamped 1..10 (default 5), two styling shortcuts `background-color` / `text-color`, and finer control via `--repejo-leaderboard-*` CSS custom properties — and two matching-donation widgets (`<repejo-matching-donation-card>` and `<repejo-matching-donation-row>`) that show an active sponsor-matching campaign — logo + company name + matched cap + progressbar — filling as new one-time donations land. Both accept `short-code`, `host`, `locale` plus three styling shortcuts `background-color`, `text-color`, `progress-color` (CSS custom properties `--repejo-matching-donation-background` / `-color` / `-progress-color` / `-border-radius` / `-font`); both render nothing when nothing is active. Only one matching can be active per checkout at a time; activate/deactivate from the checkout's Live tab in the back office. The matched amount also counts toward the fundraising goal: `goal_raised` (read by the checkout's own progress bar and `<repejo-donation-goal>`) moves by the gift plus the sponsor's match up to the cap, and keeps what deactivated matchings collected, while `total_raised` stays donor money only. Plus `<repejo-top-donation>` — a compact single-donation highlight card that shows the biggest one-time gift on the checkout (title + big amount + donor name). Reads `top_onetime_donations[0]` from the checkout state so it stays in sync with the leaderboard automatically; renders nothing when the checkout has no donations. Accepts `short-code`, `host`, `locale`, plus three styling shortcuts `background-color`, `text-color`, `accent-color` (the big amount) — CSS custom properties `--repejo-top-donation-background` / `-color` / `-accent-color` / `-border-radius` / `-font`. Plus `<repejo-donation-list>` — a rolling list of the three most recent donations (newest at the bottom, oldest sliding off the top with a CSS enter-animation as new ones arrive). Reads `latest_donations`; renders nothing until at least one donation exists. Same donor-name policy as `<repejo-donation-card>`. Accepts `short-code`, `host`, `locale`, `show-icon` (boolean; gift for one-time, heart for recurring), plus three styling shortcuts `background-color`, `text-color`, `accent-color` (icon + amount) — CSS custom properties `--repejo-donation-list-background` / `-color` / `-accent-color` / `-border-radius` / `-font`. Plus `<repejo-donation-ticker>` — a full-width news-ticker bar of recent donations that scrolls right-to-left continuously, with a dot separator between entries. Reads `latest_donations`; renders nothing until at least one donation exists. Edge-to-edge (`width: 100%`); the streamer places it wherever they want on the page. Hover to pause the strip; honors `prefers-reduced-motion` (freezes instead of animating). Accepts `short-code`, `host`, `locale`, `duration` (seconds per traversal, default 40, clamped 5+), plus three styling shortcuts `background-color`, `text-color`, `accent-color` (amount + dot) — CSS custom properties `--repejo-donation-ticker-background` / `-color` / `-accent-color` / `-font`. Plus `<repejo-live-products>` — a per-checkout mini-shop grid of preset gift products (name + amount + optional image + description + one-time-or-monthly period). Clicking a product opens `<repejo-checkout>` in a modal with `live-product-id` set, which pins a summary card of the picked product above the normal checkout body. Products are created per checkout via the Live tab's Produkter panel and never surface in the global /settings/products list. Accepts `short-code`, `host`, `locale`, plus three styling shortcuts `background-color`, `text-color`, `accent-color` (amount + CTA button) — CSS custom properties `--repejo-live-products-background` / `-color` / `-accent-color` / `-font`. `<repejo-checkout>` gained a new `live-product-id` attribute (additive; unset means the checkout renders unchanged). All widgets accept an optional `preview` boolean for a socket-free static demo; donation-card also accepts `preview-type` (`onetime`/`recurring`) and leaderboard accepts `preview-type` (`teams`/`onetime`/`recurring`) to preview any variant. TypeScript types for the elements: https://test.repejo.se/assets/repejo-checkout.d.ts
- `<repejo-progress-bar>` — a checkout's fundraising progress as a standalone element. Attributes: `short-code` (the checkout's short code, required), `host` (set it to https://test.repejo.se), optional `locale` (sv/en/de/fi, defaults to the checkout's own locale). It fetches the checkout's config, adopts its branding, and live-updates over a websocket as donations complete: a money checkout shows the collected amount against its goal (or the revealed stretch-goal ladder), a petition checkout shows the live signature count against its signature goal. Self-styling (shadow DOM + the checkout stylesheet) — override the fill colour with a CSS rule or inline style targeting the element itself (`repejo-progress-bar { --color-primary: ... }`); a value merely inherited from an ancestor is overridden by the checkout's own branding. Load https://test.repejo.se/assets/checkout.js on the page first.

## Docs

- [Documentation home](https://test.repejo.se/docs): all integration guides.