=== BMPF Payment Infrastructure ===
Contributors: xyno
Tags: payfast, payments, payment gateway, invoice, donations
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.1.6
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

PayFast payment infrastructure for WordPress, with reusable invoice and donation payment experiences for Bold Mark Creative integrations.

== Description ==

BMPF Payment Infrastructure (BMPF) is a modular WordPress payment foundation developed by Bold Mark Creative that integrates with PayFast for payment processing.

The Free Edition provides a reliable payment foundation for WordPress websites that need to accept invoice payments or donations through PayFast.

BMPF handles the payment infrastructure so website owners and developers do not need to implement PayFast transaction handling, signatures, ITN processing and transaction tracking themselves.

== Features ==

* PayFast Sandbox and Live environment support
* Merchant ID, Merchant Key and Passphrase settings
* PayFast payment request generation
* PayFast signature generation
* Secure payment redirects
* PayFast ITN REST endpoint
* ITN signature validation
* PayFast notification source validation
* Payment amount validation
* Server-side PayFast transaction confirmation
* Payment status handling
* Dedicated BMPF transaction database table
* Transaction creation and retrieval
* Transaction verification and status updates
* Transaction administration
* BMPF dashboard
* Public BMPF integration API
* Standalone invoice payments
* Decimal invoice amounts
* Invoice or Payment Reference field
* Standalone donations
* Suggested donation amount buttons
* Custom donation amounts
* Reusable payment configurations
* Enable/disable payment configurations
* Payment shortcodes
* Optional per-integration Pay Button Colour

== External Services ==

BMPF communicates with PayFast, a third-party payment service, to process payments and verify payment notifications.

When a payment is created, BMPF sends the payment request data required by PayFast, including the merchant identifier, payment amount, payment description, customer return URLs and the BMPF transaction reference. PayFast processes the payment on its own service.

PayFast sends an Instant Transaction Notification (ITN) to the BMPF endpoint configured for the site. BMPF validates the notification and performs a server-side confirmation request to PayFast before updating the transaction status.

For more information about PayFast's services, terms and privacy practices, see:

* PayFast General Terms & Conditions: https://payfast.io/legal/general-terms-conditions/
* PayFast Privacy Policy: https://payfast.io/privacy-policy/

== Invoice Payments ==

BMPF can provide a standalone invoice payment experience using the `[bmpf_payment]` shortcode.

The customer enters an invoice or payment reference and the amount to be paid. BMPF validates the request, creates the PayFast transaction and redirects the customer to PayFast.

Example:

`[bmpf_payment id="invoice-default"]`

Invoice references support letters, numbers and common reference characters including periods, underscores, slashes and hyphens.

== Donations ==

BMPF can provide a standalone donation payment experience using the same reusable payment shortcode system.

Suggested donation amounts can be configured alongside a custom donation amount.

Example:

`[bmpf_payment id="donation-default"]`

== Payment Flow ==

The standard BMPF payment lifecycle is:

1. A website requests a payment through BMPF.
2. BMPF validates the payment request.
3. BMPF creates a pending transaction.
4. BMPF generates the PayFast payment request and signature.
5. The customer is redirected to PayFast.
6. PayFast processes the payment.
7. PayFast sends an ITN notification to BMPF.
8. BMPF validates the notification.
9. BMPF locates the original transaction.
10. BMPF validates the payment amount.
11. BMPF confirms the transaction directly with PayFast.
12. BMPF updates the transaction according to the verified PayFast status.

== Transaction Protection ==

BMPF maintains its own transaction record for each payment attempt.

Verified transactions are protected against being treated as new active payments for the same payment reference.

Pending transactions are handled separately from completed transactions so that payment state can be tracked safely.

Existing transaction records are retained for administration and audit purposes.

== Payment Configuration ==

BMPF provides reusable payment configurations for standalone payment experiences.

Each configuration can define:

* Configuration name
* Configuration key
* Description
* Payment type
* Minimum amount
* Maximum amount
* PayFast payment name
* Suggested donation amounts where applicable
* Optional Pay Button Colour
* Enabled or disabled status

Configurations can be managed from the WordPress administration area.

== Public Integration API ==

BMPF includes a public integration API that allows other Bold Mark Creative systems and custom WordPress development to request payments through the central BMPF payment infrastructure.

This keeps PayFast handling, transaction creation, verification and payment state in one reusable payment layer.

== Current Status ==

The Free Edition currently provides the core payment foundation for invoice payments and donations.

The PayFast Sandbox payment lifecycle has been successfully tested, including payment creation, redirect, ITN receipt, notification validation, amount validation, server-side confirmation and transaction verification.

Standalone invoice payments and donations have also been implemented and tested, including decimal payment amounts and configurable donation amounts.

The plugin is intended to provide a stable foundation for future payment integrations while keeping the core payment engine reusable and independent.

== Screenshots ==

1. PayFast Sandbox configuration
2. Sandbox connection test
3. Live PayFast credentials
4. Creating a payment shortcode
5. Customising the success message and button colour
6. Managing payment shortcodes
7. BMPF payment form on a website
8. Customer payment flow
9. PayFast checkout
10. PayFast payment
11. PayFast processing
12. Success message displayed on the website
13. Verified transaction on the BMPF dashboard

== Development Roadmap ==

1. PayFast payment infrastructure — COMPLETE
2. Signature generation — COMPLETE
3. PayFast redirect — COMPLETE
4. ITN validation — COMPLETE
5. Server-side payment verification — COMPLETE
6. Transaction system — COMPLETE
7. Transaction administration — COMPLETE
8. BMPF dashboard — COMPLETE
9. Public integration API — COMPLETE
10. Standalone invoice payments — COMPLETE
11. Standalone donations — COMPLETE
12. Payment configuration system — COMPLETE
13. Free Edition 0.1.2 — COMPLETE
14. Additional payment integrations — FUTURE

== Architecture ==

BMPF is designed as a reusable payment infrastructure layer.

The core architecture consists of:

BMPF
|
+-- Payment Engine
+-- PayFast Signature Handling
+-- ITN Verification
+-- Transaction System
+-- Admin Dashboard
+-- Integration API
      |
      +-- Standalone Payment Experiences
      +-- Future Integrations

The payment engine remains responsible for PayFast communication and payment state, while individual payment experiences provide the customer-facing payment context.

== Security ==

BMPF validates payment requests server-side and does not rely solely on browser-side payment information.

PayFast ITN notifications are validated before transactions are updated.

Payment amounts are checked against the original transaction before a payment can be marked as verified.

Administrative actions use WordPress capability checks and nonces.

== Requirements ==

* WordPress 6.0 or later
* PHP 7.4 or later
* A PayFast merchant account

== Author ==

Bold Mark Creative

https://boldmark.co.za/

== Changelog ==

= 0.1.6 =
* Added an optional per-integration Pay Button Colour setting.
* Added front-end styling for custom payment button colours.
* Updated the short description to comply with WordPress.org length requirements.


= 0.1.5 =
* Updated the plugin identity and WordPress.org contributor metadata.
* Added PayFast external service documentation.
* Replaced direct inline JavaScript output with enqueued assets.
* Updated release metadata for the 0.1.5 remediation release.

= 0.1.3 =
* Added configurable success messages for verified invoice and donation payments.
* Added verified payment return handling with automatic status confirmation.
