Feature: Abstraction on Payments based on their operations
This commit is contained in:
@@ -0,0 +1,50 @@
|
||||
<?php
|
||||
|
||||
namespace Modules\Core\Payment\Contracts;
|
||||
|
||||
use Modules\Core\Payment\DTOs\PaymentResult;
|
||||
|
||||
/**
|
||||
* The async counterpart to SupportsPay::pay()/SupportsAuthorization::
|
||||
* authorize() — implemented only by a driver whose gateway can't resolve
|
||||
* one of those synchronously (a redirect the shopper completes elsewhere,
|
||||
* a webhook that arrives later). A driver whose pay()/authorize() always
|
||||
* returns a terminal PaymentResult (Succeeded/Failed) in the same call
|
||||
* never implements this — there is nothing left to call back.
|
||||
*
|
||||
* Resolves into the SAME events the original pay()/authorize() call would
|
||||
* have produced had it resolved synchronously — PaymentCaptured/
|
||||
* PaymentCaptureFailed for a pending pay(), PaymentAuthorized/
|
||||
* PaymentAuthorizationFailed for a pending authorize(). Which pair
|
||||
* applies is up to the driver to track (e.g. against whatever it stored
|
||||
* when the original call returned Pending), not something this method's
|
||||
* signature can express generically.
|
||||
*/
|
||||
interface HandlesPaymentCallback
|
||||
{
|
||||
/**
|
||||
* $reference is the gateway's own identifier for the pending attempt
|
||||
* (the same value the original pay()/authorize() call returned via
|
||||
* PaymentResult::$reference) — how the driver finds which attempt
|
||||
* this callback belongs to.
|
||||
*
|
||||
* $data carries whatever the callback/webhook payload contains
|
||||
* (Stripe: ['payment_intent' => $id], a redirect-based provider: its
|
||||
* query params or POST body) — passed explicitly by the caller rather
|
||||
* than the driver reaching into the global request(), so this works
|
||||
* the same whether it's called from a synchronous HTTP request or an
|
||||
* async webhook job with no active request at all.
|
||||
*
|
||||
* $context is opaque to the driver, carried through untouched into
|
||||
* whichever Payment event this callback produces — see SupportsPay::
|
||||
* pay()'s own $context param for the full reasoning. A driver that
|
||||
* needs the ORIGINAL context from the pay()/authorize() call (a
|
||||
* webhook's own payload carries none of its own) must have persisted
|
||||
* it itself when that call returned Pending — Payment provides no
|
||||
* storage for this.
|
||||
*
|
||||
* @param array<string, mixed> $data
|
||||
* @param array<string, mixed> $context
|
||||
*/
|
||||
public function handleCallback(string $reference, array $data, array $context = []): PaymentResult;
|
||||
}
|
||||
@@ -1,54 +0,0 @@
|
||||
<?php
|
||||
|
||||
namespace Modules\Core\Payment\Contracts;
|
||||
|
||||
use Modules\Core\Payment\DataTransferObjects\PaymentInitiation;
|
||||
|
||||
/**
|
||||
* The synchronous half of a payment driver — every driver implements this,
|
||||
* since every provider has some notion of "start a payment," even if (like
|
||||
* an offline/cash type) there's no real gateway round-trip involved.
|
||||
*
|
||||
* This is deliberately synchronous, unlike the rest of the payment
|
||||
* lifecycle: a storefront request needing a redirect URL, or frontend JS
|
||||
* needing a client secret to render an embedded payment form, has nothing
|
||||
* to redirect to or render until initiate() returns — there is no event
|
||||
* that can hand a mid-request controller a value it needs for its own HTTP
|
||||
* response. Everything after this point (the payment actually completing,
|
||||
* failing, a chargeback) is genuinely async and belongs on
|
||||
* HandlesPaymentCallback / PaymentSucceeded / PaymentFailed instead.
|
||||
*/
|
||||
interface InitiatesPayment
|
||||
{
|
||||
/**
|
||||
* Whether this driver can actually be used right now — e.g. checking
|
||||
* an API key is configured. Independent of
|
||||
* Modules\Core\Payment\Models\PaymentMethod::enabled (the admin
|
||||
* on/off toggle).
|
||||
*/
|
||||
public function isConfigured(): bool;
|
||||
|
||||
/**
|
||||
* $type is the payment type key being initiated (e.g.
|
||||
* 'cash-on-delivery', 'viva', 'stripe') — passed through even though
|
||||
* most drivers only ever serve one type, because a driver shared
|
||||
* across several types needs it to look up that type's own config.
|
||||
*
|
||||
* $data carries whatever the gateway needs to start this payment
|
||||
* (amount, currency, return/webhook URLs, customer details) — the
|
||||
* caller's responsibility to assemble, since a driver has no notion
|
||||
* of a cart or order to pull them from itself.
|
||||
*
|
||||
* $context is opaque to the driver (see PaymentDriver — actually
|
||||
* PaymentSucceeded's docblock — for the full reasoning): carried
|
||||
* through untouched into whatever PaymentSucceeded/PaymentFailed this
|
||||
* payment eventually produces, so the caller can correlate the result
|
||||
* back to whatever it needs (a cart id and fingerprint, for
|
||||
* Checkout), without this driver or Payment generally needing to know
|
||||
* what that is.
|
||||
*
|
||||
* @param array<string, mixed> $data
|
||||
* @param array<string, mixed> $context
|
||||
*/
|
||||
public function initiate(string $type, array $data, array $context = []): PaymentInitiation;
|
||||
}
|
||||
@@ -1,65 +0,0 @@
|
||||
<?php
|
||||
|
||||
namespace Modules\Core\Payment\Contracts;
|
||||
|
||||
use Lunar\Exceptions\FingerprintMismatchException;
|
||||
use Lunar\Exceptions\Carts\CartException;
|
||||
use Lunar\Models\Cart;
|
||||
|
||||
/**
|
||||
* A boboko-owned payment driver — wraps a payment gateway's own confirmation
|
||||
* mechanics (Stripe's synchronous authorize() call, a redirect-based
|
||||
* provider's async callback/webhook, anything else) behind one uniform
|
||||
* moment: "payment is confirmed."
|
||||
*
|
||||
* confirm() is the only thing a driver is required to do: once it has,
|
||||
* by whatever mechanism is native to that gateway, independently decided
|
||||
* the payment succeeded, it dispatches Modules\Core\Checkout\Events\
|
||||
* PaymentConfirmed — no driver ever calls CheckoutService::placeOrder() or
|
||||
* Lunar\Models\Cart::createOrder() directly. CheckoutService itself listens
|
||||
* for PaymentConfirmed and places the order from there; a driver that needs
|
||||
* to do something to the placed Order afterward (status mapping, syncing
|
||||
* gateway state) listens for the resulting OrderPlaced itself, matching it
|
||||
* via $order->meta['payment_method'] — see PaymentConfirmed's docblock for
|
||||
* why. This split is what makes an async/webhook-driven gateway (payment
|
||||
* confirmed in a request that has no synchronous caller waiting for an
|
||||
* Order at all) and a synchronous one (Stripe) work through the exact same
|
||||
* contract. See docs/checkout.md / docs/payments.md.
|
||||
*/
|
||||
interface PaymentDriver
|
||||
{
|
||||
/**
|
||||
* Whether this driver can actually be used right now — e.g. Stripe
|
||||
* checking its own API key is present, an offline-style driver always
|
||||
* returning true since it has no external dependency. Independent of
|
||||
* Modules\Core\Payment\Models\PaymentMethod::enabled (the admin
|
||||
* on/off toggle) — CheckoutService::getPaymentMethods() combines both:
|
||||
* a type is only offered to the storefront if it's administratively
|
||||
* enabled AND its driver reports itself configured.
|
||||
*/
|
||||
public function isConfigured(): bool;
|
||||
|
||||
/**
|
||||
* $type is the payment type key being confirmed (e.g. 'cash-in-hand',
|
||||
* 'cash-on-delivery', 'stripe') — passed through even though most
|
||||
* drivers only ever serve one type, because a driver shared across
|
||||
* several types (e.g. one "no real confirmation" offline driver behind
|
||||
* both cash-in-hand and cash-on-delivery) needs it to look up that
|
||||
* type's own config (e.g. its 'authorized' status) rather than another
|
||||
* type's.
|
||||
*
|
||||
* $data carries whatever the gateway needs to confirm this specific
|
||||
* payment (Stripe: ['payment_intent' => $id], a redirect-based
|
||||
* provider: its callback payload) — passed explicitly by the caller
|
||||
* (a controller, a webhook job) rather than a driver reaching into the
|
||||
* global request(), so confirm() works the same whether it's called
|
||||
* from a synchronous HTTP request or an async webhook/job with no
|
||||
* active request at all.
|
||||
*
|
||||
* @param array<string, mixed> $data
|
||||
*
|
||||
* @throws FingerprintMismatchException
|
||||
* @throws CartException
|
||||
*/
|
||||
public function confirm(Cart $cart, string $type, string $fingerprint, array $data): void;
|
||||
}
|
||||
@@ -0,0 +1,36 @@
|
||||
<?php
|
||||
|
||||
namespace Modules\Core\Payment\Contracts;
|
||||
|
||||
use Modules\Core\Payment\DTOs\PaymentResult;
|
||||
|
||||
/**
|
||||
* A driver's hold-only operation (Mastercard's "Authorize", Nexi's
|
||||
* ActionType::PREAUTH(), Stripe's capture_method=manual) — places a hold
|
||||
* on the customer's payment method without moving any funds. Only a
|
||||
* driver that also implements SupportsCaptures/SupportsVoids can do
|
||||
* anything with the resulting hold afterward; implementing this alone
|
||||
* with neither of those would leave the hold to simply expire
|
||||
* (typically ~7 days, gateway-dependent) with no way to settle or release
|
||||
* it early.
|
||||
*
|
||||
* A driver capable of both authorize-then-settle AND an atomic charge
|
||||
* (most card gateways) implements this alongside SupportsPay — which one
|
||||
* gets called for a given payment attempt is the CALLER's choice (a
|
||||
* policy decision), not something this driver decides for itself.
|
||||
*
|
||||
* Dispatches Modules\Core\Payment\Events\PaymentAuthorized or
|
||||
* PaymentAuthorizationFailed based on the returned PaymentResult's status,
|
||||
* unless $result->status is Pending — see SupportsPay's docblock for the
|
||||
* same async-resolution note.
|
||||
*/
|
||||
interface SupportsAuthorization
|
||||
{
|
||||
/**
|
||||
* Same $type/$data/$context reasoning as SupportsPay::pay().
|
||||
*
|
||||
* @param array<string, mixed> $data
|
||||
* @param array<string, mixed> $context
|
||||
*/
|
||||
public function authorize(string $type, array $data, array $context = []): PaymentResult;
|
||||
}
|
||||
@@ -2,22 +2,33 @@
|
||||
|
||||
namespace Modules\Core\Payment\Contracts;
|
||||
|
||||
use Lunar\Models\Order;
|
||||
use Modules\Core\Payment\DataTransferObjects\CaptureResult;
|
||||
use Modules\Core\Payment\DTOs\PaymentResult;
|
||||
|
||||
/**
|
||||
* Optional capability for payment drivers whose gateway supports a
|
||||
* separate authorize-then-capture step. Many redirect/wallet-style
|
||||
* gateways (Viva Wallet included, for most flows) charge in full at
|
||||
* checkout and never need this — SupportsRefunds is the one they're more
|
||||
* likely to implement instead.
|
||||
* Settles a PRIOR SupportsAuthorization::authorize() hold — only ever
|
||||
* valid against a reference that call (or a HandlesPaymentCallback
|
||||
* resolving it) produced, never called standalone. A driver with no
|
||||
* authorize-then-settle model at all (most redirect/wallet gateways, any
|
||||
* offline driver) never implements this — it settles everything through
|
||||
* SupportsPay::pay() in one step instead.
|
||||
*
|
||||
* Dispatches Modules\Core\Payment\Events\PaymentCaptured or
|
||||
* PaymentCaptureFailed — the same terminal events SupportsPay::pay()
|
||||
* produces, since "money has been captured" is the same business fact
|
||||
* regardless of which path reached it.
|
||||
*/
|
||||
interface SupportsCaptures
|
||||
{
|
||||
/**
|
||||
* $reference is the gateway's own identifier for the authorized charge
|
||||
* — see SupportsRefunds::refund() for why this isn't a Lunar
|
||||
* Transaction. $amount is in the currency's minor unit.
|
||||
* $reference is the identifier SupportsAuthorization::authorize()
|
||||
* returned (PaymentResult::$reference) for the hold being settled.
|
||||
*
|
||||
* $amount lets a driver capture less than the full authorized amount
|
||||
* (e.g. shipping less than ordered) — up to the driver/gateway
|
||||
* whether a partial capture also releases the remainder or leaves it
|
||||
* capturable again later (multicapture-style gateways).
|
||||
*
|
||||
* @param array<string, mixed> $context
|
||||
*/
|
||||
public function capture(Order $order, string $reference, int $amount, ?string $notes = null): CaptureResult;
|
||||
}
|
||||
public function capture(string $reference, int $amount, array $context = []): PaymentResult;
|
||||
}
|
||||
@@ -0,0 +1,45 @@
|
||||
<?php
|
||||
|
||||
namespace Modules\Core\Payment\Contracts;
|
||||
|
||||
use Modules\Core\Payment\DTOs\PaymentResult;
|
||||
|
||||
/**
|
||||
* A driver's atomic charge — authorize and capture in one gateway call
|
||||
* (Mastercard's own "Pay" operation, Nexi's ActionType::PAY(), Stripe's
|
||||
* capture_method=automatic, or an offline driver with no gateway at all).
|
||||
* Distinct from SupportsAuthorization: a driver that only ever settles in
|
||||
* one step implements this and nothing else — there is no separate hold
|
||||
* to later capture() or void().
|
||||
*
|
||||
* Dispatches Modules\Core\Payment\Events\PaymentCaptured or
|
||||
* PaymentCaptureFailed based on the returned PaymentResult's status,
|
||||
* unless $result->status is Pending (an async gateway that hasn't
|
||||
* resolved yet — see HandlesPaymentCallback for how that gets resolved
|
||||
* later, from a separate call this method's return value does not wait
|
||||
* on).
|
||||
*/
|
||||
interface SupportsPay
|
||||
{
|
||||
/**
|
||||
* $type is the payment type key being charged (e.g. 'cash-on-delivery',
|
||||
* 'stripe') — passed through even though most drivers only ever serve
|
||||
* one type, because a driver shared across several types needs it to
|
||||
* look up that type's own config.
|
||||
*
|
||||
* $data carries whatever the gateway needs (amount, currency, customer
|
||||
* details, a payment method token) — the caller's responsibility to
|
||||
* assemble, since a driver has no notion of a cart or order to pull
|
||||
* them from itself.
|
||||
*
|
||||
* $context is opaque to the driver — carried through untouched into
|
||||
* whichever Payment event this call (or a later handleCallback()
|
||||
* resolving it) produces, so the caller can correlate the result back
|
||||
* to whatever it needs, without Payment ever needing to know what
|
||||
* that is.
|
||||
*
|
||||
* @param array<string, mixed> $data
|
||||
* @param array<string, mixed> $context
|
||||
*/
|
||||
public function pay(string $type, array $data, array $context = []): PaymentResult;
|
||||
}
|
||||
@@ -2,23 +2,30 @@
|
||||
|
||||
namespace Modules\Core\Payment\Contracts;
|
||||
|
||||
use Lunar\Models\Order;
|
||||
use Modules\Core\Payment\DataTransferObjects\RefundResult;
|
||||
use Modules\Core\Payment\DTOs\PaymentResult;
|
||||
|
||||
/**
|
||||
* Optional capability for payment drivers whose gateway supports refunding
|
||||
* a prior charge. Drivers without a refund API (or that never got that far
|
||||
* — e.g. an offline/manual driver) simply don't implement it. Mirrors
|
||||
* Shipping\Contracts\SupportsTracking's opt-in shape.
|
||||
* Reverses settled funds — independent of SupportsCaptures/SupportsVoids:
|
||||
* a driver that only ever settles via SupportsPay::pay() (no separate
|
||||
* authorize step) can still implement this, since a refund targets money
|
||||
* already taken regardless of how it got taken. A driver implements this
|
||||
* whenever its gateway exposes any refund capability at all, whether or
|
||||
* not it also supports authorize-then-capture.
|
||||
*
|
||||
* Dispatches Modules\Core\Payment\Events\PaymentRefunded or
|
||||
* PaymentRefundFailed.
|
||||
*/
|
||||
interface SupportsRefunds
|
||||
{
|
||||
/**
|
||||
* $reference is the gateway's own identifier for the charge being
|
||||
* refunded (e.g. a Viva Wallet transaction id) — not a Lunar
|
||||
* Transaction model, since not every gateway's refund flow maps
|
||||
* cleanly onto one. $amount is in the currency's minor unit, same
|
||||
* convention as Lunar\Base\Casts\Price.
|
||||
* $reference is the identifier the original SupportsPay::pay() or
|
||||
* SupportsCaptures::capture() call returned for the settled funds
|
||||
* being refunded.
|
||||
*
|
||||
* $amount allows a partial refund; a gateway may allow multiple
|
||||
* partial refunds against one settlement, up to its own total.
|
||||
*
|
||||
* @param array<string, mixed> $context
|
||||
*/
|
||||
public function refund(Order $order, string $reference, int $amount, ?string $notes = null): RefundResult;
|
||||
public function refund(string $reference, int $amount, array $context = []): PaymentResult;
|
||||
}
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
<?php
|
||||
|
||||
namespace Modules\Core\Payment\Contracts;
|
||||
|
||||
use Modules\Core\Payment\DTOs\PaymentResult;
|
||||
|
||||
/**
|
||||
* Cancels a PRIOR SupportsAuthorization::authorize() hold WITHOUT
|
||||
* settling it — the "actually, never mind" exit SupportsCaptures::capture()
|
||||
* doesn't take. No funds ever moved, so this is not a refund: there is
|
||||
* nothing to give back, only a hold to release early (rather than letting
|
||||
* it simply expire on its own).
|
||||
*
|
||||
* Dispatches Modules\Core\Payment\Events\PaymentVoided or
|
||||
* PaymentVoidFailed.
|
||||
*/
|
||||
interface SupportsVoids
|
||||
{
|
||||
/**
|
||||
* $reference is the identifier SupportsAuthorization::authorize()
|
||||
* returned for the hold being released.
|
||||
*
|
||||
* @param array<string, mixed> $context
|
||||
*/
|
||||
public function void(string $reference, array $context = []): PaymentResult;
|
||||
}
|
||||
Reference in New Issue
Block a user