cURL Examples

A collection of ready-to-use cURL examples for the QPay V2 API. Each script demonstrates a specific API endpoint with proper authentication, request formatting, and documented response structures.

Prerequisites

curl — command-line HTTP client (pre-installed on macOS and most Linux distributions)
jq — JSON processor, used by the auth helper to parse tokens


# macOS
brew install jq
 
# Ubuntu / Debian
apt-get install jq

Installation


git clone https://github.com/qpay-sdk/qpay-curl.git
cd qpay-curl

Configuration

Copy the example environment file and fill in your credentials:


cp .env.example .env

Edit .env with your actual values:


QPAY_BASE_URL=https://merchant.qpay.mn
QPAY_USERNAME=your_username
QPAY_PASSWORD=your_password
QPAY_INVOICE_CODE=your_invoice_code
QPAY_CALLBACK_URL=https://your-domain.com/callback

Variable	Description
`QPAY_BASE_URL`	QPay API base URL
`QPAY_USERNAME`	QPay merchant username
`QPAY_PASSWORD`	QPay merchant password
`QPAY_INVOICE_CODE`	Default invoice code
`QPAY_CALLBACK_URL`	URL that QPay calls after payment

Make all scripts executable:


chmod +x helpers/*.sh examples/**/*.sh

Quick Start


# Authenticate and export tokens
source helpers/auth.sh
 
# Verify the token is set
echo "$ACCESS_TOKEN"
 
# Run any example
./examples/invoice/create-simple.sh

Get Token

The auth helper authenticates using Basic Auth and exports ACCESS_TOKEN and REFRESH_TOKEN as environment variables.


source helpers/auth.sh

Or manually with cURL:


curl -s -X POST "${QPAY_BASE_URL}/v2/auth/token" \
    -u "${QPAY_USERNAME}:${QPAY_PASSWORD}" | jq .

Response:


{
  "token_type": "Bearer",
  "refresh_expires_in": 3600,
  "refresh_token": "eyJ...",
  "access_token": "eyJ...",
  "expires_in": 600
}

Refresh Token


curl -s -X POST "${QPAY_BASE_URL}/v2/auth/refresh" \
    -H "Authorization: Bearer ${REFRESH_TOKEN}" | jq .

Create Invoice

Simple Invoice


source helpers/auth.sh
 
curl -s -X POST "${QPAY_BASE_URL}/v2/invoice" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
        "invoice_code": "'"${QPAY_INVOICE_CODE}"'",
        "sender_invoice_no": "ORDER-001",
        "invoice_receiver_code": "terminal",
        "invoice_description": "Payment for Order #001",
        "amount": 10000,
        "callback_url": "'"${QPAY_CALLBACK_URL}"'"
    }' | jq .

Response:


{
  "invoice_id": "abc123...",
  "qr_text": "...",
  "qr_image": "base64_encoded_qr_image...",
  "qPay_shortUrl": "https://qpay.mn/shorturl",
  "urls": [
    {
      "name": "Khan Bank",
      "description": "Khan Bank app",
      "logo": "https://...",
      "link": "https://..."
    }
  ]
}

Cancel Invoice


INVOICE_ID="your_invoice_id"
 
curl -s -X DELETE "${QPAY_BASE_URL}/v2/invoice/${INVOICE_ID}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq .

Check Payment


INVOICE_ID="your_invoice_id"
 
curl -s -X POST "${QPAY_BASE_URL}/v2/payment/check" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
        "object_type": "INVOICE",
        "object_id": "'"${INVOICE_ID}"'",
        "offset": {
            "page_number": 1,
            "page_limit": 10
        }
    }' | jq .

Response:


{
  "count": 1,
  "paid_amount": 1000.00,
  "rows": [
    {
      "payment_id": "...",
      "payment_status": "PAID",
      "payment_amount": "1000.00",
      "payment_currency": "MNT",
      "payment_wallet": "qpay"
    }
  ]
}

List Payments


INVOICE_ID="your_invoice_id"
 
curl -s -X POST "${QPAY_BASE_URL}/v2/payment/list" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
        "object_type": "INVOICE",
        "object_id": "'"${INVOICE_ID}"'",
        "start_date": "2024-01-01",
        "end_date": "2024-12-31",
        "offset": {
            "page_number": 1,
            "page_limit": 20
        }
    }' | jq .

Get Payment Details


PAYMENT_ID="your_payment_id"
 
curl -s -X GET "${QPAY_BASE_URL}/v2/payment/${PAYMENT_ID}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq .

Cancel Payment (Card Only)


PAYMENT_ID="your_payment_id"
 
curl -s -X DELETE "${QPAY_BASE_URL}/v2/payment/cancel/${PAYMENT_ID}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
        "callback_url": "'"${QPAY_CALLBACK_URL}"'",
        "note": "Customer requested cancellation"
    }' | jq .

Refund Payment (Card Only)


PAYMENT_ID="your_payment_id"
 
