Payment Routes Documentation

This document outlines the available payment routes. The payment routes include pricing, coupon validation, and payment gateways such as Esewa and Khalti.

Base URL

Bas path /api2/payment

Authorization

Requires Cookie: JSESSIONID=session_id

Pricing

Pricing Detail

Description:

Retrieve pricing information based on the specified duration and duration type.

🛠 Endpoint:

 POST `/pricing`

Request Body

Field	Type	Description	Required
`duration`	Number	Duration value	Yes
`duration_type`	String	Unit of duration (years/days/weeks/months)	Yes

curl -X POST "https://api.trackongps.com/api2/payment/pricing" \
  -H "Content-Type: application/json" \
  -H "Cookie: JSESSIONID=your_session_id" \
  -d '{
    "duration": 1,
    "duration_type": "years"
  }'

Sample Request Body:

{
  "duration": 1,
  "duration_type": "years"
}

Success Response

Field	Type	Description
`message`	String	Success message
`success`	Boolean	Indicates if the request was successful
`document`	Object	The first matching pricing document

200 OK - Example Response

{
  "message": "Pricing retrieved successfully.",
  "success": true,
  "document": {
    "feature": "Basic Plan",
    "isActive": true,
    "VAT": 0,
    "bonus_days": 5,
    "duration": 1,
    "duration_unit": "years",
    "duration_price": 10000,
    "price_unit": "NPR",
    "discount_type": null,
    "discount": null
  }
}

404 Not Found

{
  "message": "No pricing found",
  "success": false
}

400 Bad Request

{
  "message": "Invalid input provided.",
  "success": false
}

Available Pricing

Description: Retrieve a list of all active pricing options available in the system.

🛠 Endpoint:

 GET `/pricing/available`

Example Request:

curl -X GET "https://api.trackongps.com/api2/payment/pricing/available" \
  -H "Cookie: JSESSIONID=your_session_id"

Success Response

Field	Type	Description
`message`	String	Success message
`success`	Boolean	Indicates if the request was successful
`data`	Array	List of active pricing documents

200 OK - Example Response

{
  "message": "Available pricing options retrieved successfully.",
  "success": true,
  "data": [
    {
      "feature": "Basic Plan",
      "isActive": true,
      "VAT": 0,
      "bonus_days": 5,
      "duration": 1,
      "duration_unit": "years",
      "duration_price": 10000,
      "price_unit": "NPR",
      "discount_type": null,
      "discount": null
    },
    {
      "feature": "Premium Plan",
      "isActive": true,
      "VAT": 0,
      "bonus_days": 10,
      "duration": 2,
      "duration_unit": "years",
      "duration_price": 18000,
      "price_unit": "NPR",
      "discount_type": null,
      "discount": null
    }
  ]
}

404 Not Found

{
  "message": "No active pricing options found.",
  "success": false,
  "data": []
}

500 Server Error

{
  "message": "Database connection error.",
  "success": false
}

Coupon

Validate

Description: Validates a coupon code and returns the associated discount information if the code is valid and not expired or overused.

POST /coupon/validate

Request Body

Field	Type	Description	Required
`code`	String	The coupon code to validate	Yes

curl -X POST "https://api.trackongps.com/api2/payment/coupon/validate" \
  -H "Content-Type: application/json" \
  -H "Cookie: JSESSIONID=your_session_id" \
  -d '{
    "code": "SUMMER2024"
  }'

Sample Request

{
  "code": "SUMMER2024"
}

Sample Responses

200 OK - Example Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "discount": 20,
  "discount_type": "percentage",
  "expirationTime": "2024-12-31T19:15:00.000Z"
}

Esewa

Init Payment

Description:
Initiates an Esewa payment for a specific device and duration.

🛠 Endpoint:

POST /esewa/pay

Request Body

Field	Type	Description	Required
`finalUrl`	String	The URL to redirect upon success	Yes
`client`	String	The client's website URL	Yes
`deviceId`	String	Device ID to be paid for	Yes
`duration`	Number	Number of duration to pay for	Yes
`coupon`	String	Token received upon coupon validation	No
`duration_type`	String	Type of duration (i.e., months, years, days, weeks)	Yes

Example Request:

curl -X POST "https://api.trackongps.com/api2/payment/esewa/pay" \
  -H "Content-Type: application/json" \
  -H "Cookie: JSESSIONID=your_session_id" \
  -d '{
    "finalUrl": "https://example.com/success",
    "client": "https://example.com",
    "deviceId": "123456",
    "duration": 1,
    "duration_type": "years",
    "coupon": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Sample Request Body:

{
  "finalUrl": "https://example.com/success",
  "client": "https://example.com",
  "deviceId": "123456",
  "duration": 1,
  "duration_type": "years",
  "coupon": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Success Response

Field	Type	Description
`amount`	Number	Total amount in NPR
`failure_url`	String	URL to redirect upon payment failure
`product_delivery_charge`	String	Delivery charge for the product
`product_service_charge`	String	Service charge for the product
`product_code`	String	Product code for Esewa payment
`signature`	String	Digital signature for the payment
`signed_field_names`	String	Signed fields for the payment
`success_url`	String	URL to redirect upon payment success
`tax_amount`	String	Tax amount for the product
`total_amount`	Number	Total amount including tax and charges
`transaction_uuid`	String	Unique transaction ID for the payment

200 OK - Example Response

{
  "amount": 10000,
  "failure_url": "https://example.com/failure",
  "product_delivery_charge": "0",
  "product_service_charge": "0",
  "product_code": "12345",
  "signature": "12345",
  "signed_field_names": "all",
  "success_url": "https://example.com/success",
  "tax_amount": "0",
  "total_amount": 10000,
  "transaction_uuid": "12345"
}

400 Bad Request

{
  "message": "Invalid credentials"
}

Redirect to Payment

POST https://epay.esewa.com.np/api/epay/main/v2/form

Description: After successful payment to redirect user to payment page, you must request use the response received from init process to request to esewa payment api.

Example Request:

curl -X POST "https://epay.esewa.com.np/api/epay/main/v2/form" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Cookie: JSESSIONID=your_session_id" \
  -d '{
    "amount": "2500",
    "failure_url": "https://web.trackongps.com/dashboard/subscription/verify",
    "product_delivery_charge": "0",
    "product_service_charge": "0",
    "product_code": "NP-ES-TRACKON",
    "signature": "m7bLHkJoZWUcl/HH3rGlzxC+me+xR6nZTUUN4RcdcMM=",
    "signed_field_names": "total_amount,transaction_uuid,product_code",
    "success_url": "https://web.trackongps.com/dashboard/subscription/verify",
    "tax_amount": "0",
    "total_amount": "2500",
    "transaction_uuid": "1742209655657-4daffbf0-a36c-4ad1-bf69-115a166d4334"
  }'

Sample Request Body:

{
  "amount": "2500",
  "failure_url": "https://web.trackongps.com/dashboard/subscription/verify",
  "product_delivery_charge": "0",
  "product_service_charge": "0",
  "product_code": "NP-ES-TRACKON",
  "signature": "m7bLHkJoZWUcl/HH3rGlzxC+me+xR6nZTUUN4RcdcMM=",
  "signed_field_names": "total_amount,transaction_uuid,product_code",
  "success_url": "https://web.trackongps.com/dashboard/subscription/verify",
  "tax_amount": "0",
  "total_amount": "2500",
  "transaction_uuid": "1742209655657-4daffbf0-a36c-4ad1-bf69-115a166d4334"
}

Note: The request Content-Type must be **aapplication/x-www-form-urlencoded**

Verify Payment

Description: Verifies the payment and updates the device's expiration.

🛠 Endpoint:

POST /esewa/verify

Request Body

Field	Type	Description	Required
`token`	String	Token received after payment	Yes

Success Response

Field	Type	Description
`UpdatedDevice`	Object	Updated device details
`paymentInfo`	Object	Payment details
`message`	String	Success or error message

200 OK - Example Response

{
  "UpdatedDevice": {
    "id": "123456",
    "name": "Device A",
    "expirationTime": "2025-12-31T00:00:00Z"
  },
  "paymentInfo": {
    "amount": 10000,
    "status": "Completed",
    "refId": "ref_12345"
  },
  "message": "Payment verified Successfully!"
}

400 Bad Request

{
  "message": "Sorry, you can't verify this transaction",
  "error": {
    "status": "Pending"
  }
}

Khalti

Init Payment

Description:
Initiates a Khalti payment for a specific device and duration.

🛠 Endpoint:

POST /khalti/pay

Request Body

