Quickstart — Zero to First Webhook

This is the full path for one test client, in the order the API expects it:

account → payment product → billing → TPA + signatories → organization → webhook → tpa.signed → card holder → transaction

Every step produces an id that the next step needs. Don’t skip ahead — the two most common integration failures are an organization without billing_id and card holders created before the webhook exists. Both are avoided by simply following the order below. Grab coffee. ☕ Let’s go.

Step 0: Register (sandbox)

👉 sandbox-api.opencard.io/register You get an Account + admin user. Verify email. Log in. Your accountId is in the dashboard URL or API responses.

Step 1: Create an account_client and get a token

# Dashboard: Account → OAuth Clients → Create
# This is an account_client — machine-to-machine credential for your EMS integration.

curl -X POST https://sandbox-api.opencard.io/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=billings-write account-tpas-write account-tpas-read account-tpa-signatories-write organizations-write organizations-read card-holders-write webhooks-write webhooks-read public-records-read payment-products-read account-payment-products-read account-payment-products-write"

Save the access_token. All subsequent calls:

Authorization: Bearer {access_token}
Accept: application/json

Scopes are space-separated. Request only what you need. Full list in Authentication. Always send Accept: application/json so error responses stay JSON (not an HTML login page).

Verify: GET /api/v1/application/payment-products returns 200. Auth works.

Step 2: Enable a payment product (once per account)

# List available payment products
curl https://sandbox-api.opencard.io/api/v1/application/payment-products \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

# Enable one on your account (use the id from above)
curl -X POST https://sandbox-api.opencard.io/api/v1/application/accounts/$ACCOUNT_ID/payment-products/1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Save payment_product_id. You need it for the TPA in step 4. → Payment product setup

Step 3: Create a billing profile 🧾

The billing profile is the client’s invoice profile and the switch that turns on products. The product_* flags decide which webhook events the client is allowed to subscribe to — so this must exist before the organization and the webhook.

curl -X POST https://sandbox-api.opencard.io/api/v1/application/accounts/$ACCOUNT_ID/billings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name_display": "Acme AB",
    "name_legal": "Acme AB",
    "organization_number": "5561234567",
    "country": "SE",
    "email_invoice": "finance@acme.se",
    "your_reference_invoice": "PO-12345",
    "product_transaction": true,
    "product_digital_receipt": false,
    "product_aland_index": false
  }'

Response → save id as billing_id.

product_transaction: true is what allows card_transaction_* events on the webhook later. Creating a webhook with transaction events for an organization whose billing lacks this flag (or that has no billing_id at all) fails.

→ Model: Billing

Step 4: Create the TPA 📜

TPA = Transaction Processing Authorisation. Legal permission for the client’s transaction data to flow. First, check who may sign for the company (optional, but saves a round-trip with the client):

curl "https://sandbox-api.opencard.io/api/v1/application/accounts/$ACCOUNT_ID/publicrecords?country=SE&organization_number=5561234567" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Response includes signature_combinations — the people you’ll add as signatories in step 5. Then create the TPA:

curl -X POST https://sandbox-api.opencard.io/api/v1/application/accounts/$ACCOUNT_ID/tpas \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "payment_product_id": 1,
    "name": "Acme AB",
    "country": "SE",
    "organization_number": "5561234567",
    "language": "sv"
  }'

Org number formats:

Country	Format	Example
🇸🇪 SE	10 digits	`5561234567`
🇳🇴 NO	9 digits	`123456789`
🇩🇰 DK	8 digits	`12345678`
🇫🇮 FI	`XXXXXXX-X`	`1234567-8`

Response → save id as tpa_id. → TPA flow

Step 5: Add signatories → email goes out 📧

curl -X POST https://sandbox-api.opencard.io/api/v1/application/accounts/$ACCOUNT_ID/tpas/$TPA_ID/signatories \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "ceo@acme.se",
    "name": "Anna Andersson"
  }'

The email is queued immediately with a signing link. Repeat for each signatory required by signature_combinations.

Signatories can only be updated/deleted while signed=false. Once signed, they’re locked.

Don’t wait for the signature here — continue with steps 6 and 7 right away so the webhook is in place when tpa.signed fires.

Step 6: Create the organization 🏢

The organization is the runtime container for the client. It links the TPA (legal) and the billing (products) together.

curl -X POST https://sandbox-api.opencard.io/api/v1/application/accounts/$ACCOUNT_ID/organizations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "reference_id": "client_acme_001",
    "tpa_id": '"$TPA_ID"',
    "billing_id": '"$BILLING_ID"',
    "name": "Acme AB"
  }'

reference_id = your internal client ID. It comes back in every webhook. Response → save id as organization_id. → Model: Organization

Step 7: Create the webhook 🔔

curl -X POST https://sandbox-api.opencard.io/api/v1/application/accounts/$ACCOUNT_ID/organizations/$ORG_ID/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/opencard",
    "enabled": true,
    "tpa_signed": true,
    "card_holder_created": true,
    "card_holder_identified": true,
    "card_holder_signed_pdpc": true,
    "card_transaction_authorized": true,
    "card_transaction_cleared": true,
    "card_transaction_deleted": true
  }'

Challenge happens immediately. OpenCard sends:

GET https://your-app.com/webhooks/opencard?challenge=RANDOM_STRING
Header: X-Event: challenge

Your endpoint must respond with header:

