Laravel Sumsub Sdk Laravel Package

Technical Evaluation

Architecture fit shureban/laravel-sumsub-sdk is a domain-specific adapter around SumSub's KYC/AML API, not infrastructure. Architecturally it buys us three things a TPM should value: service-provider registration (one line in config/app.php), a publishable config with interface-to-class bindings (dependency inversion for testability and vendor swapping), and modeled request/response objects for SumSub payloads (applicant info, fixed info, company/beneficiary structures, review results, reject labels, webhook bodies). The SumSub surface it covers — applicants, documents, review status, webhook signature verification via payload digest — maps to the full verification lifecycle we'd otherwise hand-roll.

The real architectural decision it encodes is where SumSub state lives. This package is a transport + DTO layer; it does not give us persistence, state machines, retry semantics, or webhook idempotency. That's the right boundary for a vendor SDK, but it means the TPM owns the surrounding design: our own applicant/verification entities, a webhook ingestion endpoint with replay protection, and a reconciliation job against SumSub's API as source of truth. Treat the package as the seam, not the system.

A secondary architectural coupling: the package depends on shureban/laravel-object-mapper, a second package by the same single author, and the install docs require publishing its config too. That's a transitive dependency on an equally small, equally young library sitting in our request/response path. It also implies reflection- or attribute-driven hydration of SumSub payloads — convenient, but a debugging hazard when SumSub adds or renames fields.

Integration feasibility Feasible for a Laravel shop in days, not weeks. Composer install, provider registration, config publish, credentials in env, then wrap calls behind our own service interface. The v2 line added per-jurisdiction API keys and secret keys (v2.0.2, v2.2.0), which matters if we onboard users across regions — a genuinely useful capability that removes the need for us to fork.

Blockers to a clean estimate:

• No usage documentation. The README has an empty ## Usage section. There are no code examples of creating an applicant, generating an SDK access token, or handling a webhook. Onboarding cost is therefore "read the source and the SumSub public API docs side by side," not "follow the guide."
• API surface is inferred from git history. Reject labels, document subtypes, statuses, and payload fields arrived as dozens of small releases. The true v2 contract is only discoverable by reading src/.
• Webhook signature verification exists (payload digest checker) but is undocumented; we should verify it against SumSub's HMAC scheme ourselves before trusting it in a security-relevant path.

Technical risk Ranked for a TPM audience:

1. Bus factor of one (high). 1 star, 0 dependents, essentially a single maintainer with occasional drive-by contributors (makeale, AlexeyHrynko). No evidence of a support commitment, security policy, or response SLA. If the author stops, we own the fork.
2. Compliance-critical domain (high). KYC/AML is regulated. Bugs are not cosmetic — a mislabeled reject reason, a dropped webhook, or a mis-parsed review status can gate a customer out of a financial product or leave us non-compliant. A package whose changelog is dominated by "add reject label" and "fix null fields" tells us the domain model is still being discovered in production.
3. Version history volatility (medium-high). 0.0.1→0.0.33 in rapid succession, then a 1.0.0, then a full 2.0.0 rewrite eleven days later. That's a young library that has already broken its own API once. Semver discipline in the 0.x era was effectively absent.
4. Thin test/CI signal (medium). Not evidenced in the provided material; no badge, no coverage, no static analysis claim in the README.
5. Transitive mapper dependency (medium). Doubles the untrusted-code surface and the pinning burden.
6. Laravel-version chasing as the release driver (low-medium). v2.3.1 exists solely for Laravel 13 support. Good for longevity; also means the package's roadmap is externally dictated by framework churn.

Key questions

• Which SumSub endpoints and webhook types do we actually need, and does the src/ tree cover 100% of them — or will we be extending vendor code?
• Is the PayloadDigest verifier constant-time and correct against SumSub's current signing spec?
• Does the package retry, or does every network blip become our exception? (Assume ours.)
• What is our exit plan — a thin SumsubClient interface we control, so the package can be replaced by a direct Guzzle/cURL client in a day?
• Who is the named internal owner of this dependency, and what is the patch-SLA for a CVE in it or in laravel-object-mapper?
• Does the author respond to issues/PRs within a window we can tolerate for a compliance-adjacent dependency?

Integration Approach

Stack fit Strong if we are on Laravel 10–13 and PHP 8.1+. The service-provider + config-publish idiom is exactly what a Laravel team expects, and interface bindings in config let us swap the HTTP client, the mapper, or the whole client for a fake in tests. If we are on Lumen, Symfony, or a non-Laravel service, the package's value evaporates — the SumSub REST API is plain HTTP and we'd skip the wrapper.

Migration path If we already call SumSub directly (Guzzle + hand-parsed JSON), migrate seam-by-seam, not big-bang:

