Skip to main content
This guide shows you how to add Kwugwo to your online store so your customers can pay you by bank transfer, USSD or with their bank app. You don’t need to write any code. If you can log in to your website’s dashboard and copy and paste, you can do this. It takes about 20 to 30 minutes the first time.

​
Before you start

Make sure you have these things ready:
  1. A WordPress website with WooCommerce. WordPress is the software your website runs on. WooCommerce is the part that turns it into a shop, with products, a cart and a checkout. If you can see a WooCommerce item in the black menu on the left of your website’s dashboard, you have it.
  2. Your website’s admin login. You need an account that can install plugins, usually the “Administrator” account. You log in at https://your-website.com/wp-admin.
  3. A Kwugwo account. If you don’t have one yet, sign up at kwugwo.africa.
  4. An account with a payment provider (the company that already collects payments for you), connected to Kwugwo. Kwugwo sends each payment to your provider, and the money settles into your own provider account. Kwugwo never holds your money.
Kwugwo has two sides. Sandbox is for practice: nothing is charged and no real money moves. Live is for real customers and real money. You’ll set up Sandbox first, try a test payment, then switch to Live. Each side has its own keys and settings.

​
Step 1: Install the plugin

A plugin is an add-on that gives your website a new feature. The Kwugwo plugin adds Kwugwo as a payment option at your checkout.
  1. Log in to your website’s dashboard (https://your-website.com/wp-admin).
  2. In the left menu, go to Plugins → Add Plugin. (On some websites it’s called Add New Plugin.)
  3. In the search box at the top right, type Kwugwo for WooCommerce.
  4. When the Kwugwo plugin appears, click Install Now.
  5. Wait a few seconds, then click Activate.
You’ll be taken to your list of plugins. “Kwugwo for WooCommerce” should now be on the list, with a Set up link under its name.
If WordPress says the plugin needs WooCommerce, install and activate WooCommerce first (Plugins → Add Plugin, search for “WooCommerce”), then come back to this step.

​
Step 2: Set your store currency to Naira

Kwugwo only takes payments in Nigerian Naira (₦). If your store shows prices in another currency, Kwugwo won’t appear at checkout.
  1. In the left menu, go to WooCommerce → Settings.
  2. Stay on the General tab and scroll down to Currency options.
  3. Set Currency to Nigerian naira (₦).
  4. Scroll to the bottom and click Save changes.
Kwugwo accepts orders from ₦200 up to ₦50,000,000. Orders outside that range can’t be paid with Kwugwo.

​
Step 3: Get your Kwugwo account ready

Open a new browser tab and sign in to your Kwugwo dashboard. Switch the dashboard to Sandbox, then check these two things:
  1. Your payment provider is connected. In Sandbox, connect it using the test details from your provider’s own dashboard, not the live ones.
  2. You have a checkout for NGN. A checkout is where you choose which payment methods your customers see (bank transfer, USSD, pay with bank) and which provider handles each one. Create one if you don’t have one yet, with currency NGN.
Keep this tab open. You’ll copy things from it in the next steps.

​
Step 4: Open the Kwugwo settings on your website

Go back to your website’s dashboard and open the Kwugwo settings page. There are two ways to get there:
  • Plugins, then click Set up under “Kwugwo for WooCommerce”, or
  • WooCommerce → Settings → Payments, then click Manage next to Kwugwo.
At the top of the page you’ll see a Setup checklist. Each item shows a green tick ✅ when it’s done, or a yellow warning ⚠️ when it still needs attention. The checklist updates every time you save, so use it to see what’s left to do. Under the checklist there’s a short step-by-step guide. You can open it any time by clicking How to set up Kwugwo, step by step.

​
Step 5: Add your Sandbox API keys

API keys are like a username and password that let your website talk to your Kwugwo account. There are two: Sandbox keys always end in _t. Live keys never do. That’s an easy way to check you’ve copied the right ones.
  1. On the Kwugwo settings page, find Test or live payments and make sure Mode is set to Sandbox (test payments, no real money).
  2. In your Kwugwo dashboard (Sandbox side), open the API Keys page.
  3. Copy the public key and paste it into Public key under Sandbox keys on your website.
  4. Copy the secret key and paste it into Secret key.
  5. Click Test connection.
You should see a green message like “Connected to Kwugwo Sandbox. You have 1 active checkout.” If you see a red message instead, it tells you what’s wrong. The most common causes:
  • “Kwugwo did not accept this secret key for Sandbox”: you may have copied the Live key instead of the Sandbox one, or missed part of it. Copy it again from the Sandbox side of your dashboard.
  • “these look like Live keys” (or “these look like Sandbox keys”): the keys are from the other side of your dashboard. Sandbox keys end in _t; Live keys don’t. Copy them from the right side, or paste them into the other section.
  • “come from different Kwugwo workspaces”: the two keys belong to different accounts or workspaces. Copy both keys from the same place.
  • “should start with pk.” / “should start with sk.”: the two keys were pasted into the wrong boxes. Swap them.
  • “no active checkouts yet”: your keys work, but you still need to create a checkout in your Kwugwo dashboard (see Step 3).
Click Save changes at the bottom of the page.
Never share your secret key in WhatsApp, email or screenshots. If you think someone else has seen it, generate a new one in your Kwugwo dashboard and paste the new one here.

​
Step 6: Connect the webhook so orders update by themselves

A webhook is how Kwugwo tells your website that a customer has paid. With it, the order is marked as paid automatically, even if the customer closes their browser straight after paying. Without it, some orders may stay on “Pending payment” for a while.

​
6a. Copy your webhook URL

On the Kwugwo settings page, find Webhook URL. It looks like this:
Click the Copy button next to it.

​
6b. Add it in your Kwugwo dashboard

  1. In your Kwugwo dashboard (Sandbox side), open the Webhooks page.
  2. Add a new endpoint and paste your webhook URL.
  3. When asked which events to send, tick these (see Webhook events for the full list):
  4. Set a signing secret when asked. It starts with wsk.. Copy it.

​
6c. Paste the signing secret on your website

  1. Back on the Kwugwo settings page, paste the signing secret into Webhook signing secret under Sandbox keys.
  2. Click Save changes.
The signing secret lets your website check that payment updates really come from Kwugwo and not from someone pretending to be Kwugwo.
Is your website behind a firewall? Some hosting companies block unknown visitors. If so, ask your host to allow Kwugwo’s address 176.97.192.227, so webhooks can reach your website.

​
Step 7: Turn on Kwugwo

  1. At the top of the settings form, tick Turn on Kwugwo (“Show Kwugwo as a payment option at checkout”).
  2. Optionally, change Name at checkout and Message at checkout. This is what your customers see when they choose how to pay.
  3. Click Save changes.
All four items in the Setup checklist should now be green, with the message “All set. Kwugwo is ready to take payments.” The webhook item may say Kwugwo “has not sent an update yet”. That’s normal: the first update arrives with your first payment.

​
Optional: choose a checkout

Under your keys there’s a Checkout (optional) box. Leave it on Automatic (use my routing rules) unless you have a reason to change it. Pick a specific checkout only if you want every payment from this store to use that checkout’s payment methods and providers, for example to keep this store’s money separate from your other businesses.

​
Step 8: Make a test payment

Now buy something from your own store, the way a customer would. You’re still in Sandbox, so nothing is really charged.
  1. Open your shop in a new tab (or a private/incognito window), add a product to the cart and go to Checkout. The product must cost at least ₦200.
  2. Fill in the billing details and choose Kwugwo as the payment method. You’ll see a note saying “Test mode: no real money will be taken.”
  3. Click Place order. A secure Kwugwo window opens on the page.
  4. Choose a payment method (for example Bank Transfer) and follow the instructions in the window.
In Sandbox, how the payment completes depends on your payment provider (see Testing in sandbox). Some complete the test payment by themselves after a moment. Others ask you to take one more step in the provider’s own test dashboard. If the window shows a link to the next steps, follow it. When the payment goes through, the customer is taken to the Order received page. Then check it on your side:
  1. In your website’s dashboard, go to WooCommerce → Orders.
  2. Your test order should show the status Processing. That means it’s paid and ready to fulfil.
  3. Open the order. On the right you’ll see a Kwugwo payment box with the payment details, and in Order notes you’ll see “Kwugwo payment confirmed”.
If the customer closes the payment window by mistake, nothing is lost. The page shows a Pay button so they can open the window again and finish paying.

​
Step 9: Go live and take real payments

When your test payment works, switch to Live. You’ll repeat steps 3, 5 and 6, this time on the Live side of your Kwugwo dashboard.
  1. In your Kwugwo dashboard, switch to Live. Connect your payment provider with its live details and create a checkout for NGN.
  2. On your website, go to the Kwugwo settings and set Mode to Live (real payments). The page now shows the Live keys section.
  3. Copy your Live public key and secret key from the API Keys page on the Live side of your dashboard, paste them in, and click Test connection.
  4. On the Webhooks page of the Live side, add the same webhook URL, tick the same events, set a signing secret, and paste it into Webhook signing secret under Live keys.
  5. Click Save changes and check that the Setup checklist (Live) is all green.
Your customers can now pay you for real. Consider making one small real purchase yourself to be sure everything works end to end.
Your Sandbox keys stay saved. If you ever want to test something again, switch Mode back to Sandbox, but remember that while it’s on Sandbox, customers can’t pay you for real.

​
Everyday use

​
What the order statuses mean

​
”The customer says they’ve paid, but the order is still Pending”

  1. Open the order in WooCommerce → Orders.
  2. In the Kwugwo payment box on the right, click Check payment status now.
Your website asks Kwugwo directly. If the payment is complete and matches the order, the order moves to Processing straight away. If it doesn’t move, the payment hasn’t arrived yet; the order notes explain anything unusual, such as a part payment. Your website also checks unpaid orders by itself every 15 minutes, so a missed update is caught even if you do nothing.

​
Giving a refund

  1. Open the order and click Refund (below the order items).
  2. Enter the amount to refund and, if you like, a reason. The smallest refund Kwugwo can send is ₦200.
  3. Click Refund ₦… via Kwugwo, then confirm.
The order notes show “Kwugwo refund … requested”, and later “Kwugwo refund … completed” once your payment provider has sent the money back. If the refund asks for the customer’s bank account: some payment providers can’t send money back to a customer who paid by bank transfer or USSD unless they know the customer’s account. In that case:
  1. Ask the customer for their bank and 10-digit account number.
  2. In the Kwugwo payment box on the order, choose the Bank and type the Account number under Refund account.
  3. Click Update (top right of the order page), then try the refund again.
If a note says a refund FAILED, the customer hasn’t been paid back, even though WooCommerce lists the refund. Fix the cause and refund again, or pay the customer directly.

​
”The customer paid twice”

Sometimes a customer pays into an old transfer account after the order was already paid. You’ll see an order note saying “the customer paid for this order a second time”. Refund that extra payment from your Kwugwo dashboard.

​
Troubleshooting

Kwugwo doesn’t show at checkout. Open the Kwugwo settings and look at the Setup checklist. Kwugwo only appears when it’s turned on, the store currency is Naira, and both keys are saved for the mode you’ve selected (Sandbox or Live). Also check that the order total is at least ₦200. I see “We could not start your payment” at checkout. Open the order in WooCommerce → Orders and read the order notes. They say what went wrong and how to fix it, for example a key that no longer works, or a checkout that was switched off in your Kwugwo dashboard. The webhook item in the checklist never turns into “Webhook connected”.
  • Check that the webhook URL in your Kwugwo dashboard matches the one on the settings page exactly.
  • Check that the signing secret on your website matches the one in your dashboard, and that it’s in the right section (Sandbox or Live).
  • If your hosting has a firewall, ask your host to allow 176.97.192.227.
Orders stay on “Pending payment” after the customer has paid. Use Check payment status now on the order. If that works but orders don’t update on their own, your webhook isn’t reaching your website; see the item above. I changed my keys in the Kwugwo dashboard and payments stopped working. When you generate a new key, the old one stops working immediately. Paste the new key into the plugin settings and click Test connection. Something else is wrong. On the Kwugwo settings page, under Troubleshooting, tick Debug log and save, then try again. The details are recorded under WooCommerce → Status → Logs (choose the source kwugwo). Share them with Kwugwo support if you need help. The log contains customer emails and order amounts, so turn it off again when you’re done.

​
Keeping your account safe

  • Only paste your secret key into the plugin settings. Never send it to anyone, and never post it online.
  • Always set a webhook signing secret.
  • Give the WordPress “Administrator” role only to people who really need it. Anyone who can change the plugin settings can see your keys.