Bitsnap for WooCommerce

Accept BLIK, cards, bank transfers and more in WooCommerce through Bitsnap. The buyer pays on a secure Bitsnap page and returns to your shop. Payment status, test mode and refunds work end to end.

• Works with the Cart and Checkout Blocks and with the classic (shortcode) checkout.
• Compatible with High-Performance Order Storage (HPOS).
• Connect with Bitsnap (OAuth with PKCE), or a manual API key. Separate test and live connections.
• Refunds from the WooCommerce order screen, for gateways that can refund through Bitsnap.
• Reads the NIP from the invoice plugin you already use. It adds no checkout field.
• Polish and English.

Requires WordPress 6.5+, PHP 7.4+ and WooCommerce 9.0+. Licence: GPLv2 or later.

Install

This plugin is not in the WordPress.org plugin directory. Install it from a zip:

1. Download bitsnap-for-woocommerce.zip (always the newest release). In wp-admin open Plugins > Add New > Upload Plugin, choose the zip, install and activate it. WooCommerce must be active.
2. In WooCommerce, open Settings > Payments > Bitsnap and click Connect with Bitsnap under Test credentials. Sign in to Bitsnap, choose a project and approve. The plugin registers the webhook and stores its secret. This needs an https address for your shop (localhost works for development).
3. Or set it up by hand: in Bitsnap, create an API key (test first) with the permissions checkout:create, orders:read and refunds:write, and customers:pii to send buyer details. Paste it under Test credentials, save, and click Register webhook (needs webhooks:write). Without that permission, create a webhook in Bitsnap for the URL shown on the settings page and paste its whsec_ secret.
4. Place a test order. When it works, connect the live environment the same way and turn Test mode off.

If an environment has both a connection and an API key, the connection is used. Disconnect deletes the webhook, revokes the access and clears that environment only.

Updates

New versions are published as GitHub releases and appear in wp-admin (Dashboard > Updates, Plugins) like any other plugin update, with automatic updates if you turn them on. The plugin uses Plugin Update Checker (MIT) and installs the release asset bitsnap-for-woocommerce.zip, never the source archive. The checks run only in the admin, cron and WP-CLI and contact api.github.com and github.com (see "External services" in readme.txt).

To turn update checks off, add this to wp-config.php, or return false from the bitsnap_wc_enable_updates filter:

define( 'BITSNAP_WC_DISABLE_UPDATES', true );

How it works

See docs/ARCHITECTURE.md for the flow, the API contract with Bitsnap, webhook handling and the response codes.

Develop

You need Docker (PHP and Composer are not required on the host) and Node 20+.

# PHP dependencies (dev tools, plus the one runtime package, Plugin Update Checker)
docker run --rm -v "$PWD":/app -w /app composer:2 install

# Unit tests and coding standards
docker run --rm -v "$PWD":/app -w /app php:8.3-cli vendor/bin/phpunit
docker run --rm -v "$PWD":/app -w /app php:8.3-cli vendor/bin/phpcs

# Block checkout script
npm install
npm run build        # or: npm start

# A local WordPress with WooCommerce, with the plugin mounted
npm run env:start    # http://localhost:8888, admin / password

# Smoke test inside that site: a real WooCommerce, with the Bitsnap API mocked.
# It creates orders, pays them with signed webhooks, refunds, and checks Blocks registration.
npm run test:smoke

If port 8888 is taken, start wp-env with WP_ENV_PORT=18888 WP_ENV_TESTS_PORT=18889. Run npx wp-env destroy when you are done.

If you have PHP and Composer installed, composer install, composer test and composer lint do the same.

The plugin source is in src/ and assets/js/blocks/. The compiled script in build/ is generated by npm run build, is not committed, and is included in release zips. The one runtime dependency, Plugin Update Checker, is installed by Composer into vendor/ and shipped in the zip (composer install --no-dev).

Release

1. Bump the version in bitsnap-for-woocommerce.php (header and BITSNAP_WC_VERSION), readme.txt (Stable tag, changelog, upgrade notice) and package.json.
2. Push a tag that equals the version, such as v0.2.0.

The Release workflow checks that the tag and all three versions agree, builds the block script and translations, assembles the production plugin (.distignore plus composer install --no-dev, see bin/build-zip.sh) and publishes a GitHub release with a single asset named bitsnap-for-woocommerce.zip. The release notes come from the matching readme.txt changelog section. Because the file name has no version, this address always serves the newest build: https://github.com/emmems/bitsnap-woocommerce/releases/latest/download/bitsnap-for-woocommerce.zip. Installed sites pick the release up through the update checker.

Run the workflow by hand (Actions > Release > Run workflow) to build the zip as a workflow artifact without publishing. To build it locally: npm ci && npm run build && bash bin/build-mo.sh && bash bin/build-zip.sh (needs rsync, zip and Composer or Docker); the result is dist/bitsnap-for-woocommerce.zip.

Contributing and security

See CONTRIBUTING.md and SECURITY.md.