Mpay24 Php Laravel Package

Getting Started

Install and configure

composer require mpay24/mpay24-php

You need two things from mPAY24 before any code will work: a merchant ID and the SOAP/API password (the test and production systems issue separate credentials). Wire them into config/services.php / .env rather than hardcoding:

// config/services.php
'mpay24' => [
    'merchant_id' => env('MPAY24_MERCHANT_ID'),
    'password'    => env('MPAY24_PASSWORD'),
    'test'        => env('MPAY24_TEST', true),
],

Where to look first

1. The repo's README.md and examples/ directory — the SDK ships runnable samples for the hosted payment page, token payments and transaction operations, and those are the fastest way to see real method signatures.
2. src/ — the main client class (typically Mpay24\Mpay24) plus the DTOs for PaymentPage, PaymentToken, Operation and Transaction. Read these before trusting any blog snippet; the SDK's method names have drifted across versions.
3. The official mPAY24 developer docs for the SOAP API — the PHP SDK is a thin wrapper, so the gateway's own semantics (status codes, operation types) are the source of truth when the SDK's docblocks are vague.

First use case: hosted payment page

The lowest-risk integration is the redirect flow. You build a payment page definition (amount, currency, description, success/error/cancel URLs), hand it to the SDK, and get back a redirect URL:

use Mpay24\Mpay24;

$mpay24 = new Mpay24(
    config('services.mpay24.merchant_id'),
    config('services.mpay24.password'),
    config('services.mpay24.test'),
);

// Build a PaymentPage via the SDK's DTO/setters, then:
$redirectUrl = $mpay24->paymentPage($paymentPage);

return redirect()->away($redirectUrl);

The customer pays on mPAY24's page, and mPAY24 calls your confirmation URL with a transaction ID. Persist the TID before redirecting (correlate it with your own order ID) so you can reconcile later.

Implementation Patterns

Hosted payment page (redirect flow). Create an order record in your DB first, put your internal order reference in the payment page's tid/description, redirect the user, and handle three return URLs: success, error, and cancel. Never mark an order paid based on the browser returning to your success URL — that is user-controllable.

Server-to-server confirmation. mPAY24 POSTs to your confirmation endpoint. Always re-verify with transactionStatus($tid) before fulfilling, and make the endpoint idempotent (unique constraint on TID, queue the fulfillment). Respond with HTTP 200 quickly; do the heavy lifting in a job. A typical pattern:

Route::post('/mpay24/confirm', function (Request $request) {
    $tid = $request->input('TID');
    $status = $mpay24->transactionStatus($tid);

    if ($status->isPaid()) {           // check the actual status constants in src/
        ProcessPaidOrder::dispatch($tid);
    }
    return response('OK', 200);
})->withoutMiddleware([VerifyCsrfToken::class]);

Excluding CSRF on that route is essential and easy to forget.

Token payments (recurring / one-click). For subscriptions, use the payment-token flow instead of the redirect: create a token/profile against a card or PayPal account, store the token ID against the customer, then charge it with a PaymentToken request. This is the pattern for MIT (merchant-initiated) recurring charges. Test carefully — the test system's token behavior is close to production but not identical for every payment method.

Transaction operations. Capture, refund, credit and cancel are all expressed through the SDK's operation abstraction (capture, refund, credit, cancel, reversal). Wrap each in a small service method and log the raw SOAP request/response alongside your own order record. Amounts for partial refunds are in minor units (cents) — confirm this against the SDK's amount helpers before shipping.

Multi-payment-method selection. Use the SDK's listPaymentMethods to render only the methods enabled for your merchant account (Klarna, PayPal, credit card, EPS, etc. differ per contract and per country). Cache the list for a few hours; it changes when mPAY24 onboards or disables a method on your account.

Gotchas and Tips

• Maintenance risk. Last release was August 2022 and the package has a very small user base. Pin the version in composer.json, and budget for the possibility of forking or maintaining the SOAP wrapper yourself if a PHP upgrade breaks it. Run it against your target PHP version in CI early.
• SOAP under the hood. The SDK talks SOAP, which means the PHP soap extension (and often libxml) must be installed. Class "SoapClient" not found in a slim Docker image is the classic first failure — install php-soap.
• Test vs. production are separate universes. Different credentials, different endpoint, different transaction IDs. Guard with an explicit config flag and never let a test credential reach production; a common bug is a .env copied wholesale.
• Status codes are strings, not booleans. Treat every status as an enum and map it explicitly (RESERVED, BILLED, CAPTURED, REFUNDED, ERROR, …). Unknown statuses should fail closed, not open.
• Amounts and currency. mPAY24 expects amounts in the currency's minor unit for most currencies. Store the amount and currency together, and round-trip through the SDK's formatter rather than doing string math yourself.
• Do not trust the confirmation POST body. The POST is a notification, not proof of payment. Verify server-side with transactionStatus; also handle duplicate and out-of-order callbacks.
• Debugging tips. The SDK's exceptions often wrap a SOAP fault with a numeric code — log $e->getMessage() and the previous exception, and dump the raw response in the test system. If a call fails silently, check that your merchant account has the payment method enabled and that the amount is within that method's limits.
• No official Laravel package. Don't expect a service provider, facade or config publish. Bind the client as a singleton in a small service provider and inject it — that also makes it mockable in tests.
• Extension points are thin. There is little customization; for retries, timeouts or advanced logging you will wrap the client rather than extend it. A thin Mpay24Client decorator around the SDK is the cleanest way to add correlation IDs and structured logging.
• Timeouts. The default SOAP timeout may be unsuitable for a web request. Set a short timeout for synchronous calls and move anything slow (transaction listings, reporting) to a queue.