Set Up Flutterwave Payments
Selling across Africa means buyers who pay by mobile money in one country, bank transfer in the next and card in a third, in a dozen currencies. One gateway per country is a lot of settings screens to keep working.
Flutterwave covers those methods on one hosted checkout. The Flutterwave module adds it to Easy Digital Downloads for one-time payments. Each payment is verified with Flutterwave before the order is marked paid. Refunds go back through Flutterwave, and webhooks bring in payments and refunds made in Flutterwave.
Currencies
Flutterwave shows at checkout when the order’s currency is one of these:
- African currencies: NGN, GHS, KES, UGX, TZS, RWF, ZAR, XAF, XOF, MWK, ZMW and EGP
- International: USD, EUR and GBP
Which of them your account can take, and which methods buyers see, depends on your Flutterwave account’s country and settings. UGX, RWF, XAF and XOF are sent as whole numbers.
Flutterwave works with Sell in Multiple Currencies, and Match Payment Gateways to Currencies knows its currency list.
Turn On the Gateway
- Switch on the Flutterwave module under Stackless → Dashboard.
- Add your secret key under Stackless → Settings → Flutterwave and save.
- Go to Downloads → Settings → Payments and switch on Flutterwave (Stackless) under Active Gateways. Save.
Flutterwave stays off the checkout until the current mode has a secret key.
Add Your API Keys
This gateway uses Flutterwave’s v3 API. In the Live keys section of the settings screen, the Get API keys button opens the live keys page in the Flutterwave dashboard. Copy the v3 secret key. If your dashboard offers “Switch to v4 live API keys”, stay on v3. Switch the dashboard to test mode to copy the test key.
- Title: the gateway name at checkout. Default “Card, bank transfer or mobile money (Flutterwave)”.
- Description: the text under it. Default “You’ll finish paying on Flutterwave’s secure checkout.”
- Test mode: uses Flutterwave test mode, so no real money moves. On by default. This switch is separate from EDD’s Enable Test Mode.
- Debug log: writes Flutterwave activity to the EDD debug log. Off by default.
- Live secret key and Live webhook secret hash
- Test secret key and Test webhook secret hash
Test keys start with FLWSECK_TEST. When you save, Stackless checks each new key once with Flutterwave and shows Flutterwave’s error if the key is rejected, or an error if a key sits in the other mode’s field. The public key isn’t needed.
You can also set these as wp-config.php constants, which win over saved settings and hide their fields: STACKLESS_EDD_FLUTTERWAVE_LIVE_SECRET_KEY, STACKLESS_EDD_FLUTTERWAVE_LIVE_SECRET_HASH, STACKLESS_EDD_FLUTTERWAVE_TEST_SECRET_KEY and STACKLESS_EDD_FLUTTERWAVE_TEST_SECRET_HASH.
Connect the Webhook
Flutterwave doesn’t hand you a webhook secret. You make one up, any long random text, and enter it in both places:
- Type it into the webhook secret hash field for the mode and save.
- In Flutterwave, open Settings → Webhooks, once in test mode and once in live mode. The Open webhook settings button opens the live screen.
- Choose the V3 webhook and paste
https://yoursite.com/wp-json/stackless-edd/v1/flutterwave/webhook. The Webhook section of the settings screen shows your exact URL. - Enter the same text as the Secret hash.
- Tick Receive webhook response in JSON format, Enable webhook retries and Enable webhook for refunds, then save.
Flutterwave sends the secret hash back in the verif-hash header of every delivery, and Stackless compares it with your live and test hashes. Accounts whose webhooks were moved to v4 send a flutterwave-signature header instead, an HMAC-SHA256 of the raw body keyed with the same hash, and that’s accepted too. A delivery with a missing or wrong hash is refused.
Stackless acts on charge.completed deliveries and on refund deliveries, and applies each one once, however often Flutterwave retries it. Without a secret hash every webhook is refused and payments are confirmed only when buyers come back to your store. So saving with the gateway on and no hash shows “Add the Flutterwave webhook secret hash. Payments and refunds stay in sync through the webhook.”
What Buyers See
At checkout, Flutterwave shows as “Card, bank transfer or mobile money (Flutterwave)” with “You’ll finish paying on Flutterwave’s secure checkout.” In test mode, checkout adds “Test mode: no real payment will be taken.”
- Purchasing sends the buyer to Flutterwave’s hosted checkout, titled with your store name and “Order [number]”. Their email and name are passed along.
- A completed payment lands on your EDD success page.
- A failed or cancelled payment sends the buyer back to pay the same order again, with “Your payment did not go through. Please try again or choose another payment method.”
- A payment Flutterwave is still processing lands on the success page, and the webhook confirms it later.
- Flutterwave needs a valid email address on the order. Paying the same order again within 30 minutes reuses the open payment link.
How Payments Are Verified
Every path that can pay an order, whether the buyer’s return, the webhook or a repeated checkout, reads the transaction from Flutterwave’s API first. Stackless then checks that:
- its reference was made for this order on this site
- its status is successful
- it was made in the same mode as the order
- its currency and amount match the order total exactly
A transaction that passes completes the order, with a note naming the reference and payment type. A mismatch puts the order On Hold with a note to check it in Flutterwave. A failed payment reported by webhook adds a note with Flutterwave’s reason. On the order screen, the transaction ID links to the transaction in your Flutterwave dashboard.
Refunds
- EDD’s refund form on the order gets a Refund transaction in Flutterwave box, ticked by default. Flutterwave is asked first. If it refuses, you see its error and EDD records nothing. Partial and full refunds both work.
- Untick the box to record the refund in EDD only. The order gets a note saying the transaction wasn’t refunded in Flutterwave.
- Refunds made in the Flutterwave dashboard are recorded on the order once, after Stackless reads the refund back from Flutterwave: a full refund, or a partial one spread across the order’s items. This needs Enable webhook for refunds ticked.
- If Flutterwave can’t complete a refund made from EDD, an order note says the money didn’t reach the customer, so you can refund another way.
Subscriptions With Flutterwave
Flutterwave takes one-time payments. It doesn’t save a payment method for Stackless to charge later, so subscriptions bought with it renew by pay link. The download’s Renewal mode decides whether Flutterwave shows at checkout:
- Automatic only (requires a gateway that saves cards) hides Flutterwave.
- Automatic when the gateway supports it, otherwise manual shows Flutterwave, and paying with it makes the subscription manual.
- Manual only (customer pays each renewal invoice) shows Flutterwave as usual.
At each renewal the customer gets the Subscription renewal invoice email with a link to pay the renewal order. They can pay it with Flutterwave or any other active gateway, and paying puts an on-hold subscription back to Active. See Sell Downloads as Subscriptions and Handle Renewals and Failed Payments for grace periods and reminders.
Check the Connection
- Billing Health lists Flutterwave setup problems: no secret key for the current mode, a key for the other mode, no webhook secret hash, no webhook received yet and test mode left on. It also shows recent webhook events that failed.
- With Alerts on in Extra Enhancements (“Email me about failed live payments”), failed live Flutterwave orders and failed live calls to Flutterwave are emailed to you.
- Turn on Debug log to write Flutterwave activity to Downloads → Tools → Debug Log, tagged
stackless-edd-flutterwave_gateway, while EDD debug mode is on. Keys are never logged.
Limits
- One-time payments only. Subscriptions renew by emailed pay link, never automatically.
- Uses Flutterwave’s v3 API. Keep the account’s API keys and webhooks on v3.
- The webhook and its secret hash have to be set in the Flutterwave dashboard by hand.
- Which currencies and methods work depends on the account’s country and settings.
- The buyer’s phone number isn’t sent, because EDD orders don’t store one. Add it with the checkout args filter if your store collects it.
- Buyers always pay on Flutterwave’s hosted page. There’s no popup on your own checkout.
- A buyer who finishes paying in a different browser from the one they checked out in lands on the success page without the purchase details. The webhook still confirms the order.
- Flutterwave isn’t used for orders with nothing to pay, and can’t be duplicated for a second account with Payment Gateway Tools.
For Developers
stackless_edd_flutterwave_gateway_checkout_args changes the payment sent to Flutterwave and receives the body, the order and the gateway. stackless_edd_flutterwave_gateway_currencies changes the currency list. The stackless_edd_flutterwave_gateway_webhook action runs after each applied delivery with the event type, its data and the mode. To show your logo on Flutterwave’s checkout:
add_filter('stackless_edd_flutterwave_gateway_checkout_args', function ($args, $order, $gateway) {
$args['customizations']['logo'] = 'https://yoursite.com/logo.png';
return $args;
}, 10, 3);
Override the checkout fields by copying the template to yourtheme/stackless-edd/flutterwave_gateway/payment-fields.php.