API Reference

Complete reference for the QPay V2 API. All endpoints use JSON request and response bodies. Authentication is via Bearer token, obtained through Basic Auth credentials.

Base URLs

Environment	URL
Production	`https://merchant.qpay.mn`
Sandbox	`https://merchant-sandbox.qpay.mn`

Use the sandbox URL for development and testing. All API behavior is identical between environments.

Authentication

All endpoints (except POST /v2/auth/token) require a Bearer token in the Authorization header:


Authorization: Bearer <access_token>

To obtain a token, send your merchant credentials via Basic Auth to the token endpoint. See Authentication for full details.

Content Type

All requests must include the Content-Type header:


Content-Type: application/json

Endpoints Overview

Authentication

Method	Endpoint	Description
`POST`	`/v2/auth/token`	Get access token
`POST`	`/v2/auth/refresh`	Refresh access token

Invoices

Method	Endpoint	Description
`POST`	`/v2/invoice`	Create invoice
`GET`	`/v2/invoice/{id}`	Get invoice
`DELETE`	`/v2/invoice/{id}`	Cancel invoice
`POST`	`/v2/invoice/list`	List invoices
`POST`	`/v2/invoice/check`	Check invoice payment status

Payments

Method	Endpoint	Description
`GET`	`/v2/payment/{id}`	Get payment details
`POST`	`/v2/payment/check`	Check payment status
`POST`	`/v2/payment/list`	List payments
`POST`	`/v2/payment/cancel/{id}`	Cancel payment
`POST`	`/v2/payment/refund/{id}`	Refund payment

Ebarimt

Method	Endpoint	Description
`POST`	`/v2/ebarimt_v3/create`	Create ebarimt
`DELETE`	`/v2/ebarimt_v3/{id}`	Cancel ebarimt

HTTP Status Codes

Status Code	Description
`200`	Success — request processed successfully
`400`	Bad Request — invalid parameters or malformed request body
`401`	Unauthorized — missing, invalid, or expired token
`403`	Forbidden — insufficient permissions for this operation
`404`	Not Found — the requested resource does not exist
`500`	Internal Server Error — an unexpected error occurred on the QPay server

Error Response Format

All error responses return a JSON body with the following structure:


{
  "error_code": "ERROR_CODE_STRING",
  "message": "Human-readable error description"
}

Field	Type	Description
`error_code`	string	Machine-readable error code for programmatic handling
`message`	string	Human-readable description of the error

See Error Codes for a complete list of error codes and their meanings.

Rate Limits

The QPay API applies rate limiting per merchant account. If you exceed the rate limit, you will receive a 429 Too Many Requests response. Implement exponential backoff in your retry logic.

Quick Start

Here is a minimal example of the complete payment flow using cURL:

1. Get Access Token


curl -X POST https://merchant.qpay.mn/v2/auth/token \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -H "Content-Type: application/json"

2. Create Invoice


curl -X POST https://merchant.qpay.mn/v2/invoice \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_code": "YOUR_INVOICE_CODE",
    "sender_invoice_no": "ORDER-001",
    "invoice_receiver_code": "terminal",
    "invoice_description": "Payment for Order #001",
    "amount": 50000,
    "callback_url": "https://yoursite.com/callback"
  }'

3. Check Payment Status


curl -X POST https://merchant.qpay.mn/v2/payment/check \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "object_type": "INVOICE",
    "object_id": "<invoice_id>"
  }'

For language-specific examples, see our SDK documentation.