Skip to main content

Quickstart: your first collection request

Send one invoice for a new, fictional client in test, open the link Debitura returns, then read the request back. This is the whole Starter Integration loop.

Use this when: you're building the Starter Integration. You'll need: a test XApiKey (see Get started) and curl.

Step 1: Send the invoice​

Choose your own identifiers: externalTenantId is your ID for the client, and creditorReference is the invoice number. The Idempotency-Key makes a retry safe.

curl -X POST https://testreferral-api.debitura.com/collection-requests \
  -H "XApiKey: $DEBITURA_TEST_KEY" \
  -H "Idempotency-Key: quickstart-inv-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "externalTenantId": "quickstart-client-1",
    "client": {
      "name": "Quickstart Client Ltd",
      "country": "GB",
      "supportEmail": "you@your-company.example"
    },
    "user": {
      "name": "Quickstart User",
      "email": "you@your-company.example"
    },
    "invoices": [{
      "creditorReference": "QS-INV-0001",
      "debtor": {
        "type": "Company",
        "name": "Example Debtor Ltd",
        "countryAlpha2": "GB",
        "address": "10 Example Street",
        "city": "London"
      },
      "amountToRecover": 1500.00,
      "currencyCode": "GBP",
      "date": "2026-06-01T00:00:00Z",
      "dueDate": "2026-06-30T00:00:00Z",
      "isTest": true
    }]
  }'

The client is new, so Debitura creates it and answers 202 Accepted. Onboarding comes next:

{
  "id": "33333333-3333-4333-8333-000000000042",
  "status": "awaiting_onboarding",
  "solutionType": "onboarding",
  "solutionUrl": "https://testreferral.debitura.com/Onboarding/CompanyDetails/55555555-5555-4555-8555-555555555555",
  "externalTenantId": "quickstart-client-1",
  "invoices": [{ "creditorReference": "QS-INV-0001", "status": "waiting" }]
}

Store the id. In your product, this is the moment the button opens solutionUrl.

Step 2: Open the solutionUrl​

Open solutionUrl in a browser and complete onboarding as your client would, on Debitura's pages with your branding.

Signing asks for a verification code sent by email. Test emails only reach domains Debitura has whitelisted for you, so use an email address on such a domain. Alternatively, ask your partnership contact for a demo-flagged test partner; there, the code is always 123456.

Step 3: Read the request back​

curl https://testreferral-api.debitura.com/collection-requests/33333333-3333-4333-8333-000000000042 \
  -H "XApiKey: $DEBITURA_TEST_KEY"

When nothing is left for the client to do, the request is submitted and the invoice has a case:

{
  "id": "33333333-3333-4333-8333-000000000042",
  "status": "submitted",
  "solutionType": "case",
  "solutionUrl": "https://…  (the client's case page)",
  "invoices": [{ "creditorReference": "QS-INV-0001", "status": "created", "caseId": "…" }]
}

If the status is still awaiting_… (another agreement, or KYC for this debtor's country), the response carries a new solutionUrl. Open it and read again. That loop is your integration.

What you built​

One request, one link and one read. In production, a button replaces the curl, and the collection_request.updated webhook replaces the manual read.

What's next​