Epoint.az Payment Gateway PHP SDK

Modern PHP SDK for integrating Epoint.az payment gateway into your application. Supports standard payments, card tokenization, split payments, preauth, Apple Pay, Google Pay, wallets, and invoices.

Features

✅ Standard Payment - Accept online card payments
✅ Card Registration - Save cards for future payments (PCI-compliant tokenization)
✅ Card Registration with Payment - Register card and process payment in one step
✅ Saved Card Payments - Charge saved cards without re-entering details
✅ Split Payments - Split payment between multiple merchants (with saved card & registration)
✅ Preauth - Hold funds before capture (authorization + completion)
✅ Refunds & Reversals - Full or partial refunds, transaction cancellation
✅ Apple Pay & Google Pay - Native token payments on your own page, or the hosted widget
✅ Wallets - Support for local e-wallets
✅ Payment Methods - Get active payment methods, wallets and installment banks for your own checkout
✅ Installment Payments - Pay with a chosen installment bank and month
✅ Invoices - Create and send payment invoices
✅ Signature Verification - Secure callback validation
✅ Type-safe - Full PHP 8.2+ type coverage with enums
✅ Fluent API - Clean, readable builder pattern

📚 Documentation

For detailed documentation, guides, and advanced usage examples, visit our GitHub Wiki.

Quick Links:

Official Epoint API Documentation:

📄 Epoint API Documentation (PDF)

Official Platform Plugins

Use the ready-made plugins below if you need to integrate Epoint into popular e-commerce platforms without writing a custom integration from scratch:

🛒 OpenCart 3.0.x Plugin
🧩 WooCommerce 9.x.x Plugin

Requirements

PHP 8.2 or higher
ext-json
ext-curl

Installation

composer require rafoabbas/epoint-php

Quick Start

1. Initialize Client

use Epoint\EpointClient;

$client = new EpointClient(
    publicKey: 'i000000001',      // Your merchant public key
    privateKey: 'your-private-key'  // Your merchant private key
);

Base URL and timeouts

All options are optional and default to production:

$client = new EpointClient(
    publicKey: 'i000000001',
    privateKey: 'your-private-key',
    baseUrl: 'https://epoint.az/api/1', // EpointClient::DEFAULT_BASE_URL; point it at a test environment if you have one
    timeout: 30,                       // total request timeout in seconds
    connectTimeout: 10,                // connection timeout in seconds
);

// A copy with a shorter budget, e.g. for Apple Pay's ~30 s onpaymentauthorized window
$applePayClient = $client->withTimeout(20);

2. Create Payment

use Epoint\Enums\Language;

$response = $client->payment()
    ->amount(100.50)
    ->orderId('ORDER-12345')
    ->description('Product purchase')
    ->language(Language::EN)
    ->successUrl('https://yoursite.com/payment/success')
    ->errorUrl('https://yoursite.com/payment/error')
    ->send();

if ($response->isSuccess()) {
    // Redirect user to payment page
    header('Location: ' . $response->getRedirectUrl());
}

3. Handle Callback

// In your callback handler (result_url)
$data = $_POST['data'];
$signature = $_POST['signature'];

try {
    $callbackData = $client->verifyCallback($data, $signature);

    if ($callbackData['status'] === 'success') {
        // Payment successful
        $orderId = $callbackData['order_id'];
        $transaction = $callbackData['transaction'];
        $amount = $callbackData['amount'];

        // Update your database
    }
} catch (\Epoint\Exceptions\SignatureVerificationException $e) {
    // Invalid signature - possible fraud
    http_response_code(400);
}

Usage Examples

Standard Payment

$response = $client->payment()
    ->amount(50.00)
    ->orderId('ORDER-001')
    ->description('Monthly subscription')
    ->installment(true) // Enable installment payment
    ->send();

Active Payment Methods

use Epoint\Enums\Language;
use Epoint\Enums\PaymentMethod;

$methods = $client->paymentMethods()
    ->language(Language::AZ) // Optional: installment card names language
    ->get();

