Add api support for order endpoint to receive refunds

modules/ppcp-api-client/services.php

@@ -14,6 +14,7 @@ use WooCommerce\PayPalCommerce\ApiClient\Endpoint\CatalogProducts;
 use WooCommerce\PayPalCommerce\ApiClient\Endpoint\BillingPlans;
 use WooCommerce\PayPalCommerce\ApiClient\Factory\BillingCycleFactory;
 use WooCommerce\PayPalCommerce\ApiClient\Factory\PaymentPreferencesFactory;
+use WooCommerce\PayPalCommerce\ApiClient\Factory\RefundFactory;
 use WooCommerce\PayPalCommerce\ApiClient\Factory\PlanFactory;
 use WooCommerce\PayPalCommerce\ApiClient\Factory\ProductFactory;
 use WooCommerce\PayPalCommerce\ApiClient\Factory\ShippingOptionFactory;
@@ -289,6 +290,12 @@ return array(
 			$container->get( 'api.factory.fraud-processor-response' )
 		);
 	},
+	'api.factory.refund'                        => static function ( ContainerInterface $container ): RefundFactory {
+		$amount_factory   = $container->get( 'api.factory.amount' );
+		return new RefundFactory(
+			$amount_factory
+		);
+	},
 	'api.factory.purchase-unit'                 => static function ( ContainerInterface $container ): PurchaseUnitFactory {
 
 		$amount_factory   = $container->get( 'api.factory.amount' );
@@ -374,7 +381,8 @@ return array(
 	'api.factory.payments'                      => static function ( ContainerInterface $container ): PaymentsFactory {
 		$authorizations_factory = $container->get( 'api.factory.authorization' );
 		$capture_factory        = $container->get( 'api.factory.capture' );
-		return new PaymentsFactory( $authorizations_factory, $capture_factory );
+		$refund_factory         = $container->get( 'api.factory.refund' );
+		return new PaymentsFactory( $authorizations_factory, $capture_factory, $refund_factory );
 	},
 	'api.factory.authorization'                 => static function ( ContainerInterface $container ): AuthorizationFactory {
 		return new AuthorizationFactory();

modules/ppcp-api-client/src/Endpoint/PaymentsEndpoint.php

@@ -13,7 +13,7 @@ use WooCommerce\PayPalCommerce\ApiClient\Authentication\Bearer;
 use WooCommerce\PayPalCommerce\ApiClient\Entity\Authorization;
 use WooCommerce\PayPalCommerce\ApiClient\Entity\Capture;
 use WooCommerce\PayPalCommerce\ApiClient\Entity\Money;
-use WooCommerce\PayPalCommerce\ApiClient\Entity\Refund;
+use WooCommerce\PayPalCommerce\ApiClient\Entity\RefundCapture;
 use WooCommerce\PayPalCommerce\ApiClient\Exception\PayPalApiException;
 use WooCommerce\PayPalCommerce\ApiClient\Exception\RuntimeException;
 use WooCommerce\PayPalCommerce\ApiClient\Factory\AuthorizationFactory;
@@ -196,13 +196,13 @@ class PaymentsEndpoint {
 	/**
 	 * Refunds a payment.
 	 *
-	 * @param Refund $refund The refund to be processed.
+	 * @param RefundCapture $refund The refund to be processed.
 	 *
 	 * @return string Refund ID.
 	 * @throws RuntimeException If the request fails.
 	 * @throws PayPalApiException If the request fails.
 	 */
-	public function refund( Refund $refund ) : string {
+	public function refund( RefundCapture $refund ) : string {
 		$bearer = $this->bearer->bearer();
 		$url    = trailingslashit( $this->host ) . 'v2/payments/captures/' . $refund->for_capture()->id() . '/refund';
 		$args   = array(

modules/ppcp-api-client/src/Entity/Payments.php

@@ -28,13 +28,21 @@ class Payments {
 	 */
 	private $captures;
 
+    /**
+     * The Captures.
+     *
+     * @var Refund[]
+     */
+    private $refunds;
+
 	/**
 	 * Payments constructor.
 	 *
 	 * @param array $authorizations The Authorizations.
 	 * @param array $captures The Captures.
+	 * @param array $refunds The Refunds.
 	 */
-	public function __construct( array $authorizations, array $captures ) {
+	public function __construct( array $authorizations, array $captures, array $refunds ) {
 		foreach ( $authorizations as $key => $authorization ) {
 			if ( is_a( $authorization, Authorization::class ) ) {
 				continue;
@@ -47,8 +55,15 @@ class Payments {
 			}
 			unset( $captures[ $key ] );
 		}
+        foreach ( $refunds as $key => $refund ) {
+            if ( is_a( $refund, Refund::class ) ) {
+                continue;
+            }
+            unset( $refunds[ $key ] );
+        }
 		$this->authorizations = $authorizations;
 		$this->captures       = $captures;
+		$this->refunds        = $refunds;
 	}
 
 	/**
@@ -70,6 +85,12 @@ class Payments {
 				},
 				$this->captures()
 			),
+			'refunds'        => array_map(
+				static function ( Refund $refund ): array {
+					return $refund->to_array();
+				},
+				$this->refunds()
+			),
 		);
 	}
 
@@ -90,4 +111,13 @@ class Payments {
 	public function captures(): array {
 		return $this->captures;
 	}
+
+    /**
+     * Returns the Refunds.
+     *
+     * @return Refund[]
+     **/
+    public function refunds(): array {
+        return $this->refunds;
+    }
 }

modules/ppcp-api-client/src/Entity/Refund.php

@@ -1,6 +1,8 @@
 <?php
 /**
- * The refund object.
+ * The refund entity.
+ *
+ * @link https://developer.paypal.com/docs/api/orders/v2/#definition-refund
  *
  * @package WooCommerce\PayPalCommerce\ApiClient\Entity
  */
@@ -15,11 +17,32 @@ namespace WooCommerce\PayPalCommerce\ApiClient\Entity;
 class Refund {
 
 	/**
-	 * The Capture.
+	 * The ID.
 	 *
-	 * @var Capture
+	 * @var string
 	 */
-	private $capture;
+	private $id;
+
+	/**
+	 * The status.
+	 *
+	 * @var RefundStatus
+	 */
+	private $status;
+
+	/**
+	 * The amount.
+	 *
+	 * @var Amount
+	 */
+	private $amount;
+
+	/**
+	 * The detailed breakdown of the refund activity (fees, ...).
+	 *
+	 * @var SellerPayableBreakdown|null
+	 */
+	private $seller_payable_breakdown;
 
 	/**
 	 * The invoice id.
@@ -29,90 +52,13 @@ class Refund {
 	private $invoice_id;
 
 	/**
-	 * The note to the payer.
-	 *
-	 * @var string
-	 */
-	private $note_to_payer;
-
-	/**
-	 * The Amount.
-	 *
-	 * @var Amount|null
-	 */
-	private $amount;
-
-	/**
-	 * Refund constructor.
-	 *
-	 * @param Capture     $capture The capture where the refund is supposed to be applied at.
-	 * @param string      $invoice_id The invoice id.
-	 * @param string      $note_to_payer The note to the payer.
-	 * @param Amount|null $amount The Amount.
-	 */
-	public function __construct(
-		Capture $capture,
-		string $invoice_id,
-		string $note_to_payer = '',
-		Amount $amount = null
-	) {
-		$this->capture       = $capture;
-		$this->invoice_id    = $invoice_id;
-		$this->note_to_payer = $note_to_payer;
-		$this->amount        = $amount;
-	}
-
-	/**
-	 * Returns the capture for the refund.
-	 *
-	 * @return Capture
-	 */
-	public function for_capture() : Capture {
-		return $this->capture;
-	}
-
-	/**
-	 * Return the invoice id.
-	 *
-	 * @return string
-	 */
-	public function invoice_id() : string {
-		return $this->invoice_id;
-	}
-
-	/**
-	 * Returns the note to the payer.
-	 *
-	 * @return string
-	 */
-	public function note_to_payer() : string {
-		return $this->note_to_payer;
-	}
-
-	/**
-	 * Returns the Amount.
-	 *
-	 * @return Amount|null
-	 */
-	public function amount() {
-		return $this->amount;
-	}
-
-	/**
-	 * Returns the object as array.
+	 * Returns the entity as array.
 	 *
 	 * @return array
 	 */
 	public function to_array() : array {
-		$data = array(
-			'invoice_id' => $this->invoice_id(),
+		$data    = array(
 		);
-		if ( $this->note_to_payer() ) {
-			$data['note_to_payer'] = $this->note_to_payer();
-		}
-		if ( $this->amount() ) {
-			$data['amount'] = $this->amount()->to_array();
-		}
 		return $data;
 	}
 }

modules/ppcp-api-client/src/Entity/RefundCapture.php

@@ -0,0 +1,118 @@
+<?php
+/**
+ * The refund capture object.
+ *
+ * @package WooCommerce\PayPalCommerce\ApiClient\Entity
+ */
+
+declare( strict_types=1 );
+
+namespace WooCommerce\PayPalCommerce\ApiClient\Entity;
+
+/**
+ * Class RefundCapture
+ */
+class RefundCapture {
+
+	/**
+	 * The Capture.
+	 *
+	 * @var Capture
+	 */
+	private $capture;
+
+	/**
+	 * The invoice id.
+	 *
+	 * @var string
+	 */
+	private $invoice_id;
+
+	/**
+	 * The note to the payer.
+	 *
+	 * @var string
+	 */
+	private $note_to_payer;
+
+	/**
+	 * The Amount.
+	 *
+	 * @var Amount|null
+	 */
+	private $amount;
+
+	/**
+	 * Refund constructor.
+	 *
+	 * @param Capture     $capture The capture where the refund is supposed to be applied at.
+	 * @param string      $invoice_id The invoice id.
+	 * @param string      $note_to_payer The note to the payer.
+	 * @param Amount|null $amount The Amount.
+	 */
+	public function __construct(
+		Capture $capture,
+		string $invoice_id,
+		string $note_to_payer = '',
+		Amount $amount = null
+	) {
+		$this->capture       = $capture;
+		$this->invoice_id    = $invoice_id;
+		$this->note_to_payer = $note_to_payer;
+		$this->amount        = $amount;
+	}
+
+	/**
+	 * Returns the capture for the refund.
+	 *
+	 * @return Capture
+	 */
+	public function for_capture() : Capture {
+		return $this->capture;
+	}
+
+	/**
+	 * Return the invoice id.
+	 *
+	 * @return string
+	 */
+	public function invoice_id() : string {
+		return $this->invoice_id;
+	}
+
+	/**
+	 * Returns the note to the payer.
+	 *
+	 * @return string
+	 */
+	public function note_to_payer() : string {
+		return $this->note_to_payer;
+	}
+
+	/**
+	 * Returns the Amount.
+	 *
+	 * @return Amount|null
+	 */
+	public function amount() {
+		return $this->amount;
+	}
+
+	/**
+	 * Returns the object as array.
+	 *
+	 * @return array
+	 */
+	public function to_array() : array {
+		$data = array(
+			'invoice_id' => $this->invoice_id(),
+		);
+		if ( $this->note_to_payer() ) {
+			$data['note_to_payer'] = $this->note_to_payer();
+		}
+		if ( $this->amount() ) {
+			$data['amount'] = $this->amount()->to_array();
+		}
+		return $data;
+	}
+}

modules/ppcp-api-client/src/Entity/RefundStatus.php

@@ -0,0 +1,59 @@
+<?php
+/**
+ * The RefundStatus object.
+ *
+ * @see https://developer.paypal.com/docs/api/orders/v2/#definition-refund_status
+ *
+ * @package WooCommerce\PayPalCommerce\ApiClient\Entity
+ */
+
+declare(strict_types=1);
+
+namespace WooCommerce\PayPalCommerce\ApiClient\Entity;
+
+/**
+ * Class RefundStatus
+ */
+class RefundStatus {
+
+	const COMPLETED          = 'COMPLETED';
+	const CANCELLED          = 'CANCELLED';
+	const FAILED             = 'FAILED';
+	const PENDING            = 'PENDING';
+
+	/**
+	 * The status.
+	 *
+	 * @var string
+	 */
+	private $status;
+
+	/**
+	 * RefundStatus constructor.
+	 *
+	 * @param string $status The status.
+	 */
+	public function __construct( string $status ) {
+		$this->status  = $status;
+	}
+
+	/**
+	 * Compares the current status with a given one.
+	 *
+	 * @param string $status The status to compare with.
+	 *
+	 * @return bool
+	 */
+	public function is( string $status ): bool {
+		return $this->status === $status;
+	}
+
+	/**
+	 * Returns the status.
+	 *
+	 * @return string
+	 */
+	public function name(): string {
+		return $this->status;
+	}
+}

modules/ppcp-api-client/src/Entity/SellerPayableBreakdown.php

@@ -0,0 +1,202 @@
+<?php
+/**
+ * The info about fees and amount that will be paid by the seller.
+ *
+ * @package WooCommerce\PayPalCommerce\ApiClient\Entity
+ */
+
+declare(strict_types=1);
+
+namespace WooCommerce\PayPalCommerce\ApiClient\Entity;
+
+/**
+ * Class SellerPayableBreakdown
+ */
+class SellerPayableBreakdown {
+
+	/**
+	 * The amount for this refunded payment in the currency of the transaction.
+	 *
+	 * @var Money
+	 */
+	private $gross_amount;
+
+	/**
+	 * The applicable fee for this refunded payment in the currency of the transaction.
+	 *
+	 * @var Money|null
+	 */
+	private $paypal_fee;
+
+	/**
+	 * The applicable fee for this captured payment in the receivable currency.
+	 *
+	 * Present only in cases the fee is charged in the receivable currency.
+	 *
+	 * @var Money|null
+	 */
+	private $paypal_fee_in_receivable_currency;
+
+	/**
+	 * The net amount that the payee receives for this refunded payment in their PayPal account.
+	 *
+	 * Computed as gross_amount minus the paypal_fee minus the platform_fees.
+	 *
+	 * @var Money|null
+	 */
+	private $net_amount;
+
+	/**
+	 * @var Money|null
+	 */
+	private $net_amount_in_receivable_currency;
+
+	/**
+	 * @var Money|null
+	 */
+	private $total_refunded_amount;
+
+	/**
+	 * An array of platform or partner fees, commissions, or brokerage fees that associated with the captured payment.
+	 *
+	 * @var PlatformFee[]
+	 */
+	private $platform_fees;
+
+//	/**
+//	 * SellerReceivableBreakdown constructor.
+//	 *
+//	 * @param Money             $gross_amount The amount for this captured payment in the currency of the transaction.
+//	 * @param Money|null        $paypal_fee The applicable fee for this captured payment in the currency of the transaction.
+//	 * @param Money|null        $paypal_fee_in_receivable_currency The applicable fee for this captured payment in the receivable currency.
+//	 * @param Money|null        $net_amount The net amount that the payee receives for this captured payment in their PayPal account.
+//	 * @param Money|null        $receivable_amount The net amount that is credited to the payee's PayPal account.
+//	 * @param ExchangeRate|null $exchange_rate The exchange rate that determines the amount that is credited to the payee's PayPal account.
+//	 * @param PlatformFee[]     $platform_fees An array of platform or partner fees, commissions, or brokerage fees that associated with the captured payment.
+//	 */
+//	public function __construct(
+//		Money $gross_amount,
+//		?Money $paypal_fee,
+//		?Money $paypal_fee_in_receivable_currency,
+//		?Money $net_amount,
+//		?Money $receivable_amount,
+//		?ExchangeRate $exchange_rate,
+//		array $platform_fees
+//	) {
+//		$this->gross_amount                      = $gross_amount;
+//		$this->paypal_fee                        = $paypal_fee;
+//		$this->paypal_fee_in_receivable_currency = $paypal_fee_in_receivable_currency;
+//		$this->net_amount                        = $net_amount;
+//		$this->receivable_amount                 = $receivable_amount;
+//		$this->exchange_rate                     = $exchange_rate;
+//		$this->platform_fees                     = $platform_fees;
+//	}
+//
+//	/**
+//	 * The amount for this captured payment in the currency of the transaction.
+//	 *
+//	 * @return Money
+//	 */
+//	public function gross_amount(): ?Money {
+//		return $this->gross_amount;
+//	}
+//
+//	/**
+//	 * The applicable fee for this captured payment in the currency of the transaction.
+//	 *
+//	 * @return Money|null
+//	 */
+//	public function paypal_fee(): ?Money {
+//		return $this->paypal_fee;
+//	}
+//
+//	/**
+//	 * The applicable fee for this captured payment in the receivable currency.
+//	 *
+//	 * Present only in cases the fee is charged in the receivable currency.
+//	 *
+//	 * @return Money|null
+//	 */
+//	public function paypal_fee_in_receivable_currency(): ?Money {
+//		return $this->paypal_fee_in_receivable_currency;
+//	}
+//
+//	/**
+//	 * The net amount that the payee receives for this captured payment in their PayPal account.
+//	 *
+//	 * Computed as gross_amount minus the paypal_fee minus the platform_fees.
+//	 *
+//	 * @return Money|null
+//	 */
+//	public function net_amount(): ?Money {
+//		return $this->net_amount;
+//	}
+//
+//	/**
+//	 * The net amount that is credited to the payee's PayPal account.
+//	 *
+//	 * Present only when the currency of the captured payment is different from the currency
+//	 * of the PayPal account where the payee wants to credit the funds. Computed as net_amount times exchange_rate.
+//	 *
+//	 * @return Money|null
+//	 */
+//	public function receivable_amount(): ?Money {
+//		return $this->receivable_amount;
+//	}
+//
+//	/**
+//	 * The exchange rate that determines the amount that is credited to the payee's PayPal account.
+//	 *
+//	 * Present when the currency of the captured payment is different from the currency of the PayPal account where the payee wants to credit the funds.
+//	 *
+//	 * @return ExchangeRate|null
+//	 */
+//	public function exchange_rate(): ?ExchangeRate {
+//		return $this->exchange_rate;
+//	}
+//
+//	/**
+//	 * An array of platform or partner fees, commissions, or brokerage fees that associated with the captured payment.
+//	 *
+//	 * @return PlatformFee[]
+//	 */
+//	public function platform_fees(): array {
+//		return $this->platform_fees;
+//	}
+//
+//	/**
+//	 * Returns the object as array.
+//	 *
+//	 * @return array
+//	 */
+//	public function to_array(): array {
+//		$data = array(
+//			'gross_amount' => $this->gross_amount->to_array(),
+//		);
+//		if ( $this->paypal_fee ) {
+//			$data['paypal_fee'] = $this->paypal_fee->to_array();
+//		}
+//		if ( $this->paypal_fee_in_receivable_currency ) {
+//			$data['paypal_fee_in_receivable_currency'] = $this->paypal_fee_in_receivable_currency->to_array();
+//		}
+//		if ( $this->net_amount ) {
+//			$data['net_amount'] = $this->net_amount->to_array();
+//		}
+//		if ( $this->receivable_amount ) {
+//			$data['receivable_amount'] = $this->receivable_amount->to_array();
+//		}
+//		if ( $this->exchange_rate ) {
+//			$data['exchange_rate'] = $this->exchange_rate->to_array();
+//		}
+//		if ( $this->platform_fees ) {
+//			$data['platform_fees'] = array_map(
+//				function ( PlatformFee $fee ) {
+//					return $fee->to_array();
+//				},
+//				$this->platform_fees
+//			);
+//		}
+//
+//		return $data;
+//	}
+}

modules/ppcp-api-client/src/Factory/PaymentsFactory.php

@@ -11,6 +11,7 @@ namespace WooCommerce\PayPalCommerce\ApiClient\Factory;
 
 use WooCommerce\PayPalCommerce\ApiClient\Entity\Authorization;
 use WooCommerce\PayPalCommerce\ApiClient\Entity\Capture;
+use WooCommerce\PayPalCommerce\ApiClient\Entity\Refund;
 use WooCommerce\PayPalCommerce\ApiClient\Entity\Payments;
 
 /**
@@ -32,19 +33,29 @@ class PaymentsFactory {
 	 */
 	private $capture_factory;
 
+	/**
+	 * The Refund factory.
+	 *
+	 * @var RefundFactory
+	 */
+	private $refund_factory;
+
 	/**
 	 * PaymentsFactory constructor.
 	 *
 	 * @param AuthorizationFactory $authorization_factory The Authorization factory.
 	 * @param CaptureFactory       $capture_factory The Capture factory.
+	 * @param RefundFactory $refund_factory The Refund factory.
 	 */
 	public function __construct(
 		AuthorizationFactory $authorization_factory,
-		CaptureFactory $capture_factory
+		CaptureFactory $capture_factory,
+		RefundFactory $refund_factory
 	) {
 
 		$this->authorization_factory = $authorization_factory;
 		$this->capture_factory       = $capture_factory;
+		$this->refund_factory        = $refund_factory;
 	}
 
 	/**
@@ -62,12 +73,18 @@ class PaymentsFactory {
 			isset( $data->authorizations ) ? $data->authorizations : array()
 		);
 		$captures       = array_map(
-			function ( \stdClass $authorization ): Capture {
-				return $this->capture_factory->from_paypal_response( $authorization );
+			function ( \stdClass $capture ): Capture {
+				return $this->capture_factory->from_paypal_response( $capture );
 			},
 			isset( $data->captures ) ? $data->captures : array()
 		);
-		$payments       = new Payments( $authorizations, $captures );
+		$refunds        = array_map(
+			function ( \stdClass $refund ): Refund {
+				return $this->refund_factory->from_paypal_response( $refund );
+			},
+			isset( $data->refunds ) ? $data->refunds : array()
+		);
+		$payments       = new Payments( $authorizations, $captures, $refunds );
 		return $payments;
 	}
 }

modules/ppcp-api-client/src/Factory/RefundFactory.php

@@ -0,0 +1,43 @@
+<?php
+/**
+ * The payment refund factory.
+ *
+ * @package WooCommerce\PayPalCommerce\ApiClient\Factory
+ */
+
+declare( strict_types=1 );
+
+namespace WooCommerce\PayPalCommerce\ApiClient\Factory;
+
+use WooCommerce\PayPalCommerce\ApiClient\Entity\Refund;
+
+/**
+ * Class RefundFactory
+ */
+class RefundFactory {
+
+	/**
+	 * RefundFactory constructor.
+	 *
+	 * @param AmountFactory                    $amount_factory The amount factory.
+	 */
+	public function __construct(
+		AmountFactory $amount_factory
+	) {
+		$this->amount_factory                      = $amount_factory;
+
+	}
+
+	/**
+	 * Returns the payment refund object based off the PayPal response.
+	 *
+	 * @param \stdClass $data The PayPal response.
+	 *
+	 * @return Refund
+	 */
+	public function from_paypal_response( \stdClass $data ) : Refund {
+
+		return new Refund(
+		);
+	}
+}