Invoice-to-cash integration

This guide describes how to connect the system that issues your invoices — your ERP, billing or subscription system — to your debt collection partner, so that an unpaid invoice becomes a collection case without anyone retyping it, and the money comes back with enough detail to be posted. The integration is small. Four endpoints push data in, and one webhook plus two endpoints bring the settlement back:

Create your customer

The debtor, with the contact details the collector will write to.

Add the case vouchers

The unpaid invoices, and any reminder and compensation fees you have already charged.

Attach the documentation

Invoice copies, contracts, photos — whatever proves the claim.

Money the debtor pays straight to you after handover.

Book the settlement

What you are paid, and what you are charged.

Before you start

Get access to the creditor portal. Your debt collection partner invites you. If you do not have access yet, reach out to them.
Create an API key. In the portal, go to Developers → API, name the key and grant it the scopes listed under Scopes. Authenticate with Authorization: Bearer {token} — see Authentication.
Note your ids. The same page shows your tenantId — your debt collection partner’s tenant, which is part of every URL — and your creditorId, which identifies you.
Ask for the configuration ids you need. The case group you should send cases under, the handles of any custom attributes, and the id of any custom voucher type. These are set up in the platform by your partner.
Add a webhook. Under Developers → Webhooks in the portal, or with Create webhook. It only ever receives events for your own cases. See Webhooks.

Make every write retryable. Every write endpoint accepts an Idempotency-Key header, and case vouchers additionally take a uniqueId that is unique per tenant — so a request that is replayed from a queue cannot create the same invoice or the same payment twice.

Identifiers to store on both sides

Getting the identifier mapping right is the most important part of the integration. Decide up front which id lives where, and persist it.

Store in your own system	Where it comes from	Used for
`customerId`	`POST /customers` response `customerId`	Adding case vouchers for that debtor
`caseId`	`POST /customers/{customerId}/add-case-vouchers` response `caseId`	Attaching documents to the case
`caseVoucherId`	The same response, `caseVoucherId`	Recognising a payment you pushed yourself when it comes back on a webhook

Store in Debbie	Field	Used for
Your customer number	`referenceId` on the customer	Settlement — every payment is reported back under it
Your invoice number	`referenceId` on the case voucher	Registering direct payments, and posting the settlement

customer.referenceId is the identifier your settlement is keyed on. It must be the customer number from the system you post the money back into — not a number invented for the integration. Get it wrong and the money arrives without anything to match it to.

1. Create your customer

A customer is your relationship with the party that owes the money. It holds one or more users: the people involved. Exactly one of them is the debtor.

POST /v1/{tenantId}/customers?creditorId={creditorId}

{
  "isCompany": false,
  "referenceId": "CUST-40218",
  "users": [
    {
      "relation": "debtor",
      "contact": true,
      "lang": "da",
      "details": {
        "name": "Mette Jensen",
        "cpr": "0101801234",
        "email": "mette@example.com",
        "phone": { "locale": "45", "number": "12345678" },
        "address": {
          "address": "Søndergade 5, 2. th",
          "zipcode": "8000",
          "city": "Aarhus C",
          "country": "DK"
        }
      }
    }
  ]
}

One user must be the debtor. relation: "debtor" is the party the claim is against, and the one the debt is registered on. Anyone else on the matter — a guardian, an administrator, a contact at a company — is relation: "alternative-contact".
contact: true marks the user Debbie addresses its letters, emails and texts to.
isCompany says whether the customer is a business or a private individual. Send cvr on the user for a company and cpr for a person.
referenceId is your customer number — the one in the system you keep your books in. It is what the settlement refers to, so it has to match. It only needs to be unique within your creditor, which is why GET /customers/by-reference-id/{referenceId}?creditorId={creditorId} finds the customer again instead of you keeping a mapping table.

The response gives you the customerId. Store it.

API reference: Create customer

See POST Create customer for full details.

2. Add the case vouchers for collection

A case voucher is one financial entry on the claim. Send the unpaid invoice, plus any reminder fees and compensation fees you have already charged, in one request. Debbie decides itself whether that opens a new case or extends an existing one for the same debtor.

POST /v1/{tenantId}/customers/{customerId}/add-case-vouchers

