1 <?php
2
3 namespace PayPal\Api;
4
5 use PayPal\Common\PayPalResourceModel;
6 use PayPal\Core\PayPalConstants;
7 use PayPal\Validation\ArgumentValidator;
8 use PayPal\Rest\ApiContext;
9
10 /**
11 * Class Payment
12 *
13 * Lets you create, process and manage payments.
14 *
15 * @package PayPal\Api
16 *
17 * @property string id
18 * @property string intent
19 * @property \PayPal\Api\Payer payer
20 * @property \PayPal\Api\Transaction[] transactions
21 * @property string state
22 * @property string experience_profile_id
23 * @property string note_to_payer
24 * @property \PayPal\Api\Payee $payee
25 * @property \PayPal\Api\RedirectUrls redirect_urls
26 * @property string failure_reason
27 * @property string create_time
28 * @property string update_time
29 * @property \PayPal\Api\Links[] links
30 */
31 class Payment extends PayPalResourceModel
32 {
33 /**
34 * Identifier of the payment resource created.
35 *
36 * @param string $id
37 *
38 * @return $this
39 */
40 public function setId($id)
41 {
42 $this->id = $id;
43 return $this;
44 }
45
46 /**
47 * Identifier of the payment resource created.
48 *
49 * @return string
50 */
51 public function getId()
52 {
53 return $this->id;
54 }
55
56 /**
57 * Payment intent.
58 * Valid Values: ["sale", "authorize", "order"]
59 *
60 * @param string $intent
61 *
62 * @return $this
63 */
64 public function setIntent($intent)
65 {
66 $this->intent = $intent;
67 return $this;
68 }
69
70 /**
71 * Payment intent.
72 *
73 * @return string
74 */
75 public function getIntent()
76 {
77 return $this->intent;
78 }
79
80 /**
81 * Source of the funds for this payment represented by a PayPal account or a direct credit card.
82 *
83 * @param \PayPal\Api\Payer $payer
84 *
85 * @return $this
86 */
87 public function setPayer($payer)
88 {
89 $this->payer = $payer;
90 return $this;
91 }
92
93 /**
94 * Source of the funds for this payment represented by a PayPal account or a direct credit card.
95 *
96 * @return \PayPal\Api\Payer
97 */
98 public function getPayer()
99 {
100 return $this->payer;
101 }
102
103 /**
104 * Information that the merchant knows about the payer. This information is not definitive and only serves as a hint to the UI or any pre-processing logic.
105 * @deprecated Not publicly available
106 * @param \PayPal\Api\PotentialPayerInfo $potential_payer_info
107 *
108 * @return $this
109 */
110 public function setPotentialPayerInfo($potential_payer_info)
111 {
112 $this->potential_payer_info = $potential_payer_info;
113 return $this;
114 }
115
116 /**
117 * Information that the merchant knows about the payer. This information is not definitive and only serves as a hint to the UI or any pre-processing logic.
118 * @deprecated Not publicly available
119 * @return \PayPal\Api\PotentialPayerInfo
120 */
121 public function getPotentialPayerInfo()
122 {
123 return $this->potential_payer_info;
124 }
125
126 /**
127 * Receiver of funds for this payment.
128 * @param \PayPal\Api\Payee $payee
129 *
130 * @return $this
131 */
132 public function setPayee($payee)
133 {
134 $this->payee = $payee;
135 return $this;
136 }
137
138 /**
139 * Receiver of funds for this payment.
140 * @return \PayPal\Api\Payee
141 */
142 public function getPayee()
143 {
144 return $this->payee;
145 }
146
147 /**
148 * ID of the cart to execute the payment.
149 * @deprecated Not publicly available
150 * @param string $cart
151 *
152 * @return $this
153 */
154 public function setCart($cart)
155 {
156 $this->cart = $cart;
157 return $this;
158 }
159
160 /**
161 * ID of the cart to execute the payment.
162 * @deprecated Not publicly available
163 * @return string
164 */
165 public function getCart()
166 {
167 return $this->cart;
168 }
169
170 /**
171 * Transactional details including the amount and item details.
172 *
173 * @param \PayPal\Api\Transaction[] $transactions
174 *
175 * @return $this
176 */
177 public function setTransactions($transactions)
178 {
179 $this->transactions = $transactions;
180 return $this;
181 }
182
183 /**
184 * Transactional details including the amount and item details.
185 *
186 * @return \PayPal\Api\Transaction[]
187 */
188 public function getTransactions()
189 {
190 return $this->transactions;
191 }
192
193 /**
194 * Append Transactions to the list.
195 *
196 * @param \PayPal\Api\Transaction $transaction
197 * @return $this
198 */
199 public function addTransaction($transaction)
200 {
201 if (!$this->getTransactions()) {
202 return $this->setTransactions(array($transaction));
203 } else {
204 return $this->setTransactions(
205 array_merge($this->getTransactions(), array($transaction))
206 );
207 }
208 }
209
210 /**
211 * Remove Transactions from the list.
212 *
213 * @param \PayPal\Api\Transaction $transaction
214 * @return $this
215 */
216 public function removeTransaction($transaction)
217 {
218 return $this->setTransactions(
219 array_diff($this->getTransactions(), array($transaction))
220 );
221 }
222
223 /**
224 * Applicable for advanced payments like multi seller payment (MSP) to support partial failures
225 * @deprecated Not publicly available
226 * @param \PayPal\Api\Error[] $failed_transactions
227 *
228 * @return $this
229 */
230 public function setFailedTransactions($failed_transactions)
231 {
232 $this->failed_transactions = $failed_transactions;
233 return $this;
234 }
235
236 /**
237 * Applicable for advanced payments like multi seller payment (MSP) to support partial failures
238 * @deprecated Not publicly available
239 * @return \PayPal\Api\Error[]
240 */
241 public function getFailedTransactions()
242 {
243 return $this->failed_transactions;
244 }
245
246 /**
247 * Append FailedTransactions to the list.
248 * @deprecated Not publicly available
249 * @param \PayPal\Api\Error $error
250 * @return $this
251 */
252 public function addFailedTransaction($error)
253 {
254 if (!$this->getFailedTransactions()) {
255 return $this->setFailedTransactions(array($error));
256 } else {
257 return $this->setFailedTransactions(
258 array_merge($this->getFailedTransactions(), array($error))
259 );
260 }
261 }
262
263 /**
264 * Remove FailedTransactions from the list.
265 * @deprecated Not publicly available
266 * @param \PayPal\Api\Error $error
267 * @return $this
268 */
269 public function removeFailedTransaction($error)
270 {
271 return $this->setFailedTransactions(
272 array_diff($this->getFailedTransactions(), array($error))
273 );
274 }
275
276 /**
277 * Collection of PayPal generated billing agreement tokens.
278 * @deprecated Not publicly available
279 * @param string[] $billing_agreement_tokens
280 *
281 * @return $this
282 */
283 public function setBillingAgreementTokens($billing_agreement_tokens)
284 {
285 $this->billing_agreement_tokens = $billing_agreement_tokens;
286 return $this;
287 }
288
289 /**
290 * Collection of PayPal generated billing agreement tokens.
291 * @deprecated Not publicly available
292 * @return string[]
293 */
294 public function getBillingAgreementTokens()
295 {
296 return $this->billing_agreement_tokens;
297 }
298
299 /**
300 * Append BillingAgreementTokens to the list.
301 * @deprecated Not publicly available
302 * @param string $billingAgreementToken
303 * @return $this
304 */
305 public function addBillingAgreementToken($billingAgreementToken)
306 {
307 if (!$this->getBillingAgreementTokens()) {
308 return $this->setBillingAgreementTokens(array($billingAgreementToken));
309 } else {
310 return $this->setBillingAgreementTokens(
311 array_merge($this->getBillingAgreementTokens(), array($billingAgreementToken))
312 );
313 }
314 }
315
316 /**
317 * Remove BillingAgreementTokens from the list.
318 * @deprecated Not publicly available
319 * @param string $billingAgreementToken
320 * @return $this
321 */
322 public function removeBillingAgreementToken($billingAgreementToken)
323 {
324 return $this->setBillingAgreementTokens(
325 array_diff($this->getBillingAgreementTokens(), array($billingAgreementToken))
326 );
327 }
328
329 /**
330 * Credit financing offered to payer on PayPal side. Returned in payment after payer opts-in
331 * @deprecated Not publicly available
332 * @param \PayPal\Api\CreditFinancingOffered $credit_financing_offered
333 *
334 * @return $this
335 */
336 public function setCreditFinancingOffered($credit_financing_offered)
337 {
338 $this->credit_financing_offered = $credit_financing_offered;
339 return $this;
340 }
341
342 /**
343 * Credit financing offered to payer on PayPal side. Returned in payment after payer opts-in
344 * @deprecated Not publicly available
345 * @return \PayPal\Api\CreditFinancingOffered
346 */
347 public function getCreditFinancingOffered()
348 {
349 return $this->credit_financing_offered;
350 }
351
352 /**
353 * Instructions for the payer to complete this payment.
354 * @deprecated Not publicly available
355 * @param \PayPal\Api\PaymentInstruction $payment_instruction
356 *
357 * @return $this
358 */
359 public function setPaymentInstruction($payment_instruction)
360 {
361 $this->payment_instruction = $payment_instruction;
362 return $this;
363 }
364
365 /**
366 * Instructions for the payer to complete this payment.
367 * @deprecated Not publicly available
368 * @return \PayPal\Api\PaymentInstruction
369 */
370 public function getPaymentInstruction()
371 {
372 return $this->payment_instruction;
373 }
374
375 /**
376 * The state of the payment, authorization, or order transaction. The value is:<ul><li><code>created</code>. The transaction was successfully created.</li><li><code>approved</code>. The buyer approved the transaction.</li><li><code>failed</code>. The transaction request failed.</li></ul>
377 * Valid Values: ["created", "approved", "failed", "partially_completed", "in_progress"]
378 *
379 * @param string $state
380 *
381 * @return $this
382 */
383 public function setState($state)
384 {
385 $this->state = $state;
386 return $this;
387 }
388
389 /**
390 * The state of the payment, authorization, or order transaction. The value is:<ul><li><code>created</code>. The transaction was successfully created.</li><li><code>approved</code>. The buyer approved the transaction.</li><li><code>failed</code>. The transaction request failed.</li></ul>
391 *
392 * @return string
393 */
394 public function getState()
395 {
396 return $this->state;
397 }
398
399 /**
400 * PayPal generated identifier for the merchant's payment experience profile. Refer to [this](https://developer.paypal.com/docs/api/#payment-experience) link to create experience profile ID.
401 *
402 * @param string $experience_profile_id
403 *
404 * @return $this
405 */
406 public function setExperienceProfileId($experience_profile_id)
407 {
408 $this->experience_profile_id = $experience_profile_id;
409 return $this;
410 }
411
412 /**
413 * PayPal generated identifier for the merchant's payment experience profile. Refer to [this](https://developer.paypal.com/docs/api/#payment-experience) link to create experience profile ID.
414 *
415 * @return string
416 */
417 public function getExperienceProfileId()
418 {
419 return $this->experience_profile_id;
420 }
421
422 /**
423 * free-form field for the use of clients to pass in a message to the payer
424 *
425 * @param string $note_to_payer
426 *
427 * @return $this
428 */
429 public function setNoteToPayer($note_to_payer)
430 {
431 $this->note_to_payer = $note_to_payer;
432 return $this;
433 }
434
435 /**
436 * free-form field for the use of clients to pass in a message to the payer
437 *
438 * @return string
439 */
440 public function getNoteToPayer()
441 {
442 return $this->note_to_payer;
443 }
444
445 /**
446 * Set of redirect URLs you provide only for PayPal-based payments.
447 *
448 * @param \PayPal\Api\RedirectUrls $redirect_urls
449 *
450 * @return $this
451 */
452 public function setRedirectUrls($redirect_urls)
453 {
454 $this->redirect_urls = $redirect_urls;
455 return $this;
456 }
457
458 /**
459 * Set of redirect URLs you provide only for PayPal-based payments.
460 *
461 * @return \PayPal\Api\RedirectUrls
462 */
463 public function getRedirectUrls()
464 {
465 return $this->redirect_urls;
466 }
467
468 /**
469 * Failure reason code returned when the payment failed for some valid reasons.
470 * Valid Values: ["UNABLE_TO_COMPLETE_TRANSACTION", "INVALID_PAYMENT_METHOD", "PAYER_CANNOT_PAY", "CANNOT_PAY_THIS_PAYEE", "REDIRECT_REQUIRED", "PAYEE_FILTER_RESTRICTIONS"]
471 *
472 * @param string $failure_reason
473 *
474 * @return $this
475 */
476 public function setFailureReason($failure_reason)
477 {
478 $this->failure_reason = $failure_reason;
479 return $this;
480 }
481
482 /**
483 * Failure reason code returned when the payment failed for some valid reasons.
484 *
485 * @return string
486 */
487 public function getFailureReason()
488 {
489 return $this->failure_reason;
490 }
491
492 /**
493 * Payment creation time as defined in [RFC 3339 Section 5.6](http://tools.ietf.org/html/rfc3339#section-5.6).
494 *
495 * @param string $create_time
496 *
497 * @return $this
498 */
499 public function setCreateTime($create_time)
500 {
501 $this->create_time = $create_time;
502 return $this;
503 }
504
505 /**
506 * Payment creation time as defined in [RFC 3339 Section 5.6](http://tools.ietf.org/html/rfc3339#section-5.6).
507 *
508 * @return string
509 */
510 public function getCreateTime()
511 {
512 return $this->create_time;
513 }
514
515 /**
516 * Payment update time as defined in [RFC 3339 Section 5.6](http://tools.ietf.org/html/rfc3339#section-5.6).
517 *
518 * @param string $update_time
519 *
520 * @return $this
521 */
522 public function setUpdateTime($update_time)
523 {
524 $this->update_time = $update_time;
525 return $this;
526 }
527
528 /**
529 * Payment update time as defined in [RFC 3339 Section 5.6](http://tools.ietf.org/html/rfc3339#section-5.6).
530 *
531 * @return string
532 */
533 public function getUpdateTime()
534 {
535 return $this->update_time;
536 }
537
538 /**
539 * Get Approval Link
540 *
541 * @return null|string
542 */
543 public function getApprovalLink()
544 {
545 return $this->getLink(PayPalConstants::APPROVAL_URL);
546 }
547
548 /**
549 * Get token from Approval Link
550 *
551 * @return null|string
552 */
553 public function getToken()
554 {
555 $parameter_name = "token";
556 parse_str(parse_url($this->getApprovalLink(), PHP_URL_QUERY), $query);
557 return !isset($query[$parameter_name]) ? null : $query[$parameter_name];
558 }
559
560 /**
561 * Creates and processes a payment. In the JSON request body, include a `payment` object with the intent, payer, and transactions. For PayPal payments, include redirect URLs in the `payment` object.
562 *
563 * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
564 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
565 * @return Payment
566 */
567 public function create($apiContext = null, $restCall = null)
568 {
569 $payLoad = $this->toJSON();
570 $json = self::executeCall(
571 "/v1/payments/payment",
572 "POST",
573 $payLoad,
574 null,
575 $apiContext,
576 $restCall
577 );
578 $this->fromJson($json);
579 return $this;
580 }
581
582 /**
583 * Shows details for a payment, by ID.
584 *
585 * @param string $paymentId
586 * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
587 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
588 * @return Payment
589 */
590 public static function get($paymentId, $apiContext = null, $restCall = null)
591 {
592 ArgumentValidator::validate($paymentId, 'paymentId');
593 $payLoad = "";
594 $json = self::executeCall(
595 "/v1/payments/payment/$paymentId",
596 "GET",
597 $payLoad,
598 null,
599 $apiContext,
600 $restCall
601 );
602 $ret = new Payment();
603 $ret->fromJson($json);
604 return $ret;
605 }
606
607 /**
608 * Partially updates a payment, by ID. You can update the amount, shipping address, invoice ID, and custom data. You cannot use patch after execute has been called.
609 *
610 * @param PatchRequest $patchRequest
611 * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
612 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
613 * @return boolean
614 */
615 public function update($patchRequest, $apiContext = null, $restCall = null)
616 {
617 ArgumentValidator::validate($this->getId(), "Id");
618 ArgumentValidator::validate($patchRequest, 'patchRequest');
619 $payLoad = $patchRequest->toJSON();
620 self::executeCall(
621 "/v1/payments/payment/{$this->getId()}",
622 "PATCH",
623 $payLoad,
624 null,
625 $apiContext,
626 $restCall
627 );
628 return true;
629 }
630
631 /**
632 * Executes, or completes, a PayPal payment that the payer has approved. You can optionally update selective payment information when you execute a payment.
633 *
634 * @param PaymentExecution $paymentExecution
635 * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
636 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
637 * @return Payment
638 */
639 public function execute($paymentExecution, $apiContext = null, $restCall = null)
640 {
641 ArgumentValidator::validate($this->getId(), "Id");
642 ArgumentValidator::validate($paymentExecution, 'paymentExecution');
643 $payLoad = $paymentExecution->toJSON();
644 $json = self::executeCall(
645 "/v1/payments/payment/{$this->getId()}/execute",
646 "POST",
647 $payLoad,
648 null,
649 $apiContext,
650 $restCall
651 );
652 $this->fromJson($json);
653 return $this;
654 }
655
656 /**
657 * List payments that were made to the merchant who issues the request. Payments can be in any state.
658 *
659 * @param array $params
660 * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
661 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
662 * @return PaymentHistory
663 */
664 public static function all($params, $apiContext = null, $restCall = null)
665 {
666 ArgumentValidator::validate($params, 'params');
667 $payLoad = "";
668 $allowedParams = array(
669 'count' => 1,
670 'start_id' => 1,
671 'start_index' => 1,
672 'start_time' => 1,
673 'end_time' => 1,
674 'payee_id' => 1,
675 'sort_by' => 1,
676 'sort_order' => 1,
677 );
678 $json = self::executeCall(
679 "/v1/payments/payment?" . http_build_query(array_intersect_key($params, $allowedParams)),
680 "GET",
681 $payLoad,
682 null,
683 $apiContext,
684 $restCall
685 );
686 $ret = new PaymentHistory();
687 $ret->fromJson($json);
688 return $ret;
689 }
690
691 }
692