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

noorani-mm / laravel-saman-payment-gateway

Maintainers

Details