Black Bean Shop — Getting started

Black Bean Shop — Getting started#

1. Prerequisites#

1. Install and activate Black Bean Tables
2. Seed + sync shop tables if prompted (Tables → Settings / Structure)
3. Activate Black Bean Shop
4. Flush permalinks (Settings → Permalinks → Save)

2. Configure payments#

PayPal (optional)#

1. Open Shop → Settings
2. Enable PayPal Checkout and Show PayPal at checkout as needed
3. Enter PayPal client ID / secret (sandbox or live)
4. Save and register the webhook URL shown in settings (live mode):
   • POST /wp-json/blackbean/v1/shop/paypal-webhook
   • Subscribe to CHECKOUT.ORDER.APPROVED and PAYMENT.CAPTURE.COMPLETED

MoMo (optional)#

1. Open Shop → Settings → MoMo
2. Enable MoMo Checkout and Show MoMo at checkout as needed
3. Enter Partner Code, Access Key, and Secret Key (sandbox or live)
4. Set a USD → VND fallback rate (used when the exchange-rate API is unavailable)
5. Register the IPN URL in the MoMo merchant portal:
   • POST /wp-json/blackbean/v1/shop/momo-ipn

You can enable PayPal only, MoMo only, or both. Checkout shows a selector when more than one gateway is enabled and visible.

Store prices remain in USD. MoMo checkout converts the order total to integer VND using Open ExchangeRate-API (cached 12 hours) with admin fallback.

3. Create a product#

1. Shop → Products → Add product
2. Set title, price, digital flag
3. Attach a download file (Media ID) or external download URL
4. Optional license: prefix + max activations
5. For plugin updates: fill Auto-updates (slug, version, requires WP/PHP)

4. Test the storefront#

1. Visit /products/ on the front end
2. Add to cart → checkout
3. Choose PayPal or MoMo (if both are enabled)
4. Complete payment in sandbox
5. Confirm order email includes license key + download link

5. License a customer site#

1. Copy the license key from the order email or Shop → Licenses
2. On the customer WordPress site, open the product’s License settings
3. Activate the key
4. Dashboard → Updates will show new versions when you publish them

6. Publish a new plugin version#

# Build ZIP
npm run release:full --prefix wp-content/plugins/blackbean-forms

# Publish to shop registry (optional automation)
node scripts/publish-release.mjs blackbean-forms --product-id=N --apply

Or manually: upload ZIP to Media → set product Download file → bump Latest version under Auto-updates.

7. Verify versions#

• Shop → Versions — code vs shop registry
• Or: composer versions / composer versions:diff from the site root

8. Verify product indexing#

1. Open /bb-shop-sitemap.xml and confirm the catalog and published products are listed
2. With Rank Math active, open /sitemap_index.xml and confirm it references /bb-shop-sitemap.xml
3. After deploying a new sitemap rewrite, save Settings → Permalinks once
4. If Rank Math still serves a cached index, save Rank Math → Sitemap Settings

Troubleshooting#