<?php
declare( strict_types=1 );

namespace Automattic\WooCommerce\Internal\Admin\Settings\PaymentProviders\WooPayments;

use Automattic\Jetpack\Connection\Manager as WPCOM_Connection_Manager;
use Automattic\Jetpack\Constants;
use Automattic\WooCommerce\Internal\Admin\Settings\Exceptions\ApiArgumentException;
use Automattic\WooCommerce\Internal\Admin\Settings\Exceptions\ApiException;
use Automattic\WooCommerce\Internal\Admin\Settings\PaymentProviders;
use Automattic\WooCommerce\Internal\Admin\Settings\Utils;
use Automattic\WooCommerce\Proxies\LegacyProxy;
use Exception;
use WP_Error;
use WP_Http;

defined( 'ABSPATH' ) || exit;
/**
 * WooPayments-specific Payments settings page service class.
 */
class WooPaymentsService {

	const GATEWAY_ID = 'woocommerce_payments';

	/**
	 * The minimum required version of the WooPayments extension.
	 */
	const EXTENSION_MINIMUM_VERSION = '9.3.0';

	const ONBOARDING_PATH_BASE = '/woopayments/onboarding';

	const ONBOARDING_STEP_PAYMENT_METHODS       = 'payment_methods';
	const ONBOARDING_STEP_WPCOM_CONNECTION      = 'wpcom_connection';
	const ONBOARDING_STEP_TEST_ACCOUNT          = 'test_account';
	const ONBOARDING_STEP_BUSINESS_VERIFICATION = 'business_verification';

	/**
	 * A step is not started if the user has not interacted with it yet.
	 */
	const ONBOARDING_STEP_STATUS_NOT_STARTED = 'not_started';

	/**
	 * A step should be considered started if the user has interacted with it.
	 * There will be cases where a step may be auto-started based on the current state of the store.
	 */
	const ONBOARDING_STEP_STATUS_STARTED = 'started';

	/**
	 * A step is completed if the user has successfully completed it.
	 * This is the final state of a step.
	 */
	const ONBOARDING_STEP_STATUS_COMPLETED = 'completed';

	/**
	 * Failure generally refers to some error that occurred during a step action.
	 * Retrying the action should be possible and lead to a different step status.
	 */
	const ONBOARDING_STEP_STATUS_FAILED = 'failed';

	/**
	 * Blocked generally refers to a step can't progress to a completed state due to some technical requirements
	 * that are beyond the purview of the Payments Settings page or the WooPayments extension.
	 * Most of the time, the reasons will be environment-related.
	 * For example, the store may not use HTTPS, or live onboarding might be prevented due to environment settings.
	 */
	const ONBOARDING_STEP_STATUS_BLOCKED = 'blocked';

	const ACTION_TYPE_REST     = 'REST';
	const ACTION_TYPE_REDIRECT = 'REDIRECT';

	const NOX_PROFILE_OPTION_KEY    = 'woocommerce_woopayments_nox_profile';
	const NOX_ONBOARDING_LOCKED_KEY = 'woocommerce_woopayments_nox_onboarding_locked';

	const FROM_PAYMENT_SETTINGS = 'WCADMIN_PAYMENT_SETTINGS';
	const FROM_NOX_IN_CONTEXT   = 'WCADMIN_NOX_IN_CONTEXT';
	const FROM_KYC              = 'KYC';

	const EVENT_PREFIX = 'settings_payments_woopayments_';

	/**
	 * The PaymentProviders instance.
	 *
	 * @var PaymentProviders
	 */
	private PaymentProviders $payment_providers;

	/**
	 * The LegacyProxy instance.
	 *
	 * @var LegacyProxy
	 */
	private LegacyProxy $proxy;

	/**
	 * The WPCOM connection manager instance.
	 *
	 * @var WPCOM_Connection_Manager|object
	 */
	private $wpcom_connection_manager;

	/**
	 * The WooPayments provider instance.
	 *
	 * @var PaymentProviders\PaymentGateway
	 */
	private PaymentProviders\PaymentGateway $provider;

	/**
	 * Initialize the class instance.
	 *
	 * @internal
	 *
	 * @param PaymentProviders $payment_providers The PaymentProviders instance.
	 * @param LegacyProxy      $proxy             The LegacyProxy instance.
	 */
	final public function init( PaymentProviders $payment_providers, LegacyProxy $proxy ): void {
		$this->payment_providers = $payment_providers;
		$this->proxy             = $proxy;

		$this->wpcom_connection_manager = $this->proxy->get_instance_of( WPCOM_Connection_Manager::class, 'woocommerce' );
		$this->provider                 = $this->payment_providers->get_payment_gateway_provider_instance( self::GATEWAY_ID );
	}

	/**
	 * Get the onboarding details for the settings page.
	 *
	 * @param string $location  The location for which we are onboarding.
	 *                          This is a ISO 3166-1 alpha-2 country code.
	 * @param string $rest_path The REST API path to use for constructing REST API URLs.
	 *
	 * @return array The onboarding details.
	 * @throws ApiException If the onboarding action can not be performed due to the current state of the site.
	 * @throws Exception If there were errors when generating the onboarding details.
	 */
	public function get_onboarding_details( string $location, string $rest_path ): array {
		// Since getting the onboarding details is not idempotent, we will check it as an action.
		$this->check_if_onboarding_action_is_acceptable();

		return array(
			// This state is high-level data, independent of the type of onboarding flow.
			'state'   => array(
				'started'   => $this->provider->is_onboarding_started( $this->get_payment_gateway() ),
				'completed' => $this->provider->is_onboarding_completed( $this->get_payment_gateway() ),
				'test_mode' => $this->provider->is_in_test_mode_onboarding( $this->get_payment_gateway() ),
				'dev_mode'  => $this->provider->is_in_dev_mode( $this->get_payment_gateway() ),
			),
			'steps'   => $this->get_onboarding_steps( $location, trailingslashit( $rest_path ) . 'step' ),
			'context' => array(
				'urls' => array(
					'overview_page' => $this->get_overview_page_url(),
				),
			),
		);
	}

	/**
	 * Check if the given onboarding step ID is valid.
	 *
	 * @param string $step_id The ID of the onboarding step.
	 *
	 * @return bool Whether the given onboarding step ID is valid.
	 */
	public function is_valid_onboarding_step_id( string $step_id ): bool {
		return in_array(
			$step_id,
			array(
				self::ONBOARDING_STEP_PAYMENT_METHODS,
				self::ONBOARDING_STEP_WPCOM_CONNECTION,
				self::ONBOARDING_STEP_TEST_ACCOUNT,
				self::ONBOARDING_STEP_BUSINESS_VERIFICATION,
			),
			true
		);
	}

	/**
	 * Get the status of an onboarding step.
	 *
	 * @param string $step_id  The ID of the onboarding step.
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 *
	 * @return string The status of the onboarding step.
	 * @throws ApiArgumentException If the given onboarding step ID is invalid.
	 */
	public function get_onboarding_step_status( string $step_id, string $location ): string {
		if ( ! $this->is_valid_onboarding_step_id( $step_id ) ) {
			throw new ApiArgumentException(
				'woocommerce_woopayments_onboarding_invalid_step_id',
				esc_html__( 'Invalid onboarding step ID.', 'woocommerce' ),
				(int) WP_Http::BAD_REQUEST
			);
		}

		$meets_requirements = $this->check_onboarding_step_requirements( $step_id, $location );

		// First, determine if the step should be reported as completed based on the current state of the store.
		// The step can only be auto-completed if the requirements are met.
		if ( $meets_requirements ) {
			switch ( $step_id ) {
				case self::ONBOARDING_STEP_PAYMENT_METHODS:
					// If there is already a valid account, report the step as completed
					// since allowing the user to configure payment methods won't have any effect.
					if ( $this->has_valid_account() ) {
						return self::ONBOARDING_STEP_STATUS_COMPLETED;
					}
					break;
				case self::ONBOARDING_STEP_WPCOM_CONNECTION:
					// If we have a working WPCOM connection, report the step as completed.
					// The step can only be auto-completed if the requirements are met.
					if ( $this->has_working_wpcom_connection() ) {
						return self::ONBOARDING_STEP_STATUS_COMPLETED;
					}
					break;
				case self::ONBOARDING_STEP_TEST_ACCOUNT:
					// If the account is a valid, working test account, the step is completed.
					if ( $this->has_test_account() && $this->has_valid_account() && $this->has_working_account() ) {
						return self::ONBOARDING_STEP_STATUS_COMPLETED;
					}
					break;
				case self::ONBOARDING_STEP_BUSINESS_VERIFICATION:
					// The step can only be auto-completed if the requirements are met.
					// If the current account is fully onboarded and is a live account,
					// we report the business verification step as completed.
					if ( $this->has_valid_account() && $this->has_live_account() ) {
						return self::ONBOARDING_STEP_STATUS_COMPLETED;
					}
					break;
			}
		}

		// Second, try to determine the status of the onboarding step based on the step's stored statuses.
		// We take a waterfall approach: completed > blocked > failed > started > not started.
		// Reporting a completed status involves additional logic.
		switch ( $step_id ) {
			case self::ONBOARDING_STEP_WPCOM_CONNECTION:
				// Ignore any completed stored statuses because of the critical nature of the WPCOM connection.
				break;
			case self::ONBOARDING_STEP_TEST_ACCOUNT:
				// If there is a stored completed status, we respect that IF there is NO invalid test account.
				// This is the case when the user first creates a test account and then switches to live.
				// The step can only be completed if the requirements are met.
				if ( $meets_requirements &&
					$this->was_onboarding_step_marked_completed( $step_id, $location ) &&
					! ( $this->has_test_account() && ! $this->has_valid_account() )
				) {
					return self::ONBOARDING_STEP_STATUS_COMPLETED;
				}
				break;
			case self::ONBOARDING_STEP_PAYMENT_METHODS:
			case self::ONBOARDING_STEP_BUSINESS_VERIFICATION:
			default:
				// The step can only be completed if the requirements are met. Otherwise, ignore the stored completed status.
				if ( $meets_requirements && $this->was_onboarding_step_marked_completed( $step_id, $location ) ) {
					return self::ONBOARDING_STEP_STATUS_COMPLETED;
				}

				break;
		}
		// Blocked and failed statuses are only reported if the step's requirements are met.
		if ( $meets_requirements ) {
			if ( $this->is_onboarding_step_blocked( $step_id, $location ) ) {
				return self::ONBOARDING_STEP_STATUS_BLOCKED;
			}
			if ( $this->is_onboarding_step_failed( $step_id, $location ) ) {
				return self::ONBOARDING_STEP_STATUS_FAILED;
			}
		}
		if ( $this->was_onboarding_step_marked_started( $step_id, $location ) ) {
			return self::ONBOARDING_STEP_STATUS_STARTED;
		}

		// Finally, we default to not started.
		return self::ONBOARDING_STEP_STATUS_NOT_STARTED;
	}

