README

A PHP SDK for integrating the Halkode payment gateway into your application. Designed as a Yii2-compatible Composer package with clean abstraction for token storage, encryption, and multi-language response handling.

📖 Official Integration Docs: This SDK is built based on the official Halkode Integration Documentation. Refer to it for detailed API specifications, parameter descriptions, and response formats.

Table of Contents

• Requirements
• Installation
• Configuration
• Quick Start
• API Reference
• Payment Workflows
• Token Storage
• Error Handling
• Testing
• Project Structure
• License

Requirements

• PHP >= 8.1
• yiisoft/yii2 ~2.0.0
• yiisoft/yii2-httpclient ~2.0.0

Installation

composer require mskayali/halkode

Configuration

As a Yii2 Component

Add the following to your config/web.php or config/main.php:

'components' => [
    'halkode' => [
        'class'            => \mskayali\halkode\Client::class,
        'baseUrl'          => \mskayali\halkode\Client::BASE_URL_DEV, // or BASE_URL_PROD
        'merchantUID'      => 'your-merchant-uid',
        'apikeypublic'     => 'your-api-secret-key',
        'apiclientpublic'  => 'your-api-client-key',
        'language'         => 'tr', // 'tr' or 'en' for response messages
        // Optional: custom token storage (see Token Storage section)
        // 'tokenStorage' => new RedisTokenStorage($redis),
    ],
],

Standalone Usage

use mskayali\halkode\Client;

$client = new Client([
    'baseUrl'          => Client::BASE_URL_DEV,
    'merchantUID'      => 'your-merchant-uid',
    'apikeypublic'     => 'your-api-secret-key',
    'apiclientpublic'  => 'your-api-client-key',
]);

$services = $client->getPaymentServices();

Environment URLs

Quick Start

use mskayali\halkode\Client;
use mskayali\halkode\models\PurchaseLinkRequest;
use mskayali\halkode\models\Invoice;
use mskayali\halkode\models\InvoiceItem;

// 1. Create client
$client = new Client([
    'baseUrl'          => Client::BASE_URL_DEV,
    'merchantUID'      => 'your-merchant-uid',
    'apikeypublic'     => 'your-api-secret-key',
    'apiclientpublic'  => 'your-api-client-key',
]);

// 2. Build invoice
$invoice = new Invoice([
    'invoice_id'          => 'INV-' . time(),
    'invoice_description' => 'Order #123',
    'total'               => 250.00,
    'return_url'          => 'https://example.com/payment/success',
    'cancel_url'          => 'https://example.com/payment/cancel',
    'items'               => [
        new InvoiceItem(['name' => 'Widget', 'price' => 250, 'quantity' => 1]),
    ],
]);

// 3. Create payment link
$services = $client->getPaymentServices();
$result   = $services->purchaseLink(new PurchaseLinkRequest([
    'currency_code' => 'TRY',
    'invoice'       => $invoice,
    'name'          => 'John',
    'surname'       => 'Doe',
]));

if ($result->success) {
    // Redirect user to the payment page
    header('Location: ' . $result->data->link);
}

API Reference

Available Services

All services are accessed through $client->getPaymentServices():

Response Structure

Every service method returns an object with these attributes:

$result->success;  // bool — whether the operation succeeded
$result->message;  // string|null — localized status message (based on Client language)
$result->data;     // object|null — response data on success
$result->error;    // mixed|null — error details on failure

Payment Workflows

Workflow 1: Hosted Payment Page (Purchase Link)

Best for: redirecting users to a Halkode-hosted payment page.

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  Client   │────▶│  Server  │────▶│ Halkode  │────▶│ Customer │
│  (Your    │     │ purchase │     │ Hosted   │     │ completes│
│   App)    │◀────│  Link()  │◀────│ Page     │◀────│ payment  │
└──────────┘     └──────────┘     └──────────┘     └──────────┘
                                       │
                               redirect to return_url
                               or cancel_url

// Step 1: Create payment link
$result = $services->purchaseLink(new PurchaseLinkRequest([
    'currency_code' => 'TRY',
    'invoice'       => $invoice,
    'name'          => 'John',
    'surname'       => 'Doe',
]));

// Step 2: Redirect user
if ($result->success) {
    return redirect($result->data->link);
}

// Step 3: Handle callback (on your return_url)
// Halkode redirects back with payment result in POST data
$invoiceId = $_POST['invoice_id'];
$status    = $services->checkstatus(new CheckstatusRequest([
    'invoice_id'   => $invoiceId,
    'merchant_key' => $client->getMerchantUID(),
]));

if ($status->success) {
    // Payment confirmed — update your order
}

