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:

Create an order and payment session
Redirect customer to Elavon's hosted payment page
Customer enters card details and completes 3DS authentication
Customer is redirected back to your site
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

Parameter	Description
`merchantAlias`	Your Elavon merchant alias
`apiKey`	Your API key for authentication
`region`	API region: 'eu' or 'na'
`testMode`	Set to `true` for sandbox environment

Request Parameters

Common Parameters

Parameter	Description
`amount`	Transaction amount (e.g., '10.00')
`currency`	Three-letter ISO currency code (e.g., 'USD')
`transactionId`	Your unique order/transaction ID
`transactionReference`	Gateway's transaction reference (href URL)
`returnUrl`	URL to redirect after successful payment
`cancelUrl`	URL to redirect if payment is cancelled

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.

academe / omnipay-elavon

Maintainers

Details