ivyforms / backend / src / Services / Payment / PaymentChargeResult.php

PaymentChargeResult.php in The Innovative Form Builder – IvyForms 1.5, at backend/src/Services/Payment/PaymentChargeResult.php

252 lines 6.8 KB

Raw Download Zip

1	<?php
2
3	namespace IvyForms\Services\Payment;
4
5	/**
6	* Outcome of a payment gateway charge attempt during form submission.
7	*/
8	final class PaymentChargeResult
9	{
10	public const STATUS_SUCCEEDED = 'succeeded';
11
12	public const STATUS_REQUIRES_ACTION = 'requires_action';
13
14	public const STATUS_FAILED = 'failed';
15
16	public const STATUS_DECLINED = 'declined';
17
18	private string $status;
19
20	private string $paymentMethod;
21
22	private float $paymentTotal;
23
24	private string $paymentCurrency;
25
26	private ?string $transactionId;
27
28	private ?string $receiptUrl;
29
30	private ?string $clientSecret;
31
32	private ?string $paymentIntentId;
33
34	private ?string $message;
35
36	private ?string $customerName;
37
38	private ?string $squareOrderId;
39
40	private ?string $squareCustomerId;
41
42	private ?string $providerMeta;
43
44	/**
45	* @param array{
46	* status: string,
47	* paymentMethod: string,
48	* paymentTotal?: float,
49	* paymentCurrency?: string,
50	* transactionId?: ?string,
51	* receiptUrl?: ?string,
52	* clientSecret?: ?string,
53	* paymentIntentId?: ?string,
54	* message?: ?string,
55	* customerName?: ?string,
56	* squareOrderId?: ?string,
57	* squareCustomerId?: ?string,
58	* providerMeta?: ?string
59	* } $data
60	*/
61	private function __construct(array $data)
62	{
63	$this->status = $data['status'];
64	$this->paymentMethod = $data['paymentMethod'];
65	$this->paymentTotal = (float) ($data['paymentTotal'] ?? 0.0);
66	$this->paymentCurrency = (string) ($data['paymentCurrency'] ?? 'USD');
67	$this->transactionId = $data['transactionId'] ?? null;
68	$this->receiptUrl = $data['receiptUrl'] ?? null;
69	$this->clientSecret = $data['clientSecret'] ?? null;
70	$this->paymentIntentId = $data['paymentIntentId'] ?? null;
71	$this->message = $data['message'] ?? null;
72	$this->customerName = $data['customerName'] ?? null;
73	$this->squareOrderId = $data['squareOrderId'] ?? null;
74	$this->squareCustomerId = $data['squareCustomerId'] ?? null;
75	$this->providerMeta = $data['providerMeta'] ?? null;
76	}
77
78	/**
79	* @param array<string, mixed> $paymentResult Gateway success payload (must include transactionId)
80	*/
81	public static function succeeded(
82	string $paymentMethod,
83	array $paymentResult,
84	float $paymentTotal,
85	string $paymentCurrency,
86	?string $customerName = null,
87	?string $squareOrderId = null,
88	?string $squareCustomerId = null
89	): self {
90	return new self([
91	'status' => self::STATUS_SUCCEEDED,
92	'paymentMethod' => $paymentMethod,
93	'paymentTotal' => $paymentTotal,
94	'paymentCurrency' => $paymentCurrency,
95	'transactionId' => (string) ($paymentResult['transactionId'] ?? ''),
96	'receiptUrl' => !empty($paymentResult['receiptUrl'])
97	? (string) $paymentResult['receiptUrl']
98	: null,
99	'customerName' => $customerName,
100	'squareOrderId' => $squareOrderId,
101	'squareCustomerId' => $squareCustomerId,
102	'providerMeta' => isset($paymentResult['providerMeta'])
103	? (string) $paymentResult['providerMeta']
104	: null,
105	]);
106	}
107
108	public static function requiresAction(
109	string $paymentMethod,
110	string $clientSecret,
111	string $paymentIntentId,
112	float $paymentTotal,
113	string $paymentCurrency
114	): self {
115	return new self([
116	'status' => self::STATUS_REQUIRES_ACTION,
117	'paymentMethod' => $paymentMethod,
118	'paymentTotal' => $paymentTotal,
119	'paymentCurrency' => $paymentCurrency,
120	'clientSecret' => $clientSecret,
121	'paymentIntentId' => $paymentIntentId,
122	'transactionId' => $paymentIntentId,
123	]);
124	}
125
126	public static function failed(string $paymentMethod, string $message): self
127	{
128	return new self([
129	'status' => self::STATUS_FAILED,
130	'paymentMethod' => $paymentMethod,
131	'message' => $message,
132	]);
133	}
134
135	public static function terminalFailure(
136	string $paymentMethod,
137	string $message,
138	string $transactionId,
139	float $paymentTotal,
140	string $paymentCurrency,
141	string $status = self::STATUS_FAILED,
142	?string $receiptUrl = null
143	): self {
144	return new self([
145	'status' => $status,
146	'paymentMethod' => $paymentMethod,
147	'message' => $message,
148	'transactionId' => $transactionId,
149	'paymentTotal' => $paymentTotal,
150	'paymentCurrency' => $paymentCurrency,
151	'receiptUrl' => $receiptUrl,
152	]);
153	}
154
155	public function isSucceeded(): bool
156	{
157	return $this->status === self::STATUS_SUCCEEDED;
158	}
159
160	public function isRequiresAction(): bool
161	{
162	return $this->status === self::STATUS_REQUIRES_ACTION;
163	}
164
165	public function isFailed(): bool
166	{
167	return !$this->isSucceeded() && !$this->isRequiresAction();
168	}
169
170	public function getStatus(): string
171	{
172	return $this->status;
173	}
174
175	public function getPaymentMethod(): string
176	{
177	return $this->paymentMethod;
178	}
179
180	public function getPaymentTotal(): float
181	{
182	return $this->paymentTotal;
183	}
184
185	public function getPaymentCurrency(): string
186	{
187	return $this->paymentCurrency;
188	}
189
190	public function getTransactionId(): ?string
191	{
192	return $this->transactionId;
193	}
194
195	public function getReceiptUrl(): ?string
196	{
197	return $this->receiptUrl;
198	}
199
200	public function getClientSecret(): ?string
201	{
202	return $this->clientSecret;
203	}
204
205	public function getPaymentIntentId(): ?string
206	{
207	return $this->paymentIntentId;
208	}
209
210	public function getMessage(): ?string
211	{
212	return $this->message;
213	}
214
215	public function getCustomerName(): ?string
216	{
217	return $this->customerName;
218	}
219
220	public function getSquareOrderId(): ?string
221	{
222	return $this->squareOrderId;
223	}
224
225	public function getSquareCustomerId(): ?string
226	{
227	return $this->squareCustomerId;
228	}
229
230	public function getProviderMeta(): ?string
231	{
232	return $this->providerMeta;
233	}
234
235	/**
236	* Shape expected by FormSubmissionController for a successful charge.
237	*
238	* @return array<string, mixed>
239	*/
240	public function toPaymentResultArray(): array
241	{
242	return [
243	'success' => true,
244	'transactionId' => (string) ($this->transactionId ?? ''),
245	'paymentMethod' => $this->paymentMethod,
246	'status' => $this->status,
247	'receiptUrl' => $this->receiptUrl,
248	'providerMeta' => $this->providerMeta,
249	];
250	}
251	}
252