Php Sdk V2 Laravel Package

Product Decisions This Supports

• Build vs. Buy: Still Buy. v5.1.0 reinforces the case: Mangopay is actively evolving the SDK (new endpoints, entities, enums, and events shipped in a minor release), so we inherit new payment capabilities without writing API wrappers ourselves.
• Payment Method Expansion (PayPal): Extended preauthorizations ship with first-class PayPal support (CreatePayPalExtendedPreauthorization(), PayPalExtendedPreauthorization, and polymorphic returns from Get()/Update()/GetAllForUser()). This is a new payment-method decision we can now make cheaply — supporting PayPal preauthorized payments may improve conversion for consumer-facing flows without a separate integration.
• Roadmap Sequencing / Avoid Deprecated Surfaces: Deposits are now deprecated in favor of extended preauthorizations, with removal planned in a future major. This changes how we build, not whether we build:
  • Do now: Build all new preauthorization/deposit-like flows on ApiExtendedPreauthorizations ($api->ExtendedPreauthorizations), ExtendedPreauthorizationStatus, and Transaction::$ExtendedPreauthorizationId.
  • Do not: Start new work on ApiDeposits, DepositStatus, Transaction::$DepositId, or CreatePayInDepositPreauthorizedWithoutComplement().
  • Backlog item: If/when we have existing deposit-based flows or stored DepositId mappings, schedule a migration to the extended equivalents (low effort — the new API mirrors deposits) as technical debt before the next major upgrade.
• Finance Ops & Reconciliation Features: New settlement event types (SETTLEMENT_CREATED, SETTLEMENT_RECONCILED, SETTLEMENT_PARTIALLY_MATCHED, SETTLEMENT_UNMATCHED, SETTLEMENT_INSUFFICIENT_FUNDS, SETTLEMENT_FAILED, etc.) unlock webhook-driven reconciliation dashboards and exception alerts for marketplaces and payout-heavy products — a candidate Phase 2/3 roadmap item that previously would have required custom polling.
• Compliance & SCA: ProfilingAttemptReference on UserNaturalSca/UserLegalSca supports SCA/KYC profiling flows, giving us more control over 3DS/SCA success rates and auditability in EU-regulated onboarding — a conversion and compliance lever.
• Roadmap Prioritization (revised):
  • Phase 1: Core flows on the new surfaces — user onboarding (incl. SCA users with ProfilingAttemptReference), bank account linking, and extended-preauthorization-based payment flows.
  • Phase 2: PayPal extended preauthorizations (new payment method) and settlement-event-driven reconciliation reporting.
  • Phase 3: Payout optimization and high-volume transaction tuning; consume the extended-preauthorization event types (EXTENDED_PREAUTHORIZATION_PAYMENT_VALIDATED, ..._EXPIRED, ..._CANCELED) for lifecycle automation.
• Use Cases: Unchanged in shape — fintech wallets, marketplace seller payouts with disputes, SaaS subscription billing, regulated/PSD2 services — but now with stronger reconciliation and a second payment rail (PayPal) to justify the platform choice.

When to Consider This Package

Adopt This Package If:

• Your product requires PCI-compliant payment processing but lacks in-house fintech expertise.
• You’re building a multi-currency wallet, payout system, or user-funded platform (gig economy, crowdfunding, marketplaces).
• You need fast integration with Mangopay’s API (core flows in weeks) without managing OAuth/mTLS manually.
• Your stack is PHP/Laravel, and you want to avoid REST boilerplate (serialization, retries, pagination, error parsing).
• You need mTLS support for regulated environments (EU/PSD2).
• You need preauthorized payments with PayPal as an option, or settlement-level reconciliation events for finance operations.
• You’re targeting European markets where Mangopay has strong local banking partnerships.

Look Elsewhere If:

