Skip to content
Gaurav TiwariDocs

Set Up Paystack Payments

Version 1.0.0-beta.1 Updated November 8, 2026

A lot of buyers in Nigeria, Ghana, Kenya and South Africa don’t pay by card. They pay by bank transfer, USSD or mobile money, and a card-only checkout loses them at the last step.

The Paystack module adds Paystack’s hosted checkout to Easy Digital Downloads for one-time payments. Each payment is verified with Paystack before the order is marked paid. Refunds go back through Paystack, and signed webhooks bring in refunds and disputes made in the Paystack dashboard.

Countries and Currencies

Which currencies your account can take depends on where your Paystack business is registered:

Business registered inCurrenciesSmallest charge
NigeriaNGN, USDNGN 50, or USD 2
GhanaGHSGHS 0.10
South AfricaZARZAR 1
KenyaKES, USDKES 3, or USD 2
Côte d’IvoireXOFXOF 1

Paystack shows at checkout when the order’s currency is one of these. Paystack itself refuses a currency your account can’t use when the payment starts. An order below the smallest charge sends the buyer back to checkout with “Paystack accepts payments of [amount] or more. Choose another payment method for this order.” Egypt (EGP) and Rwanda (RWF) accounts can add their currency with a filter, shown under For Developers.

Paystack works with Sell in Multiple Currencies, and Match Payment Gateways to Currencies knows its currency list.

Turn On the Gateway

  1. Switch on the Paystack module under Stackless → Dashboard.
  2. Add your secret key under Stackless → Settings → Paystack and save.
  3. Go to Downloads → Settings → Payments and switch on Paystack (Stackless) under Active Gateways. Save.

Paystack stays off the checkout until the current mode has a secret key.

Add Your API Keys

The settings screen has a Live keys section and a Test mode keys section. In the Live keys section, the Get API keys and Get webhook signing secret buttons open those pages in the Paystack dashboard. Switch the dashboard to Test Mode to copy the test keys and the test signing secret.

  • Title: the gateway name at checkout. Default “Card, bank transfer or mobile money (Paystack)”.
  • Description: the text under it. Default “You’ll finish paying on Paystack’s secure checkout.”
  • Test mode: uses Paystack test mode, so no real money moves. On by default. This switch is separate from EDD’s Enable Test Mode.
  • Debug log: writes Paystack activity to the EDD debug log. Off by default.
  • Live secret key and Live webhook signing secret
  • Test secret key and Test webhook signing secret

A secret key starts with sk_live_ or sk_test_. You can paste a restricted key instead (rk_live_ or rk_test_) as long as it has the transactions and refunds permissions. The public key isn’t needed.

When you save, Stackless checks each new key once with Paystack and shows Paystack’s error if the key is rejected. A live key in the test field, or a test key in the live field, gets an error naming the key to paste. With the gateway switched on and no secret key for the selected mode, you see “Paystack is turned on but has no secret key for the selected mode.”

You can also set these as wp-config.php constants, which win over saved settings and hide their fields: STACKLESS_EDD_PAYSTACK_LIVE_SECRET_KEY, STACKLESS_EDD_PAYSTACK_LIVE_WEBHOOK_SECRET, STACKLESS_EDD_PAYSTACK_TEST_SECRET_KEY and STACKLESS_EDD_PAYSTACK_TEST_WEBHOOK_SECRET.

Connect the Webhook

In the Paystack dashboard, paste https://yoursite.com/wp-json/stackless-edd/v1/paystack/webhook into both the Test Webhook URL and the Live Webhook URL. The Webhook section of the settings screen shows your exact URL. Paystack sends every event to that one address, so there are no events to pick, and it doesn’t let plugins add the URL for you.

Stackless acts on these events and acknowledges the rest:

charge.success
refund.processed
refund.failed
refund.needs-attention
charge.dispute.create
charge.dispute.remind
charge.dispute.resolve

How Deliveries Are Signed

Paystack can sign a delivery in two ways, and Stackless accepts both:

  • Webhook signing secret (starts with whsec_): the Paystack-Signature header carries a timestamp and an HMAC-SHA512 of the timestamp and the raw body. Deliveries more than five minutes old are refused. Paste the secret into the signing secret field for each mode.
  • Secret key: the older x-paystack-signature header, an HMAC-SHA512 of the raw body keyed with your sk_ secret key. Paystack marks it deprecated.

