Knet Laravel Package

Product Decisions This Supports

• Market entry into Kuwait (or GCC expansion sequencing). KNET is the dominant domestic debit/payment rail in Kuwait; if KNET is not supported, the product is effectively unlaunchable for Kuwaiti customers. This package turns "can we sell in Kuwait?" from an integration project into a config-and-controller task, which materially changes the launch-date estimate and the cost of testing the market.
• Build vs. buy on payment plumbing. The alternative is building the K-064 RAW protocol integration in-house: AES-128-CBC payload encryption, tranportal credential handling, callback decryption, action codes (1 = purchase, 2 = refund, 8 = inquiry), and reconciliation state. This package already encodes that protocol, so the buy decision is defensible on engineering time alone — the ROI question is maintainer risk, not capability.
• Pricing and catalog decisions that depend on KWD mechanics. Amounts must be expressed to three decimal places (KWD has 3 minor units), and currency 414 is hard-coded into the flow. That constrains how you model prices, rounding, and minimum order value (min 0.001 KWD). PMs should confirm the pricing model handles 3-decimal currency before committing to tiered plans or per-unit metering.
• Checkout conversion roadmap: KFAST. KFAST (faster checkout, 8-digit customer token) is the highest-leverage product feature here — returning-customer checkout without re-entering card details is the standard conversion lever in the Kuwait market. The package exposes payWithKfast() and an overridable kfastToken() strategy, so the product decision is: do we invest in a stable customer-token identity (e.g., mapping to customer_number rather than user ID) and negotiate KFAST enablement with the acquirer? This is a roadmap item, not an engineering blocker — but KFAST must be enabled on the terminal by the bank, which is a business-development dependency with lead time.
• Post-purchase experience: refunds and support tooling. Full and partial refunds are first-class, with validation (must be captured, not already refunded, amount > 0, amount ≤ original) and a separate linked refund transaction record (action = 2, original_transaction_id). This makes a meaningful difference to support cost and to whether you can offer a self-serve refund policy in the T&Cs rather than a manual, bank-mediated process.
• Order state machine and fulfillment design. The package's event surface (KnetPaymentSucceeded, KnetPaymentFailed, KnetRefundSucceeded/Failed, KnetTransactionCreated/Updated, KnetResponseReceived/Handled) is the integration seam. The PM decision is what "paid" means in the product: the redirect back to KNET_REDIRECT_URL is a UX signal, while the server-to-server POST to /knet/response is the source of truth. Fulfillment must key off the callback/event path, not the browser return — otherwise you ship a class of bugs where users see "failed" but are charged, or vice versa.
• Reconciliation and finance operations. inquireAndUpdateTransaction() and the PaymentStatus enum (with pending states: INITIATED, PENDING, UNKNOWN) support a scheduled reconciliation job. This determines whether finance can close the books daily and whether you need a human to eyeball a spreadsheet — a recurring operating cost that should be in the business case.
• Data model and reporting. UDF fields udf1–udf5 are the only clean way to carry your own identifiers (order ID, subscription ID, product SKU) through the gateway lifecycle. Deciding a UDF convention up front is a small decision with outsized impact on analytics, reconciliation, and dispute handling later.
• Multi-entity / multi-storefront roadmap. Credentials are single-terminal via env config (KNET_TRANSPORT_ID, KNET_TRANSPORT_PASSWORD, KNET_RESOURCE_KEY). If the roadmap includes multiple brands, regions, or merchant accounts, budget for config layering or per-tenant credential resolution — do not assume this is free.
• Scope containment for audit and compliance conversations. The redirect-based RAW flow means card data never touches your servers, so PCI scope stays in the lighter questionnaire territory. That should be stated explicitly in the security review rather than discovered late.

When to Consider This Package

Adopt when most of these hold:

• You are on Laravel/PHP and are already comfortable with the framework's package conventions (service providers, migrations, events, artisan commands).
• You have, or are close to having, a KNET merchant/terminal agreement with a tranportal ID, password, and resource key. The package validates configuration (knet:check) but cannot substitute for the acquirer relationship.
• You need a single KNET terminal and a single Kuwaiti Dinar price surface. That is the shape the package assumes.
• Your requirements are redirect-based checkout plus refunds and status inquiry. That is genuinely the whole of it — the package covers it with focused interfaces (CreatesPayments, InquiresPayments, RefundsPayments) that keep your controllers honest.
• You want speed to first transaction above abstraction purity. knet:install publishes config, runs migrations, and validates setup; the HasKnet trait gives you pay(), payWithKfast(), refund(), and a knetTransactions() relationship in one line on your User model.
• You can absorb vendor and maintainer risk. Stars (14) and a single-maintainer, MIT-licensed package mean no support SLA, no security response commitment, and no guarantee of a fix on your timeline. Mitigate with a fork-and-own posture, a pinned version, and an internal test suite against the gateway sandbox.

Look elsewhere, or plan to build, when:

• You need multi-gateway abstraction (KNET alongside Stripe, Checkout.com, Adyen, or a local processor) with a common payment interface. This package is deliberately KNET-specific; wrapping it behind your own port is possible but the abstraction is yours to design.
• You need tokenization beyond KFAST, stored-card-on-file semantics, or recurring/mandate billing. KFAST is a faster-checkout token, not a subscription primitive — do not let it get scoped as one.
• You need 3-D Secure variants, capture/void semantics separate from purchase, or partial-capture flows. The action surface here is purchase, refund, inquiry.
• You require multi-currency or non-KWD amounts. The 3-decimal amount assumption and currency 414 are baked into the request contract.
• You need multi-terminal or per-tenant credentials out of the box.
• Your compliance posture demands a vendored, supported SDK with contractual support. In that case, budget the fork explicitly rather than pretending it is a normal dependency.
• You are not on Laravel, or you are on an ancient Laravel version outside the package's tested range — verify against your framework version before it enters the plan.

How to Pitch It (Stakeholders)

For executives — one paragraph. KNET is the payment rail that decides whether we can sell in Kuwait at all. This package is a production-shaped Laravel integration for KNET covering checkout, faster checkout (KFAST), full and partial refunds, and transaction status inquiry, with card data never touching our infrastructure (redirect-based flow, so PCI exposure stays minimal). It replaces what would otherwise be a bespoke protocol implementation — AES-encrypted payloads, gateway action codes, callback decryption — with configuration, a trait, and events. It is MIT-licensed and free, which means the cost is not license fees but ownership: it is a small, single-maintainer package, so we should treat it as code we adopt and are prepared to own, pin the version, test against the KNET sandbox, and plan a fork if upstream goes quiet. The gating dependency is commercial, not technical: the acquirer must issue our tranportal credentials and enable KFAST on the terminal, and that lead time should drive the launch date, not engineering.

For engineering — the short version. Redirect-based RAW integration. knet:install publishes config, migrates the knet_transactions table, validates setup. Add HasKnet to your billable model and you get pay(), payWithKfast(), refund(), and a transactions relationship. Depend on the narrow contracts (CreatesPayments, InquiresPayments, RefundsPayments) rather than the concrete KnetPaymentService so your controllers stay testable. The callback is a signed, encrypted POST to /knet/response; middleware decrypts once and stashes the payload in request attributes, then KnetPaymentSucceeded / KnetPaymentFailed fire. Treat the server callback as the source of truth for fulfillment; the redirect to KNET_REDIRECT_URL is presentation only. Amounts are 3-decimal strings (KWD), track IDs are unique, and udf1–udf5 are our channel for order/subscription IDs — agree the convention before the first commit. Routes and migrations are both opt-out (Knet::ignoreRoutes(), Knet::ignoreMigrations()) if they collide with our conventions.

Risks to name in the same breath. Small community and single maintainer; no support contract; KNET-specific with no multi-gateway abstraction; single-terminal credentials from env; KFAST requires bank-side enablement. None of these are blockers for a first Kuwait launch — all of them are things we should be able to state we accepted deliberately rather than discovered in month three.