1 <?php
2
3 namespace PayPal\Api;
4
5 use PayPal\Common\PayPalResourceModel;
6 use PayPal\Validation\ArgumentValidator;
7 use PayPal\Rest\ApiContext;
8
9 /**
10 * Class Sale
11 *
12 * A sale transaction. This is the resource that is returned as a part related resources in Payment
13 *
14 * @package PayPal\Api
15 *
16 * @property string id
17 * @property string purchase_unit_reference_id
18 * @property \PayPal\Api\Amount amount
19 * @property string payment_mode
20 * @property string state
21 * @property string reason_code
22 * @property string protection_eligibility
23 * @property string protection_eligibility_type
24 * @property string clearing_time
25 * @property string payment_hold_status
26 * @property string[] payment_hold_reasons
27 * @property \PayPal\Api\Currency transaction_fee
28 * @property \PayPal\Api\Currency receivable_amount
29 * @property string exchange_rate
30 * @property \PayPal\Api\FmfDetails fmf_details
31 * @property string receipt_id
32 * @property string parent_payment
33 * @property \PayPal\Api\ProcessorResponse processor_response
34 * @property string billing_agreement_id
35 * @property string create_time
36 * @property string update_time
37 * @property \PayPal\Api\Links[] links
38 */
39 class Sale extends PayPalResourceModel
40 {
41 /**
42 * Identifier of the sale transaction.
43 *
44 * @param string $id
45 *
46 * @return $this
47 */
48 public function setId($id)
49 {
50 $this->id = $id;
51 return $this;
52 }
53
54 /**
55 * Identifier of the sale transaction.
56 *
57 * @return string
58 */
59 public function getId()
60 {
61 return $this->id;
62 }
63
64 /**
65 * Identifier to the purchase or transaction unit corresponding to this sale transaction.
66 *
67 * @param string $purchase_unit_reference_id
68 *
69 * @return $this
70 */
71 public function setPurchaseUnitReferenceId($purchase_unit_reference_id)
72 {
73 $this->purchase_unit_reference_id = $purchase_unit_reference_id;
74 return $this;
75 }
76
77 /**
78 * Identifier to the purchase or transaction unit corresponding to this sale transaction.
79 *
80 * @return string
81 */
82 public function getPurchaseUnitReferenceId()
83 {
84 return $this->purchase_unit_reference_id;
85 }
86
87 /**
88 * Amount being collected.
89 *
90 * @param \PayPal\Api\Amount $amount
91 *
92 * @return $this
93 */
94 public function setAmount($amount)
95 {
96 $this->amount = $amount;
97 return $this;
98 }
99
100 /**
101 * Amount being collected.
102 *
103 * @return \PayPal\Api\Amount
104 */
105 public function getAmount()
106 {
107 return $this->amount;
108 }
109
110 /**
111 * Specifies payment mode of the transaction. Only supported when the `payment_method` is set to `paypal`.
112 * Valid Values: ["INSTANT_TRANSFER", "MANUAL_BANK_TRANSFER", "DELAYED_TRANSFER", "ECHECK"]
113 *
114 * @param string $payment_mode
115 *
116 * @return $this
117 */
118 public function setPaymentMode($payment_mode)
119 {
120 $this->payment_mode = $payment_mode;
121 return $this;
122 }
123
124 /**
125 * Specifies payment mode of the transaction. Only supported when the `payment_method` is set to `paypal`.
126 *
127 * @return string
128 */
129 public function getPaymentMode()
130 {
131 return $this->payment_mode;
132 }
133
134 /**
135 * State of the sale transaction.
136 * Valid Values: ["completed", "partially_refunded", "pending", "refunded", "denied"]
137 *
138 * @param string $state
139 *
140 * @return $this
141 */
142 public function setState($state)
143 {
144 $this->state = $state;
145 return $this;
146 }
147
148 /**
149 * State of the sale transaction.
150 *
151 * @return string
152 */
153 public function getState()
154 {
155 return $this->state;
156 }
157
158 /**
159 * Reason code for the transaction state being Pending or Reversed. Only supported when the `payment_method` is set to `paypal`.
160 * Valid Values: ["CHARGEBACK", "GUARANTEE", "BUYER_COMPLAINT", "REFUND", "UNCONFIRMED_SHIPPING_ADDRESS", "ECHECK", "INTERNATIONAL_WITHDRAWAL", "RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION", "PAYMENT_REVIEW", "REGULATORY_REVIEW", "UNILATERAL", "VERIFICATION_REQUIRED", "TRANSACTION_APPROVED_AWAITING_FUNDING"]
161 *
162 * @param string $reason_code
163 *
164 * @return $this
165 */
166 public function setReasonCode($reason_code)
167 {
168 $this->reason_code = $reason_code;
169 return $this;
170 }
171
172 /**
173 * Reason code for the transaction state being Pending or Reversed. Only supported when the `payment_method` is set to `paypal`.
174 *
175 * @return string
176 */
177 public function getReasonCode()
178 {
179 return $this->reason_code;
180 }
181
182 /**
183 * The level of seller protection in force for the transaction. Only supported when the `payment_method` is set to `paypal`.
184 * Valid Values: ["ELIGIBLE", "PARTIALLY_ELIGIBLE", "INELIGIBLE"]
185 *
186 * @param string $protection_eligibility
187 *
188 * @return $this
189 */
190 public function setProtectionEligibility($protection_eligibility)
191 {
192 $this->protection_eligibility = $protection_eligibility;
193 return $this;
194 }
195
196 /**
197 * The level of seller protection in force for the transaction. Only supported when the `payment_method` is set to `paypal`.
198 *
199 * @return string
200 */
201 public function getProtectionEligibility()
202 {
203 return $this->protection_eligibility;
204 }
205
206 /**
207 * The kind of seller protection in force for the transaction. It is returned only when protection_eligibility is ELIGIBLE or PARTIALLY_ELIGIBLE. Only supported when the `payment_method` is set to `paypal`.
208 * Valid Values: ["ITEM_NOT_RECEIVED_ELIGIBLE", "UNAUTHORIZED_PAYMENT_ELIGIBLE", "ITEM_NOT_RECEIVED_ELIGIBLE,UNAUTHORIZED_PAYMENT_ELIGIBLE"]
209 *
210 * @param string $protection_eligibility_type
211 *
212 * @return $this
213 */
214 public function setProtectionEligibilityType($protection_eligibility_type)
215 {
216 $this->protection_eligibility_type = $protection_eligibility_type;
217 return $this;
218 }
219
220 /**
221 * The kind of seller protection in force for the transaction. It is returned only when protection_eligibility is ELIGIBLE or PARTIALLY_ELIGIBLE. Only supported when the `payment_method` is set to `paypal`.
222 *
223 * @return string
224 */
225 public function getProtectionEligibilityType()
226 {
227 return $this->protection_eligibility_type;
228 }
229
230 /**
231 * Expected clearing time for eCheck Transactions. Returned when payment is made with eCheck. Only supported when the `payment_method` is set to `paypal`.
232 *
233 * @param string $clearing_time
234 *
235 * @return $this
236 */
237 public function setClearingTime($clearing_time)
238 {
239 $this->clearing_time = $clearing_time;
240 return $this;
241 }
242
243 /**
244 * Expected clearing time for eCheck Transactions. Returned when payment is made with eCheck. Only supported when the `payment_method` is set to `paypal`.
245 *
246 * @return string
247 */
248 public function getClearingTime()
249 {
250 return $this->clearing_time;
251 }
252
253 /**
254 * Status of the Recipient Fund. For now, it will be returned only when fund status is held
255 * Valid Values: ["HELD"]
256 *
257 * @param string $payment_hold_status
258 *
259 * @return $this
260 */
261 public function setPaymentHoldStatus($payment_hold_status)
262 {
263 $this->payment_hold_status = $payment_hold_status;
264 return $this;
265 }
266
267 /**
268 * Status of the Recipient Fund. For now, it will be returned only when fund status is held
269 *
270 * @return string
271 */
272 public function getPaymentHoldStatus()
273 {
274 return $this->payment_hold_status;
275 }
276
277 /**
278 * Reasons for PayPal holding recipient fund. It is set only if payment hold status is held
279 *
280 * @param string[] $payment_hold_reasons
281 *
282 * @return $this
283 */
284 public function setPaymentHoldReasons($payment_hold_reasons)
285 {
286 $this->payment_hold_reasons = $payment_hold_reasons;
287 return $this;
288 }
289
290 /**
291 * Reasons for PayPal holding recipient fund. It is set only if payment hold status is held
292 *
293 * @return string[]
294 */
295 public function getPaymentHoldReasons()
296 {
297 return $this->payment_hold_reasons;
298 }
299
300 /**
301 * Append PaymentHoldReasons to the list.
302 *
303 * @param string $string
304 * @return $this
305 */
306 public function addPaymentHoldReason($string)
307 {
308 if (!$this->getPaymentHoldReasons()) {
309 return $this->setPaymentHoldReasons(array($string));
310 } else {
311 return $this->setPaymentHoldReasons(
312 array_merge($this->getPaymentHoldReasons(), array($string))
313 );
314 }
315 }
316
317 /**
318 * Remove PaymentHoldReasons from the list.
319 *
320 * @param string $string
321 * @return $this
322 */
323 public function removePaymentHoldReason($string)
324 {
325 return $this->setPaymentHoldReasons(
326 array_diff($this->getPaymentHoldReasons(), array($string))
327 );
328 }
329
330 /**
331 * Transaction fee applicable for this payment.
332 *
333 * @param \PayPal\Api\Currency $transaction_fee
334 *
335 * @return $this
336 */
337 public function setTransactionFee($transaction_fee)
338 {
339 $this->transaction_fee = $transaction_fee;
340 return $this;
341 }
342
343 /**
344 * Transaction fee applicable for this payment.
345 *
346 * @return \PayPal\Api\Currency
347 */
348 public function getTransactionFee()
349 {
350 return $this->transaction_fee;
351 }
352
353 /**
354 * Net amount the merchant receives for this transaction in their receivable currency. Returned only in cross-currency use cases where a merchant bills a buyer in a non-primary currency for that buyer.
355 *
356 * @param \PayPal\Api\Currency $receivable_amount
357 *
358 * @return $this
359 */
360 public function setReceivableAmount($receivable_amount)
361 {
362 $this->receivable_amount = $receivable_amount;
363 return $this;
364 }
365
366 /**
367 * Net amount the merchant receives for this transaction in their receivable currency. Returned only in cross-currency use cases where a merchant bills a buyer in a non-primary currency for that buyer.
368 *
369 * @return \PayPal\Api\Currency
370 */
371 public function getReceivableAmount()
372 {
373 return $this->receivable_amount;
374 }
375
376 /**
377 * Exchange rate applied for this transaction. Returned only in cross-currency use cases where a merchant bills a buyer in a non-primary currency for that buyer.
378 *
379 * @param string $exchange_rate
380 *
381 * @return $this
382 */
383 public function setExchangeRate($exchange_rate)
384 {
385 $this->exchange_rate = $exchange_rate;
386 return $this;
387 }
388
389 /**
390 * Exchange rate applied for this transaction. Returned only in cross-currency use cases where a merchant bills a buyer in a non-primary currency for that buyer.
391 *
392 * @return string
393 */
394 public function getExchangeRate()
395 {
396 return $this->exchange_rate;
397 }
398
399 /**
400 * Fraud Management Filter (FMF) details applied for the payment that could result in accept, deny, or pending action. Returned in a payment response only if the merchant has enabled FMF in the profile settings and one of the fraud filters was triggered based on those settings. See [Fraud Management Filters Summary](/docs/classic/fmf/integration-guide/FMFSummary/) for more information.
401 *
402 * @param \PayPal\Api\FmfDetails $fmf_details
403 *
404 * @return $this
405 */
406 public function setFmfDetails($fmf_details)
407 {
408 $this->fmf_details = $fmf_details;
409 return $this;
410 }
411
412 /**
413 * Fraud Management Filter (FMF) details applied for the payment that could result in accept, deny, or pending action. Returned in a payment response only if the merchant has enabled FMF in the profile settings and one of the fraud filters was triggered based on those settings. See [Fraud Management Filters Summary](/docs/classic/fmf/integration-guide/FMFSummary/) for more information.
414 *
415 * @return \PayPal\Api\FmfDetails
416 */
417 public function getFmfDetails()
418 {
419 return $this->fmf_details;
420 }
421
422 /**
423 * Receipt id is a payment identification number returned for guest users to identify the payment.
424 *
425 * @param string $receipt_id
426 *
427 * @return $this
428 */
429 public function setReceiptId($receipt_id)
430 {
431 $this->receipt_id = $receipt_id;
432 return $this;
433 }
434
435 /**
436 * Receipt id is a payment identification number returned for guest users to identify the payment.
437 *
438 * @return string
439 */
440 public function getReceiptId()
441 {
442 return $this->receipt_id;
443 }
444
445 /**
446 * ID of the payment resource on which this transaction is based.
447 *
448 * @param string $parent_payment
449 *
450 * @return $this
451 */
452 public function setParentPayment($parent_payment)
453 {
454 $this->parent_payment = $parent_payment;
455 return $this;
456 }
457
458 /**
459 * ID of the payment resource on which this transaction is based.
460 *
461 * @return string
462 */
463 public function getParentPayment()
464 {
465 return $this->parent_payment;
466 }
467
468 /**
469 * Response codes returned by the processor concerning the submitted payment. Only supported when the `payment_method` is set to `credit_card`.
470 *
471 * @param \PayPal\Api\ProcessorResponse $processor_response
472 *
473 * @return $this
474 */
475 public function setProcessorResponse($processor_response)
476 {
477 $this->processor_response = $processor_response;
478 return $this;
479 }
480
481 /**
482 * Response codes returned by the processor concerning the submitted payment. Only supported when the `payment_method` is set to `credit_card`.
483 *
484 * @return \PayPal\Api\ProcessorResponse
485 */
486 public function getProcessorResponse()
487 {
488 return $this->processor_response;
489 }
490
491 /**
492 * ID of the billing agreement used as reference to execute this transaction.
493 *
494 * @param string $billing_agreement_id
495 *
496 * @return $this
497 */
498 public function setBillingAgreementId($billing_agreement_id)
499 {
500 $this->billing_agreement_id = $billing_agreement_id;
501 return $this;
502 }
503
504 /**
505 * ID of the billing agreement used as reference to execute this transaction.
506 *
507 * @return string
508 */
509 public function getBillingAgreementId()
510 {
511 return $this->billing_agreement_id;
512 }
513
514 /**
515 * Time of sale as defined in [RFC 3339 Section 5.6](http://tools.ietf.org/html/rfc3339#section-5.6)
516 *
517 * @param string $create_time
518 *
519 * @return $this
520 */
521 public function setCreateTime($create_time)
522 {
523 $this->create_time = $create_time;
524 return $this;
525 }
526
527 /**
528 * Time of sale as defined in [RFC 3339 Section 5.6](http://tools.ietf.org/html/rfc3339#section-5.6)
529 *
530 * @return string
531 */
532 public function getCreateTime()
533 {
534 return $this->create_time;
535 }
536
537 /**
538 * Time the resource was last updated in UTC ISO8601 format.
539 *
540 * @param string $update_time
541 *
542 * @return $this
543 */
544 public function setUpdateTime($update_time)
545 {
546 $this->update_time = $update_time;
547 return $this;
548 }
549
550 /**
551 * Time the resource was last updated in UTC ISO8601 format.
552 *
553 * @return string
554 */
555 public function getUpdateTime()
556 {
557 return $this->update_time;
558 }
559
560 /**
561 * Shows details for a sale, by ID. Returns only sales that were created through the REST API.
562 *
563 * @param string $saleId
564 * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
565 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
566 * @return Sale
567 */
568 public static function get($saleId, $apiContext = null, $restCall = null)
569 {
570 ArgumentValidator::validate($saleId, 'saleId');
571 $payLoad = "";
572 $json = self::executeCall(
573 "/v1/payments/sale/$saleId",
574 "GET",
575 $payLoad,
576 null,
577 $apiContext,
578 $restCall
579 );
580 $ret = new Sale();
581 $ret->fromJson($json);
582 return $ret;
583 }
584
585 /**
586 * Refund a completed payment by passing the sale_id in the request URI. In addition, include an empty JSON payload in the request body for a full refund. For a partial refund, include an amount object in the request body.
587 *
588 * @deprecated Please use #refundSale instead.
589 * @param Refund $refund
590 * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
591 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
592 * @return Refund
593 */
594 public function refund($refund, $apiContext = null, $restCall = null)
595 {
596 ArgumentValidator::validate($this->getId(), "Id");
597 ArgumentValidator::validate($refund, 'refund');
598 $payLoad = $refund->toJSON();
599 $json = self::executeCall(
600 "/v1/payments/sale/{$this->getId()}/refund",
601 "POST",
602 $payLoad,
603 null,
604 $apiContext,
605 $restCall
606 );
607 $ret = new Refund();
608 $ret->fromJson($json);
609 return $ret;
610 }
611
612 /**
613 * Refunds a sale, by ID. For a full refund, include an empty payload in the JSON request body. For a partial refund, include an `amount` object in the JSON request body.
614 *
615 * @param RefundRequest $refundRequest
616 * @param ApiContext $apiContext is the APIContext for this call. It can be used to pass dynamic configuration and credentials.
617 * @param PayPalRestCall $restCall is the Rest Call Service that is used to make rest calls
618 * @return DetailedRefund
619 */
620 public function refundSale($refundRequest, $apiContext = null, $restCall = null)
621 {
622 ArgumentValidator::validate($this->getId(), "Id");
623 ArgumentValidator::validate($refundRequest, 'refundRequest');
624 $payLoad = $refundRequest->toJSON();
625 $json = self::executeCall(
626 "/v1/payments/sale/{$this->getId()}/refund",
627 "POST",
628 $payLoad,
629 null,
630 $apiContext,
631 $restCall
632 );
633 $ret = new DetailedRefund();
634 $ret->fromJson($json);
635 return $ret;
636 }
637 }
638