> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kwugwo.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up Kwugwo on WooCommerce

> Install the Kwugwo for WooCommerce plugin and start taking bank transfer, USSD and pay-with-bank payments on your online store, step by step.

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](https://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.

> [!NOTE]
>
> 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.

> [!TIP]
>
> 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**.

> [!NOTE]
>
> 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](https://app.kwugwo.africa). 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:

| Key | Starts with | What it's for |
| - | - | - |
| **Public key** | `pk.` | Opens the Kwugwo payment window for your customers. It's safe for customers' browsers to see. |
| **Secret key** | `sk.` | Lets your website create and check payments. **Keep it private.** Anyone with this key can manage payments on your account. |

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.

> [!WARNING]
>
> **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:

```
https://your-website.com/?wc-api=kwugwo_webhook
```

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](https://docs.kwugwo.africa/webhook-events.md) for the full list):

   | Event | What it does on your store |
   | - | - |
   | `ugwo.successful` | **Required.** Marks the order as paid. |
   | `ugwo.updated` | Updates the order when a payment is cancelled or refunded. |
   | `ugwo.activity.updated` | Puts the order on hold if your payment provider reverses a payment. |
   | `ugwo.activity.double_charge_detected` | Warns you when a customer pays twice for the same order. |
   | `refund.successful` | Adds a note to the order when a refund is completed. |
   | `refund.failed` | Warns you on the order when a refund fails. |

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.

> [!NOTE]
>
> **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](https://docs.kwugwo.africa/guides/testing.md#simulating-a-payment)).
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"*.

> [!TIP]
>
> 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.

> [!NOTE]
>
> 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

| Status | What it means | What to do |
| - | - | - |
| **Pending payment** | The customer placed the order but hasn't finished paying yet, or the payment hasn't been confirmed. | Wait. Bank transfers and USSD can take a few minutes. Don't send the goods yet. |
| **Processing** | Kwugwo confirmed the payment and it matches the order. | Send the goods or deliver the service. |
| **On hold** | Something needs your attention, for example the amount paid doesn't match the order, or a payment was reversed. | Read the order notes, check the payment in your Kwugwo dashboard, and don't send anything until it's sorted. |
| **Cancelled** | The order was cancelled before it was paid. Kwugwo cancels its payment request too, so the customer can't pay for it later. | Nothing. |

### "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.

> [!WARNING]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.