	/**
	 * Check if the onboarding step has a started status.
	 *
	 * @param string $step_id  The ID of the onboarding step.
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 *
	 * @return bool Whether the onboarding step is started.
	 * @throws ApiException On invalid step ID.
	 */
	private function is_onboarding_step_started( string $step_id, string $location ): bool {
		return self::ONBOARDING_STEP_STATUS_COMPLETED === $this->get_onboarding_step_status( $step_id, $location );
	}

	/**
	 * Check if an onboarding step has been marked as started.
	 *
	 * This means that, at some point, the step was marked/recorded as started in the DB.
	 * This doesn't mean that the current reported status is started. The step status might be different now.
	 *
	 * @see get_onboarding_step_status() for that.
	 *
	 * @param string $step_id  The ID of the onboarding step.
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 *
	 * @return bool Whether the onboarding step has been marked as started.
	 */
	private function was_onboarding_step_marked_started( string $step_id, string $location ): bool {
		$statuses = (array) $this->get_nox_profile_onboarding_step_entry( $step_id, $location, 'statuses' );

		return ! empty( $statuses[ self::ONBOARDING_STEP_STATUS_STARTED ] );
	}

	/**
	 * Mark an onboarding step as started.
	 *
	 * @param string $step_id   The ID of the onboarding step.
	 * @param string $location  The location for which we are onboarding.
	 *                          This is a ISO 3166-1 alpha-2 country code.
	 * @param bool   $overwrite Whether to overwrite the step status if it is already started and update the timestamp.
	 *
	 * @return bool Whether the onboarding step was marked as started.
	 * @throws ApiArgumentException If the given onboarding step ID is invalid.
	 * @throws ApiException If the onboarding action can not be performed due to the current state of the site.
	 */
	public function mark_onboarding_step_started( string $step_id, string $location, bool $overwrite = false ): bool {
		$this->check_if_onboarding_step_action_is_acceptable( $step_id, $location );

		// Clear possible failed status for the step.
		$this->clear_onboarding_step_failed( $step_id, $location );

		$statuses = (array) $this->get_nox_profile_onboarding_step_entry( $step_id, $location, 'statuses' );
		if ( ! $overwrite && ! empty( $statuses[ self::ONBOARDING_STEP_STATUS_STARTED ] ) ) {
			return true;
		}

		// Mark the step as started and record the timestamp.
		$statuses[ self::ONBOARDING_STEP_STATUS_STARTED ] = $this->proxy->call_function( 'time' );

		// Store the updated step data.
		$result = $this->save_nox_profile_onboarding_step_entry( $step_id, $location, 'statuses', $statuses );

		if ( $result ) {
			// Record an event for the step being started.
			$this->record_event(
				self::EVENT_PREFIX . 'onboarding_step_started',
				$location,
				array(
					'step_id' => $step_id,
				)
			);
		}

		return $result;
	}

	/**
	 * Check if the onboarding step has a completed status.
	 *
	 * @param string $step_id  The ID of the onboarding step.
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 *
	 * @return bool Whether the onboarding step is completed.
	 * @throws ApiException On invalid step ID.
	 */
	private function is_onboarding_step_completed( string $step_id, string $location ): bool {
		return self::ONBOARDING_STEP_STATUS_COMPLETED === $this->get_onboarding_step_status( $step_id, $location );
	}

	/**
	 * Check if an onboarding step has been marked as completed.
	 *
	 * This means that, at some point, the step was marked/recorded as completed in the DB.
	 * This doesn't mean that the current reported status is completed. The step status might be different now.
	 *
	 * @see get_onboarding_step_status() for that.
	 *
	 * @param string $step_id  The ID of the onboarding step.
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 *
	 * @return bool Whether the onboarding step has been marked as completed.
	 */
	private function was_onboarding_step_marked_completed( string $step_id, string $location ): bool {
		$statuses = (array) $this->get_nox_profile_onboarding_step_entry( $step_id, $location, 'statuses' );

		return ! empty( $statuses[ self::ONBOARDING_STEP_STATUS_COMPLETED ] );
	}

	/**
	 * Mark an onboarding step as completed.
	 *
	 * @param string $step_id   The ID of the onboarding step.
	 * @param string $location  The location for which we are onboarding.
	 *                          This is a ISO 3166-1 alpha-2 country code.
	 * @param bool   $overwrite Whether to overwrite the step status if it is already completed and update the timestamp.
	 *
	 * @return bool Whether the onboarding step was marked as completed.
	 * @throws ApiArgumentException If the given onboarding step ID is invalid.
	 * @throws ApiException If the onboarding action can not be performed due to the current state of the site.
	 */
	public function mark_onboarding_step_completed( string $step_id, string $location, bool $overwrite = false ): bool {
		$this->check_if_onboarding_step_action_is_acceptable( $step_id, $location );

		// Clear possible failed status for the step.
		$this->clear_onboarding_step_failed( $step_id, $location );

		$statuses = (array) $this->get_nox_profile_onboarding_step_entry( $step_id, $location, 'statuses' );
		if ( ! $overwrite && ! empty( $statuses[ self::ONBOARDING_STEP_STATUS_COMPLETED ] ) ) {
			return true;
		}

		// Mark the step as completed and record the timestamp.
		$statuses[ self::ONBOARDING_STEP_STATUS_COMPLETED ] = $this->proxy->call_function( 'time' );

		// Store the updated step data.
		$result = $this->save_nox_profile_onboarding_step_entry( $step_id, $location, 'statuses', $statuses );

		if ( $result ) {
			// Record an event for the step being completed.
			$this->record_event(
				self::EVENT_PREFIX . 'onboarding_step_completed',
				$location,
				array(
					'step_id' => $step_id,
				)
			);
		}

		return $result;
	}

	/**
	 * Cleans an onboarding step progress.
	 *
	 * @param string $step_id   The ID of the onboarding step.
	 * @param string $location  The location for which we are onboarding.
	 *                          This is a ISO 3166-1 alpha-2 country code.
	 *
	 * @return bool Whether the onboarding step was cleaned.
	 * @throws ApiArgumentException If the given onboarding step ID is invalid.
	 * @throws ApiException If the onboarding action can not be performed due to the current state of the site.
	 */
	public function clean_onboarding_step_progress( string $step_id, string $location ): bool {
		$this->check_if_onboarding_step_action_is_acceptable( $step_id, $location );

		// Clear possible failed or blocked status for the step.
		$this->clear_onboarding_step_failed( $step_id, $location );
		$this->clear_onboarding_step_blocked( $step_id, $location );

		// Reset the stored step statuses.
		$result = $this->save_nox_profile_onboarding_step_entry( $step_id, $location, 'statuses', array() );

		if ( $result ) {
			// Record an event for the step being cleaned.
			$this->record_event(
				self::EVENT_PREFIX . 'onboarding_step_progress_reset',
				$location,
				array(
					'step_id' => $step_id,
				)
			);
		}

		return $result;
	}

	/**
	 * Check if an onboarding step has a failed status.
	 *
	 * @param string $step_id  The ID of the onboarding step.
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 *
	 * @return bool Whether the onboarding step is failed.
	 */
	private function is_onboarding_step_failed( string $step_id, string $location ): bool {
		$statuses = (array) $this->get_nox_profile_onboarding_step_entry( $step_id, $location, 'statuses' );

		return ! empty( $statuses[ self::ONBOARDING_STEP_STATUS_FAILED ] );
	}

	/**
	 * Mark an onboarding step as failed.
	 *
	 * This is for internal use only as a failed step status should not be the result of a user action.
	 *
	 * @param string $step_id  The ID of the onboarding step.
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 * @param array  $error    Optional. An error to be stored for the step to provide context to API consumers.
	 *                         The error should be an associative array with the following keys:
	 *                         - 'code': A string representing the error code.
	 *                         - 'message': A string representing the error message.
	 *                         - 'context': Optional. An array of additional data related to the error.
	 *
	 * @return bool Whether the onboarding step was marked as failed.
	 */
	private function mark_onboarding_step_failed( string $step_id, string $location, array $error = array() ): bool {
		// There is no need to do onboarding checks because setting a step as failed should be possible at any time.

		// Record the error for the step, even if it is empty.
		// This will ensure we only store the most recent error.
		$this->save_nox_profile_onboarding_step_data_entry( $step_id, $location, 'error', $this->sanitize_onboarding_step_error( $error ) );

		$statuses = (array) $this->get_nox_profile_onboarding_step_entry( $step_id, $location, 'statuses' );

		// Mark the step as failed and record the timestamp.
		$statuses[ self::ONBOARDING_STEP_STATUS_FAILED ] = $this->proxy->call_function( 'time' );

		// Make sure we clear the blocked status if it was set since blocked and failed should be mutually exclusive.
		unset( $statuses[ self::ONBOARDING_STEP_STATUS_BLOCKED ] );

		// Store the updated step data.
		$result = $this->save_nox_profile_onboarding_step_entry( $step_id, $location, 'statuses', $statuses );

		if ( $result ) {
			// Record an event for the step being failed.
			$this->record_event(
				self::EVENT_PREFIX . 'onboarding_step_failed',
				$location,
				array(
					'step_id'    => $step_id,
					'error_code' => ! empty( $error['code'] ) ? $error['code'] : '',
				)
			);
		}

		return $result;
	}

	/**
	 * Clear the failed status of an onboarding step.
	 *
	 * @param string $step_id  The ID of the onboarding step.
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 *
	 * @return bool Whether the onboarding step was cleared from failed status.
	 *              Returns false if the step was not failed.
	 */
	private function clear_onboarding_step_failed( string $step_id, string $location ): bool {
		if ( ! $this->is_onboarding_step_failed( $step_id, $location ) ) {
			return false;
		}

		// Clear any error for the step.
		$this->save_nox_profile_onboarding_step_data_entry( $step_id, $location, 'error', array() );

		$statuses = (array) $this->get_nox_profile_onboarding_step_entry( $step_id, $location, 'statuses' );

		// Clear the failed status.
		unset( $statuses[ self::ONBOARDING_STEP_STATUS_FAILED ] );

		// Store the updated step data.
		return $this->save_nox_profile_onboarding_step_entry( $step_id, $location, 'statuses', $statuses );
	}

	/**
	 * Check if an onboarding step has a blocked status.
	 *
	 * @param string $step_id The ID of the onboarding step.
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 *
	 * @return bool Whether the onboarding step is blocked.
	 */
	private function is_onboarding_step_blocked( string $step_id, string $location ): bool {
		$statuses = (array) $this->get_nox_profile_onboarding_step_entry( $step_id, $location, 'statuses' );

		return ! empty( $statuses[ self::ONBOARDING_STEP_STATUS_BLOCKED ] );
	}

