Xendivel Laravel Package

Product Decisions This Supports

• Go/no-go on QR Ph (QRPH) checkout. v3.2.0 turns "should we support QR payments?" from a scoping exercise into a config-and-ship decision. If your market is the Philippines, QR Ph is the BSP-mandated national QR standard, and the payer-side reach (banking apps + e-wallets in one scan) is broad enough that this is usually a parity feature rather than a differentiator — which argues for shipping it quickly and cheaply, not building it bespoke.
• Roadmap sequencing for payment method coverage. The package now spans card, e-wallet, OTC, and QR behind one facade (Xendivel::createQrCode, getQrCode, simulateQrPayment mirroring the existing payment verbs). Each additional method is incremental, so "add method X next quarter" becomes a smaller, more predictable line item — useful when negotiating scope with stakeholders who expect per-method timelines.
• Build vs. buy on payments integration. The release quietly makes the buy case stronger: unified Payments API usage (no separate channel activation), publishable event/listener stubs, per-type test suites, and runnable demo templates in three frontend flavors. The remaining in-house justification narrows to control over retry/ledger semantics or multi-PSP abstraction — not "we can't get QR working fast enough."
• Static vs. dynamic QR as a product choice, not a technical one. DYNAMIC → ONE_TIME_USE (fixed amount) and STATIC → MULTIPLE_USE (payer enters amount) map directly to two distinct merchant experiences: fixed-price checkout vs. countertop/printed QR for in-person or variable-amount collection. Decide per surface — a fixed-amount dynamic QR in an online cart removes a payer error mode; a static QR on a printed standee is a different product.
• UX decision on payment confirmation. Asynchronous webhook confirmation (status flips PENDING → SUCCEEDED) forces an explicit choice: optimistic "waiting for payment" screen with polling, or redirect-and-notify. The bundled demo (generate → render → poll → simulate) is a usable reference for the first pattern and a reasonable basis for a design review.
• QA and launch-readiness investment. simulateQrPayment accepting either a QR reference or a pr-… id, plus demo-route and webhook auth-guard tests, lowers the cost of end-to-end rehearsal in test mode — relevant when you're deciding whether to gate launch on a manual payments test pass.

When to Consider This Package

Adopt when:

• You're on Laravel/PHP and already (or intend to) use Xendit as your PSP — this is a thin, opinionated wrapper, not a PSP abstraction layer.
• Your customers pay in PHP/QRPH and you need bank-app and e-wallet coverage from a single scannable code. QR Ph interoperability is the main reason to prefer this over a wallet-specific QR integration.
• You want a working reference implementation fast. The Blade/JSX/TSX checkout templates plus the QR tab give you something demoable in days, which matters for stakeholder buy-in and for validating flows before committing design resources.
• You're comfortable with the webhook pattern the package assumes: publish the event/listener stubs, register the listener, point a Xendit payment.succeeded callback at qr_webhook_url. The default /xendit/* CSRF exclusion already covers the path.
• Your team is small enough that per-method test suites and facade symmetry (create/get/simulate) meaningfully reduce maintenance overhead.

Look elsewhere or build when:

• You need multi-PSP routing or failover. This is Xendit-coupled by design; a PSP-agnostic layer (or a gateway abstraction you own) is the better long-term bet if you expect to add or swap providers.
• Recurring/subscription billing is on the roadmap. Nothing in this release addresses mandates, tokenization, or scheduled charges — don't infer capability from "Payments API" branding.
• You need reconciliation-grade primitives. The package surfaces status polling and webhooks; it does not give you a ledger, idempotency guarantees across your own writes, or settlement reporting. Plan to own that.
• You're outside PHP/Laravel, or you're running a non-standard Laravel setup where republishing config with --force would clobber customized templates. The upgrade path is vendor:publish --tag=xendivel --force — treat that flag as destructive and diff before applying.
• Compliance/audit requirements demand you control the payment request lifecycle and webhook verification end to end rather than delegating to a convenience wrapper.
• High-volume, latency-sensitive checkout. A facade-based synchronous create-then-poll flow is workable but you should validate it against your p95 targets before committing; the demo is a reference, not a performance proof.

How to Pitch It (Stakeholders)

For executives (one paragraph): The payment package now supports QR Ph, the Philippine national QR standard, so customers can scan one code with any participating banking or e-wallet app and pay. That's the cheapest route to covering the long tail of wallets and banks we can't integrate individually, and because it runs on Xendit's default payments API there's no new channel activation or procurement cycle — the work is configuration and a webhook hookup, not a new vendor. It arrives with a working demo, automated tests, and a documented upgrade path. Realistic framing: this is market-parity capability delivered at low marginal cost, not a differentiator — the value is closing a coverage gap and reducing checkout abandonment for customers who don't use cards.

For engineering (what the upgrade actually costs):

• Republish config and assets to pick up qr_webhook_url, qr_channel_code (default QRPH), qr_currency (default PHP), the event/listener stubs, and updated checkout templates. Note the --force flag overwrites — diff and re-apply any local template customizations, and React users must rebuild assets and re-add the publishable key.
• Register QrPaymentEvents::class => [QrPaymentWebhookListener::class] in EventServiceProvider.
• Add a Payment (payment.succeeded) callback in the Xendit dashboard pointing at qr_webhook_url (default /xendit/qr/webhook); CSRF exclusion is already handled.
• Interface surface is additive and consistent with existing verbs — no breaking changes to card, e-wallet, or OTC calls. The one behavioral change is UI-side: checkout templates were restructured so each tab shows only its own fields (fixing field leakage across tabs) — expect snapshot/test churn if you forked those templates.
• Tests were split per payment type; if you extended the old monolithic payment test file, migrate those cases.
• Channel and currency are overridable per request, so multi-currency or non-QRPH experiments don't require a config change — useful for a staged rollout behind a flag.