{
  "caseVouchers": [
    {
      "voucherTypeId": "eb41e58e-fccf-419d-a771-cd5027fe6e87",
      "referenceId": "D12412347",
      "uniqueId": "D12412347",
      "amount": -450000,
      "currency": "DKK",
      "date": "2026-05-02",
      "dueDate": "2026-05-16",
      "text": "Invoice 2026-05",
      "properties": { "meterNumber": "874113" }
    },
    {
      "voucherTypeId": "3e51bf87-3c8f-4dd5-abd5-69417d113c89",
      "referenceId": "D12412347-R1",
      "uniqueId": "D12412347-R1",
      "amount": -10000,
      "currency": "DKK",
      "date": "2026-06-01"
    },
    {
      "voucherTypeId": "ed3e3d61-e1bc-4ee2-9166-adf2c41a2bbf",
      "referenceId": "D12412347-K1",
      "uniqueId": "D12412347-K1",
      "amount": -31000,
      "currency": "DKK",
      "date": "2026-06-01"
    }
  ],
  "constraints": {
    "caseGroupId": "0b1a0f3c-6c1d-4b8f-9b6b-6f6a1f2e7a10"
  }
}

Voucher types

voucherTypeId says what the entry is. These are the ones an invoice-to-cash integration normally sends:

What you are sending	`voucherTypeId`
Invoice (faktura)	`eb41e58e-fccf-419d-a771-cd5027fe6e87`
Credit note (kreditnota)	`ef2cdc50-230f-4046-b1af-0f9c498dddd3`
Reminder fee (rykkergebyr)	`3e51bf87-3c8f-4dd5-abd5-69417d113c89`
Compensation fee (kompensationsgebyr)	`ed3e3d61-e1bc-4ee2-9166-adf2c41a2bbf`

The full list, including subscription and loan types, is on the Voucher types page, and Get voucher types returns the same list at runtime including any types your debt collection partner has defined themselves. Fetch it once and cache it rather than hard-coding the ids.

Amounts, references and duplicates

Amounts are integers in the minor unit, and debt is negative. -450000 is a debt of 4,500.00 DKK. A positive amount is a credit note or a payment.
referenceId is your invoice number. It is what you will refer to when you register a direct payment, and what the settlement reports back, so send the number your own system knows.
uniqueId stops duplicates. It is unique across the whole tenant, so a replayed request is rejected rather than creating the invoice twice. Setting it to the invoice number is usually right.

You do not send `source`

Everything you send through this API is imposed by you, and is registered with source: "CREDITOR" whatever the field says. Leave it out.

This matters most for payments. A deposit registered with source: "COLLECTOR" reads as money your debt collection partner received on your behalf — the opposite of a payment made to you — and the settlement comes out backwards. Because the source is decided by the key you are calling with, you cannot get this wrong; do not try to set it.

Attributes and case groups

Two mechanisms carry your own structure into the collection process:

Attributes (properties) are custom fields on a case or a case voucher — a meter number, a contract id, a subscription plan. Your debt collection partner defines the property types in the platform and gives you the handle to use as the key: "properties": { "meterNumber": "874113" }. Attributes can be printed in the letters to the debtor and reported on, so anything the collector or the debtor needs to recognise the claim belongs here.
Case groups segment your portfolio — a product line, a business unit, a brand. Pass constraints.caseGroupId and the case is opened in that group, which decides how the collector treats and reports on it. The id comes from your partner. constraints only applies when the vouchers open a new case; it is ignored when they land on an existing one.

The response gives you one entry per voucher, each with the caseId it landed on and the caseVoucherId it was created as. Store the caseId — you need it for the next step.

[
  {
    "merged": false,
    "caseId": "3f1c2d4e-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    "caseVoucherId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
  }
]

API reference: Add case vouchers

See POST Add case vouchers for full details.

3. Attach the documentation

A claim that is documented is a claim that survives an objection. Attach the invoice copy, the contract, the delivery note, the photo — whatever your partner would otherwise have to ask you for. Documents are attached in two calls: upload the file, then create the document that points at it.

Upload the file

POST /v1/{tenantId}/files

{
  "name": "invoice-D12412347.pdf",
  "contentType": "application/pdf",
  "content": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ..."
}

content is the file, base64 encoded. The response is the stored file:

{
  "id": "8d9f0c1e-2b3a-4c5d-6e7f-8a9b0c1d2e3f",
  "fileName": "invoice-D12412347.pdf",
  "contentType": "application/pdf"
}

The upload calls the identifier id; everywhere it is referenced afterwards — on a document, and as the appendix of a case voucher — the field is called fileId. It is the same value. On a document only the id is read: the name and content type are taken from the stored file.

Create the document

POST /v1/{tenantId}/documents

