1 <?php
2
3 namespace PayPal\Api;
4
5 use PayPal\Common\PayPalResourceModel;
6 use PayPal\Core\PayPalConstants;
7 use PayPal\Rest\ApiContext;
8 use PayPal\Transport\PayPalRestCall;
9 use PayPal\Validation\ArgumentValidator;
10
11 /**
12 * Class Agreement
13 *
14 * A resource representing an agreement.
15 *
16 * @package PayPal\Api
17 *
18 * @property string id
19 * @property string state
20 * @property string name
21 * @property string description
22 * @property string start_date
23 * @property \PayPal\Api\Payer payer
24 * @property \PayPal\Api\Address shipping_address
25 * @property \PayPal\Api\MerchantPreferences override_merchant_preferences
26 * @property \PayPal\Api\OverrideChargeModel[] override_charge_models
27 * @property \PayPal\Api\Plan plan
28 * @property string create_time
29 * @property string update_time
30 * @property \PayPal\Api\AgreementDetails agreement_details
31 */
32 class Agreement extends PayPalResourceModel
33 {
34 /**
35 * Identifier of the agreement.
36 *
37 * @param string $id
38 *
39 * @return $this
40 */
41 public function setId($id)
42 {
43 $this->id = $id;
44 return $this;
45 }
46
47 /**
48 * Identifier of the agreement.
49 *
50 * @return string
51 */
52 public function getId()
53 {
54 return $this->id;
55 }
56
57 /**
58 * State of the agreement.
59 *
60 * @param string $state
61 *
62 * @return $this
63 */
64 public function setState($state)
65 {
66 $this->state = $state;
67 return $this;
68 }
69
70 /**
71 * State of the agreement.
72 *
73 * @return string
74 */
75 public function getState()
76 {
77 return $this->state;
78 }
79
80 /**
81 * Name of the agreement.
82 *
83 * @param string $name
84 *
85 * @return $this
86 */
87 public function setName($name)
88 {
89 $this->name = $name;
90 return $this;
91 }
92
93 /**
94 * Name of the agreement.
95 *
96 * @return string
97 */
98 public function getName()
99 {
100 return $this->name;
101 }
102
103 /**
104 * Description of the agreement.
105 *
106 * @param string $description
107 *
108 * @return $this
109 */
110 public function setDescription($description)
111 {
112 $this->description = $description;
113 return $this;
114 }
115
116 /**
117 * Description of the agreement.
118 *
119 * @return string
120 */
121 public function getDescription()
122 {
123 return $this->description;
124 }
125
126 /**
127 * Start date of the agreement. Date format yyyy-MM-dd z, as defined in [ISO8601](http://tools.ietf.org/html/rfc3339#section-5.6).
128 *
129 * @param string $start_date
130 *
131 * @return $this
132 */
133 public function setStartDate($start_date)
134 {
135 $this->start_date = $start_date;
136 return $this;
137 }
138
139 /**
140 * Start date of the agreement. Date format yyyy-MM-dd z, as defined in [ISO8601](http://tools.ietf.org/html/rfc3339#section-5.6).
141 *
142 * @return string
143 */
144 public function getStartDate()
145 {
146 return $this->start_date;
147 }
148
149 /**
150 * Details of the buyer who is enrolling in this agreement. This information is gathered from execution of the approval URL.
151 *
152 * @param \PayPal\Api\Payer $payer
153 *
154 * @return $this
155 */
156 public function setPayer($payer)
157 {
158 $this->payer = $payer;
159 return $this;
160 }
161
162 /**
163 * Details of the buyer who is enrolling in this agreement. This information is gathered from execution of the approval URL.
164 *
165 * @return \PayPal\Api\Payer
166 */
167 public function getPayer()
168 {
169 return $this->payer;
170 }
171
172 /**
173 * Shipping address object of the agreement, which should be provided if it is different from the default address.
174 *
175 * @param \PayPal\Api\Address $shipping_address
176 *
177 * @return $this
178 */
179 public function setShippingAddress($shipping_address)
180 {
181 $this->shipping_address = $shipping_address;
182 return $this;
183 }
184
185 /**
186 * Shipping address object of the agreement, which should be provided if it is different from the default address.
187 *
188 * @return \PayPal\Api\Address
189 */
190 public function getShippingAddress()
191 {
192 return $this->shipping_address;
193 }
194
195 /**
196 * Default merchant preferences from the billing plan are used, unless override preferences are provided here.
197 *
198 * @param \PayPal\Api\MerchantPreferences $override_merchant_preferences
199 *
200 * @return $this
201 */
202 public function setOverrideMerchantPreferences($override_merchant_preferences)
203 {
204 $this->override_merchant_preferences = $override_merchant_preferences;
205 return $this;
206 }
207
208 /**
209 * Default merchant preferences from the billing plan are used, unless override preferences are provided here.
210 *
211 * @return \PayPal\Api\MerchantPreferences
212 */
213 public function getOverrideMerchantPreferences()
214 {
215 return $this->override_merchant_preferences;
216 }
217
218 /**
219 * Array of override_charge_model for this agreement if needed to change the default models from the billing plan.
220 *
221 * @param \PayPal\Api\OverrideChargeModel[] $override_charge_models
222 *
223 * @return $this
224 */
225 public function setOverrideChargeModels($override_charge_models)
226 {
227 $this->override_charge_models = $override_charge_models;
228 return $this;
229 }
230
231 /**
232 * Array of override_charge_model for this agreement if needed to change the default models from the billing plan.
233 *
234 * @return \PayPal\Api\OverrideChargeModel[]
235 */
236 public function getOverrideChargeModels()
237 {
238 return $this->override_charge_models;
239 }
240
241 /**
242 * Append OverrideChargeModels to the list.
243 *
244 * @param \PayPal\Api\OverrideChargeModel $overrideChargeModel
245 * @return $this
246 */
247 public function addOverrideChargeModel($overrideChargeModel)
248 {
249 if (!$this->getOverrideChargeModels()) {
250 return $this->setOverrideChargeModels(array($overrideChargeModel));
251 } else {
252 return $this->setOverrideChargeModels(
253 array_merge($this->getOverrideChargeModels(), array($overrideChargeModel))
254 );
255 }
256 }
257
258 /**
259 * Remove OverrideChargeModels from the list.
260 *
261 * @param \PayPal\Api\OverrideChargeModel $overrideChargeModel
262 * @return $this
263 */
264 public function removeOverrideChargeModel($overrideChargeModel)
265 {
266 return $this->setOverrideChargeModels(
267 array_diff($this->getOverrideChargeModels(), array($overrideChargeModel))
268 );
269 }
270
271 /**
272 * Plan details for this agreement.
273 *
274 * @param \PayPal\Api\Plan $plan
275 *
276 * @return $this
277 */
278 public function setPlan($plan)
279 {
280 $this->plan = $plan;
281 return $this;
282 }
283
284 /**
285 * Plan details for this agreement.
286 *
287 * @return \PayPal\Api\Plan
288 */
289 public function getPlan()
290 {
291 return $this->plan;
292 }
293
294 /**
295 * Date and time that this resource was created. Date format yyyy-MM-dd z, as defined in [ISO8601](http://tools.ietf.org/html/rfc3339#section-5.6).
296 *
297 * @param string $create_time
298 *
299 * @return $this
300 */
301 public function setCreateTime($create_time)
302 {
303 $this->create_time = $create_time;
304 return $this;
305 }
306
307 /**
308 * Date and time that this resource was created. Date format yyyy-MM-dd z, as defined in [ISO8601](http://tools.ietf.org/html/rfc3339#section-5.6).
309 *
310 * @return string
311 */
312 public function getCreateTime()
313 {
314 return $this->create_time;
315 }
316
317 /**
318 * Date and time that this resource was updated. Date format yyyy-MM-dd z, as defined in [ISO8601](http://tools.ietf.org/html/rfc3339#section-5.6).
319 *
320 * @param string $update_time
321 *
322 * @return $this
323 */
324 public function setUpdateTime($update_time)
325 {
326 $this->update_time = $update_time;
327 return $this;
328 }
329
330 /**
331 * Date and time that this resource was updated. Date format yyyy-MM-dd z, as defined in [ISO8601](http://tools.ietf.org/html/rfc3339#section-5.6).
332 *
333 * @return string
334 */
335 public function getUpdateTime()
336 {
337 return $this->update_time;
338 }
339
340 /**
341 * Agreement Details
342 *
343 * @param \PayPal\Api\AgreementDetails $agreement_details
344 *
345 * @return $this
346 */
347 public function setAgreementDetails($agreement_details)
348 {
349 $this->agreement_details = $agreement_details;
350 return $this;
351 }
352
353 /**
354 * Agreement Details
355 *
356 * @return \PayPal\Api\AgreementDetails
357 */
358 public function getAgreementDetails()
359 {
360 return $this->agreement_details;
361 }
362
363 /**
364 * Get Approval Link
365 *
366 * @return null|string
367 */
368 public function getApprovalLink()
369 {
370 return $this->getLink(PayPalConstants::APPROVAL_URL);
371 }
372
373 /**
374 * Create a new billing agreement by passing the details for the agreement, including the name, description, start date, payer, and billing plan in the request JSON.
375 *
376 * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
377 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
378 * @return Agreement
379 */
380 public function create($apiContext = null, $restCall = null)
381 {
382 $payLoad = $this->toJSON();
383 $json = self::executeCall(
384 "/v1/payments/billing-agreements/",
385 "POST",
386 $payLoad,
387 null,
388 $apiContext,
389 $restCall
390 );
391 $this->fromJson($json);
392 return $this;
393 }
394
395 /**
396 * Execute a billing agreement after buyer approval by passing the payment token to the request URI.
397 *
398 * @param $paymentToken
399 * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
400 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
401 * @return Agreement
402 */
403 public function execute($paymentToken, $apiContext = null, $restCall = null)
404 {
405 ArgumentValidator::validate($paymentToken, 'paymentToken');
406 $payLoad = "";
407 $json = self::executeCall(
408 "/v1/payments/billing-agreements/$paymentToken/agreement-execute",
409 "POST",
410 $payLoad,
411 null,
412 $apiContext,
413 $restCall
414 );
415 $this->fromJson($json);
416 return $this;
417 }
418
419 /**
420 * Retrieve details for a particular billing agreement by passing the ID of the agreement to the request URI.
421 *
422 * @param string $agreementId
423 * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
424 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
425 * @return Agreement
426 */
427 public static function get($agreementId, $apiContext = null, $restCall = null)
428 {
429 ArgumentValidator::validate($agreementId, 'agreementId');
430 $payLoad = "";
431 $json = self::executeCall(
432 "/v1/payments/billing-agreements/$agreementId",
433 "GET",
434 $payLoad,
435 null,
436 $apiContext,
437 $restCall
438 );
439 $ret = new Agreement();
440 $ret->fromJson($json);
441 return $ret;
442 }
443
444 /**
445 * Update details of a billing agreement, such as the description, shipping address, and start date, by passing the ID of the agreement to the request URI.
446 *
447 * @param PatchRequest $patchRequest
448 * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
449 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
450 * @return bool
451 */
452 public function update($patchRequest, $apiContext = null, $restCall = null)
453 {
454 ArgumentValidator::validate($this->getId(), "Id");
455 ArgumentValidator::validate($patchRequest, 'patchRequest');
456 $payLoad = $patchRequest->toJSON();
457 self::executeCall(
458 "/v1/payments/billing-agreements/{$this->getId()}",
459 "PATCH",
460 $payLoad,
461 null,
462 $apiContext,
463 $restCall
464 );
465 return true;
466 }
467
468 /**
469 * Suspend a particular billing agreement by passing the ID of the agreement to the request URI.
470 *
471 * @param AgreementStateDescriptor $agreementStateDescriptor
472 * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
473 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
474 * @return bool
475 */
476 public function suspend($agreementStateDescriptor, $apiContext = null, $restCall = null)
477 {
478 ArgumentValidator::validate($this->getId(), "Id");
479 ArgumentValidator::validate($agreementStateDescriptor, 'agreementStateDescriptor');
480 $payLoad = $agreementStateDescriptor->toJSON();
481 self::executeCall(
482 "/v1/payments/billing-agreements/{$this->getId()}/suspend",
483 "POST",
484 $payLoad,
485 null,
486 $apiContext,
487 $restCall
488 );
489 return true;
490 }
491
492 /**
493 * Reactivate a suspended billing agreement by passing the ID of the agreement to the appropriate URI. In addition, pass an agreement_state_descriptor object in the request JSON that includes a note about the reason for changing the state of the agreement and the amount and currency for the agreement.
494 *
495 * @param AgreementStateDescriptor $agreementStateDescriptor
496 * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
497 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
498 * @return bool
499 */
500 public function reActivate($agreementStateDescriptor, $apiContext = null, $restCall = null)
501 {
502 ArgumentValidator::validate($this->getId(), "Id");
503 ArgumentValidator::validate($agreementStateDescriptor, 'agreementStateDescriptor');
504 $payLoad = $agreementStateDescriptor->toJSON();
505 self::executeCall(
506 "/v1/payments/billing-agreements/{$this->getId()}/re-activate",
507 "POST",
508 $payLoad,
509 null,
510 $apiContext,
511 $restCall
512 );
513 return true;
514 }
515
516 /**
517 * Cancel a billing agreement by passing the ID of the agreement to the request URI. In addition, pass an agreement_state_descriptor object in the request JSON that includes a note about the reason for changing the state of the agreement and the amount and currency for the agreement.
518 *
519 * @param AgreementStateDescriptor $agreementStateDescriptor
520 * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
521 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
522 * @return bool
523 */
524 public function cancel($agreementStateDescriptor, $apiContext = null, $restCall = null)
525 {
526 ArgumentValidator::validate($this->getId(), "Id");
527 ArgumentValidator::validate($agreementStateDescriptor, 'agreementStateDescriptor');
528 $payLoad = $agreementStateDescriptor->toJSON();
529 self::executeCall(
530 "/v1/payments/billing-agreements/{$this->getId()}/cancel",
531 "POST",
532 $payLoad,
533 null,
534 $apiContext,
535 $restCall
536 );
537 return true;
538 }
539
540 /**
541 * Bill an outstanding amount for an agreement by passing the ID of the agreement to the request URI. In addition, pass an agreement_state_descriptor object in the request JSON that includes a note about the reason for changing the state of the agreement and the amount and currency for the agreement.
542 *
543 * @param AgreementStateDescriptor $agreementStateDescriptor
544 * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
545 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
546 * @return bool
547 */
548 public function billBalance($agreementStateDescriptor, $apiContext = null, $restCall = null)
549 {
550 ArgumentValidator::validate($this->getId(), "Id");
551 ArgumentValidator::validate($agreementStateDescriptor, 'agreementStateDescriptor');
552 $payLoad = $agreementStateDescriptor->toJSON();
553 self::executeCall(
554 "/v1/payments/billing-agreements/{$this->getId()}/bill-balance",
555 "POST",
556 $payLoad,
557 null,
558 $apiContext,
559 $restCall
560 );
561 return true;
562 }
563
564 /**
565 * Set the balance for an agreement by passing the ID of the agreement to the request URI. In addition, pass a common_currency object in the request JSON that specifies the currency type and value of the balance.
566 *
567 * @param Currency $currency
568 * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
569 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
570 * @return bool
571 */
572 public function setBalance($currency, $apiContext = null, $restCall = null)
573 {
574 ArgumentValidator::validate($this->getId(), "Id");
575 ArgumentValidator::validate($currency, 'currency');
576 $payLoad = $currency->toJSON();
577 self::executeCall(
578 "/v1/payments/billing-agreements/{$this->getId()}/set-balance",
579 "POST",
580 $payLoad,
581 null,
582 $apiContext,
583 $restCall
584 );
585 return true;
586 }
587
588 /**
589 * List transactions for a billing agreement by passing the ID of the agreement, as well as the start and end dates of the range of transactions to list, to the request URI.
590 *
591 * @deprecated Please use searchTransactions Instead
592 * @param string $agreementId
593 * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
594 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
595 * @return AgreementTransactions
596 */
597 public static function transactions($agreementId, $apiContext = null, $restCall = null)
598 {
599 ArgumentValidator::validate($agreementId, 'agreementId');
600 $payLoad = "";
601 $json = self::executeCall(
602 "/v1/payments/billing-agreements/$agreementId/transactions",
603 "GET",
604 $payLoad,
605 null,
606 $apiContext,
607 $restCall
608 );
609 $ret = new AgreementTransactions();
610 $ret->fromJson($json);
611 return $ret;
612 }
613
614 /**
615 * List transactions for a billing agreement by passing the ID of the agreement, as well as the start and end dates of the range of transactions to list, to the request URI.
616 *
617 * @param string $agreementId
618 * @param array $params Parameters for search string. Options: start_date, and end_date
619 * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
620 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
621 * @return AgreementTransactions
622 */
623 public static function searchTransactions($agreementId, $params = array(), $apiContext = null, $restCall = null)
624 {
625 ArgumentValidator::validate($agreementId, 'agreementId');
626 ArgumentValidator::validate($params, 'params');
627
628 $allowedParams = array(
629 'start_date' => 1,
630 'end_date' => 1,
631 );
632
633 $payLoad = "";
634 $json = self::executeCall(
635 "/v1/payments/billing-agreements/$agreementId/transactions?" . http_build_query(array_intersect_key($params, $allowedParams)),
636 "GET",
637 $payLoad,
638 null,
639 $apiContext,
640 $restCall
641 );
642 $ret = new AgreementTransactions();
643 $ret->fromJson($json);
644 return $ret;
645 }
646
647 }
648