Merge branch 'trunk' into PCP-1877-improve-line-item-mismatch-handling

modules/ppcp-api-client/services.php

@@ -10,6 +10,20 @@ declare(strict_types=1);
 namespace WooCommerce\PayPalCommerce\ApiClient;
 
 use WooCommerce\PayPalCommerce\Common\Pattern\SingletonDecorator;
+use WooCommerce\PayPalCommerce\ApiClient\Endpoint\BillingSubscriptions;
+use WooCommerce\PayPalCommerce\ApiClient\Endpoint\CatalogProducts;
+use WooCommerce\PayPalCommerce\ApiClient\Endpoint\BillingPlans;
+use WooCommerce\PayPalCommerce\ApiClient\Entity\SellerPayableBreakdown;
+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\RefundPayerFactory;
+use WooCommerce\PayPalCommerce\ApiClient\Factory\SellerPayableBreakdownFactory;
+use WooCommerce\PayPalCommerce\ApiClient\Factory\ShippingOptionFactory;
+use WooCommerce\PayPalCommerce\Session\SessionHandler;
+use WooCommerce\PayPalCommerce\Vendor\Psr\Container\ContainerInterface;
 use WooCommerce\PayPalCommerce\ApiClient\Authentication\Bearer;
 use WooCommerce\PayPalCommerce\ApiClient\Authentication\PayPalBearer;
 use WooCommerce\PayPalCommerce\ApiClient\Endpoint\BillingAgreementsEndpoint;
@@ -292,6 +306,14 @@ 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,
+			$container->get( 'api.factory.seller-payable-breakdown' ),
+			$container->get( 'api.factory.refund_payer' )
+		);
+	},
 	'api.factory.purchase-unit'                 => static function ( ContainerInterface $container ): PurchaseUnitFactory {
 
 		$amount_factory   = $container->get( 'api.factory.amount' );
@@ -356,6 +378,9 @@ return array(
 		$address_factory = $container->get( 'api.factory.address' );
 		return new PayerFactory( $address_factory );
 	},
+	'api.factory.refund_payer'                  => static function ( ContainerInterface $container ): RefundPayerFactory {
+		return new RefundPayerFactory();
+	},
 	'api.factory.address'                       => static function ( ContainerInterface $container ): AddressFactory {
 		return new AddressFactory();
 	},
@@ -379,7 +404,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();
@@ -400,6 +426,12 @@ return array(
 			$container->get( 'api.factory.platform-fee' )
 		);
 	},
+	'api.factory.seller-payable-breakdown'      => static function ( ContainerInterface $container ): SellerPayableBreakdownFactory {
+		return new SellerPayableBreakdownFactory(
+			$container->get( 'api.factory.money' ),
+			$container->get( 'api.factory.platform-fee' )
+		);
+	},
 	'api.factory.fraud-processor-response'      => static function ( ContainerInterface $container ): FraudProcessorResponseFactory {
 		return new FraudProcessorResponseFactory();
 	},

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

@@ -54,8 +54,6 @@ class BillingPlans {
 	private $plan_factory;
 
 	/**
-	 * The logger.
-	 *
 	 * The logger.
 	 *
 	 * @var LoggerInterface
@@ -226,4 +224,40 @@ class BillingPlans {
 			);
 		}
 	}
+
+	/**
+	 * Deactivates a Subscription Plan.
+	 *
+	 * @param string $billing_plan_id The Plan ID.
+	 *
+	 * @return void
+	 *
+	 * @throws RuntimeException If the request fails.
+	 * @throws PayPalApiException If the request fails.
+	 */
+	public function deactivate_plan( string $billing_plan_id ) {
+		$bearer = $this->bearer->bearer();
+		$url    = trailingslashit( $this->host ) . 'v1/billing/plans/' . $billing_plan_id . '/deactivate';
+		$args   = array(
+			'method'  => 'POST',
+			'headers' => array(
+				'Authorization' => 'Bearer ' . $bearer->token(),
+				'Content-Type'  => 'application/json',
+			),
+		);
+
+		$response = $this->request( $url, $args );
+		if ( is_wp_error( $response ) || ! is_array( $response ) ) {
+			throw new RuntimeException( 'Could not deactivate plan.' );
+		}
+
+		$json        = json_decode( $response['body'] );
+		$status_code = (int) wp_remote_retrieve_response_code( $response );
+		if ( 204 !== $status_code ) {
+			throw new PayPalApiException(
+				$json,
+				$status_code
+			);
+		}
+	}
 }

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