$methods->getMethods();                         // ['card', 'installment', 'wallet', ...]
$methods->hasMethod(PaymentMethod::APPLE_PAY);  // true / false
$methods->getWallets();                         // [['id' => 8, 'key' => 'portmanat', 'name' => 'Portmanat'], ...]
$methods->getInstallmentMinAmount();            // 30.0 or null
$methods->getInstallmentBanks();                // [['id' => 2, 'name' => 'TamKart', 'bank' => 'ABB', 'image' => '...', 'months' => [3, 6, 12]], ...]

Installment Payment

$response = $client->installmentPayment()
    ->amount(120.00)
    ->orderId('ORDER-007')
    ->description('Order #007')
    ->installmentCardId(2) // banks[].id from paymentMethods()
    ->installmentMonth(6)  // one of banks[].months
    ->send();

header('Location: ' . $response->getRedirectUrl());

Check Payment Status

$status = $client->checkStatus()
    ->transaction('te001234567')
    ->get();

if ($status->getPaymentStatus() === \Epoint\Enums\PaymentStatus::SUCCESS) {
    echo 'Payment successful!';
}

Or by your own order ID — e.g. for widget (Apple Pay / Google Pay) payments, which return no transaction ID:

$status = $client->checkStatus()
    ->orderId('ORDER-001')
    ->get();

$status->getTransaction(); // Epoint transaction ID of the latest payment for this order

Check Card Registration Status

use Epoint\Enums\CardStatus;

$status = $client->checkCardStatus()
    ->cardId('ce001234567')
    ->get();

if ($status->getCardStatus() === CardStatus::ACTIVE) {
    echo 'Card is active!';
    echo 'Card: ' . $status->getCardMask();    // ****1234
    echo 'Expiry: ' . $status->getExpiredDate(); // 12/25
}

Card Registration

// Register card without payment
$response = $client->registerCard()
    ->description('Save card for future purchases')
    ->successUrl('https://yoursite.com/cards/success')
    ->errorUrl('https://yoursite.com/cards/error')
    ->send();

// Get card_id from callback and store in your database
$cardId = $response->getCardId();

Card Registration with Payment

// Register card and process payment simultaneously
$response = $client->registerCardWithPay()
    ->amount(100.50)
    ->orderId('ORDER-123')
    ->description('First purchase + save card')
    ->successUrl('https://yoursite.com/cards/success')
    ->errorUrl('https://yoursite.com/cards/error')
    ->send();

// Get both card_id and transaction from response
$cardId = $response->getCardId();
$transaction = $response->getTransaction();

Payment with Saved Card

$response = $client->savedCardPayment()
    ->cardId('saved-card-id-from-database')
    ->amount(25.00)
    ->orderId('ORDER-002')
    ->description('Subscription renewal')
    ->execute();

Refund

$response = $client->refund()
    ->cardId('card-id-for-refund')
    ->orderId('original-order-id')
    ->amount(50.00)
    ->description('Product return')
    ->send();

Reverse/Cancel Transaction

$response = $client->reverse()
    ->transaction('te001234567')
    ->amount(100.00) // Optional: partial reversal
    ->send();

Split Payment

// Split payment between two merchants
$response = $client->splitPayment()
    ->amount(100.00)
    ->orderId('ORDER-003')
    ->splitUser('i000000002') // Second merchant ID
    ->splitAmount(30.00)      // Amount for second merchant
    ->description('Marketplace order')
    ->send();

// Split payment with saved card
$response = $client->splitCardPayment()
    ->cardId('saved-card-id')
    ->amount(100.00)
    ->orderId('ORDER-003')
    ->splitUser('i000000002')
    ->splitAmount(30.00)
    ->execute();

// Split payment with card registration
$response = $client->splitCardRegistrationWithPay()
    ->amount(100.00)
    ->orderId('ORDER-003')
    ->splitUser('i000000002')
    ->splitAmount(30.00)
    ->description('First split payment + save card')
    ->send();

// Get both card_id and transaction from response
$cardId = $response->getCardId();
$transaction = $response->getTransaction();

Preauth (Hold Funds)

// Step 1: Create preauth request
$response = $client->preauth()
    ->amount(100.00)
    ->orderId('ORDER-004')
    ->description('Hotel reservation')
    ->send();

$transaction = $response->getTransaction();

