Set Up Paystack Payments

Many 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 turns them away at the last step.

Paystack takes those methods on its hosted checkout. The Paystack module adds it to WooCommerce 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 use depends on where your Paystack business is registered:

Business registered in	Currencies	Smallest charge
Nigeria	NGN, USD	₦50, or $2
Ghana	GHS	GHS 0.10
South Africa	ZAR	ZAR 1
Kenya	KES, USD	KSh 3, or $2
Côte d’Ivoire	XOF	XOF 1

Paystack shows at checkout when the order is in one of these currencies. Paystack itself refuses a currency your account can’t use when the payment starts, and an order below the smallest charge gets a message asking the buyer to pick another payment method. Egypt (EGP) and Rwanda (RWF) accounts can add their currency with a filter, shown under For Developers.

Paystack works with Multi-Currency Checkout, and Currency-Aware Payment Gateways knows its list.

Turn On the Gateway

1. Switch on the Paystack module under Stackless → Dashboard.
2. Go to WooCommerce → Settings → Payments → Paystack (Stackless).
3. Tick Enable (Accept payments with Paystack).

Stackless → Settings → Paystack only shows a link to that screen and your webhook URL. Paystack stays off the checkout until the current mode has a secret key.

Add Your API Keys

The Get API keys button in the gateway’s Live section opens the keys page in the Paystack dashboard. Copy test keys with the dashboard in Test Mode. Then fill in:

• Test mode: on by default. No real money moves.
• 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 with Paystack and shows an error if Paystack rejects it. A live key in the test field, or a test key in the live field, gets an error naming the key to paste.

You can also set these as wp-config.php constants, which win over saved settings and hide their fields: STACKLESS_PAYSTACK_LIVE_SECRET_KEY, STACKLESS_PAYSTACK_LIVE_WEBHOOK_SECRET, STACKLESS_PAYSTACK_TEST_SECRET_KEY and STACKLESS_PAYSTACK_TEST_WEBHOOK_SECRET.

Connect the Webhook

In the Paystack dashboard, open Settings → API Keys & Webhooks and paste https://yoursite.com/wp-json/stackless/v1/paystack/webhook into both the Test Webhook URL and the Live Webhook URL. The gateway settings show 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. The Get webhook signing secret button opens the Paystack page that shows it. Paste it 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 WooCommerce.

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.” Test mode adds “Test mode: no real payment will be taken.” It works in the Checkout block, the classic checkout and the order payment page.

• Placing the order 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 order number shows on the transaction in your Paystack dashboard.
• A completed payment lands on the order received page.
• A failed or abandoned payment, or cancelling on Paystack, sends the buyer back to the order payment page to try again.
• A payment Paystack is still processing lands on the order received page, and the webhook confirms it when Paystack does.
• Paystack needs a valid email address on the order. Placing the same order again within 30 minutes reuses the open Paystack payment.

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 marks the order paid, 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. On the order screen, the transaction ID links to the transaction in your Paystack dashboard.

Refunds and Disputes

• Refunds from the WooCommerce order screen, partial or full, are made in Paystack. The order 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.
• Refunds made in the Paystack dashboard are recorded on the order once when Paystack reports them. Items aren’t restocked.
• If Paystack can’t complete a refund made from WooCommerce, 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 product’s Renewal mode decides whether Paystack shows:

• Automatic only hides Paystack at checkout.
• Automatic when the gateway supports it, otherwise manual shows Paystack, and paying with it makes the subscription manual.
• Manual only 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 available method, and paying reactivates the subscription if it went on hold. See Create Subscription Products and Renewals, Failed Payments and Retries 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.
• Turn on Debug log to write Paystack activity to WooCommerce → Status → Logs (stackless-paystack_gateway). Keys are never logged.

Limits

• One-time payments only. Subscriptions renew by emailed invoice, 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.
• Paystack can’t be duplicated for a second account with Payment Gateway Tools.

For Developers

stackless_paystack_gateway_checkout_args changes the transaction sent to Paystack and receives the body, the order and the gateway. stackless_paystack_gateway_currencies changes the currency list. The stackless_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_paystack_gateway_currencies', function ($currencies) {
    $currencies[] = 'EGP';
    return $currencies;
});

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