{
  "entityId": "3f1c2d4e-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
  "entityType": "case",
  "type": "OTHER",
  "minAccessRole": "debtor",
  "file": {
    "fileId": "8d9f0c1e-2b3a-4c5d-6e7f-8a9b0c1d2e3f",
    "fileName": "invoice-D12412347.pdf",
    "contentType": "application/pdf"
  }
}

entityId and entityType say what the document belongs to. case with the caseId you got back in step 2 is what you want for invoice copies and anything else about a specific claim. creditor with your own creditorId is for documents about the relationship itself — a power of attorney, a standing agreement — and they are not tied to a case.
type is always OTHER. The other document types — foundation, verdict, settlement — decide whether a debt has a legal foundation and when it expires, and are set by your debt collection partner as the case progresses through the courts.
minAccessRole decides who can see it. Consider setting it to debtor: the document then shows up in the debtor’s self-service portal, so someone disputing an invoice can see the invoice. Leave it out and the document stays between you and your collection partner.

API reference: Add document

See POST Add document for full details.

4. Register direct payments and credit notes

Once a case is handed over, the debtor may still pay you rather than your debt collection partner — into your own bank account, or through your own portal. Those payments have to reach Debbie, or the collection process keeps chasing money that has already arrived, and the settlement is wrong.

POST /v1/{tenantId}/case-vouchers/allocations?creditorId={creditorId}

{
  "voucherTypeId": "c51f2f6a-8081-45ef-b52d-5e0569fdf12e",
  "matches": [
    { "caseVoucherReferenceId": "D12412347", "amount": 100000 },
    { "caseVoucherReferenceId": "D12412348", "amount": 20000 },
    { "caseVoucherId": "d341b682-c7b2-48b4-9152-17c3b4085089", "amount": 30000 }
  ],
  "date": "2026-06-04",
  "currency": "DKK"
}

Each match identifies an invoice. Use caseVoucherReferenceId for the referenceId you sent the invoice under, or caseVoucherId for Debbie’s id. Give exactly one per match. References must identify exactly one case voucher within your creditor. You can mix the two identifier types in the list, but the same target must not appear twice.
Amounts belong to the matches. Each positive amount is in minor units and cannot exceed the target’s remaining fixed-distribution capacity. Earlier payments and credit notes matched against it count. There is no separate total amount on the request.
One payment voucher is created per case. The two invoices in one case share a payment voucher with their combined amount. An invoice on another case gets a separate payment voucher. Each fixed distribution stays within its case. The response is an array of the created vouchers and their targetCaseVouchers, including each matchedAmount.
All targets must use the same currency. Optional currency asserts that currency; when omitted it is taken from the first target. No conversion is performed.
Send one Idempotency-Key for the whole request. Retry the same request with the same key within 48 hours to get the original result. The operation is atomic: if any match fails, none of the payment vouchers are created.
source is not a field here either. A direct payment is by definition money that never passed through your collection partner, and is always registered as CREDITOR.

Credit notes

Use the same endpoint with voucherTypeId set to ef2cdc50-230f-4046-b1af-0f9c498dddd3 to register a credit note. Send a positive amount for each entry in matches and its issue date in date. One credit-note voucher is created per case, with fixed distributions to the matched invoices on that case. Its amount is the sum of that case’s match amounts. Only deposits and credit notes are currently supported.

When the allocation is refused

Every refusal carries a message that says why. These are the ones to handle:

Status	`message`	What it means
404	`No case voucher found with id …` / `No case voucher found with reference id …`	The voucher does not exist within your creditor, has been deleted, or has not been handed over as part of a case yet.
400	`Reference id … matches more than one case voucher, …`	Two of your invoices share that reference id. Send `caseVoucherId` instead.
400	`Allocation is in … but case voucher … is in …`	All matched invoices must use the same currency, and optional `currency` must agree. Split different currencies into separate requests.
400	`Case voucher … is expired and can no longer be settled`	The claim has expired in Debbie. Contact your collection partner.
400	`Case voucher … is not a debt`	You referenced a payment or a credit note rather than an invoice or a fee.
400	`Amount … exceeds the … still outstanding on case voucher …`	The amount exceeds the remaining capacity after payments and credit notes already matched against the invoice.
400	`Each case voucher may only appear once in matches`	The same target occurs more than once, possibly by both ID and reference.
422	`Give exactly one of caseVoucherId and caseVoucherReferenceId`, or a field error	The body is invalid: `matches` is empty or missing, a match has both or neither identifier, an amount is not a positive integer, or an ID is not a UUID.

A 400 or 404 will not succeed on retry with the same body; put those aside for review rather than back on the queue.

