=== CamPay Shortcode Payment Gateway ===
Tags: mobile money, orange money, mtn, payment button, shortcode
Requires at least: 5.3
Tested up to: 7.1
Requires PHP: 7.2
Stable tag: 1.7
License: GPLv3
License URI: https://www.gnu.org/licenses/gpl-3.0.html

Add a CamPay pay button anywhere with a shortcode and accept MTN Mobile Money, Orange Money and debit or credit card payments.

== Description ==

CamPay is a Cameroonian fintech service of TAKWID GROUP, running since January 2021. It lets businesses and organisations collect and send money online, mainly through MTN Mobile Money and Orange Money.

With this plugin you do not need a shop or a donation plugin: place the `[campay]` shortcode in any page or post and your visitors can pay you, for a fixed amount or an amount they choose.

= How visitors pay =

* **Mobile Money**: the visitor clicks the button, enters their MTN or Orange number and approves the payment on their phone. The payment window shows the instructions, a countdown and the result live. No prompt? They can dial *126# (MTN) or #150*50# (Orange) to approve pending payments.
* **Debit or credit card**: the visitor chooses "Debit or credit card", pays on a secure CamPay page and comes back to your success or failure page. Cards are only offered when you enable them and card payments are activated on your CamPay account.

= Features =

* One shortcode, as many buttons as you want on the same page
* Fixed amounts, or visitor-entered amounts with suggested amounts and limits
* MTN Mobile Money and Orange Money with operator detection, and debit or credit cards
* Optional extra field saved with each payment (room number, invoice number, full name…)
* Amounts in FCFA (XAF), US dollars or euros; USD and EUR are converted to XAF with your own rates
* Default "Payment successful" and "Payment not completed" pages, created on activation, with a receipt of the payment
* Payments list with totals, status, filters, search, CSV export and a details page
* Pending payments are re-checked automatically, and the webhook records late confirmations
* Every card return and webhook is checked with the CamPay signature and verified with the CamPay API
* Shortcode builder, connection test, demo mode, dashboard widget
* Real CamPay API errors in the logs and on each payment, visible to administrators only

= Shortcode attributes =

Every attribute is optional; missing ones use the defaults of CamPay > Settings > Payment form.

* `amount`: fixed amount. Leave it out to let the visitor enter the amount
* `amounts`: comma-separated suggested amounts, e.g. `amounts="1000,2000,5000"`
* `min_amount` / `max_amount`: limits for visitor-entered amounts
* `currency`: XAF (default), or USD / EUR when their conversion rate is enabled
* `product_title`: what the payment is for, shown in the payment window and the payments list
* `product_ref`: your own reference
* `button_text`: text of the button
* `success_url` / `failure_url`: pages to open after a successful or failed payment
* `extra_label` / `extra_required`: optional extra text field
* `class`: extra CSS class for the button

Examples:

* `[campay amount="2000" product_title="Membership" button_text="Pay"]`
* `[campay product_title="Donation" amounts="1000,5000,10000" button_text="Donate"]`

`[campay_payment_status]` shows the receipt of the payment the visitor just made. It is already on the default result pages.

== Installation ==

1. In your WordPress dashboard go to Plugins > Add New, search for "CamPay Shortcode Payment Gateway", then click Install and Activate. The "Payment successful" and "Payment not completed" pages are created.
2. Go to CamPay > Settings > Account.
3. Choose Live or Demo, enter the App Username and App Password of your CamPay app (demo and live apps have different credentials), click "Test connection", then save.
4. On the same tab, copy the Webhook URL into your CamPay app settings, and paste the app's Webhook Key into "Webhook key". Save.
5. On the Payment form tab, set your defaults: button text, currency, amounts, limits, redirects, extra field, colour.
6. Optional, on the Payment form tab: tick "Let visitors pay by debit or credit card" (the tab shows whether card payments are activated on your CamPay account), and enable USD and/or EUR with their conversion rates. Save.
7. Use the Shortcode builder tab to create your button, then paste the shortcode into any page, post or Shortcode block.

== Frequently Asked Questions ==

= Where do I find my App Username, App Password and Webhook Key? =

Log in to your CamPay dashboard, open your app and look under the app keys. The demo site (demo.campay.net) and the live site (campay.net) have different apps and credentials.

= Why don't visitors see the card option? =

"Card payments" must be ticked in CamPay > Settings > Payment form, and card payments must be activated on your CamPay account: the Payment form tab shows whether they are. If you use a page cache, clear it.

= Card payments fail with "Invalid redirect_url" =

