README

SimplePay for Laravel

Modern Laravel package for SimplePay online payment integration. Start payments, handle IPN webhooks, manage card storage, process refunds, and more.

Based on the official SimplePay PHP SDK v2.1, rebuilt for Laravel with typed DTOs, Enums, Events, and full API coverage.

Quick Example

use Netipar\SimplePay\Facades\SimplePay;
use Netipar\SimplePay\Enums\Currency;
use Netipar\SimplePay\Enums\PaymentMethod;
use Netipar\SimplePay\Dto\PaymentRequest;
use Netipar\SimplePay\Dto\Address;

$response = SimplePay::payment()->start(new PaymentRequest(
    currency: Currency::HUF,
    total: 2500,
    orderRef: 'ORDER-123',
    customerEmail: 'customer@example.com',
    language: 'HU',
    url: route('simplepay.back'),
    methods: [PaymentMethod::CARD],
    invoice: new Address(
        name: 'John Doe',
        country: 'hu',
        city: 'Budapest',
        zip: '1111',
        address: 'Main Street 1',
    ),
));

return redirect($response->paymentUrl);

Requirements

• PHP 8.2+
• Laravel 11 or 12
• A SimplePay merchant account

Installation

composer require netipar/simplepay

Publish the config file:

php artisan vendor:publish --tag=simplepay-config

Add your merchant credentials to .env:

SIMPLEPAY_SANDBOX=true
SIMPLEPAY_HUF_MERCHANT=your_merchant_id
SIMPLEPAY_HUF_SECRET_KEY=your_secret_key
SIMPLEPAY_BACK_URL=https://yourdomain.com/payment/back

Usage

Obtaining the Services

Access all services through the SimplePay facade:

use Netipar\SimplePay\Facades\SimplePay;

SimplePay::payment();      // PaymentService
SimplePay::cardStorage();  // CardStorageService
SimplePay::autoPayment();  // AutoPaymentService
SimplePay::rtp();          // RtpService

Start a Payment

use Netipar\SimplePay\Facades\SimplePay;
use Netipar\SimplePay\Enums\Currency;
use Netipar\SimplePay\Enums\PaymentMethod;
use Netipar\SimplePay\Dto\PaymentRequest;
use Netipar\SimplePay\Dto\Address;
use Netipar\SimplePay\Dto\Item;

$response = SimplePay::payment()->start(new PaymentRequest(
    currency: Currency::HUF,
    total: 25400,
    orderRef: 'ORDER-2026-001',
    customerEmail: 'customer@example.com',
    language: 'HU',
    url: route('simplepay.back'),
    methods: [PaymentMethod::CARD],
    invoice: new Address(
        name: 'Customer Kft.',
        country: 'hu',
        city: 'Budapest',
        zip: '1234',
        address: 'Main Street 1.',
    ),
    items: [
        new Item(
            title: 'Product name',
            price: 10000,
            quantity: 2,
        ),
        new Item(
            title: 'Delivery',
            price: 5400,
            quantity: 1,
        ),
    ],
));

$response->transactionId; // SimplePay transaction ID
$response->paymentUrl;    // Redirect URL to SimplePay payment page
$response->timeout;       // Payment timeout

return redirect($response->paymentUrl);

Two-Step Payment (Authorize + Finish)

use Netipar\SimplePay\Dto\PaymentRequest;
use Netipar\SimplePay\Dto\FinishRequest;

// Step 1: Authorize with twoStep enabled
$response = SimplePay::payment()->start(new PaymentRequest(
    // ... same as above
    twoStep: true,
));

// Step 2: Later, finish the authorized payment
$result = SimplePay::payment()->finish(new FinishRequest(
    currency: Currency::HUF,
    transactionId: $transactionId,
    orderRef: 'ORDER-2026-001',
    approveTotal: 25400,
));

Refund a Transaction

use Netipar\SimplePay\Dto\RefundRequest;

// Full refund
$result = SimplePay::payment()->refund(new RefundRequest(
    currency: Currency::HUF,
    transactionId: $transactionId,
    orderRef: 'ORDER-2026-001',
    refundTotal: 25400,
));

// Partial refund
$result = SimplePay::payment()->refund(new RefundRequest(
    currency: Currency::HUF,
    transactionId: $transactionId,
    orderRef: 'ORDER-2026-001',
    refundTotal: 10000,
));