API reference: Register case voucher allocation

See POST Register case voucher allocation for full details.

5. Book the settlement

When your debt collection partner settles with you, a settlement is created and billings.create fires with a billingId. That is the trigger to fetch what the settlement is made of — the payments and how they were split, and the fees and disbursements you are charged — and post it.

Settlements

Settlement has enough detail of its own that it has a separate guide. See Settlements.

What happens in between

Between handover and settlement, the collection process is your partner’s. Three webhooks tell you what is going on without you having to ask:

Event	What it tells you
`cases.create`	A case was opened for you — including the ones your debt collection partner opens without you, from an import or by hand.
`cases.update`	The case changed. A status transition carries the new status, and an ended case carries the reason — paid, written off, withdrawn — which is usually what closes the claim in your own system.
`cases.delete`	A case was deleted.
`billings.create`	A settlement was created. See step 5.

There is no per-payment event today: money reaching a case is accounted for in the settlement, and visible in the creditor portal meanwhile. billings.create is the one your integration has to handle. Subscribe to them under Developers → Webhooks in the portal or with Create webhook; a webhook of yours only ever carries your own creditor’s events.

Do not rebuild the case balance in your own system. Interest accrues on rules agreed with your collection partner, fees follow the collection workflow, and expiry is recalculated as the case moves. A copy would need all of that logic to stay correct and would drift the moment it did not. The balance lives in Debbie — the creditor portal shows it, and GET /customers/{customerId} gives you the cases and their statuses. Book money in your own system, not entries: the payments, and the settlement.

Scopes

Grant the API key only what the integration uses:

Scope	Needed for
`read:customers`, `write:customers`	Steps 1 and 2
`read:case-vouchers`, `write:case-vouchers`	Steps 2 and 4
`write:files`	Step 3, uploading the file
`write:documents`	Step 3, attaching it
`read:billings`	Step 5, reading the settlement
`read:webhooks`, `write:webhooks`	Managing your webhooks over the API instead of in the portal
`read:voucher-types`	Resolving `voucherTypeId` at runtime instead of hard-coding it

Checklist before going live

The customer reference is the one you post money into

customer.referenceId is the customer number from the system that receives the settlement, and caseVoucher.referenceId is your invoice number.

Every write is replayable

Idempotency-Key on every request, uniqueId on every voucher, and failed calls go to a retry queue rather than being dropped.

Identifiers are stored on both sides

customerId, caseId and the caseVoucherId of every voucher you created are persisted in your own system.

Documentation follows the claim

Invoice copies and contracts are uploaded and attached to the case, and it is decided per document type whether the debtor should be able to see it.

Direct payments flow to Debbie the same day

Payments into your own account are registered against the invoice they settle, keyed on the bank transaction id.

The webhook receiver verifies and is idempotent

X-Verification-Token is checked, creditorId is checked against your own, the handler tolerates duplicate deliveries, and it responds 200 before doing downstream work.

Settlement is booked in full

billings.create triggers a fetch of both the deposit distribution and the billing vouchers, and the payout, the commission, the fees and the disbursements are all posted. See Settlements.

Get Started

Guides

Before you start

Identifiers to store on both sides

1. Create your customer

API reference: Create customer

2. Add the case vouchers for collection

Voucher types

Amounts, references and duplicates

You do not send `source`

Attributes and case groups

API reference: Add case vouchers

3. Attach the documentation

Upload the file

Create the document

API reference: Add document

4. Register direct payments and credit notes

Credit notes

When the allocation is refused

API reference: Register case voucher allocation

5. Book the settlement

Settlements

What happens in between

Scopes

Checklist before going live

​Before you start

​Identifiers to store on both sides

​1. Create your customer

API reference: Create customer

​2. Add the case vouchers for collection

​Voucher types

​Amounts, references and duplicates

​You do not send source

​Attributes and case groups

API reference: Add case vouchers

​3. Attach the documentation

​Upload the file

​Create the document

API reference: Add document

​4. Register direct payments and credit notes

​Credit notes

​When the allocation is refused

API reference: Register case voucher allocation

​5. Book the settlement

Settlements

​What happens in between

​Scopes

​Checklist before going live

Before you start

Identifiers to store on both sides

1. Create your customer

2. Add the case vouchers for collection

Voucher types

Amounts, references and duplicates

You do not send `source`

Attributes and case groups

3. Attach the documentation

Upload the file

Create the document

4. Register direct payments and credit notes

Credit notes

When the allocation is refused

5. Book the settlement

What happens in between

Scopes

Checklist before going live