1. Install the package alongside existing code; publish config; wire credentials from our secret store, not .env committed to a repo.
2. Introduce our own KycProvider interface in the app. Implement it once with the legacy client, once with the SDK. Bind via config/env.
3. Move read paths first (fetch applicant, get review status, fetch documents) — these are low-risk and where DTO hydration saves the most code.
4. Move write paths (create applicant, upload document, reset applicant) second, behind a feature flag, per-endpoint.
5. Move webhook ingestion last and separately — it's the highest-blast-radius path and needs its own idempotency and signature tests regardless of which client sends the bytes.
6. Delete the legacy client only after a full verification cycle has passed through the SDK in production.

Compatibility

• Pin to a caret range but pin tightly: ^2.3 with a committed composer.lock, not ^2.0. Never let a CI job resolve a new 2.x minor without review.
• Track Laravel upgrade windows explicitly. v2.3.1 was cut for Laravel 13; if we're on 11/12, we may be able to stay on 2.2.x and skip risk — confirm the 2.3.0 diff first.
• The laravel-object-mapper peer requirement must be pinned in the same lockfile review. Two version constraints, one decision.
• Verify PHP version floor and any ext-* requirements before committing to a base image.

Sequencing (suggested 4–6 week envelope for one backend engineer, part-time)

• Week 1 — diligence: read src/ end to end, diff v2.2.6→v2.3.1, confirm endpoint coverage against our SumSub contract, run the signature verifier against SumSub's spec, write the exit-plan abstraction.
• Week 2 — scaffold: provider registration, config, secret management, KycProvider interface + fake, first read-path call in staging with a sandbox SumSub token.
• Weeks 3–4 — writes + webhooks: applicant creation and document upload behind flags; webhook endpoint with signature verification, idempotency key, and dead-letter handling.
• Week 5 — failure drills: simulate SumSub 5xx, timeouts, duplicate webhooks, out-of-order webhooks, and an applicant that never reaches a terminal status.
• Week 6 — cutover: flag-on per endpoint, legacy path retained for one release cycle, runbook published.

Operational Impact

Maintenance Ongoing cost is dominated by SumSub's API evolution, not ours. Every new document subtype, reject label, or applicant field either arrives via an upstream release (upgrade + regression test) or requires us to patch vendor code (fork + divergence). Budget a recurring line item: one dependency-review pass per quarter plus an unplanned pass whenever a new verification flow ships. The single-maintainer profile means the review pass must include "is this package still alive?" — a cheap check that no dependency bot will do for us.

Support No vendor, no SLA, no security policy visible. Internally this means the package cannot be a blind dependency: we need a named owner, a fork in our namespace ready to go, and the KycProvider abstraction in place so a fork is a configuration change rather than a refactor. Escalation path is "open a PR upstream, ship from our fork same day."

Scaling The package is not the bottleneck. SumSub's rate limits, per-applicant webhook volume, and our own webhook throughput are. Two concrete concerns:

• Verbatim/level-by-level DTO hydration on large applicant or company payloads adds CPU per request; measure before assuming it's free at volume.
• Webhook endpoints must be horizontally scalable and idempotent — SumSub retries, and a package-level DTO layer does nothing to prevent double-processing. That's our queue and our dedupe key.

Failure modes

• Unhandled SumSub error shapes → the SDK throws an unmapped or generic exception; our controller returns 500 to a user mid-verification. Mitigate with a catch-all at the KycProvider boundary and a typed app-level exception.
• Null-field drift (the repeated fix null fields / fix null company info releases) → a nullable DTO property blows up a consumer that assumed non-null. Mitigate with defensive accessors and contract tests against recorded SumSub fixtures.
• Webhook signature verification defect or drift → either rejected legitimate events (users stuck pending) or accepted forged ones (compliance exposure). Mitigate with a verifier we've independently tested plus a canary event.
• Dependency abandonment or a compromised shureban/laravel-object-mapper → supply-chain risk in a KYC path. Mitigate with lockfile pinning, composer audit in CI, and an allowlist of new Composer packages.
• Framework upgrade collision → Laravel 14 lands, the SDK lags, and we're blocked. Mitigate by keeping the abstraction boundary thin enough that the fork path is one sprint, not one quarter.
• Applicant state divergence → webhook lost, our DB and SumSub disagree. Mitigate with a scheduled reconciliation job that reads review status from the API and repairs local state.

Ramp-up Realistic for one mid/senior Laravel engineer: 2–3 days to first successful sandbox applicant, 1–1.5 weeks to confident, flag-gated production use, contingent on reading src/ because the README's Usage section is empty. Add a half-day for a second engineer to review the webhook/signature path. Because there is no documentation to hand over, capture what we learn as an internal ADR plus a runbook — otherwise the bus factor is one inside our org as well as in the repo.

Net TPM read: adopt with guardrails, not by default. The package substitutes for maybe 300–600 lines of hand-written HTTP plumbing in a compliance-critical path, at the cost of a single-maintainer, zero-adopter dependency plus a second such dependency. That trade is defensible only behind our own thin interface, with a pinned lockfile, an owner, and a fork we could ship today. If we cannot commit those four things, calling SumSub's REST API directly with Guzzle is the lower-risk call — the SDK's surface is small enough that we would not miss much.