levilabs / laravel-nass

dev-main / 1.0.x-dev 2026-11-05 12:16 UTC

Requires

• php: ^8.2
• illuminate/console: ^11.0 || ^12.0 || ^13.0
• illuminate/contracts: ^11.0 || ^12.0 || ^13.0
• illuminate/database: ^11.0 || ^12.0 || ^13.0
• illuminate/http: ^11.0 || ^12.0 || ^13.0
• illuminate/support: ^11.0 || ^12.0 || ^13.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.22
• orchestra/testbench: ^9.0 || ^10.0 || ^11.0
• pestphp/pest: ^3.8 || ^4.4
• pestphp/pest-plugin-laravel: ^3.2 || ^4.1

MIT

• Levi Labs
• Nizam Omer

• payment
• gateway
• laravel
• iraq
• nass
• iqd
• levilabs
• nasswallet

Published on Packagist.org on 2026-11-05 18:17 UTC

README

A modern Laravel SDK for the NASS E-Payment Gateway (Iraq) — hosted card checkout, server notify callbacks, and status polling — plus Nass Wallet merchant checkout when you need wallet-based payments. Typed DTOs and enums, cached merchant authentication, optional database persistence, and Artisan sync commands when notifications are missed.

Maintained by Levi Labs (GitHub) — built by Nizam Omer

NASS: nass.iq · Developers: nass.iq/resources/developers

Table of Contents

• Requirements
• Installation
• Configuration
• Payment Gateway — creating a transaction
• Payment Gateway — notify callback
• Payment Gateway — checking status
• Missed notifications: gateway sync command
• UAT test card (gateway)
• Nass Wallet — init checkout
• Nass Wallet — checking status & callbacks
• Missed updates: wallet sync command
• Multiple merchants
• Automatic persistence
• Events
• Error handling
• Security
• Testing
• NASS API reference
• Changelog
• Contributing
• Author
• License

Requirements

• PHP 8.2+ (Laravel 13.x requires PHP 8.3+ on the application)
• Laravel 11.x, 12.x, or 13.x
• NASS merchant credentials (gateway and/or wallet), as issued by Nass

Installation

composer require levilabs/laravel-nass
php artisan vendor:publish --tag=nass-config
php artisan migrate

Publish step copies config/nass.php. Migrations create nass_gateway_payments and nass_wallet_transactions; gateway and wallet lifecycle events upsert rows automatically when listeners are registered (default).

Configuration

Gateway settings are listed first because the Payment Gateway is the primary integration path for most apps. Wallet variables are separate under NASS_WALLET_*.

# --- NASS E-Payment Gateway (portal / hosted checkout) ---
NASS_GATEWAY_MERCHANT=default
NASS_GATEWAY_ENVIRONMENT=uat
NASS_GATEWAY_USERNAME=
NASS_GATEWAY_PASSWORD=
NASS_GATEWAY_BASE_URL=https://uat-gateway.nass.iq:9746
NASS_GATEWAY_BACK_REF=https://your-app.test/payments/nass/return
NASS_GATEWAY_NOTIFY_URL=https://your-app.test/payments/nass/notify

# --- Nass Wallet (optional second product in the same package) ---
NASS_WALLET_MERCHANT=default
NASS_WALLET_BASIC_TOKEN=
NASS_WALLET_USERNAME=
NASS_WALLET_PASSWORD=
NASS_WALLET_TRANSACTION_PIN=
NASS_WALLET_GRANT_TYPE=password
NASS_WALLET_BASE_URL=https://uatgw1.nasswallet.com/payment/transaction
NASS_WALLET_PORTAL_URL=https://uatcheckout1.nasswallet.com
NASS_WALLET_PORTAL_PARAM=transactionId
NASS_WALLET_CALLBACK_URL=https://your-app.test/payments/nass-wallet/callback
NASS_WALLET_LANGUAGE=en

Production hosts: UAT URLs are safe defaults for development. Production gateway and wallet base URLs are issued with your merchant account — set NASS_GATEWAY_BASE_URL and NASS_WALLET_BASE_URL explicitly before going live.

Currency code 368 (Iraqi Dinar) and transaction type 1 (sale) are the usual gateway defaults; see config/nass.php for overrides per merchant.

Payment Gateway — creating a transaction

Authenticates with cached bearer tokens, creates a portal transaction, and returns a hosted payment URL — redirect the customer there to pay.

use LeviLabs\LaravelNass\Data\Gateway\CreateTransactionData;
use LeviLabs\LaravelNass\Facades\NassGatewayPayment;

$created = NassGatewayPayment::create(new CreateTransactionData(
    orderId: 'ORDER-'.uniqid(),
    orderDesc: 'Checkout',
    amount: 150.0,
));

return redirect($created->paymentUrl);

backRef and notifyUrl fall back to NASS_GATEWAY_BACK_REF and NASS_GATEWAY_NOTIFY_URL when omitted on the DTO.

