Skip to content

API Reference

Jump to bottom
Rauf Abbas edited this page Oct 22, 2026 · 7 revisions

API Reference

Complete reference for all SDK methods.

EpointClient

Constructor

new EpointClient(
    string $publicKey,
    string $privateKey,
    string $baseUrl = EpointClient::DEFAULT_BASE_URL, // https://epoint.az/api/1
    int $timeout = 30,
    int $connectTimeout = 10
)

Parameters:

  • publicKey - Your merchant public key (e.g., i000000001)
  • privateKey - Your merchant private key
  • baseUrl - API base URL including /api/1 (trailing slash is trimmed)
  • timeout - Total request timeout in seconds (at least 1)
  • connectTimeout - Connection timeout in seconds (at least 1)

Other client methods:

  • withTimeout(int $timeout, ?int $connectTimeout = null): static - returns a copy with different timeouts; the connection timeout defaults to the smaller of the current one and $timeout
  • getBaseUrl(), getTimeout(), getConnectTimeout()

Example:

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

Payment Methods

payment()

Create a standard payment request.

$client->payment()
    ->amount(float $amount)
    ->orderId(string $orderId)
    ->description(string $description = null)
    ->language(Language $language = Language::EN)
    ->currency(Currency $currency = Currency::AZN)
    ->installment(bool $installment = false)
    ->successUrl(string $url = null)
    ->errorUrl(string $url = null)
    ->send()

Returns: PaymentResponse

paymentMethods()

Get active payment methods, wallets and installment banks of the business. Use it before building your own checkout page.

$client->paymentMethods()
    ->language(Language $language = null) // Optional: az, en, ru
    ->get()

Returns: PaymentMethodsResponse

installmentPayment()

Create an installment payment with a specific bank and month (values from paymentMethods()).

$client->installmentPayment()
    ->amount(float $amount)
    ->orderId(string $orderId)
    ->installmentCardId(int $cardId)
    ->installmentMonth(int $month)
    ->description(string $description = null)
    ->language(Language $language = Language::AZ)
    ->currency(Currency $currency = Currency::AZN)
    ->successUrl(string $url = null)
    ->errorUrl(string $url = null)
    ->otherAttributes(array $attributes = null)
    ->send()

Returns: PaymentResponse

checkStatus()

Check payment status by transaction ID or by your order ID (one of them is required).

$client->checkStatus()
    ->transaction(string $transactionId)
    ->get()

$client->checkStatus()
    ->orderId(string $orderId)
    ->get()

Returns: StatusResponse

checkCardStatus()

Check card registration status by card ID.

$client->checkCardStatus()
    ->cardId(string $cardId)
    ->get()

Returns: CardStatusResponse

registerCard()

Register a card for future payments.

$client->registerCard()
    ->description(string $description = null)
    ->successUrl(string $url = null)
    ->errorUrl(string $url = null)
    ->send()

Returns: CardRegistrationResponse

registerCardWithPay()

Register a card and process payment in one step.

$client->registerCardWithPay()
    ->amount(float $amount)
    ->orderId(string $orderId)
    ->description(string $description = null)
    ->language(Language $language = Language::EN)
    ->currency(Currency $currency = Currency::AZN)
    ->forRefund(bool $forRefund = false)
    ->successUrl(string $url = null)
    ->errorUrl(string $url = null)
    ->send()

Returns: CardRegistrationWithPayResponse

savedCardPayment()

Charge a saved card.

$client->savedCardPayment()
    ->cardId(string $cardId)
    ->amount(float $amount)
    ->orderId(string $orderId)
    ->description(string $description = null)
    ->installment(bool $installment = false)
    ->execute()

Returns: PaymentResponse

refund()

Refund a payment.

$client->refund()
    ->cardId(string $cardId)
    ->orderId(string $orderId)
    ->amount(float $amount)
    ->description(string $description = null)
    ->send()

Returns: RefundResponse

reverse()

Reverse/cancel a transaction.

$client->reverse()
    ->transaction(string $transactionId)
    ->amount(float $amount = null)
    ->send()

Returns: RefundResponse

splitPayment()

Split payment between merchants.

$client->splitPayment()
    ->amount(float $amount)
    ->orderId(string $orderId)
    ->splitUser(string $merchantId)
    ->splitAmount(float $amount)
    ->description(string $description = null)
    ->language(Language $language = Language::AZ)
    ->currency(Currency $currency = Currency::AZN)
    ->successUrl(string $url = null)
    ->errorUrl(string $url = null)
    ->send()

Returns: PaymentResponse

splitCardPayment()

Execute split payment with saved card.

