Magento 2 · Adobe Commerce

Waffy Escrow Payment for Magento 2

Add Waffy escrow checkout to your Magento Open Source or Adobe Commerce store. Install once from the command line, then configure everything from the Admin panel.

Package waffy/module-paymentModule Waffy_PaymentVersion 0.6.0License OSL-3.0

View on Packagist Get Sandbox Credentials

The Waffy PHP SDK is bundled inside the extension

It ships under the extension's Sdk/ directory. There is no external Composer dependency to add and nothing to fetch from Packagist separately — installing the extension installs everything it needs.

1. Requirements

Compatible with Adobe Commerce (Cloud & on-premises) and Magento Open Source 2.4.x, on PHP 8.1+.

Requirement	Value
Magento / Adobe Commerce	2.4.x
PHP	8.1 or higher
PHP extensions	ext-json, ext-openssl (standard on any Magento host)
Access	SSH / command-line access to the store
Waffy credentials	Client ID, Client Secret, admin email & password — request from support@waffyapp.com

Why the command line? Since Magento 2.4.0 the admin "Web Setup Wizard" was removed, so all extensions on both Adobe Commerce and Magento Open Source are installed from the command line. This is a one-time technical step (done by your developer or hosting provider). Everything after installation is configured from the Admin panel — no commands needed.

2. Installation

Pick the path that matches your store. Packagist (Option A) is the simplest and needs no access keys.

A
PackagistRecommended · no access keys

Works on Adobe Commerce (Cloud & on-premises) and Magento Open Source with no Adobe account and no repository configuration. Run from the Magento root.

composer require waffy/module-payment
bin/magento module:enable Waffy_Payment
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

Pin an exact version if you prefer: composer require waffy/module-payment:0.6.0

On Adobe Commerce Cloud: run the composer require locally, then commit composer.json + composer.lock and git push. The Cloud build/deploy pipeline runs the bin/magento steps automatically — you don't run them by hand.

B
Adobe Commerce MarketplaceOfficial channel · requires access keys

Downloads from Adobe's private Composer server (repo.magento.com), which requires access keys — every merchant needs their own, including Magento Open Source users. They are free to generate.

1. Get the keys

Sign in to the Adobe Commerce Marketplace (a free account is enough — no paid licence required).
Go to Your name → My Profile → Access Keys.
Click Create A New Access Key and give it a name.
Use the Public Key as the Composer username and the Private Key as the password.

2. Give the keys to Composer

# Run from the Magento root. Replace with your own keys.
composer config --global http-basic.repo.magento.com <PUBLIC_KEY> <PRIVATE_KEY>

This writes to ~/.composer/auth.json. To keep them per-project, drop --global — Composer then writes auth.json in the project root. Do not commit that file to Git.

3. Install

Confirm the extension is listed under My Profile → My Purchases, then run:

composer require waffy/module-payment:0.6.0
bin/magento module:enable Waffy_Payment
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

C
Manual install from the ZIPOffline / no Composer

Use this for offline or air-gapped installs, or when Composer isn't available. Download waffy-module-payment.zip from GitHub Releases. It bundles the frontend assets under view/, so the file set is identical to the Composer install.

Download latest zip Releases page

Ignore "Source code (zip)" and "(tar.gz)". GitHub attaches those to every release automatically. They wrap everything in a waffy-magento2-<version>/ folder, so unzipping one into app/code/Waffy/Payment leaves Magento unable to find the module. Take the waffy-module-payment-<version>.zip asset.

# From the Magento root
curl -LO https://github.com/WaffyApp/waffy-magento2/releases/latest/download/waffy-module-payment.zip

mkdir -p app/code/Waffy/Payment
unzip waffy-module-payment.zip -d app/code/Waffy/Payment

bin/magento module:enable Waffy_Payment
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

The version-less waffy-module-payment.zip is byte-identical to the versioned asset — it exists so scripted installs always fetch the current version from one unchanging address. Verify a download against the checksum published on the release with shasum -a 256.

Note on -f and static content: setup:static-content:deploy -f is required in production mode. In developer mode you can skip that line. Run bin/magento deploy:mode:show if you're unsure which mode the store is in.

Verify the module is active