	/**
	 * Mark an onboarding step as blocked.
	 *
	 * This is for internal use only as a blocked step status should not be the result of a user action.
	 *
	 * @param string $step_id  The ID of the onboarding step.
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 * @param array  $errors   Optional. A list of errors to be stored for the step to provide context to API consumers.
	 *
	 * @return bool Whether the onboarding step was marked as blocked.
	 */
	private function mark_onboarding_step_blocked( string $step_id, string $location, array $errors = array() ): bool {
		// There is no need to do onboarding checks because setting a step as blocked should be possible at any time.

		// Record the error for the step, even if it is empty.
		// This will ensure we only store the most recent error.
		$this->save_nox_profile_onboarding_step_data_entry( $step_id, $location, 'error', $this->sanitize_onboarding_step_error( $errors ) );

		$statuses = (array) $this->get_nox_profile_onboarding_step_entry( $step_id, $location, 'statuses' );

		// Mark the step as blocked and record the timestamp.
		$statuses[ self::ONBOARDING_STEP_STATUS_BLOCKED ] = $this->proxy->call_function( 'time' );

		// Make sure we clear the failed status if it was set since blocked and failed should be mutually exclusive.
		unset( $statuses[ self::ONBOARDING_STEP_STATUS_FAILED ] );

		// Store the updated step data.
		return $this->save_nox_profile_onboarding_step_entry( $step_id, $location, 'statuses', $statuses );
	}

	/**
	 * Clear the blocked status of an onboarding step.
	 *
	 * @param string $step_id  The ID of the onboarding step.
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 *
	 * @return bool Whether the onboarding step was cleared from blocked status.
	 *              Returns false if the step was not blocked.
	 */
	private function clear_onboarding_step_blocked( string $step_id, string $location ): bool {
		if ( ! $this->is_onboarding_step_blocked( $step_id, $location ) ) {
			return false;
		}

		// Clear any error for the step.
		$this->save_nox_profile_onboarding_step_data_entry( $step_id, $location, 'error', array() );

		$statuses = (array) $this->get_nox_profile_onboarding_step_entry( $step_id, $location, 'statuses' );

		// Clear the blocked status.
		unset( $statuses[ self::ONBOARDING_STEP_STATUS_BLOCKED ] );

		// Store the updated step data.
		return $this->save_nox_profile_onboarding_step_entry( $step_id, $location, 'statuses', $statuses );
	}

	/**
	 * Get the current stored error for an onboarding step.
	 *
	 * @param string $step_id  The ID of the onboarding step.
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 *
	 * @return array The error for the onboarding step.
	 */
	private function get_onboarding_step_error( string $step_id, string $location ): array {
		return (array) $this->get_nox_profile_onboarding_step_data_entry( $step_id, $location, 'error', array() );
	}

	/**
	 * Sanitize an error for an onboarding step.
	 *
	 * @param array $error The error to sanitize.
	 *
	 * @return array The sanitized error.
	 */
	private function sanitize_onboarding_step_error( array $error ): array {
		$sanitized_error = array(
			'code'    => isset( $error['code'] ) ? sanitize_text_field( $error['code'] ) : '',
			'message' => isset( $error['message'] ) ? sanitize_text_field( $error['message'] ) : '',
			'context' => array(),
		);

		if ( isset( $error['context'] ) && ( is_array( $error['context'] ) || is_object( $error['context'] ) ) ) {
			// Make sure we are dealing with an array.
			$sanitized_error['context'] = json_decode( wp_json_encode( $error['context'] ), true );
			if ( ! is_array( $sanitized_error['context'] ) ) {
				$sanitized_error['context'] = array();
			}

			// Sanitize the context data.
			// It can only contain strings or arrays of strings.
			// Scalar values will be converted to strings. Other types will be ignored.
			foreach ( $sanitized_error['context'] as $key => $value ) {
				if ( is_string( $value ) ) {
					$sanitized_error['context'][ $key ] = sanitize_text_field( $value );
				} elseif ( is_array( $value ) ) {
					// Arrays can only contain strings.
					$sanitized_error['context'][ $key ] = array_map(
						function ( $item ) {
							if ( is_string( $item ) ) {
								return sanitize_text_field( $item );
							} elseif ( is_scalar( $item ) ) {
								return sanitize_text_field( (string) $item );
							} else {
								return '';
							}
						},
						$value
					);
					// Remove any empty values from the array.
					$sanitized_error['context'][ $key ] = array_filter(
						$sanitized_error['context'][ $key ],
						function ( $item ) {
							return '' !== $item;
						}
					);
				} else {
					unset( $sanitized_error['context'][ $key ] );
				}
			}
		}

		return $sanitized_error;
	}

	/**
	 * Save the data for an onboarding step.
	 *
	 * @param string $step_id      The ID of the onboarding step.
	 * @param string $location     The location for which we are onboarding.
	 *                             This is a ISO 3166-1 alpha-2 country code.
	 * @param array  $request_data The entire data received in the request.
	 *
	 * @return bool Whether the onboarding step data was saved.
	 * @throws ApiArgumentException If the given onboarding step ID or step data is invalid.
	 * @throws ApiException If the onboarding action can not be performed due to the current state of the site.
	 */
	public function onboarding_step_save( string $step_id, string $location, array $request_data ): bool {
		$this->check_if_onboarding_step_action_is_acceptable( $step_id, $location );

		// Validate the received step data.
		// If we didn't receive any known data for the step, we consider it an invalid save operation.
		if ( ! $this->is_valid_onboarding_step_data( $step_id, $request_data ) ) {
			throw new ApiArgumentException(
				'woocommerce_woopayments_onboarding_invalid_step_data',
				esc_html__( 'Invalid onboarding step data.', 'woocommerce' ),
				(int) WP_Http::BAD_REQUEST
			);
		}

		$step_details = $this->get_nox_profile_onboarding_step( $step_id, $location );
		if ( empty( $step_details['data'] ) ) {
			$step_details['data'] = array();
		}

		// Extract the data for the step.
		switch ( $step_id ) {
			case self::ONBOARDING_STEP_PAYMENT_METHODS:
				if ( isset( $request_data['payment_methods'] ) ) {
					$step_details['data']['payment_methods'] = $request_data['payment_methods'];
				}
				break;
			case self::ONBOARDING_STEP_BUSINESS_VERIFICATION:
				if ( isset( $request_data['self_assessment'] ) ) {
					$step_details['data']['self_assessment'] = $request_data['self_assessment'];
				}
				if ( isset( $request_data['sub_steps'] ) ) {
					$step_details['data']['sub_steps'] = $request_data['sub_steps'];
				}
				break;
			default:
				throw new ApiException(
					'woocommerce_woopayments_onboarding_step_action_not_supported',
					esc_html__( 'Save action not supported for the onboarding step ID.', 'woocommerce' ),
					(int) WP_Http::NOT_ACCEPTABLE
				);
		}

		// Store the updated step data.
		return $this->save_nox_profile_onboarding_step( $step_id, $location, $step_details );
	}

	/**
	 * Check if the given onboarding step data is valid.
	 *
	 * If we didn't receive any known data for the step, we consider it invalid.
	 *
	 * @param string $step_id      The ID of the onboarding step.
	 * @param array  $request_data The entire data received in the request.
	 *
	 * @return bool Whether the given onboarding step data is valid.
	 */
	private function is_valid_onboarding_step_data( string $step_id, array $request_data ): bool {
		switch ( $step_id ) {
			case self::ONBOARDING_STEP_PAYMENT_METHODS:
				// Check that we have at least one piece of data.
				if ( ! isset( $request_data['payment_methods'] ) ) {
					return false;
				}

				// Check that the data is in the expected format.
				if ( ! is_array( $request_data['payment_methods'] ) ) {
					return false;
				}
				break;
			case self::ONBOARDING_STEP_BUSINESS_VERIFICATION:
				// Check that we have at least one piece of data.
				if ( ! isset( $request_data['self_assessment'] ) &&
					! isset( $request_data['sub_steps'] ) ) {
					return false;
				}

				// Check that the data is in the expected format.
				if ( isset( $request_data['self_assessment'] ) && ! is_array( $request_data['self_assessment'] ) ) {
					return false;
				}
				if ( isset( $request_data['sub_steps'] ) && ! is_array( $request_data['sub_steps'] ) ) {
					return false;
				}
				break;
			default:
				// If we don't know how to validate the data, we assume it is valid.
				return true;
		}

		return true;
	}

	/**
	 * Check an onboarding step's status/progress.
	 *
	 * @param string $step_id The ID of the onboarding step.
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 *
	 * @return array The check result.
	 * @throws ApiArgumentException If the given onboarding step ID or step data is invalid.
	 * @throws ApiException If the onboarding action can not be performed due to the current state of the site.
	 */
	public function onboarding_step_check( string $step_id, string $location ): array {
		$this->check_if_onboarding_step_action_is_acceptable( $step_id, $location );

		return array(
			'status' => $this->get_onboarding_step_status( $step_id, $location ),
			'error'  => $this->get_onboarding_step_error( $step_id, $location ),
		);
	}

	/**
	 * Get the recommended payment methods details for onboarding.
	 *
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 *
	 * @return array The recommended payment methods details.
	 */
	public function get_onboarding_recommended_payment_methods( string $location ): array {
		return $this->provider->get_recommended_payment_methods( $this->get_payment_gateway(), $location );
	}

