Waffy Escrow Payment for WooCommerce
Add Waffy escrow checkout to your WordPress store. Upload one zip from the WP Admin, then configure everything under WooCommerce → Settings → Payments.
waffy-woocommerceVersion 0.3.0License GPL-2.0-or-laterNo command line required
Unlike the Magento 2 extension, the whole install is done from the WordPress admin. The Waffy PHP SDK and every PHP dependency are bundled inside the zip (under sdk/ and vendor/) — a WordPress site never runs Composer, so there is nothing to fetch. Uploading the zip installs everything the plugin needs.
1. Requirements
Compatible with WordPress 6.0+ and WooCommerce 8.0+ on PHP 8.1+. Supports both the classic and the Blocks (Gutenberg) checkout, and High-Performance Order Storage (HPOS).
| Requirement | Value |
|---|---|
| WordPress | 6.0 or higher |
| WooCommerce | 8.0 or higher (active) |
| PHP | 8.1 or higher |
| PHP extensions | ext-json, ext-openssl (standard on any WooCommerce host) |
| Permalinks | Plain works, but any other structure is recommended — see 3.2 |
| Access | WordPress admin with the install_plugins capability (Administrator) |
| Waffy credentials | Client ID, Client Secret, admin email & password — request from support@waffyapp.com |
2. Installation from the zip
The admin uploader (Option A) is the recommended path. Use SFTP only if the uploader is disabled.
2.1 Get the zip
Download waffy-woocommerce.zip — the permanent link below always resolves to the newest release, so it never needs updating. The zip is the only install path; WooCommerce has no Composer equivalent for merchants.
Ignore "Source code (zip)" and "(tar.gz)". GitHub attaches those to every release automatically and they look like the right file. They are archives of the distribution repo, not the plugin — WordPress will reject them.
Each release attaches the plugin twice, byte-identical — waffy-woocommerce.zip and waffy-woocommerce-<version>.zip. Either one installs the same plugin. Take the version-less copy unless you need to pin a specific version.
https://github.com/WaffyApp/waffy-woocommerce-dist/releases/latest/download/waffy-woocommerce.zipA2.2 Upload from WP AdminRecommended · no file access
- In WP Admin, go to Plugins → Add New → Upload Plugin.
- Click Choose File, select the
waffy-woocommercezip you downloaded, then Install Now. - Click Activate Plugin.
wp_waffy_tokens) and schedules its background token refresh."The uploaded file exceeds the upload_max_filesize directive" — the zip is roughly 700 KB, well under any normal limit, but some hosts cap uploads very low. If you hit this, use the SFTP method below or ask your host to raise upload_max_filesize.
B2.3 Upload by SFTP / SSHUploader disabled
Use this if the admin uploader is disabled or you prefer direct file access.
- Unzip the file locally. It contains a single top-level folder,
waffy-woocommerce/. - Upload that whole folder into
wp-content/plugins/so you end up with the path below. - In WP Admin go to Plugins, find Waffy Escrow Payment for WooCommerce, and click Activate.
wp-content/plugins/waffy-woocommerce/waffy-woocommerce.php2.4 Verify it activated
Go to Plugins — the entry should show as active. If something is missing, what you see depends on which requirement it is:
- PHP below 8.1, or WordPress below 6.0 — WordPress refuses to activate the plugin at all and shows its own error. This is enforced by WordPress from the plugin header, not by the plugin.
- WooCommerce not installed or not active — the plugin does activate, but it shows an admin notice and does not register the payment method. Install or activate WooCommerce and the gateway appears.
- WooCommerce older than 8.0 — nothing blocks this. The plugin loads normally, and WooCommerce may flag the version mismatch on the Plugins screen. Treat 8.0 as the supported floor, not an enforced one.
3. Configuration
Go to WooCommerce → Settings → Payments → Waffy Escrow Payment.
3.1 Connect your Waffy account
- Set Environment to Sandbox first (no real money). Sandbox and Production have separate credential fields, so you can fill both and switch without re-entering anything.
- Enter the Client ID, Client Secret, Client Admin Email, and Client Admin Password provided by Waffy.
- Merchant Phone Number (required) — E.164 format, e.g.
+966555555555. Identifies the merchant as the PROVIDER party on every escrow contract. - Broker Phone Number (optional) — leave empty if no broker is involved.
3.2 Register your webhook
- Copy the Webhook URL shown in the settings — it looks like:
https://your-store.com/wp-json/waffy/v1/webhook- Send that URL to the Waffy team so they register your store for order status updates. Order status will never update until this is done.
- Webhook Allowed IPs (optional) — leave empty to allow all. To restrict, enter one IP or CIDR range per line (e.g.
203.0.113.0/24); anything else gets a 403. Ask Waffy for their server IPs before turning this on.
Permalinks matter. The webhook is a WordPress REST route. If Settings → Permalinks is set to Plain, the pretty /wp-json/ URL does not work and the settings page shows the fallback ?rest_route=/waffy/v1/webhook form instead. Either is fine as long as you send Waffy exactly the URL the settings page displays — but any non-Plain permalink structure is recommended.
3.3 Contract settings
Match these to how you sell:
| Setting | Meaning |
|---|---|
| Return Policy | No Return or Returnable |
| Return Fee Payee | Who pays the return fee — Merchant (Provider) or Customer |
| Is Deliverable | Product requires physical delivery |
| Is Inspectable | Buyer may inspect goods before funds are released |
| Is Acceptable (by Customer) | Buyer explicitly accepts/rejects before release |
| Milestone Deadline (days) | Days from order date until the payment milestone expires (default 30) |
| Contract Category | Category shown to the buyer on the Waffy page (e.g. Services, Electronics, Food) |
3.4 Storefront settings
- Title — what buyers see at checkout (default "Pay with Waffy").
- Description — the explanatory line under the title at checkout.
- Tick Enable Waffy Escrow Payment.
- Click Save changes.
Leave everything under Advanced empty. Those URL overrides are derived automatically from the Environment setting and exist only for pointing at a custom or staging Waffy server.
4. Test in Sandbox
- Place a test order on the storefront and choose Pay with Waffy at checkout.
- You are redirected to the Waffy-hosted payment page. The order is created in WooCommerce as On hold at this point.
- Complete the payment on the Waffy page.
- Confirm the order moves to Processing once Waffy's webhook arrives, and that an order note records the Waffy status.
Test both the classic and the Blocks checkout if your store offers both.
5. Go Live
- Set Environment → Production.
- Enter your Production Client ID, Client Secret, Admin Email & Password.
- If your store URL changed (e.g. staging → live domain), re-share the new Webhook URL with Waffy — it is derived from the site URL.
- Click Save changes.
- Place one small real order to confirm end to end.
6. Updating to a new version
Settings and cached tokens survive an update — they live in WordPress options and the wp_waffy_tokens table, not in the plugin folder.
Via the admin uploader
Go to Plugins → Add New → Upload Plugin, choose the newer zip, and click Install Now. WordPress detects the existing copy and offers Replace current with uploaded — take it.
Via SFTP
Deactivate the plugin, delete the wp-content/plugins/waffy-woocommerce/ folder, upload the new one, reactivate. Do not merge the new folder over the old one — files removed in the new version would linger and can break the plugin.
Do not use "Delete" in the Plugins screen to update. Deleting runs the uninstall routine, which wipes your credentials and token cache.
7. Uninstalling
- Deactivate stops the plugin and cancels its background token refresh. Nothing is deleted; reactivating restores the previous setup.
- Delete (after deactivating) additionally removes the
wp_waffy_tokenstable, the gateway settings, and the token-warmer bookkeeping.
_waffy_milestone_id, _waffy_contract_id) are deliberately kept as part of those orders' historical record.8. Troubleshooting
| Symptom | Fix |
|---|---|
| Plugin won’t activate | Check the admin notice — usually WooCommerce inactive/too old, or PHP below 8.1 |
| "Waffy" not shown at checkout | Confirm Enable Waffy Escrow Payment is ticked and the settings were saved |
| Order stuck on On hold | The webhook never arrived. Confirm the Webhook URL was registered with Waffy and isn't blocked by the IP allowlist or a firewall/WAF |
| Webhook returns 403 | The caller's IP isn't in Webhook Allowed IPs. Clear the field to allow all, or add Waffy's IPs |
| Webhook returns 404 | Permalinks are set to Plain, or a security plugin is blocking /wp-json/. See 3.2 |
| Checkout is slow on the first order | Token warm-up hasn’t run yet. Harmless — the SDK fetches what is missing. Confirm WP-Cron is working |
| Credentials seem not to save | Secret/password fields intentionally display blank after saving. Re-entering is only needed to change them |
| Admin notice: "stored … could not be read" | The site's WordPress security keys/salts changed (common after a migration or a host security reset), so the encrypted secrets can't be decrypted. Re-enter and save the credentials |
The call log
Every Waffy call is logged with its outcome and duration under WooCommerce → Status → Logs, source waffy. Start here for anything unexplained — it shows each checkout step, whether tokens were cached or fetched, and the webhook decisions.
wp-content/uploads/wc-logs/waffy-*.logstatus=cached means the call never left the server — the token was already in the cache. A healthy setup shows the four auth calls under warm-up/login-prefetch, and only the contract calls under checkout.
Support
Email support@waffyapp.com for credentials, webhook registration, or setup help.