bin/magento module:status Waffy_Payment

Expected output: Module is enabled.

3. Configuration

All in the Admin panel — no commands. Go to Stores → Configuration → Sales → Payment Methods → Waffy Escrow Payment.

3.1 Connect your Waffy account

Set Environment to Sandbox first (no real money).
Enter the Sandbox Client ID, Client Secret, Admin Email, and Admin Password provided by Waffy.
Merchant Phone Number (required) — E.164 format, e.g. +9665XXXXXXXX. Identifies the merchant on every escrow contract.
Broker Phone Number (optional) — leave empty if not used.

3.2 Register your webhook

Copy the Webhook URL shown at the top of the config section — it looks like https://your-store.com/waffy/webhook.
Send that URL to the Waffy team so they register your store for order status updates.
Webhook Allowed IPs (optional) — leave empty to allow all, or add one IP/CIDR per line.

3.3 Contract settings

Match these to how you sell:

Setting	Meaning
Return Policy	Whether/what returns are allowed on the contract
Return Fee Payee	Who pays the return fee (provider / 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 until the payment milestone expires (default 30)
Contract Category	Category shown to the buyer on the Waffy page (e.g. Services)

3.4 Storefront settings

Title — what buyers see at checkout (e.g. "Pay with Waffy").
Payment from Applicable Countries — all, or a specific list.
Enabled → Yes.
Click Save Config, then flush the cache:

bin/magento cache:flush

4. Test in Sandbox

Place a test order on the storefront and choose Waffy at checkout.
Complete payment on the Waffy hosted payment page.
Confirm the order moves to Processing and shows Waffy status comments in the order's Comments History.

Testing cards

5. Go Live

Set Environment → Production.
Enter your Production Client ID, Client Secret, Admin Email & Password.
If your store URL changed, re-share the new Webhook URL with Waffy.
Save Config and flush the cache.
Place one small real order to confirm end to end.

6. Updating & Uninstalling

Settings and cached tokens survive an update — they live in Magento's configuration and the waffy_token table, not in the module folder.

Updating

Composer installs

composer update waffy/module-payment
bin/magento module:enable Waffy_Payment
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

Manual (zip) installs

Delete app/code/Waffy/Payment entirely, unpack the new zip in its place, then re-run the same commands. Do not unzip over the existing folder — files removed in the new version would linger and can break the module.

Uninstalling

Disable (reversible)

bin/magento module:disable Waffy_Payment
bin/magento setup:upgrade
bin/magento cache:flush

Stops the module and its token-refresh cron. Nothing is deleted; re-enabling restores the previous setup.

Remove

composer remove waffy/module-payment for Composer installs, or delete app/code/Waffy/Payment for manual ones, then re-run setup:upgrade.

The module ships no uninstall script, so the waffy_token table and your saved configuration are left in place after removal. Clearing them is a manual database step — which also means a remove-and-reinstall keeps your credentials.

7. Troubleshooting

Symptom	Fix
Waffy not shown at checkout	Confirm Enabled = Yes, correct countries, and cache:flush was run
composer require auth error	Use Marketplace public key as username, private key as password (Access Keys)
Order status not updating	Confirm the Webhook URL was registered with Waffy and isn't blocked by the IP allowlist
Class/compile errors after install	Re-run bin/magento setup:di:compile then cache:flush
Checkout is slow on the first order	Token warm-up has not run yet — confirm Magento cron is configured. Harmless: the SDK fetches what is missing

Token warm-up & Magento cron

Checkout needs four OAuth tokens. The extension keeps them cached in the waffy_token table and refreshes them ahead of expiry so no shopper's request pays for a fetch.

Store tokens — the cron job waffy_refresh_tokens runs every 15 minutes and renews anything near expiry. It is a no-op when both tokens are still fresh, and each store is warmed independently, since credentials are store-scoped.
Customer token — prefetched on the storefront when a shopper signs in, or arrives with a session cookie already set.

If Magento cron is not running, checkout still works — the SDK fetches whatever is missing, just more slowly on the first order. Confirm cron is configured with bin/magento cron:install.

Support

Email support@waffyapp.com for credentials, webhook registration, or setup help.

Contact Support Browse Documentation