PHPackages                             shahkochaki/tara-in-person-purchases - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [CLI & Console](/categories/cli)
4. /
5. shahkochaki/tara-in-person-purchases

ActiveLibrary[CLI & Console](/categories/cli)

shahkochaki/tara-in-person-purchases
====================================

🚀 Tara in-person purchase service for Laravel - Iranian credit card integration with POS terminals

2.2.1(7mo ago)11353MITPHPPHP ^7.4|^8.0|^8.1|^8.2|^8.3CI failing

Since Sep 29Pushed 6mo agoCompare

[ Source](https://github.com/shahkochaki/tara-in-person-purchases)[ Packagist](https://packagist.org/packages/shahkochaki/tara-in-person-purchases)[ Docs](https://github.com/shahkochaki/tara-in-person-purchases)[ RSS](/packages/shahkochaki-tara-in-person-purchases/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (3)Versions (6)Used By (0)

Tara In-Person Purchases for Laravel
====================================

[](#tara-in-person-purchases-for-laravel)

[![Tara360](https://camo.githubusercontent.com/26e53520e756aa6b40b2df79b6b79827fa9f860c2c6005f8b272524acac9fbd8/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f546172613336302d5061796d656e74253230476174657761792d626c7565)](https://camo.githubusercontent.com/26e53520e756aa6b40b2df79b6b79827fa9f860c2c6005f8b272524acac9fbd8/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f546172613336302d5061796d656e74253230476174657761792d626c7565)[![Laravel](https://camo.githubusercontent.com/b30a468acd1d53979d9bd905c6838a6fbf172975a381997777533ed397893bec/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d382532422d726564)](https://camo.githubusercontent.com/b30a468acd1d53979d9bd905c6838a6fbf172975a381997777533ed397893bec/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d382532422d726564)[![PHP](https://camo.githubusercontent.com/304648072498203eded0cde1e7eafda467ffe7fb625aaa0c39ce7192ba7db96b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d372e342532422d707572706c65)](https://camo.githubusercontent.com/304648072498203eded0cde1e7eafda467ffe7fb625aaa0c39ce7192ba7db96b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d372e342532422d707572706c65)[![License](https://camo.githubusercontent.com/5caa455d8debc46fb23abbadb45a733a937f3910a73fc875c2f7820468e1bb54/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e)](https://camo.githubusercontent.com/5caa455d8debc46fb23abbadb45a733a937f3910a73fc875c2f7820468e1bb54/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e)

**A Laravel package specifically designed for Tara360 in-person purchase integration - handles credit payments for physical stores and POS terminals**

[Installation](#installation) • [Configuration](#configuration) • [Usage](#usage) • \[API Reference\](#$verifyResult = $tara->purchaseVerify($traceNumber);

```

## ⚠️ مشکلات معمول و$verifyResult = $tara->purchaseVerify($traceNumber);
```

## 🔍 مدیریت خطاهای بهبود یافته

سرویس حالا **فرمت استاندارد** برای خطاها ارائه می‌دهد:

```php
// فرمت جدید خطاها:
'error' => [
    'title' => 'عنوان خطا',
    'code' => 84780028,
    'message' => 'پیام کاربرپسند'
]
```

### مثال استفاده:

```php
try {
    $result = $tara->purchaseRequest($amount, $payerIdentity);

    if (isset($result['error'])) {
        $error = $result['error'];

        echo "خطا: " . $error['title'] . "\n";
        echo "کد: " . $error['code'] . "\n";
        echo "پیام: " . $error['message'] . "\n";

        // مدیریت خطاهای خاص
        switch ($error['code']) {
            case 84780028:
                echo "راهکار: موجودی حساب را بررسی کنید\n";
                break;
            case 84780001:
                echo "راهکار: اطلاعات کاربری را بررسی کنید\n";
                break;
            default:
                echo "راهکار: لطفاً دوباره تلاش کنید\n";
        }
    }

} catch (TaraException $e) {
    echo "خطای سیستمی: " . $e->getMessage();
}
```

### کدهای خطای رایج:

| کد | معنی | راهکار |
|---|------|---------|
| `84780028` | موجودی کافی نیست | بررسی موجودی حساب |
| `84780001` | اطلاعات کاربری نامعتبر | بررسی نام کاربری و رمز عبور |
| `84780002` | مبلغ تراکنش نامعتبر | بررسی مبلغ وارد شده |
| `84780003` | تراکنش تکراری | بررسی تراکنش‌های قبلی |
| `84780004` | خطا در اتصال | بررسی اتصال شبکه |
```

### کدهای خطای رایج

| کد خطا | پیام فارسی | توضیحات |
|--------|------------|---------|
| 84780028 | موجودی کافی نیست | موجودی کافی برای انجام تراکنش |
| 84780001 | کاربر یافت نشد | کاربر با این مشخصات وجود ندارد |
| 84780015 | ترمینال غیرفعال | ترمینال انتخاب شده فعال نیست |

**مثال response خطا:**
```json
{
  "success": false,
  "error": "موجودی کافی نیست.",
  "error_code": 84780028,
  "error_message": "موجودی کافی نیست.",
  "status": 400,
  "full_response": {
    "data": {"code": 84780028, "message": "موجودی کافی نیست."},
    "success": false,
    "timestamp": "2025-10-01T13:40:48.832853676Z"
  }
}
```

## 📚 منابع و مستندات‌حل‌ها

### مشکل: `purchaseData` تعریف نشده

**خطای معمول:**
```php
// ❌ اشتباه - purchaseData وجود ندارد
$result = $tara->completePurchaseFlow($payment, $purchaseData, $terminalCode);

```

**راه‌حل صحیح:**

```
// ✅ درست - ساخت purchaseData کامل
$item = $tara->createPurchaseItem('نام محصول', 'کد', 1, TaraConstants::UNIT_PIECE, 100000, 'گروه', 'عنوان', TaraConstants::MADE_IRANIAN);
$invoiceData = $tara->createInvoiceData(100000, 'INV001', '', 9000, [$item]);
$purchaseData = $tara->createPurchaseRequestData(100000, 'INV001', '', [$invoiceData]);
$result = $tara->completePurchaseFlow($payment, $purchaseData, $terminalCode);
```

**مثال کامل بدون خطا:** [TaraExampleFixed.php](./src/TaraExampleFixed.php)

📚 منابع و مستنداتreference) • [فارسی](#%D9%81%D8%A7%D8%B1%D8%B3%DB%8C)
----------------------------------------------------------------------

[](#-منابع-و-مستنداتreference--فارسی)

About Tara360
-------------

[](#about-tara360)

**Tara360** is Iran's leading credit payment and digital wallet application that enables customers to make purchases on credit and pay in installments. With over **14,000+ merchant partners** across Iran, Tara360 provides:

### � Specialized for In-Person Purchases

[](#-specialized-for-in-person-purchases)

- **Physical Store Integration**: Designed specifically for brick-and-mortar stores
- **POS Terminal Support**: Works with Tara360 POS terminals and cash registers
- **Branch & Terminal Management**: Handle multiple store locations and terminals
- **Real-time Transaction Processing**: Immediate payment processing for in-store purchases

### 💳 Credit Amounts

[](#-credit-amounts)

- **Micro Credit**: 500,000 to 10,000,000 IRR
- **Quick Loan**: Additional loan facilities for approved users
- **Organization Services**: Corporate credit solutions

### 🏆 Awards & Recognition

[](#-awards--recognition)

- **Winner of FAB Silver Award** in IT Product Excellence at the 8th National IT Awards
- Trusted by thousands of merchants and millions of customers

---

> **Note**: This package is specifically designed for **in-person purchases** at physical stores using Tara360 POS terminals. For online purchases or other Tara services, please check our other packages.

Installation
------------

[](#installation)

### Option 1: Install from Packagist (Recommended)

[](#option-1-install-from-packagist-recommended)

```
composer require shahkochaki/tara-in-person-purchases
```

### Option 2: Install from GitHub (If Packagist is not available)

[](#option-2-install-from-github-if-packagist-is-not-available)

Add to your `composer.json`:

```
{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/shahkochaki/tara-in-person-purchases.git"
    }
  ],
  "require": {
    "shahkochaki/tara-in-person-purchases": "^1.0"
  }
}
```

Then run:

```
composer install
```

Configuration
-------------

[](#configuration)

### Quick Setup (Recommended)

[](#quick-setup-recommended)

**1. Copy configuration files directly:**

FileDescriptionQuick Copy`.env` setupEnvironment variables[📋 Copy .env template](https://raw.githubusercontent.com/shahkochaki/tara-in-person-purchases/main/.env.example)Config fileLaravel configuration[📋 Copy config/tara.php](https://raw.githubusercontent.com/shahkochaki/tara-in-person-purchases/main/config/tara.php)**2. One-command setup:**

```
# Copy .env template
curl -o .env.tara https://raw.githubusercontent.com/shahkochaki/tara-in-person-purchases/main/.env.example

# Copy config file (Laravel)
curl -o config/tara.php https://raw.githubusercontent.com/shahkochaki/tara-in-person-purchases/main/config/tara.php
```

### Manual Setup

[](#manual-setup)

1. **Publish the config file (Laravel):**

```
php artisan vendor:publish --provider="Shahkochaki\TaraService\TaraServiceProvider"
```

2. **Add your Tara credentials to `.env`:**

```
# Tara API Configuration
TARA_BASE_URL=https://stage.tara-club.ir/club/api/v1
TARA_USERNAME=your_username_here
TARA_PASSWORD=your_password_here
TARA_BRANCH_CODE=your_branch_code_here
TARA_LOGGING=true
```

> ⚠️ **Security Note**: Never commit your actual credentials to version control. Replace the placeholder values with your real Tara API credentials.

### Configuration Options

[](#configuration-options)

📚 **Detailed Configuration Guide**: [CONFIG\_GUIDE.md](CONFIG_GUIDE.md)

SettingDescriptionDefault`TARA_BASE_URL`API base URL`https://stage.tara-club.ir/club/api/v1``TARA_USERNAME`Your Tara username**Required**`TARA_PASSWORD`Your Tara password**Required**`TARA_BRANCH_CODE`Your branch code**Required**`TARA_ENVIRONMENT`Environment (staging/production)`staging``TARA_TOKEN_BUFFER`Token expiry buffer (seconds)`60``TARA_LOGGING_ENABLED`Enable logging`true`### Environment-Specific Configuration

[](#environment-specific-configuration)

```
# Development/Staging
TARA_BASE_URL=https://stage.tara-club.ir/club/api/v1
TARA_ENVIRONMENT=staging

# Production
TARA_BASE_URL=https://api.tara-club.ir/club/api/v1
TARA_ENVIRONMENT=production
```

Usage
-----

[](#usage)

Usage
-----

[](#usage-1)

### Basic Implementation

[](#basic-implementation)

```
use Shahkochaki\TaraService\TaraService;
use Shahkochaki\TaraService\TaraConstants;

// Create instance (reads config automatically)
$tara = new TaraService();

// Or with specific branch code
$tara = new TaraService('your_branch_code');

// Or with custom configuration
$config = [
    'credentials' => [
        'username' => 'your_username',
        'password' => 'your_password'
    ],
    'default_branch_code' => 'your_branch_code'
];
$tara = new TaraService('your_branch_code', $config);
```

> 📖 **Complete Setup Guide**: [SETUP\_GUIDE.md](SETUP_GUIDE.md)

### Quick Start (One Method)

[](#quick-start-one-method)

```
try {
    $tara = new TaraService();

    // Customer barcode (one-time use from customer)
    $customerBarcode = 9700083615425377;
    $amount = 100000; // 100,000 IRR

    // Payment data
    $payment = [$tara->createTracePayment($customerBarcode, $amount, 0)];

    // Purchase items
    $items = [
        $tara->createPurchaseItem('نان سنگک', '12345', 2.0, 5, 50000, 'BAKERY', 'نانوایی', 1)
    ];

    $invoiceData = $tara->createInvoiceData($amount, 'INV-' . time(), 'Purchase', 9000, $items);
    $purchaseData = $tara->createPurchaseRequestData($amount, 'INV-' . time(), 'Test', $invoiceData);

    // Complete flow: login → terminals → trace → request → verify
    $result = $tara->completePurchaseFlow($payment, $purchaseData);

    if ($result['success']) {
        echo "Purchase successful! Trace: " . $result['traceNumber'];
    } else {
        echo "Purchase failed: " . $result['error'];
    }

} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
    echo "\nPlease ensure credentials are set in .env file";
}
```

### Step-by-Step Implementation

[](#step-by-step-implementation)

```
try {
    // 1. Initialize session (login + get terminals)
    $tara = new TaraService();
    $sessionResult = $tara->initializeSession();

    if (!$sessionResult['success']) {
        throw new Exception('Session failed: ' . $sessionResult['error']);
    }

    // 2. Select terminal (optional - uses first terminal if not selected)
    $terminals = $tara->getTerminals();
    $terminalCode = $terminals[0]['terminalCode'];
    $tara->selectTerminal($terminalCode);

    // 3. Create payment trace for customer
    $customerBarcode = 9700083615425377; // From customer (one-time use)
    $amount = 500000; // Amount in IRR (Rials)

    $payment = [
        $tara->createTracePayment($customerBarcode, $amount, 0)
    ];

    $traceResult = $tara->purchaseTrace($payment, $terminalCode);

    if (!$traceResult['success']) {
        throw new Exception('Trace failed: ' . $traceResult['error']);
    }

    $traceNumber = $traceResult['data']['traceNumber'];

    // 4. Create purchase items and invoice
    $item = $tara->createPurchaseItem(
        'Premium Product',           // Product name
        'PROD001',                  // Product code
        TaraConstants::UNIT_PIECE,  // Unit type
        2,                          // Quantity
        250000,                     // Unit price (IRR)
        'ELECTRONICS',              // Group code
        'Electronics',              // Group name
        TaraConstants::MADE_FOREIGN // Origin
    );

    $invoice = $tara->createInvoiceData(
        $amount,      // Total amount
        'INV-2025001', // Invoice number
        'Purchase description',
        0,            // Discount
        [$item]       // Items array
    );

    $purchaseData = $tara->createPurchaseRequestData(
        $amount,       // Total amount
        'INV-2025001', // Invoice number
        'Purchase via Tara API',
        [$invoice]     // Invoices array
    );

    // 5. Submit purchase request
    $requestResult = $tara->purchaseRequest($purchaseData, $traceNumber);

    if (!$requestResult['success']) {
        throw new Exception('Purchase request failed: ' . $requestResult['error']);
    }

    // 6. Verify purchase
    $verifyResult = $tara->purchaseVerify($traceNumber);

    if ($verifyResult['success']) {
        echo "Purchase completed successfully!";
        // Process successful payment
    } else {
        echo "Purchase verification failed: " . $verifyResult['error'];
        // Handle failed verification
    }

} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
    // Handle errors appropriately
}
```

API Reference
-------------

[](#api-reference)

### Core Methods

[](#core-methods)

#### Authentication

[](#authentication)

```
$result = $tara->login();
// Returns: ['success' => bool, 'data' => array, 'error' => string]
```

#### Terminal Management

[](#terminal-management)

```
$result = $tara->getAccessCode($branchCode = null);
$terminals = $tara->getAvailableTerminals($accessCodeResult);
$terminalCode = $tara->getTerminalCodeFromResponse($accessCodeResult, $index);
```

#### Product Categories

[](#product-categories)

```
$result = $tara->getMerchandiseGroups();
```

#### Purchase Flow

[](#purchase-flow)

```
// Create payment trace
$result = $tara->purchaseTrace($paymentArray, $terminalCode);

// Submit purchase request (with terminal code - optional)
$result = $tara->purchaseRequest($purchaseData, $traceNumber, $terminalCode);

// Verify purchase (with terminal code - optional)
$result = $tara->purchaseVerify($traceNumber, $terminalCode);

// Reverse/cancel purchase (with terminal code - optional)
$result = $tara->purchaseReverse($traceNumber, $terminalCode);

// Inquiry purchase status (with terminal code - optional)
$result = $tara->purchaseInquiry($referenceOrTraceNumber, $terminalCode);
```

> **Important Note**: All purchase operations (`purchaseRequest`, `purchaseVerify`, `purchaseReverse`, `purchaseInquiry`) now use **terminal tokens** instead of user tokens for better security and API compliance. Terminal code is optional - if not provided, the service will use the selected terminal or first available terminal.

```

### Helper Methods

```php
// Create payment data for trace
$payment = $tara->createTracePayment($userId, $amount, $discount);

// Create purchase item
$item = $tara->createPurchaseItem($name, $code, $unit, $quantity, $price, $groupCode, $groupName, $madeIn);

// Create invoice data
$invoice = $tara->createInvoiceData($totalAmount, $invoiceNumber, $description, $discount, $items);

// Create complete purchase request data
$purchaseData = $tara->createPurchaseRequestData($totalAmount, $invoiceNumber, $description, $invoices);

```

### Constants

[](#constants)

```
// Product Units
TaraConstants::UNIT_PIECE        // 5 - Piece
TaraConstants::UNIT_KILOGRAM     // 1 - Kilogram
TaraConstants::UNIT_METER        // 2 - Meter
TaraConstants::UNIT_LITER        // 3 - Liter
TaraConstants::UNIT_GRAM         // 4 - Gram

// Product Origin
TaraConstants::MADE_IRANIAN      // 1 - Made in Iran
TaraConstants::MADE_FOREIGN      // 2 - Foreign made
TaraConstants::MADE_UNKNOWN      // 0 - Unknown origin
```

Response Format
---------------

[](#response-format)

All methods return a standardized response array:

```
// Success Response
[
    'success' => true,
    'data' => [],              // Response data on success
]

// Error Response (Enhanced)
[
    'success' => false,        // Operation success status
    'error' => '',             // Main error message
    'error_code' => 84780028,  // API error code (if available)
    'error_message' => 'موجودی کافی نیست.',  // Detailed error message
    'error_data' => [],        // Full error data from API
    'status' => 400,           // HTTP status code
    'full_response' => [],     // Complete API response for debugging
]
```

Enhanced Error Handling
-----------------------

[](#enhanced-error-handling)

The service now provides detailed error information including **error codes** and **Persian error messages** from the Tara API:

```
try {
    $result = $tara->purchaseRequest($data, $traceNumber);

    if (!$result['success']) {
        // Display main error message
        echo "Error: " . $result['error'] . "\n";

        // Display error code if available
        if (isset($result['error_code'])) {
            echo "Error Code: " . $result['error_code'] . "\n";
        }

        // Display detailed error message
        if (isset($result['error_message'])) {
            echo "Details: " . $result['error_message'] . "\n";
        }

        // Full error data for debugging
        if (isset($result['error_data'])) {
            var_dump($result['error_data']);
        }
    }

} catch (Exception $e) {
    echo "System Error: " . $e->getMessage();
}
```

### Common Error Codes

[](#common-error-codes)

Error CodePersian MessageEnglish Description84780028موجودی کافی نیستInsufficient balance84780001کاربر یافت نشدUser not found84780015ترمینال غیرفعالTerminal inactive### Legacy Error Handling

[](#legacy-error-handling)

```
use Shahkochaki\TaraService\TaraException;

try {
    $result = $tara->purchaseRequest($data, $traceNumber);

    if (!$result['success']) {
        // Handle API errors
        Log::error('Tara API Error: ' . $result['error']);
        throw new TaraException($result['error']);
    }

} catch (TaraException $e) {
    // Handle Tara-specific exceptions
    return response()->json(['error' => $e->getMessage()], 400);
} catch (Exception $e) {
    // Handle general exceptions
    return response()->json(['error' => 'Payment processing failed'], 500);
}
```

Testing
-------

[](#testing)

```
# Run tests
composer test

# Or with PHPUnit directly
./vendor/bin/phpunit
```

Requirements
------------

[](#requirements)

- **PHP**: >= 7.4
- **Laravel**: >= 8.0
- **Extensions**: cURL, JSON

Contributing
------------

[](#contributing)

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

Security
--------

[](#security)

If you discover any security vulnerabilities, please email \[\] instead of using the issue tracker.

Changelog
---------

[](#changelog)

See [CHANGELOG.md](CHANGELOG.md) for detailed changes.

License
-------

[](#license)

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

Support
-------

[](#support)

- **Phone**: 1573 (7 days a week, 24 hours)
- **Website**:
- **Documentation**:

---

فارسی
=====

[](#فارسی)

درباره تارا۳۶۰
--------------

[](#درباره-تارا۳۶۰)

**تارا۳۶۰** یکی از پیشروترین اپلیکیشن‌های پرداخت اعتباری و کیف پول دیجیتال ایران است که به مشتریان امکان خرید اعتباری و پرداخت قسطی را می‌دهد. با بیش از **۱۴,۰۰۰ فروشگاه** شریک در سراسر ایران، تارا۳۶۰ خدماتی شامل:

### ✨ ویژگی‌های کلیدی

[](#-ویژگی‌های-کلیدی)

- **خرید اعتباری**: الان بخر، بعداً در ۲-۳ قسط پرداخت کن
- **کیف پول دیجیتال**: کیف پول نقدی با ۳٪ بازگشت پول
- **بدون ضامن**: تأیید آنی اعتبار بدون نیاز به ضامن
- **تأیید فوری**: دریافت اعتبار در کمتر از ۲۰ دقیقه
- **شبکه گسترده**: ۱۴,۰۰۰+ فروشگاه و مرکز خدماتی در سراسر کشور
- **آنلاین و حضوری**: پشتیبانی از خرید آنلاین و حضوری

### 💰 میزان اعتبار

[](#-میزان-اعتبار)

- **اعتبار خرد**: ۵۰۰,۰۰۰ تا ۱۰,۰۰۰,۰۰۰ تومان
- **وام فوری**: امکانات وام اضافی برای کاربران تأیید شده
- **خدمات سازمانی**: راهکارهای اعتباری سازمانی

نصب
---

[](#نصب)

```
composer require shahkochaki/tara-in-person-purchases
```

تنظیمات
-------

[](#تنظیمات)

۱. انتشار فایل تنظیمات:

```
php artisan vendor:publish --provider="Shahkochaki\TaraService\TaraServiceProvider"
```

۲. اضافه کردن اطلاعات تارا به `.env`:

```
TARA_BASE_URL=https://stage.tara-club.ir/club/api/v1
TARA_USERNAME=نام_کاربری_شما
TARA_PASSWORD=رمز_عبور_شما
TARA_BRANCH_CODE=کد_شعبه_شما
```

استفاده
-------

[](#استفاده)

### پیاده‌سازی ساده

[](#پیاده‌سازی-ساده)

```
use Shahkochaki\TaraService\TaraService;
use Shahkochaki\TaraService\TaraConstants;

// استفاده از dependency injection (توصیه شده)
$tara = app(TaraService::class);

// یا ایجاد دستی
$tara = new TaraService('کد_شعبه', 'نام_کاربری', 'رمز_عبور');
```

### فرآیند کامل خرید

[](#فرآیند-کامل-خرید)

```
// ۱. ورود به سیستم (خودکار با اولین فراخوانی API)
$loginResult = $tara->login();

// ۲. دریافت کد دسترسی و انتخاب ترمینال
$accessCodeResult = $tara->getAccessCode();
$terminalCode = $tara->getTerminalCodeFromResponse($accessCodeResult, 0);

// ۳. ایجاد ردیابی پرداخت
$userId = ۱۲۳۴۵۶۷۸۹۰; // شناسه کاربری مشتری
$amount = ۵۰۰۰۰۰; // مبلغ به ریال

$payment = [
    $tara->createTracePayment($userId, $amount, 0)
];

$traceResult = $tara->purchaseTrace($payment, $terminalCode);
$traceNumber = $traceResult['data']['traceNumber'];

// ۴. ایجاد آیتم خرید و فاکتور
$item = $tara->createPurchaseItem(
    'محصول پریمیم',                // نام محصول
    'PROD001',                  // کد محصول
    ۲,                          // تعداد
    TaraConstants::UNIT_PIECE,  // نوع واحد
    ۲۵۰۰۰۰,                     // قیمت واحد (ریال)
    'ELECTRONICS',              // کد گروه
    'الکترونیک',                // نام گروه
    TaraConstants::MADE_FOREIGN // منشأ
);

// ۵. ایجاد اطلاعات فاکتور
$invoiceData = $tara->createInvoiceData(
    ۵۰۰۰۰۰,                     // مبلغ کل
    'INV' . time(),            // شماره فاکتور
    '',                        // اطلاعات اضافی
    ۴۵۰۰۰,                     // مالیات (۹%)
    [$item]                    // آیتم‌های خرید
);

// ۶. ایجاد درخواست خرید (purchaseData)
$purchaseData = $tara->createPurchaseRequestData(
    ۵۰۰۰۰۰,                    // مبلغ
    'INV' . time(),           // شماره فاکتور
    '',                       // اطلاعات اضافی
    [$invoiceData]            // اطلاعات فاکتور
);

// ۷. ارسال درخواست خرید
$requestResult = $tara->purchaseRequest($purchaseData, $traceNumber);

// ۸. تأیید خرید
$verifyResult = $tara->purchaseVerify($traceNumber);
```

� منابع و مستندات
-----------------

[](#-منابع-و-مستندات)

### فایل‌های پیکربندی

[](#فایل‌های-پیکربندی)

نوع فایلتوضیحاتلینک مستقیم برای کپی`.env`متغیرهای محیطی[کپی فایل .env](https://raw.githubusercontent.com/shahkochaki/tara-in-person-purchases/main/.env.example)`config/tara.php`پیکربندی Laravel[کپی فایل config](https://raw.githubusercontent.com/shahkochaki/tara-in-person-purchases/main/config/tara.php)### راهنماهای تخصصی

[](#راهنماهای-تخصصی)

موضوعتوضیحاتفایلنصب و راه‌اندازیراهنمای گام به گام نصب[SETUP\_GUIDE.md](./docs/SETUP_GUIDE.md)پیکربندی سیستمتنظیمات پیشرفته[CONFIG\_GUIDE.md](./docs/CONFIG_GUIDE.md)جریان کاری APIتوضیح کامل فرآیند[API\_FLOW\_GUIDE.md](./docs/API_FLOW_GUIDE.md)### دستورات سریع برای شروع

[](#دستورات-سریع-برای-شروع)

```
# کپی فایل پیکربندی محیطی
curl -o .env https://raw.githubusercontent.com/shahkochaki/tara-in-person-purchases/main/.env.example

# کپی فایل پیکربندی Laravel (اختیاری)
mkdir -p config
curl -o config/tara.php https://raw.githubusercontent.com/shahkochaki/tara-in-person-purchases/main/config/tara.php
```

### نمونه کدهای عملی

[](#نمونه-کدهای-عملی)

نوع کدتوضیحاتفایلاستفاده سادهمثال کلی از سرویس[TaraExample.php](./src/TaraExample.php)پیکربندی محیطیاستفاده از env variables[TaraExampleUpdated.php](./src/TaraExampleUpdated.php)پیکربندی پیشرفتهاستفاده از config arrays[TaraConfigExample.php](./src/TaraConfigExample.php)**کد اصلاح شده****رفع مشکل purchaseData**[**TaraExampleFixed.php**](./src/TaraExampleFixed.php)**مدیریت خطا****نمایش کد و پیام خطا**[**TaraErrorHandlingExample.php**](./src/TaraErrorHandlingExample.php)پیکربندی پیشرفتهاستفاده از config arrays[TaraConfigExample.php](./src/TaraConfigExample.php)�📄 مستندات کامل فارسی
---------------------

[](#-مستندات-کامل-فارسی)

برای راهنمای کامل و مستندات فارسی، فایل زیر را مشاهده کنید:

[دانلود مستندات فارسی (Persian-document.pdf)](./Persian-document.pdf)

پشتیبانی
--------

[](#پشتیبانی)

- **تلفن**: ۱۵۷۳ (۷ روز هفته، ۲۴ ساعته)
- **وب‌سایت**:
- **سوالات متداول**:

مجوز
----

[](#مجوز)

مجوز MIT. برای اطلاعات بیشتر [فایل مجوز](LICENSE) را مشاهده کنید.

###  Health Score

39

—

LowBetter than 86% of packages

Maintenance65

Regular maintenance activity

Popularity18

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~4 days

Total

5

Last Release

210d ago

Major Versions

v1.0.0 → v2.0.02025-09-30

PHP version history (2 changes)v1.0.0PHP >=7.4

2.2.1PHP ^7.4|^8.0|^8.1|^8.2|^8.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/de31856b93697866020ad79667e85b4cce9440e231c65a5582f0d1a611983860?d=identicon)[shahkochaki](/maintainers/shahkochaki)

---

Top Contributors

[![shahkochaki](https://avatars.githubusercontent.com/u/19410674?v=4)](https://github.com/shahkochaki "shahkochaki (24 commits)")

---

Tags

paymentpayment-gatewaypayment-servicetaraterminallaravelpaymentpospurchaseiranpersiancredit-cardtarairanian-paymentin-person

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/shahkochaki-tara-in-person-purchases/health.svg)

```
[![Health](https://phpackages.com/badges/shahkochaki-tara-in-person-purchases/health.svg)](https://phpackages.com/packages/shahkochaki-tara-in-person-purchases)
```

###  Alternatives

[dena-a/iran-payment

a Laravel package to handle Internet Payment Gateways for Iran Banking System

312.4k1](/packages/dena-a-iran-payment)[mwguerra/web-terminal

A web-based terminal component for Filament/Laravel with command whitelisting and multiple connection types

251.1k](/packages/mwguerra-web-terminal)[sunaoka/laravel-facade-generator

Provide command line generation of facade layer files.

171.9k](/packages/sunaoka-laravel-facade-generator)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)