Installing the Papi WooCommerce plugin

The Papi WooCommerce plugin allows you to integrate the Papi payment aggregator into a WordPress WooCommerce store.

It allows you to accept payments by Mobile Money (MVola, Orange Money, Airtel Money) and by Visa and Mastercard cards in Madagascar.

Prerequisites

Before installing the plugin, check the following points:

• You are using WordPress 5.0 or later
• You are using WooCommerce 3.0 or later (tested up to 9.9)
• Your site uses PHP version 7.2 minimum
• You have created a store with Papi with a store API key
• Your WooCommerce store is configured to use the MGA currency (Malagasy Ariary)

Download the plugin

Download the official Papi WooCommerce plugin Zip file from the Downloads page.

Use the latest release unless Papi support has specifically asked you to install another version. The Downloads page lists official releases from newest to oldest, with each release's Zip file, SHA-256 checksum, compatibility notes, and changelog.

After downloading the file, keep it as a Zip archive. You do not need to unzip it before installing it from the WordPress back office.

Install the plugin from the WordPress back office

Installation by upload

1. In the WordPress back office, open Plugins → Add New Plugin.
2. Click Upload Plugin.
3. Select the downloaded papi-woocommerce-gateway.zip file.
4. Click Install Now.
5. Once the installation completes, click Activate Plugin.
6. Go to WooCommerce → Settings → Payments and click Manage next to Papi Payment to configure it.

Manual installation via FTP

Use manual installation only if your WordPress back office cannot upload the plugin Zip file.

1. Extract the downloaded papi-woocommerce-gateway.zip file on your computer.
2. Check that the extracted folder is named papi-woocommerce-gateway.
3. Copy the papi-woocommerce-gateway/ folder into the wp-content/plugins/ directory of your WordPress installation.
4. In the WordPress back office, open Plugins.
5. Find Papi Payment Gateway for WooCommerce and click Activate.

Mandatory MGA currency configuration

Papi currently accepts payments only in Malagasy Ariary (MGA). If the WooCommerce store is not configured with MGA as the active currency, the Papi payment option will not appear at checkout.

Set MGA as the WooCommerce currency

1. In the WordPress back office, open WooCommerce → Settings → General.
2. In the Currency field, select Malagasy ariary (Ar).
3. Save the settings.

Once MGA is selected, prices will be displayed in Ar on product pages and in the cart.

Plugin configuration

1. In the WordPress back office, open WooCommerce → Settings → Payments.
2. Click Manage next to Papi Payment.
3. Fill in the required fields.

Field	Description
Enable/Disable	Activate the Papi payment method at checkout. Disabled by default.
Title	The label the customer sees at checkout. Default: Paiement Mobile Money / Carte.
Description	The description shown below the payment option. Default: Payez par MVola, Airtel Money, Orange Money ou carte bancaire.
Papi API key	Your store API key from dashboard.papi.mg under Boutiques → Developer.

After saving, the Papi payment method is immediately available at checkout.

Papi webhook configuration

The webhook is the URL of your store called by Papi after each payment status change. This mechanism allows WooCommerce to automatically update the order status.

In production

The notification URL is generated automatically by the plugin. No manual configuration is required in WooCommerce.

In the Papi dashboard, configure your store notification URL. The URL follows this format:

https://your-store.mg/?wc-api=wc_gateway_papi

If your WordPress installation uses pretty permalinks, the URL may also appear as:

https://your-store.mg/wc-api/wc_gateway_papi/

The notification URL must be publicly accessible from the Internet. A local server, a server behind a VPN, or an environment that is not publicly exposed will not receive Papi notifications.

In local development

If WordPress is running locally, for example on http://localhost/my-store, Papi cannot directly call your machine.

Two approaches are possible.

Option A: ngrok tunnel

1. Install and configure ngrok.
2. Start a tunnel to your local port:

ngrok http 80

3. Retrieve the public URL provided by ngrok, for example https://abc123.ngrok-free.app.
4. In the Papi dashboard, set the notification URL to:

https://abc123.ngrok-free.app/?wc-api=wc_gateway_papi

Option B: direct command-line test

To test webhook processing without going through Papi, retrieve a valid JSON payload and replay it directly to your local WordPress.

First retrieve the _papi_notification_token meta value for the order you want to test. You can find it in the WordPress database (wp_postmeta or wp_wc_orders_meta if HPOS is enabled) or directly from the WooCommerce order screen under Custom Fields.

Then send a test notification.

PowerShell example:

$body = '{"paymentStatus":"SUCCESS","merchantPaymentReference":"WC-123","notificationToken":"YOUR_TOKEN","paymentMethod":"MVOLA","currency":"MGA","amount":8000}'
Invoke-WebRequest -Uri "http://localhost/my-store/?wc-api=wc_gateway_papi" `
  -Method POST `
  -ContentType "application/json" `
  -Body $body

curl example:

curl -X POST "http://localhost/my-store/?wc-api=wc_gateway_papi" \
  -H "Content-Type: application/json" \
  -d '{"paymentStatus":"SUCCESS","merchantPaymentReference":"WC-123","notificationToken":"YOUR_TOKEN","paymentMethod":"MVOLA","currency":"MGA","amount":8000}'

A 200 OK response with {"success":true} confirms the webhook was processed correctly.

Purchase flow verification

Before going live, test the full flow:

1. Select a product and add it to the cart.
2. Go to checkout.
3. At the payment step, check that Papi Payment appears with the Papi logo.
4. Select Papi Payment and click Place Order.
5. Check that WooCommerce creates an order with the Pending payment status.
6. Check the redirect to the Papi-hosted payment page.
7. Complete a test payment on the Papi page.
8. Return to the store and check the order confirmation page.
9. After receiving the webhook, check that the order status changes to Processing or Completed in the WooCommerce back office.

Order statuses

WooCommerce status	When	Notes
Pending payment	As soon as the customer is redirected to the Papi payment page	The cart is cleared at this point.
Processing	SUCCESS webhook received	Triggered by payment_complete(). WooCommerce may move to Completed automatically depending on your product settings.
Failed	FAILED webhook received	The order note contains the failure reason returned by Papi.
Pending payment (note added)	PENDING webhook received	The order status is unchanged; a note is added to indicate the payment is awaiting confirmation.

Logs

The plugin writes all webhook events to the WooCommerce log system. Logs are accessible from WooCommerce → Status → Logs. Select the source papi-gateway from the dropdown.

Log level	When
info	Every incoming webhook notification (full payload).
warning	Malformed notification received (missing required fields).
error	Order not found for reference, or notification token mismatch.

Log files are stored in wp-content/uploads/wc-logs/ and are rotated automatically by WooCommerce.

Technical points to watch

Payment link validity period

The Papi payment link is valid for 60 minutes after creation. If the customer does not complete payment within that time, the link expires. The order remains in Pending payment status and can be canceled manually from the WooCommerce back office.

Multiple orders on the same cart

WooCommerce creates the order and clears the cart before redirecting to Papi. If the customer abandons payment and returns to the store, the cart will be empty. The old order remains in Pending payment and can be manually canceled from the back office if necessary.

Block-based checkout

The plugin is fully compatible with both the classic WooCommerce checkout and the WooCommerce block-based checkout (Cart & Checkout blocks, default since WooCommerce 8+).

HPOS compatibility

The plugin is compatible with WooCommerce High-Performance Order Storage (HPOS / custom order tables). All order data is read and written using the WooCommerce order API.

No HTTPS in development

WooCommerce may display a warning when the store is not running over HTTPS. This does not prevent the Papi payment method from appearing at checkout in a development environment. In production, HTTPS is required.

Plugin structure

papi-woocommerce-gateway/
├── papi-woocommerce-gateway.php
├── uninstall.php
├── readme.txt
├── assets/
│   ├── logo-papi-full.svg
│   └── zone.png
└── includes/
    └── class-papi-delivery-fee-module.php

File	Role
papi-woocommerce-gateway.php	Main plugin file. Declares the WC_Gateway_Papi payment gateway class, registers WooCommerce feature compatibility (HPOS, block checkout), and loads the delivery fee module.
uninstall.php	Executed when the plugin is deleted from the WordPress back office. Removes all plugin options and order meta from the database.
readme.txt	WordPress.org standard plugin readme.
assets/logo-papi-full.svg	Papi logo displayed at checkout next to the payment method name.
assets/zone.png	Delivery zone map image (reserved for a future release).
includes/class-papi-delivery-fee-module.php	Zone-based delivery fee module (disabled in v1.0, planned for a future release).

Order meta keys

The plugin stores the following metadata on WooCommerce orders.

Meta key	Description
_papi_payment_reference	Merchant reference sent to Papi, in the format WC-{order_number}.
_papi_notification_token	Security token returned by Papi when creating the payment link. Used to verify incoming webhooks.
_papi_payment_link	URL of the Papi-hosted payment page.
_papi_merchant_reference	Merchant reference confirmed in the SUCCESS webhook.
_papi_payment_method	Payment method used by the customer (e.g. MVOLA, AIRTEL_MONEY, ORANGE_MONEY).

Uninstallation

Uninstallation from Plugins → Installed Plugins → Delete performs the following operations:

• Deletion of the gateway settings (woocommerce_papi_gateway_settings WordPress option).
• Deletion of all Papi-related order meta from the database (both the classic wp_postmeta table and the HPOS wp_wc_orders_meta table if present).

Deletion of order meta is irreversible. If the transaction history must be preserved, back up the relevant meta keys before uninstalling the plugin.