README

Akbank Virtual POS driver for the Omnipay PHP payment processing library

Omnipay is a framework agnostic, multi-gateway payment processing library for PHP. This package implements Akbank Virtual POS support for Omnipay.

Akbank uses a modern REST JSON API with HMAC-SHA512 request signing.

Installation

composer require tcgunel/omnipay-akbank

Requirements

• PHP >= 8.0
• ext-json

Usage

Gateway Initialization

use Omnipay\Omnipay;

$gateway = Omnipay::create('Akbank');

$gateway->setMerchantSafeId('your-merchant-safe-id');
$gateway->setTerminalSafeId('your-terminal-safe-id');
$gateway->setSecretKey('your-secret-key');
$gateway->setTestMode(true); // Use test endpoints

Non-3D Payment (Direct Sale)

$response = $gateway->purchase([
    'amount'        => '100.00',
    'currency'      => 'TRY',
    'transactionId' => 'ORDER-001',
    'clientIp'      => '127.0.0.1',
    'installment'   => 1,
    'secure'        => false,
    'card'          => [
        'firstName'   => 'John',
        'lastName'    => 'Doe',
        'number'      => '5218076007402834',
        'expiryMonth' => '12',
        'expiryYear'  => '2030',
        'cvv'         => '000',
    ],
])->send();

if ($response->isSuccessful()) {
    echo 'Payment successful! Auth Code: ' . $response->getTransactionReference();
} else {
    echo 'Payment failed: ' . $response->getMessage();
    echo ' Code: ' . $response->getCode();
}

3D Secure Payment

$response = $gateway->purchase([
    'amount'        => '100.00',
    'currency'      => 'TRY',
    'transactionId' => 'ORDER-001',
    'clientIp'      => '127.0.0.1',
    'installment'   => 1,
    'secure'        => true,
    'returnUrl'     => 'https://example.com/payment/success',
    'cancelUrl'     => 'https://example.com/payment/failure',
    'card'          => [
        'firstName'   => 'John',
        'lastName'    => 'Doe',
        'number'      => '5218076007402834',
        'expiryMonth' => '12',
        'expiryYear'  => '2030',
        'cvv'         => '000',
    ],
])->send();

if ($response->isRedirect()) {
    $response->redirect(); // Redirects to bank 3D page
}

Complete 3D Purchase (Callback Handler)

After the bank redirects back to your returnUrl, complete the purchase:

$response = $gateway->completePurchase([
    'transactionId' => $_POST['orderId'],
    'amount'        => '100.00',
    'currency'      => 'TRY',
    'clientIp'      => $_SERVER['REMOTE_ADDR'],
    'installment'   => 1,
    'responseCode'  => $_POST['responseCode'],
    'mdStatus'      => $_POST['mdStatus'],
    'secureId'      => $_POST['secureId'],
    'secureEcomInd' => $_POST['secureEcomInd'],
    'secureData'    => $_POST['secureData'],
    'secureMd'      => $_POST['secureMd'],
])->send();

if ($response->isSuccessful()) {
    echo 'Payment successful! Auth Code: ' . $response->getTransactionReference();
} else {
    echo 'Payment failed: ' . $response->getMessage();
}

Cancel (Void)

$response = $gateway->void([
    'transactionId' => 'ORDER-001',
    'clientIp'      => '127.0.0.1',
])->send();

if ($response->isSuccessful()) {
    echo 'Transaction cancelled successfully.';
} else {
    echo 'Cancel failed: ' . $response->getMessage();
}

Refund

$response = $gateway->refund([
    'transactionId' => 'ORDER-001',
    'amount'        => '50.00',
    'currency'      => 'TRY',
    'clientIp'      => '127.0.0.1',
])->send();

if ($response->isSuccessful()) {
    echo 'Refund successful.';
} else {
    echo 'Refund failed: ' . $response->getMessage();
}

API Details

Transaction Codes

Endpoints

Authentication

• Each API request includes HMAC-SHA512 hash of the JSON body as the auth-hash header
• 3D requests include HMAC-SHA512 hash of concatenated form fields
• All requests include a 128-character random hex number and ISO datetime

Currency Codes

Testing

composer test

License

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