Merge pull request #316 from woocommerce/improve-pending-statuses

Improve pending statuses

modules/ppcp-api-client/src/Entity/class-authorizationstatusdetails.php

@@ -47,10 +47,25 @@ public function is( string $reason ): bool {
 
 	/**
 	 * Returns the reason explaining authorization status.
+	 * One of AuthorizationStatusDetails constants.
 	 *
 	 * @return string
 	 */
 	public function reason(): string {
 		return $this->reason;
 	}
+
+	/**
+	 * Returns the human-readable reason text explaining authorization status.
+	 *
+	 * @return string
+	 */
+	public function text(): string {
+		switch ( $this->reason ) {
+			case self::PENDING_REVIEW:
+				return __( 'Authorization is pending manual review.', 'woocommerce-paypal-payments' );
+			default:
+				return $this->reason;
+		}
+	}
 }

modules/ppcp-api-client/src/Entity/class-capturestatusdetails.php

@@ -25,7 +25,7 @@ class CaptureStatusDetails {
 	const RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION = 'RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION';
 	const REFUNDED                                    = 'REFUNDED';
 	const TRANSACTION_APPROVED_AWAITING_FUNDING       = 'TRANSACTION_APPROVED_AWAITING_FUNDING';
-	const UNILATERAL                                  = 'REFUNDED';
+	const UNILATERAL                                  = 'UNILATERAL';
 	const VERIFICATION_REQUIRED                       = 'VERIFICATION_REQUIRED';
 
 	/**
@@ -57,10 +57,45 @@ public function is( string $reason ): bool {
 
 	/**
 	 * Returns the reason explaining capture status.
+	 * One of CaptureStatusDetails constants.
 	 *
 	 * @return string
 	 */
 	public function reason(): string {
 		return $this->reason;
 	}
+
+	/**
+	 * Returns the human-readable reason text explaining capture status.
+	 *
+	 * @return string
+	 */
+	public function text(): string {
+		switch ( $this->reason ) {
+			case self::BUYER_COMPLAINT:
+				return __( 'The payer initiated a dispute for this captured payment with PayPal.', 'woocommerce-paypal-payments' );
+			case self::CHARGEBACK:
+				return __( 'The captured funds were reversed in response to the payer disputing this captured payment with the issuer of the financial instrument used to pay for this captured payment.', 'woocommerce-paypal-payments' );
+			case self::ECHECK:
+				return __( 'The payer paid by an eCheck that has not yet cleared.', 'woocommerce-paypal-payments' );
+			case self::INTERNATIONAL_WITHDRAWAL:
+				return __( 'Visit your online account. In your Account Overview, accept and deny this payment.', 'woocommerce-paypal-payments' );
+			case self::OTHER:
+				return __( 'No additional specific reason can be provided. For more information about this captured payment, visit your account online or contact PayPal.', 'woocommerce-paypal-payments' );
+			case self::PENDING_REVIEW:
+				return __( 'The captured payment is pending manual review.', 'woocommerce-paypal-payments' );
+			case self::RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION:
+				return __( 'The payee has not yet set up appropriate receiving preferences for their account. For more information about how to accept or deny this payment, visit your account online. This reason is typically offered in scenarios such as when the currency of the captured payment is different from the primary holding currency of the payee.', 'woocommerce-paypal-payments' );
+			case self::REFUNDED:
+				return __( 'The captured funds were refunded.', 'woocommerce-paypal-payments' );
+			case self::TRANSACTION_APPROVED_AWAITING_FUNDING:
+				return __( 'The payer must send the funds for this captured payment. This code generally appears for manual EFTs.', 'woocommerce-paypal-payments' );
+			case self::UNILATERAL:
+				return __( 'The payee does not have a PayPal account.', 'woocommerce-paypal-payments' );
+			case self::VERIFICATION_REQUIRED:
+				return __( 'The payee\'s PayPal account is not verified.', 'woocommerce-paypal-payments' );
+			default:
+				return $this->reason;
+		}
+	}
 }

modules/ppcp-wc-gateway/src/Gateway/class-paypalgateway.php

@@ -9,6 +9,7 @@
 
 namespace WooCommerce\PayPalCommerce\WcGateway\Gateway;
 
+use WooCommerce\PayPalCommerce\ApiClient\Entity\CaptureStatus;
 use WooCommerce\PayPalCommerce\Onboarding\Environment;
 use WooCommerce\PayPalCommerce\Onboarding\State;
 use WooCommerce\PayPalCommerce\Session\SessionHandler;
@@ -271,12 +272,16 @@ public function capture_authorized_payment( \WC_Order $wc_order ): bool {
 			return false;
 		}
 
-		$this->handle_capture_status( end( $captures ), $wc_order );
+		$capture = end( $captures );
+
+		$this->handle_capture_status( $capture, $wc_order );
 
 		if ( AuthorizedPaymentsProcessor::SUCCESSFUL === $result_status ) {
-			$wc_order->add_order_note(
-				__( 'Payment successfully captured.', 'woocommerce-paypal-payments' )
-			);
+			if ( $capture->status()->is( CaptureStatus::COMPLETED ) ) {
+				$wc_order->add_order_note(
+					__( 'Payment successfully captured.', 'woocommerce-paypal-payments' )
+				);
+			}
 			$wc_order->update_meta_data( self::CAPTURED_META_KEY, 'true' );
 			$wc_order->save();
 			return true;

modules/ppcp-wc-gateway/src/Processor/class-paymentstatushandlingtrait.php

@@ -56,7 +56,7 @@ protected function handle_capture_status(
 		$status = $capture->status();
 
 		if ( $status->details() ) {
-			$this->add_status_details_note( $wc_order, $status->name(), $status->details()->reason() );
+			$this->add_status_details_note( $wc_order, $status->name(), $status->details()->text() );
 		}
 
 		switch ( $status->name() ) {
@@ -96,7 +96,7 @@ protected function handle_authorization_status(
 		$status = $authorization->status();
 
 		if ( $status->details() ) {
-			$this->add_status_details_note( $wc_order, $status->name(), $status->details()->reason() );
+			$this->add_status_details_note( $wc_order, $status->name(), $status->details()->text() );
 		}
 
 		switch ( $status->name() ) {
@@ -130,8 +130,8 @@ protected function add_status_details_note(
 	): void {
 		$wc_order->add_order_note(
 			sprintf(
-				/* translators: %1$s - PENDING, DENIED, ... %2$s - PENDING_REVIEW, ... */
-				__( 'PayPal order payment is set to %1$s status, details: %2$s.', 'woocommerce-paypal-payments' ),
+				/* translators: %1$s - PENDING, DENIED, ... %2$s - text explaining the reason, ... */
+				__( 'PayPal order payment is set to %1$s status, details: %2$s', 'woocommerce-paypal-payments' ),
 				$status,
 				$reason
 			)