	/**
	 * Initialize the test account for onboarding.
	 *
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 * @param string $source   Optional. The source for the current onboarding flow.
	 *                         If not provided, it will identify the source as the WC Admin Payments settings.
	 *
	 * @return array The result of the test account initialization.
	 * @throws ApiArgumentException|ApiException If the given onboarding step ID or step data is invalid.
	 *                                           If the onboarding action can not be performed due to the current state
	 *                                           of the site or there was an error initializing the test account.
	 */
	public function onboarding_test_account_init( string $location, string $source = '' ): array {
		$this->check_if_onboarding_step_action_is_acceptable( self::ONBOARDING_STEP_TEST_ACCOUNT, $location );

		// Nothing to do if we already have a connected test account.
		if ( $this->has_test_account() ) {
			throw new ApiException(
				'woocommerce_woopayments_onboarding_action_error',
				esc_html__( 'A test account is already set up.', 'woocommerce' ),
				(int) WP_Http::FORBIDDEN
			);
		}

		// Nothing to do if there is a connected account, but it is not a test account.
		if ( $this->has_account() ) {
			// Mark the onboarding step as blocked, if it is not already.
			$this->mark_onboarding_step_blocked(
				self::ONBOARDING_STEP_TEST_ACCOUNT,
				$location,
				array(
					'code'    => 'account_already_exists',
					'message' => esc_html__( 'An account is already set up. Reset the onboarding first.', 'woocommerce' ),
				)
			);

			throw new ApiException(
				'woocommerce_woopayments_onboarding_action_error',
				esc_html__( 'An account is already set up. Reset the onboarding first.', 'woocommerce' ),
				(int) WP_Http::FORBIDDEN
			);
		}

		// Clear any previous failed status for the step.
		$this->clear_onboarding_step_failed( self::ONBOARDING_STEP_TEST_ACCOUNT, $location );

		$selected_payment_methods = $this->get_nox_profile_onboarding_step_data_entry( self::ONBOARDING_STEP_PAYMENT_METHODS, $location, 'payment_methods', array() );

		// Ensure the payment gateways logic is initialized in case actions need to be taken on payment gateway changes.
		WC()->payment_gateways();

		// Lock the onboarding to prevent concurrent actions.
		$this->set_onboarding_lock();

		if ( empty( $source ) ) {
			// The default source is the WC Admin Payments settings.
			$source = self::FROM_PAYMENT_SETTINGS;
		}

		try {
			// Call the WooPayments API to initialize the test account.
			$response = $this->proxy->call_static(
				Utils::class,
				'rest_endpoint_post_request',
				'/wc/v3/payments/onboarding/test_drive_account/init',
				array(
					'country'      => $location,
					'capabilities' => $selected_payment_methods,
					'source'       => $source,
					'from'         => self::FROM_NOX_IN_CONTEXT,
				)
			);
		} catch ( Exception $e ) {
			// Catch any exceptions to allow for proper error handling and onboarding unlock.
			$response = new WP_Error(
				'woocommerce_woopayments_onboarding_client_api_exception',
				esc_html__( 'An unexpected error happened while initializing the test account.', 'woocommerce' ),
				array(
					'code'    => $e->getCode(),
					'message' => $e->getMessage(),
					'trace'   => $e->getTrace(),
				)
			);
		}

		// Unlock the onboarding after the API call finished or errored.
		$this->clear_onboarding_lock();

		if ( is_wp_error( $response ) ) {
			// Mark the onboarding step as failed.
			$this->mark_onboarding_step_failed(
				self::ONBOARDING_STEP_TEST_ACCOUNT,
				$location,
				array(
					'code'    => $response->get_error_code(),
					'message' => $response->get_error_message(),
					'context' => $response->get_error_data(),
				)
			);

			throw new ApiException(
				'woocommerce_woopayments_onboarding_client_api_error',
				esc_html( $response->get_error_message() ),
				(int) WP_Http::FAILED_DEPENDENCY,
				map_deep( (array) $response->get_error_data(), 'esc_html' )
			);
		}

		if ( ! is_array( $response ) || empty( $response['success'] ) ) {
			// Mark the onboarding step as failed.
			$this->mark_onboarding_step_failed(
				self::ONBOARDING_STEP_TEST_ACCOUNT,
				$location,
				array(
					'code'    => 'malformed_response',
					'message' => esc_html__( 'Received an unexpected response from the platform.', 'woocommerce' ),
					'context' => array(
						'response' => $response,
					),
				)
			);

			throw new ApiException(
				'woocommerce_woopayments_onboarding_client_api_error',
				esc_html__( 'Failed to initialize the test account.', 'woocommerce' ),
				(int) WP_Http::FAILED_DEPENDENCY
			);
		}

		// Record an event for the test account being initialized.
		$this->record_event(
			self::EVENT_PREFIX . 'onboarding_test_account_init',
			$location,
			array(
				'source' => $source,
			)
		);

		return $response;
	}

	/**
	 * Get the onboarding KYC account session.
	 *
	 * @param string $location        The location for which we are onboarding.
	 *                                This is a ISO 3166-1 alpha-2 country code.
	 * @param array  $self_assessment Optional. The self-assessment data.
	 *                                If not provided, the stored data will be used.
	 * @param string $source          Optional. The source for the current onboarding flow.
	 *                                If not provided, it will identify the source as the WC Admin Payments settings.
	 *
	 * @return array The KYC account session data.
	 * @throws ApiException If the extension is not active, step requirements are not met, or
	 *                      the KYC session data could not be retrieved.
	 */
	public function get_onboarding_kyc_session( string $location, array $self_assessment = array(), string $source = '' ): array {
		$this->check_if_onboarding_step_action_is_acceptable( self::ONBOARDING_STEP_BUSINESS_VERIFICATION, $location );

		if ( empty( $self_assessment ) ) {
			// Get the stored self-assessment data.
			$self_assessment = (array) $this->get_nox_profile_onboarding_step_data_entry( self::ONBOARDING_STEP_BUSINESS_VERIFICATION, $location, 'self_assessment' );
		}

		// Clear any previous failed status for the step.
		$this->clear_onboarding_step_failed( self::ONBOARDING_STEP_BUSINESS_VERIFICATION, $location );

		// Ensure the payment gateways logic is initialized in case actions need to be taken on payment gateway changes.
		WC()->payment_gateways();

		// Lock the onboarding to prevent concurrent actions.
		$this->set_onboarding_lock();

		if ( empty( $source ) ) {
			// The default source is the WC Admin Payments settings.
			$source = self::FROM_PAYMENT_SETTINGS;
		}

		try {
			// Call the WooPayments API to get the KYC session.
			$response = $this->proxy->call_static(
				Utils::class,
				'rest_endpoint_post_request',
				'/wc/v3/payments/onboarding/kyc/session',
				array(
					'self_assessment' => $self_assessment,
				)
			);
		} catch ( Exception $e ) {
			// Catch any exceptions to allow for proper error handling and onboarding unlock.
			$response = new WP_Error(
				'woocommerce_woopayments_onboarding_client_api_exception',
				esc_html__( 'An unexpected error happened while creating the KYC session.', 'woocommerce' ),
				array(
					'code'    => $e->getCode(),
					'message' => $e->getMessage(),
					'trace'   => $e->getTrace(),
				)
			);
		}

		// Unlock the onboarding after the API call finished or errored.
		$this->clear_onboarding_lock();

		if ( is_wp_error( $response ) ) {
			// Mark the onboarding step as failed.
			$this->mark_onboarding_step_failed(
				self::ONBOARDING_STEP_BUSINESS_VERIFICATION,
				$location,
				array(
					'code'    => $response->get_error_code(),
					'message' => $response->get_error_message(),
					'context' => $response->get_error_data(),
				)
			);

			throw new ApiException(
				'woocommerce_woopayments_onboarding_client_api_error',
				esc_html( $response->get_error_message() ),
				(int) WP_Http::FAILED_DEPENDENCY,
				map_deep( (array) $response->get_error_data(), 'esc_html' )
			);
		}

		if ( ! is_array( $response ) ) {
			// Mark the onboarding step as failed.
			$this->mark_onboarding_step_failed(
				self::ONBOARDING_STEP_BUSINESS_VERIFICATION,
				$location,
				array(
					'code'    => 'malformed_response',
					'message' => esc_html__( 'Received an unexpected response from the platform.', 'woocommerce' ),
					'context' => array(
						'response' => $response,
					),
				)
			);

			throw new ApiException(
				'woocommerce_woopayments_onboarding_client_api_error',
				esc_html__( 'Failed to get the KYC session data.', 'woocommerce' ),
				(int) WP_Http::FAILED_DEPENDENCY
			);
		}

		// Add the user locale to the account session data to allow for localized KYC sessions.
		$response['locale'] = $this->proxy->call_function( 'get_user_locale' );

		// For sanity, make sure the test account step is blocked if not already completed,
		// since we are doing live account KYC.
		if ( ! $this->is_onboarding_step_completed( self::ONBOARDING_STEP_TEST_ACCOUNT, $location ) ) {
			$this->mark_onboarding_step_blocked(
				self::ONBOARDING_STEP_TEST_ACCOUNT,
				$location,
				array(
					'code'    => 'live_account_kyc_session',
					'message' => esc_html__( 'A live account is set up. Reset the onboarding first.', 'woocommerce' ),
				)
			);
		}

		// Record an event for the KYC session being created.
		$this->record_event(
			self::EVENT_PREFIX . 'onboarding_kyc_session_created',
			$location,
			array(
				'source' => $source,
			)
		);

		return $response;
	}

	/**
	 * Finish the onboarding KYC account session.
	 *
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 * @param string $source   Optional. The source for the current onboarding flow.
	 *                         If not provided, it will identify the source as the WC Admin Payments settings.
	 *
	 * @return array The response from the WooPayments API.
	 * @throws ApiException If the extension is not active, step requirements are not met, or
	 *                      the KYC session could not be finished.
	 */
	public function finish_onboarding_kyc_session( string $location, string $source = '' ): array {
		$this->check_if_onboarding_step_action_is_acceptable( self::ONBOARDING_STEP_BUSINESS_VERIFICATION, $location );

		// Ensure the payment gateways logic is initialized in case actions need to be taken on payment gateway changes.
		WC()->payment_gateways();

		// Lock the onboarding to prevent concurrent actions.
		$this->set_onboarding_lock();

		if ( empty( $source ) ) {
			// The default source is the WC Admin Payments settings.
			$source = self::FROM_PAYMENT_SETTINGS;
		}

		try {
			// Call the WooPayments API to finalize the KYC session.
			$response = $this->proxy->call_static(
				Utils::class,
				'rest_endpoint_post_request',
				'/wc/v3/payments/onboarding/kyc/finalize',
				array(
					'source' => $source,
					'from'   => self::FROM_NOX_IN_CONTEXT,
				)
			);
		} catch ( Exception $e ) {
			// Catch any exceptions to allow for proper error handling and onboarding unlock.
			$response = new WP_Error(
				'woocommerce_woopayments_onboarding_client_api_exception',
				esc_html__( 'An unexpected error happened while finalizing the KYC session.', 'woocommerce' ),
				array(
					'code'    => $e->getCode(),
					'message' => $e->getMessage(),
					'trace'   => $e->getTrace(),
				)
			);
		}

		// Unlock the onboarding after the API call finished or errored.
		$this->clear_onboarding_lock();

		if ( is_wp_error( $response ) ) {
			// Mark the onboarding step as failed.
			$this->mark_onboarding_step_failed(
				self::ONBOARDING_STEP_BUSINESS_VERIFICATION,
				$location,
				array(
					'code'    => $response->get_error_code(),
					'message' => $response->get_error_message(),
					'context' => $response->get_error_data(),
				)
			);

			throw new ApiException(
				'woocommerce_woopayments_onboarding_client_api_error',
				esc_html( $response->get_error_message() ),
				(int) WP_Http::FAILED_DEPENDENCY,
				map_deep( (array) $response->get_error_data(), 'esc_html' )
			);
		}

		if ( ! is_array( $response ) ) {
			// Mark the onboarding step as failed.
			$this->mark_onboarding_step_failed(
				self::ONBOARDING_STEP_BUSINESS_VERIFICATION,
				$location,
				array(
					'code'    => 'malformed_response',
					'message' => esc_html__( 'Received an unexpected response from the platform.', 'woocommerce' ),
					'context' => array(
						'response' => $response,
					),
				)
			);

			throw new ApiException(
				'woocommerce_woopayments_onboarding_client_api_error',
				esc_html__( 'Failed to finish the KYC session.', 'woocommerce' ),
				(int) WP_Http::FAILED_DEPENDENCY
			);
		}

		// Record an event for the KYC session being finished.
		$this->record_event(
			self::EVENT_PREFIX . 'onboarding_kyc_session_finished',
			$location,
			array(
				'source' => $source,
			)
		);

		// Mark the business verification step as completed.
		$this->mark_onboarding_step_completed( self::ONBOARDING_STEP_BUSINESS_VERIFICATION, $location );

		// For sanity, make sure the test account step is blocked if not already completed,
		// since we are doing live account KYC.
		if ( ! $this->is_onboarding_step_completed( self::ONBOARDING_STEP_TEST_ACCOUNT, $location ) ) {
			$this->mark_onboarding_step_blocked(
				self::ONBOARDING_STEP_TEST_ACCOUNT,
				$location,
				array(
					'code'    => 'live_account_kyc_session',
					'message' => esc_html__( 'A live account is set up. Reset the onboarding first.', 'woocommerce' ),
				)
			);
		}

		return $response;
	}

