tobelyan / omnipay-arca-epg

dev-master 2026-11-05 07:45 UTC

Requires

• omnipay/common: ^3

Requires (Dev)

• omnipay/tests: ^3

MIT

• Rafayel Tobelyan

• payment
• pay
• gateway
• merchant
• wallet
• purchase
• omnipay
• armenia
• epg
• Apple Pay
• google pay
• Acba
• arca
• ashib

Published on Packagist.org on 2026-11-05 07:45 UTC

README

ARCA EPG (Electronic Payment Gateway) driver for the Omnipay payment processing library.

Omnipay is a framework agnostic, multi-gateway payment processing library for PHP. This package implements ARCA EPG support for Omnipay, enabling integration with Armenian banks including ACBA, ASHIB, INECO, and all other arca.am partner banks. Supports card binding (tokenization) for recurring payments.

Features

• Card payments through the ARCA hosted payment page (one-phase and two-phase / pre-authorization)
• Apple Pay and Google Pay on the ARCA payment page, plus other payment methods via paymentWay (CARD, APPLE_PAY, GOOGLE_PAY, SAMSUNG_PAY, ...)
• Card binding (tokenization) for recurring and one-click payments
• Order status, deposit, reverse and refund
• 3-D Secure enrollment check

Supported Banks

All banks connected to the ARCA EPG network, including:

• ACBA Bank
• ASHIB Bank (Ardshinbank)
• INECO Bank
• Converse Bank
• and other arca.am partners

Installation

Install via Composer:

composer require tobelyan/omnipay-arca-epg

Or add to your composer.json:

{
    "require": {
        "tobelyan/omnipay-arca-epg": "^1.0"
    }
}

Endpoints

Environment	URL
Production	https://epg.arca.am/payment/rest/
Test	https://testepg.arca.am/payment/rest/

To use a different URL, set it on the gateway; it is used instead of both defaults:

$gateway->setParameter('baseUrl', 'https://example.com/payment/rest');

Basic Usage

1. Initialize the Gateway

use Omnipay\Omnipay;

$gateway = Omnipay::create('ArcaEpg');
$gateway->setUserName(env('ARCA_USERNAME'));
$gateway->setPassword(env('ARCA_PASSWORD'));
$gateway->setTestMode(true); // set false for production

2. Register an Order (Purchase)

$response = $gateway->purchase([
    'transactionId' => 'YOUR_ORDER_NUMBER',  // unique order number in your system
    'amount'        => '10.00',              // amount in AMD (e.g. 10.00 = 1000 minor units)
    'currency'      => '051',                // AMD = 051, USD = 840
    'returnUrl'     => 'https://yoursite.am/payment/callback',
    'description'   => 'Order #123',
    'language'      => 'hy',                 // hy / ru / en
])->send();

if ($response->isRedirect()) {
    $response->redirect(); // redirects customer to ARCA payment page
}

// Store $response->getTransactionReference() (orderId from ARCA) for later status checks
$arcaOrderId = $response->getTransactionReference();

3. Check Order Status After Callback

When the customer returns from the payment page, ARCA appends ?orderId=... to your returnUrl. Use that to check the result:

public function callback(Request $request)
{
    $gateway = Omnipay::create('ArcaEpg');
    $gateway->setUserName(env('ARCA_USERNAME'));
    $gateway->setPassword(env('ARCA_PASSWORD'));
    $gateway->setTestMode(true);

    $response = $gateway->getOrderStatusExtended([
        'transactionId' => $request->orderId,
        'language'      => 'hy',
    ])->send();

    if ($response->isSuccessful()) {
        // Payment completed — fulfill the order
    } else {
        // Payment failed or pending
        $error = $response->getMessage();
    }
}

All Available Methods

purchase(array $params) — Register order

Parameter	Required	Description
transactionId	yes	Your unique order number
amount	yes	Amount (e.g. 10.00)
returnUrl	yes	URL to redirect after payment
currency	no	ISO 4217 numeric code (default: AMD = 051)
description	no	Order description
language	no	hy, ru, or en
pageView	no	DESKTOP or MOBILE
clientId	no	Your client ID (required for card binding)
jsonParams	no	JSON string with additional parameters
sessionTimeoutSecs	no	Session timeout in seconds
paymentWay	no	Payment method: CARD, APPLE_PAY, GOOGLE_PAY, ... (see below)

Apple Pay and Google Pay on the ARCA payment page

When the bank enables Apple Pay / Google Pay for your merchant, the ARCA hosted payment page shows those buttons next to the card form, depending on the customer's device. ARCA holds the Apple and Google certificates, so no wallet integration is needed on your side. ARCA asks merchants to send the payment method when registering the order; for the hosted page that is CARD:

$response = $gateway->purchase([
    'transactionId' => 'ORDER_001',
    'amount'        => '10.00',
    'returnUrl'     => 'https://yoursite.am/payment/callback',
    'paymentWay'    => 'CARD',
])->send();

