PHP SDK

PHP client library for the QPay V2 API. Built on Guzzle HTTP with automatic token management, typed request/response objects using PHP 8.1+ named arguments, and comprehensive error handling.

Requirements: PHP 8.1+, Guzzle HTTP 7.0+

Installation


composer require usukhbayar/qpay-php

Configuration

Environment Variables

Variable	Description
`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


use QPay\Config;
 
$config = Config::fromEnv();

Manual Configuration


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

Custom Guzzle Client


use GuzzleHttp\Client as HttpClient;
use QPay\QPayClient;
 
$http = new HttpClient(['timeout' => 60, 'http_errors' => false]);
$client = new QPayClient($config, $http);

Quick Start


use QPay\Config;
use QPay\QPayClient;
use QPay\Models\CreateSimpleInvoiceRequest;
use QPay\Exceptions\QPayException;
 
$config = Config::fromEnv();
$client = new QPayClient($config);
 
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 . "\n";
    echo $invoice->qPayShortUrl . "\n";
    echo $invoice->qrImage . "\n";    // base64-encoded QR
} catch (QPayException $e) {
    echo "Error: {$e->errorCode} - {$e->errorMessage}\n";
}

Create Invoice

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',
));
 
echo "Invoice ID: {$invoice->invoiceId}\n";
echo "QR Text: {$invoice->qrText}\n";
echo "Short URL: {$invoice->qPayShortUrl}\n";
 
foreach ($invoice->urls as $url) {
    echo "  {$url['name']}: {$url['link']}\n";
}

Cancel Invoice


$client->cancelInvoice('invoice-id-here');

Check Payment


use QPay\Models\PaymentCheckRequest;
 
$result = $client->checkPayment(new PaymentCheckRequest(
    objectType: 'INVOICE',
    objectId: 'INVOICE_ID',
    pageNumber: 1,
    pageLimit: 10,
));
 
if ($result->count > 0) {
    echo "Payment received! Paid: {$result->paidAmount}\n";
    foreach ($result->rows as $row) {
        echo "  {$row['payment_id']}: {$row['payment_status']} ({$row['payment_amount']} {$row['payment_currency']})\n";
    }
} else {
    echo "No payment yet\n";
}

List Payments


use QPay\Models\PaymentListRequest;
 
$result = $client->listPayments(new PaymentListRequest(
    objectType: 'INVOICE',
    objectId: 'INVOICE_ID',
    startDate: '2024-01-01',
    endDate: '2024-12-31',
    pageNumber: 1,
    pageLimit: 20,
));
 
echo "Total: {$result->count}\n";
foreach ($result->rows as $row) {
    echo "  {$row['payment_id']}: {$row['payment_amount']} {$row['payment_currency']} ({$row['payment_status']})\n";
}

Get details for a single payment:


$detail = $client->getPayment('payment-id-here');
echo "Payment {$detail->paymentId}: {$detail->paymentStatus}\n";

Webhook Handling

QPay sends a POST request to your callbackUrl when a payment completes.

Laravel


use Illuminate\Http\Request;
use QPay\Config;
use QPay\QPayClient;
use QPay\Models\PaymentCheckRequest;
 
Route::post('/api/qpay/callback', function (Request $request) {
    $config = Config::fromEnv();
    $client = new QPayClient($config);
 
    $paymentId = $request->input('payment_id');
 
    $result = $client->checkPayment(new PaymentCheckRequest(
        objectType: 'INVOICE',
        objectId: $paymentId,
    ));
 
    if ($result->count > 0) {
        // Payment verified -- update your order status
        \Log::info("Payment confirmed: {$paymentId} ({$result->paidAmount} MNT)");
    }
 
    return response()->json(['status' => 'ok']);
});

Vanilla PHP


$body = json_decode(file_get_contents('php://input'), true);
$paymentId = $body['payment_id'] ?? null;
 
if ($paymentId) {
    $result = $client->checkPayment(new PaymentCheckRequest(
        objectType: 'INVOICE',
        objectId: $paymentId,
    ));
 
    if ($result->count > 0) {
        // Payment verified
    }
}
 
http_response_code(200);
echo json_encode(['status' => 'ok']);

Error Handling


use QPay\Exceptions\QPayException;
 
try {
    $client->createSimpleInvoice($request);
} catch (QPayException $e) {
    echo $e->statusCode;     // HTTP status code (e.g., 400)
    echo $e->errorCode;      // QPay error code (e.g., "INVOICE_CODE_INVALID")
    echo $e->errorMessage;   // Human-readable error message
    echo $e->rawBody;        // Raw response body
}

Error Code Constants


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(),
        QPayException::INVALID_AMOUNT => handleInvalidAmount(),
        default => handleUnknownError($e),
    };
}

API Reference

Method	Parameters	Returns	Description
`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, PaymentCancelRequest`	`void`	Cancel a card payment
`refundPayment()`	`string, PaymentRefundRequest`	`void`	Refund a card payment
`createEbarimt()`	`CreateEbarimtRequest`	`EbarimtResponse`	Create tax receipt
`cancelEbarimt()`	`string $paymentId`	`EbarimtResponse`	Cancel tax receipt