How to build a "Send to collection" button
Where the button sits, what your server sends, what your user sees after the click and which events you handle. Based on Debitura's Starter integration: one API call per invoice, one button and one webhook.
What happens when your user clicks
Your product sends the invoice. Debitura works out what your user still has to do and returns one link. A local collector takes over once the case is ready.[1]
Your user clicks "Send to collection"
The button sits next to an invoice that is still unpaid after your last reminder.
Your server sends the invoice
One call to
POST /collection-requestswith your partner API key and anIdempotency-Key. Never from browser code.[1]Your button opens the returned link
If your user has to sign up, approve the connection, sign an agreement, verify their identity or fix the invoice, the response carries a
solutionUrl. Debitura's hosted pages show your logo.[1][4]The invoice becomes a case
Debitura matches the case to a vetted local collection agency or law firm in the debtor's country, which works it under local law.[4]
You show the status
Webhooks tell you when the request or the case changes; a read gives you the current state to show next to the invoice.[1][2]
Where the button sits and what it says
Collection is the step after the last reminder, so the button belongs where your users already look at overdue invoices.
On the overdue list
A row action or a bulk action for several selected invoices. Five selected invoices are five separate requests, each with its own key.[1]
On the invoice
Next to the reminder history, once the last reminder has gone out. This is where a user decides that reminders are not enough.
In the reminder flow
As the final step of a reminder sequence, offered rather than automatic. The Ledgerline demo shows placements inside a fictional accounting product.[3]
| Status returned | Label to show | What your button does |
|---|---|---|
awaiting_onboarding | Set up account | Opens the returned link |
awaiting_approval | Approve connection | Opens the returned link; Debitura also emails the user an invitation |
awaiting_signature | Sign agreement | Opens the returned link |
awaiting_kyc | Complete identity details | Opens the returned link |
needs_fixing | Correct and submit invoice | Opens the returned link; saving alone creates no case |
processing | Processing | Waits, then reads the request again |
submitted | Submitted, check case status | Shows the case status and its link |
rejected | Not accepted | Shows the returned reason |
expired | Connection approval expired | Explains the expiry; a new request can ask again |
Source: Build the collection button.[1] Use the URL the API returns, never one you build from IDs. A submitted invoice is not yet in active collection: the case can still be in verification.
What your server sends
One invoice per request. Your own identifiers let you find the request again later.[1]
POST https://testreferral-api.debitura.com/collection-requests
XApiKey: <your-test-partner-key>
Idempotency-Key: inv-0042
{
"externalTenantId": "your-client-42",
"client": { "name": "Example Client Ltd",
"country": "GB",
"supportEmail": "accounts@example.invalid" },
"user": { "name": "Example User",
"email": "accounts@example.invalid" },
"invoices": [{
"creditorReference": "INV-0042",
"debtor": { "type": "Company",
"name": "Example Debtor Ltd",
"countryAlpha2": "GB" },
"amountToRecover": 1500.00,
"currencyCode": "GBP",
"dueDate": "2026-06-30T00:00:00Z",
"isTest": true
}]
}Shortened from the example in the developer docs; the API reference lists every field.[1]
What to know
externalTenantIdis your stable ID for your user's company;creditorReferenceis the invoice number.clientanduserset up a new account once and never overwrite an existing one.invoicesholds exactly one invoice. A bulk action sends one request per invoice.isTest: truecreates classified test data in the test environment, where no real collection happens and emails are suppressed.[5]- Return navigation after the hosted pages is set on your partner account, not per request.
Retries that never create a second case
Same key, same answer
For 24 hours, the same Idempotency-Key returns the original response. A changed payload with that key is refused.[1]
Read, do not resend
A replayed response is the original snapshot and can show an earlier step. To check progress, read the request with GET /collection-requests/{id} or by client and invoice reference.[1]
Existing cases are recognised
A new request for the same client, invoice reference and test or live classification returns the existing case, whichever route created it.[1]
Webhooks to subscribe to
Subscriptions, signatures, retries and deduplication work the same way for every Debitura partner webhook.[2]
| Event | When it fires | What you do |
|---|---|---|
collection_request.updated | The request's status or an invoice outcome changes | Read the request and update the invoice row |
case.created | The invoice has become a case | Store the case and show its status |
case.updated | The case's lifecycle state changes | Update the status next to the invoice |
case.closed | The case is closed | Show the outcome and stop showing the case as active |
Handle every delivery safely
A read is the recovery path
Some changes, such as moving from one agreement to the next, appear in a read without a new request event. After your user returns from the hosted pages, read every selected request again, even if no webhook arrived.[1]
Failures and conflicts to plan for
| What happens | What it means | What to do |
|---|---|---|
400 | The request is unreadable: malformed JSON, missing identifiers, more than one invoice | Fix the request; nothing was stored |
needs_fixing | The invoice is readable but needs correcting | Open the returned link; your user fixes it on Debitura |
rejected | Debitura cannot take the invoice, for example the country is not covered or the amount is below the minimum | Show the returned reason |
Timeout or 5xx | A dependency failed | Retry with the same key or read the request; do not tell your user it worked |
| Existing Debitura account | Your user's company already uses Debitura | Nothing is created until the user approves the connection; approvals normally expire after 7 days |
| Identity details missing | The case waits for KYC | Open the returned link; submitting the details releases the case |
Source: Build the collection button.[1] In the Full integration you create clients yourself with POST /clients and handle its 201, 202 and 409 responses, including the approval link for an existing account.[3]
What your user and their customer see
Your user
A short flow on Debitura's hosted pages with your logo and primary color: confirm the company, sign the collection agreement with two-factor verification, then back to your product.[4]
Their emails
No "collection started" email arrives just because your request was received. When the local collector starts, a case-start email names the collector and the fee recorded for that case.[1]
The debtor
Hears from the local collection agency or law firm in their own country, not from your platform.[4]
From test keys to the first live case
Starter integration
Two endpoints (POST and GET /collection-requests), one button and one webhook. Debitura handles sign-up, approvals, agreements, identity checks and invoice fixes.[3]
Build and test against the test environment, where no real collection happens and emails only reach whitelisted domains. Then switch to production keys and follow cases in the partner dashboard.[5][4] For the business case and the three ways to embed collection, read Embedded collections: the missing layer of embedded finance.
"Send to collection" button: questions
What does a "Send to collection" button do?
It hands an overdue invoice from your product to a collection provider. Your server sends the invoice through an API, your user finishes any setup on a short hosted flow, and a local collector in the debtor's country works the claim.
Can my users send several invoices at once?
Yes. Keep your bulk button and send one request per invoice, each with its own idempotency key. One shared step, such as signing the agreement, can move all of that client's requests forward.
How do I stop a retry from creating a duplicate case?
Reuse the same Idempotency-Key. For 24 hours, Debitura returns the original response for that key and refuses a changed payload. A request for an invoice that is already a case returns the existing case.
Which webhooks do I need?
For the Starter integration, collection_request.updated, plus case.created, case.updated and case.closed if you show case progress. Verify the signature, answer within 10 seconds and deduplicate by event id.
What happens if my user already has a Debitura account?
Nothing is created until they approve the connection to your product. Debitura emails them an invitation, and the same link comes back to your button. Approvals normally expire after 7 days.
How long does it take to build?
The Starter integration is one API call per invoice, a button and one webhook. A Full integration typically takes two to four weeks, including testing.
Woher diese Fakten stammen
Debitura's developer docs and partner page, accessed 11 November 2026. The docs are the reference for every field and response.
- Debitura, Developer docs: Build the collection button. docs.debitura.com/referral-partners/integration-guides/starter-integration
- Debitura, Developer docs: Webhooks. docs.debitura.com/referral-partners/integration-guides/webhooks
- Debitura, Developer docs: Referral partners, two ways to integrate. docs.debitura.com/referral-partners
- Debitura, Referral partner program: embed debt collection in your platform. debitura.com/solutions/referral-partners
- Debitura, Developer docs: Environments and test data. docs.debitura.com/referral-partners/getting-started/environments
Get test keys for your button
Tell us about your product and the countries your users invoice, and we will set you up with the test environment and the partner docs.