# Repejo Payment Sessions API

> Create a payment **server-side**, send the donor through Repejo's hosted
> checkout (redirect) or an embedded `<repejo-checkout>` element, and receive
> the outcome via webhooks. This is Repejo's "Pay by Link" capability.
> Donors complete the recurring mandate
> (e.g. Autogiro) with BankID on their own device.

- Machine-readable spec (OpenAPI 3.1, JSON): https://macbook-air-som-tillhr-daniel.tail570149.ts.net/api/v1/openapi
- Interactive API explorer (Swagger UI): https://macbook-air-som-tillhr-daniel.tail570149.ts.net/api/v1/swagger
- Human docs: https://macbook-air-som-tillhr-daniel.tail570149.ts.net/docs/api-payment-sessions

**For coding agents:** point your tool at the OpenAPI URL above — it is the
source of truth and contains every operation, schema, enum and error.

## How it works

1. **Create the session (server-side).** `POST /api/v1/payment_session` with
   your `Authorization: Bearer` token and the amount, currency, `checkout_id`,
   `payment_method` and optional `metadata`.
2. **Receive the session token.** The `201` response returns `session_token`,
   `payment_url` and `short_code`.
3. **Initialize the front end.** Embed
   `<repejo-checkout short_code="…" session-token="…" host="https://macbook-air-som-tillhr-daniel.tail570149.ts.net"></repejo-checkout>`
   on your page, or redirect the donor to `payment_url` (Repejo's hosted
   checkout).
4. **Repejo runs the payment steps.** Account information lookup (the donor's
   bank and account are fetched automatically), bank / payment-method handling
   (e.g. the Autogiro mandate) and BankID signing are all
   handled entirely inside Repejo.
5. **Receive the webhook.** Repejo sends `payment_session.succeeded` (also
   `.created` / `.cancelled`) to your endpoint with the payment details —
   amount, currency, payment method, payer — plus your `metadata`, so you can
   reconcile the donation.

## Prerequisites

Before you can create a payment session you must already have **both** of the
following. They are provided by the integrating organisation — you cannot
create them through this API:

1. An **organisation-scoped API token** (the `Authorization: Bearer` value).
2. A **`checkout_id`** (`chk_…`) of an **API-type** (`:api`) checkout in that
   same organisation. Payment sessions can only be created against `:api`
   checkouts; any other checkout type returns `422 checkout_not_api`.

If you are building the **embedded** flow (the `<repejo-checkout>` element),
you also need:

3. The checkout's **`short_code`** — a short, human-readable handle (e.g.
   `aunt123`) that is **not** the same value as the `checkout_id` (`chk_…`).
   The `short_code` is what the embed element takes as its `short_code`
   attribute. It is returned on every `POST /payment_session` response, but
   for a statically embedded element you typically hardcode it, so have the
   integrating organisation provide it up front. They can copy it from the
   checkout's *Användning* tab in the Repejo back office (shown next to the
   API-checkout-ID, which is the `checkout_id`). **If it is unclear which of
   the two values you have been given, ask** — `chk_…` is the `checkout_id`
   used in the API request body; the short code is the embed handle.

### One checkout per periodicity

An `:api` checkout is locked to a single payment period. To offer both
**one-time** and **monthly** donations, create **two separate checkouts** —
one per periodicity — each with its own `checkout_id` (`chk_…`), and pick the
one that matches the donation type when creating the session. A
`payment_method` whose periodicity doesn't match the checkout is rejected with
`422 payment_method_not_valid_for_period` (e.g. `swish_onetime` on a recurring
checkout, or `autogiro` on a one-time checkout).

### Choose an integration flow

