Download the PHP package moolre/moolre-php without Composer

Moolre PHP SDK

Framework-agnostic PHP package for initiating Moolre hosted payments and verifying transactions from any PHP application.

This package was extracted from the working Moolre WooCommerce gateway flow. It uses the same Moolre API endpoint:

• state=starter starts a payment and returns data.authorization_url
• POST /open/transact/status verifies a transaction by reference

Requirements

• PHP 7.4 or newer
• JSON extension
• cURL extension recommended, with PHP streams used as a fallback
• HTTPS access to the Moolre API

For integration testing only, set MOOLRE_FORCE_STREAMS=1 to exercise the PHP-stream transport even when cURL is installed.

Installation

Install with Composer:

Until the package is published to Packagist, install it into an app as a local path repository:

For development inside this package:

Example Project

A complete raw PHP demo app is included at examples/raw-php-app. It shows a cart checkout, payment initiation, webhook callback handling, customer redirect verification, and a small local JSON order store.

Run it from the SDK repository:

Set your credentials before starting the server:

Then edit .env with your Moolre values. You can also set environment variables directly:

On Windows PowerShell:

Then edit .env, or set variables in the same terminal:

Then open http://localhost:8080. If Moolre needs to call your local callback/webhook, expose the app through a tunnel and set APP_URL to the public tunnel URL.

Live and Sandbox Mode

The raw PHP example uses MOOLRE_PRODUCTION as the environment switch:

• MOOLRE_PRODUCTION=true: live mode, using https://api.moolre.com/embed/src/start
• MOOLRE_PRODUCTION=false or unset: sandbox mode, using https://sandbox.moolre.com/embed/src/start

Live payment initiation requires MOOLRE_PUBLIC_KEY and MOOLRE_ACCOUNT_NUMBER; live verification also requires MOOLRE_API_USER.

Sandbox mode requires MOOLRE_ACCOUNT_NUMBER and MOOLRE_API_USER. The SDK sends MOOLRE_API_USER as the X-API-USER header. MOOLRE_PUBLIC_KEY is optional only in sandbox.

MOOLRE_API_USER is required for every verifyPayment() call, including live mode. Transaction-status requests also include X-API-PUBKEY when a public key is configured.

For a direct SDK integration, choose the endpoint with your own config:

MOOLRE_BASE_URL and MOOLRE_VERIFICATION_URL are supported in the raw PHP example as advanced overrides, but most apps should switch with MOOLRE_PRODUCTION.

Raw PHP

Use callback for the server-to-server notification URL and redirect for the customer return page. Your redirect page should verify the returned reference before showing a paid receipt. Your callback/webhook should also verify the posted reference before updating fulfillment state. The SDK rejects verification responses whose returned reference does not match the reference you requested:

Integration Examples

The SDK is framework-agnostic. Each framework only needs to provide configuration, routing, redirects, and your own order update logic.

Laravel

Symfony

Slim

CodeIgniter 4

API

new Moolre\Client($publicKey, $accountNumber, $transport = null, $baseUrl = Client::DEFAULT_BASE_URL, $timeout = 60, $allowInsecureBaseUrl = false, $apiUser = null, $verificationUrl = null)

Creates a Moolre client.

By default, the SDK requires the Moolre base URL to use HTTPS. Set $allowInsecureBaseUrl to true only for a controlled local HTTP endpoint; the SDK always rejects other URL schemes and base URLs containing user credentials.