Workflow 2: Direct Card Payment (2D)

Best for: collecting card data on your own PCI-compliant form.

// Step 1: Charge the card directly
$result = $services->paySmart2D(new PaySmart2DRequest([
    'cc_holder_name'      => 'John Doe',
    'cc_no'               => '4155141122223339',
    'expiry_month'        => '12',
    'expiry_year'         => '26',
    'cvv'                 => '555',
    'currency_code'       => 'TRY',
    'installments_number' => 1,
    'invoice_id'          => 'INV-' . time(),
    'invoice_description' => 'Premium subscription',
    'total'               => 99.00,
    'name'                => 'John',
    'surname'             => 'Doe',
]));

// Step 2: Check result
if ($result->success) {
    $orderNo = $result->data->order_no;
    // Save $orderNo to your database for future reference
} else {
    $error = $result->error;
    // Display error to user or log
}

Workflow 3: 3D Secure Payment

Best for: most production card payments — adds an extra bank verification step.

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  Your    │────▶│ Halkode  │────▶│ Bank 3D  │────▶│ Halkode  │
│  Server  │     │ API      │     │ Verify   │     │ Callback │
│ paySmart │     │ returns  │     │ Page     │     │ return   │
│   3D()   │     │ redirect │     │ (OTP)    │     │ _url     │
└──────────┘     └──────────┘     └──────────┘     └──────────┘
                                                         │
                                                   ┌─────▼─────┐
                                                   │ Your App  │
                                                   │ handles   │
                                                   │ callback  │
                                                   └───────────┘

// Step 1: Initiate 3D payment
$result = $services->paySmart3D(new PaySmart3DRequest([
    'cc_holder_name'      => 'John Doe',
    'cc_no'               => '4155141122223339',
    'expiry_month'        => '12',
    'expiry_year'         => '26',
    'cvv'                 => '555',
    'currency_code'       => 'TRY',
    'installments_number' => 1,
    'invoice_id'          => 'INV-3D-' . time(),
    'total'               => 500.00,
    'name'                => 'John',
    'surname'             => 'Doe',
    'return_url'          => 'https://example.com/payment/3d-callback',
    'cancel_url'          => 'https://example.com/payment/cancel',
]));

// Step 2: Redirect user to 3D verification
if ($result->success) {
    return redirect($result->data->redirect_url);
}

// Step 3: Handle 3D callback (on your return_url)
// The bank redirects back after OTP verification
$invoiceId = $_POST['invoice_id'] ?? $_GET['invoice_id'];

// Step 4: Verify the payment status
$status = $services->checkstatus(new CheckstatusRequest([
    'invoice_id'   => $invoiceId,
    'merchant_key' => $client->getMerchantUID(),
]));

if ($status->success && $status->data->payment_status == 1) {
    // Payment successful — fulfill the order
} else {
    // Payment failed or pending
}

Workflow 4: Pre-Authorization + Capture

Best for: reserving funds first, then capturing later (e.g., hotel bookings, car rentals).

// Step 1: Pre-authorize (hold funds on the card)
$result = $services->paySmart2D(new PaySmart2DRequest([
    'cc_holder_name'      => 'John Doe',
    'cc_no'               => '4155141122223339',
    'expiry_month'        => '12',
    'expiry_year'         => '26',
    'cvv'                 => '555',
    'currency_code'       => 'TRY',
    'installments_number' => 1,
    'invoice_id'          => 'PREAUTH-' . time(),
    'total'               => 1000.00,
    'name'                => 'John',
    'surname'             => 'Doe',
    'transaction_type'    => TransactionType::PreAuthorization,
]));

// Step 2: Later — confirm (capture) the payment
if ($result->success) {
    $confirmed = $services->confirmPayment(new ConfirmPaymentRequest([
        'invoice_id'   => 'PREAUTH-XXX',
        'total'        => '1000.00',
        'status'       => '1',
        'merchant_key' => $client->getMerchantUID(),
        'hash_key'     => $client->generateHash('PREAUTH-XXX'),
    ]));

    if ($confirmed->success) {
        // Funds captured — order finalized
    }
}

Workflow 5: Refund (Full or Partial)

// Full refund
$result = $services->refundPayment(new RefundAPIRequest([
    'invoice_id'   => 'INV-ORIGINAL',
    'amount'       => 99.00,      // Full amount
    'app_id'       => $client->apiclientpublic,
    'app_secret'   => $client->apikeypublic,
    'merchant_key' => $client->getMerchantUID(),
    'hash_key'     => $client->generateHash('INV-ORIGINAL'),
]));