@@ -214,4 +214,6 @@ class BillingSubscriptions {
 
 		return $json;
 	}
+
+
 }

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

@@ -236,9 +236,15 @@ class PayUponInvoiceOrderEndpoint {
 	 * @return array
 	 */
 	private function ensure_taxes( WC_Order $wc_order, array $data ): array {
-		$tax_total       = $data['purchase_units'][0]['amount']['breakdown']['tax_total']['value'];
-		$item_total      = $data['purchase_units'][0]['amount']['breakdown']['item_total']['value'];
-		$shipping        = $data['purchase_units'][0]['amount']['breakdown']['shipping']['value'];
+		$tax_total  = $data['purchase_units'][0]['amount']['breakdown']['tax_total']['value'];
+		$item_total = $data['purchase_units'][0]['amount']['breakdown']['item_total']['value'];
+		$shipping   = $data['purchase_units'][0]['amount']['breakdown']['shipping']['value'];
+
+		$handling          = isset( $data['purchase_units'][0]['amount']['breakdown']['handling'] ) ? $data['purchase_units'][0]['amount']['breakdown']['handling']['value'] : 0;
+		$insurance         = isset( $data['purchase_units'][0]['amount']['breakdown']['insurance'] ) ? $data['purchase_units'][0]['amount']['breakdown']['insurance']['value'] : 0;
+		$shipping_discount = isset( $data['purchase_units'][0]['amount']['breakdown']['shipping_discount'] ) ? $data['purchase_units'][0]['amount']['breakdown']['shipping_discount']['value'] : 0;
+		$discount          = isset( $data['purchase_units'][0]['amount']['breakdown']['discount'] ) ? $data['purchase_units'][0]['amount']['breakdown']['discount']['value'] : 0;
+
 		$order_tax_total = $wc_order->get_total_tax();
 		$tax_rate        = round( ( $order_tax_total / $item_total ) * 100, 1 );
 
@@ -266,7 +272,7 @@ class PayUponInvoiceOrderEndpoint {
 		);
 
 		$total_amount    = $data['purchase_units'][0]['amount']['value'];
-		$breakdown_total = $item_total + $tax_total + $shipping;
+		$breakdown_total = $item_total + $tax_total + $shipping + $handling + $insurance - $shipping_discount - $discount;
 		$diff            = round( $total_amount - $breakdown_total, 2 );
 		if ( $diff === -0.01 || $diff === 0.01 ) {
 			$data['purchase_units'][0]['amount']['value'] = number_format( $breakdown_total, 2, '.', '' );

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

@@ -19,6 +19,7 @@ use WooCommerce\PayPalCommerce\ApiClient\Factory\PaymentTokenActionLinksFactory;
 use WooCommerce\PayPalCommerce\ApiClient\Factory\PaymentTokenFactory;
 use Psr\Log\LoggerInterface;
 use WooCommerce\PayPalCommerce\ApiClient\Repository\CustomerRepository;
+use WP_Error;
 
 /**
  * Class PaymentTokenEndpoint
@@ -97,7 +98,7 @@ class PaymentTokenEndpoint {
 	}
 
 	/**
-	 * Returns the payment tokens for a user.
+	 * Returns the payment tokens for the given user id.
 	 *
 	 * @param int $id The user id.
 	 *
@@ -118,7 +119,67 @@ class PaymentTokenEndpoint {
 		$response = $this->request( $url, $args );
 		if ( is_wp_error( $response ) ) {
 			$error = new RuntimeException(
-				__( 'Could not fetch payment token.', 'woocommerce-paypal-payments' )
+				__( 'Could not fetch payment token for customer id.', 'woocommerce-paypal-payments' )
+			);
+			$this->logger->log(
+				'warning',
+				$error->getMessage(),
+				array(
+					'args'     => $args,
+					'response' => $response,
+				)
+			);
+			throw $error;
+		}
+		$json        = json_decode( $response['body'] );
+		$status_code = (int) wp_remote_retrieve_response_code( $response );
+		if ( 200 !== $status_code ) {
+			$error = new PayPalApiException(
+				$json,
+				$status_code
+			);
+			$this->logger->log(
+				'warning',
+				$error->getMessage(),
+				array(
+					'args'     => $args,
+					'response' => $response,
+				)
+			);
+			throw $error;
+		}
+
+		$tokens = array();
+		foreach ( $json->payment_tokens as $token_value ) {
+			$tokens[] = $this->factory->from_paypal_response( $token_value );
+		}
+
+		return $tokens;
+	}
+
+	/**
+	 * Returns the payment tokens for the given guest customer id.
+	 *
+	 * @param string $customer_id The guest customer id.
+	 *
+	 * @return PaymentToken[]
+	 * @throws RuntimeException If the request fails.
+	 */
+	public function for_guest( string $customer_id ): array {
+		$bearer = $this->bearer->bearer();
+		$url    = trailingslashit( $this->host ) . 'v2/vault/payment-tokens/?customer_id=' . $customer_id;
+		$args   = array(
+			'method'  => 'GET',
+			'headers' => array(
+				'Authorization' => 'Bearer ' . $bearer->token(),
+				'Content-Type'  => 'application/json',
+			),
+		);
+
+		$response = $this->request( $url, $args );
+		if ( $response instanceof WP_Error ) {
+			$error = new RuntimeException(
+				__( 'Could not fetch payment token for guest customer id.', 'woocommerce-paypal-payments' )
 			);
 			$this->logger->log(
 				'warning',

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 Refunds.
+	 *
+	 * @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 = array() ) {
 		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,50 +52,97 @@ class Refund {
 	private $invoice_id;
 
 	/**
-	 * The note to the payer.
+	 * The custom id.
+	 *
+	 * @var string
+	 */
+	private $custom_id;
+
+	/**
+	 * The acquirer reference number.
+	 *
+	 * @var string
+	 */
+	private $acquirer_reference_number;
+
+	/**
+	 * The acquirer reference number.
 	 *
 	 * @var string
 	 */
 	private $note_to_payer;
 
 	/**
-	 * The Amount.
+	 * The payer of the refund.
 	 *
-	 * @var Amount|null
+	 * @var ?RefundPayer
 	 */
-	private $amount;
+	private $payer;
 
 	/**
 	 * 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.
+	 * @param string                      $id The ID.
+	 * @param RefundStatus                $status The status.
+	 * @param Amount                      $amount The amount.
+	 * @param string                      $invoice_id The invoice id.
+	 * @param string                      $custom_id The custom id.
+	 * @param SellerPayableBreakdown|null $seller_payable_breakdown The detailed breakdown of the refund activity (fees, ...).
+	 * @param string                      $acquirer_reference_number The acquirer reference number.
+	 * @param string                      $note_to_payer The note to payer.
+	 * @param RefundPayer|null            $payer The payer.
 	 */
 	public function __construct(
-		Capture $capture,
+		string $id,
+		RefundStatus $status,
+		Amount $amount,
 		string $invoice_id,
-		string $note_to_payer = '',
-		Amount $amount = null
+		string $custom_id,
+		?SellerPayableBreakdown $seller_payable_breakdown,
+		string $acquirer_reference_number,
+		string $note_to_payer,
+		?RefundPayer $payer
 	) {
-		$this->capture       = $capture;
-		$this->invoice_id    = $invoice_id;
-		$this->note_to_payer = $note_to_payer;
-		$this->amount        = $amount;
+		$this->id                        = $id;
+		$this->status                    = $status;
+		$this->amount                    = $amount;
+		$this->invoice_id                = $invoice_id;
+		$this->custom_id                 = $custom_id;
+		$this->seller_payable_breakdown  = $seller_payable_breakdown;
+		$this->acquirer_reference_number = $acquirer_reference_number;
+		$this->note_to_payer             = $note_to_payer;
+		$this->payer                     = $payer;
 	}
 
 	/**
-	 * Returns the capture for the refund.
+	 * Returns the ID.
 	 *
-	 * @return Capture
+	 * @return string
 	 */
-	public function for_capture() : Capture {
-		return $this->capture;
+	public function id() : string {
+		return $this->id;
 	}
 
 	/**
-	 * Return the invoice id.
+	 * Returns the status.
+	 *
+	 * @return RefundStatus
+	 */
+	public function status() : RefundStatus {
+		return $this->status;
+	}
+
+	/**
+	 * Returns the amount.
+	 *
+	 * @return Amount
+	 */
+	public function amount() : Amount {
+		return $this->amount;
+	}
+
+	/**
+	 * Returns the invoice id.
 	 *
 	 * @return string
 	 */
@@ -81,7 +151,34 @@ class Refund {
 	}
 
 	/**
-	 * Returns the note to the payer.
+	 * Returns the custom id.
+	 *
+	 * @return string
+	 */
+	public function custom_id() : string {
+		return $this->custom_id;
+	}
+
+	/**
+	 * Returns the detailed breakdown of the refund activity (fees, ...).
+	 *
+	 * @return SellerPayableBreakdown|null
+	 */
+	public function seller_payable_breakdown() : ?SellerPayableBreakdown {
+		return $this->seller_payable_breakdown;
+	}
+
+	/**
+	 * The acquirer reference number.
+	 *
+	 * @return string
+	 */
+	public function acquirer_reference_number() : string {
+		return $this->acquirer_reference_number;
+	}
+
+	/**
+	 * The note to payer.
 	 *
 	 * @return string
 	 */
@@ -90,28 +187,38 @@ class Refund {
 	}
 
 	/**
-	 * Returns the Amount.
+	 * Returns the refund payer.
 	 *
-	 * @return Amount|null
+	 * @return RefundPayer|null
 	 */
-	public function amount() {
-		return $this->amount;
+	public function payer() : ?RefundPayer {
+		return $this->payer;
 	}
 
 	/**
-	 * 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(
+			'id'                        => $this->id(),
+			'status'                    => $this->status()->name(),
+			'amount'                    => $this->amount()->to_array(),
+			'invoice_id'                => $this->invoice_id(),
+			'custom_id'                 => $this->custom_id(),
+			'acquirer_reference_number' => $this->acquirer_reference_number(),
+			'note_to_payer'             => (array) $this->note_to_payer(),
 		);
-		if ( $this->note_to_payer() ) {
-			$data['note_to_payer'] = $this->note_to_payer();
+		$details = $this->status()->details();
+		if ( $details ) {
+			$data['status_details'] = array( 'reason' => $details->reason() );
 		}
-		if ( $this->amount() ) {
-			$data['amount'] = $this->amount()->to_array();
+		if ( $this->seller_payable_breakdown ) {
+			$data['seller_payable_breakdown'] = $this->seller_payable_breakdown->to_array();
+		}
+		if ( $this->payer ) {
+			$data['payer'] = $this->payer->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/RefundPayer.php

@@ -0,0 +1,79 @@
+<?php
+/**
+ * The refund payer object.
+ *
+ * @package WooCommerce\PayPalCommerce\ApiClient\Entity
+ */
+
+declare(strict_types=1);
+
+namespace WooCommerce\PayPalCommerce\ApiClient\Entity;
+
+/**
+ * Class RefundPayer
+ * The customer who sends the money.
+ */
+class RefundPayer {
+
+	/**
+	 * The email address.
+	 *
+	 * @var string
+	 */
+	private $email_address;
+
+	/**
+	 * The merchant id.
+	 *
+	 * @var string
+	 */
+	private $merchant_id;
+
+	/**
+	 * RefundPayer constructor.
+	 *
+	 * @param string $email_address The email.
+	 * @param string $merchant_id The merchant id.
+	 */
+	public function __construct(
+		string $email_address,
+		string $merchant_id
+	) {
+
+		$this->email_address = $email_address;
+		$this->merchant_id   = $merchant_id;
+	}
+
+	/**
+	 * Returns the email address.
+	 *
+	 * @return string
+	 */
+	public function email_address(): string {
+		return $this->email_address;
+	}
+
+	/**
+	 * Returns the merchant id.
+	 *
+	 * @return string
+	 */
+	public function merchant_id(): string {
+		return $this->merchant_id;
+	}
+
+	/**
+	 * Returns the object as array.
+	 *
+	 * @return array
+	 */
+	public function to_array() {
+		$payer = array(
+			'email_address' => $this->email_address(),
+		);
+		if ( $this->merchant_id ) {
+			$payer['merchant_id'] = $this->merchant_id();
+		}
+		return $payer;
+	}
+}

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

@@ -0,0 +1,77 @@
+<?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;
+
+	/**
+	 * The details.
+	 *
+	 * @var RefundStatusDetails|null
+	 */
+	private $details;
+
+	/**
+	 * RefundStatus constructor.
+	 *
+	 * @param string                   $status The status.
+	 * @param RefundStatusDetails|null $details The details.
+	 */
+	public function __construct( string $status, ?RefundStatusDetails $details = null ) {
+		$this->status  = $status;
+		$this->details = $details;
+	}
+
+	/**
+	 * 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;
+	}
+
+	/**
+	 * Returns the details.
+	 *
+	 * @return RefundStatusDetails|null
+	 */
+	public function details(): ?RefundStatusDetails {
+		return $this->details;
+	}
+}

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

@@ -0,0 +1,71 @@
+<?php
+/**
+ * The RefundStatusDetails object.
+ *
+ * @see https://developer.paypal.com/docs/api/payments/v2/#definition-refund_status_details
+ *
+ * @package WooCommerce\PayPalCommerce\ApiClient\Entity
+ */
+
+declare(strict_types=1);
+
+namespace WooCommerce\PayPalCommerce\ApiClient\Entity;
+
+/**
+ * Class RefundStatusDetails
+ */
+class RefundStatusDetails {
+
+	const ECHECK = 'ECHECK';
+
+	/**
+	 * The reason.
+	 *
+	 * @var string
+	 */
+	private $reason;
+
+	/**
+	 * RefundStatusDetails constructor.
+	 *
+	 * @param string $reason The reason explaining refund status.
+	 */
+	public function __construct( string $reason ) {
+		$this->reason = $reason;
+	}
+
+	/**
+	 * Compares the current reason with a given one.
+	 *
+	 * @param string $reason The reason to compare with.
+	 *
+	 * @return bool
+	 */
+	public function is( string $reason ): bool {
+		return $this->reason === $reason;
+	}
+
+	/**
+	 * Returns the reason explaining refund status.
+	 * One of RefundStatusDetails constants.
+	 *
+	 * @return string
+	 */
+	public function reason(): string {
+		return $this->reason;
+	}
+
+	/**
+	 * Returns the human-readable reason text explaining refund status.
+	 *
+	 * @return string
+	 */
+	public function text(): string {
+		switch ( $this->reason ) {
+			case self::ECHECK:
+				return __( 'The payer paid by an eCheck that has not yet cleared.', 'woocommerce-paypal-payments' );
+			default:
+				return $this->reason;
+		}
+	}
+}

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|null
+	 */
+	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;
+
+	/**
+	 * The net amount for this refunded payment in the receivable currency.
+	 *
+	 * @var Money|null
+	 */
+	private $net_amount_in_receivable_currency;
+
+	/**
+	 * The total amount for this refund.
+	 *
+	 * @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;
+
+	/**
+	 * SellerPayableBreakdown constructor.
+	 *
+	 * @param Money|null    $gross_amount The amount for this refunded payment in the currency of the transaction.
+	 * @param Money|null    $paypal_fee The applicable fee for this refunded payment in the currency of the transaction.
+	 * @param Money|null    $paypal_fee_in_receivable_currency The applicable fee for this refunded payment in the receivable currency.
+	 * @param Money|null    $net_amount The net amount that the payee receives for this refunded payment in their PayPal account.
+	 * @param Money|null    $net_amount_in_receivable_currency The net amount for this refunded payment in the receivable currency.
+	 * @param Money|null    $total_refunded_amount The total amount for this refund.
+	 * @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 $net_amount_in_receivable_currency,
+		?Money $total_refunded_amount,
+		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->net_amount_in_receivable_currency = $net_amount_in_receivable_currency;
+		$this->total_refunded_amount             = $total_refunded_amount;
+		$this->platform_fees                     = $platform_fees;
+	}
+
+	/**
+	 * The amount for this refunded payment in the currency of the transaction.
+	 *
+	 * @return Money|null
+	 */
+	public function gross_amount(): ?Money {
+		return $this->gross_amount;
+	}
+
+	/**
+	 * The applicable fee for this refunded payment in the currency of the transaction.
+	 *
+	 * @return Money|null
+	 */
+	public function paypal_fee(): ?Money {
+		return $this->paypal_fee;
+	}
+
+	/**
+	 * The applicable fee for this refunded 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 refunded 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 for this refunded payment in the receivable currency.
+	 *
+	 * @return Money|null
+	 */
+	public function net_amount_in_receivable_currency(): ?Money {
+		return $this->net_amount_in_receivable_currency;
+	}
+
+	/**
+	 * The total amount for this refund.
+	 *
+	 * @return Money|null
+	 */
+	public function total_refunded_amount(): ?Money {
+		return $this->total_refunded_amount;
+	}
+
+	/**
+	 * An array of platform or partner fees, commissions, or brokerage fees that associated with the refunded 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();
+		if ( $this->gross_amount ) {
+			$data['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->net_amount_in_receivable_currency ) {
+			$data['net_amount_in_receivable_currency'] = $this->net_amount_in_receivable_currency->to_array();
+		}
+		if ( $this->total_refunded_amount ) {
+			$data['total_refunded_amount'] = $this->total_refunded_amount->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,91 @@
+<?php
+/**
+ * The refund factory.
+ *
+ * @package WooCommerce\PayPalCommerce\ApiClient\Factory
+ */
+
+declare( strict_types=1 );
+
+namespace WooCommerce\PayPalCommerce\ApiClient\Factory;
+
+use WooCommerce\PayPalCommerce\ApiClient\Entity\Refund;
+use WooCommerce\PayPalCommerce\ApiClient\Entity\RefundStatus;
+use WooCommerce\PayPalCommerce\ApiClient\Entity\RefundStatusDetails;
+
+/**
+ * Class RefundFactory
+ */
+class RefundFactory {
+
+	/**
+	 * The Amount factory.
+	 *
+	 * @var AmountFactory
+	 */
+	private $amount_factory;
+
+	/**
+	 * The SellerPayableBreakdownFactory factory.
+	 *
+	 * @var SellerPayableBreakdownFactory
+	 */
+	private $seller_payable_breakdown_factory;
+
+	/**
+	 * The RefundPayerFactory factory.
+	 *
+	 * @var RefundPayerFactory
+	 */
+	private $refund_payer_factory;
+
+	/**
+	 * RefundFactory constructor.
+	 *
+	 * @param AmountFactory                 $amount_factory The amount factory.
+	 * @param SellerPayableBreakdownFactory $seller_payable_breakdown_factory The payable breakdown factory.
+	 * @param RefundPayerFactory            $refund_payer_factory The payer breakdown factory.
+	 */
+	public function __construct(
+		AmountFactory $amount_factory,
+		SellerPayableBreakdownFactory $seller_payable_breakdown_factory,
+		RefundPayerFactory $refund_payer_factory
+	) {
+		$this->amount_factory                   = $amount_factory;
+		$this->seller_payable_breakdown_factory = $seller_payable_breakdown_factory;
+		$this->refund_payer_factory             = $refund_payer_factory;
+	}
+
+	/**
+	 * Returns the refund object based off the PayPal response.
+	 *
+	 * @param \stdClass $data The PayPal response.
+	 *
+	 * @return Refund
+	 */
+	public function from_paypal_response( \stdClass $data ) : Refund {
+		$reason                   = $data->status_details->reason ?? null;
+		$seller_payable_breakdown = isset( $data->seller_payable_breakdown ) ?
+			$this->seller_payable_breakdown_factory->from_paypal_response( $data->seller_payable_breakdown )
+			: null;
+
+		$payer = isset( $data->payer ) ?
+			$this->refund_payer_factory->from_paypal_response( $data->payer )
+			: null;
+
+		return new Refund(
+			(string) $data->id,
+			new RefundStatus(
+				(string) $data->status,
+				$reason ? new RefundStatusDetails( $reason ) : null
+			),
+			$this->amount_factory->from_paypal_response( $data->amount ),
+			(string) ( $data->invoice_id ?? '' ),
+			(string) ( $data->custom_id ?? '' ),
+			$seller_payable_breakdown,
+			(string) ( $data->acquirer_reference_number ?? '' ),
+			(string) ( $data->note_to_payer ?? '' ),
+			$payer
+		);
+	}
+}

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

@@ -0,0 +1,39 @@
+<?php
+/**
+ * The RefundPayerFactory factory.
+ *
+ * @package WooCommerce\PayPalCommerce\ApiClient\Factory
+ */
+
+declare(strict_types=1);
+
+namespace WooCommerce\PayPalCommerce\ApiClient\Factory;
+
+use WooCommerce\PayPalCommerce\ApiClient\Entity\Address;
+use WooCommerce\PayPalCommerce\ApiClient\Entity\Payer;
+use WooCommerce\PayPalCommerce\ApiClient\Entity\PayerName;
+use WooCommerce\PayPalCommerce\ApiClient\Entity\PayerTaxInfo;
+use WooCommerce\PayPalCommerce\ApiClient\Entity\Phone;
+use WooCommerce\PayPalCommerce\ApiClient\Entity\PhoneWithType;
+use WooCommerce\PayPalCommerce\ApiClient\Entity\RefundPayer;
+use WooCommerce\PayPalCommerce\ApiClient\Exception\RuntimeException;
+
+/**
+ * Class RefundPayerFactory
+ */
+class RefundPayerFactory {
+
+	/**
+	 * Returns a Refund Payer object based off a PayPal Response.
+	 *
+	 * @param \stdClass $data The JSON object.
+	 *
+	 * @return RefundPayer
+	 */
+	public function from_paypal_response( \stdClass $data ): RefundPayer {
+		return new RefundPayer(
+			isset( $data->email_address ) ? $data->email_address : '',
+			isset( $data->merchant_id ) ? $data->merchant_id : ''
+		);
+	}
+}

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

@@ -0,0 +1,81 @@
+<?php
+/**
+ * The SellerPayableBreakdownFactory Factory.
+ *
+ * @package WooCommerce\PayPalCommerce\ApiClient\Factory
+ */
+
+declare(strict_types=1);
+
+namespace WooCommerce\PayPalCommerce\ApiClient\Factory;
+
+use stdClass;
+use WooCommerce\PayPalCommerce\ApiClient\Entity\PlatformFee;
+use WooCommerce\PayPalCommerce\ApiClient\Entity\SellerPayableBreakdown;
+
+/**
+ * Class SellerPayableBreakdownFactory
+ */
+class SellerPayableBreakdownFactory {
+
+	/**
+	 * The Money factory.
+	 *
+	 * @var MoneyFactory
+	 */
+	private $money_factory;
+
+	/**
+	 * The PlatformFee factory.
+	 *
+	 * @var PlatformFeeFactory
+	 */
+	private $platform_fee_factory;
+
+	/**
+	 * SellerPayableBreakdownFactory constructor.
+	 *
+	 * @param MoneyFactory       $money_factory The Money factory.
+	 * @param PlatformFeeFactory $platform_fee_factory The PlatformFee factory.
+	 */
+	public function __construct(
+		MoneyFactory $money_factory,
+		PlatformFeeFactory $platform_fee_factory
+	) {
+		$this->money_factory        = $money_factory;
+		$this->platform_fee_factory = $platform_fee_factory;
+	}
+
+	/**
+	 * Returns a SellerPayableBreakdownFactory object based off a PayPal Response.
+	 *
+	 * @param stdClass $data The JSON object.
+	 *
+	 * @return SellerPayableBreakdown
+	 */
+	public function from_paypal_response( stdClass $data ): SellerPayableBreakdown {
+
+		$gross_amount                      = ( isset( $data->gross_amount ) ) ? $this->money_factory->from_paypal_response( $data->gross_amount ) : null;
+		$paypal_fee                        = ( isset( $data->paypal_fee ) ) ? $this->money_factory->from_paypal_response( $data->paypal_fee ) : null;
+		$paypal_fee_in_receivable_currency = ( isset( $data->paypal_fee_in_receivable_currency ) ) ? $this->money_factory->from_paypal_response( $data->paypal_fee_in_receivable_currency ) : null;
+		$net_amount                        = ( isset( $data->net_amount ) ) ? $this->money_factory->from_paypal_response( $data->net_amount ) : null;
+		$net_amount_in_receivable_currency = ( isset( $data->net_amount_in_receivable_currency ) ) ? $this->money_factory->from_paypal_response( $data->net_amount_in_receivable_currency ) : null;
+		$total_refunded_amount             = ( isset( $data->total_refunded_amount ) ) ? $this->money_factory->from_paypal_response( $data->total_refunded_amount ) : null;
+		$platform_fees                     = ( isset( $data->platform_fees ) ) ? array_map(
+			function ( stdClass $fee_data ): PlatformFee {
+				return $this->platform_fee_factory->from_paypal_response( $fee_data );
+			},
+			$data->platform_fees
+		) : array();
+
+		return new SellerPayableBreakdown(
+			$gross_amount,
+			$paypal_fee,
+			$paypal_fee_in_receivable_currency,
+			$net_amount,
+			$net_amount_in_receivable_currency,
+			$total_refunded_amount,
+			$platform_fees
+		);
+	}
+}