FISHBSE LISTINGS — USER GUIDE — VERSION 1.5.1

SETUP
1. Register with FishBSE and verify your email, then complete Stripe seller verification (card payments and payouts enabled).
   The separate FishBSE Verified badge is not required and cannot substitute for Stripe verification.
   FishBSE staff may disable the integration globally or for your seller account. Existing API keys and embedded sign-ins are also checked, not only new connections.
   Each feed request reports your WordPress home URL. FishBSE stores its origin, your seller ID, first/last request times and request count for the staff website list. Display-only sites report this information too.
2. Open https://fishbse.com/dashboard.php#wordpress-integration.
3. Generate an API key and copy it privately. The full key is revealed once.
4. In WordPress (6.3 or newer, PHP 7.4 or newer), open Plugins > Add New > Upload Plugin. Upload fishbse-listings.zip, install and activate. To update, choose Replace current with uploaded; do not uninstall first if you want to retain settings.
5. Open Settings > FishBSE Listings or its Settings link in Installed Plugins.
6. Paste the key, choose your display settings and save. A successful connection confirms authentication. The “API key saved” badge only indicates stored credentials; it is not a live health check.

DISPLAY SETTINGS
Choose Cards, List or Compact, and light, dark or inherited theme colors. Select all listings, auctions only, for-sale listings or wanted listings. Optionally filter by category. Set the maximum number of items from 1 to 24, newest first. The count is the combined maximum when displaying both listings and auctions.
The admin preview uses actual saved feed data. Layout/color changes preview immediately; save to apply category, listing type and count changes. A blank key field preserves the stored key. To disconnect, check Disconnect this website and save.

DRAG-AND-DROP BLOCK
Open a page or post in the WordPress block editor. Click + and search FishBSE Listings (look for the FishBSE fish icon). Insert it and drag the block to its desired position, or use the editor's move arrows. It can sit inside Groups and Columns. Select the block to use its sidebar controls. Enable Set listing width in the block sidebar to choose 240–1000 pixels per listing. Turn it off to restore automatic sizing. Cards wrap and shrink to fit smaller screens; this is separate from the toolbar’s overall block alignment. Each block can override layout and colors; listing filters and count stay site-wide. Wide/full alignment and spacing require theme support. Publish or update the page.
With a block theme, use Appearance > Editor to place the block in an editable template. The editor preview is a snapshot; use Refresh preview after listing changes. Reload the editor after changing the connection or site-wide settings.

SHORTCODE AND OTHER BUILDERS
Use [fishbse_listings] inside a Shortcode block or a builder's supported shortcode widget. This version does not provide a dedicated Elementor, Divi or other builder widget.
PHP templates can use: <?php echo do_shortcode('[fishbse_listings]'); ?>
Use a child theme for template changes. Themes must call wp_head() and wp_footer().

WHAT IT CAN DO
- Review and submit purchases/bids inside a WordPress panel, with a FishBSE sign-in popup and Stripe embedded payment/card verification.
- Read the connected seller's eligible public listings and live/scheduled auctions.
- Display images, titles, locations, prices, current/starting bids, bid counts and auction deadlines on published pages.
- Show aggregate pending/accepted trade-request counts for regular listings.
- Refresh visible published pages every 15 seconds, rechecking access with FishBSE on each refresh.
- Reflect auction extensions and remove listings that become unavailable.
- Clear stale cards after connection errors. Hidden browser tabs pause polling.

WHAT IT CANNOT DO
- Manage refunds, disputes, shipping or later auction winner-payment recovery inside WordPress. Those tools remain on FishBSE.
- Create/edit listings, accept negotiated offers or manage orders inside WordPress.
- Import WordPress posts or WooCommerce products, or synchronize orders/customers.
- Reveal private messages, bidder identities, reserve prices or private contact data.
- Display negotiated offer amounts: regular listings have request counts, not an offer-price feed.
- Show another seller's inventory or hidden/staged/unavailable listings.
- Push instantaneous updates or apply different listing filters to separate blocks.
- Operate as a background WordPress cron job. FishBSE's existing auction scheduler/finalizer remains necessary.

