Changeset 3698250

Timestamp:

09/16/2026 09:19:10 AM (6 weeks ago)

Author:

abdullahalmulhim1

Message:

Release 1.1.0: rewrite listing copy around merchant outcomes, add FAQ, add settings Test Connection button and order-screen status panel, correct documented retry/default-invoice behavior

Location:

saudi-vat-pro-for-woocommerce/trunk

Files:

• assets/js/order-status.js (added)
• assets/js/settings.js (added)
• includes/class-svp-admin.php (modified) (2 diffs)
• includes/class-svp-api-client.php (modified) (1 diff)
• includes/class-svp-order-handler.php (modified) (5 diffs)
• readme.txt (modified) (5 diffs)
• saudi-vat-pro-woocommerce.php (modified) (2 diffs)

saudi-vat-pro-for-woocommerce/trunk/includes/class-svp-admin.php

@@ -10 +10 @@
         add_action( 'woocommerce_settings_tabs_saudi_vat_pro', [ __CLASS__, 'render_settings_tab' ] );
         add_action( 'woocommerce_update_options_saudi_vat_pro', [ __CLASS__, 'save_settings' ] );
+        add_action( 'woocommerce_admin_field_saudivatpro_test_connection', [ __CLASS__, 'render_test_connection_field' ] );
+        add_action( 'admin_enqueue_scripts', [ __CLASS__, 'enqueue_settings_assets' ] );
+        add_action( 'wp_ajax_saudivatpro_wc_test_connection', [ __CLASS__, 'ajax_test_connection' ] );
+    }
+
+    /**
+     * Load the Test Connection button script only on our Settings tab.
+     */
+    public static function enqueue_settings_assets() {
+        $screen = get_current_screen();
+        if ( ! $screen || 'woocommerce_page_wc-settings' !== $screen->id ) {
+            return;
+        }
+        // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only tab check, no state change.
+        if ( ! isset( $_GET['tab'] ) || 'saudi_vat_pro' !== sanitize_key( wp_unslash( $_GET['tab'] ) ) ) {
+            return;
+        }
+
+        wp_enqueue_script(
+            'saudivatpro-wc-settings',
+            SAUDIVATPRO_WC_PLUGIN_URL . 'assets/js/settings.js',
+            [ 'jquery' ],
+            SAUDIVATPRO_WC_VERSION,
+            true
+        );
+        wp_localize_script( 'saudivatpro-wc-settings', 'SaudiVATProSettings', [
+            'ajaxUrl' => admin_url( 'admin-ajax.php' ),
+            'nonce'   => wp_create_nonce( 'saudivatpro_wc_test_connection' ),
+            'i18n'    => [
+                'testing' => __( 'Testing…', 'saudi-vat-pro-for-woocommerce' ),
+                'success' => __( 'Connection verified — the webhook URL and secret are valid.', 'saudi-vat-pro-for-woocommerce' ),
+                'missing' => __( 'Enter the webhook URL and secret above first.', 'saudi-vat-pro-for-woocommerce' ),
+            ],
+        ] );
+    }
+
+    /**
+     * Render the "Test Connection" button and result area as a WooCommerce
+     * settings field row. Registered via the 'saudivatpro_test_connection'
+     * custom field type declared in get_settings().
+     */
+    public static function render_test_connection_field() {
+        ?>
+        <tr valign="top">
+            <th scope="row" class="titledesc"></th>
+            <td class="forminp">
+                <button type="button" class="button" id="saudivatpro-wc-test-connection">
+                    <?php esc_html_e( 'Test Connection', 'saudi-vat-pro-for-woocommerce' ); ?>
+                </button>
+                <span id="saudivatpro-wc-test-connection-result" style="margin-left:10px;"></span>
+                <p class="description">
+                    <?php esc_html_e( 'Verifies the webhook URL and secret above without creating a test invoice or touching a live order.', 'saudi-vat-pro-for-woocommerce' ); ?>
+                </p>
+            </td>
+        </tr>
+        <?php
+    }
+
+    /**
+     * AJAX handler for the Test Connection button. Verifies the currently
+     * entered (not necessarily saved) webhook URL and secret against the
+     * Saudi VAT Pro API's connection-verification endpoint.
+     */
+    public static function ajax_test_connection() {
+        check_ajax_referer( 'saudivatpro_wc_test_connection', 'nonce' );
+        if ( ! current_user_can( 'manage_woocommerce' ) ) {
+            wp_send_json_error( [ 'message' => __( 'You do not have permission to do this.', 'saudi-vat-pro-for-woocommerce' ) ], 403 );
+        }
+
+        $webhook_url = isset( $_POST['webhook_url'] ) ? esc_url_raw( wp_unslash( $_POST['webhook_url'] ) ) : '';
+        $secret      = isset( $_POST['secret'] ) ? sanitize_text_field( wp_unslash( $_POST['secret'] ) ) : '';
+
+        $result = SaudiVATPro_WC_API_Client::test_connection( $webhook_url, $secret );
+
+        if ( is_wp_error( $result ) ) {
+            wp_send_json_error( [ 'message' => $result->get_error_message() ] );
+        }
+
+        wp_send_json_success( [ 'message' => __( 'Connection verified — the webhook URL and secret are valid.', 'saudi-vat-pro-for-woocommerce' ) ] );
     }
 
