Accept Mobile Money on WooCommerce with the DGateway Plugin

DGateway is a unified payment and commerce platform for Africa that lets businesses accept mobile money (MTN, Airtel) and card payments through a single integration. Its WordPress plugin brings these payment methods directly to your WooCommerce checkout.

WooCommerce powers millions of online stores worldwide, including a growing number in East Africa. But out of the box, WooCommerce does not support mobile money — the dominant payment method in the region. The DGateway WordPress plugin changes that.

In this guide, you will install the plugin, configure it, test your checkout flow, and go live. By the end, your WooCommerce store will accept MTN Mobile Money, Airtel Money, and card payments — whether you are selling physical goods, digital downloads, or subscription services.

Why You Need This

If you run a WooCommerce store targeting customers in Uganda, Kenya, Tanzania, or Rwanda, you already know the challenge. Your customers want to pay with mobile money. But WooCommerce's built-in payment options are designed for card-based markets.

Consider the numbers: In Uganda alone, over 30 million mobile money accounts are active, while fewer than 5 million people hold bank cards. In rural areas, mobile money is often the only digital payment method available. If your store only accepts Visa and Mastercard, you are locking out the vast majority of your potential customers.

You could build a custom integration from scratch, but that means writing code to handle payment initiation, callback processing, order status updates, and error handling. The DGateway plugin does all of this for you in a few clicks.

Plugin vs. Custom API Integration

Not sure whether to use the plugin or build a custom integration? Here is a side-by-side comparison:

Use the plugin if you are running a WooCommerce store and want the fastest path to accepting mobile money. Use the custom API if you are building a custom application, need full control over the payment flow, or are not using WordPress.

Prerequisites

Before you begin, ensure you have:

• A WordPress site (version 5.8 or later) with WooCommerce installed and activated (version 5.0+).
• A DGateway account. Sign up at dgateway.io if you do not have one.
• Your DGateway API keys (both test and live). Find these under Settings > API Keys in your DGateway dashboard.
• WordPress admin access.
• PHP 7.4 or later (PHP 8.1+ recommended).
• An SSL certificate on your domain (required for webhook delivery).

Getting Your API Keys

If you have not generated API keys yet, here is how:

1. Log in to your DGateway dashboard at dgatewayadmin.desispay.com.
2. Navigate to your app and click Settings in the sidebar.
3. Scroll to the API Keys section.
4. Click Generate New Key. You will see two values:
   • Public Key — starts with dgw_pk_test_ (test) or dgw_pk_live_ (live)
   • Secret Key — starts with dgw_sk_test_ (test) or dgw_sk_live_ (live)
5. Copy both keys immediately. The secret key is only shown once.

Important: Keep your secret key safe. Never commit it to version control or expose it in client-side code. The plugin stores it encrypted in your WordPress database.

Step 1: Install the Plugin

There are two ways to install the DGateway plugin.

Option A: Install from WordPress Plugin Directory

1. Log in to your WordPress admin dashboard.
2. Navigate to Plugins > Add New.
3. Search for "DGateway" in the search bar.
4. Find the "DGateway Payment Gateway for WooCommerce" plugin and click Install Now.
5. Once installed, click Activate.

Option B: Upload Manually

1. Download the plugin ZIP file from the DGateway docs page or your DGateway dashboard.
2. In your WordPress admin, go to Plugins > Add New > Upload Plugin.
3. Choose the ZIP file and click Install Now.
4. Click Activate after installation completes.

Option C: Install via WP-CLI

If you prefer the command line, use WP-CLI:

# Download the plugin ZIP from DGateway
curl -O https://dgateway.desispay.com/downloads/dgateway-plugin-v1.0.2.zip
 
# Install and activate
wp plugin install dgateway-plugin-v1.0.2.zip --activate
 
# Verify installation
wp plugin list | grep dgateway

After activation, you should see "DGateway" in your WordPress admin sidebar under WooCommerce > Settings > Payments.

