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

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

304 lines 11.2 KB

Raw Download Zip

1	<?php
2
3	namespace Square\Refunds;
4
5	use GuzzleHttp\ClientInterface;
6	use Square\Core\Client\RawClient;
7	use Square\Refunds\Requests\ListRefundsRequest;
8	use Square\Core\Pagination\Pager;
9	use Square\Types\PaymentRefund;
10	use Square\Core\Pagination\CursorPager;
11	use Square\Types\ListPaymentRefundsResponse;
12	use Square\Refunds\Requests\RefundPaymentRequest;
13	use Square\Types\RefundPaymentResponse;
14	use Square\Exceptions\SquareException;
15	use Square\Exceptions\SquareApiException;
16	use Square\Core\Json\JsonApiRequest;
17	use Square\Environments;
18	use Square\Core\Client\HttpMethod;
19	use JsonException;
20	use GuzzleHttp\Exception\RequestException;
21	use Psr\Http\Client\ClientExceptionInterface;
22	use Square\Refunds\Requests\GetRefundsRequest;
23	use Square\Types\GetPaymentRefundResponse;
24
25	class RefundsClient
26	{
27	/**
28	* @var array{
29	* baseUrl?: string,
30	* client?: ClientInterface,
31	* maxRetries?: int,
32	* timeout?: float,
33	* headers?: array<string, string>,
34	* } $options
35	*/
36	private array $options;
37
38	/**
39	* @var RawClient $client
40	*/
41	private RawClient $client;
42
43	/**
44	* @param RawClient $client
45	* @param ?array{
46	* baseUrl?: string,
47	* client?: ClientInterface,
48	* maxRetries?: int,
49	* timeout?: float,
50	* headers?: array<string, string>,
51	* } $options
52	*/
53	public function __construct(
54	RawClient $client,
55	?array $options = null,
56	) {
57	$this->client = $client;
58	$this->options = $options ?? [];
59	}
60
61	/**
62	* Retrieves a list of refunds for the account making the request.
63	*
64	* Results are eventually consistent, and new refunds or changes to refunds might take several
65	* seconds to appear.
66	*
67	* The maximum results per page is 100.
68	*
69	* @param ListRefundsRequest $request
70	* @param ?array{
71	* baseUrl?: string,
72	* maxRetries?: int,
73	* timeout?: float,
74	* headers?: array<string, string>,
75	* queryParameters?: array<string, mixed>,
76	* bodyProperties?: array<string, mixed>,
77	* } $options
78	* @return Pager<PaymentRefund>
79	*/
80	public function list(ListRefundsRequest $request = new ListRefundsRequest(), ?array $options = null): Pager
81	{
82	return new CursorPager(
83	request: $request,
84	getNextPage: fn (ListRefundsRequest $request) => $this->_list($request, $options),
85	setCursor: function (ListRefundsRequest $request, ?string $cursor) {
86	$request->setCursor($cursor);
87	},
88	/* @phpstan-ignore-next-line */
89	getNextCursor: fn (ListPaymentRefundsResponse $response) => $response?->getCursor() ?? null,
90	/* @phpstan-ignore-next-line */
91	getItems: fn (ListPaymentRefundsResponse $response) => $response?->getRefunds() ?? [],
92	);
93	}
94
95	/**
96	* Refunds a payment. You can refund the entire payment amount or a
97	* portion of it. You can use this endpoint to refund a card payment or record a
98	* refund of a cash or external payment. For more information, see
99	* [Refund Payment](https://developer.squareup.com/docs/payments-api/refund-payments).
100	*
101	* @param RefundPaymentRequest $request
102	* @param ?array{
103	* baseUrl?: string,
104	* maxRetries?: int,
105	* timeout?: float,
106	* headers?: array<string, string>,
107	* queryParameters?: array<string, mixed>,
108	* bodyProperties?: array<string, mixed>,
109	* } $options
110	* @return RefundPaymentResponse
111	* @throws SquareException
112	* @throws SquareApiException
113	*/
114	public function refundPayment(RefundPaymentRequest $request, ?array $options = null): RefundPaymentResponse
115	{
116	$options = array_merge($this->options, $options ?? []);
117	try {
118	$response = $this->client->sendRequest(
119	new JsonApiRequest(
120	baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value,
121	path: "v2/refunds",
122	method: HttpMethod::POST,
123	body: $request,
124	),
125	$options,
126	);
127	$statusCode = $response->getStatusCode();
128	if ($statusCode >= 200 && $statusCode < 400) {
129	$json = $response->getBody()->getContents();
130	return RefundPaymentResponse::fromJson($json);
131	}
132	} catch (JsonException $e) {
133	throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e);
134	} catch (RequestException $e) {
135	$response = $e->getResponse();
136	if ($response === null) {
137	throw new SquareException(message: $e->getMessage(), previous: $e);
138	}
139	throw new SquareApiException(
140	message: "API request failed",
141	statusCode: $response->getStatusCode(),
142	body: $response->getBody()->getContents(),
143	);
144	} catch (ClientExceptionInterface $e) {
145	throw new SquareException(message: $e->getMessage(), previous: $e);
146	}
147	throw new SquareApiException(
148	message: 'API request failed',
149	statusCode: $statusCode,
150	body: $response->getBody()->getContents(),
151	);
152	}
153
154	/**
155	* Retrieves a specific refund using the `refund_id`.
156	*
157	* @param GetRefundsRequest $request
158	* @param ?array{
159	* baseUrl?: string,
160	* maxRetries?: int,
161	* timeout?: float,
162	* headers?: array<string, string>,
163	* queryParameters?: array<string, mixed>,
164	* bodyProperties?: array<string, mixed>,
165	* } $options
166	* @return GetPaymentRefundResponse
167	* @throws SquareException
168	* @throws SquareApiException
169	*/
170	public function get(GetRefundsRequest $request, ?array $options = null): GetPaymentRefundResponse
171	{
172	$options = array_merge($this->options, $options ?? []);
173	try {
174	$response = $this->client->sendRequest(
175	new JsonApiRequest(
176	baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value,
177	path: "v2/refunds/{$request->getRefundId()}",
178	method: HttpMethod::GET,
179	),
180	$options,
181	);
182	$statusCode = $response->getStatusCode();
183	if ($statusCode >= 200 && $statusCode < 400) {
184	$json = $response->getBody()->getContents();
185	return GetPaymentRefundResponse::fromJson($json);
186	}
187	} catch (JsonException $e) {
188	throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e);
189	} catch (RequestException $e) {
190	$response = $e->getResponse();
191	if ($response === null) {
192	throw new SquareException(message: $e->getMessage(), previous: $e);
193	}
194	throw new SquareApiException(
195	message: "API request failed",
196	statusCode: $response->getStatusCode(),
197	body: $response->getBody()->getContents(),
198	);
199	} catch (ClientExceptionInterface $e) {
200	throw new SquareException(message: $e->getMessage(), previous: $e);
201	}
202	throw new SquareApiException(
203	message: 'API request failed',
204	statusCode: $statusCode,
205	body: $response->getBody()->getContents(),
206	);
207	}
208
209	/**
210	* Retrieves a list of refunds for the account making the request.
211	*
212	* Results are eventually consistent, and new refunds or changes to refunds might take several
213	* seconds to appear.
214	*
215	* The maximum results per page is 100.
216	*
217	* @param ListRefundsRequest $request
218	* @param ?array{
219	* baseUrl?: string,
220	* maxRetries?: int,
221	* timeout?: float,
222	* headers?: array<string, string>,
223	* queryParameters?: array<string, mixed>,
224	* bodyProperties?: array<string, mixed>,
225	* } $options
226	* @return ListPaymentRefundsResponse
227	* @throws SquareException
228	* @throws SquareApiException
229	*/
230	private function _list(ListRefundsRequest $request = new ListRefundsRequest(), ?array $options = null): ListPaymentRefundsResponse
231	{
232	$options = array_merge($this->options, $options ?? []);
233	$query = [];
234	if ($request->getBeginTime() != null) {
235	$query['begin_time'] = $request->getBeginTime();
236	}
237	if ($request->getEndTime() != null) {
238	$query['end_time'] = $request->getEndTime();
239	}
240	if ($request->getSortOrder() != null) {
241	$query['sort_order'] = $request->getSortOrder();
242	}
243	if ($request->getCursor() != null) {
244	$query['cursor'] = $request->getCursor();
245	}
246	if ($request->getLocationId() != null) {
247	$query['location_id'] = $request->getLocationId();
248	}
249	if ($request->getStatus() != null) {
250	$query['status'] = $request->getStatus();
251	}
252	if ($request->getSourceType() != null) {
253	$query['source_type'] = $request->getSourceType();
254	}
255	if ($request->getLimit() != null) {
256	$query['limit'] = $request->getLimit();
257	}
258	if ($request->getUpdatedAtBeginTime() != null) {
259	$query['updated_at_begin_time'] = $request->getUpdatedAtBeginTime();
260	}
261	if ($request->getUpdatedAtEndTime() != null) {
262	$query['updated_at_end_time'] = $request->getUpdatedAtEndTime();
263	}
264	if ($request->getSortField() != null) {
265	$query['sort_field'] = $request->getSortField();
266	}
267	try {
268	$response = $this->client->sendRequest(
269	new JsonApiRequest(
270	baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value,
271	path: "v2/refunds",
272	method: HttpMethod::GET,
273	query: $query,
274	),
275	$options,
276	);
277	$statusCode = $response->getStatusCode();
278	if ($statusCode >= 200 && $statusCode < 400) {
279	$json = $response->getBody()->getContents();
280	return ListPaymentRefundsResponse::fromJson($json);
281	}
282	} catch (JsonException $e) {
283	throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e);
284	} catch (RequestException $e) {
285	$response = $e->getResponse();
286	if ($response === null) {
287	throw new SquareException(message: $e->getMessage(), previous: $e);
288	}
289	throw new SquareApiException(
290	message: "API request failed",
291	statusCode: $response->getStatusCode(),
292	body: $response->getBody()->getContents(),
293	);
294	} catch (ClientExceptionInterface $e) {
295	throw new SquareException(message: $e->getMessage(), previous: $e);
296	}
297	throw new SquareApiException(
298	message: 'API request failed',
299	statusCode: $statusCode,
300	body: $response->getBody()->getContents(),
301	);
302	}
303	}
304