PHPackages                             usukhbayar/qpay-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. usukhbayar/qpay-php

ActiveLibrary[Payment Processing](/categories/payments)

usukhbayar/qpay-php
===================

QPay V2 API PHP SDK with auto token management

v1.0.0(2mo ago)08MITPHPPHP ^8.1CI passing

Since Feb 26Pushed 2mo agoCompare

[ Source](https://github.com/qpay-sdk/qpay-php)[ Packagist](https://packagist.org/packages/usukhbayar/qpay-php)[ RSS](/packages/usukhbayar-qpay-php/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (2)Versions (2)Used By (0)

QPay PHP SDK
============

[](#qpay-php-sdk)

[![CI](https://github.com/qpay-sdk/qpay-php/actions/workflows/ci.yml/badge.svg)](https://github.com/qpay-sdk/qpay-php/actions/workflows/ci.yml)[![Packagist Version](https://camo.githubusercontent.com/6c1552b0d85fcdc7c006189a81dd80ff4379560890d1917509e7b0090df917d4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7573756b6862617961722f717061792d7068702e737667)](https://packagist.org/packages/usukhbayar/qpay-php)[![License: MIT](https://camo.githubusercontent.com/08cef40a9105b6526ca22088bc514fbfdbc9aac1ddbf8d4e6c750e3a88a44dca/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d626c75652e737667)](LICENSE)

PHP SDK for the QPay V2 payment gateway API. Provides a clean, type-safe interface with automatic token management, Guzzle-based HTTP, and comprehensive error handling.

Requirements
------------

[](#requirements)

- PHP 8.1+
- Guzzle HTTP 7.0+

Installation
------------

[](#installation)

```
composer require usukhbayar/qpay-php
```

Quick Start
-----------

[](#quick-start)

```
use QPay\Config;
use QPay\QPayClient;
use QPay\Models\CreateSimpleInvoiceRequest;
use QPay\Exceptions\QPayException;

// Configure from environment variables
$config = Config::fromEnv();
$client = new QPayClient($config);

// Or configure manually
$config = new Config(
    baseUrl: 'https://merchant.qpay.mn',
    username: 'YOUR_USERNAME',
    password: 'YOUR_PASSWORD',
    invoiceCode: 'YOUR_INVOICE_CODE',
    callbackUrl: 'https://yoursite.com/callback',
);
$client = new QPayClient($config);

// Create an invoice (token is obtained automatically)
try {
    $invoice = $client->createSimpleInvoice(new CreateSimpleInvoiceRequest(
        invoiceCode: $config->invoiceCode,
        senderInvoiceNo: 'ORDER-001',
        invoiceReceiverCode: 'terminal',
        invoiceDescription: 'Payment for Order #001',
        amount: 10000.0,
        callbackUrl: $config->callbackUrl,
    ));

    echo $invoice->invoiceId;   // Invoice ID
    echo $invoice->qPayShortUrl; // Payment link
    echo $invoice->qrImage;     // QR code image (base64)
} catch (QPayException $e) {
    echo "Error: {$e->errorCode} - {$e->errorMessage}";
}
```

Configuration
-------------

[](#configuration)

### Environment Variables

[](#environment-variables)

VariableDescription`QPAY_BASE_URL`QPay API base URL (e.g. `https://merchant.qpay.mn`)`QPAY_USERNAME`Merchant username`QPAY_PASSWORD`Merchant password`QPAY_INVOICE_CODE`Default invoice code`QPAY_CALLBACK_URL`Payment callback URL### Loading from Environment

[](#loading-from-environment)

```
// All 5 variables must be set, otherwise InvalidArgumentException is thrown
$config = Config::fromEnv();
```

### Manual Configuration

[](#manual-configuration)

```
$config = new Config(
    baseUrl: 'https://merchant.qpay.mn',
    username: 'YOUR_USERNAME',
    password: 'YOUR_PASSWORD',
    invoiceCode: 'YOUR_INVOICE_CODE',
    callbackUrl: 'https://yoursite.com/callback',
);
```

Token Management
----------------

[](#token-management)

The SDK handles authentication automatically. When you make any API call, the client will:

1. Obtain an access token if none exists
2. Reuse the token while it is valid
3. Refresh the token using the refresh token when expired
4. Re-authenticate with credentials if the refresh token is also expired

You can also manage tokens manually:

```
// Explicitly obtain a token
$token = $client->getToken();
echo $token->accessToken;
echo $token->refreshToken;
echo $token->expiresIn;

// Explicitly refresh the token
$refreshed = $client->refreshTokenRequest();
```

Usage
-----

[](#usage)

### Create Invoice (Full Options)

[](#create-invoice-full-options)

```
use QPay\Models\CreateInvoiceRequest;

$invoice = $client->createInvoice(new CreateInvoiceRequest(
    invoiceCode: 'YOUR_INVOICE_CODE',
    senderInvoiceNo: 'ORDER-001',
    invoiceReceiverCode: 'terminal',
    invoiceDescription: 'Payment for services',
    amount: 50000.0,
    callbackUrl: 'https://yoursite.com/callback',
    // Optional fields:
    senderBranchCode: 'BRANCH_01',
    allowPartial: true,
    minimumAmount: 10000.0,
    allowExceed: false,
    maximumAmount: 100000.0,
    note: 'Additional notes',
    lines: [
        [
            'line_description' => 'Product A',
            'line_quantity' => '2',
            'line_unit_price' => '25000',
        ],
    ],
));

echo $invoice->invoiceId;
echo $invoice->qrText;
echo $invoice->qrImage;
echo $invoice->qPayShortUrl;

foreach ($invoice->urls as $url) {
    echo "{$url['name']}: {$url['link']}";
}
```

### Create Simple Invoice

[](#create-simple-invoice)

```
use QPay\Models\CreateSimpleInvoiceRequest;

$invoice = $client->createSimpleInvoice(new CreateSimpleInvoiceRequest(
    invoiceCode: 'YOUR_INVOICE_CODE',
    senderInvoiceNo: 'ORDER-002',
    invoiceReceiverCode: 'terminal',
    invoiceDescription: 'Simple payment',
    amount: 5000.0,
    callbackUrl: 'https://yoursite.com/callback',
    senderBranchCode: 'BRANCH_01', // optional
));
```

### Create Invoice with Ebarimt (Tax)

[](#create-invoice-with-ebarimt-tax)

```
use QPay\Models\CreateEbarimtInvoiceRequest;

$invoice = $client->createEbarimtInvoice(new CreateEbarimtInvoiceRequest(
    invoiceCode: 'YOUR_INVOICE_CODE',
    senderInvoiceNo: 'ORDER-003',
    invoiceReceiverCode: 'terminal',
    invoiceDescription: 'Invoice with tax receipt',
    taxType: '1',
    districtCode: '01',
    callbackUrl: 'https://yoursite.com/callback',
    lines: [
        [
            'line_description' => 'Product B',
            'line_quantity' => '1',
            'line_unit_price' => '30000',
            'tax_product_code' => '1234',
        ],
    ],
));
```

### Cancel Invoice

[](#cancel-invoice)

```
$client->cancelInvoice('INVOICE_ID');
```

### Get Payment Details

[](#get-payment-details)

```
$payment = $client->getPayment('PAYMENT_ID');

echo $payment->paymentId;
echo $payment->paymentStatus;   // e.g. "PAID"
echo $payment->paymentAmount;
echo $payment->paymentCurrency; // e.g. "MNT"
echo $payment->paymentWallet;
echo $payment->transactionType;
echo $payment->paymentDate;
```

### Check Payment Status

[](#check-payment-status)

```
use QPay\Models\PaymentCheckRequest;

$result = $client->checkPayment(new PaymentCheckRequest(
    objectType: 'INVOICE',
    objectId: 'INVOICE_ID',
    pageNumber: 1,  // optional
    pageLimit: 10,   // optional
));

echo $result->count;
echo $result->paidAmount;

foreach ($result->rows as $row) {
    echo "{$row['payment_id']}: {$row['payment_status']} ({$row['payment_amount']})";
}
```

### List Payments

[](#list-payments)

```
use QPay\Models\PaymentListRequest;

$result = $client->listPayments(new PaymentListRequest(
    objectType: 'INVOICE',
    objectId: 'INVOICE_ID',
    startDate: '2026-01-01',
    endDate: '2026-01-31',
    pageNumber: 1,
    pageLimit: 20,
));

echo $result->count;

foreach ($result->rows as $row) {
    echo "{$row['payment_id']}: {$row['payment_amount']} {$row['payment_currency']}";
}
```

### Cancel Payment (Card Only)

[](#cancel-payment-card-only)

```
use QPay\Models\PaymentCancelRequest;

$client->cancelPayment('PAYMENT_ID', new PaymentCancelRequest(
    callbackUrl: 'https://yoursite.com/cancel-callback', // optional
    note: 'Reason for cancellation',                      // optional
));
```

### Refund Payment (Card Only)

[](#refund-payment-card-only)

```
use QPay\Models\PaymentRefundRequest;

$client->refundPayment('PAYMENT_ID', new PaymentRefundRequest(
    callbackUrl: 'https://yoursite.com/refund-callback', // optional
    note: 'Reason for refund',                            // optional
));
```

### Create Ebarimt (Tax Receipt)

[](#create-ebarimt-tax-receipt)

```
use QPay\Models\CreateEbarimtRequest;

$ebarimt = $client->createEbarimt(new CreateEbarimtRequest(
    paymentId: 'PAYMENT_ID',
    ebarimtReceiverType: 'citizen',
    ebarimtReceiver: 'AA12345678',    // optional
    districtCode: '01',                // optional
    classificationCode: '1234',        // optional
));

echo $ebarimt->id;
echo $ebarimt->barimtStatus;
echo $ebarimt->ebarimtQrData;
echo $ebarimt->ebarimtLottery;
echo $ebarimt->amount;
echo $ebarimt->vatAmount;
```

### Cancel Ebarimt

[](#cancel-ebarimt)

```
$ebarimt = $client->cancelEbarimt('PAYMENT_ID');

echo $ebarimt->barimtStatus;
```

Error Handling
--------------

[](#error-handling)

All API errors throw `QPay\Exceptions\QPayException`:

```
use QPay\Exceptions\QPayException;

try {
    $client->createSimpleInvoice($request);
} catch (QPayException $e) {
    echo $e->statusCode;    // HTTP status code (0 for network errors)
    echo $e->errorCode;     // QPay error code string
    echo $e->errorMessage;  // Human-readable error message
    echo $e->rawBody;       // Raw response body
    echo $e->getMessage();  // "qpay: ERROR_CODE - message (status 400)"
    echo $e->getCode();     // Same as statusCode
}
```

### Error Code Constants

[](#error-code-constants)

The `QPayException` class provides constants for all known QPay error codes:

```
use QPay\Exceptions\QPayException;

try {
    $client->cancelInvoice('inv_123');
} catch (QPayException $e) {
    match ($e->errorCode) {
        QPayException::INVOICE_NOTFOUND => handleNotFound(),
        QPayException::INVOICE_ALREADY_CANCELED => handleAlreadyCancelled(),
        QPayException::INVOICE_PAID => handleAlreadyPaid(),
        QPayException::AUTHENTICATION_FAILED => handleAuthError(),
        QPayException::PERMISSION_DENIED => handlePermissionDenied(),
        default => handleUnknownError($e),
    };
}
```

Available error code constants:

ConstantValue`AUTHENTICATION_FAILED`Authentication failed`PERMISSION_DENIED`Permission denied`NO_CREDENDIALS`Missing credentials`INVOICE_NOTFOUND`Invoice not found`INVOICE_PAID`Invoice already paid`INVOICE_ALREADY_CANCELED`Invoice already cancelled`INVOICE_CODE_INVALID`Invalid invoice code`INVOICE_LINE_REQUIRED`Invoice lines required`PAYMENT_NOTFOUND`Payment not found`PAYMENT_NOT_PAID`Payment not paid`PAYMENT_ALREADY_CANCELED`Payment already cancelled`INVALID_AMOUNT`Invalid amount`MIN_AMOUNT_ERR`Below minimum amount`MAX_AMOUNT_ERR`Exceeds maximum amount`MERCHANT_NOTFOUND`Merchant not found`MERCHANT_INACTIVE`Merchant inactive`EBARIMT_NOT_REGISTERED`Ebarimt not registered`EBARIMT_CANCEL_NOTSUPPERDED`Ebarimt cancel not supported`CUSTOMER_NOTFOUND`Customer not found`CUSTOMER_DUPLICATE`Duplicate customerSee the `QPayException` class for the full list of constants.

API Reference
-------------

[](#api-reference)

### QPayClient Methods

[](#qpayclient-methods)

MethodParametersReturnsDescription`getToken()`-`TokenResponse`Authenticate and get token pair`refreshTokenRequest()`-`TokenResponse`Refresh the access token`createInvoice()``CreateInvoiceRequest``InvoiceResponse`Create invoice with full options`createSimpleInvoice()``CreateSimpleInvoiceRequest``InvoiceResponse`Create invoice with minimal fields`createEbarimtInvoice()``CreateEbarimtInvoiceRequest``InvoiceResponse`Create invoice with tax info`cancelInvoice()``string $invoiceId``void`Cancel an invoice`getPayment()``string $paymentId``PaymentDetail`Get payment details`checkPayment()``PaymentCheckRequest``PaymentCheckResponse`Check payment status`listPayments()``PaymentListRequest``PaymentListResponse`List payments`cancelPayment()``string $paymentId, PaymentCancelRequest``void`Cancel a card payment`refundPayment()``string $paymentId, PaymentRefundRequest``void`Refund a card payment`createEbarimt()``CreateEbarimtRequest``EbarimtResponse`Create tax receipt`cancelEbarimt()``string $paymentId``EbarimtResponse`Cancel tax receipt### Custom HTTP Client

[](#custom-http-client)

You can inject a custom Guzzle client (useful for testing, proxies, or custom middleware):

```
use GuzzleHttp\Client as HttpClient;

$http = new HttpClient([
    'timeout' => 60,
    'proxy' => 'tcp://localhost:8080',
]);

$client = new QPayClient($config, $http);
```

Testing
-------

[](#testing)

```
composer install
composer test
```

License
-------

[](#license)

MIT License. See [LICENSE](LICENSE) for details.

###  Health Score

35

—

LowBetter than 80% of packages

Maintenance84

Actively maintained with recent releases

Popularity5

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

82d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/256abce1f8c60e471be886ba32e500133b26461307e59beb0ccd9c8f8682ef32?d=identicon)[usukhv](/maintainers/usukhv)

---

Tags

laravelmongoliapaymentpayment-gatewayphpqpayqpay-apisdk

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/usukhbayar-qpay-php/health.svg)

```
[![Health](https://phpackages.com/badges/usukhbayar-qpay-php/health.svg)](https://phpackages.com/packages/usukhbayar-qpay-php)
```

###  Alternatives

[chargebee/chargebee-php

ChargeBee API client implementation for PHP

768.0M9](/packages/chargebee-chargebee-php)[imdhemy/google-play-billing

Google Play Billing

491.3M5](/packages/imdhemy-google-play-billing)[bitpay/sdk

Complete version of the PHP library for the new cryptographically secure BitPay API

42337.5k4](/packages/bitpay-sdk)[buckaroo/sdk

Buckaroo payment SDK

12189.1k9](/packages/buckaroo-sdk)[contica/facturador-electronico-cr

Un facturador de código libre para integrar facturación electrónica en Costa Rica a un proyecto PHP

2128.8k](/packages/contica-facturador-electronico-cr)[karson/mpesa-php-sdk

172.2k](/packages/karson-mpesa-php-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)