// Partial refund (e.g., 30 TRY of a 99 TRY charge)
$partialRefund = $services->refundPayment(new RefundAPIRequest([
    'invoice_id'   => 'INV-ORIGINAL',
    'amount'       => 30.00,      // Partial amount
    'app_id'       => $client->apiclientpublic,
    'app_secret'   => $client->apikeypublic,
    'merchant_key' => $client->getMerchantUID(),
    'hash_key'     => $client->generateHash('INV-ORIGINAL'),
]));

Workflow 6: Transaction Monitoring & Reconciliation

// Check a specific transaction
$tx = $services->getTransaction(new GetTransactionRequest([
    'invoice_id'   => 'INV-001',
    'merchant_key' => $client->getMerchantUID(),
    'hash_key'     => $client->generateHash('INV-001'),
]));

// List all transactions (for daily reconciliation)
$allTx = $services->allTransaction(new AllTransactionRequest([
    'merchant_key' => $client->getMerchantUID(),
]));

// Check payment status (polling for async flows)
$status = $services->checkstatus(new CheckstatusRequest([
    'invoice_id'   => 'INV-001',
    'merchant_key' => $client->getMerchantUID(),
]));

Workflow 7: Installment Query Before Payment

Best for: showing available installment options to the user before payment.

// Step 1: Query installments for the card BIN
$installments = $services->getInstallment(new GetInstallmentRequest([
    'bin_number'    => substr($cardNumber, 0, 6), // First 6 digits
    'total'         => 1200.00,
    'currency_code' => 'TRY',
]));

// Step 2: Display installment options to user
if ($installments->success) {
    foreach ($installments->data as $option) {
        echo "Installments: {$option->installment_number} "
           . "— Monthly: {$option->monthly_payment} TRY "
           . "— Total: {$option->total_amount} TRY\n";
    }
}

// Step 3: User selects installment count, then call paySmart2D/3D
$result = $services->paySmart3D(new PaySmart3DRequest([
    'installments_number' => 6,  // User's selection
    // ... other fields
]));

Workflow 8: POS Selection

Query available POS terminals for a card:

$pos = $services->getPos(new GetPosRequest([
    'credit_card'   => '415514',  // First 6 digits (BIN)
    'amount'        => 500.00,
    'currency_code' => 'TRY',
    'merchant_key'  => $client->getMerchantUID(),
]));

if ($pos->success) {
    // pos->data contains available POS terminals with:
    // - pos_id, card_type, card_scheme
    // - payable_amount, hash_key
    // - commission_rate, installment details
}

Token Storage

The SDK automatically manages API authentication tokens. By default, tokens are stored in-memory and discarded after each request.

Default: In-Memory Storage

// No configuration needed — MemoryTokenStorage is used automatically
$client = new Client([...]);

Custom: Redis Storage (Plain)

For persistent token caching across requests:

use mskayali\halkode\TokenStorageInterface;

class RedisTokenStorage implements TokenStorageInterface
{
    private \Redis $redis;

    public function __construct(\Redis $redis)
    {
        $this->redis = $redis;
    }

    public function get(string $key): ?string
    {
        $value = $this->redis->get($key);
        return $value === false ? null : $value;
    }

    public function set(string $key, string $value, int $ttl): bool
    {
        return $this->redis->setex($key, $ttl, $value);
    }
}

// Usage:
$client = new Client([
    // ... credentials
    'tokenStorage' => new RedisTokenStorage($redis),
]);

Recommended: Encrypted Redis Storage

⚠️ Security Note: API tokens stored in Redis are sensitive credentials. If your Redis instance is shared, accessible over a network, or not configured with TLS, you should encrypt tokens before storing them. This prevents token leakage if Redis is compromised.

use mskayali\halkode\TokenStorageInterface;

class EncryptedRedisTokenStorage implements TokenStorageInterface
{
    private \Redis $redis;
    private string $encryptionKey;
    private string $cipher = 'aes-256-cbc';

    /**
     * @param \Redis $redis       Connected Redis instance
     * @param string $encryptionKey A 32-byte (256-bit) secret key.
     *                              Generate once with: bin2hex(random_bytes(16))
     *                              Store securely (e.g., environment variable).
     */
    public function __construct(\Redis $redis, string $encryptionKey)
    {
        $this->redis = $redis;
        $this->encryptionKey = $encryptionKey;
    }

    public function get(string $key): ?string
    {
        $encrypted = $this->redis->get($key);
        if ($encrypted === false) {
            return null;
        }

        $data = base64_decode($encrypted);
        $ivLength = openssl_cipher_iv_length($this->cipher);
        $iv = substr($data, 0, $ivLength);
        $ciphertext = substr($data, $ivLength);

        $decrypted = openssl_decrypt($ciphertext, $this->cipher, $this->encryptionKey, OPENSSL_RAW_DATA, $iv);
        return $decrypted === false ? null : $decrypted;
    }