@@ -57 +136 @@
             ],
             [
+                'type' => 'saudivatpro_test_connection',
+                'id'   => 'saudivatpro_wc_test_connection',
+            ],
+            [
                 'title'    => __( 'Show VAT Number field at checkout', 'saudi-vat-pro-for-woocommerce' ),
                 'type'     => 'checkbox',

saudi-vat-pro-for-woocommerce/trunk/includes/class-svp-api-client.php

@@ -264 +264 @@
     }
 
+    /**
+     * Verify a webhook URL + secret pair without creating any invoice, order,
+     * or credit-note record. Used by the Settings screen's "Test Connection"
+     * button so merchants can confirm setup before placing a real order.
+     *
+     * @param string $webhook_url Candidate webhook URL (may be unsaved).
+     * @param string $secret      Candidate webhook secret (may be unsaved).
+     * @return true|WP_Error
+     */
+    public static function test_connection( $webhook_url, $secret ) {
+        $webhook_url = esc_url_raw( $webhook_url );
+        if ( ! self::is_valid_webhook_url( $webhook_url ) ) {
+            return new WP_Error( 'saudivatpro_wc_not_configured', __( 'Enter a valid HTTPS Saudi VAT Pro webhook URL before testing.', 'saudi-vat-pro-for-woocommerce' ) );
+        }
+
+        $secret = sanitize_text_field( $secret );
+        if ( '' === $secret ) {
+            return new WP_Error( 'saudivatpro_wc_not_configured', __( 'Enter the webhook secret before testing.', 'saudi-vat-pro-for-woocommerce' ) );
+        }
+
+        $url  = rtrim( $webhook_url, '/' ) . '/test-connection';
+        $body = wp_json_encode( [ 'test' => true, 'site' => get_site_url() ] );
+
+        $headers = [
+            'Content-Type'         => 'application/json',
+            'X-SaudiVATPro-Source' => 'woocommerce/' . SAUDIVATPRO_WC_VERSION,
+        ];
+        // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_encode -- benign: base64 is the wire format for an HMAC-SHA256 webhook signature header, not obfuscation.
+        $headers['X-WC-Webhook-Signature'] = base64_encode( hash_hmac( 'sha256', $body, $secret, true ) );
+
+        $response = wp_remote_post( $url, [
+            'headers'     => $headers,
+            'body'        => $body,
+            'timeout'     => 15,
+            'data_format' => 'body',
+        ] );
+
+        if ( is_wp_error( $response ) ) {
+            return $response;
+        }
+
+        $code = wp_remote_retrieve_response_code( $response );
+        $data = json_decode( wp_remote_retrieve_body( $response ), true );
+
+        if ( $code < 200 || $code >= 300 ) {
+            $message = isset( $data['message'] )
+                ? sanitize_text_field( $data['message'] )
+                : sprintf(
+                    /* translators: %d: HTTP status code returned by the Saudi VAT Pro API. */
+                    __( 'Saudi VAT Pro returned HTTP %d.', 'saudi-vat-pro-for-woocommerce' ),
+                    $code
+                );
+            return new WP_Error( 'saudivatpro_wc_api_error', $message );
+        }
+
+        return true;
+    }
+
     private static function validate_invoice_response( $response ) {
         if ( is_wp_error( $response ) ) {

saudi-vat-pro-for-woocommerce/trunk/includes/class-svp-order-handler.php

@@ -26 +26 @@
         add_action( 'saudivatpro_wc_retry_submission', [ __CLASS__, 'retry_submission' ] );
         add_action( 'saudivatpro_wc_retry_refund_submission', [ __CLASS__, 'retry_refund_submission' ], 10, 2 );
+        // Order edit screen status panel (classic and HPOS).
+        add_action( 'add_meta_boxes', [ __CLASS__, 'register_status_meta_box' ] );
+        add_action( 'admin_enqueue_scripts', [ __CLASS__, 'enqueue_order_assets' ] );
+        add_action( 'wp_ajax_saudivatpro_wc_retry_order', [ __CLASS__, 'ajax_retry_order' ] );
+    }
+
+    /**
+     * The order edit screen ID differs between classic (post-based) orders and
+     * HPOS custom-table orders. wc_get_page_screen_id() (WC 8.0+) returns the
+     * correct one; older WooCommerce versions register on both since we cannot
+     * otherwise detect which storage is active.
+     *
+     * @return string[]
+     */
+    private static function get_order_screen_ids() {
+        if ( function_exists( 'wc_get_page_screen_id' ) ) {
+            return [ wc_get_page_screen_id( 'shop-order' ) ];
+        }
+        return [ 'shop_order', 'woocommerce_page_wc-orders' ];
+    }
+
+    /**
+     * Register the "Saudi VAT Pro" status panel meta box on the order edit screen.
+     */
+    public static function register_status_meta_box() {
+        add_meta_box(
+            'saudivatpro-wc-status',
+            __( 'Saudi VAT Pro', 'saudi-vat-pro-for-woocommerce' ),
+            [ __CLASS__, 'render_status_meta_box' ],
+            self::get_order_screen_ids(),
+            'side',
+            'high'
+        );
+    }
+
+    /**
+     * Load the retry-button script only on the order edit screen.
+     */
+    public static function enqueue_order_assets() {
+        $screen = get_current_screen();
+        if ( ! $screen || ! in_array( $screen->id, self::get_order_screen_ids(), true ) ) {
+            return;
+        }
+
+        wp_enqueue_script(
+            'saudivatpro-wc-order-status',
+            SAUDIVATPRO_WC_PLUGIN_URL . 'assets/js/order-status.js',
+            [ 'jquery' ],
+            SAUDIVATPRO_WC_VERSION,
+            true
+        );
+        wp_localize_script( 'saudivatpro-wc-order-status', 'SaudiVATProOrderStatus', [
+            'ajaxUrl' => admin_url( 'admin-ajax.php' ),
+            'nonce'   => wp_create_nonce( 'saudivatpro_wc_retry_order' ),
+            'i18n'    => [
+                'retrying' => __( 'Retrying…', 'saudi-vat-pro-for-woocommerce' ),
+                'failed'   => __( 'Retry failed. Check the error message above.', 'saudi-vat-pro-for-woocommerce' ),
+            ],
+        ] );
+    }
+
+    /**
+     * Meta box callback. WooCommerce passes a WP_Post on classic order-admin
+     * screens and the WC_Order object itself on HPOS screens.
+     *
+     * @param WP_Post|WC_Order $post_or_order
+     */
+    public static function render_status_meta_box( $post_or_order ) {
+        $order = $post_or_order instanceof WC_Order ? $post_or_order : wc_get_order( $post_or_order );
+        if ( ! $order ) {
+            esc_html_e( 'Order not found.', 'saudi-vat-pro-for-woocommerce' );
+            return;
+        }
+
+        $data = self::get_status_panel_data( $order );
+
+        $status_colors = [
+            'submitted'     => '#1a7f37',
+            'failed'        => '#cc1818',
+            'not_submitted' => '#646970',
+        ];
+        $color = isset( $status_colors[ $data['status'] ] ) ? $status_colors[ $data['status'] ] : '#646970';
+        ?>
+        <div class="saudivatpro-wc-status-panel" data-order-id="<?php echo esc_attr( $order->get_id() ); ?>">
+            <p>
+                <strong><?php esc_html_e( 'Status:', 'saudi-vat-pro-for-woocommerce' ); ?></strong>
+                <span class="saudivatpro-wc-status-label" style="color: <?php echo esc_attr( $color ); ?>; font-weight:600;">
+                    <?php echo esc_html( $data['status_label'] ); ?>
+                </span>
+            </p>
+            <?php if ( $data['invoice_id'] ) : ?>
+                <p>
+                    <strong><?php esc_html_e( 'Invoice ID:', 'saudi-vat-pro-for-woocommerce' ); ?></strong>
+                    <?php echo esc_html( $data['invoice_id'] ); ?>
+                </p>
+            <?php endif; ?>
+            <?php if ( $data['pdf_url'] ) : ?>
+                <p>
+                    <a href="<?php echo esc_url( $data['pdf_url'] ); ?>" target="_blank" rel="noopener noreferrer" class="button">
+                        <?php esc_html_e( 'View Invoice PDF', 'saudi-vat-pro-for-woocommerce' ); ?>
+                    </a>
+                </p>
+            <?php endif; ?>
+            <?php if ( $data['error'] ) : ?>
+                <p class="saudivatpro-wc-status-error-message" style="color: #cc1818;">
+                    <strong><?php esc_html_e( 'Last error:', 'saudi-vat-pro-for-woocommerce' ); ?></strong><br />
+                    <?php echo esc_html( $data['error'] ); ?>
+                </p>
+            <?php endif; ?>
+            <?php if ( ! $data['invoice_id'] ) : ?>
+                <p>
+                    <button type="button" class="button saudivatpro-wc-retry-button">
+                        <?php esc_html_e( 'Retry submission', 'saudi-vat-pro-for-woocommerce' ); ?>
+                    </button>
+                    <span class="saudivatpro-wc-retry-result" style="margin-left:8px;"></span>
+                </p>
+            <?php endif; ?>
+        </div>
+        <?php
+    }
+
+    /**
+     * Collect the status-panel fields for one order: not yet submitted,
+     * submitted, or failed, with invoice ID, PDF link, and last error.
+     *
+     * @param WC_Order $order
+     * @return array
+     */
+    private static function get_status_panel_data( $order ) {
+        $invoice_id = saudivatpro_wc_get_order_meta( $order, 'invoice_id' );
+        $pdf_url    = saudivatpro_wc_get_order_meta( $order, 'invoice_url' );
+        $error      = saudivatpro_wc_get_order_meta( $order, 'error' );
+
+        if ( $invoice_id ) {
+            $status       = 'submitted';
+            $status_label = __( 'Submitted', 'saudi-vat-pro-for-woocommerce' );
+        } elseif ( $error ) {
+            $status       = 'failed';
+            $status_label = __( 'Failed', 'saudi-vat-pro-for-woocommerce' );
+        } else {
+            $status       = 'not_submitted';
+            $status_label = __( 'Not yet submitted', 'saudi-vat-pro-for-woocommerce' );
+        }
+
+        return [
+            'status'       => $status,
+            'status_label' => $status_label,
+            'invoice_id'   => $invoice_id,
+            'pdf_url'      => $pdf_url,
+            'error'        => $error,
+        ];
+    }
+
+    /**
+     * AJAX handler for the status panel's "Retry submission" button. Reuses
+     * admin_retry_action(), which already refuses to resubmit an order that
+     * has an invoice, so this stays safe against duplicate submissions.
+     */
+    public static function ajax_retry_order() {
+        check_ajax_referer( 'saudivatpro_wc_retry_order', 'nonce' );
+        if ( ! current_user_can( 'edit_shop_orders' ) ) {
+            wp_send_json_error( [ 'message' => __( 'You do not have permission to do this.', 'saudi-vat-pro-for-woocommerce' ) ], 403 );
+        }
+
+        $order_id = isset( $_POST['order_id'] ) ? absint( $_POST['order_id'] ) : 0;
+        $order    = $order_id ? wc_get_order( $order_id ) : false;
+        if ( ! $order ) {
+            wp_send_json_error( [ 'message' => __( 'Order not found.', 'saudi-vat-pro-for-woocommerce' ) ], 404 );
+        }
+
+        self::admin_retry_action( $order );
+
+        $order = wc_get_order( $order_id );
+        wp_send_json_success( self::get_status_panel_data( $order ) );
     }
 
@@ -76 +250 @@
             $order->update_meta_data( '_saudivatpro_wc_invoice_id', sanitize_text_field( $result['invoiceId'] ) );
         }