• You’re not using PHP/Laravel (use Mangopay’s Node.js, Python, or Java SDKs instead).
• Your use case is highly custom (e.g., real-time fraud scoring) and Mangopay’s API lacks flexibility.
• You need multi-provider orchestration (e.g., Stripe + Adyen + Mangopay side by side) — this SDK is single-provider by design.
• Your team lacks PHP experience and prefers a more abstracted service (e.g., Stripe’s PHP library).
• You’re building a crypto-native product where Mangopay’s fiat focus is misaligned.
• You cannot tolerate a deprecation cycle: if deposits are core to your design and you’re unwilling to track the extended-preauthorization migration and a future major upgrade, budget for that effort explicitly — otherwise this is not a blocker, just a plan item.

How to Pitch It (Stakeholders)

For Executives:

"This SDK lets us launch payment features in weeks, not months, on Mangopay’s PCI-compliant infrastructure — and the vendor is actively shipping new capability, which de-risks our buy decision.

What v5.1.0 changes for us:

• New revenue lever: Native PayPal extended preauthorizations let us add a second payment rail without a second integration — a direct conversion/coverage play for consumer flows.
• Finance-grade operations: New settlement event types let us automate reconciliation, flag unmatched or insufficient-funds settlements, and cut manual finance work — turning a back-office cost into a differentiator.
• Lower compliance friction: SCA profiling support on users helps us improve EU payment success rates while staying audit-ready.
• No rework if we move now: The prior deposits API is deprecated in favor of extended preauthorizations. We should build new flows on the new API from day one, avoiding a migration later. The old and new APIs mirror each other, so the switching cost is low but non-zero — sequencing matters.
• Cost/risk: These are additive changes in a minor release (non-breaking today), with deprecations signposted for a future major. The main planning item is version pinning and a scheduled upgrade path.

Ask: "Should we prioritize PayPal extended preauthorizations for [Phase 2] and fund a small reconciliation dashboard off the new settlement events to hit [revenue/margin goal]?"

For Engineering:

"Drop-in PHP SDK for Mangopay’s API — OAuth/mTLS, retries, pagination, and error parsing are handled. v5.1.0 additions change our implementation choices:

• Use extended preauthorizations, not deposits. ApiExtendedPreauthorizations ($api->ExtendedPreauthorizations) mirrors the deposits API with Create(), CreatePayPalExtendedPreauthorization(), Get(), Update(), GetAllForUser(), GetAllForCard(), and GetTransactions(), backed by /extended-preauthorizations. Deposits (ApiDeposits), DepositStatus, Transaction::$DepositId, and CreatePayInDepositPreauthorizedWithoutComplement() are deprecated and slated for removal in a future major.
• Polymorphic returns to handle: Get(), Update(), and GetAllForUser() return PayPalExtendedPreauthorization when created via PayPal, otherwise ExtendedPreauthorization. Type-check before persisting; don’t assume a single concrete class.
• Data model change: Transaction::$ExtendedPreauthorizationId replaces $DepositId. Any schema, DTO, or mapping keyed on DepositId must migrate.
• New PayIn path: ApiPayIns::CreatePayInExtendedPreauthorized(CreatePreAuthorizedExtendedPayIn $payIn) → POST /payins/extended-preauthorized/direct/full-capture. Note it’s full-capture — partial/complementary capture semantics should be validated against our product requirements before committing.
• Webhooks: add handling for EXTENDED_PREAUTHORIZATION_* and SETTLEMENT_* EventType constants. Settlement events are a good fit for an idempotent reconciliation consumer.
• SCA: optional ProfilingAttemptReference on UserNaturalSca/UserLegalSca — thread through onboarding if we use profiling.

Key trade-offs:

• Pros: Fast iteration, compliance-ready, mTLS, active upstream maintenance, additive minor release, PayPal support out of the box.
• Cons: PHP-only; small community; deprecation cycle means we must track the deposits→extended-preauthorization migration and pin mangopay/php-sdk-v2 to a tested patch/minor range.

Recommendation: Build all new payment flows on extended preauthorizations, add settlement-event reconciliation to the backlog, and schedule a DepositId → ExtendedPreauthorizationId sweep if any deposit surfaces exist. Re-evaluate alternatives only for niche needs outside Mangopay’s scope."

Ask: "Should we allocate [X dev weeks] to integrate extended preauthorizations + settlement reconciliation for [specific feature], and lock the SDK version to 5.1.x?"