README

QNB Finansbank sanal pos gateway for the Omnipay PHP payment processing library

Omnipay is a framework agnostic, multi-gateway payment processing library for PHP. This package implements QNB Finansbank support for Omnipay.

Installation

composer require tcgunel/omnipay-qnbfinansbank

Available Methods

Supported Features

Usage

Gateway Initialization

use Omnipay\Omnipay;

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

$gateway->setMerchantId('your_merchant_id');
$gateway->setMerchantUser('your_user_code');
$gateway->setMerchantPassword('your_user_password');
$gateway->setMerchantStorekey('your_store_key'); // Required for 3D Secure
$gateway->setTestMode(true); // Use test endpoint

Non-3D Purchase (Direct Sale)

$response = $gateway->purchase([
    'amount'      => '100.00',
    'currency'    => 'TRY',
    'transactionId' => 'ORDER-12345',
    'secure'      => false,
    'card'        => [
        'number'      => '4508034508034509',
        'expiryMonth' => '12',
        'expiryYear'  => '2030',
        'cvv'         => '000',
    ],
])->send();

if ($response->isSuccessful()) {
    echo 'Transaction ID: ' . $response->getTransactionReference();
} else {
    echo 'Error: ' . $response->getMessage();
}

3D Secure Purchase

$response = $gateway->purchase([
    'amount'      => '100.00',
    'currency'    => 'TRY',
    'transactionId' => 'ORDER-12345',
    'secure'      => true,
    'returnUrl'   => 'https://yoursite.com/payment/success',
    'cancelUrl'   => 'https://yoursite.com/payment/fail',
    'card'        => [
        'number'      => '4508034508034509',
        'expiryMonth' => '12',
        'expiryYear'  => '2030',
        'cvv'         => '000',
    ],
])->send();

if ($response->isRedirect()) {
    $response->redirect(); // POSTs card data to the bank 3D Secure page
}

Complete 3D Secure Purchase (Callback Handler)

After the bank posts back to your returnUrl:

$response = $gateway->completePurchase([])->send();

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

The full callback POST payload is read directly from $_POST by the request. completePurchase() is successful only when ProcReturnCode is 00 and the QNB response hash verifies — see Response Hash Verification.

Void (Cancel)

$response = $gateway->void([
    'orderNumber' => 'ORDER-12345',
    'currency'    => 'TRY',
])->send();

if ($response->isSuccessful()) {
    echo 'Transaction voided.';
} else {
    echo 'Error: ' . $response->getMessage();
}

Refund

$response = $gateway->refund([
    'orderNumber' => 'ORDER-12345',
    'amount'      => '50.00',
    'currency'    => 'TRY',
])->send();

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

Order Inquiry (Payment Status)

Query the current bank-side status of an order — useful for reconciliation when a 3D callback is never received:

$response = $gateway->transactionQuery([
    'transactionId' => 'ORDER-12345',
    'currency'      => 'TRY',
])->send();

if ($response->isSuccessful()) {
    echo 'Order found at the bank.';
    echo $response->isVoided()   ? ' (voided)'   : '';
    echo $response->isRefunded() ? ' (refunded)' : '';
} else {
    echo 'Not found / failed: ' . $response->getMessage();
}

Hash Algorithm

Request hash (3D Secure)

SHA1Base64(MbrId + OrderId + PurchAmount + OkUrl + FailUrl + TxnType + InstallmentCount + Rnd + MerchantPass)

Response Hash Verification

After a 3D callback, the response hash is checked to confirm it genuinely came from QNB:

SHA1Base64(MerchantId + MerchantPass + OrderId + AuthCode + ProcReturnCode + 3DStatus + ResponseRnd + UserCode)

completePurchase()->isSuccessful() returns true only when ProcReturnCode is 00 and this hash matches. Verification is skipped (not failed) when no merchantStorekey is configured or the bank returns no ResponseHash, so a genuine payment is never rejected purely because the key is missing.

Note: MbrId is always 5 for QNB Finansbank. MerchantPass is the 3D Secure store key (merchantStorekey); it is only used for hashing and is never transmitted in a request.

Endpoints

Key Differences from Denizbank

• Uses MbrId: 5 field in all requests
• Uses ErrMsg instead of ErrorMessage for error messages
• Different endpoint URLs (vpos.qnb.com.tr vs inter-vpos.com.tr)

Running Tests

composer test

Static Analysis

composer analyse

Code Style

composer lint

License

MIT License. See LICENSE for details.