Query Transaction Status

$result = SimplePay::payment()->query(
    currency: Currency::HUF,
    transactionId: $transactionId,
);

$result->status;         // PaymentStatus enum
$result->remainingTotal; // Remaining amount
$result->paymentDate;    // Payment date
$result->finishDate;     // Finish date (two-step)

Cancel a Transaction

SimplePay::payment()->cancel(
    currency: Currency::HUF,
    transactionId: $transactionId,
);

Card Storage (OneClick Payments)

use Netipar\SimplePay\Dto\CardStorageDoRequest;

// Pay with a stored card
$result = SimplePay::cardStorage()->do(new CardStorageDoRequest(
    currency: Currency::HUF,
    total: 5000,
    orderRef: 'ORDER-2026-002',
    customerEmail: 'customer@example.com',
    cardId: $savedCardId,
));

// Query stored card
$card = SimplePay::cardStorage()->cardQuery(Currency::HUF, $cardId);

// Remove stored card
SimplePay::cardStorage()->cardCancel(Currency::HUF, $cardId);

Recurring Payments

use Netipar\SimplePay\Dto\RecurringRequest;

$result = SimplePay::cardStorage()->doRecurring(new RecurringRequest(
    currency: Currency::HUF,
    total: 9900,
    orderRef: 'SUB-2026-003',
    customerEmail: 'customer@example.com',
    token: $recurringToken,
));

Apple Pay

use Netipar\SimplePay\Dto\ApplePayStartRequest;
use Netipar\SimplePay\Dto\ApplePayDoRequest;

// Start Apple Pay session
$session = SimplePay::payment()->startApplePay(new ApplePayStartRequest(
    currency: Currency::HUF,
    total: 5000,
    orderRef: 'ORDER-AP-001',
    customerEmail: 'customer@example.com',
));

// Complete Apple Pay payment
$result = SimplePay::payment()->doApplePay(new ApplePayDoRequest(
    currency: Currency::HUF,
    transactionId: $session->transactionId,
    applePayToken: $tokenFromJs,
));

EAM / Qvik Payment

use Netipar\SimplePay\Dto\EamStartRequest;

$response = SimplePay::payment()->startEam(new EamStartRequest(
    currency: Currency::HUF,
    total: 3000,
    orderRef: 'ORDER-EAM-001',
    customerEmail: 'customer@example.com',
    url: route('simplepay.back'),
));

Request to Pay (RTP)

use Netipar\SimplePay\Dto\RtpStartRequest;

// Start RTP transaction
$result = SimplePay::rtp()->start(new RtpStartRequest(
    currency: Currency::HUF,
    total: 15000,
    orderRef: 'RTP-2026-001',
    customerEmail: 'customer@example.com',
    url: route('simplepay.back'),
));

// Query RTP status
$status = SimplePay::rtp()->query(Currency::HUF, transactionId: $id);

// Refund RTP
SimplePay::rtp()->refund(Currency::HUF, $transactionId, 15000);

// Reverse RTP
SimplePay::rtp()->reverse(Currency::HUF, $transactionId);

IPN Webhook

The package automatically registers a POST /simplepay/ipn route with signature verification middleware. Listen to payment events in your application:

// In EventServiceProvider or via Event::listen()
use Netipar\SimplePay\Events\PaymentSucceeded;
use Netipar\SimplePay\Events\PaymentFailed;

protected $listen = [
    PaymentSucceeded::class => [HandlePaymentSuccess::class],
    PaymentFailed::class => [HandlePaymentFailure::class],
];

Available events (all receive IpnMessage DTO):

The IpnMessage DTO contains:

$event->ipnMessage->orderRef;       // Your order reference
$event->ipnMessage->transactionId;  // SimplePay transaction ID
$event->ipnMessage->status;         // PaymentStatus enum
$event->ipnMessage->paymentMethod;  // PaymentMethod enum
$event->ipnMessage->cardMask;       // Masked card number

Back URL Handling

The package registers a GET /simplepay/back route. Customize the response by binding your own BackUrlResponse in AppServiceProvider:

use Netipar\SimplePay\Contracts\BackUrlResponse;
use App\Http\Responses\SimplePayBackResponse;