CamPay refuses return addresses on localhost or private domains. Card payments need your site on a public domain. Mobile Money works everywhere.

= Can I use USD or EUR amounts? =

Yes. Enable the currency and set its rate in CamPay > Settings > Payment form, then use `currency="USD"` or `currency="EUR"`. The visitor sees the amount they are charged in FCFA before paying; it is rounded up to the next franc.

= A payment stays pending =

The visitor may not have approved it yet. Pending payments are re-checked with CamPay every 10 minutes, the webhook records late confirmations, and you can check a payment manually from its details page.

= Where can I see what went wrong with a payment? =

CamPay > Settings > Logs & maintenance lists the CamPay API errors, and each payment's details page shows the CamPay API response. They are visible to administrators only.

= Can I change the success and failure pages? =

Yes. Set other pages in CamPay > Settings > Payment form, or per button with `success_url` and `failure_url`. The default pages can be edited like any other page; keep `[campay_payment_status]` on them to show the receipt.

== External services ==

This plugin connects to the CamPay API (https://campay.net, or https://demo.campay.net in Demo mode) to process payments. It is required for the plugin to work.

* **Authentication**: when a payment is started, a status is checked, card availability is checked or you click "Test connection", your App Username and App Password are sent to get an access token.
* **Card availability**: on pages with a payment button, and in the settings, when card payments are enabled the plugin asks CamPay whether cards are activated on your account (the answer is cached for up to an hour).
* **Mobile Money payment**: when a visitor submits the payment window, the amount in XAF, the visitor's phone number, the payment title and reference, and a unique reference are sent. The payment status is then checked until it is confirmed, and pending payments are re-checked in the background.
* **Card payment**: when a visitor chooses to pay by card, the amount in XAF, the payment title and reference, a unique reference and the return address on your site are sent to create the payment page. The visitor enters card details on the CamPay page, not on your site.
* **Verification**: when the visitor comes back from the card page or CamPay calls the webhook, the transaction is fetched from CamPay to confirm it.

CamPay is provided by TAKWID GROUP: [terms and conditions](https://www.campay.net/static/docs/CamPay_Terms_and_Conditions.pdf), [privacy policy](https://www.campay.net/static/docs/CamPay_Privacy_Policy.pdf). API documentation: [CamPay API](https://documenter.getpostman.com/view/2391374/T1LV8PVA).

== Screenshots ==

1. CamPay settings
2. Payments list

== Changelog ==

= 1.7 - 2026-09-15 =
* New payment window: phone confirmation instructions, live status, countdown, retry, suggested amounts, operator detection, mobile friendly and accessible
* New: debit and credit card payments on the secure CamPay page, when activated on the CamPay account
* New: the pay button shows the Visa / Mastercard logo when card payments are available
* New: default "Payment successful" and "Payment not completed" pages with the `[campay_payment_status]` receipt
* New: webhook, secured with the CamPay signature (JWT signed with the app Webhook Key)
* New: USD and EUR amounts converted to XAF with manual rates
* Multiple buttons on the same page now work
* Payments list: status badges, totals, filters, search, CSV export, details page, refresh from CamPay
* Pending payments are re-checked automatically
* Dashboard widget
* Settings reorganised into tabs: Live/Demo switch, connection test, payment form defaults, shortcode builder, logs
* New: real CamPay API errors (HTTP status and response) in the logs and on the payment details, for administrators only
* New: webhook calls, card returns and transactions in CamPay > Settings > Logs & maintenance
* Logs moved from a publicly readable file to the database
* Buttons are no longer saved to the database on every page view; a cleanup tool removes old records
* Security: removed an unauthenticated URL handler that could mark payments as successful
* Security: card returns and webhooks are always verified with the CamPay API (reference and amount)
* The payment request no longer blocks a PHP worker for up to 15 minutes

= 1.6 - 2025-07-20 =
* Minor fixes
* Error logs

= 1.5 - 2025-05-03 =
* Fix: transactions not initiating

= 1.4 - 2024-11-19 =
* Credit card payments removed

= 1.3 - 2024-09-20 =
* Bug fixes

= 1.2 - 2023-04-15 =
* Added credit card payments

= 1.1 - 2023-04-15 =
* Stable tag update

= 1.0 - 2021-04-10 =
* First release

== Upgrade Notice ==

= 1.7 =
New payment window, payments list, card payments, USD/EUR conversion and a secured webhook. Security fix: payments could be marked as successful without being paid. After updating, set the Webhook URL and Webhook key of your CamPay app in CamPay > Settings > Account, and clear your page cache.