There are **two ways** to bring the donor through the payment session, and they
drive a different front-end implementation (see [Integration modes](#integration-modes)):

- **Redirect** — send the donor's browser to `payment_url` (Repejo's hosted
  checkout) and reconcile via webhooks / `success_url`. If your organisation
  has a verified domain, `payment_url` is on that domain.
- **Embedded** — render the `<repejo-checkout>` element on your own page and
  listen for its DOM events.

Decide which flow you are building **before** you start. If the integrating
user hasn't made it clear which they want, **ask them** rather than guessing —
the choice changes the front-end code you write.

## Authentication

All requests use a Bearer **API token scoped to a single organisation**.
An organisation admin mints one in the Repejo back office under
*Settings → API-nycklar*; the secret is shown once.

```
Authorization: Bearer <api_token>
```

Missing/invalid token → `401`:

```json
{ "errors": { "detail": "Unauthorized" } }
```

## Quickstart

1. Mint an org-scoped API token (back office, once).
2. Create an `:api` ("API") type checkout in the back office; note its
   `checkout_id` (`chk_…`).
3. Create a payment session:

```bash
curl -X POST https://macbook-air-som-tillhr-daniel.tail570149.ts.net/api/v1/payment_session \
  -H "Authorization: Bearer <api_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "checkout_id": "chk_0TMXp8QPR6yGvKuV2GZQ10",
    "subscription": { "amount": 200, "currency": "SEK" },
    "payment_method": { "type": "autogiro" },
    "metadata": { "lead_id": "12345" },
    "payer": {
      "first_name": "Anna",
      "last_name": "Andersson",
      "phone_number": "+46701234567",
      "email": "anna@example.com"
    },
    "success_url": "https://example.org/success",
    "cancel_url": "https://example.org/cancel"
  }'
```

Response `201`:

```json
{
  "payment_url": "https://macbook-air-som-tillhr-daniel.tail570149.ts.net/s/aunt123?rp_token=abc123",
  "session_token": "abc123",
  "short_code": "aunt123"
}
```

4. Send the donor to the payment session — either **redirect** them to
   `payment_url`, or **embed** the checkout (see below).
5. Reconcile the outcome from the `payment_session.*` **webhooks**.

## Endpoint

`POST /api/v1/payment_session`

### Request body

| Field            | Type                | Required | Notes |
|------------------|---------------------|----------|-------|
| `request_type`   | enum                | no       | `subscription` (default) or `payment_method`. `subscription` sets up a subscription and the payment method that pays it. `payment_method` sets up an autogiro mandate **only** — no amount, no currency, no subscription — for a donor changing bank. Omit it and nothing changes for an existing integration. |
| `subscription`   | object              | cond.    | `{ amount, currency }`, both required inside the object. Required for a `subscription` request (`422 subscription_required` without it); must be absent on a `payment_method` request (`422 subscription_not_allowed`). Amount > 0 and at most `99999999.99`. The checkout's periodicity decides how it is charged: on a recurring checkout it is the per-period amount (e.g. monthly), confirmed by `payment_session.succeeded`; on a one-time checkout it is the single charge. Currency is one of `SEK`, `EUR`. |
| `amount`         | number              | no       | **Deprecated** — use `subscription.amount`. Still accepted and identical in meaning. Sending both forms returns `422 subscription_conflict`. |
| `currency`       | enum                | no       | **Deprecated** — use `subscription.currency`. |
| `checkout_id`    | string (`chk_…`)    | yes      | Must be a checkout of type `api`. Always include the `chk_` prefix; an unknown or malformed id returns `422 checkout_not_found`. |
| `payment_method` | object              | no       | `{ type }`, mirroring the `payment_method` object the webhooks return. Preselects and opens that method directly. `type` is one of `autogiro`, `swish`, `swish_onetime`, `card`, `apple_pay`, `google_pay`, `mobile_pay`, `sepa_direct_debit`. A bare string (`"autogiro"`) is **deprecated** but still accepted. On a `payment_method` request it is required (`422 payment_method_required`) and must be `autogiro` (`422 payment_method_not_valid_for_request_type`). Must be enabled on the checkout, and must match the checkout's periodicity. `apple_pay`/`google_pay` are gated by the checkout's wallet toggles at session creation; both wallets additionally require the presentation domain to be a verified Apple Pay domain (back office → Settings → Payment methods), otherwise the wallet is not offered when the payment page renders. For `swish` and `card` (recurring) the consent / setup-intent is created when the donor opens the checkout, so send the donor's `phone_number` (Swish) via `payer` if you have it. For `swish_onetime` the device-appropriate flow (QR on desktop, app prompt on mobile) opens once the donor's browser is detected. For `mobile_pay` the checkout opens with MobilePay selected, and MobilePay opens when the donor taps the button. Omit to let the donor choose. With `type: autogiro` on a `subscription` request, the optional `account_entry: "bank_account_selection"` opens Brite's bank account selection as soon as the checkout loads, instead of the Autogiro form. If the donor closes Brite or Brite fails, the donor sees the Autogiro form. Sent with another method or on a `payment_method` request it returns `422 account_entry_not_supported`. |
| `payer`          | object              | no       | `{ first_name, last_name, phone_number, email, address_street, address_zip, address_city, address_country }`. All optional, except `phone_number` is **required when `payment_method.type` is `swish`** (recurring): a Swish mandate binds to the donor's phone, so a session without it would strand the donor at the final "Fortsätt med Swish" step. Omitting it for `swish` returns `422 payer_phone_number_required`. Values are normalized (trimmed; email lower-cased; phone to E.164 without `+`), but an `email` or `phone_number` that is still invalid returns a 422 (`invalid_payer_email` / `invalid_payer_phone_number`) — validate donor input before calling. If you don't send donor details, link the donor via `metadata` (e.g. `metadata.lead_id`). Max lengths: `first_name` / `last_name` 500, `email` 254, `phone_number` 32, `address_*` 500. The address is printed on the mandate PDF. |
| `metadata`       | object<string,string>| no      | Echoed back on the `payment_session.*` webhooks (e.g. `lead_id`). Not copied to the payer or subscription, so `payer.*` and `subscription.*` webhooks do not carry it. Each value is at most 500 characters. |
| `merchant_reference` | string            | no       | Your own reference for the payment. When the donor pays through your organisation's Adyen account, Adyen gets it as the reference of the first payment and shows it as `merchantReference`; later monthly charges that Repejo makes carry Repejo's own reference. 1 to 80 characters after trimming, the limit Adyen sets; anything else returns `422 invalid_merchant_reference`. It need not be unique. Without it, Adyen shows `<organisation_id>.<user_session_id>`. Echoed on the `payment_session.*` webhooks. |
| `success_url`    | string (http/https) | yes      | Absolute URL the donor returns to on completion, in both the redirect and the embedded flow. An embedded page that wants to stay put sets it to its own address with a new `#fragment`. The page reloads unless everything before the `#` (path, query, trailing slash) matches the current address exactly, and after a donor returns from the BankID or Swish app the address carries extra `rp_*` parameters, so it reloads. Max 2048 characters. |
| `cancel_url`     | string (http/https) | yes      | Absolute URL the donor returns to on cancel (redirect flow only). The hosted page's back button becomes a cancel button that redirects here. The embedded back button never leaves your page: the element dispatches `repejo:cancelled` instead. Max 2048 characters. |

`success_url` and `cancel_url` must be absolute `http`/`https` URLs. Other
schemes (`javascript:`, `data:`), relative paths, empty strings, a missing
host, and whitespace anywhere in the host are rejected with a `400`.
Whitespace *after* the host is allowed, so an unencoded space in a query
string (`https://example.com/cb?q=a b`) is accepted.

String fields are length-bounded (see the table above, and `maxLength` in the
OpenAPI spec). A value over its limit returns a `400` whose `details` array
names the field, e.g. `{"location":["success_url"]}` or
`{"location":["payer","email"]}`.

### Response `201`

| Field           | Type   | Notes |
|-----------------|--------|-------|
| `payment_url`   | string | `{host}/s/{short_code}?rp_token={session_token}` — redirect the donor here. |
| `session_token` | string | The session handle; also used as the embed `session-token`. |
| `short_code`    | string | The checkout's short code; used as the embed `short_code`. |

### Errors

| Status | Body | When |
|--------|------|------|
| `400`  | validation error | Malformed body, `currency`/`payment_method` outside the enum, a string field over its maximum length, or a `success_url`/`cancel_url` that is not a well-formed absolute http(s) URL. The `details` array names the offending field (e.g. `{"location":["currency"]}`). |
| `401`  | `{"errors":{"detail":"Unauthorized"}}` | Missing/invalid token. |
| `422`  | `{"error":"checkout_not_found"}` | The `checkout_id` is unknown or malformed (e.g. missing the `chk_` prefix). |
| `422`  | `{"error":"checkout_not_api"}` | `checkout_id` is not an `api`-type checkout. |
| `422`  | `{"error":"payment_method_not_enabled"}` | The `payment_method` isn't enabled on that checkout. |
| `422`  | `{"error":"payment_method_not_valid_for_period"}` | The `payment_method`'s periodicity doesn't match the checkout (e.g. `swish_onetime` on a recurring checkout). |
| `422`  | `{"error":"currency_not_enabled"}` | The `currency` isn't one the checkout offers (e.g. `EUR` on a SEK-only checkout). |
| `422`  | `{"error":"amount_below_minimum"}` | On a **one-time** checkout, `amount` is zero or less, or below the checkout's minimum. |
| `422`  | `{"error":"invalid_subscription"}` | On a **recurring** checkout, the subscription failed validation — most often `amount` below the checkout's minimum. |
| `422`  | `{"error":"amount_above_maximum"}` | `amount` is above `99999999.99`. |
| `422`  | `{"error":"invalid_payer_email"}` | `payer.email` is not a valid email address (after trimming/lower-casing). |
| `422`  | `{"error":"invalid_merchant_reference"}` | `merchant_reference` is empty or longer than 80 characters after trimming. |
| `422`  | `{"error":"invalid_payer_phone_number"}` | `payer.phone_number` is not a valid mobile number. |
| `422`  | `{"error":"payer_phone_number_required"}` | `payment_method.type` is `swish` and `payer.phone_number` is missing or blank. A recurring Swish mandate needs the donor's phone as the Swish `payer_alias`; without it the donor would strand at "Fortsätt med Swish". Send `payer.phone_number`. |
| `422`  | `{"error":"invalid_payer"}` | Another `payer` field failed validation (e.g. a value over 500 characters). |
| `422`  | `{"error":"invalid_success_url"}` / `{"error":"invalid_cancel_url"}` | The URL is not an absolute `http`/`https` URL. Malformed URLs are normally caught earlier and answered with a `400`; these codes remain as a fallback. |

## Documents — mandate PDFs and BankID signature XML

A signed recurring mandate produces documents you can download with the same
Bearer token. Their urls are handed to you in the `documents` object of
`payment_session.finalized` and of every `subscription.*` webhook, so you never
build them by hand. The bytes are served through the API — there is no public
or redirect url.

| Endpoint | Serves | Content type |
|----------|--------|--------------|
| `GET /api/v1/subscriptions/:id/mandate_pdf_masked`   | Donor-facing copy of the mandate PDF; account number and personal identity number redacted. | `application/pdf` |
| `GET /api/v1/subscriptions/:id/mandate_pdf_unmasked` | The organisation's copy with full details. | `application/pdf` |
| `GET /api/v1/mandates/:id/mandate_pdf_masked`       | The donor-facing copy for a mandate signed without a subscription (`request_type: "payment_method"`), without amount, periodicity and debit date. | `application/pdf` |
| `GET /api/v1/mandates/:id/mandate_pdf_unmasked`     | The organisation's copy of that PDF. | `application/pdf` |
| `GET /api/v1/mandates/:id/signature_xml`             | The BankID signature envelope of an Autogiro mandate. `:id` is the `payment_method.id` (`aum_…`). | `application/xml` |

PDFs are owned by the subscription (one mandate can back several
subscriptions, each with its own PDF), except for a mandate signed without a
subscription, which owns its PDF; the XML is owned by the mandate.

`documents` on a webhook:

```json
"documents": {
  "mandate_pdf_masked_url": "https://macbook-air-som-tillhr-daniel.tail570149.ts.net/api/v1/subscriptions/sub_…/mandate_pdf_masked",
  "mandate_pdf_unmasked_url": "https://macbook-air-som-tillhr-daniel.tail570149.ts.net/api/v1/subscriptions/sub_…/mandate_pdf_unmasked",
  "signature_xml_url": "https://macbook-air-som-tillhr-daniel.tail570149.ts.net/api/v1/mandates/aum_…/signature_xml"
}
```

A url is `null` when the document does not exist at the time of the event:

- `mandate_pdf_*_url` appear once the mandate PDF has been rendered. That
  happens right after signing for `autogiro` and `sepa_direct_debit`
  mandates on a checkout that enables the mandate language (Swedish resp.
  German), and never for other payment methods. A subscription created
  outside a checkout gets its PDF urls on the first `subscription.updated`
  after the PDFs have been produced.
- `signature_xml_url` exists only for mandates signed with BankID — not for
  paper, imported or hand-drawn mandates, and never for SEPA.

Every endpoint answers `404 {"error":"not_found"}` whenever the document is
not available — unknown id, an id belonging to another organisation, or a
document that does not exist for that record — and `401` without a valid
token. Wait for `payment_session.finalized` before fetching: it is sent after
the PDFs have been rendered, so a url it carries is ready to download.

## Integration modes

### Redirect

Redirect the donor's browser to `payment_url`. Repejo's hosted checkout skips
the amount screen and opens the (optionally preselected) payment method. On
completion Repejo redirects to your `success_url`; the back button cancels and
redirects to your `cancel_url`.

### Embedded

Render the custom element on your own page (load `https://macbook-air-som-tillhr-daniel.tail570149.ts.net/assets/checkout.js`
once). Pass the `short_code` and `session_token` from the response:

```html
<script defer src="https://macbook-air-som-tillhr-daniel.tail570149.ts.net/assets/checkout.js" data-host="https://macbook-air-som-tillhr-daniel.tail570149.ts.net"></script>

<repejo-checkout short_code="aunt123" session-token="abc123" host="https://macbook-air-som-tillhr-daniel.tail570149.ts.net"></repejo-checkout>
```

The `host` attribute (and the script tag's `data-host`) **must point at the
Repejo environment you are integrating against** — `https://test.repejo.se`
for testing/staging, or `https://app.repejo.se` for production. It must match
the environment where the API token and `checkout_id` were created and where
you called `POST /payment_session`; pointing the element at a different host
than the one that issued the session will not find the session. The examples
above use `https://macbook-air-som-tillhr-daniel.tail570149.ts.net`, the environment that served this document.

The element's attributes are `short_code` (the kebab-case `short-code` is also
accepted), `session-token` and `host`. To create it in JavaScript, set them as
attributes **or** properties — either before or after `appendChild` works; the
element fetches the checkout once `short_code` is set:

```js
const el = document.createElement("repejo-checkout");
el.host = "https://macbook-air-som-tillhr-daniel.tail570149.ts.net";
el.short_code = "aunt123";       // property (or el.setAttribute("short_code", "aunt123"))
el.session_token = "abc123";     // property (attribute: session-token)
document.querySelector("#checkout").appendChild(el);
```

**Team competitions are not available on payment sessions.** The `team`
attribute assigns a donation to a fundraising team (`ftm_…`), but it only
applies to a checkout the element opens itself — the hosted page equivalent is
`?rp_team=ftm_…`. A payment session is created server-side and reused via
`session-token`, so `team` is ignored in that mode, and
`POST /payment_session` has no field for a team. Use the plain
`<repejo-checkout short_code=... team=...>` integration for team competitions.
Team attribution is also not included in webhook payloads.

**Styling.** The checkout renders in a card with its own background, border and
shadow; on a coloured page this can look like a card-in-card. For a fully
seamless embed, add the **`bare`** attribute — the card chrome (background,
border, shadow, fixed width) and the footer (Repejo logo, back button, trust
logos) are removed entirely, leaving only the payment screen on your page's
own background. `bare` is only honored on API checkouts (payment sessions);
other checkout types ignore it. Note that bare mode also removes the
in-checkout back/cancel navigation. Alternatively, set the checkout's
background/border/shadow in its **branding** (back office) to match your
page (or transparent). These are **not** overridable from host-page CSS
variables — branding writes them directly onto the component, so a page-level
`--color-checkout-background` has no effect. Only the typographic variables
(`--font-sans`, `--font-weight-*`, …) are host-overridable.

**TypeScript / React.** Type declarations — including an `HTMLElementTagNameMap`
entry and a JSX augmentation for `<repejo-checkout>` — are published at
`https://macbook-air-som-tillhr-daniel.tail570149.ts.net/assets/repejo-checkout.d.ts`. Copy the file into your project (or
reference it); no `@types` package is required.

The element connects to Repejo cross-origin and skips the amount screen. It
dispatches DOM events you can listen for, then follows `success_url` on completion. The events **bubble
from the `<repejo-checkout>` element up to `window`**, so you may listen on
either. Both recurring (mandate signed) and one-time (payment captured)
completions fire `repejo:completed`; `event.detail.type` is `"recurring"` or
`"onetime"`.

```js
window.addEventListener("repejo:completed", (e) => { /* e.detail.type → show your thank-you */ });
window.addEventListener("repejo:cancelled", (e) => { /* donor cancelled */ });
```

`repejo:ready` fires once, when the first screen has rendered. Use it to
scroll the donor to the checkout:

```js
el.addEventListener("repejo:ready", () => el.scrollIntoView({ behavior: "smooth" }));
```

The element also emits informational events you can ignore:
`repejo:first-interaction` (donor started) and `repejo:registered` (left the
amount step). `repejo:ready`, `repejo:completed` and `repejo:cancelled` are part of the
contract.

Treat the `payment_session.succeeded` webhook as the authoritative signal;
the DOM events are a UX convenience.

## Webhooks

Outcomes are delivered as webhooks to the tenant webhook endpoints you
register in the back office (subscribe them to the `payment_session.*`
events). Delivery is asynchronous, signed and retried.

Events:

```
payment_session.created     // session created (donor not yet finished)
payment_session.succeeded   // recurring mandate signed OR one-time payment captured — mark the lead done
payment_session.finalized   // post-processing done — mandate documents available (data.documents)
payment_session.cancelled   // donor cancelled
```

`payment_session.succeeded` is the single reconciliation signal for **both**
periodicities: a recurring checkout fires it when the mandate is signed, a
one-time checkout (Swish / card) when the single payment is captured. You do
**not** need to consume `transaction.*` to confirm a one-time gift.

Every delivery has this envelope; `data.metadata` carries your `lead_id`.
`data.metadata` also lists every defined custom attribute — attributes with no
value are delivered as an empty string `""`, not omitted.
`payment_session.succeeded` also embeds the resulting `subscription`, the
signed `payment_method` object and the `payer`, so you can reconcile the
donor without a follow-up call:

```json
{
  "sent_at": "2026-06-13T12:00:00Z",
  "event_type": "payment_session.succeeded",
  "data": {
    "id": "pls_8x…",
    "checkout_id": "chk_0TMXp8QPR6yGvKuV2GZQ10",
    "user_session_id": "uss_4kRb7mQ2wTnZxL9pVdHgA3",
    "status": "succeeded",
    "request_type": "subscription",
    "amount": "200",
    "currency": "SEK",
    "payment_method_type": "autogiro",
    "payment_channel": "autogiro",
    "collected_by": "repejo",
    "metadata": { "lead_id": "12345" },
    "merchant_reference": null,
    "inserted_at": "2026-06-13T11:59:00Z",
    "updated_at": "2026-06-13T12:00:00Z",
    "subscription": {
      "id": "sub_9y…",
      "amount": "200",
      "status": "active",
      "reference": "Monthly gift",
      "recruiter_external_id": null,
      "recruiter_first_name": null,
      "recruiter_last_name": null
    },
    "payment_method": {
      "id": "aum_1a…",
      "type": "autogiro",
      "clearing_number": "8393",
      "account_number": "41231614",
      "bank": "Swedbank"
    },
    "payer": {
      "id": "pay_2b…",
      "name": "Anna Andersson",
      "email": "anna@example.com",
      "status": "active"
    }
  }
}
```

The scalar preselect `payment_method` string is replaced by the embedded
object plus `payment_channel` and `collected_by`. `payment_channel` is the
payment method the donor chose, never the provider that processed it: `autogiro`,
`swish`, `card`, `apple_pay`, `google_pay`, `mobile_pay` or `sepa_direct_debit`.
`collected_by` says who charges the later payments: `repejo` (Repejo sends
the payment orders or charges the stored card) or `organisation` (the
organisation's own setup charges, and Repejo starts no charge). The deprecated `payment_method_type` is still sent unchanged;
it ends in `_external` when the organisation collects. Read `payment_channel`
and `collected_by` instead. This mirrors the `subscription.*` webhook shape.
For a **one-time** session there is no subscription, so `subscription`,
`payment_method`, `payment_channel`, `collected_by` and `payment_method_type`
are `null`; the `payer` is always present. See the
Webhooks reference for the full `subscription` / `payment_method` / `payer`
field lists: https://macbook-air-som-tillhr-daniel.tail570149.ts.net/docs/api-webhooks.md

`data.request_type` echoes what you asked for, on all four events.

### `request_type: "payment_method"` — mandate without an amount

For a donor who already gives and is only changing bank, create the session
with `request_type: "payment_method"` and `payment_method: { "type":
"autogiro" }`, and send no amount or currency. The donor picks their bank
and signs with BankID exactly as before.

The webhook then carries the `payment_method` and the `payer`, and
`subscription` is `null` — there is none. `amount` and `currency` are `null`
too:

```json
{
  "sent_at": "2026-06-13T12:00:00Z",
  "event_type": "payment_session.succeeded",
  "data": {
    "id": "pls_8x…",
    "checkout_id": "chk_0TMXp8QPR6yGvKuV2GZQ10",
    "user_session_id": "uss_4kRb7mQ2wTnZxL9pVdHgA3",
    "status": "succeeded",
    "request_type": "payment_method",
    "amount": null,
    "currency": null,
    "subscription": null,
    "payment_method_type": "autogiro",
    "payment_channel": "autogiro",
    "collected_by": "repejo",
    "payment_method": {
      "id": "aum_1a…",
      "type": "autogiro",
      "clearing_number": "8393",
      "account_number": "41231614",
      "bank": "Swedbank"
    },
    "payer": { "id": "pay_2b…", "name": "Anna Andersson" },
    "metadata": { "lead_id": "12345" },
    "merchant_reference": null
  }
}
```

On `payment_session.finalized` the `documents` object carries the BankID
`signature_xml_url` and both `mandate_pdf_*_url`, which point at
`/api/v1/mandates/:id/mandate_pdf_masked` and `…_unmasked`. This mandate PDF
has no amount, periodicity or debit date. The PDF urls are `null` when the
checkout does not enable Swedish.

The mandate is **not** attached to any subscription the donor already has.
Repejo transmits it to Bankgirot and reports it to you; connecting it to an
existing recurring gift is your side of the integration for now.

Only `autogiro` is supported. The checkout must be a recurring `api`
checkout.

`payment_session.created` and `payment_session.cancelled` carry the lean
envelope without the embeds (they fire before a mandate exists): same fields
minus `subscription` / `payment_method` (object) / `payment_channel` /
`collected_by` / `payment_method_type`, and
they keep the scalar `payment_method` preselect string and `request_type`, with `event_type` /
`data.status` = `created` / `cancelled`. `amount` is delivered as a **string**
(`"200"`), not a number.

`payment_session.finalized` is sent once per succeeded session after
post-processing (mandate PDF rendering) has finished — for a one-time
payment straight after `succeeded` — whether or not any document exists. It has exactly the `succeeded` shape plus a `documents`
object (see **Documents** above for the endpoints and when a url is `null`):

```json
{
  "sent_at": "2026-06-13T12:00:30Z",
  "event_type": "payment_session.finalized",
  "data": {
    "id": "pls_8x…",
    "status": "succeeded",
    "metadata": { "lead_id": "12345" },
    "subscription": { "id": "sub_9y…", "…": "…" },
    "payment_method": { "id": "aum_1a…", "type": "autogiro", "…": "…" },
    "payer": { "id": "pay_2b…", "…": "…" },
    "documents": {
      "mandate_pdf_masked_url": "https://macbook-air-som-tillhr-daniel.tail570149.ts.net/api/v1/subscriptions/sub_9y…/mandate_pdf_masked",
      "mandate_pdf_unmasked_url": "https://macbook-air-som-tillhr-daniel.tail570149.ts.net/api/v1/subscriptions/sub_9y…/mandate_pdf_unmasked",
      "signature_xml_url": "https://macbook-air-som-tillhr-daniel.tail570149.ts.net/api/v1/mandates/aum_1a…/signature_xml"
    }
  }
}
```

A completed recurring mandate also emits a `subscription.created` event (from
the general webhooks family, `data.id = sub_…`). Both families fire; treat
`payment_session.succeeded` as authoritative for reconciling a Payment Session
because it carries your `metadata`, and `payment_session.finalized` as the
signal that its documents can be fetched. See the Webhooks reference for the
`subscription.*` payload and PII/security notes: https://macbook-air-som-tillhr-daniel.tail570149.ts.net/docs/api-webhooks.md

### Verifying & handling deliveries

- Each POST is signed: `Repejo-Signature: sha256=<hex>` is HMAC-SHA256 over
  the **raw** body using the endpoint's secret. Compare against the raw body,
  not re-serialized JSON.
- Headers also include `X-Repejo-Event-ID` (dedupe retries),
  `X-Repejo-Event-Type` and `X-Repejo-Attempt`.
- Return `2xx` once accepted. Non-2xx is retried with exponential backoff.
- Treat handlers as idempotent (use `X-Repejo-Event-ID` / `data.id`).

See the general Webhooks reference for the full signing/retry contract:
https://macbook-air-som-tillhr-daniel.tail570149.ts.net/docs/api-webhooks
