How OpenCard works

The hierarchy (memorize this)

Account          ← you (the EMS partner)
├── Billing      ← invoice recipient; orgs with same billing_id = one line on YOUR OpenCard invoice
└── Organization ← your end-client company
    ├── billing_id → which billing profile (invoice line roll-up) this org belongs to
    ├── Webhook    ← where events get POSTed
    ├── CardHolder ← employee whose card data you want
    │   └── Card ← actual credit card (managed by issuer)
    │       └── Transaction
    │           └── TransactionState (authorized → cleared → invoiced)
    └── TPA        ← legal agreement (signed by client's authorized signatories)

Account = your OpenCard partner account. One per EMS. Billing = invoice recipient for your OpenCard bill. Organizations that share a billing_id are rolled up as one line on that invoice (not separate invoices per org). Example: three orgs with billing_id: 1 → one combined line to your finance team. → Billing Organization = one of your customers. You set reference_id to your internal client ID. Most EMSs map 1:1 (one org per client), but you can split one client into multiple orgs if you need different webhook configs or card type filters. → Organization Card Holder = a person. You set reference_id to your internal user ID. Two ways to onboard: email (user signs with eID) or identity_id (instant, person already in OpenCard). → Card holder · Onboarding TPA (Transaction Processing Authorization) = legal doc the client’s signatories sign saying “yes, our card data can flow to this EMS via OpenCard.” → TPA PDPC (Personal Data Processing Consent) = GDPR consent the individual cardholder signs saying “yes, my transactions can be shared.”

Two legal docs, two audiences

Doc	Who signs	How	Purpose
TPA	Company’s authorized signatories (CEO, board, etc.)	eID sign mode — they sign the actual legal document	Company-level permission
PDPC	Individual cardholder (employee)	eID auth mode — identity verification + consent checkbox	Person-level GDPR consent

OpenCard handles all of this. For new users you provide an email — we send the link, they sign with eID. For users already in OpenCard you pass identity_id and skip the wait entirely.

The full onboarding sequence

Step-by-step for EMS integrators (APIs, phases, checklist) → Customer onboarding

Runtime: what happens on a purchase

Cardholder buys coffee ☕
Issuer sends authorized transaction state to OpenCard
OpenCard normalizes the data, checks org/webhook config
Your webhook gets card.transaction.authorized within seconds
If merchant is receipt-enabled → OpenCard requests receipt match
3–5 days later issuer sends cleared state
Your webhook gets card.transaction.cleared — this is the accounting truth
Maybe receipt.fetched, transaction.true.vat, transaction.line_items follow

What you build vs what OpenCard builds

You build	OpenCard builds
Webhook endpoint + event handlers	Legal signing flows (TPA + PDPC)
Org/cardholder CRUD in your UI	eID signing flows
Map `reference_id` to your DB	Issuer communication
Transaction UI in your expense app	Receipt matching orchestration
	Webhook delivery + retry + logs

Reference IDs — your best friend

Every organization and card holder has a reference_id you define. Put your internal ID there. Every webhook payload includes it. Zero lookup tables needed.

{
  "card_holder": { "reference_id": "user_48291" },
  "organization": { "reference_id": "client_acme_corp" }
}

Map straight to your DB. Done. 🎯

Client already has another transaction feed?

Common during rollout. Your client enables OpenCard with the issuer — they do not have to disable an existing connection first, and you are not responsible for that. If they want one feed only, the client coordinates with the issuer. OpenCard sends authorized events (many other integrations do not) and replays history on card_holder.identified. Deduplicate cleared events with card_issuer_reference when merging with your existing store. → Current card issuer integration

Overview

First integration

How OpenCard works

The hierarchy (memorize this)

Two legal docs, two audiences

The full onboarding sequence

Runtime: what happens on a purchase

What you build vs what OpenCard builds

Reference IDs — your best friend

Client already has another transaction feed?

​The hierarchy (memorize this)

​Two legal docs, two audiences

​The full onboarding sequence

​Runtime: what happens on a purchase

​What you build vs what OpenCard builds

​Reference IDs — your best friend

​Client already has another transaction feed?

The hierarchy (memorize this)

Two legal docs, two audiences

The full onboarding sequence

Runtime: what happens on a purchase

What you build vs what OpenCard builds

Reference IDs — your best friend

Client already has another transaction feed?