Skip to main content

Going Live

You've validated your integration against the test environment. This page covers what needs to be in place before production traffic reaches Debitura, followed by a pre-flight checklist to verify every integration requirement.

Business context: See How to go live (non-technical checklist) for the commercial go-live steps your business and operations team needs to complete.

Environments​

Debitura runs two fully isolated environments. Credentials, webhook subscriptions, clients, cases, tokens, and signing secrets are all environment-scoped — production and test never share data in either direction.

ServiceProductionTestUsed for
Referral Partner APIreferral-api.debitura.comtestreferral-api.debitura.comClient onboarding, token minting, webhooks, reporting
Customer APIcustomer-api.debitura.comtestcustomer-api.debitura.comCase submission and management
White-Label UIreferral.debitura.comtestreferral.debitura.comOnboarding and signing URLs presented to clients

:::info Enforcement is identical across environments KYC, SDCA, PoA, and carveout requirements are driven by per-partner flags and per-jurisdiction configuration — not by which environment you're in. A flow that works in test will behave the same way in production, provided you test against a collection partner with the same enforcement profile as your production partner. Test with a KYC-required partner if your production cases will route to one. :::

Production readiness​

Three things need to be in place before your production build calls Debitura. How you deploy them — single environment with feature flags, separate staging/prod builds, blue-green cutover — is up to you.

1. Request production credentials​

Production API keys are issued by Debitura separately from test keys. Contact your Debitura account manager to request them. You will receive:

  • A production XApiKey for the Referral Partner API
  • Confirmation that your partner account is enabled in production

Keep the test key — you will still need it for regression testing and staging going forward.

2. Point production at the production hosts​

Make sure your production build is configured with the production API base URLs listed above — referral-api.debitura.com and customer-api.debitura.com. Common miss: hardcoded URLs in webhook-handling code, background jobs, or retry logic.

The White-Label UI host (referral.debitura.com vs testreferral.debitura.com) is not something you configure — it is returned inside solutionUrl values by the API you called. If your production build calls the production API, the signing URLs it receives will already point at the production UI.

3. Register webhook subscriptions in production​

Webhook subscriptions do not migrate between environments. Create new subscriptions in production via POST /v1/webhooks on referral-api.debitura.com.

  • Save the signing secret returned at creation time — it is never returned again and differs from your test secret
  • Configure your production handler to verify signatures using the production secret
  • Subscribe to the same event types you use in test — at minimum: client.onboarding.contract_signed, client.linked, client.link_requested, client.link_expired, case.created, case.updated, case.closed

See Webhooks for the full setup.

Dry-run your first production case with isTest: true​

Before opening the integration to real customer traffic, submit your first production case with isTest: true on the payload. The case is created in production and exercises the full end-to-end flow — onboarding, signing, case creation, webhook delivery, status updates — but it is classified internally as a test case and is never dispatched to the collection partner, so no real debtor outreach happens.

POST https://customer-api.debitura.com/cases
{
  "isTest": true,
  "currencyCode": "…",
  "amountToRecover": …,
  // rest of the case payload
}

Once the dry-run case completes and all your systems behave as expected, submit real cases with isTest unset (or false).

tip

Let your Debitura account manager know before you send the dry-run case so someone on our side can watch webhook delivery and case creation alongside you during your first production call.

Pre-flight checklist​

Verify every integration requirement before switching to production.

Prerequisites​

  • Partnership agreement signed and API credentials received for both test and production
  • White-label branding configured — verify via GET /me that logoUrl and backgroundColorCode are correct
  • Production URLs configured — not pointing at test environment

Authentication​

  • Bearer tokens minted via POST /oauth/token per externalTenantId, cached per client, re-minted only on 401 — never hardcoded or shared across clients
  • Retry-on-401 pattern implemented — re-mint once, treat second 401 as invalid client link. See Token Expiry Handling.