	/**
	 * Preload the onboarding process.
	 *
	 * This method is used to run the heavier logic required for onboarding ahead of time,
	 * so that we can be quicker to respond to the user when they start the onboarding process.
	 *
	 * @return array An array containing the success status and any errors encountered during the preload.
	 *               'success' => true if the preload was successful, false otherwise.
	 *               'errors'  => An array of error messages if any errors occurred, empty if no errors.
	 * @throws ApiException If the onboarding preload failed or the onboarding is locked.
	 */
	public function onboarding_preload(): array {
		// If the onboarding is locked, we shouldn't do anything.
		if ( $this->is_onboarding_locked() ) {
			throw new ApiException(
				'woocommerce_woopayments_onboarding_locked',
				esc_html__( 'Another onboarding action is already in progress. Please wait for it to finish.', 'woocommerce' ),
				(int) WP_Http::CONFLICT
			);
		}

		$result = true;

		// Register the site to WPCOM if it is not already registered.
		// This sets up the site for connection. For new sites, this tends to take a while.
		// It is a prerequisite to generating the WPCOM/Jetpack authorization URL.
		if ( ! $this->wpcom_connection_manager->is_connected() ) {
			$result = $this->wpcom_connection_manager->try_registration();
			if ( is_wp_error( $result ) ) {
				throw new ApiException(
					'woocommerce_woopayments_onboarding_action_error',
					esc_html( $result->get_error_message() ),
					(int) WP_Http::INTERNAL_SERVER_ERROR,
					map_deep( (array) $result->get_error_data(), 'esc_html' )
				);
			}
		}

		return array(
			'success' => $result,
		);
	}

	/**
	 * Reset onboarding.
	 *
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 * @param string $from     Optional. Where in the UI the request is coming from.
	 *                         If not provided, it will identify the origin as the WC Admin Payments settings.
	 * @param string $source   Optional. The source for the current onboarding flow.
	 *                         If not provided, it will identify the source as the WC Admin Payments settings.
	 *
	 * @return array The response from the WooPayments API.
	 * @throws ApiException If we could not reset onboarding or there was an error.
	 */
	public function reset_onboarding( string $location, string $from = '', string $source = '' ): array {
		$this->check_if_onboarding_action_is_acceptable();

		// Ensure the payment gateways logic is initialized in case actions need to be taken on payment gateway changes.
		WC()->payment_gateways();

		// Lock the onboarding to prevent concurrent actions.
		$this->set_onboarding_lock();

		// If no source is provided, default to the WC Admin Payments settings.
		if ( empty( $source ) ) {
			$source = self::FROM_PAYMENT_SETTINGS;
		}

		try {
			// Call the WooPayments API to reset onboarding.
			$response = $this->proxy->call_static(
				Utils::class,
				'rest_endpoint_post_request',
				'/wc/v3/payments/onboarding/reset',
				array(
					'from'   => ! empty( $from ) ? esc_attr( $from ) : self::FROM_PAYMENT_SETTINGS,
					'source' => $source,
				)
			);
		} catch ( Exception $e ) {
			// Catch any exceptions to allow for proper error handling and onboarding unlock.
			$response = new WP_Error(
				'woocommerce_woopayments_onboarding_client_api_exception',
				esc_html__( 'An unexpected error happened while resetting onboarding.', 'woocommerce' ),
				array(
					'code'    => $e->getCode(),
					'message' => $e->getMessage(),
					'trace'   => $e->getTrace(),
				)
			);
		}

		// Unlock the onboarding after the API call finished or errored.
		$this->clear_onboarding_lock();

		if ( is_wp_error( $response ) ) {
			throw new ApiException(
				'woocommerce_woopayments_onboarding_client_api_error',
				esc_html( $response->get_error_message() ),
				(int) WP_Http::FAILED_DEPENDENCY,
				map_deep( (array) $response->get_error_data(), 'esc_html' )
			);
		}

		if ( ! is_array( $response ) || empty( $response['success'] ) ) {
			throw new ApiException(
				'woocommerce_woopayments_onboarding_client_api_error',
				esc_html__( 'Failed to reset onboarding.', 'woocommerce' ),
				(int) WP_Http::FAILED_DEPENDENCY
			);
		}

		// Clean up any NOX-specific onboarding data.
		$this->proxy->call_function( 'delete_option', self::NOX_PROFILE_OPTION_KEY );

		// Record an event for the onboarding reset.
		$this->record_event(
			self::EVENT_PREFIX . 'onboarding_reset',
			$location,
			array(
				'source' => $source,
			)
		);

		return $response;
	}

	/**
	 * Disable test account during the switch-to-live onboarding flow.
	 *
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 * @param string $from     Optional. Where in the UI the request is coming from.
	 *                         If not provided, it will identify the origin as the WC Admin Payments settings.
	 * @param string $source   Optional. The source for the current onboarding flow.
	 *                         If not provided, it will identify the source as the WC Admin Payments settings.
	 *
	 * @return array The response from the WooPayments API.
	 * @throws ApiException If we could not disable the test account or there was an error.
	 */
	public function disable_test_account( string $location, string $from = '', string $source = '' ): array {
		$this->check_if_onboarding_action_is_acceptable();

		// Ensure the payment gateways logic is initialized in case actions need to be taken on payment gateway changes.
		WC()->payment_gateways();

		// Lock the onboarding to prevent concurrent actions.
		$this->set_onboarding_lock();

		// If no source is provided, default to the WC Admin Payments settings.
		if ( empty( $source ) ) {
			$source = self::FROM_PAYMENT_SETTINGS;
		}

		try {
			// Call the WooPayments API to disable the test account and prepare for the switch to live.
			$response = $this->proxy->call_static(
				Utils::class,
				'rest_endpoint_post_request',
				'/wc/v3/payments/onboarding/test_drive_account/disable',
				array(
					'from'   => ! empty( $from ) ? esc_attr( $from ) : self::FROM_PAYMENT_SETTINGS,
					'source' => $source,
				)
			);
		} catch ( Exception $e ) {
			// Catch any exceptions to allow for proper error handling and onboarding unlock.
			$response = new WP_Error(
				'woocommerce_woopayments_onboarding_client_api_exception',
				esc_html__( 'An unexpected error happened while disabling the test account.', 'woocommerce' ),
				array(
					'code'    => $e->getCode(),
					'message' => $e->getMessage(),
					'trace'   => $e->getTrace(),
				)
			);
		}

		// Unlock the onboarding after the API call finished or errored.
		$this->clear_onboarding_lock();

		if ( is_wp_error( $response ) ) {
			throw new ApiException(
				'woocommerce_woopayments_onboarding_client_api_error',
				esc_html( $response->get_error_message() ),
				(int) WP_Http::FAILED_DEPENDENCY,
				map_deep( (array) $response->get_error_data(), 'esc_html' )
			);
		}

		if ( ! is_array( $response ) || empty( $response['success'] ) ) {
			throw new ApiException(
				'woocommerce_woopayments_onboarding_client_api_error',
				esc_html__( 'Failed to disable the test account.', 'woocommerce' ),
				(int) WP_Http::FAILED_DEPENDENCY
			);
		}

		// For sanity, make sure the payment methods step is marked as completed.
		// This is to avoid the user being prompted to set up payment methods again.
		$this->mark_onboarding_step_completed( self::ONBOARDING_STEP_PAYMENT_METHODS, $location );
		// For sanity, make sure the test account step is marked as completed and not blocked or failed.
		// After disabling a test account, the user should be prompted to set up a live account.
		$this->mark_onboarding_step_completed( self::ONBOARDING_STEP_TEST_ACCOUNT, $location );
		$this->clear_onboarding_step_blocked( self::ONBOARDING_STEP_TEST_ACCOUNT, $location );
		$this->clear_onboarding_step_failed( self::ONBOARDING_STEP_TEST_ACCOUNT, $location );

		// Record an event for the test account being disabled.
		$this->record_event(
			self::EVENT_PREFIX . 'onboarding_test_account_disabled',
			$location,
			array(
				'source' => $source,
			)
		);

		return $response;
	}

	/**
	 * Check if an onboarding action should be allowed to be processed.
	 *
	 * @return void
	 * @throws ApiException If the extension is not active or onboarding is locked.
	 */
	private function check_if_onboarding_action_is_acceptable() {
		// If the WooPayments plugin is not active, we can't do anything.
		if ( ! $this->is_extension_active() ) {
			throw new ApiException(
				'woocommerce_woopayments_onboarding_extension_not_active',
				/* translators: %s: WooPayments. */
				sprintf( esc_html__( 'The %s extension is not active.', 'woocommerce' ), 'WooPayments' ),
				(int) WP_Http::FORBIDDEN
			);
		}

		// If the WooPayments installed version is less than the minimum required version, we can't do anything.
		if ( Constants::is_defined( 'WCPAY_VERSION_NUMBER' ) &&
			version_compare( Constants::get_constant( 'WCPAY_VERSION_NUMBER' ), self::EXTENSION_MINIMUM_VERSION, '<' ) ) {
			throw new ApiException(
				'woocommerce_woopayments_onboarding_extension_version',
				/* translators: %s: WooPayments. */
				sprintf( esc_html__( 'The %s extension is not up-to-date. Please update to the latest version and try again.', 'woocommerce' ), 'WooPayments' ),
				(int) WP_Http::FORBIDDEN
			);
		}

		// If the onboarding is locked, we shouldn't do anything.
		if ( $this->is_onboarding_locked() ) {
			throw new ApiException(
				'woocommerce_woopayments_onboarding_locked',
				esc_html__( 'Another onboarding action is already in progress. Please wait for it to finish.', 'woocommerce' ),
				(int) WP_Http::CONFLICT
			);
		}
	}

