*/ private function check_providers_order_map_arg( $value ) { if ( ! is_array( $value ) ) { return new WP_Error( 'rest_invalid_param', esc_html__( 'The ordering argument must be an object.', 'woocommerce' ), array( 'status' => 400 ) ); } foreach ( $value as $provider_id => $order ) { if ( ! is_string( $provider_id ) || ! is_numeric( $order ) ) { return new WP_Error( 'rest_invalid_param', esc_html__( 'The ordering argument must be an object with provider IDs as keys and numeric values as values.', 'woocommerce' ), array( 'status' => 400 ) ); } if ( sanitize_key( $provider_id ) !== $provider_id ) { return new WP_Error( 'rest_invalid_param', esc_html__( 'The provider ID must be a valid string.', 'woocommerce' ), array( 'status' => 400 ) ); } if ( false === filter_var( $order, FILTER_VALIDATE_INT ) ) { return new WP_Error( 'rest_invalid_param', esc_html__( 'The order value must be an integer.', 'woocommerce' ), array( 'status' => 400 ) ); } } return true; } /** * Sanitize the providers ordering argument. * * @param array $value Value of the argument. * * @return array */ private function sanitize_providers_order_arg( array $value ): array { // Sanitize the ordering object to ensure that the order values are integers and the provider IDs are safe strings. foreach ( $value as $provider_id => $order ) { $id = sanitize_key( $provider_id ); $value[ $id ] = intval( $order ); } return $value; } /** * Prepare the response for the GET payment providers request. * * @param array $response The response to prepare. * * @return array The prepared response. */ private function prepare_payment_providers_response( array $response ): array { $response = $this->prepare_payment_providers_response_recursive( $response, $this->get_schema_for_get_payment_providers() ); $response['providers'] = $this->add_provider_links( $response['providers'] ); return $response; } /** * Recursively prepare the response items for the GET payment providers request. * * @param mixed $response_item The response item to prepare. * @param array $schema The schema to use for preparing the response. * * @return mixed The prepared response item. */ private function prepare_payment_providers_response_recursive( $response_item, array $schema ) { if ( is_null( $response_item ) || ! array_key_exists( 'properties', $schema ) || ! is_array( $schema['properties'] ) ) { return $response_item; } $prepared_response = array(); foreach ( $schema['properties'] as $key => $property_schema ) { if ( is_array( $response_item ) && array_key_exists( $key, $response_item ) ) { if ( is_array( $property_schema ) && array_key_exists( 'properties', $property_schema ) ) { $prepared_response[ $key ] = $this->prepare_payment_providers_response_recursive( $response_item[ $key ], $property_schema ); } elseif ( is_array( $property_schema ) && array_key_exists( 'items', $property_schema ) ) { $prepared_response[ $key ] = array_map( fn( $item ) => $this->prepare_payment_providers_response_recursive( $item, $property_schema['items'] ), $response_item[ $key ] ); } else { $prepared_response[ $key ] = $response_item[ $key ]; } } } // Ensure the order is the same as in the schema. $prepared_response = array_merge( array_fill_keys( array_keys( $schema['properties'] ), null ), $prepared_response ); // Remove any null values from the response. $prepared_response = array_filter( $prepared_response, fn( $value ) => ! is_null( $value ) ); return $prepared_response; } /** * Add links to providers list items. * * @param array $providers The providers list. * * @return array The providers list with added links. */ private function add_provider_links( array $providers ): array { foreach ( $providers as $key => $provider ) { if ( empty( $provider['_links'] ) ) { $providers[ $key ]['_links'] = array(); } // If this is a suggestion, add a link to hide it. if ( ! empty( $provider['_type'] ) && PaymentProviders::TYPE_SUGGESTION === $provider['_type'] && ! empty( $provider['_suggestion_id'] ) ) { $providers[ $key ]['_links']['hide'] = array( 'href' => rest_url( sprintf( '/%s/%s/suggestion/%s/hide', $this->route_namespace, $this->rest_base, $provider['_suggestion_id'] ) ), ); } // If we have an incentive, add a link to dismiss it. if ( ! empty( $provider['_incentive'] ) && ! empty( $provider['_suggestion_id'] ) ) { if ( empty( $provider['_incentive']['_links'] ) ) { $providers[ $key ]['_incentive']['_links'] = array(); } $providers[ $key ]['_incentive']['_links']['dismiss'] = array( 'href' => rest_url( sprintf( '/%s/%s/suggestion/%s/incentive/%s/dismiss', $this->route_namespace, $this->rest_base, $provider['_suggestion_id'], $provider['_incentive']['id'] ) ), ); } } return $providers; } /** * Get the schema for the GET payment providers request. * * @return array[] */ private function get_schema_for_get_payment_providers(): array { $schema = array( '$schema' => 'http://json-schema.org/draft-04/schema#', 'title' => 'WooCommerce Settings Payments providers for the given location.', 'type' => 'object', ); $schema['properties'] = array( 'providers' => array( 'type' => 'array', 'description' => esc_html__( 'The ordered providers list. This includes registered payment gateways, suggestions, and offline payment methods group entry. The individual offline payment methods are separate.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, 'items' => $this->get_schema_for_payment_provider(), ), 'offline_payment_methods' => array( 'type' => 'array', 'description' => esc_html__( 'The ordered offline payment methods providers list.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, 'items' => $this->get_schema_for_payment_provider(), ), 'suggestions' => array( 'type' => 'array', 'description' => esc_html__( 'The list of suggestions, excluding the ones part of the providers list.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, 'items' => $this->get_schema_for_suggestion(), ), 'suggestion_categories' => array( 'type' => 'array', 'description' => esc_html__( 'The suggestion categories.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, 'items' => array( 'type' => 'object', 'description' => esc_html__( 'A suggestion category.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, 'properties' => array( 'id' => array( 'type' => 'string', 'description' => esc_html__( 'The unique identifier for the category.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), '_priority' => array( 'type' => 'integer', 'description' => esc_html__( 'The priority of the category.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'title' => array( 'type' => 'string', 'description' => esc_html__( 'The title of the category.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'description' => array( 'type' => 'string', 'description' => esc_html__( 'The description of the category.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), ), ), ), ); return $schema; } /** * Get the schema for a payment provider. * * @return array The schema for a payment provider. */ private function get_schema_for_payment_provider(): array { return array( 'type' => 'object', 'description' => esc_html__( 'A payment provider in the context of the main Payments Settings page list.', 'woocommerce' ), 'properties' => array( 'id' => array( 'type' => 'string', 'description' => esc_html__( 'The unique identifier for the provider.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), '_order' => array( 'type' => 'integer', 'description' => esc_html__( 'The sort order of the provider.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), '_type' => array( 'type' => 'string', 'description' => esc_html__( 'The type of payment provider. Use this to differentiate between the various items in the list and determine their intended use.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'title' => array( 'type' => 'string', 'description' => esc_html__( 'The title of the provider.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'description' => array( 'type' => 'string', 'description' => esc_html__( 'The description of the provider.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'supports' => array( 'description' => __( 'Supported features for this provider.', 'woocommerce' ), 'type' => 'array', 'context' => array( 'view', 'edit' ), 'readonly' => true, 'items' => array( 'type' => 'string', ), ), 'plugin' => array( 'type' => 'object', 'description' => esc_html__( 'The corresponding plugin details of the provider.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, 'properties' => array( '_type' => array( 'type' => 'string', 'enum' => array( PaymentProviders::EXTENSION_TYPE_WPORG ), 'description' => esc_html__( 'The type of the plugin.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'slug' => array( 'type' => 'string', 'description' => esc_html__( 'The slug of the plugin.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'file' => array( 'type' => 'string', 'description' => esc_html__( 'The plugin main file. This is a relative path to the plugins directory.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'status' => array( 'type' => 'string', 'enum' => array( PaymentProviders::EXTENSION_NOT_INSTALLED, PaymentProviders::EXTENSION_INSTALLED, PaymentProviders::EXTENSION_ACTIVE, ), 'description' => esc_html__( 'The status of the plugin.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), ), ), 'image' => array( 'type' => 'string', 'description' => esc_html__( 'The URL of the provider image.', 'woocommerce' ), 'readonly' => true, ), 'icon' => array( 'type' => 'string', 'description' => esc_html__( 'The URL of the provider icon (square aspect ratio - 72px by 72px).', 'woocommerce' ), 'readonly' => true, ), 'links' => array( 'type' => 'array', 'description' => __( 'Links for the provider.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, 'items' => array( 'type' => 'object', 'properties' => array( '_type' => array( 'type' => 'string', 'description' => esc_html__( 'The type of the link.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'url' => array( 'type' => 'string', 'description' => esc_html__( 'The URL of the link.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), ), ), ), 'state' => array( 'type' => 'object', 'description' => esc_html__( 'The general state of the provider with regards to it\'s payments processing.', 'woocommerce' ), 'properties' => array( 'enabled' => array( 'type' => 'boolean', 'description' => esc_html__( 'Whether the provider is enabled for use on checkout.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'account_connected' => array( 'type' => 'boolean', 'description' => esc_html__( 'Whether the provider has a payments processing account connected.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'needs_setup' => array( 'type' => 'boolean', 'description' => esc_html__( 'Whether the provider needs setup.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'test_mode' => array( 'type' => 'boolean', 'description' => esc_html__( 'Whether the provider is in test mode for payments processing.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'dev_mode' => array( 'type' => 'boolean', 'description' => esc_html__( 'Whether the provider is in dev mode. Having this true usually leads to forcing test payments. ', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), ), ), 'management' => array( 'type' => 'object', 'description' => esc_html__( 'The management details of the provider.', 'woocommerce' ), 'properties' => array( '_links' => array( 'type' => 'object', 'context' => array( 'view', 'edit' ), 'readonly' => true, 'properties' => array( 'settings' => array( 'type' => 'object', 'description' => esc_html__( 'The link to the settings page for the payment gateway.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, 'properties' => array( 'href' => array( 'type' => 'string', 'description' => esc_html__( 'The URL to the settings page for the payment gateway.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), ), ), ), ), ), ), 'onboarding' => array( 'type' => 'object', 'description' => esc_html__( 'Onboarding-related details for the provider.', 'woocommerce' ), 'properties' => array( 'state' => array( 'type' => 'object', 'description' => esc_html__( 'The state of the onboarding process.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'properties' => array( 'started' => array( 'type' => 'boolean', 'description' => esc_html__( 'Whether the onboarding process has been started.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'completed' => array( 'type' => 'boolean', 'description' => esc_html__( 'Whether the onboarding process has been completed.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'test_mode' => array( 'type' => 'boolean', 'description' => esc_html__( 'Whether the onboarding process happens in test mode (aka sandbox or test-drive).', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), ), ), '_links' => array( 'type' => 'object', 'context' => array( 'view', 'edit' ), 'readonly' => true, 'properties' => array( 'onboard' => array( 'type' => 'object', 'description' => esc_html__( 'The start/continue onboarding link for the payment gateway.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, 'properties' => array( 'href' => array( 'type' => 'string', 'description' => esc_html__( 'The URL to start/continue onboarding for the payment gateway.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), ), ), ), ), 'recommended_payment_methods' => array( 'type' => 'array', 'description' => esc_html__( 'The list of recommended payment methods details for the payment gateway.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, 'items' => array( 'type' => 'object', 'description' => esc_html__( 'The details for a recommended payment method.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, 'properties' => array( 'id' => array( 'type' => 'string', 'description' => esc_html__( 'The unique identifier for the payment method.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), '_order' => array( 'type' => 'integer', 'description' => esc_html__( 'The sort order of the payment method.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'enabled' => array( 'type' => 'boolean', 'description' => esc_html__( 'Whether the payment method should be recommended as enabled or not.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'required' => array( 'type' => 'boolean', 'description' => esc_html__( 'Whether the payment method should be required (and force-enabled) or not.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'title' => array( 'type' => 'string', 'description' => esc_html__( 'The title of the payment method. Does not include HTML tags.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'description' => array( 'type' => 'string', 'description' => esc_html__( 'The description of the payment method. It can contain basic HTML.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'icon' => array( 'type' => 'string', 'description' => esc_html__( 'The URL of the payment method icon or a base64-encoded SVG image.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), ), ), ), ), ), 'tags' => array( 'type' => 'array', 'description' => esc_html__( 'The tags associated with the provider.', 'woocommerce' ), 'uniqueItems' => true, 'context' => array( 'view', 'edit' ), 'readonly' => true, 'items' => array( 'type' => 'string', 'description' => esc_html__( 'Tag associated with the provider.', 'woocommerce' ), 'readonly' => true, ), ), '_suggestion_id' => array( 'type' => 'string', 'description' => esc_html__( 'The suggestion ID matching this provider.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), '_incentive' => array( 'type' => 'object', 'description' => esc_html__( 'The active incentive for the provider.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, 'properties' => array( 'id' => array( 'type' => 'string', 'description' => esc_html__( 'The incentive unique ID. This ID needs to be used for incentive dismissals.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'promo_id' => array( 'type' => 'string', 'description' => esc_html__( 'The incentive promo ID. This ID need to be fed into the onboarding flow.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'title' => array( 'type' => 'string', 'description' => esc_html__( 'The incentive title. It can contain stylistic HTML.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'description' => array( 'type' => 'string', 'description' => esc_html__( 'The incentive description. It can contain stylistic HTML.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'short_description' => array( 'type' => 'string', 'description' => esc_html__( 'The short description of the incentive. It can contain stylistic HTML.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'cta_label' => array( 'type' => 'string', 'description' => esc_html__( 'The call to action label for the incentive.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'tc_url' => array( 'type' => 'string', 'description' => esc_html__( 'The URL to the terms and conditions for the incentive.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'badge' => array( 'type' => 'string', 'description' => esc_html__( 'The badge label for the incentive.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), '_dismissals' => array( 'type' => 'array', 'description' => esc_html__( 'The dismissals list for the incentive. The `all` entry means the incentive was dismissed for all contexts.', 'woocommerce' ), 'uniqueItems' => true, 'context' => array( 'view', 'edit' ), 'readonly' => true, 'items' => array( 'type' => 'string', 'description' => esc_html__( 'Context ID in which the incentive was dismissed.', 'woocommerce' ), 'readonly' => true, ), ), '_links' => array( 'type' => 'object', 'context' => array( 'view', 'edit' ), 'readonly' => true, 'properties' => array( 'dismiss' => array( 'type' => 'object', 'description' => esc_html__( 'The link to dismiss the incentive.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, 'properties' => array( 'href' => array( 'type' => 'string', 'description' => esc_html__( 'The URL to dismiss the incentive.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), ), ), 'onboard' => array( 'type' => 'object', 'description' => esc_html__( 'The start/continue onboarding link for the payment gateway.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, 'properties' => array( 'href' => array( 'type' => 'string', 'description' => esc_html__( 'The URL to start/continue onboarding for the payment gateway.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), ), ), ), ), ), ), '_links' => array( 'type' => 'object', 'context' => array( 'view', 'edit' ), 'readonly' => true, 'properties' => array( 'hide' => array( 'type' => 'object', 'description' => esc_html__( 'The link to hide the suggestion.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, 'properties' => array( 'href' => array( 'type' => 'string', 'description' => esc_html__( 'The URL to hide the suggestion.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), ), ), ), ), ), ); } /** * Get the schema for a suggestion. * * @return array The schema for a suggestion. */ private function get_schema_for_suggestion(): array { return array( 'type' => 'object', 'description' => esc_html__( 'A suggestion with full details.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, 'properties' => array( 'id' => array( 'type' => 'string', 'description' => esc_html__( 'The unique identifier for the suggestion.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), '_priority' => array( 'type' => 'integer', 'description' => esc_html__( 'The priority of the suggestion.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), '_type' => array( 'type' => 'string', 'description' => esc_html__( 'The type of the suggestion.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'title' => array( 'type' => 'string', 'description' => esc_html__( 'The title of the suggestion.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'description' => array( 'type' => 'string', 'description' => esc_html__( 'The description of the suggestion.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'plugin' => array( 'type' => 'object', 'context' => array( 'view', 'edit' ), 'readonly' => true, 'properties' => array( '_type' => array( 'type' => 'string', 'enum' => array( PaymentProviders::EXTENSION_TYPE_WPORG ), 'description' => esc_html__( 'The type of the plugin.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'slug' => array( 'type' => 'string', 'description' => esc_html__( 'The slug of the plugin.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'status' => array( 'type' => 'string', 'enum' => array( PaymentProviders::EXTENSION_NOT_INSTALLED, PaymentProviders::EXTENSION_INSTALLED, PaymentProviders::EXTENSION_ACTIVE, ), 'description' => esc_html__( 'The status of the plugin.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), ), ), 'image' => array( 'type' => 'string', 'description' => esc_html__( 'The URL of the image.', 'woocommerce' ), 'readonly' => true, ), 'icon' => array( 'type' => 'string', 'description' => esc_html__( 'The URL of the icon (square aspect ratio).', 'woocommerce' ), 'readonly' => true, ), 'links' => array( 'type' => 'array', 'context' => array( 'view', 'edit' ), 'readonly' => true, 'items' => array( 'type' => 'object', 'properties' => array( '_type' => array( 'type' => 'string', 'description' => esc_html__( 'The type of the link.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'url' => array( 'type' => 'string', 'description' => esc_html__( 'The URL of the link.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), ), ), ), 'tags' => array( 'description' => esc_html__( 'The tags associated with the suggestion.', 'woocommerce' ), 'type' => 'array', 'uniqueItems' => true, 'context' => array( 'view', 'edit' ), 'readonly' => true, 'items' => array( 'type' => 'string', 'description' => esc_html__( 'The tags associated with the suggestion.', 'woocommerce' ), 'readonly' => true, ), ), 'category' => array( 'type' => 'string', 'description' => esc_html__( 'The category of the suggestion.', 'woocommerce' ), 'context' => array( 'view', 'edit' ), 'readonly' => true, ), ), ); } }