// AppServiceProvider::register()
$this->app->singleton(BackUrlResponse::class, SimplePayBackResponse::class);

use Netipar\SimplePay\Contracts\BackUrlResponse;
use Netipar\SimplePay\Dto\BackResponse;
use Netipar\SimplePay\Enums\BackEvent;

class SimplePayBackResponse implements BackUrlResponse
{
    public function toResponse(Request $request, BackResponse $back): Response
    {
        return match ($back->event) {
            BackEvent::Success => redirect()->route('payment.success', $back->orderRef),
            BackEvent::Fail    => redirect()->route('payment.failed'),
            BackEvent::Cancel  => redirect()->route('checkout'),
            BackEvent::Timeout => redirect()->route('payment.timeout'),
        };
    }
}

Enums

Always use enum cases instead of raw strings:

• Currency -- HUF, EUR, USD
• PaymentMethod -- CARD, WIRE, EAM
• PaymentStatus -- INIT, FINISHED, AUTHORIZED, NOTAUTHORIZED, INPAYMENT, CANCELLED, TIMEOUT, INFRAUD, FRAUD, REFUND, REVERSED
• BackEvent -- SUCCESS, FAIL, CANCEL, TIMEOUT
• TransactionType -- CIT (Customer Initiated), MIT (Merchant Initiated), REC (Recurring)
• ErrorCode -- 358+ error codes with Hungarian descriptions

Error Handling

The package throws SimplePayApiException when the SimplePay API returns error codes:

use Netipar\SimplePay\Exceptions\SimplePayApiException;

try {
    $response = SimplePay::payment()->start($request);
} catch (SimplePayApiException $e) {
    $e->getMessage();       // "[5083] Token times szükséges"
    $e->getErrorCodes();    // [5083]
    $e->hasErrorCode(5083); // true
    $e->getResolvedCodes(); // [ErrorCode::TokenTimesRequired]
}

Configuration

Key .env variables:

SIMPLEPAY_SANDBOX=true
SIMPLEPAY_HUF_MERCHANT=your_merchant_id
SIMPLEPAY_HUF_SECRET_KEY=your_secret_key
SIMPLEPAY_BACK_URL=https://yourdomain.com/payment/back
SIMPLEPAY_TIMEOUT=600
SIMPLEPAY_LOG_CHANNEL=simplepay
SIMPLEPAY_AUTO_CHALLENGE=true

Multi-currency support -- each currency has its own merchant credentials:

SIMPLEPAY_EUR_MERCHANT=your_eur_merchant_id
SIMPLEPAY_EUR_SECRET_KEY=your_eur_secret_key
SIMPLEPAY_USD_MERCHANT=your_usd_merchant_id
SIMPLEPAY_USD_SECRET_KEY=your_usd_secret_key

Logos and Assets

The package includes the official SimplePay merchant logo pack. Publish the assets:

php artisan vendor:publish --tag=simplepay-assets

This copies logos and pre-composed variations to public/vendor/simplepay/.

Usage in Blade, Vue.js, or React:

{{-- Blade --}}
<img src="{{ asset('vendor/simplepay/logos/simplepay_200x50.png') }}" alt="SimplePay">

<!-- Vue.js / React (Inertia.js) -->
<img src="/vendor/simplepay/logos/simplepay_200x50.png" alt="SimplePay" />

Available logos: SimplePay (multiple sizes/orientations + white variants), Visa, Mastercard, Maestro, Amex, Apple Pay, Google Pay, Qvik, OTP SZÉP. Pre-composed card type combinations are also included. See examples for Blade, Vue.js, and React checkout page examples.

Logging

Set SIMPLEPAY_LOG_CHANNEL to any Laravel log channel name. Example dedicated channel in config/logging.php:

'simplepay' => [
    'driver' => 'daily',
    'path' => storage_path('logs/simplepay.log'),
    'days' => 14,
],

Services Overview

SDK Compatibility

This package is built based on the SimplePay PHP SDK v2.1 (API v2). All API requests include the sdkVersion: SimplePay_PHP_SDK_2.1_Laravel identifier.

Examples

• English examples
• Magyar példák

Testing

composer test

Credits

• NETipar

License

The MIT License (MIT). Please see License File for more information.