README

A comprehensive Yii2 extension for the PayWall Payment Gateway — supports checkout, 3D Secure, direct payments, recurring billing, marketplace, card management, payout, bulk payments, and more.

Requirements

• PHP >= 8.1
• Yii2 >= 2.0

Installation

composer require mskayali/paywall

Quick Start

1. Configure as Yii2 Component

// config/web.php or config/main.php
return [
    'components' => [
        'paywall' => [
            'class' => \mskayali\paywall\PayWallClient::class,
            'baseUrl' => 'https://payment-api.paywall.com.tr',
        ],
    ],
];

2. Set API Keys

// In bootstrap or EVENT_BEFORE_REQUEST
$paywall = Yii::$app->paywall;
$paywall->setApiclientpublic('YOUR_API_KEY');
$paywall->setApikeypublic('YOUR_SECRET_KEY');
$paywall->setMerchantUID('YOUR_MERCHANT_UID');

3. Make a 3D Secure Payment

use mskayali\paywall\models\ThreeDPaymentRequest;
use mskayali\paywall\models\CurrencyCodeId;

$paymentService = Yii::$app->paywall->getPaymentServices();

$request = new ThreeDPaymentRequest();
$request->load([
    'MerchantUniqueCode' => 'ORDER-' . time(),
    'Amount' => 99.90,
    'CurrencyId' => CurrencyCodeId::TRY->value,
    'InstallmentCount' => 1,
    'CardHolderName' => 'John Doe',
    'CardNo' => '4111111111111111',
    'CardExpireMonth' => '12',
    'CardExpireYear' => '2028',
    'Cvv' => '123',
    'SuccessUrl' => 'https://example.com/success',
    'FailUrl' => 'https://example.com/fail',
], '');

$result = $paymentService->start3DPayment($request);

if ($result->success) {
    // Redirect to 3D Secure page
    return $this->redirect($result->data->Url);
}

Services

The SDK provides 16 specialized services accessible via PayWallClient:

Payment Workflows

Direct Payment (Non-3D)

$request = new PaymentAsyncSaleRequest();
$request->load([...], '');
$result = $paymentService->startDirectPayment($request);

Cancel & Refund

// Same-day = Cancel, next day = Refund, partial amount = Partial Refund
$result = $paymentService->revertPayment(
    uniqueCode: 'PAYWALL-GUID-123',
    amount: 50.00  // null or 0 = full refund
);

Installment Inquiry

use mskayali\paywall\models\InstallmentRequest;

$request = new InstallmentRequest();
$request->load([
    'BinNumber' => '411111',
    'Amount' => 500.00,
    'CurrencyId' => CurrencyCodeId::TRY->value,
], '');
$result = $paymentService->getInstallments($request);

Hosted Checkout Page

use mskayali\paywall\models\CheckoutGenerateRequest;

$request = new CheckoutGenerateRequest();
$request->load([
    'MerchantUniqueCode' => 'CHECKOUT-' . uniqid(),
    'Amount' => 250.00,
    'CurrencyId' => CurrencyCodeId::TRY->value,
    'SuccessUrl' => 'https://example.com/success',
    'FailUrl' => 'https://example.com/fail',
], '');
$result = $checkoutService->createCheckoutPage($request);

Recurring / Subscription

use mskayali\paywall\models\RecurringCreateRequest;
use mskayali\paywall\models\SubscriptionType;
use mskayali\paywall\models\RecurringPeriodType;

$request = new RecurringCreateRequest();
$request->load([
    'SubscriptionMerchantCode' => 'SUB-' . uniqid(),
    'Amount' => 49.99,
    'CurrencyId' => CurrencyCodeId::TRY->value,
    'SubscriptionType' => SubscriptionType::UNLIMITED->value,
    'RecurringPeriodType' => RecurringPeriodType::MONTHLY->value,
    'SuccessUrl' => 'https://example.com/subscription/success',
    'FailUrl' => 'https://example.com/subscription/fail',
], '');
$result = $recurringService->createRecurring($request);

Sub-Merchant (Member) Management

use mskayali\paywall\models\Member;
use mskayali\paywall\models\MerchantTypeId;

$member = new Member();
$member->IsSubMerchant = true;
$member->MemberType = MerchantTypeId::INDIVIDUAL;
$member->MemberExternalId = 'EXT-001';
$member->MemberName = 'Acme Corp';
$member->MemberTitle = 'Acme Corporation';
$member->MemberEmail = 'info@acme.com';
$member->MemberPhone = '5551234567';
$member->MemberAddress = '123 Business St, Istanbul';
$member->ContactName = 'John';
$member->ContactLastname = 'Doe';

$result = $memberService->createMember($member);

Enums

The SDK includes PHP 8.1+ enums for type safety:

use mskayali\paywall\models\CurrencyCodeId;      // TRY, USD, EUR, GBP, ...
use mskayali\paywall\models\PaymentTypeId;        // SALE, CANCELLATION, REFUND
use mskayali\paywall\models\PaymentStatusId;      // CREATED, SUCCESS, FAILED, ...
use mskayali\paywall\models\MerchantTypeId;       // INDIVIDUAL, PERSONAL_COMPANY, ...
use mskayali\paywall\models\CardBrandId;          // VISA, MASTERCARD, AMEX, TROY
use mskayali\paywall\models\SubscriptionType;     // UNLIMITED, COUNT_BASED
use mskayali\paywall\models\RecurringPeriodType;  // DAILY, WEEKLY, MONTHLY, ...
use mskayali\paywall\models\FeedbackType;         // Webhook callback types
use mskayali\paywall\models\RegionCountry;        // TR, US, DE, GB, ...

// All enums support fromName() lookup:
$currency = CurrencyCodeId::fromName('TRY'); // CurrencyCodeId::TRY

Error Handling

All service methods return a DynamicModel with:

$result = $paymentService->start3DPayment($request);

if ($result->success) {
    $data = $result->data;  // Response body
} else {
    $error = $result->error;
    // $error['code']    — Error code
    // $error['message'] — Error description
}

Testing

composer install
./vendor/bin/phpunit --testdox

Project Structure

├── src/
│   ├── PayWallClient.php          # Main HTTP client (extends yii\httpclient\Client)
│   ├── models/                    # ~114 request/response models + Enums
│   │   ├── BaseResponse.php       # Standard API response wrapper
│   │   ├── Enums.php              # 35+ PHP 8.1 enums
│   │   ├── Member.php             # Member model with validation
│   │   └── ...
│   └── services/                  # 16 service classes
│       ├── PaymentService.php
│       ├── MemberService.php
│       └── ...
├── tests/                         # PHPUnit test suites
├── examples/                      # Usage examples
├── composer.json
└── phpunit.xml

API Endpoints

The PayWall API operates across multiple subdomains:

License

MIT License. See LICENSE for details.