1. Wrong environment (test vs. production)
Problem
API calls succeed but data does not appear in the live platform, or you see test data where you expect real data.
Likely cause
Your integration is pointing at the wrong base URL. Debitura provides two separate environments for the Referral Partner API:
Production: https://referral-api.debitura.com/
Each environment has its own API keys. A production key will not work against the test endpoint and vice versa.
Fix
Ask your developer which base URL is configured in your integration.
Confirm the API key matches the environment. Production and test keys are issued separately.
If you are unsure which keys you have, see How to request credentials, environments, and support access.
2. Missing or invalid API credentials
Problem
API calls return authentication errors (HTTP 401 or 403), or the integration cannot connect at all.
Likely cause
The Referral Partner API requires an API key in the X-Api-Key header of every request. Common issues:
The API key was never configured in your integration.
The key is for the wrong environment (see section 1 above).
The key contains extra whitespace or formatting characters.
Fix
Ask your developer to confirm that the X-Api-Key header is included in every API request.
Verify the key matches the target environment.
To test that the key is valid, your developer can call GET /referral-partners/{partnerId}. A successful response confirms the key works.
If you need a new key or are unsure whether one was issued, contact [email protected].
3. Webhook endpoint not receiving events
Problem
Your system is not receiving webhook notifications (for example, client onboarding events or case updates).
Likely cause
Debitura's webhook system requires specific endpoint configuration. Common issues:
No webhook subscription has been created.
The endpoint URL uses HTTP instead of HTTPS (HTTPS is required).
The endpoint is on a private IP address or localhost (public IP only).
The TLS certificate on the endpoint is invalid or expired.
The endpoint is not responding with a 2xx status code.
The webhook subscription exists but does not include the relevant event types.
Fix
Ask your developer to list current webhook subscriptions by calling GET https://referral-api.debitura.com/v1/Webhooks with your API key.
If no subscription exists, your developer needs to create one by calling POST https://referral-api.debitura.com/v1/Webhooks with the endpoint URL and desired event types.
Confirm the endpoint URL starts with https:// and resolves to a public IP address.
Ask your developer to check that the endpoint responds with a 2xx status code when it receives a POST request.
Review which event types are subscribed. Available referral partner events are: client.onboarding.poa_signed, client.onboarding.contract_signed, client.linked, client.link_declined, case.created, case.updated. For details on what each event means, see Webhook events (business meaning).
4. Client creation returns a 409 Conflict
Problem
Your integration tries to create or link a client (POST /clients) but receives a 409 Conflict response instead of 201 or 202.
Likely cause
A 409 Conflict means the client already exists in Debitura. There are three scenarios:
ClientExistsNeedsLinking: The client has a Debitura account but is not yet linked to your partner account. The response includes an approval URL.
AlreadyLinkedDifferentTenant: The client is already linked to your account, but under a different ExternalTenantId. Each client can only have one ExternalTenantId per partner.
ClientAlreadyLinkedToAnotherPartner: The client is linked to a different referral partner. Only one referral partner link per client is supported.
Fix
Check the Type field in the 409 response body to identify the specific scenario.
For ClientExistsNeedsLinking: Send the approval URL from the response to the client via email. The client must approve the link. For help with this flow, see Customer signup / activation issues.
For AlreadyLinkedDifferentTenant: Use the existing ExternalTenantId shown in the error message. If you need to change it, contact Debitura Support.
For ClientAlreadyLinkedToAnotherPartner: Contact Debitura Support at [email protected] to discuss options.
5. Client stuck in "OnboardingRequired" status
Problem
A client was created successfully (202 Accepted) but has not completed onboarding. Calling POST /clients again still returns 202.
Likely cause
The client has not signed the Standard Debt Collection Agreement (SDCA). Until the SDCA is signed, the client cannot submit cases. A 202 response always includes an OnboardingUrl that the client must visit to complete signing.
Fix
Resend the OnboardingUrl to the client and ask them to complete the signing process.
If you have webhooks configured, check whether you received a client.onboarding.contract_signed event. If not, the client has not finished onboarding.
Alternatively, your developer can check SDCA status by calling GET /contracts/debt-collection/status with the client's bearer token.
6. Case creation fails with validation errors
Problem
Submitting cases returns HTTP 400 with validation error details.
Likely cause
Required fields are missing or contain invalid data. The API returns a structured error with field-specific messages. Common validation issues include missing debtor email, invalid currency code, negative amounts, or a due date before the invoice date.
Fix
Check the error response body. It contains a Details object with field-specific validation messages.
Forward the error response to your developer so they can fix the data mapping.
Note: validation errors (HTTP 400) abort the entire operation. The client is not created if validation fails.
7. Cases fail with "NoPartnerAvailable"
Problem
Client creation succeeds (201 or 202) but some or all cases appear in the FailedCases array with ErrorType: NoPartnerAvailable.
Likely cause
Debitura does not yet have a collection partner in the debtor's country. The client account is still created and linked, but the case itself is not created for that jurisdiction.
Fix
This is not a bug. Coverage depends on Debitura's collection partner network.
The client is still linked to your account with attribution. If the client creates cases in supported countries later, you earn referral fees.
Check the FailedCases array for the specific countries that are not supported.
If coverage for a particular country is important to you, contact Debitura Support to ask about expansion plans.
8. Webhook signature verification failing
Problem
Your endpoint receives webhook deliveries but signature verification fails, so your system rejects them.
Likely cause
Debitura signs every webhook delivery using HMAC-SHA256. The signing secret is shown only once when the webhook subscription is created. Common issues:
The signing secret was not stored or was stored incorrectly.
The secret is not being decoded from Base64 before computing the signature.
The timestamp tolerance check is too strict (Debitura allows a 5-minute window).
Fix
If the signing secret was lost, your developer can regenerate it by updating the webhook subscription (set RegenerateSecret to true in the update request).
Verify the implementation follows these steps: extract timestamp and signature from the X-Debitura-Signature header, construct the signed payload as {timestamp}.{json_body}, decode the secret from Base64, then compute HMAC-SHA256.
Forward these details to your developer along with a sample webhook delivery for debugging.
Escalation checklist
If the steps above do not resolve your issue, use the checklists below to collect the right information before reaching out.
What to send Debitura Support
Email contact@debitura.com with:
Your partner name and Partner ID.
Which environment you are using (production or test).
A description of the issue and which checklist item above you tried.
The HTTP status code and full error response body (with any sensitive data redacted).
The traceId from the error response, if present.
Timestamps of when the issue occurred.
What to forward to your developer
Share these items with your development team for technical debugging:
The base URL currently configured in the integration.
The HTTP method, endpoint path, and request headers (redact the API key value).
The full response body including any ErrorType, ValidationErrors, or traceId fields.
Webhook subscription details: endpoint URL, subscribed event types, whether the signing secret is stored.
Any logs from your system related to the failed request.
Developer Docs: Developers implementing or debugging the integration can find technical details, code examples, and API schemas in Developer Docs: Referral Partners Troubleshooting.
For a broader overview of how the Referral Partner integration works, see API & integration overview.