After payment, getOrderStatusExtended() responses expose the method actually used via $response->getPaymentWay() (when EPG returns it).

registerPreAuth(array $params) — Two-phase payment (pre-authorization)

Same parameters as purchase(). The amount is only reserved, not charged. Use deposit() to confirm.

deposit(array $params) — Confirm pre-authorized order

Parameter	Required	Description
transactionId	yes	ARCA orderId returned from registerPreAuth
amount	yes	Amount to charge (must not exceed pre-auth amount)

reverse(array $params) — Cancel / reverse an order

Parameter	Required	Description
transactionId	yes	ARCA orderId

refund(array $params) — Refund a completed payment

Parameter	Required	Description
transactionId	yes	ARCA orderId
amount	yes	Amount to refund

getOrderStatus(array $params) — Basic order status

Parameter	Required	Description
transactionId	yes	ARCA orderId
language	no	hy, ru, or en

getOrderStatusExtended(array $params) — Full order status with card details

Same parameters as getOrderStatus(). Returns additional fields like cardAuthInfo and bindingInfo.

verifyEnrollment(array $params) — Check 3DS enrollment

Parameter	Required	Description
pan	yes	Card number (PAN)

Card Binding (Tokenization)

Card binding lets you save a card reference (token) for future payments without re-entering card details.

Step 1 — Register order with binding enabled

$response = $gateway->purchase([
    'transactionId' => 'ORDER_001',
    'amount'        => '10.00',
    'returnUrl'     => 'https://yoursite.am/payment/callback',
    'clientId'      => (string) auth()->id(),  // required to associate the binding
])->send();

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

Step 2 — Retrieve binding info after payment

$response = $gateway->getOrderStatusExtended([
    'transactionId' => $arcaOrderId,
])->send();

if ($response->isSuccessful()) {
    $data = $response->getData();

    // Save these to your database
    $bindingId      = $data['bindingInfo']['bindingId'];
    $clientId       = $data['bindingInfo']['clientId'];
    $pan            = $data['cardAuthInfo']['pan'];            // masked card number
    $expiration     = $data['cardAuthInfo']['expiration'];
    $cardholderName = $data['cardAuthInfo']['cardholderName'];
}

Step 3 — Pay with a saved binding

$response = $gateway->makeBindingPayment([
    'transactionId' => 'ORDER_002',
    'amount'        => '25.00',
    'bindingId'     => $savedBindingId,
    'currency'      => '051',
    'language'      => 'hy',
])->send();

if ($response->isSuccessful()) {
    // Silent payment completed
} elseif ($response->isRedirect()) {
    // 3DS required — redirect customer
    $response->redirect();
}

makeBindingPayment(array $params) — Pay with saved card

Parameter	Required	Description
transactionId	yes	Your unique order number
amount	yes	Amount to charge
bindingId	yes	Saved binding ID
currency	no	ISO 4217 numeric code
clientId	no	Client ID
language	no	hy, ru, or en
description	no	Order description
jsonParams	no	Additional parameters as JSON
mdOrder	no	ARCA order ID (if pre-registered)

activateCardBinding(array $params) — Activate a binding

Parameter	Required	Description
bindingId	yes	Binding ID to activate

unBindCard(array $params) — Deactivate a binding

Parameter	Required	Description
bindingId	yes	Binding ID to deactivate
language	no	hy, ru, or en

$response = $gateway->unBindCard([
    'bindingId' => $savedBindingId,
])->send();

getBindings(array $params) — List all bindings for a client

Parameter	Required	Description
clientId	yes	Client ID whose bindings to retrieve
language	no	hy, ru, or en

$response = $gateway->getBindings([
    'clientId' => (string) auth()->id(),
])->send();

if ($response->isSuccessful()) {
    $bindings = $response->getData()['bindings'];
}

Response Methods

All responses share these methods:

Method	Returns	Description
isSuccessful()	bool	Payment completed with no error
isRedirect()	bool	Response contains a redirect URL
getRedirectUrl()	string	URL to redirect the customer to
getTransactionReference()	string	ARCA orderId
getOrderStatus()	int|null	Order status code (2 = deposited)
getCode()	string	Error code (0 = no error)
getMessage()	string	Error message
getOrderNumberReference()	string	Your original order number
getActionCodeDescription()	string	Human-readable action description
getData()	array	Full raw response array

Order Status Codes

Code	Meaning
0	Order registered, not paid
1	Pre-authorized amount reserved
2	Order fully authorized (deposited)
3	Authorization cancelled
4	Refund performed
5	Access Control Server initiated authorization
6	Authorization rejected

Test Mode

Enable test mode to use the test environment (https://testepg.arca.am/payment/rest/):

$gateway->setTestMode(true);

Support

For general Omnipay questions, post on Stack Overflow with the omnipay tag.

Report bugs or request features via the GitHub issue tracker.

Developed by

This package was developed and is maintained by turn.am.

License

MIT © Rafayel Tobelyan