README

Laravel package for integrating Saman (SEP / Shaparak) payment gateway.

This package provides a clean, DTO-based, and IDE-friendly API for:

• Creating payment tokens
• Redirecting users to the payment page
• Verifying transactions via callback

Features

• ✅ Laravel 10 & 11 compatible
• ✅ DTO-based request & response models
• ✅ Facade support with full IDE autocomplete
• ✅ Configurable via config file & .env
• ✅ No external dependencies beyond Laravel components
• ✅ Clean service-based architecture

Installation

Install the package via Composer:

composer require noorani-mm/laravel-saman-payment-gateway

Publish Configuration

Publish the config file:

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

This will create:

config/saman-gateway.php

Configuration

Set the following values in your .env file:

SAMAN_TERMINAL_ID=XXXXXXXX
SAMAN_REDIRECT_URL=https://your-site.com/payment/callback
SAMAN_TIMEOUT=30

Example config/saman-gateway.php:

return [
    'TerminalId'   => env('SAMAN_TERMINAL_ID'),
    'RedirectURL' => env('SAMAN_REDIRECT_URL'),
    'Timeout'     => env('SAMAN_TIMEOUT', 30),
];

Usage

Import Facade

use NooraniMm\SamanGateway\Facades\Saman;

1️⃣ Create Payment Token

Create a payment token using a DTO:

use NooraniMm\SamanGateway\DTO\Requests\CreatePaymentTokenRequestDTO;

$dto = new CreatePaymentTokenRequestDTO(
    Amount: 100000,
    ResNum: 'ORDER-123'
);

$response = Saman::createPaymentToken($dto);

2️⃣ Redirect User to Payment Page

Auto redirect (HTML form auto-submit)

Saman::redirectToPayment($response);

Manual handling (JS / frontend rendering)

$data = Saman::redirectToPayment($response, false);

/*
$data = [
    'token'  => '...',
    'url'    => 'https://sep.shaparak.ir/OnlinePG/OnlinePG',
    'method' => 'post',
];
*/

3️⃣ Verify Payment (Callback)

In your callback controller:

use Illuminate\Http\Request;
use NooraniMm\SamanGateway\Facades\Saman;

public function callback(Request $request)
{
    $result = Saman::verify($request);

    if ($result->isSuccessful()) {
        // Payment successful
    } else {
        // Payment failed
    }
}

The callback data is mapped into a PaymentCallbackResponseDTO.

DTO Architecture

Requests

DTO/Requests/
├── CreatePaymentTokenRequestDTO

Responses

DTO/Responses/
├── CreatePaymentTokenResponseDTO
├── PaymentCallbackResponseDTO

Each DTO explicitly defines:

• Required fields
• Optional fields
• Exact data types
• IDE-friendly documentation

Facade Methods (IDE Autocomplete)

The Saman facade exposes the following methods:

Saman::createPaymentToken(CreatePaymentTokenRequestDTO $DTO);

Saman::redirectToPayment(
    CreatePaymentTokenResponseDTO $DTO,
    bool $autoRedirect = true
);

Saman::verify(Request $request);

All methods are documented via @method annotations for full IDE support.

Architecture Overview

Facade (Saman)
      ↓
Service (SamanPaymentGateway)
      ↓
DTOs (Request / Response)
      ↓
Saman (SEP) API

• Facade: simple static API
• Service: core business logic
• DTOs: explicit data contracts
• Config: environment-driven

Error Handling

• Network or HTTP errors throw Exception
• Gateway errors are returned inside response DTOs
• Verification failure is determined via gateway response codes

Requirements

• PHP ^8.1
• Laravel 10 or 11

License

MIT License © Mohammad Mahdi Noorani