This document outlines the data requirements for an External Collection Service to handle collection agency file generation in a common way. The service receives a JSON request with a common schema and a target format, and produces the appropriate provider-specific file.
The common schema must contain the union of all fields needed across all supported providers and file types.
Supported Providers
| Provider | Claim Format | Payment Format |
|---|---|---|
| Svea Ekonomi | Fixed-width text | Fixed-width text |
| Visma Collectors | XML (VismaCollectorsAct.xsd) | Fixed-width text |
| Intrum | Fixed-width text | Fixed-width text |
All output files are encoded as iso-8859-1. The service handles encoding conversion from UTF-8 (JSON input) to iso-8859-1 (file output), including Swedish characters (å, ä, ö, etc.).
Claim Export (System → Collection Agency)
A claim export sends unpaid invoices to a collection agency for debt recovery.
Data Hierarchy
The schema follows a four-level hierarchy: file (batch metadata), debtors (customer information), invoices (the debts), and invoice lines (per-utility/billing-point breakdown).
File Level
| Field | Type | Description | Used By |
|---|---|---|---|
timestamp | datetime | When the file was generated | All |
provider | enum | Target collection agency | All |
version | string | Calling system version identifier | Visma |
sequenceNumber | integer | Batch sequence number | Visma |
Creditor (Sending Company)
| Field | Type | Description | Used By |
|---|---|---|---|
creditor.id | string | Company's customer number at the collection agency | All |
creditor.department | string | Concern/department number at the agency | Svea, Visma |
creditor.internalReference | string | Internal reference for the creditor | Visma |
creditor.name | string | Company display name | Svea, Visma |
creditor.legalIdentity | string | Company org number | Intrum (payments) |
Debtor (Customer)
| Field | Type | Description | Used By |
|---|---|---|---|
debtor.customerNumber | string | Customer's external identifier | All |
debtor.name | string | Customer's full name | All |
debtor.legalIdentity | string | Organization number or personal number (10 digits). Mandatory for Intrum (validation fails if missing). | All |
debtor.isCompany | boolean | Whether the debtor is a company or private person | All |
debtor.isProtected | boolean | Whether the customer has protected identity | Svea |
debtor.type | enum | Debtor type: Private, Company, PrivateCompany (sole proprietor) | Visma |
debtor.role | string | Debtor role (e.g., primary debtor) | Visma |
Note: The address must be the debtor's national registration address (folkbokföringsadress), not an invoice or delivery address.
| Field | Type | Description | Used By |
|---|---|---|---|
debtor.address.careOf | string | C/O address line | Svea, Visma |
debtor.address.street | string | Street name | All |
debtor.address.houseNumber | string | House number | All |
debtor.address.apartmentNumber | string | Apartment number | All |
debtor.address.poBox | string | PO Box (alternative to street address) | Svea, Intrum |
debtor.address.postalCode | string | Postal code | All |
debtor.address.city | string | City | All |
debtor.address.countryCode | string | ISO country code (default SE) | All |
debtor.phone | string | Phone number | Intrum, Visma |
debtor.mobile | string | Mobile phone number | Visma |
debtor.email | string | Email address | Svea |
Invoice
| Field | Type | Description | Used By |
|---|---|---|---|
invoice.invoiceRef | string | Invoice reference number | All |
invoice.invoiceDate | date | When the invoice was issued | All |
invoice.dueDate | date | Payment due date | All |
invoice.originalDueDate | date | Original due date before any extensions | Visma |
invoice.invoiceAmount | decimal | Original invoice total amount | All |
invoice.capitalAmount | decimal | Capital (principal) amount | All |
invoice.currentBalance | decimal | Current outstanding balance | All |
invoice.currency | string(3) | ISO currency code (e.g., SEK, NOK, EUR) | All |
invoice.rounding | decimal | Rounding amount on invoice | Svea, Intrum |
invoice.expenseAmount | decimal | Total claim/reminder fee amount | Svea, Intrum |
invoice.interestAmount | decimal | Total interest amount | Svea, Intrum |
invoice.interestRate | decimal | Interest rate (percentage) | Svea, Visma |
invoice.interestType | enum | Interest calculation type: Fixed, Percentage, PerMonth, ReferenceRate | Visma |
invoice.hasDelayCompensation | boolean | Whether delay compensation applies | Svea, Intrum |
invoice.isFinalInvoice | boolean | Whether this is the customer's last invoice | Svea, Intrum |
invoice.isPartiallyPaid | boolean | Whether partial payments exist | Svea, Intrum |
invoice.hasDeviatingInvoiceAddress | boolean | Whether invoice was sent to a non-primary address | Svea |
invoice.paymentTermDays | integer | Payment term in days | Visma |
invoice.actionType | enum | Collection or Reminder | Visma |
invoice.debtType | string | Debt classification (e.g., Debetfaktura) | Visma |
Note on actionType: Visma produces separate Act blocks per action type and debtor type, meaning the same debtor can appear in multiple blocks — e.g., one for Collection + Company and one for Reminder + Company. The service groups invoices by actionType and debtor.type when generating the Visma XML.
Invoice Line (Utility/Billing Point Breakdown)
Each invoice is broken down by energy commodity and billing point. This grouping is central to Nordic energy collection.
| Field | Type | Description | Used By |
|---|---|---|---|
line.utility | string(2) | Utility/commodity type code (see mapping table) | All |
line.amount | decimal | Capital amount for this utility/billing point | All |
line.currentAmount | decimal | Current outstanding amount after payments | Svea |
line.comment | string | Free-text description for this line (e.g., "El: 735999100000012345, Storgatan 12 Stockholm") | Intrum |
Note: The caller sends only the real utility lines (EL, FV, VA, etc.). The service generates format-specific additional lines (e.g., Svea's KR/PA/RA lines for rounding, fees, and interest) from the invoice-level amounts (rounding, expenseAmount, interestAmount, billingFee). For Intrum, rounding is folded into the first utility line's amount rather than creating a separate record.
Note: Visma uses only the highest-amount billing point per invoice for its Property section. The service selects it from the provided lines.
Billing Point
Each invoice line may include information about the physical billing point.
| Field | Type | Description | Used By |
|---|---|---|---|
billingPoint.externalId | string | External identifier for the metering/billing point | All |
billingPoint.address | string | Full billing point address (composed) | Svea, Intrum |
billingPoint.street | string | Street address | Visma |
billingPoint.postalCode | string | Postal code | Visma |
billingPoint.city | string | City | Visma |
billingPoint.countryCode | string | Country code | Visma |
billingPoint.meterId | string | Physical meter identifier | Svea, Visma |
billingPoint.netArea | string | Network area code | Svea, Intrum |
billingPoint.regionCode | string | Region/district code ("Lan") | Svea, Intrum |
billingPoint.areaCode | string | Municipality/community code ("Kommun") | Svea, Intrum |
billingPoint.netOwnerId | string | Network owner identifier | Visma |
billingPoint.annualConsumption | decimal | Annual consumption estimate | Svea, Intrum |
billingPoint.isDisconnected | boolean | Whether the billing point is disconnected | All |
billingPoint.disconnectedDate | date | When disconnection occurred | Svea, Intrum |
billingPoint.hasMoved | boolean | Whether the customer has moved | Svea, Intrum |
billingPoint.movedDate | date | When the customer moved | Svea, Intrum |
Costs (Claim Fees)
| Field | Type | Description | Used By |
|---|---|---|---|
cost.type | enum | Claim, Reminder, or LateFee | Visma, Intrum |
cost.date | date | When the cost was incurred | Visma, Intrum |
cost.amount | decimal | Cost amount | Visma, Intrum |
cost.currentAmount | decimal | Current outstanding cost amount | Visma |
cost.invoiceRef | string | Related invoice reference | Intrum |
The service maps cost.type to provider-specific strings:
cost.type | Visma Cost.Name |
|---|---|
Claim | "Krav" |
Reminder | "Påminnelse" |
LateFee | "Förseningavgift" |
The service maps invoice.interestType to Visma XSD values:
interestType enum | Visma InterestType |
|---|---|
Fixed | FAST |
Percentage | PER |
PerMonth | PERMÅN |
ReferenceRate | ÖGR |
Billing Fee
| Field | Type | Description | Used By |
|---|---|---|---|
billingFee.amount | decimal | Invoice billing fee (VAT-inclusive) | Svea |
billingFee.transferredAmount | decimal | Sum of billing fees from transferred/consolidated invoices (VAT-inclusive) | Svea |
Payment Export (System → Collection Agency)
After invoices have been sent to collection, the system reports payments and credits received on those invoices.
File Level
| Field | Type | Description | Used By |
|---|---|---|---|
timestamp | datetime | When the file was generated | All |
provider | enum | Target collection agency | All |
creditor.id | string | Company's payment customer number at the agency | All |
creditor.department | string | Concern/department number | Svea, Visma |
creditor.name | string | Company name | Svea, Visma |
creditor.legalIdentity | string | Company org number | Intrum |
Payment Record
| Field | Type | Description | Used By |
|---|---|---|---|
payment.invoiceRef | string | Invoice reference the payment applies to | All |
payment.amount | decimal | Payment amount | All |
payment.date | date | When the payment was recorded | All |
payment.currency | string(3) | ISO currency code | Svea |
payment.type | enum | Payment or Credit (settlement between invoices) | Svea, Visma |
payment.currentBalance | decimal | Invoice balance after this payment | Svea, Intrum |
payment.customerNumber | string | Customer external ID | Svea, Intrum |
payment.customerName | string | Customer name | Svea |
payment.customerLegalIdentity | string | Customer org/personal number (10 digits) | Intrum |
payment.settledFromInvoiceRef | string | Source invoice ref (for cross-invoice settlements) | Svea |
payment.settledFromInvoiceDate | date | Source invoice date | Svea |
payment.paidCapital | decimal | Capital portion of the payment | Intrum |
payment.paidExpenses | decimal | Expense/fee portion of the payment | Intrum |
payment.paidInterest | decimal | Interest portion of the payment | Intrum |
payment.remainingCapital | decimal | Remaining capital balance after payment | Intrum |
payment.invoiceCredited | boolean | Whether the invoice this payment belongs to is credited (only one payment per invoice should set this to true to avoid duplicate credit records) | Intrum |
payment.creditComment | string | Free-text credit note (e.g., "Fakturan krediterad") | Intrum |
Note on Intrum payment breakdown: The paidCapital/paidExpenses/paidInterest split requires the caller to compute how a lump payment is distributed across capital, expenses, and interest. This typically involves balance calculations at the date the invoice was sent to collection. The service does not compute this split — the caller must provide it.
Notes
- Summary totals, record counts, and checksum records within the files are computed by the service — they are not part of the request schema.
- All amounts in the JSON are standard decimals (e.g.,
12500.00). The service converts to the format required by each provider — fixed-width formats use öre (amount × 100, no decimals, e.g.,1250000).
Utility Type Mapping
The utility code identifies the energy commodity type. The common schema uses a 2-character code:
| Code | Description (Swedish) | Description (English) | Intrum Numeric Code |
|---|---|---|---|
EL | El (handel) | Electricity (trading) | 02 |
EN | Elnat | Electricity (grid/network) | 01 |
EH | Elhandel | Electricity (trading, alt) | 02 |
FV | Fjarrvarme | District heating | 08 |
VA | Vatten | Water | 07 |
BB | Bredband | Broadband | 15 |
RH | Renhallning | Waste management | 09 |
KD | Kundspecifik | Customer-specific | 99 |
Note: Some formats require additional synthetic line types for fees, rounding, and interest (e.g., Svea's KR, PA, RA records). These are generated by the service from the invoice-level amount fields — callers do not need to send them.
Example Schema
Claim Export
Core fields always present, provider-specific fields nullable. The service computes summary totals, record counts, and format-specific transformations (e.g., Intrum numeric utility codes) from this input.
{
"type": "claim",
"format": "SVEA",
"timestamp": "2025-03-10T08:30:00Z",
"version": "3.2.1",
"sequenceNumber": 0,
"creditor": {
"id": "1234567",
"department": "001",
"internalReference": "REF-001",
"name": "Energibolaget AB",
"legalIdentity": "5561234567"
},
"debtors": [
{
"customerNumber": "K-900123",
"name": "Anna Johansson",
"legalIdentity": "8501011234",
"isCompany": false,
"isProtected": false,
"type": "Private",
"role": "Huvudgäldenär",
"address": {
"careOf": null,
"street": "Storgatan",
"houseNumber": "12",
"apartmentNumber": "1102",
"poBox": null,
"postalCode": "11122",
"city": "Stockholm",
"countryCode": "SE"
},
"phone": "0812345678",
"mobile": "0701234567",
"email": "anna.johansson@example.com",
"invoices": [
{
"invoiceRef": "2025001234",
"invoiceDate": "2025-01-15",
"dueDate": "2025-02-15",
"originalDueDate": "2025-02-15",
"invoiceAmount": 12500.00,
"capitalAmount": 11800.00,
"currentBalance": 12500.00,
"currency": "SEK",
"rounding": -0.50,
"expenseAmount": 180.00,
"interestAmount": 45.00,
"interestRate": 0,
"interestType": "PerMonth",
"isFinalInvoice": false,
"isPartiallyPaid": false,
"hasDeviatingInvoiceAddress": false,
"hasDelayCompensation": false,
"paymentTermDays": 31,
"actionType": "Collection",
"debtType": "Debetfaktura",
"billingFee": {
"amount": 45.00,
"transferredAmount": 0
},
"lines": [
{
"utility": "EL",
"amount": 8500.00,
"currentAmount": 8500.00,
"comment": "El: 735999100000012345, Storgatan 12 Stockholm",
"billingPoint": {
"externalId": "735999100000012345",
"address": "Storgatan 12 Stockholm 11122 SE",
"street": "Storgatan 12",
"postalCode": "11122",
"city": "Stockholm",
"countryCode": "SE",
"meterId": "MET-12345",
"netArea": "SN1",
"regionCode": "01",
"areaCode": "180",
"netOwnerId": "ELNAT-001",
"annualConsumption": 15000,
"isDisconnected": false,
"disconnectedDate": null,
"hasMoved": false,
"movedDate": null
}
},
{
"utility": "FV",
"amount": 3300.00,
"currentAmount": 3300.00,
"comment": "Fjärrvärme: 735999100000054321, Storgatan 12 Stockholm",
"billingPoint": {
"externalId": "735999100000054321",
"address": "Storgatan 12 Stockholm 11122 SE",
"street": "Storgatan 12",
"postalCode": "11122",
"city": "Stockholm",
"countryCode": "SE",
"meterId": "MET-54321",
"netArea": null,
"regionCode": "01",
"areaCode": "180",
"netOwnerId": null,
"annualConsumption": null,
"isDisconnected": false,
"disconnectedDate": null,
"hasMoved": false,
"movedDate": null
}
}
],
"costs": [
{
"type": "Reminder",
"date": "2025-02-20",
"amount": 60.00,
"currentAmount": 60.00,
"invoiceRef": "2025001234"
},
{
"type": "Claim",
"date": "2025-03-05",
"amount": 180.00,
"currentAmount": 180.00,
"invoiceRef": "2025001234"
}
]
}
]
},
{
"customerNumber": "K-800456",
"name": "Fastigheter i Norr AB",
"legalIdentity": "5567891234",
"isCompany": true,
"isProtected": false,
"type": "Company",
"role": "Huvudgäldenär",
"address": {
"careOf": null,
"street": "Industrivägen",
"houseNumber": "5",
"apartmentNumber": null,
"poBox": null,
"postalCode": "90325",
"city": "Umeå",
"countryCode": "SE"
},
"phone": "0901234567",
"mobile": null,
"email": null,
"invoices": [
{
"invoiceRef": "2025005678",
"invoiceDate": "2024-12-01",
"dueDate": "2025-01-01",
"originalDueDate": "2025-01-01",
"invoiceAmount": 45200.00,
"capitalAmount": 44000.00,
"currentBalance": 25200.00,
"currency": "SEK",
"rounding": 0,
"expenseAmount": 600.00,
"interestAmount": 120.00,
"interestRate": 0,
"interestType": "PerMonth",
"isFinalInvoice": false,
"isPartiallyPaid": true,
"hasDeviatingInvoiceAddress": false,
"hasDelayCompensation": true,
"paymentTermDays": 31,
"actionType": "Collection",
"debtType": "Debetfaktura",
"billingFee": {
"amount": 0,
"transferredAmount": 0
},
"lines": [
{
"utility": "VA",
"amount": 44000.00,
"currentAmount": 24000.00,
"comment": "Vatten: 735999200000099887, Industrivägen 5 Umeå",
"billingPoint": {
"externalId": "735999200000099887",
"address": "Industrivägen 5 Umeå 90325 SE",
"street": "Industrivägen 5",
"postalCode": "90325",
"city": "Umeå",
"countryCode": "SE",
"meterId": "MET-99887",
"netArea": null,
"regionCode": "24",
"areaCode": "280",
"netOwnerId": null,
"annualConsumption": null,
"isDisconnected": true,
"disconnectedDate": "2025-02-15",
"hasMoved": false,
"movedDate": null
}
}
],
"costs": [
{
"type": "Claim",
"date": "2025-02-01",
"amount": 600.00,
"currentAmount": 600.00,
"invoiceRef": "2025005678"
}
]
}
]
}
]
}
Payment Export
{
"type": "payment",
"format": "INTRUM",
"timestamp": "2025-03-10T09:00:00Z",
"creditor": {
"id": "7654321",
"department": null,
"name": "Energibolaget AB",
"legalIdentity": "5561234567"
},
"payments": [
{
"invoiceRef": "2025005678",
"amount": 20000.00,
"date": "2025-03-08",
"currency": "SEK",
"type": "Payment",
"currentBalance": 25200.00,
"customerNumber": "K-800456",
"customerName": "Fastigheter i Norr AB",
"customerLegalIdentity": "5567891234",
"settledFromInvoiceRef": null,
"settledFromInvoiceDate": null,
"paidCapital": 19500.00,
"paidExpenses": 400.00,
"paidInterest": 100.00,
"remainingCapital": 24500.00,
"invoiceCredited": false,
"creditComment": null
},
{
"invoiceRef": "2025001111",
"amount": 5500.00,
"date": "2025-03-09",
"currency": "SEK",
"type": "Credit",
"currentBalance": 0,
"customerNumber": "K-800456",
"customerName": "Fastigheter i Norr AB",
"customerLegalIdentity": "5567891234",
"settledFromInvoiceRef": "2025002222",
"settledFromInvoiceDate": "2025-01-15",
"paidCapital": 5500.00,
"paidExpenses": 0,
"paidInterest": 0,
"remainingCapital": 0,
"invoiceCredited": true,
"creditComment": "Fakturan krediterad"
}
]
}