So the signing secret is optional while you use a full secret key, and required once you switch to a restricted key, which doesn’t sign webhooks. A delivery without a valid signature is refused. Each payment is applied once, however often Paystack retries it.

Webhooks confirm payments when a buyer closes the tab before coming back, and bring refunds and disputes made in Paystack into EDD.

What Buyers See

At checkout, Paystack shows as “Card, bank transfer or mobile money (Paystack)” with “You’ll finish paying on Paystack’s secure checkout.” In test mode, checkout adds “Test mode: no real payment will be taken.”

  • Purchasing sends the buyer to Paystack’s hosted checkout, which offers the channels your account has turned on, such as card, bank transfer, USSD, mobile money and Apple Pay. The EDD order number shows on the transaction as an “Order” field in your Paystack dashboard.
  • A completed payment lands on your EDD success page.
  • A failed or abandoned payment, or cancelling on Paystack, 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 Paystack is still processing lands on the success page, and the webhook confirms it when Paystack does.
  • Paystack needs a valid email address on the order. Paying the same order again within 30 minutes reuses the open Paystack payment instead of starting a new one.
  • If Paystack can’t start the payment, the buyer stays on checkout with the reason, and the next attempt reuses the same pending order.

How Payments Are Verified

Nothing in the return address or a webhook marks an order paid on its own. Stackless asks Paystack’s API for the transaction first, then checks that:

  • it was started for this order on this site
  • its status is success
  • it was made in the same mode as the order, so a test payment never pays a live order
  • its currency matches and the amount asked for is the order total. If the buyer was asked to cover Paystack’s fee, the extra is allowed.

A transaction that passes completes the order, with a note naming the Paystack reference and channel. One that doesn’t match puts the order On Hold with a note to check it in Paystack before delivering. On the order screen, the transaction ID links to the transaction in your Paystack dashboard.

Refunds and Disputes

  • EDD’s refund form on the order gets a Refund transaction in Paystack box, ticked by default. Paystack is asked first. If it refuses, you see its error and EDD records nothing. Partial and full refunds both work, and the note says Paystack can take up to 10 business days to return the money.
  • Retrying a refund that timed out never pays the customer twice.
  • Untick the box to record the refund in EDD only. The order gets the note “Transaction not refunded in Paystack, as the box was not ticked.”
  • Refunds made in the Paystack dashboard are recorded on the order once when Paystack reports them: a full refund, or a partial one spread across the order’s items. When EDD can’t express it that way, the order is marked Partially Refunded with a note.
  • If Paystack 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.
  • Disputes opened, reminded or resolved in Paystack add an order note. Respond to them in the Paystack dashboard.

Subscriptions With Paystack

Paystack 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 Paystack shows at checkout:

  • Automatic only (requires a gateway that saves cards) hides Paystack.
  • Automatic when the gateway supports it, otherwise manual shows Paystack, and paying with it makes the subscription manual.
  • Manual only (customer pays each renewal invoice) shows Paystack 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 Paystack 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 Paystack setup problems: no secret key for the current mode, a key for the other mode, a restricted key without a webhook signing secret, no signing secret yet, 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 Paystack orders and failed live calls to Paystack are emailed to you.
  • Turn on Debug log to write Paystack activity to Downloads → Tools → Debug Log, tagged stackless-edd-paystack_gateway, while EDD debug mode is on. Keys are never logged.

Limits

  • One-time payments only. Subscriptions renew by emailed pay link, never automatically.
  • Which currencies and channels work depends on your Paystack business’s country and settings.
  • Paystack’s smallest charge applies, and Paystack isn’t used for orders with nothing to pay.
  • The webhook URL has to be added in the Paystack dashboard by hand.
  • Buyers always pay on Paystack’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.
  • Paystack can’t be duplicated for a second account with Payment Gateway Tools.

For Developers

stackless_edd_paystack_gateway_checkout_args changes the transaction sent to Paystack and receives the body, the order and the gateway. stackless_edd_paystack_gateway_currencies changes the currency list. The stackless_edd_paystack_gateway_webhook action runs after each applied event with the event type, its data and the mode. To take Egyptian pounds:

add_filter('stackless_edd_paystack_gateway_currencies', function ($currencies) {
    $currencies[] = 'EGP';
    return $currencies;
});

Override the checkout fields by copying the template to yourtheme/stackless-edd/paystack_gateway/payment-fields.php.

Share

Was this helpful?

Still stuck? Open a support ticket