For sandbox, set $baseUrl to Client::SANDBOX_BASE_URL (https://sandbox.moolre.com/embed/src/start) and pass your Moolre account username as $apiUser. The SDK sends it as X-API-USER. Public key is optional only for sandbox payment-initiation requests.

$verificationUrl defaults to Client::DEFAULT_VERIFICATION_URL (https://api.moolre.com/open/transact/status) or, when the base URL is the sandbox host, Client::SANDBOX_VERIFICATION_URL. Pass an explicit HTTPS URL if Moolre gives your sandbox a different status endpoint.

$client->initiatePayment(array|PaymentRequest $payment): PaymentInitiation

Required payment fields:

• reference: Your unique order or payment reference
• email: Customer email address
• amount: Positive decimal amount, preferably supplied as a string such as '120.00'. Values are normalized to two decimal places; scientific notation and values with more than two decimal places are rejected.
• currency: Currency code, currently GHS
• callback: Fully qualified server callback/webhook URL where Moolre can post payment updates

Optional fields:

• redirect: Fully qualified customer return URL after hosted checkout
• expiration_time: Payment link expiration time in minutes. Optional; when provided, the minimum is 1 minute.
• metadata: Additional merchant metadata to attach to the payment request, such as customer_id or order_id
• nonce_value: Optional value if your app wants to associate a nonce with the payment request
• tx_source: Optional transaction source. Defaults to php-sdk

Callback and redirect URLs must use http or https. Use https in production.

$client->verifyPayment(string $reference): TransactionVerification

Confirms the payment status for a reference. It sends a JSON POST to the configured status URL with type: 1, idtype: '1', id: $reference, and accountnumber: $accountNumber; it includes both X-API-USER and X-API-PUBKEY headers when the public key is configured. $apiUser is mandatory for this method. If Moolre returns a different reference (or transaction id) in the verification response, the SDK throws Moolre\Exceptions\ApiException.

Use matchesPaymentDetails($amount, $currency, $email, $accountNumber) before delivering value. It returns true only when Moolre reports a successful payment whose amount, currency, email, and account number all match the values supplied by your application. The verification response must include data.amount, data.currency, data.email, and data.accountnumber (or data.account_number); otherwise it fails closed.

$transaction->matchesAmountAndAccountNumber(string $amount, string $accountNumber): bool

The transaction-status endpoint returns data.txstatus, data.externalref, data.amount, and data.accountnumber. Use this method when that endpoint does not provide currency or customer-email fields. It requires a successful txstatus, the exact normalized amount, and the account number; the client also matches externalref to the requested local reference.

Client::generateReference(string $prefix = 'moolre'): string

Generates a unique reference that is safe to send to Moolre.

Error Handling

All SDK exceptions extend Moolre\Exceptions\MoolreException.

Security Notes

• Keep your Moolre public key and account number outside source control.
• Always verify payment server-side before marking an order as paid.
• Match the verified reference to a local pending order.
• Validate the final amount and currency against your own database.
• Require matchesPaymentDetails() to succeed before delivering value; do not treat a callback or redirect as proof of payment.
• Treat callback as the server notification/webhook URL and redirect as the customer return page.
• Use HTTPS callback and redirect URLs in production.

Troubleshooting

SSL certificate problem on local PHP

If local PHP reports SSL certificate problem: unable to get local issuer certificate, PHP/cURL cannot find a trusted CA bundle. Configure curl.cainfo and openssl.cafile in php.ini, or set MOOLRE_CA_FILE/SSL_CERT_FILE to a valid cacert.pem path.

This is a local PHP trust-store issue. It can happen even when a WooCommerce integration works, because WordPress has its own HTTP layer and CA handling.

Testing

composer smoke runs without dev dependencies. composer test requires the PHPUnit dev dependency from composer install.

The client accepts a custom TransportInterface, so applications can test payment flows without hitting the live Moolre API.

Publishing Checklist

Before tagging a public release:

• Confirm the Moolre API request and response schema with the API/backend owner.
• Run composer validate --strict --no-check-publish.
• Run composer install and composer test.
• Run composer analyse and composer prepublish-check from a clean, committed working tree with an origin remote.
• Run composer audit from a machine with working Composer TLS certificates.
• Update CHANGELOG.md with the release version and date.
• Tag the release in Git, for example v1.0.0.
• Submit or refresh the package on Packagist.