charitable / vendor / square / square / src / Terminal / Refunds / RefundsClient.php

RefundsClient.php in Charitable – Donation & Fundraising Platform (Donation Forms, Recurring Donations & Fundraising Campaigns) 1.8.13, at vendor/square/square/src/Terminal/Refunds/RefundsClient.php

282 lines 10.9 KB

Raw Download Zip

1	<?php
2
3	namespace Square\Terminal\Refunds;
4
5	use GuzzleHttp\ClientInterface;
6	use Square\Core\Client\RawClient;
7	use Square\Terminal\Refunds\Requests\CreateTerminalRefundRequest;
8	use Square\Types\CreateTerminalRefundResponse;
9	use Square\Exceptions\SquareException;
10	use Square\Exceptions\SquareApiException;
11	use Square\Core\Json\JsonApiRequest;
12	use Square\Environments;
13	use Square\Core\Client\HttpMethod;
14	use JsonException;
15	use GuzzleHttp\Exception\RequestException;
16	use Psr\Http\Client\ClientExceptionInterface;
17	use Square\Terminal\Refunds\Requests\SearchTerminalRefundsRequest;
18	use Square\Types\SearchTerminalRefundsResponse;
19	use Square\Terminal\Refunds\Requests\GetRefundsRequest;
20	use Square\Types\GetTerminalRefundResponse;
21	use Square\Terminal\Refunds\Requests\CancelRefundsRequest;
22	use Square\Types\CancelTerminalRefundResponse;
23
24	class RefundsClient
25	{
26	/**
27	* @var array{
28	* baseUrl?: string,
29	* client?: ClientInterface,
30	* maxRetries?: int,
31	* timeout?: float,
32	* headers?: array<string, string>,
33	* } $options
34	*/
35	private array $options;
36
37	/**
38	* @var RawClient $client
39	*/
40	private RawClient $client;
41
42	/**
43	* @param RawClient $client
44	* @param ?array{
45	* baseUrl?: string,
46	* client?: ClientInterface,
47	* maxRetries?: int,
48	* timeout?: float,
49	* headers?: array<string, string>,
50	* } $options
51	*/
52	public function __construct(
53	RawClient $client,
54	?array $options = null,
55	) {
56	$this->client = $client;
57	$this->options = $options ?? [];
58	}
59
60	/**
61	* Creates a request to refund an Interac payment completed on a Square Terminal. Refunds for Interac payments on a Square Terminal are supported only for Interac debit cards in Canada. Other refunds for Terminal payments should use the Refunds API. For more information, see [Refunds API](api:Refunds).
62	*
63	* @param CreateTerminalRefundRequest $request
64	* @param ?array{
65	* baseUrl?: string,
66	* maxRetries?: int,
67	* timeout?: float,
68	* headers?: array<string, string>,
69	* queryParameters?: array<string, mixed>,
70	* bodyProperties?: array<string, mixed>,
71	* } $options
72	* @return CreateTerminalRefundResponse
73	* @throws SquareException
74	* @throws SquareApiException
75	*/
76	public function create(CreateTerminalRefundRequest $request, ?array $options = null): CreateTerminalRefundResponse
77	{
78	$options = array_merge($this->options, $options ?? []);
79	try {
80	$response = $this->client->sendRequest(
81	new JsonApiRequest(
82	baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value,
83	path: "v2/terminals/refunds",
84	method: HttpMethod::POST,
85	body: $request,
86	),
87	$options,
88	);
89	$statusCode = $response->getStatusCode();
90	if ($statusCode >= 200 && $statusCode < 400) {
91	$json = $response->getBody()->getContents();
92	return CreateTerminalRefundResponse::fromJson($json);
93	}
94	} catch (JsonException $e) {
95	throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e);
96	} catch (RequestException $e) {
97	$response = $e->getResponse();
98	if ($response === null) {
99	throw new SquareException(message: $e->getMessage(), previous: $e);
100	}
101	throw new SquareApiException(
102	message: "API request failed",
103	statusCode: $response->getStatusCode(),
104	body: $response->getBody()->getContents(),
105	);
106	} catch (ClientExceptionInterface $e) {
107	throw new SquareException(message: $e->getMessage(), previous: $e);
108	}
109	throw new SquareApiException(
110	message: 'API request failed',
111	statusCode: $statusCode,
112	body: $response->getBody()->getContents(),
113	);
114	}
115
116	/**
117	* Retrieves a filtered list of Interac Terminal refund requests created by the seller making the request. Terminal refund requests are available for 30 days.
118	*
119	* @param SearchTerminalRefundsRequest $request
120	* @param ?array{
121	* baseUrl?: string,
122	* maxRetries?: int,
123	* timeout?: float,
124	* headers?: array<string, string>,
125	* queryParameters?: array<string, mixed>,
126	* bodyProperties?: array<string, mixed>,
127	* } $options
128	* @return SearchTerminalRefundsResponse
129	* @throws SquareException
130	* @throws SquareApiException
131	*/
132	public function search(SearchTerminalRefundsRequest $request = new SearchTerminalRefundsRequest(), ?array $options = null): SearchTerminalRefundsResponse
133	{
134	$options = array_merge($this->options, $options ?? []);
135	try {
136	$response = $this->client->sendRequest(
137	new JsonApiRequest(
138	baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value,
139	path: "v2/terminals/refunds/search",
140	method: HttpMethod::POST,
141	body: $request,
142	),
143	$options,
144	);
145	$statusCode = $response->getStatusCode();
146	if ($statusCode >= 200 && $statusCode < 400) {
147	$json = $response->getBody()->getContents();
148	return SearchTerminalRefundsResponse::fromJson($json);
149	}
150	} catch (JsonException $e) {
151	throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e);
152	} catch (RequestException $e) {
153	$response = $e->getResponse();
154	if ($response === null) {
155	throw new SquareException(message: $e->getMessage(), previous: $e);
156	}
157	throw new SquareApiException(
158	message: "API request failed",
159	statusCode: $response->getStatusCode(),
160	body: $response->getBody()->getContents(),
161	);
162	} catch (ClientExceptionInterface $e) {
163	throw new SquareException(message: $e->getMessage(), previous: $e);
164	}
165	throw new SquareApiException(
166	message: 'API request failed',
167	statusCode: $statusCode,
168	body: $response->getBody()->getContents(),
169	);
170	}
171
172	/**
173	* Retrieves an Interac Terminal refund object by ID. Terminal refund objects are available for 30 days.
174	*
175	* @param GetRefundsRequest $request
176	* @param ?array{
177	* baseUrl?: string,
178	* maxRetries?: int,
179	* timeout?: float,
180	* headers?: array<string, string>,
181	* queryParameters?: array<string, mixed>,
182	* bodyProperties?: array<string, mixed>,
183	* } $options
184	* @return GetTerminalRefundResponse
185	* @throws SquareException
186	* @throws SquareApiException
187	*/
188	public function get(GetRefundsRequest $request, ?array $options = null): GetTerminalRefundResponse
189	{
190	$options = array_merge($this->options, $options ?? []);
191	try {
192	$response = $this->client->sendRequest(
193	new JsonApiRequest(
194	baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value,
195	path: "v2/terminals/refunds/{$request->getTerminalRefundId()}",
196	method: HttpMethod::GET,
197	),
198	$options,
199	);
200	$statusCode = $response->getStatusCode();
201	if ($statusCode >= 200 && $statusCode < 400) {
202	$json = $response->getBody()->getContents();
203	return GetTerminalRefundResponse::fromJson($json);
204	}
205	} catch (JsonException $e) {
206	throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e);
207	} catch (RequestException $e) {
208	$response = $e->getResponse();
209	if ($response === null) {
210	throw new SquareException(message: $e->getMessage(), previous: $e);
211	}
212	throw new SquareApiException(
213	message: "API request failed",
214	statusCode: $response->getStatusCode(),
215	body: $response->getBody()->getContents(),
216	);
217	} catch (ClientExceptionInterface $e) {
218	throw new SquareException(message: $e->getMessage(), previous: $e);
219	}
220	throw new SquareApiException(
221	message: 'API request failed',
222	statusCode: $statusCode,
223	body: $response->getBody()->getContents(),
224	);
225	}
226
227	/**
228	* Cancels an Interac Terminal refund request by refund request ID if the status of the request permits it.
229	*
230	* @param CancelRefundsRequest $request
231	* @param ?array{
232	* baseUrl?: string,
233	* maxRetries?: int,
234	* timeout?: float,
235	* headers?: array<string, string>,
236	* queryParameters?: array<string, mixed>,
237	* bodyProperties?: array<string, mixed>,
238	* } $options
239	* @return CancelTerminalRefundResponse
240	* @throws SquareException
241	* @throws SquareApiException
242	*/
243	public function cancel(CancelRefundsRequest $request, ?array $options = null): CancelTerminalRefundResponse
244	{
245	$options = array_merge($this->options, $options ?? []);
246	try {
247	$response = $this->client->sendRequest(
248	new JsonApiRequest(
249	baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value,
250	path: "v2/terminals/refunds/{$request->getTerminalRefundId()}/cancel",
251	method: HttpMethod::POST,
252	),
253	$options,
254	);
255	$statusCode = $response->getStatusCode();
256	if ($statusCode >= 200 && $statusCode < 400) {
257	$json = $response->getBody()->getContents();
258	return CancelTerminalRefundResponse::fromJson($json);
259	}
260	} catch (JsonException $e) {
261	throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e);
262	} catch (RequestException $e) {
263	$response = $e->getResponse();
264	if ($response === null) {
265	throw new SquareException(message: $e->getMessage(), previous: $e);
266	}
267	throw new SquareApiException(
268	message: "API request failed",
269	statusCode: $response->getStatusCode(),
270	body: $response->getBody()->getContents(),
271	);
272	} catch (ClientExceptionInterface $e) {
273	throw new SquareException(message: $e->getMessage(), previous: $e);
274	}
275	throw new SquareApiException(
276	message: 'API request failed',
277	statusCode: $statusCode,
278	body: $response->getBody()->getContents(),
279	);
280	}
281	}
282