	/**
	 * Check if an onboarding step action should be allowed to be processed.
	 *
	 * @param string $step_id The ID of the onboarding step.
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 *
	 * @return void
	 * @throws ApiArgumentException If the onboarding step ID is invalid.
	 * @throws ApiException If the extension is not active or step requirements are not met.
	 */
	private function check_if_onboarding_step_action_is_acceptable( string $step_id, string $location ): void {
		// First, check general onboarding actions.
		$this->check_if_onboarding_action_is_acceptable();

		// Second, do onboarding step specific checks.
		if ( ! $this->is_valid_onboarding_step_id( $step_id ) ) {
			throw new ApiArgumentException(
				'woocommerce_woopayments_onboarding_invalid_step_id',
				esc_html__( 'Invalid onboarding step ID.', 'woocommerce' ),
				(int) WP_Http::BAD_REQUEST
			);
		}
		if ( ! $this->check_onboarding_step_requirements( $step_id, $location ) ) {
			throw new ApiException(
				'woocommerce_woopayments_onboarding_step_requirements_not_met',
				esc_html__( 'Onboarding step requirements are not met.', 'woocommerce' ),
				(int) WP_Http::FORBIDDEN
			);
		}
		if ( $this->is_onboarding_step_blocked( $step_id, $location ) ) {
			throw new ApiException(
				'woocommerce_woopayments_onboarding_step_blocked',
				esc_html__( 'There are environment or store setup issues which are blocking progress. Please resolve them to proceed.', 'woocommerce' ),
				(int) WP_Http::FORBIDDEN,
				array(
					'error' => map_deep( $this->get_onboarding_step_error( $step_id, $location ), 'esc_html' ),
				),
			);
		}
	}

	/**
	 * Check if the onboarding is locked.
	 *
	 * @return bool Whether the onboarding is locked.
	 */
	private function is_onboarding_locked(): bool {
		return 'yes' === $this->proxy->call_function( 'get_option', self::NOX_ONBOARDING_LOCKED_KEY, 'no' );
	}

	/**
	 * Lock the onboarding.
	 *
	 * This will save a flag in the database to indicate that onboarding is locked.
	 * This is used to prevent certain onboarding actions to happen while others have not finished.
	 * This is especially important for actions that modify the account (initializing it, deleting it, etc.)
	 * These actions tend to be longer-running and we want to have backstops in place to prevent race conditions.
	 *
	 * @return void
	 */
	private function set_onboarding_lock(): void {
		$this->proxy->call_function( 'update_option', self::NOX_ONBOARDING_LOCKED_KEY, 'yes' );
	}

	/**
	 * Unlock the onboarding.
	 *
	 * @return void
	 */
	private function clear_onboarding_lock(): void {
		// We update rather than delete the option for performance reasons.
		$this->proxy->call_function( 'update_option', self::NOX_ONBOARDING_LOCKED_KEY, 'no' );
	}

	/**
	 * Get the onboarding details for each step.
	 *
	 * @param string $location  The location for which we are onboarding.
	 *                          This is a ISO 3166-1 alpha-2 country code.
	 * @param string $rest_path The REST API path to use for constructing REST API URLs.
	 *
	 * @return array[] The list of onboarding steps details.
	 * @throws Exception If there was an error generating the onboarding steps details.
	 */
	private function get_onboarding_steps( string $location, string $rest_path ): array {
		$steps = array();

		// Add the payment methods onboarding step details.
		$steps[] = $this->standardize_onboarding_step_details(
			array(
				'id'      => self::ONBOARDING_STEP_PAYMENT_METHODS,
				'context' => array(
					'recommended_pms' => $this->get_onboarding_recommended_payment_methods( $location ),
					'pms_state'       => $this->get_onboarding_payment_methods_state( $location ),
				),
				'actions' => array(
					'start'  => array(
						'type' => self::ACTION_TYPE_REST,
						'href' => rest_url( trailingslashit( $rest_path ) . self::ONBOARDING_STEP_PAYMENT_METHODS . '/start' ),
					),
					'save'   => array(
						'type' => self::ACTION_TYPE_REST,
						'href' => rest_url( trailingslashit( $rest_path ) . self::ONBOARDING_STEP_PAYMENT_METHODS . '/save' ),
					),
					'finish' => array(
						'type' => self::ACTION_TYPE_REST,
						'href' => rest_url( trailingslashit( $rest_path ) . self::ONBOARDING_STEP_PAYMENT_METHODS . '/finish' ),
					),
				),
			),
			$location,
			$rest_path
		);

		// Add the WPCOM connection onboarding step details.
		$wpcom_step = $this->standardize_onboarding_step_details(
			array(
				'id'      => self::ONBOARDING_STEP_WPCOM_CONNECTION,
				'context' => array(
					'connection_state' => $this->get_wpcom_connection_state(),
				),
			),
			$location,
			$rest_path
		);

		// If the WPCOM connection is already set up, we don't need to add anything more.
		if ( self::ONBOARDING_STEP_STATUS_COMPLETED !== $wpcom_step['status'] ) {
			// Craft the return URL.
			// By default, we return the user to the onboarding modal.
			$return_url = $this->proxy->call_static(
				Utils::class,
				'wc_payments_settings_url',
				self::ONBOARDING_PATH_BASE,
				array(
					'wpcom_connection_return' => '1', // URL query flag so we can properly identify when the user returns.
				)
			);
			// Try to generate the authorization URL.
			$wpcom_connection = $this->get_wpcom_connection_authorization( $return_url );
			if ( ! $wpcom_connection['success'] ) {
				$wpcom_step['errors'] = array_values( $wpcom_connection['errors'] );
			}
			$wpcom_step['actions'] = array(
				'start' => array(
					'type' => self::ACTION_TYPE_REST,
					'href' => rest_url( trailingslashit( $rest_path ) . self::ONBOARDING_STEP_WPCOM_CONNECTION . '/start' ),
				),
				'auth'  => array(
					'type' => self::ACTION_TYPE_REDIRECT,
					'href' => $wpcom_connection['url'],
				),
			);
		}

		$steps[] = $wpcom_step;

		// Test account onboarding step is unavailable in UAE and Singapore.
		if ( ! in_array( $location, array( 'AE', 'SG' ), true ) ) {
			$test_account_step = $this->standardize_onboarding_step_details(
				array(
					'id' => self::ONBOARDING_STEP_TEST_ACCOUNT,
				),
				$location,
				$rest_path
			);

			// If the step is not completed, we need to add the actions.
			if ( self::ONBOARDING_STEP_STATUS_COMPLETED !== $test_account_step['status'] ) {
				$test_account_step['actions'] = array(
					'start'  => array(
						'type' => self::ACTION_TYPE_REST,
						'href' => rest_url( trailingslashit( $rest_path ) . self::ONBOARDING_STEP_TEST_ACCOUNT . '/start' ),
					),
					'init'   => array(
						'type' => self::ACTION_TYPE_REST,
						'href' => rest_url( trailingslashit( $rest_path ) . self::ONBOARDING_STEP_TEST_ACCOUNT . '/init' ),
					),
					'finish' => array(
						'type' => self::ACTION_TYPE_REST,
						'href' => rest_url( trailingslashit( $rest_path ) . self::ONBOARDING_STEP_TEST_ACCOUNT . '/finish' ),
					),
				);
			}

			$steps[] = $test_account_step;
		}

		// Add the live account business verification onboarding step details.
		$business_verification_step = $this->standardize_onboarding_step_details(
			array(
				'id'      => self::ONBOARDING_STEP_BUSINESS_VERIFICATION,
				'context' => array(
					'fields'           => array(),
					'sub_steps'        => $this->get_nox_profile_onboarding_step_data_entry( self::ONBOARDING_STEP_BUSINESS_VERIFICATION, $location, 'sub_steps', array() ),
					'self_assessment'  => $this->get_nox_profile_onboarding_step_data_entry( self::ONBOARDING_STEP_BUSINESS_VERIFICATION, $location, 'self_assessment', array() ),
					'has_test_account' => $this->has_test_account(),
				),
			),
			$location,
			$rest_path
		);

		// Try to get the pre-KYC fields, but only if the required step is completed.
		// This is because WooPayments needs a working WPCOM connection to be able to fetch the fields.
		if ( $this->check_onboarding_step_requirements( self::ONBOARDING_STEP_BUSINESS_VERIFICATION, $location ) ) {
			try {
				$business_verification_step['context']['fields'] = $this->get_onboarding_kyc_fields( $location );
			} catch ( Exception $e ) {
				$business_verification_step['errors'][] = array(
					'code'    => 'fields_error',
					'message' => $e->getMessage(),
				);
			}
		}

		// If the step is not completed, we need to add the actions.
		if ( self::ONBOARDING_STEP_STATUS_COMPLETED !== $business_verification_step['status'] ) {
			$business_verification_step['actions'] = array(
				'start'              => array(
					'type' => self::ACTION_TYPE_REST,
					'href' => rest_url( trailingslashit( $rest_path ) . self::ONBOARDING_STEP_BUSINESS_VERIFICATION . '/start' ),
				),
				'save'               => array(
					'type' => self::ACTION_TYPE_REST,
					'href' => rest_url( trailingslashit( $rest_path ) . self::ONBOARDING_STEP_BUSINESS_VERIFICATION . '/save' ),
				),
				'kyc_session'        => array(
					'type' => self::ACTION_TYPE_REST,
					'href' => rest_url( trailingslashit( $rest_path ) . self::ONBOARDING_STEP_BUSINESS_VERIFICATION . '/kyc_session' ),
				),
				'kyc_session_finish' => array(
					'type' => self::ACTION_TYPE_REST,
					'href' => rest_url( trailingslashit( $rest_path ) . self::ONBOARDING_STEP_BUSINESS_VERIFICATION . '/kyc_session/finish' ),
				),
				'kyc_fallback'       => array(
					'type' => self::ACTION_TYPE_REDIRECT,
					'href' => $this->get_onboarding_kyc_fallback_url(),
				),
				'finish'             => array(
					'type' => self::ACTION_TYPE_REST,
					'href' => rest_url( trailingslashit( $rest_path ) . self::ONBOARDING_STEP_BUSINESS_VERIFICATION . '/finish' ),
				),
			);
		}

		$steps[] = $business_verification_step;

		// Do a complete list standardization, for safety.
		return $this->standardize_onboarding_steps_details( $steps, $location, $rest_path );
	}