X-Verify-Token: HMAC-SHA256(challenge, webhook_secret)

Verify: GET .../organizations/$ORG_ID/webhooks shows active: true. Until then no events are delivered.

The webhook is not optional. Card holder lifecycle and PDPC signing write events to it — an organization without a webhook cannot complete PDPC signing. Create it now, before any card holder.

→ Webhook setup

Step 8: TPA gets signed → your first webhook ✍️

The signatory clicks the link from step 5, reads the TPA and signs with eID. When every required signatory has signed:

Signed PDF is generated and stored
tpa.signed is POSTed to your webhook — this is your first real event
TPA status → pending-activation, then activated once confirmed

Verify: you received X-Event: tpa.signed with organization.reference_id = client_acme_001. → eID signing · Event reference

Step 9: Create card holders 👤

Two paths — pick one. Full guide → Card holder onboarding.

Path A: Email + eID (new employee)

curl -X POST https://sandbox-api.opencard.io/api/v1/application/accounts/$ACCOUNT_ID/organizations/$ORG_ID/cardholders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "reference_id": "employee_john_42",
    "email": "john@acme.se"
  }'

John gets an email → signs the PDPC with eID → card_holder.identified → transactions flow.

language is optional. If omitted, OpenCard picks the PDPC language from the TPA country and falls back to English where no translation exists.

Path B: `identity_id` (instant — person already in OpenCard)

# 1. List identities on the TPA (people who already have cards)
curl "https://sandbox-api.opencard.io/api/v1/application/accounts/$ACCOUNT_ID/tpas/$TPA_ID/identities?is_card_holder=false" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

# 2. Create card holder with identity_id — transactions start immediately
curl -X POST https://sandbox-api.opencard.io/api/v1/application/accounts/$ACCOUNT_ID/organizations/$ORG_ID/cardholders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "reference_id": "employee_anna_07",
    "identity_id": 123,
    "skip_pdpc_email": true
  }'

card_holder.identified fires instantly + retroactive transaction webhooks replay. ⚡ Verify: you received X-Event: card_holder.identified.

Step 10: Receive your first transaction 🎉

Once the issuer delivers transaction states for an identified card holder:

// POST to your webhook URL
// Header: X-Event: card.transaction.authorized

{
  "id": "10",
  "state": "authorized",
  "receiptable": true,
  "card_issuer": "nordea",
  "payment_product": {
    "id": 1,
    "name": "Acme Corporate Card"
  },
  "original_amount": 109.38,
  "original_currency": "SEK",
  "purchase_merchant": "Coop Svängsta",
  "purchase_date": "2022-09-02",
  "card_funding": "credit",
  "card_holder": { "reference_id": "employee_john_42" },
  "organization": { "reference_id": "client_acme_001" }
}

Nothing arriving yet? Fire a test event: POST .../webhooks/{webhookId}/test/card.transaction.authorized. You did it. From zero to live transaction data.

Recap — what you stored

Variable	From step	Used in
`ACCOUNT_ID`	0	everything
`TOKEN`	1	everything
`payment_product_id`	2	TPA
`BILLING_ID`	3	organization
`TPA_ID`	4	signatories, organization
`ORG_ID`	6	webhook, card holders

Repeat steps 3–9 for every new client. Steps 0–2 are once per account.

What’s next?

Customer onboarding — the same flow as a production integration guide, with API reference links
Transaction states — how to handle authorized vs cleared vs deleted
All webhook events — full payload reference
Receipt enrichment — digital receipts + true VAT

Overview

First integration

Quickstart — Zero to First Webhook

Step 0: Register (sandbox)

Step 1: Create an account_client and get a token

Step 2: Enable a payment product (once per account)

Step 3: Create a billing profile 🧾

Step 4: Create the TPA 📜

Step 5: Add signatories → email goes out 📧

Step 6: Create the organization 🏢

Step 7: Create the webhook 🔔

Step 8: TPA gets signed → your first webhook ✍️

Step 9: Create card holders 👤

Path A: Email + eID (new employee)

Path B: `identity_id` (instant — person already in OpenCard)

Step 10: Receive your first transaction 🎉

Recap — what you stored

What’s next?

​Step 0: Register (sandbox)

​Step 1: Create an account_client and get a token

​Step 2: Enable a payment product (once per account)

​Step 3: Create a billing profile 🧾

​Step 4: Create the TPA 📜

​Step 5: Add signatories → email goes out 📧

​Step 6: Create the organization 🏢

​Step 7: Create the webhook 🔔

​Step 8: TPA gets signed → your first webhook ✍️

​Step 9: Create card holders 👤

​Path A: Email + eID (new employee)

​Path B: identity_id (instant — person already in OpenCard)

​Step 10: Receive your first transaction 🎉

​Recap — what you stored

​What’s next?

Step 0: Register (sandbox)

Step 1: Create an account_client and get a token

Step 2: Enable a payment product (once per account)

Step 3: Create a billing profile 🧾

Step 4: Create the TPA 📜

Step 5: Add signatories → email goes out 📧

Step 6: Create the organization 🏢

Step 7: Create the webhook 🔔

Step 8: TPA gets signed → your first webhook ✍️

Step 9: Create card holders 👤

Path A: Email + eID (new employee)

Path B: `identity_id` (instant — person already in OpenCard)

Step 10: Receive your first transaction 🎉

Recap — what you stored

What’s next?