Qiwi Api Laravel Package

Technical Evaluation

Architecture fit. jeka/qiwi-api is a thin HTTP client around the QIWI Wallet API, not a payment platform. It maps to a narrow slice of the checkout domain — invoice creation keyed by a caller-supplied bill_id, payment status lookup, and balance/account reads. It fits a Laravel monorail or a Laravel-based payment service as a convenience wrapper that replaces hand-rolled Guzzle calls, but only if QIWI is already an approved rail and the codebase is Laravel-native. It is the wrong layer to use as a multi-provider payment abstraction: if QIWI is one rail among several, the package should sit behind an internal provider contract, not in controllers or domain services. Scope gap to flag early: the package covers a subset of what a production integration needs — refunds/payouts, webhook verification, idempotency, and retry/timeout policy appear to be on us, not on the package.

Integration feasibility. Composer install plus credential configuration. The real cost is commercial and provider-side: QIWI merchant/contract onboarding, token or site_id/secret provisioning, IP whitelisting, and confirming the QIWI Wallet endpoints this package targets are still contractually live for us. The package is small enough that a fork-and-own path is realistic. Feasibility is therefore "technically easy, commercially gated" — and the gate is compliance, not code.

Technical risk.

• Community validation (high). 16 stars, zero dependents, score 0.14, single-maintainer profile. Treat as effectively unmaintained; assume we own the code after adoption.
• Documentation/discovery mismatch (medium). The package description claims "framework-friendly Laravel integration," but the Laravel assessment indicates there is no service provider, facade, or publishable config — it's a plain PHP SDK you wire up yourself. Budget for that wiring; do not promise stakeholders a drop-in Laravel integration.
• Framework compatibility (medium-high). Version constraints in composer.json may not support current Laravel/PHP releases. Verify illuminate/support ranges and PHP 8.x parity before committing engineering time.
• Provider viability (high). QIWI's regulatory and operational standing has been unstable; API availability, sanctions exposure, and jurisdiction legality must be confirmed by legal/compliance before any spend. This is the single largest risk and belongs to the TPM to sequence first.
• Security (medium). Token handling, request logging, and TLS verification need review; small packages frequently under-handle secret redaction.
• Behavioral assumptions (medium). Status reconciliation is poll-based — webhooks are not reliably pushed for all QIWI account types. Any roadmap that assumes webhook-driven state should be corrected now.

Key questions.

1. Is QIWI a required rail for our user base, and is it legally and operationally usable in our operating jurisdictions today?
2. Which Laravel and PHP versions does the package declare, and does it pass against our target versions?
3. What license governs the package, and are we permitted to fork and redistribute internally?
4. Does the package cover the full surface we need (invoice create, status, refunds/payouts, webhook verification), or only a subset?
5. Are idempotency, retry, timeout, and logging behavior provided, or entirely on us?
6. Who is the named internal owner of the fork, and what is the review/upgrade cadence?
7. Which QIWI merchant tier do we qualify for, and does that tier support webhooks or require poll-only reconciliation?

Integration Approach

Stack fit. Good fit for Laravel 8–10-era PHP with a service-container convention and QIWI already approved. Poor fit on a modern Laravel release (unverified constraints), in a DDD/hexagonal codebase where facade-style access leaks provider specifics, or where multi-provider routing is a near-term requirement. In those cases, use the package as a reference implementation and call QIWI through Laravel's HTTP client inside our own adapter.

Migration path. Do not call the client from controllers or domain services. Introduce an internal PaymentProvider contract (create, fetch status, refund, verify webhook, reconcile) with a QiwiProvider adapter that uses the package or a vendored fork. This confines the dependency to one seam and turns a future provider swap into a single-class change. If upstream is inactive — which is the working assumption — vendor the fork under our namespace, pin the commit, and record provenance and license in the repo.

Compatibility. Validate composer.json constraints against our PHP and Laravel versions first; this is the cheapest kill-switch. Check for abandoned transitive dependencies, run static analysis and a secret-handling review on the fork, and confirm the QIWI API version the package targets still matches QIWI's current docs — a stale endpoint version is the most likely silent failure.

Sequencing.

1. Compliance/legal gate. Confirm QIWI availability and sanctions/jurisdiction position. Do not spend engineering hours before this clears.
2. Compatibility and security review of the package against our stack — this is the go/no-go on using it vs. a raw HTTP client.
3. Sandbox POC. One invoice create with a persisted bill_id, one status poll, one reconciliation cycle. Validate read-only operations (balance, recent payments, IP whitelist) before moving money.
4. Wrap behind the PaymentProvider contract. Add idempotency keys, timeouts, retries with backoff, structured logging with redaction, and a circuit breaker.
5. Reconciliation job and (if the merchant tier supports it) webhook verification — always re-fetch authoritative status from the API rather than trusting the payload.
6. Production rollout behind a feature flag, with QIWI as a secondary/opt-in rail and a manual fallback documented.

Operational Impact

Maintenance. Assume we own it. Budget a small but real ongoing cost: dependency bumps on each Laravel/PHP upgrade, endpoint drift against QIWI docs, secret-handling review, and periodic sandbox regression against QIWI API changes. The fork is cheap to maintain; the failure mode is that nobody notices it has broken until a customer's payment fails.

Support. Community support is negligible at 16 stars and zero dependents — no Stack Overflow corpus, no issue-tracker momentum, no expected upstream responsiveness. Escalation is internal engineering plus QIWI's own merchant support. Plan for one named owner, a documented runbook, and a defined on-call path; otherwise the first incident is also the first time anyone reads the code.

Scaling. As a thin HTTP client, throughput is bounded by QIWI's rate limits, not by our code. Scaling work lives in our layer: queue-based invoice submission, backoff on 429/5xx, idempotent retries keyed on bill_id, and asynchronous reconciliation rather than synchronous polling in the request path. Treat QIWI as a flaky external dependency with a circuit breaker and a documented degraded mode.

Failure modes. Each needs an explicit detection signal, not reliance on the package:

• Provider API deprecation or endpoint removal — silent breakage; alert on error-rate and reconciliation delta.
• Token expiry or credential rotation not handled by the wrapper — alert on 401/403 spikes.
• Webhook loss or duplication without idempotency — reconcile from authoritative status; alert on webhook lag.
• Partial failures on refunds/payouts leaving ledger inconsistency — reconciliation job with a manual review queue.
• Framework upgrade breaking the wiring (no matter who wrote the service provider) — regression tests in CI against target Laravel/PHP versions.
• Jurisdictional or sanctions-driven cutoff of the provider mid-operation — a documented fallback to alternative rails and a customer-comms playbook.

Ramp-up. The code surface is small; a mid-level Laravel developer can be productive in one to two days. The expensive ramp is domain knowledge — QIWI status semantics, settlement timing, bill_id idempotency behavior, and reconciliation quirks — which takes weeks and must be captured in the adapter's tests and runbook, not in tribal knowledge. Plan for a TPM-owned risk register entry: this dependency should be reviewed at every major Laravel upgrade and at any QIWI policy change.