README

Elavon Payment Gateway (EPG) driver for the Omnipay PHP payment processing library

Omnipay is a framework-agnostic, multi-gateway payment processing library for PHP. This package implements Elavon Payment Gateway (EPG) support for Omnipay.

This driver uses Elavon's Hosted Payment Page (HPP) for secure card entry and 3DS authentication. All card details are entered on Elavon's hosted form, keeping your application out of PCI scope.

This package uses academe/elavon-epg-psr7 as the underlying API message driver and for DTOs.

Installation

composer require academe/omnipay-elavon

Requirements

• PHP 8.1 or higher
• Omnipay 3.x
• An Elavon EPG merchant account with API credentials

Basic Usage

Gateway Setup

use Omnipay\Omnipay;

$gateway = Omnipay::create('Elavon\Hpp');

$gateway->setMerchantAlias('your-merchant-alias');
$gateway->setApiKey('your-api-key');
$gateway->setRegion('eu'); // 'eu' or 'na'
$gateway->setTestMode(true); // Use sandbox environment

Hosted Payment Page Flow

The HPP gateway uses a redirect flow where the customer enters their card details on Elavon's secure hosted page:

1. Create an order and payment session
2. Redirect customer to Elavon's hosted payment page
3. Customer enters card details and completes 3DS authentication
4. Customer is redirected back to your site
5. Verify the transaction result

Authorize (Two-step flow)

An authorization reserves funds on the cardholder's account but does not capture them. Use capture() to complete the transaction later.

// Step 1: Create the authorization request
$response = $gateway->authorize([
    'amount' => '10.00',
    'currency' => 'USD',
    'transactionId' => 'order-123',
    'returnUrl' => 'https://example.com/payment/return',
    'cancelUrl' => 'https://example.com/payment/cancel',
])->send();

// Step 2: Redirect to Elavon's hosted payment page
if ($response->isRedirect()) {
    $response->redirect();
}

// Step 3: On return, verify the transaction
$response = $gateway->completeAuthorize([
    'transactionReference' => $_GET['transaction'],
])->send();

if ($response->isSuccessful()) {
    $transactionReference = $response->getTransactionReference();
    // Store this reference to capture later
}

Purchase (Single-step flow)

A purchase authorizes and captures payment in one step.

$response = $gateway->purchase([
    'amount' => '10.00',
    'currency' => 'USD',
    'transactionId' => 'order-124',
    'returnUrl' => 'https://example.com/payment/return',
    'cancelUrl' => 'https://example.com/payment/cancel',
])->send();

if ($response->isRedirect()) {
    $response->redirect();
}

// On return, the payment is already captured

Capture

Capture a previously authorized transaction.

$response = $gateway->capture([
    'transactionReference' => $transactionReference,
])->send();

if ($response->isSuccessful()) {
    echo 'Payment captured successfully!';
}

Refund

Refund a captured/settled transaction.

$response = $gateway->refund([
    'transactionReference' => $transactionReference,
    'amount' => '5.00', // Partial or full refund
    'currency' => 'USD',
])->send();

if ($response->isSuccessful()) {
    echo 'Refund processed successfully!';
}

Void

Void an authorized transaction before capture.

$response = $gateway->void([
    'transactionReference' => $transactionReference,
])->send();

if ($response->isSuccessful()) {
    echo 'Transaction voided successfully!';
}

Fetch Transaction

Retrieve details of a transaction.

$response = $gateway->fetchTransaction([
    'transactionReference' => $transactionReference,
])->send();

if ($response->isSuccessful()) {
    echo 'State: ' . $response->getState();
    echo 'Amount: ' . $response->getAmount();
}

Gateway Parameters

Request Parameters

Common Parameters

Response Methods

All responses provide these common methods:

$response->isSuccessful();           // Was the transaction successful?
$response->isRedirect();             // Does this require a redirect?
$response->getTransactionReference(); // Gateway's transaction reference
$response->getTransactionId();       // Your order ID
$response->getMessage();             // Response message
$response->getCode();                // Response code

Demo Scripts

The demo/ directory contains working examples demonstrating the HPP payment flow:

• hpp-form.php - Payment form with authorize/purchase option
• hpp-checkout.php - Creates order and redirects to HPP
• hpp-return.php - Handles return after payment
• hpp-capture.php - Captures authorized payments
• hpp-cancel.php - Handles cancelled payments
• transactions.php - View and manage transactions (void/refund)
• transaction-detail.php - View transaction details

Running the Demos

Start the web server:

php -S localhost:8000 -t demo

Then open: http://localhost:8000/

Configuration

Copy demo/config.php.example to demo/config.php and add your credentials:

return [
    'merchantAlias' => 'your-merchant-alias',
    'apiKey' => 'your-api-key',
    'region' => 'eu', // or 'na'
    'testMode' => true,
];

Testing

composer test

Support

If you are having general issues with Omnipay, we suggest posting on Stack Overflow. Be sure to add the omnipay tag.

If you believe you have found a bug, please report it using the GitHub issue tracker.

License

This package is released under the MIT License. See the LICENSE file for details.