// Step 2: Complete preauth to capture funds
$completeResponse = $client->preauth()
    ->complete($transaction, 85.00); // Capture partial or full amount

Apple Pay / Google Pay (token payment)

Show the official wallet button on your own page and charge the wallet token from your server. Full guide: Apple Pay & Google Pay.

// onvalidatemerchant
$session = $client->applePaySession()
    ->origin('https://shop.example.az')
    ->create();
// -> ApplePaySession.completeMerchantValidation($session->getSession())

// onpaymentauthorized: create the record, then charge the token
$tokenPayment = $client->tokenPayment()
    ->amount(25.50)
    ->orderId('ORDER-001-1')   // unique per attempt
    ->description('Order #ORDER-001')
    ->create();

$result = $client->applePay()  // or ->googlePay()->googleRawToken($rawToken)
    ->paymentId($tokenPayment->getPaymentId())
    ->applePaymentData($paymentData)
    ->billingContact($billingContact)
    ->pay();

// Declined charges come back as $result->isSuccess() === false, not as exceptions.
// Always confirm before marking the order paid:
$status = $client->checkStatus()->orderId('ORDER-001-1')->get();

Apple Pay / Google Pay (widget)

$widget = $client->widget()
    ->amount(75.00)
    ->orderId('ORDER-005')
    ->description('Digital wallet payment')
    ->create();

// Use widget URL in iframe or webview
echo '<iframe src="' . $widget->getWidgetUrl() . '"></iframe>';

Wallets

// Get available wallets
$wallets = $client->wallet()->list();

foreach ($wallets->getWallets() as $wallet) {
    echo $wallet['name'];
}

// Make wallet payment
$response = $client->wallet()->payment(
    walletId: 'wallet-id',
    amount: 50.00,
    orderId: 'ORDER-006'
);

Invoices

// Create invoice
$invoice = $client->invoice()->create([
    'sum' => 150.00,
    'display' => 1,
    'save_as_template' => 0,
    'name' => 'John Doe',
    'phone' => '+994501234567',
    'email' => 'john@example.com',
    'description' => 'Invoice for services',
    'period_from' => '2024-01-01',
    'period_to' => '2024-12-31',
]);

// Send invoice via SMS
$client->invoice()->sendSms($invoice['id'], '+994501234567');

// Send invoice via email
$client->invoice()->sendEmail($invoice['id'], 'john@example.com');

Heartbeat Check

$status = $client->heartbeat();

if ($status['status'] === 'ok') {
    echo 'Epoint API is operational';
}

API Reference

EpointClient Methods

Method	Description
`withTimeout(int $timeout, ?int $connectTimeout = null)`	Copy of the client with different timeouts
`payment()`	Create standard payment request
`paymentMethods()`	Get active payment methods, wallets and installment banks
`installmentPayment()`	Create installment payment with bank and month
`checkStatus()`	Check payment status
`checkCardStatus()`	Check card registration status
`registerCard()`	Register card without payment
`registerCardWithPay()`	Register card with payment in one step
`savedCardPayment()`	Payment with saved card
`refund()`	Refund payment
`reverse()`	Reverse/cancel transaction
`splitPayment()`	Split payment between merchants
`splitCardPayment()`	Split payment with saved card
`splitCardRegistrationWithPay()`	Register card with split payment
`preauth()`	Preauth (hold and capture)
`widget()`	Apple Pay / Google Pay widget
`tokenPayment()`	Create a token payment record for Apple Pay / Google Pay
`applePaySession()`	Apple Pay merchant session (`onvalidatemerchant`)
`applePay()`	Charge a token payment with an Apple Pay token
`googlePay()`	Charge a token payment with a Google Pay token
`wallet()`	Wallet operations
`invoice()`	Invoice management
`heartbeat()`	API health check
`verifyCallback()`	Verify callback signature

Working with Response Objects

All API methods return response objects with convenient getter methods and full data access:

$response = $client->payment()
    ->amount(100.00)
    ->orderId('ORDER-123')
    ->send();

// Use specific getter methods
$redirectUrl = $response->getRedirectUrl();
$transaction = $response->getTransaction();
$isSuccess = $response->isSuccess();

// Or get full response data as array
$fullData = $response->toArray();
print_r($fullData);