Step 2: Configure the Plugin

With the plugin activated, configure it to connect to your DGateway account.

1. Navigate to WooCommerce > Settings > Payments.
2. You will see "DGateway" listed as a payment method. Click Manage (or Set up).
3. Configure the following settings:

General Settings

• Enable/Disable — Toggle to enable DGateway as a payment option on your checkout page.
• Title — The payment method name displayed to customers. Default is "Mobile Money / Card Payment." You can customize this to something like "Pay with Mobile Money" or "MTN / Airtel Money."
• Description — A brief description shown on the checkout page. For example: "Pay securely using MTN Mobile Money, Airtel Money, or your debit/credit card."

API Credentials

• Test Mode — Enable this during setup and testing. When test mode is on, no real money is charged.
• Test Secret Key — Paste your test secret key from the DGateway dashboard.
• Test Public Key — Paste your test public key.
• Live Secret Key — Paste your live secret key (used when test mode is off).
• Live Public Key — Paste your live public key.

Payment Options

• Accepted Methods — Choose which payment methods to offer. Options typically include MTN Mobile Money, Airtel Money, and Card Payments. Enable the ones relevant to your market.
• Default Currency — Set to match your WooCommerce store currency. DGateway supports UGX, KES, TZS, RWF, and USD.

Webhook Configuration

The plugin automatically registers a webhook URL with DGateway. You can find this URL in the plugin settings — it will look something like:

https://yourstore.com/?wc-api=dgateway_webhook

Make sure this URL is accessible from the internet. If you are testing locally, you will need a tool like ngrok to expose your local server:

# Expose your local WordPress to the internet for webhook testing
ngrok http 80
 
# You will get a URL like: https://abc123.ngrok.io
# Use this as your WordPress site URL temporarily

4. Click Save Changes.

Verifying Your Configuration

After saving, the plugin will attempt to validate your API keys by making a test request to the DGateway API. If the keys are valid, you will see a green checkmark. If not, double-check that you copied the full key string including the prefix.

You can also verify manually with cURL:

# Test your API key (replace with your actual key)
curl -X GET https://api.dgateway.desispay.com/v1/health \
  -H "Authorization: Bearer dgw_sk_test_your_key_here" \
  -H "Content-Type: application/json"
 
# Expected response:
# { "data": { "status": "ok", "app": "Your App Name" } }

Step 3: Test Your Checkout

Before accepting real payments, test the entire flow.

1. Ensure Test Mode is enabled in the plugin settings.
2. Add a product to your cart on your store's frontend.
3. Proceed to checkout.
4. You should see DGateway listed as a payment option. Select it.
5. Enter a test phone number. DGateway's test mode accepts specific numbers for simulating different outcomes:

6. Click Place Order.

After placing the order, you will see a "waiting for payment confirmation" screen. In test mode, the payment will automatically complete after a few seconds.

Check your WooCommerce orders to verify:

• The order status changed to Processing (for successful payments) or Failed (for failed payments).
• The order notes include the DGateway transaction ID.
• The payment method is recorded as DGateway.

What Happens Behind the Scenes

When a customer places an order, here is the technical flow:

1. The plugin sends a POST request to the DGateway Collect API:

// What the plugin sends to DGateway
{
  "phone_number": "256700000001",
  "amount": 50000,
  "currency": "UGX",
  "provider": "mtn",
  "reason": "WooCommerce Order #1042",
  "metadata": {
    "order_id": 1042,
    "customer_email": "customer@example.com",
    "source": "woocommerce"
  }
}

2. DGateway initiates the mobile money USSD push to the customer's phone.
3. The customer enters their PIN on their phone.
4. DGateway receives confirmation from the provider (MTN/Airtel).
5. DGateway sends a webhook to your store's callback URL with the transaction result:

// Webhook payload from DGateway
{
  "event": "transaction.completed",
  "data": {
    "id": "txn_abc123",
    "status": "successful",
    "amount": 50000,
    "currency": "UGX",
    "provider": "mtn",
    "phone_number": "256700XXXXX",
    "metadata": {
      "order_id": 1042
    }
  }
}

6. The plugin updates the WooCommerce order status to "Processing" and records the transaction ID.

Step 4: Go Live

Once you are satisfied that everything works in test mode:

1. Go to WooCommerce > Settings > Payments > DGateway.
2. Disable Test Mode.
3. Verify that your live API keys are entered correctly.
4. Click Save Changes.

Your store is now accepting real mobile money and card payments.

Post-Launch Checklist

After going live, verify the following:

• Make a small real purchase. Pay with your own mobile money account to confirm the full flow works with real money. Try a UGX 500 product.
• Check settlement. Log in to your DGateway dashboard and verify that the payment appears in your transactions and that settlement is configured correctly.
• Monitor the first few days. Watch for failed payments, webhook delivery issues, or customer complaints. Address any issues promptly.
• Set up notifications. Configure email or SMS alerts in your DGateway dashboard for transaction events.
• Verify the commission. DGateway charges 8% per transaction (configurable by the super admin). Check that the net amount in your wallet matches expectations.

Standalone Payment Buttons (No WooCommerce Required)

The DGateway plugin is not limited to WooCommerce checkout. You can embed payment buttons anywhere on your WordPress site using shortcodes — even on pages, posts, or widget areas that have nothing to do with WooCommerce.

Basic Payment Button

[dgateway_pay amount="25000" currency="UGX" reason="Donation to Our Church"]

This renders a styled button that opens the DGateway payment modal when clicked. The customer enters their phone number, selects MTN or Airtel, and pays.

Open-Amount Payment Button

[dgateway_pay min_amount="5000" currency="UGX" reason="Pay What You Want" open_amount="true"]

The customer chooses how much to pay, with a minimum of UGX 5,000. Perfect for donations, tips, or pay-what-you-want products.

Styled Payment Button

[dgateway_pay amount="100000" currency="UGX" reason="Annual Membership Fee"
  button_text="Pay Membership Fee - UGX 100,000"
  button_color="#6c5ce7"
  button_text_color="#ffffff"
  success_url="https://yoursite.com/thank-you"
  cancel_url="https://yoursite.com/membership"]

Subscription Payment Button

The plugin supports recurring payments for subscription products:

[dgateway_subscribe plan_id="plan_monthly_gym" button_text="Subscribe - UGX 50,000/month"]

This creates a subscription in DGateway and charges the customer on the configured interval (weekly, monthly, or yearly).

WooCommerce Cart/Checkout Blocks Support

Starting with plugin version 1.0.2, DGateway fully supports WooCommerce's new block-based checkout (available in WooCommerce 8.0+). This is the checkout experience built on WordPress's block editor (Gutenberg).

What This Means

• The DGateway payment option appears correctly in the block-based checkout.
• The phone number field renders inline within the block checkout form.
• Payment confirmation and order status updates work identically to the classic checkout.
• The plugin is compatible with High-Performance Order Storage (HPOS), WooCommerce's newer database architecture.

Checking Your Checkout Type

Not sure which checkout your store uses? Here is how to check:

1. Go to Pages in your WordPress admin.
2. Find the "Checkout" page and click Edit.
3. If you see a [woocommerce_checkout] shortcode, you are using the classic checkout.
4. If you see a "Checkout" block in the block editor, you are using the block-based checkout.

Both work with the DGateway plugin. No additional configuration needed.

Subscription Products

The DGateway plugin adds a "DGateway Subscription" product type to WooCommerce. This lets you sell subscription-based products that automatically charge customers on a recurring basis.

Creating a Subscription Product