curl -s -X DELETE "${QPAY_BASE_URL}/v2/payment/refund/${PAYMENT_ID}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
        "callback_url": "'"${QPAY_CALLBACK_URL}"'",
        "note": "Refund requested"
    }' | jq .

Webhook Handling

QPay sends a POST request to your callback_url when a payment completes. You can verify callbacks by checking the payment status:


# In your callback handler, extract payment_id from the POST body, then verify:
curl -s -X POST "${QPAY_BASE_URL}/v2/payment/check" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
        "object_type": "INVOICE",
        "object_id": "'"${PAYMENT_ID}"'"
    }' | jq .

If count > 0, the payment is confirmed.

Create Ebarimt


PAYMENT_ID="your_payment_id"
 
curl -s -X POST "${QPAY_BASE_URL}/v2/ebarimt_v3/create" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
        "payment_id": "'"${PAYMENT_ID}"'",
        "ebarimt_receiver_type": "83",
        "district_code": "23"
    }' | jq .

Response:


{
  "id": "...",
  "ebarimt_receiver_type": "83",
  "amount": "1000.00",
  "vat_amount": "100.00",
  "ebarimt_qr_data": "...",
  "ebarimt_lottery": "...",
  "barimt_status": "CREATED"
}

Cancel Ebarimt


PAYMENT_ID="your_payment_id"
 
curl -s -X DELETE "${QPAY_BASE_URL}/v2/ebarimt_v3/${PAYMENT_ID}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq .

Error Handling

All QPay API errors return JSON with an error code and message:


{
  "error": "INVOICE_NOTFOUND",
  "message": "Invoice not found"
}

Common error codes:

Error Code	HTTP Status	Description
`AUTHENTICATION_FAILED`	401	Invalid credentials
`PERMISSION_DENIED`	403	No permission for this operation
`INVOICE_NOTFOUND`	404	Invoice does not exist
`INVOICE_PAID`	400	Invoice has already been paid
`INVOICE_ALREADY_CANCELED`	400	Invoice was already canceled
`INVOICE_CODE_INVALID`	400	Invalid invoice code
`INVALID_AMOUNT`	400	Amount is out of valid range
`PAYMENT_NOTFOUND`	404	Payment does not exist
`PAYMENT_ALREADY_CANCELED`	400	Payment was already canceled

Available Scripts

Script	Method	Path	Description
`helpers/auth.sh`	—	—	Auth helper (sources .env, exports tokens)
`examples/auth/get-token.sh`	POST	`/v2/auth/token`	Get access token
`examples/auth/refresh-token.sh`	POST	`/v2/auth/refresh`	Refresh access token
`examples/invoice/create-invoice.sh`	POST	`/v2/invoice`	Create invoice (full)
`examples/invoice/create-simple.sh`	POST	`/v2/invoice`	Create invoice (simple)
`examples/invoice/cancel-invoice.sh`	DELETE	`/v2/invoice/{id}`	Cancel invoice
`examples/payment/get-payment.sh`	GET	`/v2/payment/{id}`	Get payment details
`examples/payment/check-payment.sh`	POST	`/v2/payment/check`	Check payment status
`examples/payment/list-payments.sh`	POST	`/v2/payment/list`	List payments
`examples/payment/cancel-payment.sh`	DELETE	`/v2/payment/cancel/{id}`	Cancel payment
`examples/payment/refund-payment.sh`	DELETE	`/v2/payment/refund/{id}`	Refund payment
`examples/ebarimt/create-ebarimt.sh`	POST	`/v2/ebarimt_v3/create`	Create ebarimt
`examples/ebarimt/cancel-ebarimt.sh`	DELETE	`/v2/ebarimt_v3/{id}`	Cancel ebarimt

API Reference

Endpoint	Method	Description
`/v2/auth/token`	POST	Authenticate (Basic Auth) and get tokens
`/v2/auth/refresh`	POST	Refresh access token (Bearer refresh_token)
`/v2/invoice`	POST	Create an invoice
`/v2/invoice/{id}`	DELETE	Cancel an invoice
`/v2/payment/{id}`	GET	Get payment details
`/v2/payment/check`	POST	Check payment status
`/v2/payment/list`	POST	List payments
`/v2/payment/cancel/{id}`	DELETE	Cancel a card payment
`/v2/payment/refund/{id}`	DELETE	Refund a card payment
`/v2/ebarimt_v3/create`	POST	Create an ebarimt receipt
`/v2/ebarimt_v3/{id}`	DELETE	Cancel an ebarimt receipt

cURL Examples

Prerequisites

Installation

Configuration

Quick Start

Get Token

Refresh Token

Create Invoice

Simple Invoice

Cancel Invoice

Check Payment

List Payments

Get Payment Details

Cancel Payment (Card Only)

Refund Payment (Card Only)

Webhook Handling

Create Ebarimt

Cancel Ebarimt

Error Handling

Available Scripts

API Reference

Links