README

Laravel package for USIMPay payment integration.

This package provides the generic gateway client only:

Generate USIMPay payment checksum
Initialize payment
Verify payment status
Get payment information
Publish Laravel config
Use via dependency injection or facade

It does not manage your application database records, routes, UI, or business workflow.

Installation

Install with Composer:

composer require usimpay/usimpay-laravel

Publish the config:

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

Add your credentials:

USIMPAY_BASE_URL=https://api.usimpay.com.my
USIMPAY_API_KEY=
USIMPAY_SECRET_KEY=
USIMPAY_TIMEOUT=30
USIMPAY_DESCRIPTION_MAX_LENGTH=20
USIMPAY_VERIFY_CALLBACKS=true

Initialize Payment

use USIMPay\Laravel\USIMPayClient;

$response = app(USIMPayClient::class)->initializePayment([
    'customer_name' => 'Customer Name',
    'customer_email' => 'customer@example.com',
    'customer_phone' => '+60123456789',
    'payment_ref' => 'INV-2026-00001',
    'amount' => 150.00,
    'payment_description' => 'Invoice Payment',
    'direct_url' => route('payments.redirect', ['payment' => $payment->id]),
    'callback_url' => route('payments.callback'),
]);

if ($response->success) {
    $payment->update([
        'gateway_bill_id' => $response->billId,
    ]);

    return redirect()->away($response->paymentUrl);
}

return back()->withErrors([
    'payment' => $response->message,
]);

createPayment() is also available as an alias of initializePayment().

Facade Usage

use USIMPay;

$response = USIMPay::createPayment($payload);

Verify Payment Status

Always verify the bill_id with USIMPay before fulfilling an order or marking a local record as paid.

use USIMPay;

$status = USIMPay::verifyPaymentStatus($billId);

if (! $status->success) {
    abort(400, $status->message ?? 'Payment verification failed');
}

if ($status->isPaid()) {
    $payment->markAsPaid($status->toArray());
}

Get Payment Info

$paymentInfo = USIMPay::getPaymentInfo($billId);

if ($paymentInfo->success) {
    $amount = $paymentInfo->amount;
    $paymentRef = $paymentInfo->paymentRef;
    $fpxTxnId = $paymentInfo->fpxTxnId;
}

Generate Checksum

Most applications do not need to call this directly because the client generates the checksum during payment initialization.

$checksum = USIMPay::generateChecksum([
    'customer_name' => 'Customer Name',
    'customer_email' => 'customer@example.com',
    'payment_ref' => 'INV-2026-00001',
    'amount' => 150.00,
    'payment_description' => 'Invoice Payment',
]);

Callback Pattern

Your application owns the callback route and local persistence:

use Illuminate\Http\Request;
use Illuminate\Http\JsonResponse;
use USIMPay;

public function callback(Request $request): JsonResponse
{
    $billId = $request->input('bill_id');
    $paymentRef = $request->input('payment_ref');

    $verified = USIMPay::verifyPaymentStatus($billId);

    if (! $verified->success) {
        return response()->json(['message' => 'Payment verification failed'], 400);
    }

    $payment = Payment::where('payment_ref', $paymentRef)->firstOrFail();

    if ($verified->isPaid()) {
        $payment->markAsPaid($verified->toArray());
    } else {
        $payment->markAsFailed($verified->toArray());
    }

    return response()->json(['status' => 'success']);
}

Do not trust callback payloads or redirect query parameters by themselves. Verify with USIMPay using the bill_id.

Callback Signature

The package includes:

USIMPay::verifyCallbackSignature($request->getContent(), $request->header('X-UsimPay-Signature'));

Confirm the exact signature algorithm with USIMPay before enforcing this in production.

Testing

composer test

The package tests use Laravel's Http::fake() and do not call the real USIMPay API.

License

MIT

usimpay / usimpay-laravel

Maintainers

Package info

Statistics

Security