charitable / vendor / square / square / src / Legacy / Models / CreateCheckoutRequest.php

CreateCheckoutRequest.php in Charitable – Donation & Fundraising Platform (Donation Forms, Recurring Donations & Fundraising Campaigns) 1.8.13, at vendor/square/square/src/Legacy/Models/CreateCheckoutRequest.php

396 lines 12.8 KB

Raw Download Zip

1	<?php
2
3	declare(strict_types=1);
4
5	namespace Square\Legacy\Models;
6
7	use stdClass;
8
9	/**
10	* Defines the parameters that can be included in the body of
11	* a request to the `CreateCheckout` endpoint.
12	*/
13	class CreateCheckoutRequest implements \JsonSerializable
14	{
15	/**
16	* @var string
17	*/
18	private $idempotencyKey;
19
20	/**
21	* @var CreateOrderRequest
22	*/
23	private $order;
24
25	/**
26	* @var bool\|null
27	*/
28	private $askForShippingAddress;
29
30	/**
31	* @var string\|null
32	*/
33	private $merchantSupportEmail;
34
35	/**
36	* @var string\|null
37	*/
38	private $prePopulateBuyerEmail;
39
40	/**
41	* @var Address\|null
42	*/
43	private $prePopulateShippingAddress;
44
45	/**
46	* @var string\|null
47	*/
48	private $redirectUrl;
49
50	/**
51	* @var ChargeRequestAdditionalRecipient[]\|null
52	*/
53	private $additionalRecipients;
54
55	/**
56	* @var string\|null
57	*/
58	private $note;
59
60	/**
61	* @param string $idempotencyKey
62	* @param CreateOrderRequest $order
63	*/
64	public function __construct(string $idempotencyKey, CreateOrderRequest $order)
65	{
66	$this->idempotencyKey = $idempotencyKey;
67	$this->order = $order;
68	}
69
70	/**
71	* Returns Idempotency Key.
72	* A unique string that identifies this checkout among others you have created. It can be
73	* any valid string but must be unique for every order sent to Square Checkout for a given location ID.
74	*
75	* The idempotency key is used to avoid processing the same order more than once. If you are
76	* unsure whether a particular checkout was created successfully, you can attempt it again with
77	* the same idempotency key and all the same other parameters without worrying about creating
78	* duplicates.
79	*
80	* You should use a random number/string generator native to the language
81	* you are working in to generate strings for your idempotency keys.
82	*
83	* For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-
84	* apis/idempotency).
85	*/
86	public function getIdempotencyKey(): string
87	{
88	return $this->idempotencyKey;
89	}
90
91	/**
92	* Sets Idempotency Key.
93	* A unique string that identifies this checkout among others you have created. It can be
94	* any valid string but must be unique for every order sent to Square Checkout for a given location ID.
95	*
96	* The idempotency key is used to avoid processing the same order more than once. If you are
97	* unsure whether a particular checkout was created successfully, you can attempt it again with
98	* the same idempotency key and all the same other parameters without worrying about creating
99	* duplicates.
100	*
101	* You should use a random number/string generator native to the language
102	* you are working in to generate strings for your idempotency keys.
103	*
104	* For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-
105	* apis/idempotency).
106	*
107	* @required
108	* @maps idempotency_key
109	*/
110	public function setIdempotencyKey(string $idempotencyKey): void
111	{
112	$this->idempotencyKey = $idempotencyKey;
113	}
114
115	/**
116	* Returns Order.
117	*/
118	public function getOrder(): CreateOrderRequest
119	{
120	return $this->order;
121	}
122
123	/**
124	* Sets Order.
125	*
126	* @required
127	* @maps order
128	*/
129	public function setOrder(CreateOrderRequest $order): void
130	{
131	$this->order = $order;
132	}
133
134	/**
135	* Returns Ask for Shipping Address.
136	* If `true`, Square Checkout collects shipping information on your behalf and stores
137	* that information with the transaction information in the Square Seller Dashboard.
138	*
139	* Default: `false`.
140	*/
141	public function getAskForShippingAddress(): ?bool
142	{
143	return $this->askForShippingAddress;
144	}
145
146	/**
147	* Sets Ask for Shipping Address.
148	* If `true`, Square Checkout collects shipping information on your behalf and stores
149	* that information with the transaction information in the Square Seller Dashboard.
150	*
151	* Default: `false`.
152	*
153	* @maps ask_for_shipping_address
154	*/
155	public function setAskForShippingAddress(?bool $askForShippingAddress): void
156	{
157	$this->askForShippingAddress = $askForShippingAddress;
158	}
159
160	/**
161	* Returns Merchant Support Email.
162	* The email address to display on the Square Checkout confirmation page
163	* and confirmation email that the buyer can use to contact the seller.
164	*
165	* If this value is not set, the confirmation page and email display the
166	* primary email address associated with the seller's Square account.
167	*
168	* Default: none; only exists if explicitly set.
169	*/
170	public function getMerchantSupportEmail(): ?string
171	{
172	return $this->merchantSupportEmail;
173	}
174
175	/**
176	* Sets Merchant Support Email.
177	* The email address to display on the Square Checkout confirmation page
178	* and confirmation email that the buyer can use to contact the seller.
179	*
180	* If this value is not set, the confirmation page and email display the
181	* primary email address associated with the seller's Square account.
182	*
183	* Default: none; only exists if explicitly set.
184	*
185	* @maps merchant_support_email
186	*/
187	public function setMerchantSupportEmail(?string $merchantSupportEmail): void
188	{
189	$this->merchantSupportEmail = $merchantSupportEmail;
190	}
191
192	/**
193	* Returns Pre Populate Buyer Email.
194	* If provided, the buyer's email is prepopulated on the checkout page
195	* as an editable text field.
196	*
197	* Default: none; only exists if explicitly set.
198	*/
199	public function getPrePopulateBuyerEmail(): ?string
200	{
201	return $this->prePopulateBuyerEmail;
202	}
203
204	/**
205	* Sets Pre Populate Buyer Email.
206	* If provided, the buyer's email is prepopulated on the checkout page
207	* as an editable text field.
208	*
209	* Default: none; only exists if explicitly set.
210	*
211	* @maps pre_populate_buyer_email
212	*/
213	public function setPrePopulateBuyerEmail(?string $prePopulateBuyerEmail): void
214	{
215	$this->prePopulateBuyerEmail = $prePopulateBuyerEmail;
216	}
217
218	/**
219	* Returns Pre Populate Shipping Address.
220	* Represents a postal address in a country.
221	* For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-
222	* basics/working-with-addresses).
223	*/
224	public function getPrePopulateShippingAddress(): ?Address
225	{
226	return $this->prePopulateShippingAddress;
227	}
228
229	/**
230	* Sets Pre Populate Shipping Address.
231	* Represents a postal address in a country.
232	* For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-
233	* basics/working-with-addresses).
234	*
235	* @maps pre_populate_shipping_address
236	*/
237	public function setPrePopulateShippingAddress(?Address $prePopulateShippingAddress): void
238	{
239	$this->prePopulateShippingAddress = $prePopulateShippingAddress;
240	}
241
242	/**
243	* Returns Redirect Url.
244	* The URL to redirect to after the checkout is completed with `checkoutId`,
245	* `transactionId`, and `referenceId` appended as URL parameters. For example,
246	* if the provided redirect URL is `http://www.example.com/order-complete`, a
247	* successful transaction redirects the customer to:
248	*
249	* `http://www.example.com/order-complete?checkoutId=xxxxxx&referenceId=xxxxxx&
250	* transactionId=xxxxxx`
251	*
252	* If you do not provide a redirect URL, Square Checkout displays an order
253	* confirmation page on your behalf; however, it is strongly recommended that
254	* you provide a redirect URL so you can verify the transaction results and
255	* finalize the order through your existing/normal confirmation workflow.
256	*
257	* Default: none; only exists if explicitly set.
258	*/
259	public function getRedirectUrl(): ?string
260	{
261	return $this->redirectUrl;
262	}
263
264	/**
265	* Sets Redirect Url.
266	* The URL to redirect to after the checkout is completed with `checkoutId`,
267	* `transactionId`, and `referenceId` appended as URL parameters. For example,
268	* if the provided redirect URL is `http://www.example.com/order-complete`, a
269	* successful transaction redirects the customer to:
270	*
271	* `http://www.example.com/order-complete?checkoutId=xxxxxx&referenceId=xxxxxx&
272	* transactionId=xxxxxx`
273	*
274	* If you do not provide a redirect URL, Square Checkout displays an order
275	* confirmation page on your behalf; however, it is strongly recommended that
276	* you provide a redirect URL so you can verify the transaction results and
277	* finalize the order through your existing/normal confirmation workflow.
278	*
279	* Default: none; only exists if explicitly set.
280	*
281	* @maps redirect_url
282	*/
283	public function setRedirectUrl(?string $redirectUrl): void
284	{
285	$this->redirectUrl = $redirectUrl;
286	}
287
288	/**
289	* Returns Additional Recipients.
290	* The basic primitive of a multi-party transaction. The value is optional.
291	* The transaction facilitated by you can be split from here.
292	*
293	* If you provide this value, the `amount_money` value in your `additional_recipients` field
294	* cannot be more than 90% of the `total_money` calculated by Square for your order.
295	* The `location_id` must be a valid seller location where the checkout is occurring.
296	*
297	* This field requires `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission.
298	*
299	* This field is currently not supported in the Square Sandbox.
300	*
301	* @return ChargeRequestAdditionalRecipient[]\|null
302	*/
303	public function getAdditionalRecipients(): ?array
304	{
305	return $this->additionalRecipients;
306	}
307
308	/**
309	* Sets Additional Recipients.
310	* The basic primitive of a multi-party transaction. The value is optional.
311	* The transaction facilitated by you can be split from here.
312	*
313	* If you provide this value, the `amount_money` value in your `additional_recipients` field
314	* cannot be more than 90% of the `total_money` calculated by Square for your order.
315	* The `location_id` must be a valid seller location where the checkout is occurring.
316	*
317	* This field requires `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission.
318	*
319	* This field is currently not supported in the Square Sandbox.
320	*
321	* @maps additional_recipients
322	*
323	* @param ChargeRequestAdditionalRecipient[]\|null $additionalRecipients
324	*/
325	public function setAdditionalRecipients(?array $additionalRecipients): void
326	{
327	$this->additionalRecipients = $additionalRecipients;
328	}
329
330	/**
331	* Returns Note.
332	* An optional note to associate with the `checkout` object.
333	*
334	* This value cannot exceed 60 characters.
335	*/
336	public function getNote(): ?string
337	{
338	return $this->note;
339	}
340
341	/**
342	* Sets Note.
343	* An optional note to associate with the `checkout` object.
344	*
345	* This value cannot exceed 60 characters.
346	*
347	* @maps note
348	*/
349	public function setNote(?string $note): void
350	{
351	$this->note = $note;
352	}
353
354	/**
355	* Encode this object to JSON
356	*
357	* @param bool $asArrayWhenEmpty Whether to serialize this model as an array whenever no fields
358	* are set. (default: false)
359	*
360	* @return array\|stdClass
361	*/
362	#[\ReturnTypeWillChange] // @phan-suppress-current-line PhanUndeclaredClassAttribute for (php < 8.1)
363	public function jsonSerialize(bool $asArrayWhenEmpty = false)
364	{
365	$json = [];
366	$json['idempotency_key'] = $this->idempotencyKey;
367	$json['order'] = $this->order;
368	if (isset($this->askForShippingAddress)) {
369	$json['ask_for_shipping_address'] = $this->askForShippingAddress;
370	}
371	if (isset($this->merchantSupportEmail)) {
372	$json['merchant_support_email'] = $this->merchantSupportEmail;
373	}
374	if (isset($this->prePopulateBuyerEmail)) {
375	$json['pre_populate_buyer_email'] = $this->prePopulateBuyerEmail;
376	}
377	if (isset($this->prePopulateShippingAddress)) {
378	$json['pre_populate_shipping_address'] = $this->prePopulateShippingAddress;
379	}
380	if (isset($this->redirectUrl)) {
381	$json['redirect_url'] = $this->redirectUrl;
382	}
383	if (isset($this->additionalRecipients)) {
384	$json['additional_recipients'] = $this->additionalRecipients;
385	}
386	if (isset($this->note)) {
387	$json['note'] = $this->note;
388	}
389	$json = array_filter($json, function ($val) {
390	return $val !== null;
391	});
392
393	return (!$asArrayWhenEmpty && empty($json)) ? new stdClass() : $json;
394	}
395	}
396