	/**
	 * Standardize (and sanity check) the onboarding step details.
	 *
	 * @param array  $step_details The onboarding step details to standardize.
	 * @param string $location     The location for which we are onboarding.
	 *                             This is a ISO 3166-1 alpha-2 country code.
	 * @param string $rest_path    The REST API path to use for constructing REST API URLs.
	 *
	 * @return array The standardized onboarding step details.
	 * @throws Exception If the onboarding step details are missing required entries or if the step ID is invalid.
	 */
	private function standardize_onboarding_step_details( array $step_details, string $location, string $rest_path ): array {
		// If the required keys are not present, throw.
		if ( ! isset( $step_details['id'] ) ) {
			/* translators: %s: The required key that is missing. */
			throw new Exception( sprintf( esc_html__( 'The onboarding step is missing required entries: %s', 'woocommerce' ), 'id' ) );
		}
		// Validate the step ID.
		if ( ! $this->is_valid_onboarding_step_id( $step_details['id'] ) ) {
			/* translators: %s: The invalid step ID. */
			throw new Exception( sprintf( esc_html__( 'The onboarding step ID is invalid: %s', 'woocommerce' ), esc_attr( $step_details['id'] ) ) );
		}

		if ( empty( $step_details['status'] ) ) {
			$step_details['status'] = $this->get_onboarding_step_status( $step_details['id'], $location );
		}

		if ( empty( $step_details['errors'] ) ) {
			$step_details['errors'] = array();

			// For blocked or failed steps, we include any stored error.
			if ( in_array( $step_details['status'], array( self::ONBOARDING_STEP_STATUS_BLOCKED, self::ONBOARDING_STEP_STATUS_FAILED ), true ) ) {
				$stored_error = $this->get_onboarding_step_error( $step_details['id'], $location );
				if ( ! empty( $stored_error ) ) {
					$step_details['errors'] = array( $stored_error );
				}
			}
		}

		// Ensure that any step has the general actions.
		if ( empty( $step_details['actions'] ) ) {
			$step_details['actions'] = array();
		}
		// Any step can be checked for its status.
		if ( empty( $step_details['actions']['check'] ) ) {
			$step_details['actions']['check'] = array(
				'type' => self::ACTION_TYPE_REST,
				'href' => rest_url( trailingslashit( $rest_path ) . $step_details['id'] . '/check' ),
			);
		}
		// Any step can be cleaned of its progress.
		if ( empty( $step_details['actions']['clean'] ) ) {
			$step_details['actions']['clean'] = array(
				'type' => self::ACTION_TYPE_REST,
				'href' => rest_url( trailingslashit( $rest_path ) . $step_details['id'] . '/clean' ),
			);
		}

		return array(
			'id'             => $step_details['id'],
			'path'           => $step_details['path'] ?? trailingslashit( self::ONBOARDING_PATH_BASE ) . $step_details['id'],
			'required_steps' => $step_details['required_steps'] ?? $this->get_onboarding_step_required_steps( $step_details['id'] ),
			'status'         => $step_details['status'],
			'errors'         => $step_details['errors'],
			'actions'        => $step_details['actions'],
			'context'        => $step_details['context'] ?? array(),
		);
	}

	/**
	 * Standardize (and sanity check) the onboarding steps list.
	 *
	 * @param array  $steps The onboarding steps list to standardize.
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 * @param string $rest_path The REST API path to use for constructing REST API URLs.
	 *
	 * @return array The standardized onboarding steps list.
	 * @throws Exception If some onboarding steps are missing required entries or if invalid step IDs are present.
	 */
	private function standardize_onboarding_steps_details( array $steps, string $location, string $rest_path ): array {
		$standardized_steps = array();
		foreach ( $steps as $step ) {
			$standardized_steps[] = $this->standardize_onboarding_step_details( $step, $location, $rest_path );
		}

		return $standardized_steps;
	}

	/**
	 * Get the entire stored NOX profile data
	 *
	 * @return array The stored NOX profile.
	 */
	private function get_nox_profile(): array {
		$nox_profile = $this->proxy->call_function( 'get_option', self::NOX_PROFILE_OPTION_KEY, array() );

		if ( empty( $nox_profile ) ) {
			$nox_profile = array();
		} else {
			$nox_profile = maybe_unserialize( $nox_profile );
		}

		return $nox_profile;
	}

	/**
	 * Get the onboarding step data from the NOX profile.
	 *
	 * @param string $step_id  The ID of the onboarding step.
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 *
	 * @return array The onboarding step stored data from the NOX profile.
	 *               If the step data is not found, an empty array is returned.
	 */
	private function get_nox_profile_onboarding_step( string $step_id, string $location ): array {
		$nox_profile = $this->get_nox_profile();

		if ( empty( $nox_profile['onboarding'] ) ) {
			$nox_profile['onboarding'] = array();
		}
		if ( empty( $nox_profile['onboarding'][ $location ] ) ) {
			$nox_profile['onboarding'][ $location ] = array();
		}
		if ( empty( $nox_profile['onboarding'][ $location ]['steps'] ) ) {
			$nox_profile['onboarding'][ $location ]['steps'] = array();
		}
		if ( empty( $nox_profile['onboarding'][ $location ]['steps'][ $step_id ] ) ) {
			$nox_profile['onboarding'][ $location ]['steps'][ $step_id ] = array();
		}

		return $nox_profile['onboarding'][ $location ]['steps'][ $step_id ];
	}

	/**
	 * Save the onboarding step data in the NOX profile.
	 *
	 * @param string $step_id  The ID of the onboarding step.
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 * @param array  $data     The onboarding step data to save in the profile.
	 *
	 * @return bool Whether the onboarding step data was saved.
	 */
	private function save_nox_profile_onboarding_step( string $step_id, string $location, array $data ): bool {
		$nox_profile = $this->get_nox_profile();

		if ( empty( $nox_profile['onboarding'] ) ) {
			$nox_profile['onboarding'] = array();
		}
		if ( empty( $nox_profile['onboarding'][ $location ] ) ) {
			$nox_profile['onboarding'][ $location ] = array();
		}
		if ( empty( $nox_profile['onboarding'][ $location ]['steps'] ) ) {
			$nox_profile['onboarding'][ $location ]['steps'] = array();
		}

		// Update the stored step data.
		$nox_profile['onboarding'][ $location ]['steps'][ $step_id ] = $data;

		return $this->proxy->call_function( 'update_option', self::NOX_PROFILE_OPTION_KEY, $nox_profile, false );
	}

	/**
	 * Get an entry from the NOX profile onboarding step details.
	 *
	 * @param string $step_id       The ID of the onboarding step.
	 * @param string $location      The location for which we are onboarding.
	 *                              This is a ISO 3166-1 alpha-2 country code.
	 * @param string $entry         The entry to get from the step data.
	 * @param mixed  $default_value The default value to return if the entry is not found.
	 *
	 * @return mixed The entry from the NOX profile step details. If the entry is not found, the default value is returned.
	 */
	private function get_nox_profile_onboarding_step_entry( string $step_id, string $location, string $entry, $default_value = array() ): array {
		$step_details = $this->get_nox_profile_onboarding_step( $step_id, $location );

		if ( ! isset( $step_details[ $entry ] ) ) {
			return $default_value;
		}

		return $step_details[ $entry ];
	}

	/**
	 * Save an entry in the NOX profile onboarding step details.
	 *
	 * @param string $step_id  The ID of the onboarding step.
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 * @param string $entry    The entry key under which to save in the step data.
	 * @param array  $data     The data to save in the step data.
	 *
	 * @return bool Whether the onboarding step data was saved.
	 */
	private function save_nox_profile_onboarding_step_entry( string $step_id, string $location, string $entry, array $data ): bool {
		$step_details = $this->get_nox_profile_onboarding_step( $step_id, $location );

		// Update the stored step data.
		$step_details[ $entry ] = $data;

		return $this->save_nox_profile_onboarding_step( $step_id, $location, $step_details );
	}

	/**
	 * Get a data entry from the NOX profile onboarding step details.
	 *
	 * @param string $step_id       The ID of the onboarding step.
	 * @param string $location      The location for which we are onboarding.
	 *                              This is a ISO 3166-1 alpha-2 country code.
	 * @param string $entry         The entry to get from the step `data`.
	 * @param mixed  $default_value The default value to return if the entry is not found.
	 *
	 * @return mixed The entry value from the NOX profile stored step data.
	 *               If the entry is not found, the default value is returned.
	 */
	private function get_nox_profile_onboarding_step_data_entry( string $step_id, string $location, string $entry, $default_value = false ) {
		$step_details_data = $this->get_nox_profile_onboarding_step_entry( $step_id, $location, 'data' );

		if ( ! isset( $step_details_data[ $entry ] ) ) {
			return $default_value;
		}

		return $step_details_data[ $entry ];
	}

	/**
	 * Save a data entry in the NOX profile onboarding step details.
	 *
	 * @param string $step_id  The ID of the onboarding step.
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 * @param string $entry    The entry key under which to save in the step `data`.
	 * @param mixed  $data     The value to save.
	 *
	 * @return bool Whether the onboarding step data was saved.
	 */
	private function save_nox_profile_onboarding_step_data_entry( string $step_id, string $location, string $entry, $data ): bool {
		$step_details_data = $this->get_nox_profile_onboarding_step_entry( $step_id, $location, 'data' );

		// Update the stored step data.
		$step_details_data[ $entry ] = $data;

		return $this->save_nox_profile_onboarding_step_entry( $step_id, $location, 'data', $step_details_data );
	}

	/**
	 * Get the IDs of the onboarding steps that are required for the given step.
	 *
	 * @param string $step_id The ID of the onboarding step.
	 *
	 * @return array|string[] The IDs of the onboarding steps that are required for the given step.
	 */
	private function get_onboarding_step_required_steps( string $step_id ): array {
		switch ( $step_id ) {
			// Both the test account and business verification (live account) steps require a working WPCOM connection.
			case self::ONBOARDING_STEP_TEST_ACCOUNT:
			case self::ONBOARDING_STEP_BUSINESS_VERIFICATION:
				return array(
					self::ONBOARDING_STEP_WPCOM_CONNECTION,
				);
			default:
				return array();
		}
	}

	/**
	 * Check if the requirements for an onboarding step are met.
	 *
	 * @param string $step_id  The ID of the onboarding step.
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 *
	 * @return bool Whether the onboarding step requirements are met.
	 * @throws ApiArgumentException If the given onboarding step ID is invalid.
	 */
	private function check_onboarding_step_requirements( string $step_id, string $location ): bool {
		$requirements = $this->get_onboarding_step_required_steps( $step_id );

		foreach ( $requirements as $required_step_id ) {
			if ( $this->get_onboarding_step_status( $required_step_id, $location ) !== self::ONBOARDING_STEP_STATUS_COMPLETED ) {
				return false;
			}
		}

		return true;
	}