-        if ( isset( $result['pdfUrl'] ) ) {
-            $order->update_meta_data( '_saudivatpro_wc_invoice_url', esc_url_raw( $result['pdfUrl'] ) );
+        $invoice_url = isset( $result['pdfUrl'] ) && is_string( $result['pdfUrl'] ) ? esc_url_raw( $result['pdfUrl'] ) : '';
+        if ( $invoice_url ) {
+            // The API returns a customer-safe, expiring document URL. Keep it on the
+            // order using the established invoice URL meta key.
+            $order->update_meta_data( '_saudivatpro_wc_invoice_url', $invoice_url );
         }
         $order->delete_meta_data( '_saudivatpro_wc_error' );
@@ -147 +324 @@
 
         $state['credit_note_id'] = sanitize_text_field( $result['invoiceId'] );
-        $state['pdf_url']        = isset( $result['pdfUrl'] ) ? esc_url_raw( $result['pdfUrl'] ) : '';
+        // Preserve one customer-safe URL per refund state so partial refunds retain
+        // their own credit-note documents.
+        $state['pdf_url']        = isset( $result['pdfUrl'] ) && is_string( $result['pdfUrl'] ) ? esc_url_raw( $result['pdfUrl'] ) : '';
         $state['error']          = '';
         $state['retry_count']    = 0;
@@ -206 +385 @@
 
     /**
-     * Show "Download Tax Invoice" button on My Account → Order details.
+     * Return the customer-visible invoice and credit-note documents on an order.
+     *
+     * @return array
+     */
+    private static function get_customer_documents( $order ) {
+        $documents  = [];
+        $invoice_url = esc_url_raw( (string) saudivatpro_wc_get_order_meta( $order, 'invoice_url' ) );
+        if ( $invoice_url ) {
+            $documents[] = [
+                'label' => __( 'Tax Invoice (PDF)', 'saudi-vat-pro-for-woocommerce' ),
+                'url'   => $invoice_url,
+            ];
+        }
+
+        $states = $order->get_meta( '_saudivatpro_wc_refund_states', true );
+        $states = is_array( $states ) ? $states : [];
+        foreach ( $states as $refund_id => $state ) {
+            if ( ! is_array( $state ) ) {
+                continue;
+            }
+            $credit_note_url = isset( $state['pdf_url'] ) && is_string( $state['pdf_url'] ) ? esc_url_raw( $state['pdf_url'] ) : '';
+            if ( ! $credit_note_url || ! absint( $refund_id ) ) {
+                continue;
+            }
+            $documents[] = [
+                /* translators: %d: WooCommerce refund ID. */
+                'label' => sprintf( __( 'Credit Note for Refund #%d (PDF)', 'saudi-vat-pro-for-woocommerce' ), absint( $refund_id ) ),
+                'url'   => $credit_note_url,
+            ];
+        }
+
+        return $documents;
+    }
+
+    /**
+     * Show customer documents on the authorized My Account order details page.
      */
     public static function show_invoice_link( $order ) {
-        $url = saudivatpro_wc_get_order_meta( $order, 'invoice_url' );
-        if ( ! $url ) {
-            return;
-        }
-
-        echo '<section class="woocommerce-order-saudivatpro-invoice" style="margin-top:20px;">';
-        echo '<h2 class="woocommerce-order-details__title">' . esc_html__( 'Tax Invoice', 'saudi-vat-pro-for-woocommerce' ) . '</h2>';
-        echo '<p>' . esc_html__( 'Your ZATCA-compliant tax invoice is ready.', 'saudi-vat-pro-for-woocommerce' ) . '</p>';
-        echo '<a href="' . esc_url( $url ) . '" class="button" download>';
-        echo esc_html__( 'Download Tax Invoice (PDF)', 'saudi-vat-pro-for-woocommerce' );
-        echo '</a>';
+        $documents = self::get_customer_documents( $order );
+        if ( empty( $documents ) ) {
+            return;
+        }
+
+        echo '<section class="woocommerce-order-saudivatpro-documents" style="margin-top:20px;">';
+        echo '<h2 class="woocommerce-order-details__title">' . esc_html__( 'Documents', 'saudi-vat-pro-for-woocommerce' ) . '</h2>';
+        echo '<ul>';
+        foreach ( $documents as $document ) {
+            echo '<li><a href="' . esc_url( $document['url'] ) . '" class="button" download>';
+            echo esc_html( $document['label'] );
+            echo '</a></li>';
+        }
+        echo '</ul>';
         echo '</section>';
     }
@@ -228 +445 @@
     // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed -- $email is unused but required so this matches the 4-argument woocommerce_email_after_order_table hook signature.
     public static function add_invoice_link_to_email( $order, $sent_to_admin, $plain_text, $email ) {
-        $url = saudivatpro_wc_get_order_meta( $order, 'invoice_url' );
-        if ( ! $url ) {
+        if ( $sent_to_admin ) {
+            return;
+        }
+        $documents = self::get_customer_documents( $order );
+        if ( empty( $documents ) ) {
             return;
         }
 
         if ( $plain_text ) {
-            echo "\n" . esc_html__( 'Tax Invoice (ZATCA):', 'saudi-vat-pro-for-woocommerce' ) . ' ' . esc_url( $url ) . "\n";
+            echo "\n" . __( 'Documents:', 'saudi-vat-pro-for-woocommerce' ) . "\n";
+            foreach ( $documents as $document ) {
+                echo wp_strip_all_tags( $document['label'] ) . ': ' . $document['url'] . "\n";
+            }
         } else {
-            echo '<p style="margin:20px 0 0;">';
-            echo '<strong>' . esc_html__( 'Your ZATCA Tax Invoice:', 'saudi-vat-pro-for-woocommerce' ) . '</strong> ';
-            echo '<a href="' . esc_url( $url ) . '">' . esc_html__( 'Download PDF', 'saudi-vat-pro-for-woocommerce' ) . '</a>';
-            echo '</p>';
+            echo '<div style="margin:20px 0 0;">';
+            echo '<strong>' . esc_html__( 'Documents:', 'saudi-vat-pro-for-woocommerce' ) . '</strong>';
+            echo '<ul>';
+            foreach ( $documents as $document ) {
+                echo '<li><a href="' . esc_url( $document['url'] ) . '">' . esc_html( $document['label'] ) . '</a></li>';
+            }
+            echo '</ul>';
+            echo '</div>';
         }
     }

saudi-vat-pro-for-woocommerce/trunk/readme.txt

@@ -4 +4 @@
 Requires at least: 6.0
 Tested up to: 7.1
-Stable tag: 1.0.1
+Stable tag: 1.1.0
 Requires PHP: 8.0
 WC requires at least: 7.0
@@ -11 +11 @@
 License URI: https://www.gnu.org/licenses/gpl-2.0.html
 
-Automatically send paid store orders and refunds to Saudi VAT Pro for electronic invoicing in Saudi Arabia.
+Automatic ZATCA-compliant invoices for every paid order, a customer PDF link, and credit notes on refund — no manual invoicing.
 
 == Description ==
 
-Saudi VAT Pro sends paid orders and refunds to your Saudi VAT Pro WooCommerce integration endpoint. It can collect an optional 15-digit Saudi buyer VAT number for B2B invoices, show a returned PDF link, and submit a credit note for each refund.
+Saudi VAT Pro turns every paid WooCommerce order into a ZATCA-compliant tax invoice automatically. The customer gets a link to download their invoice PDF, and refunds generate a matching credit note — no manual invoicing, no exporting orders to a spreadsheet.
+
+= How it works =
+
+* **Trigger:** as soon as an order's payment is confirmed — either through your payment gateway's payment-complete event, or when the order status changes to Processing or Completed — the plugin sends it to your connected Saudi VAT Pro account.
+* **Customer experience:** with a ZATCA certificate (CSID) enrolled, Saudi VAT Pro generates the invoice signed, hashed, and QR-coded, then submits it to ZATCA for reporting or clearance. The PDF link is returned to the order — and made available to the customer — as soon as that processing finishes, whatever the resulting ZATCA outcome; a rejected submission or a missing certificate is flagged in your Saudi VAT Pro dashboard rather than blocking the order.
+* **Refunds:** when you refund an order, in full or in part, the plugin submits the refunded items to Saudi VAT Pro, which issues a matching ZATCA credit note referencing the original invoice.
+* **B2B vs. B2C:** business buyers can enter their 15-digit Saudi VAT number at checkout to receive a Standard (B2B) tax invoice; buyers who leave it blank get the invoice type you've set as the account default (usually Simplified/B2C, but configurable to Standard) in Saudi VAT Pro.
+
+= Connect your store =
+
+The plugin connects to Saudi VAT Pro using a webhook URL and a secret generated from your Saudi VAT Pro account — there is no API key to manage. Connect your store in two steps, then place a test order:
+
+1. In Saudi VAT Pro, go to Settings → Integrations → WooCommerce and copy the Webhook URL and Webhook Secret.
+2. In WordPress, go to WooCommerce → Settings → Saudi VAT Pro, paste both values, and save.
+
+= ZATCA scope =
+
+This plugin covers ZATCA Phase 2 (Integration Phase) e-invoicing. With a ZATCA certificate (CSID) enrolled in your Saudi VAT Pro account, every invoice is generated as signed, hashed, QR-coded UBL XML, then Simplified (B2C) invoices are reported to ZATCA and Standard (B2B) invoices are submitted for clearance. Without a certificate enrolled, invoices are still generated (with a Phase 1 QR code) but are not signed, reported, or cleared until you enroll one. This plugin does not cover Phase 1-only (generation without reporting) setups as its intended operating mode.
 
 = Requirements =
 
 * WordPress 6.0+, PHP 8.0+, and WooCommerce 7.0+.
-* An active Saudi VAT Pro account at https://saudivatpro.com.
+* An active Saudi VAT Pro account at https://saudivatpro.com with a ZATCA certificate (CSID) enrolled — without one, invoices are still generated (with a Phase 1 QR code) but are not signed, reported, or cleared.
 * A unique HTTPS WooCommerce webhook URL and its secret from Saudi VAT Pro → Settings → Integrations → WooCommerce.
 
@@ -32 +50 @@
 = Configuration and usage =
 
-The plugin submits paid orders to Saudi VAT Pro for electronic invoicing and stores the returned invoice identifier and PDF link on the WooCommerce order. When a refund is created, the plugin submits the refunded items to create a matching credit note. Failed submissions can be retried from the order screen.
+The plugin submits paid orders to Saudi VAT Pro for electronic invoicing and stores the returned invoice identifier and PDF link on the WooCommerce order. When a refund is created, the plugin submits the refunded items to create a matching credit note. If the connection to Saudi VAT Pro itself fails before an invoice is created (for example a timeout), the order is retried automatically up to three times, several minutes apart, and can also be retried manually at any time from the order screen using the "Retry Saudi VAT Pro submission" order action. Once an invoice has been created for an order, that order won't be resubmitted from WooCommerce; a ZATCA rejection or a missing certificate at that point is resolved from your Saudi VAT Pro dashboard.
 
 The classic shortcode checkout is supported. WooCommerce block checkout does not currently expose this plugin's optional VAT field; collect the VAT number by another compatible checkout extension until native block integration is released.
@@ -39 +57 @@
 
 This release supports WordPress 6.0 or newer, PHP 8.0 or newer, and WooCommerce 7.0 or newer. It supports WooCommerce HPOS. The classic shortcode checkout is supported; the optional VAT field is not currently available in WooCommerce block checkout.
+
+== Frequently Asked Questions ==
+
+= What does this plugin actually do? =
+
+It watches your WooCommerce orders. When an order is paid, it sends the order to your Saudi VAT Pro account, which creates the invoice and — once a ZATCA certificate is enrolled — signs it and reports or clears it with ZATCA, then returns a PDF link you can share with the customer. When you refund an order, it does the same to create a matching credit note.
+
+= Are invoices generated on my WordPress server, or by the Saudi VAT Pro service? =
+
+By the Saudi VAT Pro service. This plugin only collects order and refund data and sends it, over your configured webhook, to your Saudi VAT Pro account. Invoice generation, XML signing, and ZATCA submission all happen there — none of that logic runs on your WordPress site.
+
+= Are refunds supported? =
+
+Yes, both full and partial refunds. When you create a refund in WooCommerce, the plugin sends the refunded line items to Saudi VAT Pro, which issues a ZATCA credit note referencing the original invoice for that exact amount.
+
+= What ZATCA phase and scope does this cover? =
+
+ZATCA Phase 2 (Integration Phase). With a ZATCA certificate (CSID) enrolled, every invoice is generated as signed, hashed, QR-coded UBL XML, then Simplified (B2C) invoices are reported to ZATCA and Standard (B2B) invoices are submitted for clearance. Without a certificate enrolled, invoices are still generated with a Phase 1 QR code but are not signed, reported, or cleared. It does not cover Phase 1-only (generation without reporting) setups as its intended operating mode. The PDF link is returned to the order as soon as this processing finishes, whatever the resulting outcome — a rejected submission or a missing certificate is flagged in your dashboard instead of failing silently.
+
+= What is the difference between a Simplified and a Standard (B2B) invoice? =
+
+A Simplified invoice is issued to a consumer buyer and reported to ZATCA. A Standard (B2B) invoice is issued to a business buyer who provides their 15-digit Saudi VAT number at checkout, and it is submitted to ZATCA for clearance instead of reporting. Enable the optional VAT number field in the plugin settings so business buyers can request a Standard invoice; orders without a VAT number get whichever invoice type you've set as the account default in Saudi VAT Pro (usually Simplified, but this is configurable to Standard).
+
+= What happens if a submission to ZATCA fails? =
+
+It depends on where the failure happens. If the connection to Saudi VAT Pro itself fails before an invoice is created (for example a timeout), the plugin retries automatically up to three times, several minutes apart, and you can also retry manually using the "Retry Saudi VAT Pro submission" action on the order screen — that action only resends orders that don't have an invoice yet. If Saudi VAT Pro creates the invoice but ZATCA then rejects it, or no certificate is enrolled yet, the order already has its invoice ID and PDF; that failure is flagged in your Saudi VAT Pro dashboard, where you fix and resubmit it.
+
+= Does this work with WooCommerce block checkout? =
+
+Not yet for the optional VAT number field — it currently only appears on the classic shortcode checkout. Orders placed through block checkout are still invoiced automatically using your account's default invoice type; business buyers checking out through blocks should use another compatible field to submit their VAT number until native block support ships.
 
 == Privacy Policy ==
@@ -50 +98 @@
 == Screenshots ==
 
-No screenshots are included in this release.
+1. The Saudi VAT Pro settings screen in WooCommerce → Settings, showing the Webhook URL and Webhook Secret connection fields.
+2. The WooCommerce admin order screen showing the buyer's VAT number and the "Retry Saudi VAT Pro submission" order action.
+3. The customer-facing order details page "Documents" section, showing the downloadable Tax Invoice PDF link.
+4. The customer-facing order details page "Documents" section after a refund, showing the downloadable Credit Note PDF link.
 
 == Changelog ==
+
+= 1.1.0 =
+* Added a "Test Connection" button on Settings that verifies the webhook URL and secret without creating a test invoice or touching a live order.
+* Added a Saudi VAT Pro status panel on the order edit screen (classic and HPOS) showing submission status, invoice ID, PDF link, and last error, with a retry button.
+* Rewrote the listing copy to lead with the merchant outcome — automatic ZATCA-compliant invoices, customer PDF access, and refund credit notes — instead of the webhook mechanism.
+* Documented the exact ZATCA Phase 2 scope, including the difference between behavior with and without a ZATCA certificate (CSID) enrolled, and clarified that the PDF link is returned as soon as processing finishes, independent of the resulting outcome.
+* Corrected the documented trigger to match the plugin's actual hooks (payment complete, or order status moving to Processing/Completed).
+* Corrected the documented retry behavior: automatic and manual retries only resend orders that have not yet received an invoice; a ZATCA rejection or missing certificate after that point is resolved from the Saudi VAT Pro dashboard.
+* Corrected the documented behavior for orders without a buyer VAT number: they use the account's configured default invoice type rather than always being Simplified.
+* Added a Frequently Asked Questions section.
+* Added screenshot captions describing the settings, admin order actions, and customer-facing document screens that exist today (image capture tracked separately).
 
 = 1.0.1 =

saudi-vat-pro-for-woocommerce/trunk/saudi-vat-pro-woocommerce.php

@@ -3 +3 @@
  * Plugin Name:       Saudi VAT Pro for WooCommerce
  * Plugin URI:        https://saudivatpro.com
- * Description:       Automatic ZATCA Phase 2 e-invoicing for WooCommerce. Every paid order generates a ZATCA-compliant invoice, B2B buyers enter their VAT number at checkout, and refunds create credit notes — all without lifting a finger.
- * Version:           1.0.1
+ * Description:       Every paid WooCommerce order becomes a ZATCA-compliant invoice automatically — customers get a downloadable PDF, and refunds get a matching credit note. B2B buyers enter their VAT number at checkout. Powered by Saudi VAT Pro's ZATCA Phase 2 reporting and clearance.
+ * Version:           1.1.0
  * Author:            Saudi VAT Pro
  * License:           GPL v2 or later
@@ -20 +20 @@
 }
 
-define( 'SAUDIVATPRO_WC_VERSION', '1.0.1' );
+define( 'SAUDIVATPRO_WC_VERSION', '1.1.0' );
 define( 'SAUDIVATPRO_WC_PLUGIN_DIR', plugin_dir_path( __FILE__ ) );
 define( 'SAUDIVATPRO_WC_PLUGIN_URL', plugin_dir_url( __FILE__ ) );