tobelyan/omnipay-arca-epg

ARCA EPG (Electronic Payment Gateway) driver for Omnipay. Supports ACBA, ASHIB, INECO and other arca.am partner banks with card binding support.

dev-master 2026-05-16 13:49 UTC

Requires

• omnipay/common: ^3

Requires (Dev)

• omnipay/tests: ^3

MIT

• Rafayel Tobelyan

• payment
• pay
• gateway
• merchant
• purchase
• omnipay
• armenia
• epg
• Acba
• arca
• ashib

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.

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/

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

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