EMBEDDED PURCHASES AND AUCTION BIDS
1. Embedded transactions require enabled FishBSE service access. Contact FishBSE support if purchases or bids are unavailable. Existing API keys and listing blocks remain supported.
2. In Settings > FishBSE Listings, enable transaction buttons and choose Stay on this website. Open FishBSE preserves the previous redirect flow if you prefer it.
3. Use HTTPS. For Local WordPress, enable SSL, trust its certificate and open https://fishbse.local rather than http://fishbse.local. The WordPress Site Address must match the exact public origin, including www and port. localhost is accepted for development by browsers.
4. Test on the published page using a separate buyer account. The editor only shows disabled button previews. Buyers cannot buy or bid on their own inventory.
5. Click Buy now or Place bid to open the panel. Connect with FishBSE opens a popup for normal FishBSE sign-in/MFA and explicit website approval. The seller's WordPress page remains open. WordPress never collects the FishBSE password.
6. Purchases: review the description, seller, unit/lot, shipping or pickup, authoritative total, applicable terms and optional DOA coverage. Accept the terms, then continue to the Stripe payment form inside the panel. Card data goes directly to Stripe. After completion, FishBSE verifies the order before the panel says Payment confirmed. If it says processing or unconfirmed, check status or your FishBSE Orders rather than paying again.
7. Auctions: review the description, all dated seller clarifications, deadline, shipping or pickup and current minimum bid. Enter an amount and accept the binding-bid authorization and pickup acknowledgment when applicable. Confirm binding bid submits through FishBSE. If card/address verification is required, it appears inside the panel; completing verification finishes that same bid. A bid can be outbid and is not an immediate purchase.
8. The open bid review refreshes every 15 seconds. New seller clarifications reset consent and require review again. The backend checks the disclosure revision and minimum bid under its existing lock even between refreshes.
9. Cancel reserved checkout explicitly cancels an unpaid purchase reservation through FishBSE's existing Stripe verification rules. Closing the panel does not cancel a hold, payment or accepted bid. A checkout already created in redirect mode must be explicitly canceled before a new embedded checkout; the old payment session is never silently replaced.
10. Buyer connections last 30 minutes and are limited to one listing/auction and one website origin. They are kept in browser memory, not localStorage, WordPress options or page HTML. Reloading requires reconnecting. Disconnect revokes that connection. Key rotation/revocation, buyer authentication-version changes, account restrictions and MFA enrollment changes invalidate connections. Existing bids/orders remain valid.
11. Listings still refresh every 15 seconds with access rechecked on each refresh. WordPress does not keep a separate stock or order database. No additional WordPress cron job is required.

LIMITATIONS AND TROUBLESHOOTING
- Checkout uses embedded card payment and disables redirect-based payment methods. A bank may still require cardholder authentication. Additional wallet support depends on Stripe configuration and domain registration.
- Order management, refunds, disputes, shipping and later auction winner-payment recovery remain on FishBSE. There is no WooCommerce cart/import, guest bidding, negotiated-offer acceptance or private-message synchronization.
- Enable popups for FishBSE sign-in. If an external login provider detaches the popup, close it and connect again after signing in. If the popup reports connection but the panel does not continue, verify that WordPress's configured Site Address matches the page's actual origin.
- WordPress security/CSP settings must allow Stripe.js and its required payment frames, and browser connections to https://fishbse.com/wordpress_embed_api.php. A strict Cross-Origin-Opener-Policy on WordPress must allow the FishBSE popup relationship.
- Cloudflare must not challenge JSON requests or preflights to /wordpress_embed_api.php. If an event confirms a challenge, create a separate exact-path exception for this endpoint's POST and OPTIONS methods and the responsible challenge component. Keep normal rate limiting. Never broadly disable checkout/bid security.
- Expired navigation links require refreshing the listings. Revoking the seller API key invalidates new sign-ins and current buyer grants. The seller API key itself never authorizes purchases or bids.
- Prices and availability are checked again by FishBSE; sold items, expired auctions, stale disclosures and unsupported shipping configurations can be refused after a card was first shown on WordPress.

KEY MANAGEMENT
The FishBSE database stores the key hash. The separate dashboard fix redirects after generation and uses one-use form tokens, preventing page refresh or repeated submission from generating another key. A raw key is passed through a single-read session flash with a five-minute reveal deadline. Once consumed, it is not shown again. Refreshing keeps the active key unchanged. Generate a replacement only if you intend to replace it; all websites using the old key must be updated. Revocation invalidates the key everywhere. Disconnect in WordPress removes only that installation's saved key.
The plugin stores its key in the WordPress database, never in page source, editor attributes or browser requests. Protect the database and backups. Multiple websites may use one key, sharing 120 authenticated requests/minute. Configure WordPress multisite installations individually.

TROUBLESHOOTING
Cloudflare challenge: identify the matching event's ruleset. The machine API /wordpress_listings_api.php must be exempt from the responsible browser challenge. Super Bot Fight Mode uses the http_request_sbfm skip phase; basic Bot Fight Mode cannot be skipped with custom rules. Keep the exception limited to the exact host, GET method and path. An HTTP challenge has not validated the API key.
Invalid key: use the current dashboard key and confirm the FishBSE account is active, email-verified and Stripe-verified.
Empty feed: try All listings and All categories and verify ownership/active state on FishBSE.
Missing block: activate the plugin, use WordPress 6.3+, reload the editor, and check allowed-block restrictions. Classic editors/builders can use the shortcode.
Stale feed: allow JavaScript and exclude the feed from CDN/proxy caching. Check the FishBSE endpoint and connection.
Password notice: WordPress's auto-generated-password reminder is separate from this integration.

MASKED CARD DISPLAY (1.5.0)
After buyer sign-in, auction reviews show the saved card for that seller (brand and last four digits). Purchase card selection stays inside Stripe's secure form; the verified payment result shows the card used when available. An auction card is not automatically selected for purchases. Full card numbers and CVCs are never returned to this plugin. Card summaries are not included in the public listing feed or saved in WordPress options. A missing summary does not mean a verified payment failed.

OPTIONAL FOOTER CREDIT (1.5.1)
The FishBSE footer logo and View on FishBSE link are disabled by default. Enable the checkbox in Display settings only if you want this credit on public pages. Listing links and transaction controls remain available without it.

EXTERNAL SERVICE POLICIES
Review the External service and privacy section in readme.txt before connecting. FishBSE: https://fishbse.com/terms.php and https://fishbse.com/privacy.php. Stripe: https://stripe.com/legal/ssa and https://stripe.com/privacy.