1. Go to Products > Add New in WordPress admin.
2. In the Product Data dropdown, select DGateway Subscription.
3. Set the following:
   • Subscription Price — e.g., UGX 50,000
   • Billing Interval — Weekly, Monthly, or Yearly
   • Trial Period — Optional free trial (in days)
4. Publish the product.

When a customer purchases this product, the plugin creates a DGateway subscription and handles all future billing automatically. If a payment fails, DGateway retries with exponential backoff before marking the subscription as past due.

Managing Subscriptions

View active subscriptions in your DGateway dashboard under Subscriptions. Each subscription shows:

Testing with Test API Keys

DGateway provides a complete test environment so you can develop and test without real money. Here is what you need to know:

Test Mode Behavior

Simulating Different Scenarios

Use the test phone numbers to simulate various outcomes:

# Simulate a successful MTN payment
curl -X POST https://api.dgateway.desispay.com/v1/collect \
  -H "Authorization: Bearer dgw_sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "256700000001",
    "amount": 50000,
    "currency": "UGX",
    "provider": "mtn",
    "reason": "Test Order"
  }'
 
# Simulate a failed payment
curl -X POST https://api.dgateway.desispay.com/v1/collect \
  -H "Authorization: Bearer dgw_sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "256700000002",
    "amount": 50000,
    "currency": "UGX",
    "provider": "mtn",
    "reason": "Test Failure"
  }'

Safety note: DGateway blocks test phone numbers when used with live API keys. This prevents accidental test transactions from counting as real revenue.

Customizing the Checkout Experience

The DGateway plugin integrates with WooCommerce's standard checkout flow, which means it works with most WooCommerce-compatible themes. However, you can further customize the experience:

Custom Checkout Fields

The plugin adds a phone number field to the checkout form for mobile money payments. You can customize the field label and placeholder text in the plugin settings.

The phone number field validates the format automatically. Accepted formats:

• 256XXXXXXXXX (international format with country code)
• 0XXXXXXXXX (local format)

Invalid formats display a clear error message to the customer.

Order Status Mapping

By default, successful payments set the order status to "Processing." You can change this mapping in the plugin settings if your workflow requires a different status.

Email Notifications

WooCommerce's built-in email notifications work with DGateway payments. Customers receive order confirmation emails when payment is successful, and you receive new order notifications.

You can customize these emails under WooCommerce > Settings > Emails. The DGateway transaction ID is included in the order details section of all emails.

Adding Custom CSS

To style the DGateway payment option on your checkout page, add custom CSS to your theme:

/* Style the DGateway payment method */
.payment_method_dgateway {
  border: 2px solid #6c5ce7;
  border-radius: 8px;
  padding: 16px;
}
 
.payment_method_dgateway label {
  font-weight: 600;
  color: #2d3436;
}
 
/* Style the phone number input */
.dgateway-phone-field input {
  border: 1px solid #dfe6e9;
  border-radius: 6px;
  padding: 10px 14px;
  font-size: 16px;
}

Troubleshooting FAQ

The plugin does not appear in WooCommerce payment settings

Possible causes:

• WooCommerce is not activated. Go to Plugins and ensure WooCommerce is active.
• The DGateway plugin is installed but not activated. Check Plugins > Installed Plugins.
• Your WooCommerce version is below 5.0. Update WooCommerce.
• Plugin file permissions are incorrect. Ensure the plugin files are readable by your web server.

# Fix permissions (Linux/macOS server)
chmod -R 755 wp-content/plugins/dgateway-payment-gateway/
chown -R www-data:www-data wp-content/plugins/dgateway-payment-gateway/

Payments fail with "Invalid API Key" error

• Verify you are using the correct key type. Test mode requires test keys (dgw_sk_test_), live mode requires live keys (dgw_sk_live_).
• Check for extra whitespace when pasting keys.
• Generate new keys if the old ones were compromised or revoked.

Webhook not received — order stays in "Pending Payment"

1. Check that your webhook URL is publicly accessible:

