Add ACSS support for WC Subscriptions (#4051)

* Add ACSS payment tokenization

* Add support for ACSS payment tokenization

* Fix mandate using saved payment method at checkout

* Add support for payment method type in setup intent initialization

* Add unit tests for WC_Payment_Token_ACSS class

* Fix unit tests

* Fix "init_setup_intent"

* Add ACSS support for WC Subscriptions

* Handle mandate ID for renewal orders

* Refactor update_payment_intent method to support setup intents

* Add mandate ID support for additional payment methods in renewal orders

* Add support for free trial subscriptions in blocks checkout

* Update ACSS payment method options to support combined payment schedules

* Add changelog

* Fix changing payment method for subscription

* Remove duplicate switch case

* Refactor update_intent method to use consistent parameter naming for intent

Author: ricardo

changelog.txt

@@ -32,6 +32,7 @@
 * Fix - Fix subscription renewal issues for Amazon Pay.
 * Tweak - SPE: Remove radio buttons
 * Update - Hide express checkout buttons when no product variation is selected.
+* Add - Add ACSS support for WC Subscriptions.
 
 = 9.3.1 - 2025-03-14 =
 * Fix - Temporarily disables the subscriptions detached notice feature due to long loading times on stores with many subscriptions.

client/blocks/upe/upe-deferred-intent-creation/payment-elements.js

@@ -52,10 +52,13 @@ const PaymentElements = ( {
 
 		async function createIntent() {
 			try {
-				const response = await api.createIntent(
-					getBlocksConfiguration()?.orderId,
-					paymentMethodId
-				);
+				const paymentNeeded = getBlocksConfiguration()?.isPaymentNeeded;
+				const response = paymentNeeded
+					? await api.createIntent(
+							getBlocksConfiguration()?.orderId,
+							paymentMethodId
+					  )
+					: await api.initSetupIntent( paymentMethodId );
 
 				setClientSecret( response.client_secret );
 				setPaymentIntentId( response.id );

includes/abstracts/abstract-wc-stripe-payment-gateway.php

@@ -558,8 +558,13 @@ public function process_response( $response, $order ) {
 			$this->update_fees( $order, is_string( $response->balance_transaction ) ? $response->balance_transaction : $response->balance_transaction->id );
 		}
 
+		// TODO: Refactor and add mandate ID support for other payment methods, if necessary.
+		// The mandate ID is not available for the intent object, so we need to fetch the charge.
+		// Mandate ID is necessary for renewal payments for certain payment methods and Indian cards.
 		if ( isset( $response->payment_method_details->card->mandate ) ) {
 			$order->update_meta_data( '_stripe_mandate_id', $response->payment_method_details->card->mandate );
+		} elseif ( isset( $response->payment_method_details->acss_debit->mandate ) ) {
+			$order->update_meta_data( '_stripe_mandate_id', $response->payment_method_details->acss_debit->mandate );
 		}
 
 		if ( isset( $response->payment_method, $response->payment_method_details ) ) {
@@ -1631,14 +1636,23 @@ public function save_intent_to_order( $order, $intent ) {
 		if ( 'payment_intent' === $intent->object ) {
 			WC_Stripe_Helper::add_payment_intent_to_order( $intent->id, $order );
 
-			// Add the mandate id necessary for renewal payments with Indian cards if it's present.
+			// TODO: Refactor and add mandate ID support for other payment methods, if necessary.
+			// The mandate ID is not available for the intent object, so we need to fetch the charge.
+			// Mandate ID is necessary for renewal payments for certain payment methods and Indian cards.
 			$charge = $this->get_latest_charge_from_intent( $intent );
 
 			if ( isset( $charge->payment_method_details->card->mandate ) ) {
 				$order->update_meta_data( '_stripe_mandate_id', $charge->payment_method_details->card->mandate );
+			} elseif ( isset( $charge->payment_method_details->acss_debit->mandate ) ) {
+				$order->update_meta_data( '_stripe_mandate_id', $charge->payment_method_details->acss_debit->mandate );
 			}
 		} elseif ( 'setup_intent' === $intent->object ) {
 			$order->update_meta_data( '_stripe_setup_intent', $intent->id );
+
+			// Add mandate for free trial subscriptions.
+			if ( isset( $intent->mandate ) ) {
+				$order->update_meta_data( '_stripe_mandate_id', $intent->mandate );
+			}
 		}
 
 		if ( is_callable( [ $order, 'save' ] ) ) {

includes/class-wc-stripe-intent-controller.php

@@ -413,7 +413,7 @@ public function update_payment_intent_ajax() {
 				throw new Exception( __( 'Unable to verify your request. Please reload the page and try again.', 'woocommerce-gateway-stripe' ) );
 			}
 
-			wp_send_json_success( $this->update_payment_intent( $payment_intent_id, $order_id, $save_payment_method, $selected_upe_payment_type ), 200 );
+			wp_send_json_success( $this->update_intent( $payment_intent_id, $order_id, $save_payment_method, $selected_upe_payment_type ), 200 );
 		} catch ( Exception $e ) {
 			// Send back error so it can be displayed to the customer.
 			wp_send_json_error(
@@ -427,19 +427,20 @@ public function update_payment_intent_ajax() {
 	}
 
 	/**
-	 * Updates payment intent to be able to save payment method.
+	 * Updates payment intent or setup intent to be able to save payment method.
 	 *
 	 * @since 5.6.0
+	 * @version x.x.x
 	 *
-	 * @param {string}  $payment_intent_id         The id of the payment intent to update.
+	 * @param {string}  $intent_id                 The id of the payment intent or setup intent to update.
 	 * @param {int}     $order_id                  The id of the order if intent created from Order.
 	 * @param {boolean} $save_payment_method       True if saving the payment method.
 	 * @param {string}  $selected_upe_payment_type The name of the selected UPE payment type or empty string.
 	 *
 	 * @throws Exception  If the update intent call returns with an error.
 	 * @return array|null An array with result of the update, or nothing
 	 */
-	public function update_payment_intent( $payment_intent_id = '', $order_id = null, $save_payment_method = false, $selected_upe_payment_type = '' ) {
+	public function update_intent( $intent_id = '', $order_id = null, $save_payment_method = false, $selected_upe_payment_type = '' ) {
 		$order = wc_get_order( $order_id );
 
 		if ( ! is_a( $order, 'WC_Order' ) ) {
@@ -451,16 +452,20 @@ public function update_payment_intent( $payment_intent_id = '', $order_id = null
 		$currency = $order->get_currency();
 		$customer = new WC_Stripe_Customer( wp_get_current_user()->ID );
 
-		if ( $payment_intent_id ) {
-
+		if ( $intent_id ) {
 			$request = [
-				'amount'      => WC_Stripe_Helper::get_stripe_amount( $amount, strtolower( $currency ) ),
-				'currency'    => strtolower( $currency ),
 				'metadata'    => $gateway->get_metadata_from_order( $order ),
 				/* translators: 1) blog name 2) order number */
 				'description' => sprintf( __( '%1$s - Order %2$s', 'woocommerce-gateway-stripe' ), wp_specialchars_decode( get_bloginfo( 'name' ), ENT_QUOTES ), $order->get_order_number() ),
 			];
 
+			$is_setup_intent = substr( $intent_id, 0, 4 ) === 'seti';
+			if ( ! $is_setup_intent ) {
+				// These parameters are only supported for payment intents.
+				$request['amount']   = WC_Stripe_Helper::get_stripe_amount( $amount, strtolower( $currency ) );
+				$request['currency'] = strtolower( $currency );
+			}
+
 			if ( '' !== $selected_upe_payment_type ) {
 				// Only update the payment_method_types if we have a reference to the payment type the customer selected.
 				$request['payment_method_types'] = [ $selected_upe_payment_type ];
@@ -488,16 +493,21 @@ public function update_payment_intent( $payment_intent_id = '', $order_id = null
 
 			$level3_data = $gateway->get_level3_data_from_order( $order );
 
+			// Use "setup_intents" endpoint if `$intent_id` starts with `seti_`.
+			$endpoint = $is_setup_intent ? 'setup_intents' : 'payment_intents';
 			WC_Stripe_API::request_with_level3_data(
 				$request,
-				"payment_intents/{$payment_intent_id}",
+				"{$endpoint}/{$intent_id}",
 				$level3_data,
 				$order
 			);
 
-			$order->update_status( OrderStatus::PENDING, __( 'Awaiting payment.', 'woocommerce-gateway-stripe' ) );
+			// Prevent any failures if updating the status of a subscription order.
+			if ( ! $gateway->has_subscription( $order_id ) ) {
+				$order->update_status( OrderStatus::PENDING, __( 'Awaiting payment.', 'woocommerce-gateway-stripe' ) );
+			}
 			$order->save();
-			WC_Stripe_Helper::add_payment_intent_to_order( $payment_intent_id, $order );
+			WC_Stripe_Helper::add_payment_intent_to_order( $intent_id, $order );
 		}
 
 		return [
@@ -822,8 +832,8 @@ private function maybe_add_mandate_options( $request, $payment_method_type, $is_
 			$request['payment_method_options'] = [
 				WC_Stripe_Payment_Methods::ACSS_DEBIT => [
 					'mandate_options' => [
-						'payment_schedule'     => 'interval',
-						'interval_description' => __( 'One-time payment', 'woocommerce-gateway-stripe' ), // TODO: Change to cadence if purchasing a subscription.
+						'payment_schedule'     => 'combined',
+						'interval_description' => __( 'Payments as per agreement', 'woocommerce-gateway-stripe' ),
 						'transaction_type'     => 'personal',
 					],
 				],

includes/compat/trait-wc-stripe-subscriptions.php

@@ -741,9 +741,9 @@ public function validate_subscription_payment_meta( $payment_method_id, $payment
 	 * mandates for 3DS payments in India. It's ok to apply this across the board; Stripe will
 	 * take care of handling any authorizations.
 	 *
-	 * @param Array    $request          The HTTP request that will be sent to Stripe to create the payment intent.
+	 * @param array    $request          The HTTP request that will be sent to Stripe to create the payment intent.
 	 * @param WC_Order $order            The renewal order.
-	 * @param Array    $prepared_source  The source object.
+	 * @param object   $prepared_source  The source object.
 	 */
 	public function add_subscription_information_to_intent( $request, $order, $prepared_source ) {
 		// Just in case the order doesn't contain a subscription we return the base request.
@@ -783,6 +783,7 @@ public function add_subscription_information_to_intent( $request, $order, $prepa
 		}
 
 		// Add mandate options to request to create new mandate if mandate id does not already exist in a previous renewal or parent order.
+		// Note: This is for backwards compatibility if `_stripe_mandate_id` is not set.
 		$mandate_options = $this->create_mandate_options_for_order( $order, $subscriptions_for_renewal_order );
 		if ( ! empty( $mandate_options ) ) {
 			$request['payment_method_options']['card']['mandate_options'] = $mandate_options;
@@ -1000,12 +1001,20 @@ public function maybe_render_subscription_payment_method( $payment_method_to_dis
 							break 3;
 						case WC_Stripe_Payment_Methods::ACH:
 							$payment_method_to_display = sprintf(
-								/* translators: account type (checking, savings), last 4 digits of account. */
+								/* translators: 1) account type (checking, savings), 2) last 4 digits of account. */
 								__( 'Via %1$s Account ending in %2$s', 'woocommerce-gateway-stripe' ),
 								ucfirst( $source->us_bank_account->account_type ),
 								$source->us_bank_account->last4
 							);
 							break 3;
+						case WC_Stripe_Payment_Methods::ACSS_DEBIT:
+							$payment_method_to_display = sprintf(
+								/* translators: 1) bank name, 2) last 4 digits of account. */
+								__( 'Via %1$s ending in %2$s', 'woocommerce-gateway-stripe' ),
+								$source->acss_debit->bank_name,
+								$source->acss_debit->last4
+							);
+							break 3;
 						case WC_Stripe_Payment_Methods::BACS_DEBIT:
 							/* translators: 1) the Bacs Direct Debit payment method's last 4 numbers */
 							$payment_method_to_display = sprintf( __( 'Via Bacs Direct Debit ending in (%1$s)', 'woocommerce-gateway-stripe' ), $source->bacs_debit->last4 );

includes/payment-methods/class-wc-stripe-upe-payment-gateway.php

@@ -731,7 +731,7 @@ public function process_payment( $order_id, $retry = true, $force_save_source =
 		if ( $payment_intent_id && ! $this->payment_methods[ $selected_payment_type ]->supports_deferred_intent() ) {
 			// Adds customer and metadata to PaymentIntent.
 			// These parameters cannot be added upon updating the intent via the `/confirm` API.
-			$this->intent_controller->update_payment_intent( $payment_intent_id, $order_id );
+			$this->intent_controller->update_intent( $payment_intent_id, $order_id );
 		}
 
 		// Flag for using a deferred intent. To be removed.

includes/payment-methods/class-wc-stripe-upe-payment-method-acss.php

@@ -7,6 +7,7 @@
  * The Canadian Pre-Authorized Debit (ACSS Debit) Payment Method class extending UPE base class
  */
 class WC_Stripe_UPE_Payment_Method_ACSS extends WC_Stripe_UPE_Payment_Method {
+	use WC_Stripe_Subscriptions_Trait;
 
 	const STRIPE_ID = WC_Stripe_Payment_Methods::ACSS_DEBIT;
 
@@ -27,6 +28,10 @@ public function __construct() {
 		);
 		$this->supports_deferred_intent = false;
 		$this->supports[]               = 'tokenization';
+		$this->supports[]               = 'subscriptions';
+
+		// Check if subscriptions are enabled and add support for them.
+		$this->maybe_init_subscriptions();
 	}
 
 	/**

readme.txt

@@ -142,5 +142,6 @@ If you get stuck, you can ask for help in the [Plugin Forum](https://wordpress.o
 * Fix - Fix subscription renewal issues for Amazon Pay.
 * Tweak - SPE: Remove radio buttons
 * Update - Hide express checkout buttons when no product variation is selected.
+* Add - Add ACSS support for WC Subscriptions.
 
 [See changelog for all versions](https://raw.githubusercontent.com/woocommerce/woocommerce-gateway-stripe/trunk/changelog.txt).