Field	Type	Description	Required
`finalUrl`	String	The URL to redirect upon success	Yes
`client`	String	The client's website URL	Yes
`deviceId`	String	Device ID to be paid for	Yes
`duration`	Number	Number of duration to pay for	Yes
`coupon`	String	Token received upon coupon validation	No
`duration_type`	String	Type of duration (i.e., months, years, days, weeks)	Yes

Example Request:

curl -X POST "https://api.trackongps.com/api2/payment/khalti/pay" \
  -H "Content-Type: application/json" \
  -H "Cookie: JSESSIONID=your_session_id" \
  -d '{
    "finalUrl": "https://example.com/success",
    "client": "https://example.com",
    "deviceId": "123456",
    "duration": 2,
    "duration_type": "years"
  }'

Success Response

Field	Type	Description
`pidx`	String	Khalti payment identifier
`amount`	Number	Total amount in NPR
`message`	String	Success message for payment initialization

200 OK - Example Response

  {
  "pidx": "4aFpKexSnjMawLBUgao8BE",
  "payment_url": "https://pay.khalti.com/?pidx=4aFpKexSnjMawLBUgao8BE",
  "expires_at": "2025-03-17T17:56:15.861420+05:45",
  "expires_in": 3600
  }

400 Bad Request

{
  "message": "Error from Khalti API",
  "error": {
    "detail": "Invalid credentials"
  }
}

Redirect to Payment

GET https://pay.khalti.com/

Description: After successful payment initiation to redirect user to khalti payment pagem use these instructions.

Example Request:

curl -X GET "https://pay.khalti.com/?pidx=4aFpKexSnjMawLBUgao8BE" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Cookie: JSESSIONID=your_session_id" \

Query Parameters

Field	Type	Description	Required
`pidx`	String	pidx receieved in payment init success response	YES

Verify Payment

Description: Verifies the payment and updates the device's expiration.

🛠 Endpoint:

POST /khalti/verify

Request Body

Field	Type	Description	Required
`pidx`	String	Payment token received after payment	Yes

Success Response

Field	Type	Description
`UpdatedDevice`	Object	Updated device details
`paymentInfo`	Object	Payment details
`message`	String	Success or error message

200 OK - Example Response

{
  "UpdatedDevice": {
    "id": "123456",
    "name": "Device A",
    "expirationTime": "2025-12-31T00:00:00Z"
  },
  "paymentInfo": {
    "amount": 10000,
    "status": "Completed",
    "refId": "ref_12345"
  },
  "message": "Payment verified Successfully!"
}

400 Bad Request

{
  "message": "Sorry, you can't verify this transaction",
  "error": {
    "status": "Pending"
  }
}

Payment History

Get Payment List

🛠 Endpoint:

GET /history

Description:

Returns a paginated list of payment history for the authenticated user.

Query Parameters

Field	Type	Description	Required
`page`	Number	Page number (default: 1)	No
`limit`	Number	Items per page (default: 10)	No
`deviceId`	Number	Device id to filter	No
`method`	Enum	Payment method ( khalti, cash, esewa, bank, online)	No
`status`	Enum	Payment status ( pending, completed )	No

Example Request:

curl -X GET "https://api.trackongps.com/api2/payment/history?page=1&limit=10&method=esewa&status=completed" \
  -H "Cookie: JSESSIONID=your_session_id"

200 OK - Example Response

{
  "page": 1,
  "limit": 10,
  "total": 20,
  "documents": [
    {
      "transactionInfo": null,
      "deviceId": "685",
      "amount": 2500,
      "status": "Pending",
      "method": "esewa",
      "$id": "67ac75d6002b7f8435b5",
      "$createdAt": "2025-02-12T10:20:06.806+00:00"
    }
  ]
}

Get Payment Info

🛠 Endpoint:

GET /history/{paymentId}

Description:

Returns detailed information about a specific payment.

URL Parameters

Field	Type	Description	Required
`paymentId`	String	Unique payment ID	Yes

Example Request:

curl -X GET "https://api.trackongps.com/api2/payment/history/6773cc2f0006328cc592" \
  -H "Cookie: JSESSIONID=your_session_id"

200 OK - Example Response

{
  "tidx": "0RPVJ2O",
  "transactionInfo": {
    "product_code": "NP-ES-TRACKON",
    "status": "COMPLETE"
  },
  "deviceId": "5422",
  "status": "Completed",
  "method": "esewa",
  "$id": "6773cc2f0006328cc592"
}

404 Not Found

{
  "message": "Payment not found",
  "success": false
}