WooCommerce
Install TeePay for WooCommerce, connect your keys and webhooks, test and go live.
TeePay for WooCommerce adds mobile money to your WordPress store. Customers pay with M-Pesa, Airtel Money, Mixx by Yas or HaloPesa, in Tanzanian shillings.
- Requires
- WordPress 6.2+, WooCommerce 7.6+, PHP 7.4+
- Checkout
- Classic checkout and the Cart and Checkout blocks
- Order storage
- Compatible with High-Performance Order Storage (HPOS)
- Markets
- Tanzania (TZ), TZS
Choose a payment flow
| Flow | What the customer does | Needs |
|---|---|---|
| Hosted checkout (recommended) | Is sent to TeePay's checkout page, pays, and returns to your store. | checkout_sessions in capabilities |
| Mobile money prompt | Enters a Tanzanian mobile number at checkout and approves the prompt on their phone, without leaving your store. | Mobile money push enabled on your account (collection_create) |
The prompt flow accepts numbers such as 0712 345 678, +255 712 345 678 or 712345678 and sends
them as +255712345678. Numbers that are not Tanzanian mobile numbers are rejected at checkout.
Install
Add the plugin
Download teepay-for-woocommerce.zip from TeePay's releases. In WordPress go to Plugins → Add New →
Upload Plugin, upload the zip and click Activate. WooCommerce must be active.
Open the settings
Go to WooCommerce → Settings → Payments → TeePay. The screen shows the two addresses you need in the next step:
| Address | |
|---|---|
| Webhook URL | https://your-store.example/wc-api/teepay_webhook/ |
| Return URL | https://your-store.example/wc-api/teepay_return/ |
Set up your payment profile
In the TeePay dashboard open Payment profiles, pick your default profile (or create one for this store) and set its Webhook URL and Return URL to the addresses above. Then open Developers → Webhooks and create the signing secret.
Enter your keys and save
Paste your live secret key and webhook signing secret, choose the payment flow, tick Enable TeePay
mobile money and click Save changes. The plugin checks the key with GET /v1/capabilities and
shows the result at the top of the page.
Settings
Prop
Type
Keys and secrets are saved as password fields and never shown again: the field stays empty and says Saved. Leave it blank to keep the saved value, or tick Remove the saved value to delete it. A live key in the sandbox field (or the other way round) is not saved.
How orders are confirmed
When a customer places an order the plugin creates a checkout session
(or sends a prompt) with an Idempotency-Key derived from the order, total and attempt, so a retry
never creates a second session. The order stays Pending payment until TeePay confirms it.
An order is marked paid only when the plugin reads the payment from the TeePay API with your secret key and all of these hold:
- the session
statusispaidwith apayment.reference(or the collectionstatusissucceeded); - the session's
id,referenceandenvironmentbelong to this order and this store; amount_minorandcurrencyequal the order total and currency exactly.
The read happens when a signed webhook arrives, when the customer returns, while the order received page waits, and every 15 minutes for unpaid orders from the last two days. The TeePay payment reference becomes the order's transaction ID.
If TeePay reports a payment whose amount or currency differs from the order, for example because the order was edited after the customer paid, the order is put On hold with a note and is never completed automatically. Check the payment in the TeePay dashboard before you ship.
Test in sandbox
Sandbox keys confirm that your key, scopes and settings work, but money moves in the live environment only.
- Tick Sandbox mode, paste your
tp_test_key and sandbox signing secret, and save. - The notice at the top of the settings page should say Connected to TeePay sandbox.
- Shoppers see SANDBOX MODE: no money will move under the payment method, so turn sandbox mode off before you launch.
Go live
- Untick Sandbox mode, paste your live key and live signing secret, and save. The notice should
say Connected to TeePay (live) and list
TZS. - Check that your store currency is Tanzanian shilling (TZS). TeePay only appears at checkout for currencies your key can collect in.
- Place a real order for a small amount and pay it from your own phone.
- Confirm the order moves to Processing with a note that starts with TeePay payment confirmed,
and that Developers → Webhooks shows the delivery with status
200.
See the go-live checklist for the rest of your setup.
Refunds
The TeePay API does not offer refunds yet, so the plugin cannot refund from WooCommerce. Arrange the refund with TeePay and record it in WooCommerce as a manual refund.