	/**
	 * Get the payment methods state for onboarding.
	 *
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 *
	 * @return array The onboarding payment methods state.
	 */
	private function get_onboarding_payment_methods_state( string $location ): array {
		// First, get the recommended payment methods details from the provider.
		// We will use their enablement state as the default.
		// Note: The list is validated and standardized by the provider, so we don't need to do it here.
		$recommended_pms = $this->get_onboarding_recommended_payment_methods( $location );

		// Grab the stored payment methods state
		// (a key-value array of payment method IDs and if they should be automatically enabled or not).
		$step_pms_data = (array) $this->get_nox_profile_onboarding_step_data_entry( self::ONBOARDING_STEP_PAYMENT_METHODS, $location, 'payment_methods' );

		$payment_methods_state = array();
		$apple_pay_enabled     = false;
		$google_pay_enabled    = false;

		foreach ( $recommended_pms as $recommended_pm ) {
			$pm_id = $recommended_pm['id'];

			/**
			 * We need to handle Apple Pay and Google Pay separately.
			 * They are not stored in the same way as the other payment methods.
			 */
			if ( 'apple_pay' === $pm_id ) {
				$apple_pay_enabled = $recommended_pm['enabled'];
				continue;
			}

			if ( 'google_pay' === $pm_id ) {
				$google_pay_enabled = $recommended_pm['enabled'];
				continue;
			}

			// Start with the recommended enabled state.
			$payment_methods_state[ $pm_id ] = $recommended_pm['enabled'];

			// Force enable if required.
			if ( $recommended_pm['required'] ) {
				$payment_methods_state[ $pm_id ] = true;
				continue;
			}

			// Check the stored state, if any.
			if ( isset( $step_pms_data[ $pm_id ] ) ) {
				$payment_methods_state[ $pm_id ] = filter_var( $step_pms_data[ $pm_id ], FILTER_VALIDATE_BOOLEAN );
			}
		}

		// Combine Apple Pay and Google Pay into a single `apple_google` entry.
		$apple_google_enabled = $apple_pay_enabled || $google_pay_enabled;

		// Optionally also respect stored state or forced requirements if needed here.
		$payment_methods_state['apple_google'] = $apple_google_enabled;

		return $payment_methods_state;
	}

	/**
	 * Get the WPCOM (Jetpack) connection authorization details.
	 *
	 * @param string $return_url The URL to redirect to after the connection is set up.
	 *
	 * @return array The WPCOM connection authorization details.
	 */
	private function get_wpcom_connection_authorization( string $return_url ): array {
		return $this->proxy->call_static( Utils::class, 'get_wpcom_connection_authorization', $return_url );
	}

	/**
	 * Get the store's WPCOM (Jetpack) connection state.
	 *
	 * @return array The WPCOM connection state.
	 */
	private function get_wpcom_connection_state(): array {
		$is_connected        = $this->wpcom_connection_manager->is_connected();
		$has_connected_owner = $this->wpcom_connection_manager->has_connected_owner();

		return array(
			'has_working_connection' => $this->has_working_wpcom_connection(),
			'is_store_connected'     => $is_connected,
			'has_connected_owner'    => $has_connected_owner,
			'is_connection_owner'    => $has_connected_owner && $this->wpcom_connection_manager->is_connection_owner(),
		);
	}

	/**
	 * Check if the store has a working WPCOM connection.
	 *
	 * The store is considered to have a working WPCOM connection if:
	 * - The store is connected to WPCOM (blog ID and tokens are set).
	 * - The store connection has a connected owner (connection owner is set).
	 *
	 * @return bool Whether the store has a working WPCOM connection.
	 */
	private function has_working_wpcom_connection(): bool {
		return $this->wpcom_connection_manager->is_connected() && $this->wpcom_connection_manager->has_connected_owner();
	}

	/**
	 * Check if the WooPayments plugin is active.
	 *
	 * @return boolean
	 */
	private function is_extension_active(): bool {
		return $this->proxy->call_function( 'class_exists', '\WC_Payments' );
	}

	/**
	 * Get the main payment gateway instance.
	 *
	 * @return \WC_Payment_Gateway The main payment gateway instance.
	 */
	private function get_payment_gateway(): \WC_Payment_Gateway {
		return $this->proxy->call_static( '\WC_Payments', 'get_gateway' );
	}

	/**
	 * Determine if WooPayments has an account set up.
	 *
	 * @return bool Whether WooPayments has an account set up.
	 */
	private function has_account(): bool {
		return $this->provider->is_account_connected( $this->get_payment_gateway() );
	}

	/**
	 * Determine if WooPayments has a valid, fully onboarded account set up.
	 *
	 * @return bool Whether WooPayments has a valid, fully onboarded account set up.
	 */
	private function has_valid_account(): bool {
		if ( ! $this->has_account() ) {
			return false;
		}

		$account_service = $this->proxy->call_static( '\WC_Payments', 'get_account_service' );

		return $account_service->is_stripe_account_valid();
	}

	/**
	 * Determine if WooPayments has a working account set up.
	 *
	 * This is a more specific check than has_valid_account() and checks if payments are enabled for the account.
	 *
	 * @return bool Whether WooPayments has a working account set up.
	 */
	private function has_working_account(): bool {
		if ( ! $this->has_account() ) {
			return false;
		}

		$account_service = $this->proxy->call_static( '\WC_Payments', 'get_account_service' );
		$account_status  = $account_service->get_account_status_data();

		return ! empty( $account_status['paymentsEnabled'] );
	}

	/**
	 * Determine if WooPayments has a test account set up.
	 *
	 * @return bool Whether WooPayments has a test account set up.
	 */
	private function has_test_account(): bool {
		if ( ! $this->has_account() ) {
			return false;
		}

		$account_service = $this->proxy->call_static( '\WC_Payments', 'get_account_service' );
		$account_status  = $account_service->get_account_status_data();

		return ! empty( $account_status['testDrive'] );
	}

	/**
	 * Determine if WooPayments has a live account set up.
	 *
	 * @return bool Whether WooPayments has a test account set up.
	 */
	private function has_live_account(): bool {
		if ( ! $this->has_account() ) {
			return false;
		}

		$account_service = $this->proxy->call_static( '\WC_Payments', 'get_account_service' );
		$account_status  = $account_service->get_account_status_data();

		return ! empty( $account_status['isLive'] );
	}

	/**
	 * Get the onboarding fields data for the KYC business verification.
	 *
	 * @param string $location The location for which we are onboarding.
	 *                         This is a ISO 3166-1 alpha-2 country code.
	 *
	 * @return array The onboarding fields data.
	 * @throws Exception If the onboarding fields data could not be retrieved or there was an error.
	 */
	private function get_onboarding_kyc_fields( string $location ): array {
		// Call the WooPayments API to get the onboarding fields.
		$response = $this->proxy->call_static( Utils::class, 'rest_endpoint_get_request', '/wc/v3/payments/onboarding/fields' );

		if ( is_wp_error( $response ) ) {
			throw new Exception( esc_html( $response->get_error_message() ) );
		}

		if ( ! is_array( $response ) || ! isset( $response['data'] ) ) {
			throw new Exception( esc_html__( 'Failed to get onboarding fields data.', 'woocommerce' ) );
		}

		$fields = $response['data'];

		// If there is no available_countries entry, add it.
		if ( ! isset( $fields['available_countries'] ) && $this->proxy->call_function( 'is_callable', '\WC_Payments_Utils::supported_countries' ) ) {
			$fields['available_countries'] = $this->proxy->call_static( '\WC_Payments_Utils', 'supported_countries' );
		}

		$fields['location'] = $location;

		return $fields;
	}

	/**
	 * Get the fallback URL for the embedded KYC flow.
	 *
	 * @return string The fallback URL for the embedded KYC flow.
	 */
	private function get_onboarding_kyc_fallback_url(): string {
		if ( $this->proxy->call_function( 'is_callable', '\WC_Payments_Account::get_connect_url' ) ) {
			return $this->proxy->call_static( '\WC_Payments_Account', 'get_connect_url', self::FROM_NOX_IN_CONTEXT );
		}

		// Fall back to the provider onboarding URL.
		return $this->provider->get_onboarding_url(
			$this->get_payment_gateway(),
			Utils::wc_payments_settings_url( self::ONBOARDING_PATH_BASE, array( 'from' => self::FROM_KYC ) )
		);
	}

	/**
	 * Get the WooPayments Overview page URL.
	 *
	 * @return string The WooPayments Overview page URL.
	 */
	private function get_overview_page_url(): string {
		if ( $this->proxy->call_function( 'is_callable', '\WC_Payments_Account::get_overview_page_url' ) ) {
			return add_query_arg(
				array(
					'from' => self::FROM_NOX_IN_CONTEXT,
				),
				$this->proxy->call_static( '\WC_Payments_Account', 'get_overview_page_url' )
			);
		}

		// Fall back to the known WooPayments Overview page URL.
		return add_query_arg(
			array(
				'page' => 'wc-admin',
				'path' => '/payments/overview',
				'from' => self::FROM_NOX_IN_CONTEXT,
			),
			admin_url( 'admin.php' )
		);
	}

	/**
	 * Get the business location country code for the Payments settings.
	 *
	 * @return string The ISO 3166-1 alpha-2 country code to use for the overall business location.
	 *                If the user didn't set a location, the WC base location country code is used.
	 */
	private function get_country(): string {
		$user_nox_meta = get_user_meta( get_current_user_id(), self::PAYMENTS_NOX_PROFILE_KEY, true );
		if ( ! empty( $user_nox_meta['business_country_code'] ) ) {
			return $user_nox_meta['business_country_code'];
		}

		return WC()->countries->get_base_country();
	}

	/**
	 * Send a Tracks event.
	 *
	 * By default, Woo adds `url`, `blog_lang`, `blog_id`, `store_id`, `products_count`, and `wc_version`
	 * properties to every event.
	 *
	 * @param string $name              The event name.
	 *                                  If it is not prefixed with self::EVENT_PREFIX, it will be prefixed with it.
	 * @param string $business_country  The business registration country code as set in the WooCommerce Payments settings.
	 *                                  This is a ISO 3166-1 alpha-2 country code.
	 * @param array  $properties        Optional. The event custom properties.
	 *                                  These properties will be merged with the default properties.
	 *                                  Default properties values take precedence over the provided ones.
	 *
	 * @return void
	 */
	private function record_event( string $name, string $business_country, array $properties = array() ) {
		if ( ! function_exists( 'wc_admin_record_tracks_event' ) ) {
			return;
		}

		// If the event name is empty, we don't record it.
		if ( empty( $name ) ) {
			return;
		}

		// If the event name is not prefixed with `settings_payments_`, we prefix it.
		if ( ! str_starts_with( $name, self::EVENT_PREFIX ) ) {
			$name = self::EVENT_PREFIX . $name;
		}

		// Add default properties to every event and overwrite custom properties with the same keys.
		$properties = array_merge(
			$properties,
			array(
				'business_country' => $business_country,
			),
		);

		wc_admin_record_tracks_event( $name, $properties );
	}
}
