1	<?php
2
3	namespace App\Services\Payment\Contracts;
4
5	use App\Models\Order;
6	use App\Models\Payment;
7	use App\Services\Payment\PaymentResult;
8	use Illuminate\Http\Request;
9
10	/**
11	* One payment provider. Every driver is self-contained (its own config
12	* schema, its own charge/verify/refund logic) — see config/payment_gateways.php
13	* for the registry and App\Services\Payment\PaymentManager for the resolver.
14	*
15	* A driver never touches the Order/Payment models directly beyond what it's
16	* handed — PaymentManager is what persists the result, so every gateway is
17	* audited and displayed the same way regardless of provider.
18	*/
19	interface PaymentGatewayContract
20	{
21	/** Unique key — matches its entry in config/payment_gateways.php. */
22	public function key(): string;
23
24	public function label(): string;
25
26	/**
27	* Field definitions for the Settings -> Payment Gateways card, same
28	* shape as a settings schema field: [key => ['type'=>'text|password|toggle', 'label'=>, 'required'=>bool]].
29	*
30	* @return array<string, array<string, mixed>>
31	*/
32	public function configSchema(): array;
33
34	/**
35	* Start a charge for this order. Returns a redirect URL for off-site
36	* flows (SSLCommerz/Stripe/PayPal-style), or a decided result with none
37	* for on-the-spot outcomes (COD).
38	*
39	* @param  array<string, mixed>  $config  this driver's saved settings
40	*/
41	public function charge(Order $order, array $config): PaymentResult;
42
43	/**
44	* Handle the shopper's return from an off-site flow, or a provider
45	* webhook/IPN call — same entry point for both; the driver tells them
46	* apart from the request shape. Called with no auth/session guarantees.
47	*
48	* @param  array<string, mixed>  $config
49	*/
50	public function verify(Request $request, array $config): PaymentResult;
51
52	/**
53	* Refund (fully or partially) a previously paid transaction. Returns
54	* false (never throws) when the provider/driver doesn't support it, so
55	* the caller can show "not supported" instead of a crash.
56	*
57	* @param  array<string, mixed>  $config
58	*/
59	public function refund(Payment $payment, float $amount, array $config): bool;
60
61	/**
62	* True once this driver has everything (real API calls, credential
63	* verification) needed to actually process a live payment. False for a
64	* driver that's scaffolded — its config schema/UI card exist so the
65	* registry is complete, but charge() refuses until it's finished.
66	*/
67	public function isImplemented(): bool;
68	}