// Example output:
// [
//     'status' => 'success',
//     'redirect_url' => 'https://epoint.az/payment/...',
//     'transaction' => 'te001234567',
//     'message' => 'Payment initiated',
//     'trace_id' => 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
//     // ... all other response fields
// ]

Available methods on response objects:

// Common methods (available on most responses)
$response->isSuccess()          // Check if request was successful
$response->getStatus()          // Get status: 'success', 'error', 'new', etc.
$response->getMessage()         // Get response message
$response->getTraceId()         // Get trace ID for troubleshooting
$response->toArray()            // Get complete response data as array

// Payment-specific methods
$response->getRedirectUrl()     // Payment page URL (for payment requests)
$response->getTransaction()     // Transaction ID
$response->getAmount()          // Payment amount
$response->getOrderId()         // Your order ID

// Card-specific methods
$response->getCardId()          // Saved card ID (for card registration)
$response->getCardMask()        // Masked card number (e.g., "****1234")

// Widget-specific methods
$response->getWidgetUrl()       // Apple Pay / Google Pay widget URL

// Token payment methods
$response->getPaymentId()       // Epoint payment ID (tokenPayment) for applePay()/googlePay()
$response->getSession()         // Apple Pay merchant session (applePaySession)
$response->getResult()          // Raw processor result (applePay/googlePay)

// Status check methods
$response->getPaymentStatus()   // PaymentStatus enum (NEW, SUCCESS, ERROR)
$response->getCardStatus()      // CardStatus enum (NEW, ACTIVE, PENDING, REJECTED, EXPIRED, SESSION_EXPIRED)

Pro tip: Use ->toArray() for debugging or logging full API responses:

$response = $client->payment()->amount(50)->orderId('TEST-001')->send();

// Log full response for debugging
error_log(print_r($response->toArray(), true));

// Get trace_id for support requests
$traceId = $response->getTraceId();

Important: If you encounter any issues with a payment or API request, always include the trace_id when contacting Epoint support. This unique identifier helps them quickly locate and troubleshoot your specific transaction:

try {
    $response = $client->payment()->amount(100)->orderId('ORDER-123')->send();
} catch (\Exception $e) {
    // Always log trace_id when errors occur
    $traceId = $response->getTraceId() ?? 'N/A';
    error_log("Payment failed. Trace ID: {$traceId}. Error: " . $e->getMessage());

    // Include trace_id when reporting issues to Epoint support
}

### Enums

```php
use Epoint\Enums\CardStatus;
use Epoint\Enums\Currency;
use Epoint\Enums\Language;
use Epoint\Enums\PaymentMethod;
use Epoint\Enums\PaymentStatus;

Currency::AZN
Language::AZ | Language::EN | Language::RU
PaymentStatus::NEW | PaymentStatus::SUCCESS | PaymentStatus::ERROR
PaymentMethod::CARD | PaymentMethod::INSTALLMENT | PaymentMethod::WALLET | PaymentMethod::GOOGLE_PAY | PaymentMethod::APPLE_PAY | ...
CardStatus::NEW | CardStatus::ACTIVE | CardStatus::PENDING | CardStatus::REJECTED | CardStatus::EXPIRED | CardStatus::SESSION_EXPIRED

Testing

composer test

Code Quality

composer cs:fix    # Fix code style
composer cs:check  # Check code style
composer analyse   # Run static analysis

Security

All API requests are signed with SHA1 HMAC signatures
Callback responses are verified to prevent tampering
Never store raw card data - use tokenization
Use HTTPS in production
Keep your private key secure

Changelog

See CHANGELOG.md

License

MIT License. See LICENSE for details.

Credits

Rauf Abbaszade

Name		Name	Last commit message	Last commit date
.claude		.claude
examples		examples
src		src
tests		tests
wiki		wiki
.gitattributes		.gitattributes
.gitignore		.gitignore
.php-cs-fixer.php		.php-cs-fixer.php
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
composer.json		composer.json
phpstan.neon		phpstan.neon
phpunit.xml		phpunit.xml
release.sh		release.sh
wiki-publish.sh		wiki-publish.sh

Latest commit

History

Folders and files

Repository files navigation