README

AzeriCard gateway for Omnipay

This package provides AzeriCard e-commerce gateway integration with support for 3D Secure, refunds, and signature verification.

Built and maintained by Elnur Akhundov

Installation

Install via Composer:

composer require elnurxf/omnipay-azericard

Usage Examples

1. Purchase Request (3D Redirect Flow)

use Omnipay\Omnipay;

$gateway = Omnipay::create('AzeriCard');
$gateway->setTerminalId('YOUR_TERMINAL_ID');
$gateway->setPrivateKeyPath(storage_path('keys/private.pem')); // PEM file
$gateway->setTestMode(true); // or false for production

$response = $gateway->purchase([
    'amount'         => '20.00',
    'currency'       => 'AZN',
    'transactionId'  => '12345',
    'returnUrl'      => route('payment.callback'),
    'description'    => 'Order #12345',
    'email'          => 'customer@example.com',
    'name'           => 'John Doe',
])->send();

if ($response->isRedirect()) {
    $response->redirect(); // POST to AzeriCard
} else {
    echo "Error: " . $response->getMessage();
}

2. Authorization (Pre-Auth) Request

// Step 1: Create authorization request
$response = $gateway->authorize([
    'amount'         => '50.00',
    'currency'       => 'AZN',
    'transactionId'  => 'AUTH12345',
    'returnUrl'      => route('payment.auth.callback'),
    'description'    => 'Authorization for Order #12345',
    'email'          => 'customer@example.com',
    'name'           => 'John Doe',
])->send();

if ($response->isRedirect()) {
    $response->redirect(); // Redirect to AzeriCard for 3D Secure
} else {
    echo "Authorization Error: " . $response->getMessage();
}

Note: Authorization requests now support all standard parameters and properly handle 3D Secure redirects just like purchase requests.

3. Callback Handler (Complete Purchase/Authorization)

$gateway = Omnipay::create('AzeriCard');
$gateway->setPublicKeyPath(storage_path('keys/azericard-public.pem'));

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

if ($response->isSuccessful()) {
    $reference = $response->getTransactionReference(); // INT_REF
    $rrn = $response->getRRN(); // Retrieval Reference Number
    $amount = $response->getAmount();
    $action = $response->getAction(); // '0' for success
    
    // For purchase transactions
    if ($response->getTransactionType() === '1') {
        // Mark order as paid
        echo "Payment successful! Reference: {$reference}, RRN: {$rrn}";
    }
    
    // For authorization transactions  
    if ($response->getTransactionType() === '0') {
        // Authorization successful - funds are reserved
        echo "Authorization successful! Reference: {$reference}, RRN: {$rrn}";
        // Store these values for later capture
    }
} else {
    echo "Transaction failed: " . $response->getMessage();
}

4. Capture (Complete Sale) - Complete Pre-Authorized Transaction

// Step 2: Capture the authorized amount (must be done after successful authorization)
$response = $gateway->completeSale([
    'amount'        => '50.00', // Can be less than or equal to authorized amount
    'currency'      => 'AZN',
    'transactionId' => 'AUTH12345', // Original authorization transaction ID
    'rrn'           => '317276406077', // RRN from authorization callback
    'INT_REF'        => 'ABC123XYZ987', // INT_REF from authorization callback
])->send();

if ($response->isSuccessful()) {
    echo "Capture successful! Funds have been charged.";
    $captureReference = $response->getTransactionReference();
} else {
    echo "Capture failed: " . $response->getMessage();
}

5. Refund

$response = $gateway->refund([
    'amount'        => '10.00', // Refund amount (can be partial)
    'currency'      => 'AZN',
    'transactionId' => '12345', // Original transaction ID
    'rrn'           => '317276406077', // RRN from original transaction
    'INT_REF'        => 'ABC123XYZ987', // INT_REF from original transaction
])->send();

if ($response->isSuccessful()) {
    echo "Refund successful!";
    $refundReference = $response->getTransactionReference();
} else {
    echo "Refund failed: " . $response->getMessage();
}

6. Void (Cancel Authorization)

// Cancel/void an authorization before it's captured
$response = $gateway->void([
    'transactionId' => 'AUTH12345', // Original authorization transaction ID
    'rrn'           => '317276406077', // RRN from authorization
    'INT_REF'        => 'ABC123XYZ987', // INT_REF from authorization
])->send();

if ($response->isSuccessful()) {
    echo "Authorization voided successfully!";
} else {
    echo "Void failed: " . $response->getMessage();
}

7. Transaction Status Check

$response = $gateway->status([
    'transactionId' => '12345',
    'rrn'           => '317276406077',
    'INT_REF'        => 'ABC123XYZ987',
])->send();

if ($response->isSuccessful()) {
    $status = $response->getStatus();
    $amount = $response->getAmount();
    echo "Transaction Status: {$status}, Amount: {$amount}";
} else {
    echo "Status check failed: " . $response->getMessage();
}

8. Complete Payment Flow Example

// Step 1: Authorization
$authResponse = $gateway->authorize([
    'amount' => '100.00',
    'transactionId' => '12345',
    'returnUrl' => route('auth.callback'),
    // ... other parameters
])->send();

// Step 2: Handle authorization callback
$callbackResponse = $gateway->completePurchase()->send();
if ($callbackResponse->isSuccessful()) {
    $rrn = $callbackResponse->getRRN();
    $INT_REF = $callbackResponse->getTransactionReference();
    
    // Step 3a: Capture the full amount
    $captureResponse = $gateway->completeSale([
        'amount' => '100.00',
        'transactionId' => '12345',
        'rrn' => $rrn,
        'INT_REF' => $INT_REF,
    ])->send();
    
    // OR Step 3b: Void the authorization
    $voidResponse = $gateway->void([
        'transactionId' => '12345',
        'rrn' => $rrn,
        'INT_REF' => $INT_REF,
    ])->send();
}

Security

The gateway signs and verifies all transactions using RSA-SHA256. Make sure to:

Keep your private key secure and readable only by your application.
Use the public key provided by AzeriCard to verify callbacks.

Roadmap / TODO

Purchase (TRTYPE 1) - Direct payment with 3D Secure
Authorization/Pre-Auth (TRTYPE 0) - Reserve funds with 3D Secure
Sales completion/Capture (TRTYPE 21) - Capture pre-authorized funds
Refund (TRTYPE 22) - Full and partial refunds
Status check (TRTYPE 90) - Transaction status inquiry
Void authorization (TRTYPE 24) - Cancel pre-authorization
Verify P_SIGN signatures - RSA-SHA256 signature verification
Complete authorization workflow - Pre-auth → 3D Secure → Capture/Void
Tokenization support
Recurring payments
Multi-currency support enhancement

elnurxf / omnipay-azericard

Maintainers

Details