Client Onboarding​

  • All POST /clients response codes handled — 201, 202, and all 409 variants (ClientExistsNeedsLinking, ClientAlreadyLinkedToAnotherPartner, InvalidClientType). See Handling 409 Conflicts.
  • Onboarding URL delivered to the client — Debitura does not send onboarding emails. You must present the URL. See White-Label UI.
  • Return URL appended to onboarding and signing URLs, URL-encoded if it contains query parameters
  • externalTenantId stored durably — all future operations reference this ID
  • Onboarding completion confirmed before case submission — via client.onboarding.contract_signed webhook or polling GET /clients/{externalTenantId} for onboardingDone: true
  • Link request expiry handled — 409 approval URLs expire after a configurable per-partner TTL (ApprovalTtlDays, default 7 days, clamped 1–30 days). Subscribe to client.link_expired to detect expiry; resubmit POST /clients with the same externalTenantId to generate a fresh approval URL.

Case Submission​

  • Required fields validated — currencyCode, date, amountToRecover, debtor.type, debtor.name, debtor.address, debtor.city, debtor.countryAlpha2. US debtors also require debtor.stateAlpha2. (dueDate is optional.)
  • creditorReference unique per creditor — duplicates return 422. Use this as your idempotency key.
  • isTest flag not set on production submissions — test cases are never actioned by collection partners and produce no errors
  • Revenue attribution understood — automatic when using a bearer token. Direct XApiKey submissions are not attributed. See Attribution.

Error Handling​

  • 422 MissingDebtCollectionContract — catch and present solutionUrl for SDCA signing, then retry
  • 422 MissingPowerOfAttorney — catch and present solutionUrl for PoA/JPA signing, then retry. This also covers jurisdiction carveouts.
  • 422 MissingKycVerification — catch and present solutionUrl for the KYC form. Not bypassed by allowPendingContracts. See KYC Verification.
  • 422 NoPartnerAvailable — show "jurisdiction not supported" message. Do not auto-retry.
  • 422 CreditorBlocked — surface to support. Auto-retry will never resolve this.
  • Return URL on all solutionUrl redirects — without it, clients complete signing with no way back to your platform
  • 429 rate limit — read retryAfter from response and wait. Limits: 2,000/min, 20,000/hr, 100,000/day per API key.

See the Error Reference for the full list of errors across both APIs.

Webhooks​

  • HTTPS endpoint registered — HTTP, localhost, and private IPs are rejected. Only ports 443 and 8443 are allowed.
  • Production signing secret saved at subscription creation — it is never returned again and differs from your test secret. See Webhooks.
  • HMAC-SHA256 verification uses the raw request body (not re-serialized JSON) with the secret Base64-decoded. See Signature Verification.
  • Timestamp validation — reject events older than 5 minutes to prevent replay attacks
  • 10-second response time — acknowledge immediately, process asynchronously. 8 consecutive failures auto-disable the subscription.
  • Idempotency — deduplicate using event.id. Debitura uses at-least-once delivery. See Best Practices.
  • All required events subscribed — at minimum: client.onboarding.contract_signed, client.linked, client.link_requested, client.link_expired, case.created, case.updated, case.closed

KYC Readiness​

  • POST /cases/preview called before submission to detect KYC requirements proactively. The Referral Partner preview returns isEligible, ineligibilityReason, jurisdiction, pricingPreview, and requiresKycVerification — inspect requiresKycVerification to drive your KYC flow. (Unlike the Customer API preview, the Referral Partner preview does not return requiredActions.)
  • KYC tested with bearer tokens — direct XApiKey calls skip KYC checks entirely, so testing with XApiKey will not exercise your KYC flow

End-to-End Validation​

Run these flows in the test environment before switching to production:

  • New client onboarding — POST /clients → present URL → client completes SDCA signing → webhook fires → mint token → submit case
  • Existing client linking (409) — POST /clients with known email → present approval URL → client approves → webhook fires → retry
  • Case with missing PoA — submit case to a PoA-required jurisdiction → get 422 → present signing URL → sign → retry → case created
  • KYC flow — submit case to a KYC-required partner → get 422 → present KYC form → complete → retry → case created
  • Webhook signature verification — use POST /v1/webhooks/test to fire all event types and confirm your handler accepts them

:::tip Clean test state Use DELETE /clients/{externalTenantId} to reset test clients between test runs (test environment only). :::