Accepting mobile money in WooCommerce

Install

WooCommerce is served by the WordPress and WooCommerce client. There is no WooCommerce-specific package, and this page does not pretend otherwise: what is below is that client, used the way WooCommerce is written.

Upload the plugin from sdks/ultraner-wordpress, then activate it

The snippets below are checked in CI against the API's own schemas. This client is not yet driven end to end against the sandbox the way the Node one is.

The WooCommerce trap

Set the webhook URL in the plugin settings, not in your Ultraner dashboard alone. WooCommerce marks the order paid from the webhook, so a missing URL leaves paid orders sitting on hold.

Taking a payment

Two things this shows that are easy to get wrong anywhere. The amount is in whole units for most African currencies, so 5000 TZS is five thousand shillings and not fifty. And provideris the network's provider code, not its brand name: Mixx by Yas is still Tigo on the wire.

// No code. The plugin registers Ultraner as a WooCommerce payment gateway.
//
//   WooCommerce -> Settings -> Payments -> Ultraner
//     API key          uk_live_... (or uk_test_... to try it first)
//     Webhook secret   from the same dashboard page
//     Webhook URL      https://your-shop.example.com/?wc-api=ultraner
//
// To change which networks appear at checkout, filter them:

add_filter('ultraner_enabled_providers', function ($providers) {
    return ['Vodacom', 'Tigo'];   // provider codes, not brand names
});

The response means the request was accepted, not that money moved. A mobile-money charge sends a prompt to the payer's handset and they may take a minute, or never answer. Which is why the next section is not optional.

Receiving the result

The webhook is how you learn a payment succeeded. Verify the signature over the raw bytes before trusting anything in the payload, acknowledge quickly, and do the work afterwards: a slow handler gets retried, and retries mean you will see the same event twice.

// The plugin verifies and handles the webhook for you. To react to it:

add_action('ultraner_payment_completed', function ($order_id, $event) {
    $order = wc_get_order($order_id);
    // The plugin has already marked it paid. This is for your own work.
    $order->add_order_note('Paid via ' . $event['provider']);
}, 10, 2);

// Orders stuck on hold almost always mean the webhook URL is unset or
// unreachable, not that the payment failed.