TPA Flow — Full Walkthrough

TPA = Transaction Processing Authorization. It’s the legal agreement that says “this company’s card transaction data is allowed to flow through OpenCard to the EMS.” Without a signed TPA, no transactions.

New here? Start with the full customer onboarding flow — billing, organization, webhook, and card holders around this TPA step.

TPA lifecycle states

Status	Meaning
`pending-signatures`	Signatories added but not all signed yet
`pending-activation`	Waiting for TPA to be confirmed
`activated`	Live. Transactions flow.

Step 1: Create TPA

POST /api/v1/application/accounts/{accountId}/tpas
Scope: account-tpas-write

{
  "card_issuer_id": 1,
  "name": "Acme AB",
  "country": "SE",
  "organization_number": "5561234567",
  "language": "sv"
}

Field	Required	Notes
`card_issuer_id`	✅	Which card program — from issuers enabled on your account (`GET .../accounts/{accountId}/cardissuers`)
`name`	✅	Overwritten by registry name if found
`country`	✅	`SE`, `DK`, `NO`, or `FI` only
`organization_number`	✅	Format depends on country (see below)
`language`	❌	`sv`, `no`, `da`, `en`, `fi`. Defaults from country

Response 201:

{
  "id": 42,
  "account_id": 1,
  "card_issuer_id": 1,
  "name": "Acme AB",
  "country": "SE",
  "organization_number": "5561234567",
  "activated": false,
  "signatures_verified": false,
  "signed_document_path": null,
  "signatures_verified_at": null,
  "created_at": "2026-06-08T10:00:00.000000Z",
  "updated_at": "2026-06-08T10:00:00.000000Z"
}

Org number validation

Country	Rule	Example
🇸🇪 `SE`	exactly 10 digits	`5561234567`
🇳🇴 `NO`	exactly 9 digits	`987654321`
🇩🇰 `DK`	exactly 8 digits	`12345678`
🇫🇮 `FI`	`\d{7}-\d{1}`	`1234567-8`

Step 2: Check who can sign (recommended)

Before adding signatories, query the public registry:

GET /accounts/{accountId}/publicrecords?country=SE&organization_number=5561234567
Scope: public-records-read

Example response:

{
  "organization_number": "5561234567",
  "name": "Acme AB",
  "address_street": "Storgatan 1",
  "address_zip": "111 22",
  "address_city": "Stockholm",
  "signature_combinations": [
    {
      "signatories": [
        { "admin_sign": false, "name": "Anna Andersson", "ssn_hash": null },
        { "admin_sign": false, "name": "Erik Eriksson", "ssn_hash": null }
      ]
    }
  ]
}

Each entry in signature_combinations is one valid signing group — everyone listed in that group must sign for the combination to be satisfied.

The registry does not always list who may sign. Many organization types — foundations, associations, and similar entities — are not fully registered as companies in public records across the Nordic countries. The response may include company details but an empty signature_combinations array. In that case OpenCard cannot suggest signatories; your client must decide internally who is authorized to sign and you add them as signatories manually.

Step 3: Add signatories → email fires 📧

POST /accounts/{accountId}/tpas/{tpaId}/signatories
Scope: account-tpa-signatories-write

{
  "email": "ceo@acme.se",
  "name": "Anna Andersson",
  "country_code": "+46",
  "phone_number": "0701234567"
}

Only email is required. phone_number is stored but not returned in API responses. What happens immediately:

token = random 40-char string generated
Signatory record created with signed: false
Email queued via issuer-specific mailer:
- Subject: Authorise TPA for {tpaName}
- Template: TPA signing invitation
- Link: https://{env}/accounts/{accountId}/tpas/{tpaId}/sign/{token}
- Language: English (hardcoded for signatory emails)

The signatory does not need an OpenCard account. The token in the URL is their auth.

Update / delete signatory

PUT  .../signatories/{tpaSignatoryId}   ← only if signed=false, resends email
DELETE .../signatories/{tpaSignatoryId} ← only if signed=false

Reminder emails

If a signatory has not signed after 7+ days, OpenCard may send a reminder email automatically.

Step 4: Signatory signs with eID ✍️

This is a web flow, not an API call. The signatory:

Clicks email link → GET /accounts/{accountId}/tpas/{tpaId}/sign/{token}
Sees TPA legal text (markdown rendered)
Clicks “Sign” → eID widget loads
Completes signing with national eID — see eID Signing
eID result is posted back → POST .../sign/{token}

When all required signatories have signed, OpenCard verifies signing rights against signature_combinations from the registry (stored on the TPA at creation) for Sweden and Norway. If no signatory combinations were available from the registry, OpenCard cannot verify automatically — the TPA goes through manual review before signatures_verified is set.

Step 5: TPA fully signed → stuff happens

When signing is complete:

📄 Signed PDF generated with all signatory eID approval blocks
📧 Email to each signatory with signed PDF attached
📧 Card issuer notified (signed PDF delivered)
🔔 tpa.signed webhook fires on orgs that subscribed

Webhook payload:

{
  "id": "42",
  "name": "Acme AB",
  "organization_number": "5561234567",
  "url": "https://api.opencard.io/files/tpas/abc123.pdf",
  "organization": {
    "reference_id": "client_acme_001"
  }
}

Download signed PDF via API

GET /accounts/{accountId}/tpas/{tpaId}/signeddocuments
→ application/pdf

Step 6: Activation

TPA moves to activated when the TPA is confirmed — triggered on the issuer side, not something you call directly. Until activated, transactions won’t flow even if TPA is signed.

Delete TPA

DELETE /accounts/{accountId}/tpas/{tpaId}

If TPA was activated → issuer termination email sent, cascades delete organizations/webhooks/cardholders linked to it.

Only delete TPAs you’re sure are unused. Activated TPA deletion is destructive.

TPA embed plugin (optional)

OpenCard ships a JS wizard (ocTPA) for self-service TPA onboarding on your site. It collects issuer selection, signatory combos, billing info — then calls your onDataSend callback with the payload for you to hit the APIs. See Plugins.

Model

Platform

Customer onboarding

Webhooks

Enrichment

Advanced

API — Auth

API — Endpoints

TPA Flow — Full Walkthrough

TPA lifecycle states

Step 1: Create TPA

Org number validation

Step 2: Check who can sign (recommended)

Step 3: Add signatories → email fires 📧

Update / delete signatory

Reminder emails

Step 4: Signatory signs with eID ✍️

Step 5: TPA fully signed → stuff happens

Download signed PDF via API

Step 6: Activation

Delete TPA

TPA embed plugin (optional)

​TPA lifecycle states

​Step 1: Create TPA

​Org number validation

​Step 2: Check who can sign (recommended)

​Step 3: Add signatories → email fires 📧

​Update / delete signatory

​Reminder emails

​Step 4: Signatory signs with eID ✍️

​Step 5: TPA fully signed → stuff happens

​Download signed PDF via API

​Step 6: Activation

​Delete TPA

​TPA embed plugin (optional)

TPA lifecycle states

Step 1: Create TPA

Org number validation

Step 2: Check who can sign (recommended)

Step 3: Add signatories → email fires 📧

Update / delete signatory

Reminder emails

Step 4: Signatory signs with eID ✍️

Step 5: TPA fully signed → stuff happens

Download signed PDF via API

Step 6: Activation

Delete TPA

TPA embed plugin (optional)