    public function set(string $key, string $value, int $ttl): bool
    {
        $iv = openssl_random_pseudo_bytes(openssl_cipher_iv_length($this->cipher));
        $ciphertext = openssl_encrypt($value, $this->cipher, $this->encryptionKey, OPENSSL_RAW_DATA, $iv);

        $encrypted = base64_encode($iv . $ciphertext);

        if ($ttl > 0) {
            return $this->redis->setex($key, $ttl, $encrypted);
        }
        return $this->redis->set($key, $encrypted);
    }
}

Setup:

// 1. Generate an encryption key ONCE and store it securely:
//    php -r "echo bin2hex(random_bytes(16));"
//    → e.g., "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

// 2. Store the key in an environment variable:
//    HALKODE_TOKEN_KEY=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

// 3. Use in your application:
$redis = new \Redis();
$redis->connect('127.0.0.1', 6379);

$client = new Client([
    'baseUrl'          => Client::BASE_URL_PROD,
    'merchantUID'      => 'your-merchant-uid',
    'apikeypublic'     => 'your-api-secret-key',
    'apiclientpublic'  => 'your-api-client-key',
    'tokenStorage'     => new EncryptedRedisTokenStorage(
        $redis,
        getenv('HALKODE_TOKEN_KEY')
    ),
]);

When to use which:

TokenStorageInterface

Any class implementing TokenStorageInterface can be passed to the client:

interface TokenStorageInterface
{
    public function get(string $key): ?string;
    public function set(string $key, string $value, int $ttl): bool;
}

Error Handling

Every service call returns a response object. No exceptions are thrown for API errors — errors are returned in the response:

$result = $services->paySmart2D($request);

if (!$result->success) {
    // Option 1: Localized message
    echo $result->message; // e.g., "Authentication error" (en) or "Kimlik doğrulama hatası" (tr)

    // Option 2: Detailed error
    if (is_array($result->error)) {
        foreach ($result->error as $field => $messages) {
            echo "$field: " . implode(', ', $messages) . "\n";
        }
    } else {
        echo $result->error;
    }
}

Status Codes

Testing

Run the test suite:

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

The test suite includes 108 tests with 218 assertions covering:

Project Structure

mskayali/halkode/
├── composer.json              # Package definition & PSR-4 autoload
├── phpunit.xml                # PHPUnit configuration
├── README.md
├── examples/
│   ├── all_services.php       # Working examples for all 12 endpoints
│   ├── redis_token_storage.php # Custom Redis token storage
│   └── yii2_integration.php   # Yii2 component & controller patterns
├── src/
│   ├── Client.php             # HTTP client, encryption, token management
│   ├── TokenStorageInterface.php
│   ├── MemoryTokenStorage.php
│   ├── models/
│   │   ├── BaseResponse.php
│   │   ├── StatusCodes.php
│   │   ├── TransactionType.php
│   │   ├── Invoice.php
│   │   ├── InvoiceItem.php
│   │   ├── GetTokenRequest.php / GetTokenBody.php
│   │   ├── PurchaseLinkRequest.php / PurchaseLinkBody.php
│   │   ├── PaySmart2DRequest.php / PaySmart2DBody.php / PaySmart2DData.php
│   │   ├── PaySmart3DRequest.php / PaySmart3DBody.php
│   │   ├── RefundAPIRequest.php / RefundAPIBody.php
│   │   ├── CheckstatusRequest.php / CheckstatusBody.php
│   │   ├── ConfirmPaymentRequest.php / ConfirmPaymentBody.php
│   │   ├── GetInstallmentRequest.php / GetInstallmentBody.php
│   │   ├── MerchantCommissionsRequest.php / MerchantCommissionsBody.php
│   │   ├── GetPosRequest.php / GetPosBody.php / GetPosData.php
│   │   ├── GetTransactionRequest.php / GetTransactionBody.php
│   │   ├── AllTransactionRequest.php / AllTransactionBody.php
│   │   └── PaymentCompleteRequest.php / PaymentCompleteBody.php
│   └── services/
│       └── PaymentServices.php # All 12 API endpoint methods
└── tests/
    ├── bootstrap.php
    ├── AutoloadTest.php
    ├── MemoryTokenStorageTest.php
    ├── ClientTest.php
    ├── BaseResponseTest.php
    ├── ModelTest.php
    └── PaymentServicesTest.php

License

MIT