$client->splitCardPayment()
    ->cardId(string $cardId)
    ->amount(float $amount)
    ->orderId(string $orderId)
    ->splitUser(string $merchantId)
    ->splitAmount(float $amount)
    ->description(string $description = null)
    ->language(Language $language = Language::AZ)
    ->currency(Currency $currency = Currency::AZN)
    ->execute()

Returns: PaymentResponse

splitCardRegistrationWithPay()

Register card with split payment in one step.

$client->splitCardRegistrationWithPay()
    ->amount(float $amount)
    ->orderId(string $orderId)
    ->splitUser(string $merchantId)
    ->splitAmount(float $amount)
    ->description(string $description = null)
    ->language(Language $language = Language::AZ)
    ->currency(Currency $currency = Currency::AZN)
    ->successUrl(string $url = null)
    ->errorUrl(string $url = null)
    ->send()

Returns: CardRegistrationWithPayResponse

preauth()

Create preauth (hold funds).

// Create preauth
$client->preauth()
    ->amount(float $amount)
    ->orderId(string $orderId)
    ->description(string $description = null)
    ->language(Language $language = Language::AZ)
    ->currency(Currency $currency = Currency::AZN)
    ->otherAttributes(array $attributes = [])
    ->successUrl(string $url = null)
    ->errorUrl(string $url = null)
    ->send()

// Complete preauth
$client->preauth()
    ->complete(string $transactionId, float $amount)

Returns: PaymentResponse (for create), PreauthCompleteResponse (for complete)

Widget & Wallets

widget()

Create Apple Pay / Google Pay widget.

$client->widget()
    ->amount(float $amount)
    ->orderId(string $orderId)
    ->description(string $description = null)
    ->create()

Returns: WidgetResponse

tokenPayment()

Create the payment record a native Apple Pay / Google Pay token is charged against. See Apple Pay & Google Pay.

$client->tokenPayment()
    ->amount(float $amount)
    ->orderId(string $orderId)          // unique per attempt, max 250 chars
    ->description(string $description)
    ->currency(Currency $currency)      // default AZN
    ->language(Language $language)      // default AZ
    ->successUrl(string $url)
    ->errorUrl(string $url)
    ->otherAttributes(array $attributes)
    ->create()

Returns: TokenPaymentResponse

applePaySession()

Create an Apple Pay merchant session (onvalidatemerchant).

$client->applePaySession()
    ->origin(string $origin)            // e.g. https://shop.example.az
    ->create()

Returns: ApplePaySessionResponse

applePay() / googlePay()

Charge a token payment with a wallet token.

$client->applePay()                     // or googlePay()
    ->paymentId(int $paymentId)
    ->applePaymentData(array $paymentData)   // Apple Pay, or:
    ->googleRawToken(string $rawToken)       // Google Pay, or:
    ->token(string $base64Token)             // already encoded
    ->billingContact(array $billingContact)
    ->pay()

Returns: TokenPayResponse. Declined charges (HTTP 400 with JSON) are returned as unsuccessful responses, not exceptions.

wallet()

Wallet operations.

// List wallets
$client->wallet()->list()

// Make wallet payment
$client->wallet()->payment(
    string $walletId,
    float $amount,
    string $orderId
)

Invoice Methods

invoice()

Invoice management.

// Create invoice
$client->invoice()->create(array $data)

// Send via SMS
$client->invoice()->sendSms(int $invoiceId, string $phone)

// Send via email
$client->invoice()->sendEmail(int $invoiceId, string $email)

Utility Methods

verifyCallback()

Verify and decode callback data.

$client->verifyCallback(
    string $data,
    string $signature
): array

Throws: SignatureVerificationException if signature is invalid

Example:

$data = $_POST['data'];
$signature = $_POST['signature'];

try {
    $callbackData = $client->verifyCallback($data, $signature);
    // Process $callbackData
} catch (SignatureVerificationException $e) {
    // Invalid signature
}

heartbeat()

Check API health.

$client->heartbeat(): array

Returns:

[
    'status' => 'ok',
    // ... other info
]

Enums

Language

use Epoint\Enums\Language;

Language::AZ  // Azerbaijani
Language::EN  // English
Language::RU  // Russian

Currency

use Epoint\Enums\Currency;

Currency::AZN  // Azerbaijani Manat

PaymentStatus

use Epoint\Enums\PaymentStatus;

PaymentStatus::NEW      // Payment initiated
PaymentStatus::SUCCESS  // Payment successful
PaymentStatus::ERROR    // Payment failed

PaymentMethod

