# 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">`. The site's own buttons, links and menu
  items open the checkout modal with `href="?rp_modal=<short_code>"` or
  `data-repejo-checkout="<short_code>"`, optionally with the amount and the
  reference preselected (`data-repejo-amount`, `data-repejo-reference`).
  Reference: https://app.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://app.repejo.se/docs/api-payment-sessions.md

The embedded element **cannot take an amount** (no attribute, no query
parameter). The site's own button can open the checkout modal with an amount
preselected (`data-repejo-amount`), but the donor still sees Repejo's amount
screen and can change it; skipping that screen always means Payment Sessions.
Both can live on the same site.

## Embedded checkout (no backend)

- [Embedded checkout — Markdown](https://app.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 gift shop (Gåvoshop) elements `<repejo-physical-product-list>` (product grid with its own cart drawer) and `<repejo-physical-product-cart-button>` (`position`), the site's own buttons and links opening the modal (`?rp_modal=<short_code>` links, `data-repejo-checkout` with `data-repejo-amount` / `data-repejo-reference` preselection), the hosted campaign page `{host}/s/{short_code}` (built in the back office under the checkout's Campaign page (Kampanjsida) tab), 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://app.repejo.se/docs/website-implementation): the same guide, human-formatted.

## API

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

## Payment Sessions (Pay by Link)

- [Payment Sessions — Markdown](https://app.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://app.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/mandate_pdf_masked` and `GET /api/v1/mandates/:id/mandate_pdf_unmasked` for a mandate signed without a subscription, `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://app.repejo.se/docs/api-payment-sessions): the same reference, human-formatted.

## Webhooks

- [Webhooks — Markdown](https://app.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://app.repejo.se/docs/api-webhooks): the same reference, human-formatted.

## Analytics (GTM / GA4)

- [GTM dataLayer — Markdown](https://app.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://app.repejo.se/docs/gtm-events): the same reference, human-formatted.

## Embeddable elements

- [Web Component docs](https://app.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`. Both `<repejo-donation-list>` and `<repejo-donation-ticker>` accept `feed-text-onetime` / `feed-text-recurring`, the organisation's own row text per donation type, filled with `{{payer_name}}`, `{{amount}}` and, for a greeting gift (Hälsningsgåva), `{{recipient_name}}` (first name), `{{greeting_message}}` (the greeting the donor wrote) and `{{dedication_name}}` (who the gift is dedicated to, e.g. in memory of); a row whose gift has no value for a placeholder it uses falls back to the standard text. Each `latest_donations` entry carries those values as `recipient_name`, `greeting_message` and `dedication_name`, all `null` unless the checkout publishes donor names — the same gate as `donor_name`. 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://app.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://app.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) when placed directly on a page; the bar colour, label colour and corner radius come from the checkout's branding (Utseende → Insamlingsmål). 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://app.repejo.se/assets/checkout.js on the page first.
- `<repejo-counter>` — the checkout's räknare as a standalone element: a number that counts up live for every gift (paid one-time gifts and activated monthly donations; signatures on a petition checkout) plus the checkout's start value, between an optional text before and after. It needs no fundraising goal and never counts down. Attributes: `short-code` (required), `host` (set it to https://app.repejo.se), optional `locale` (number format and which language of the checkout's texts to show), `start-value` (replaces the checkout's start value), `text-before`, `text-after`; whole box `background-color`, `border-radius` (whole pixels 0–99); the number `number-size` (pixels 12–200, shrinks to fit narrow containers), `number-color`, `number-background-color`, `number-border-radius`; the text `text-size` (pixels 8–100), `text-color`. Colours are hex codes or CSS colour names. Without styling attributes it uses the checkout's own räknare settings (Utseende → Räknare); each attribute overrides one setting. Animates up on load and on each new gift; instant with `prefers-reduced-motion`. Load https://app.repejo.se/assets/checkout.js on the page first.

## Docs

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