# Test webhook URL accessibility
curl -I https://yourstore.com/?wc-api=dgateway_webhook
# Should return HTTP 200 or 302

2. Check the DGateway dashboard for webhook delivery logs. Failed deliveries show the HTTP status code and response body.
3. If you are behind Cloudflare or a CDN, ensure the webhook URL is not cached or blocked by firewall rules.
4. Check your WordPress error log:

// Add to wp-config.php to enable logging
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
 
// Check the log
// Location: wp-content/debug.log

Customer sees "Payment processing" but nothing happens

• The USSD prompt may not have reached the customer's phone. This can happen if the provider line is experiencing issues.
• Check the DGateway System Health page for provider status. If a line is down, DGateway will show a banner.
• The customer may have entered the wrong PIN or cancelled the USSD prompt. Ask them to try again.

Plugin conflicts with other payment plugins

Deactivate other payment gateway plugins one by one to identify conflicts. Common culprits:

• Other mobile money plugins that hook into the same WooCommerce filters.
• Caching plugins that cache the checkout page (disable caching for /checkout/ and /?wc-api=*).
• Security plugins that block POST requests from external servers (whitelist DGateway's IP range).

"Currency not supported" error at checkout

DGateway supports: UGX, KES, TZS, RWF, USD, EUR, and GBP. Make sure your WooCommerce store currency matches one of these. Set it under WooCommerce > Settings > General > Currency.

Frequently Asked Questions

Does the plugin work with block-based checkout? Yes, the DGateway plugin supports both the classic and block-based WooCommerce checkout (v1.0.2+). It is also compatible with HPOS (High-Performance Order Storage).

Can I accept payments in multiple currencies? Yes, as long as your WooCommerce store supports multiple currencies. The plugin sends the order currency to DGateway, which handles the processing. If you use a multi-currency plugin like WPML or WooCommerce Multicurrency, each order is processed in its displayed currency.

What happens if a customer's payment times out? The order is placed in a "Pending Payment" status. If the customer completes the payment later (within the timeout window), the webhook updates the order automatically. WooCommerce will also cancel unpaid orders after a configurable period (default: 60 minutes).

Is the plugin free? The plugin itself is free. You only pay DGateway's standard transaction fees on successful payments (8% default, configurable).

What is the minimum transaction amount? The minimum depends on the provider. For MTN Mobile Money in Uganda, the minimum is UGX 500. For Airtel Money, it is UGX 500. For card payments via Stripe, the minimum is the equivalent of USD 0.50.

Can I use the plugin without WooCommerce? Yes. The standalone payment button shortcodes work on any WordPress page or post without WooCommerce. You only need WooCommerce for the cart/checkout integration.

How do I update the plugin? When a new version is available, you will see an update notification in Plugins > Installed Plugins. Click Update Now. You can also download the latest version from the DGateway docs page and upload it manually.

Does it work with WordPress multisite? Yes, but each site in the multisite network needs its own DGateway API keys configured independently.

What's Next

You now have a fully functional WooCommerce store that accepts mobile money and card payments. Here are some next steps to consider:

• Set up subscription products — If you sell recurring services (gym memberships, SaaS, content access), create DGateway Subscription products.
• Add standalone payment buttons — Use shortcodes to accept donations, event registrations, or one-off payments on non-shop pages.
• Enable the DGateway store — List your products on the DGateway marketplace to reach buyers beyond your own website.
• Monitor transactions — Use the DGateway dashboard for real-time transaction monitoring, settlement tracking, and revenue analytics.
• Explore the API — If you need custom integrations beyond what the plugin offers, the DGateway API documentation covers every endpoint.

The DGateway WooCommerce plugin bridges the gap between WordPress and mobile money. In less than fifteen minutes, you can transform your WooCommerce store into a fully functional e-commerce platform that accepts the payment methods your East African customers actually use.

Install the plugin, configure your keys, test your checkout, and start selling. It is that straightforward.