Responsibility Matrix
Who does what in a referral partner integration.
:::warning Debitura does not email your clients Debitura never emails onboarding, approval, signing, or KYC URLs to your clients. You are responsible for delivering every URL — in-app, by redirect, or via your own emails. :::
Client Communication
| Responsibility | Owner |
|---|---|
| Deliver onboarding URLs to clients | You |
Deliver signing URLs (solutionUrl from 422 errors) to clients | You |
| Deliver 409 approval URLs to clients | You |
| Deliver KYC form URLs to clients | You |
| Send welcome email after SDCA signing (if SendGrid template configured) | Debitura (using your template and domain) |
Client Onboarding
| Responsibility | Owner |
|---|---|
Initiate onboarding via POST /clients | You |
| Host the white-label onboarding UI (company details, SDCA signing) | Debitura |
Choose and store externalTenantId | You |
Handle all POST /clients response codes (201, 202, 409 variants) | You |
| Re-present onboarding URL if client abandons mid-flow | You |
| Apply partner branding (logo, colors, fonts) to hosted flows | Debitura |
| Expire link requests after the configured TTL (default 7 days, max 30, set per-partner) | Debitura |
Receive client.link_requested / client.link_expired webhooks and re-issue approval URLs on expiry | You |
Case Submission and Collection
| Responsibility | Owner |
|---|---|
| Mint bearer tokens and submit cases to the Customer API | You |
| Validate required case fields before submission | You |
| Route cases to collection partners by jurisdiction | Debitura |
Enforce contract and KYC requirements (return 422 with solutionUrl) | Debitura |
| Perform debt recovery (contact debtors, legal escalation, payment collection) | Collection partner (not Debitura) |
| Surface case status to your clients via webhooks or polling | You |
Contract Management
| Responsibility | Owner |
|---|---|
| Host SDCA, PoA, KYC, and JPA signing flows | Debitura |
Detect missing signatures and return solutionUrl | Debitura |
| Catch 422 errors and redirect clients to signing URLs | You |
| Implement retry-after-signing flow | You |
Decide allowPendingContracts rollout strategy | You |
Revenue and Invoicing
| Responsibility | Owner |
|---|---|
| Calculate referral fees at each pipeline stage | Debitura |
| Lock USD amount when collection partner pays platform commission | Debitura |
Call GET /reporting/transactions to retrieve fee data | You |
| Send monthly invoice to Debitura for "Ready to Invoice" fees | You |
| Process payment after receiving the partner's invoice (net 10 business days) | Debitura |
| Reconcile invoice amounts against API data | You |
Business context: See Referral program overview for commercial terms and fee structure.
Webhooks
| Responsibility | Owner |
|---|---|
| Fire webhook events on state changes | Debitura |
| Retry failed deliveries (up to 8 times, exponential backoff) | Debitura |
| Auto-disable subscriptions after 8 consecutive failures | Debitura |
| Register and maintain webhook subscriptions | You |
| Save the signing secret at creation (shown only once) | You |
| Verify HMAC signatures on every incoming event | You |
| Respond within 10 seconds, process asynchronously | You |
Implement idempotency using event.id | You |
| Monitor and re-enable disabled subscriptions | You |
Common Assumption Violations
Things partners frequently assume Debitura handles — but does not:
| Assumption | Reality |
|---|---|
| Debitura sends onboarding emails | No. You must deliver every URL. |
| Debitura sends follow-up emails for signing or KYC | No. You must surface solutionUrl from 422 errors. |
| Debitura pays referral fees automatically | No. You must invoice Debitura monthly. |
allowPendingContracts bypasses KYC | No. KYC is always a hard 422 block. |
| Bearer tokens can be refreshed | No. Mint a new token on expiry (30-min lifetime). |
| Webhook delivery is exactly-once | No. At-least-once — implement idempotency. |
| Once SDCA is signed, no further signing is needed | No. New jurisdictions, carveouts, and renewals can require new signatures. |
| Partners can choose which collection partner handles a case | No. Debitura routes by jurisdiction. |
| Fee percentage changes apply to existing clients | No. Fee is snapshotted at link creation and frozen. |
| Debitura performs debt collection | No. Collection partners (agencies) do the recovery work. |