Payment Gateway — notify callback

NASS POSTs the result to your notifyUrl. Parse the payload and treat responseCode === '00' and actionCode === '0' as approval; store rrn for long-term reference (orderId is only retained on Nass side for a limited time).

use LeviLabs\LaravelNass\Facades\NassGatewayPayment;

public function notify(Request $request)
{
    $callback = NassGatewayPayment::parseCallback($request);

    if ($callback->isApproved()) {
        // Fulfill order
    }
}

Payment Gateway — checking status

Poll the gateway directly (available within 24 hours of initiation):

$status = NassGatewayPayment::status('ORDER-123');

if ($status->isApproved()) {
    // Paid — use $status->rrn
}

Missed notifications: gateway sync command

php artisan nass:sync-gateway-statuses

Re-checks pending rows in nass_gateway_payments that are still inside the 24-hour status window.

UAT test card (gateway)

Use only in UAT, with credentials Nass provides for testing:

PAN	Expiry	CVV
5123450000000008	01/39	100

Confirm test data with your Nass integration pack from NASS Developers.

Nass Wallet — init checkout

Separate product from the card gateway — wallet login, init, then redirect to the hosted wallet checkout URL.

use LeviLabs\LaravelNass\Data\Wallet\InitWalletTransactionData;
use LeviLabs\LaravelNass\Facades\NassWalletPayment;

$created = NassWalletPayment::init(new InitWalletTransactionData(
    orderId: 'W-100',
    amount: 25.00,
));

return redirect($created->checkoutUrl);

If your checkout portal expects id= instead of transactionId=, set NASS_WALLET_PORTAL_PARAM=id.

Nass Wallet — checking status & callbacks

Always confirm wallet payments with checkTransaction, not by trusting the callback body alone:

$status = NassWalletPayment::status('TX-ID-FROM-INIT');

// Incoming callback — verifies via checkTransaction internally:
$status = NassWalletPayment::parseCallback($request);

Status mapping uses the transactionStatus field returned by checkTransaction (for example SUCCESS / FAILED).

Missed updates: wallet sync command

php artisan nass:sync-wallet-statuses

Multiple merchants

Add entries under gateway.merchants and wallet.merchants in config/nass.php, then pass the merchant key as the last argument:

NassGatewayPayment::create($dto, merchant: 'second_store');
NassWalletPayment::init($dto, merchant: 'second_store');

Automatic persistence

Table	When rows update
nass_gateway_payments	Gateway create, status check, notify-driven completed/failed events
nass_wallet_transactions	Wallet init, status check

Events

Gateway: GatewayPaymentCreated, GatewayPaymentStatusChecked, GatewayPaymentCompleted, GatewayPaymentFailed, GatewayNotifyReceived

Wallet: WalletPaymentCreated, WalletPaymentStatusChecked

Error handling

use LeviLabs\LaravelNass\Exceptions\NassGatewayException;
use LeviLabs\LaravelNass\Exceptions\NassWalletException;

try {
    NassGatewayPayment::create($dto);
} catch (NassGatewayException $e) {
    // HTTP / gateway logical failure
}

Security

• Credentials belong in .env, never in version control.
• Gateway notify payloads should drive fulfillment only after isApproved(); use idempotency on rrn / orderId.
• Wallet callbacks must be confirmed with parseCallback() (which calls checkTransaction) — do not trust unsigned POST bodies alone.
• TLS verification is never disabled in this SDK.

See SECURITY.md for vulnerability reporting.

Testing

composer test        # Pest
composer analyse     # PHPStan level 8
composer format      # Laravel Pint

NASS API reference

Integration details and environment URLs are provided by Nass for your merchant account. Start here:

• NASS
• NASS Developers

SDK mapping (Payment Gateway)

SDK	HTTP	Path
NassGatewayAuth::login()	POST	/auth/merchant/login
NassGatewayPayment::create()	POST	/transaction
NassGatewayPayment::status()	GET	/transaction/{orderId}/checkStatus

Environment	Base URL
UAT	https://uat-gateway.nass.iq:9746
Production	https://gateway.nass.iq:9746

SDK mapping (Nass Wallet)

SDK	HTTP	Path
NassWalletAuth::login()	POST	/login
NassWalletPayment::init()	POST	/initTransaction
NassWalletPayment::status()	POST	/checkTransaction

Direct card-on-server (PCI) and tap-to-phone flows are out of scope for this package — use Payment Gateway portal checkout unless Nass documents additional REST endpoints in your merchant materials.

Changelog

See CHANGELOG.md.

Contributing

Bug reports and feature ideas are welcome via GitHub Issues. See CONTRIBUTING.md.

Author

Levi Labs — GitHub · [e-mail]

Created and maintained by Nizam Omer — nizaamomer.com · [e-mail]

License

MIT — see LICENSE.md.