51 lines
2.3 KiB
PHP
51 lines
2.3 KiB
PHP
<?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;
|
|
}
|