README

Laravel Vandar SDK

A structured, secure, and Laravel-native integration with Vandar APIs.

Laravel Vandar SDK is designed, developed, and maintained by Zarbin ITD Company.

Company website: https://zarbinco.com
Repository: https://github.com/zarbinco/laravel-vandar

Laravel Vandar SDK provides a structured Laravel integration layer for Vandar APIs. It helps teams avoid repeating the same low-level financial API integration work in every project: authentication, access and refresh token management, request construction, response normalization, API error mapping, sensitive data protection, retry and idempotency considerations, logging, testing, and maintenance when APIs evolve.

The SDK centralizes these concerns so Laravel teams can focus on their own application business logic. It sends Vandar API requests and returns structured responses; the consuming application still owns its financial ledger, reconciliation records, payment state, authorization rules, and business-level idempotency.

Purpose

The project exists to make Vandar integrations easier to build, test, maintain, and review inside Laravel applications. Instead of scattering HTTP calls, token handling, response parsing, and redaction logic across application code, the package exposes a Laravel-native SDK surface with consistent resources, DTOs, exceptions, configuration, and testing fakes.

Core capabilities

The current implementation includes:

IPG payment request, gateway URL generation, transaction lookup, verification, and safe callback verification helpers.
Business information, users, balance, wallet alias, and transaction listing.
Customers, customer fields, customer wallet operations, customer authentication, and customer cash-in code operations.
Customer cards and customer IBAN operations.
Banking and identity inquiries, including KYC, Shahkar, national ID, postal code, company, IBAN, card, and card-to-IBAN inquiries.
Refund, settlement, queued settlement, and batch settlement operations.
Avand / cash-in account, balance, statement, label, code, PIC transaction, and suspicious-payment operations.
Subscription / Direct Debit banks, authorizations, withdrawals, and refunds.
Secure access-token and refresh-token management with config, cache, and custom token stores.
Structured VandarResponse DTOs and structured API exception handling.
Sensitive-data redaction for package logs and exception context.
Offline fakes, Laravel HTTP testing fakes, and request assertions.
Raw API access for advanced cases that are not yet represented by named resource methods.

Ravand is intentionally documented as future work and is not presented as a supported capability.

Value proposition

Reduces duplicated integration code across Laravel projects.
Provides a consistent Laravel developer experience through a facade, service provider, publishable config, resources, DTOs, and exceptions.
Centralizes authentication, token refresh, response handling, error mapping, and redaction.
Improves testability with offline fakes and request assertions.
Keeps the SDK extensible through resource classes and raw API access.
Makes it faster to add support for future Vandar API capabilities while keeping application workflows app-owned.

Architecture

The package is exposed through the Vandar facade and resource-oriented entry points:

Vandar::business();
Vandar::customers();
Vandar::cards();
Vandar::ibans();
Vandar::inquiries();
Vandar::ipg();
Vandar::refunds();
Vandar::settlements();
Vandar::queuedSettlements();
Vandar::batchSettlements();
Vandar::avand();
Vandar::cashIn();
Vandar::subscriptions();
Vandar::subscription();
Vandar::directDebit();
Vandar::tokens();
Vandar::raw();

Vandar::tokens() exposes advanced token utilities for applications that intentionally manage token lifecycle through the SDK. The accessor itself is part of the supported facade surface, but low-level TokenManager methods and token-store implementation details are not covered by the public API compatibility guarantee.

All named resources return Zarbinco\LaravelVandar\DTO\VandarResponse for HTTP responses, with helpers for status checks, JSON/data access, messages, errors, rate-limit metadata, raw body diagnostics, and redacted body output.

Project status

The package is in active pre-1.0 development. Current repository evidence includes automated PHPUnit tests, PHPStan/Larastan analysis, a public API compatibility audit, Laravel Pint formatting checks, Composer validation, GitHub Actions CI, bilingual documentation, a changelog, a security policy, an upgrade guide, endpoint support documentation, testing utilities, and production-oriented safety notes.

Because this is a financial API SDK, consuming applications should review the endpoint support matrix and safety guidance before each upgrade.

Compatibility

Laravel	Testbench used in package CI	Supported PHP
12	10	8.2–8.5
13	11	8.3–8.5

Laravel 12 is now the minimum supported Laravel version. Laravel 11 support was intentionally removed for the next minor release, recommended as v0.5.0. Laravel 12 or Laravel 13 is required for new unrestricted installs of this release line.

Testbench is a development dependency only. Applications do not install Testbench as a runtime package. Composer selects compatible dependencies according to the application's PHP and Laravel versions.

Laravel 13 requires PHP 8.3 or newer; Laravel 13 cannot be installed on PHP 8.2. Laravel 12 consumers can continue using PHP 8.2.

Laravel 11 applications must remain on the last Laravel-11-compatible package release, for example composer require zarbinco/laravel-vandar:^0.4, until the application upgrades to Laravel 12 or Laravel 13. Existing Laravel 11 installations do not fail immediately merely because a new package release exists, but their next unrestricted Composer update must not install this incompatible release.

Quick Start

Install the package with Composer:

composer require zarbinco/laravel-vandar

Publish the Laravel configuration file:

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

Configure the values your application needs:

VANDAR_BUSINESS=
VANDAR_ACCESS_TOKEN=
VANDAR_REFRESH_TOKEN=
VANDAR_TOKEN_STORE=cache
VANDAR_IPG_API_KEY=
VANDAR_IPG_CALLBACK_URL=

Use the facade from application code:

use Zarbinco\LaravelVandar\Facades\Vandar;

$balance = Vandar::business()->balance();

if ($balance->successful()) {
    $data = $balance->data();
}

For production systems, read the security notes, payment integration guide, and endpoint support matrix before enabling money-moving flows.

Detailed documentation

Developed and maintained by

Zarbin ITD Company

Website: https://zarbinco.com
GitHub: https://github.com/zarbinco
Package repository: https://github.com/zarbinco/laravel-vandar

Cooperation with Vandar

Zarbin is interested in technical collaboration with Vandar to keep the SDK aligned with the platform, improve documentation and integration standards, support new Vandar services faster, receive technical feedback, and explore a path toward formal recognition or support.

This section describes a cooperation objective. It does not state any current Vandar approval, endorsement, certification, or maintenance responsibility for the SDK.

Trademark clarification

Vandar and its related trademarks belong to their respective legal owners. Their use in this repository is solely to identify the APIs and services supported by this SDK.

License

The package is open-sourced software licensed under the MIT license.

zarbinco / laravel-vandar

Maintainers

Package info

Statistics

Security