PaymentMethod::CARD           // 'card'
PaymentMethod::INSTALLMENT    // 'installment'
PaymentMethod::WALLET         // 'wallet'
PaymentMethod::GOOGLE_PAY     // 'google_pay'
PaymentMethod::APPLE_PAY      // 'apple_pay'
PaymentMethod::CLICK_TO_PAY   // 'click_to_pay'
PaymentMethod::AMEX           // 'amex'
PaymentMethod::PRE_AUTH       // 'pre_auth'
PaymentMethod::CARD_SAVE      // 'card_save'
PaymentMethod::PAYOUT         // 'payout'
PaymentMethod::REVERSE        // 'reverse'

CardStatus

use Epoint\Enums\CardStatus;

CardStatus::NEW              // Card registration initiated
CardStatus::ACTIVE           // Card is active
CardStatus::PENDING          // Registration pending
CardStatus::REJECTED         // Registration rejected
CardStatus::EXPIRED          // Card expired
CardStatus::SESSION_EXPIRED  // Registration session expired

Response Objects

All responses inherit from BaseResponse:

Common Methods

$response->isSuccess(): bool
$response->isError(): bool
$response->getStatus(): ?string
$response->getMessage(): ?string
$response->getTraceId(): ?string
$response->toArray(): array

PaymentResponse

$response->getRedirectUrl(): ?string
$response->getTransaction(): ?string
$response->getAmount(): ?float
$response->getOrderId(): ?string
$response->getBankResponse(): ?string
$response->getOperationCode(): ?string
$response->getOtherAttributes(): array

PaymentMethodsResponse

  • getBusinessId(): ?int
  • getBusinessName(): ?string
  • getMethods(): array - Active method keys
  • hasMethod(PaymentMethod|string $method): bool
  • getWallets(): array - Active wallets (id, key, name)
  • getInstallment(): ?array - null when installment is not available
  • getInstallmentMinAmount(): ?float
  • getInstallmentBanks(): array - Banks (id, name, bank, image, months)

StatusResponse

$response->getPaymentStatus(): PaymentStatus
$response->getTransaction(): ?string
$response->getAmount(): ?float
$response->getOrderId(): ?string
$response->getBankResponse(): ?string
$response->getOtherAttributes(): array

CardStatusResponse

$response->getCardStatus(): CardStatus
$response->getCardId(): ?string
$response->getCardName(): ?string
$response->getCardMask(): ?string
$response->getExpiredDate(): ?string
$response->getDescription(): ?string

CardRegistrationResponse

$response->getRedirectUrl(): ?string
$response->getCardId(): ?string
$response->getCardMask(): ?string
$response->getBankResponse(): ?string
$response->getOperationCode(): ?string
$response->getRrn(): ?string

CardRegistrationWithPayResponse

$response->getRedirectUrl(): ?string
$response->getCardId(): ?string
$response->getTransaction(): ?string
$response->getOrderId(): ?string
$response->getAmount(): ?float
$response->getCardMask(): ?string
$response->getCardName(): ?string
$response->getBankTransaction(): ?string
$response->getRrn(): ?string
$response->getBankResponse(): ?string
$response->getOperationCode(): ?string
$response->getOtherAttributes(): array

RefundResponse

$response->getTransaction(): ?string
$response->getOrderId(): ?string
$response->getAmount(): ?float
$response->getBankResponse(): ?string

PreauthCompleteResponse

$response->getTransaction(): ?string
$response->getAmount(): ?float
$response->getBankTransaction(): ?string
$response->getRrn(): ?string
$response->getCardMask(): ?string
$response->getCardName(): ?string
$response->getBankResponse(): ?string

WidgetResponse

$response->getWidgetUrl(): ?string

TokenPaymentResponse

$response->getPaymentId(): ?int
$response->getOrderId(): ?string
$response->getAmount(): ?float
$response->getPayment(): ?array

ApplePaySessionResponse

$response->getSession(): ?array

TokenPayResponse

$response->getOrderId(): ?string
$response->getPaymentId(): ?int
$response->getRedirectUrl(): ?string
$response->getResult(): ?array

Exceptions

EpointException

Thrown on validation, network and HTTP errors. For HTTP errors the status code and the decoded JSON body are available:

use Epoint\Exceptions\EpointException;

try {
    $client->tokenPayment()->amount(10)->orderId('ORDER-1')->create();
} catch (EpointException $e) {
    $e->getHttpCode();      // e.g. 400, or null
    $e->getResponseData();  // e.g. ['status' => 'error', 'message' => 'Duplicate order_id value'], or null
}

SignatureVerificationException

Thrown when callback signature verification fails.

use Epoint\Exceptions\SignatureVerificationException;

try {
    $client->verifyCallback($data, $signature);
} catch (SignatureVerificationException $e) {
    // Handle invalid signature
}

See Also

Getting Started

Payment Methods

Advanced Features

Integration

Reference

Clone this wiki locally