Overview

This is the end-to-end path for connecting one of your clients to OpenCard. Everything you need lives in the Application API — no embed plugin required. The guides below this page go deeper on TPA signing, eID, and card holders.

Who does what

Actor	Role
Client	Your end-customer company — signs the TPA; their employees sign PDPC
You (EMS)	Orchestrate setup in your product — call OpenCard APIs, store `reference_id`s, show status in your UI
OpenCard	Legal signing (eID), card issuer communication, webhooks with transactions and enrichment

You own the UX. OpenCard owns signing pages, identity verification, and data delivery.

Big picture

Phase 1 — Client setup

This is what the client walks through in your product (same order as the optional ocTPA plugin). You collect choices in the UI, then create the OpenCard resources.

1. Choose card program

GET /accounts/{accountId}/cardissuers

Show only issuers already enabled on your account. The client picks one → you store card_issuer_id for the TPA. Enabling new issuers on the account is one-time platform setup — not part of this per-client wizard. → Quickstart

2. Choose products

What OpenCard should deliver for this client. Stored as flags on the billing profile when you create it:

Field	Meaning	Typical UX
`product_transaction`	Real-time transaction states to your webhooks	Usually always on
`product_digital_receipt`	Digital receipts from the merchant network	Optional toggle
`product_aland_index`	Environmental impact estimates	Optional toggle

Transactions are the core product. Receipts and environmental impact are enriched add-ons — same split the plugin uses (“Transaction information” vs “Enriched information”). → Billing · Receipts · Environmental impact

3. Invoice details (for your OpenCard bill)

Collect how you (the EMS) want this client represented on the invoice OpenCard sends you:

Invoice email (email_invoice)
Your reference (your_reference_invoice)
Legal name / org number / address (often from public records)

Organizations that share the same billing profile appear as one line on that invoice — not as separate invoices per organization. This is not the bank’s card invoice to the client. → Billing

4. Create the TPA (company authorisation)

A TPA (Transaction Processing Authorisation) is the legal agreement that this company allows card transaction data from the chosen card program to flow through OpenCard to your EMS. Look up who is allowed to sign:

GET /accounts/{accountId}/publicrecords?country=SE&organization_number=...

Use signature_combinations when present so the client picks a valid signing group. Collect name + email for each person who will sign (or allow manual entry when the registry has no combinations). You create the TPA and signatories in the next step. Full walkthrough → TPA flow · eID signing

5. Configure the client

When the client confirms steps 1–4, create the OpenCard resources (same payload shape the ocTPA plugin returns in onDataSend):

POST /accounts/{accountId}/billings                         ← invoice line + product flags
POST /accounts/{accountId}/tpas                            ← company + card_issuer_id
POST /accounts/{accountId}/tpas/{tpaId}/signatories        ← emails → eID signing links
POST /accounts/{accountId}/organizations                   ← runtime container
POST /accounts/{accountId}/organizations/{id}/webhooks     ← event delivery

OpenCard emails each TPA signatory. They sign with national eID. You wait for status — do not build your own signing UI.

Event / signal	Meaning
Signatory signs	Progress toward fully signed
`tpa.signed` webhook	All required signatures done — PDF ready
Status → `activated`	TPA confirmed — transactions can flow

Organization body — link the TPA and billing you created. reference_id is your internal client ID (returned on every webhook):

{
  "reference_id": "client_acme_001",
  "tpa_id": 42,
  "billing_id": 1,
  "name": "Acme AB"
}

Complete the webhook challenge handshake so active=true and events can be delivered. → Billing · Organization · Webhook setup · TPA flow Client setup is complete when the TPA is signed (ideally activated), the organization exists with billing_id + tpa_id, and the webhook is active.

Phase 2 — Cardholder setup

Goal: each person whose card spend you want is identified in OpenCard.

POST /accounts/{accountId}/organizations/{organizationId}/cardholders

Path	You send	User action	Transactions start
🅰️ Email	`email`	Signs PDPC with eID	After `card_holder.identified`
🅱️ Instant	`identity_id`	None	Immediately

OpenCard handles PDPC email + eID. You handle status in your UI (card_holder.identified, card_holder.signed.pdpc). → Card holder onboarding · Model: Card holder · eID signing Cardholder is onboarded when you receive card_holder.identified — then expect transactions (including a retroactive batch).

Phase 3 — Live

Once card holders are identified and the TPA is activated:

Card issuer pushes transaction states to OpenCard
OpenCard POSTs to your organization webhook (card.transaction.*)
Enrichment may follow: receipt.fetched, true VAT, line items, environmental impact

→ Transaction states · Events · Receipts

Ordered checklist

Do this per client (after your account + OAuth client exist):

#	Step	API / action	Detail guide
0	Enable card issuer(s) on account (once)	`GET /cardissuers` → `POST .../accounts/{id}/cardissuers/{id}`	Quickstart
1	Client picks card program	`GET .../accounts/{id}/cardissuers`	below
2	Client picks products	Flags on billing create	Billing
3	Invoice email / reference	Part of billing create	Billing
4	Create TPA (who signs)	`GET` publicrecords — collect signatories	TPA flow
5	Configure client	`POST` billings, tpas, signatories, orgs, webhooks	Billing · Webhooks
6	Wait for eID + `tpa.signed`	Webhook / status	eID signing
7	Create card holders	`POST` cardholders	Card holders
8	Wait for `card_holder.identified`	Webhook	Card holders
9	Handle transactions + enrichment	Webhooks	Transactions

Build it yourself vs embed plugin

Approach	When
API only (this guide)	Rebuild the same steps in your own UI — recommended for production
ocTPA plugin	Ready-made wizard: issuer → products → invoice → signatories; you still POST billing / TPA / signatories from `onDataSend`

The plugin mirrors steps 1–4 in the UI and gives you billing / TPA / signatory data in onDataSend. Step 5 (organization + webhook) and card holders stay in your integration.

Deep dives in this section

Page	What it covers
TPA flow	Create TPA, signatories, activation, signed PDF
eID signing	Sign vs auth modes across Nordic countries
Card holder onboarding	Email vs `identity_id`, webhooks, updates

Models (what each entity is): Billing · Organization · TPA · Card holder

Model

Platform

Customer onboarding

Webhooks

Enrichment

Advanced

API — Auth

API — Endpoints

Who does what

Big picture

Phase 1 — Client setup

1. Choose card program

2. Choose products

3. Invoice details (for your OpenCard bill)

4. Create the TPA (company authorisation)

5. Configure the client

Phase 2 — Cardholder setup

Phase 3 — Live

Ordered checklist

Build it yourself vs embed plugin

Deep dives in this section

​Who does what

​Big picture

​Phase 1 — Client setup

​1. Choose card program

​2. Choose products

​3. Invoice details (for your OpenCard bill)

​4. Create the TPA (company authorisation)

​5. Configure the client

​Phase 2 — Cardholder setup

​Phase 3 — Live

​Ordered checklist

​Build it yourself vs embed plugin

​Deep dives in this section

Who does what

Big picture

Phase 1 — Client setup

1. Choose card program

2. Choose products

3. Invoice details (for your OpenCard bill)

4. Create the TPA (company authorisation)

5. Configure the client

Phase 2 — Cardholder setup

Phase 3 — Live

Ordered checklist

Build it yourself vs embed plugin

Deep dives in this section