VoucherMint | API Integration

API Integration

Integrate VoucherMint with your applications using our comprehensive API.

API Documentation

API Integration Guide

Welcome to the VoucherMint API integration guide. This documentation provides all the information you need to integrate VoucherMint's voucher management capabilities into your applications.

Authentication

All API requests to VoucherMint require authentication. You must include both your API key and API secret in the headers of each request.

Examples use placeholders like YOUR_API_KEY. Get live credentials from your VoucherMint Developer Dashboard.

Required Headers

X-API-Key: YOUR_API_KEY
X-API-Secret: YOUR_API_SECRET

Example Request

curl -X GET \
  https://vouchermint.xyz/api/vouchers/getAllVouchers/filter \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-API-Secret: YOUR_API_SECRET'

Authentication Errors

Status Code	Error	Description
401	Unauthorized	Missing or invalid API key or secret
403	Forbidden	Valid credentials but insufficient permissions

Security Best Practices

Never expose your API Secret in client-side code
Rotate your API keys periodically using the "Regenerate" button above
Implement proper error handling for authentication failures
Use HTTPS for all API requests

Account Endpoints

GET /api/tenant/balance

Get Tenant Balance

Returns the current balance for your tenant account.

Request Headers:

X-API-Key (required) - Your API key
X-API-Secret (required) - Your API secret

Example Request:

curl -X GET \
  https://vouchermint.xyz/api/tenant/balance \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-API-Secret: YOUR_API_SECRET'

Success Response (200 OK):

{
  "success": true,
  "data": {
    "balance": 5000,
    "currency": "INR"
  }
}

Error Responses:

401 Unauthorized - Invalid API credentials

Error Response Example:

{
  "success": false,
  "error": "Error message details"
}

Voucher Endpoints

GET /api/vouchers/getAllVouchers/filter

Get Filtered Vouchers

Returns a paginated list of vouchers based on filter criteria.

Request Headers:

X-API-Key (required) - Your API key
X-API-Secret (required) - Your API secret

Request Parameters:

name (string, optional) - Filter by voucher name (partial match)
category (string, optional) - Filter by category (can use comma-separated values)
country (string, optional) - Filter by country code (exact match)
deliveryType (string, optional) - Filter by delivery type (exact match)
page (number, optional) - Page number for pagination (default: 1)
limit (number, optional) - Results per page (default: 50, max: 100)

Example Request:

curl -X GET \
  https://vouchermint.xyz/api/vouchers/getAllVouchers/filter?name=Amazon \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-API-Secret: YOUR_API_SECRET'

Success Response (200 OK):

{
  "success": true,
  "data": [
    {
      "id": "12345",
      "name": "Amazon Gift Card",
      "description": "Amazon.com Gift Card",
      "valueType": "fixed_value",
      "valueDenominations": "10,25,50,100",
      "currencyCode": "USD",
      "countryCode": "US",
      "deliveryType": "realtime",
      "imageUrl": "https://example.com/amazon.jpg"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "totalItems": 150,
    "totalPages": 15
  }
}

Error Responses:

401 Unauthorized - Invalid API credentials
400 Bad Request - Invalid request parameters

Error Response Example:

{
  "success": false,
  "error": "Error message details"
}

GET /api/vouchers/getVoucherById/:id

Get Voucher Details

Returns detailed information about a specific voucher. The voucher ID should be provided in the URL path.

Request Headers:

X-API-Key (required) - Your API key
X-API-Secret (required) - Your API secret

Request Parameters:

id (string, required) - ID of the voucher to retrieve (path parameter)

Example Request:

curl -X GET \
  https://vouchermint.xyz/api/vouchers/getVoucherById/:id \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-API-Secret: YOUR_API_SECRET'

Success Response (200 OK):

{
  "success": true,
  "data": {
    "id": "12345",
    "name": "Amazon Gift Card",
    "description": "Amazon.com Gift Card",
    "valueType": "fixed_value",
    "valueDenominations": "10,25,50,100",
    "currencyCode": "USD",
    "countryCode": "US",
    "deliveryType": "realtime",
    "imageUrl": "https://example.com/amazon.jpg",
    "termsAndConditions": "Terms and conditions apply...",
    "redemptionInstructions": "To redeem, visit amazon.com/redeem..."
  }
}

Error Responses:

401 Unauthorized - Invalid API credentials
404 Not Found - Voucher not found

Error Response Example:

{
  "success": false,
  "error": "Error message details"
}

GET /api/vouchers/categories

Get Voucher Categories

Returns a list of all available voucher categories.

Request Headers:

X-API-Key (required) - Your API key
X-API-Secret (required) - Your API secret

Example Request:

curl -X GET \
  https://vouchermint.xyz/api/vouchers/categories \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-API-Secret: YOUR_API_SECRET'

Success Response (200 OK):

{
  "status": "success",
  "results": 15,
  "data": {
    "categories": [
      "Beauty_Health & Wellness",
      "Electronics",
      "Fashion"
    ],
    "displayCategories": [
      {
        "id": "beauty-health-wellness",
        "name": "Beauty_Health & Wellness",
        "displayName": "Beauty, Health & Wellness"
      }
    ],
    "categoryDisplayMap": {
      "Beauty_Health & Wellness": "Beauty, Health & Wellness"
    }
  }
}

Error Responses:

401 Unauthorized - Invalid API credentials

Error Response Example:

{
  "success": false,
  "error": "Error message details"
}

GET /api/vouchers/countries

Get Voucher Countries

Returns a list of all available countries where vouchers are offered.

Request Headers:

X-API-Key (required) - Your API key
X-API-Secret (required) - Your API secret

Example Request:

curl -X GET \
  https://vouchermint.xyz/api/vouchers/countries \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-API-Secret: YOUR_API_SECRET'

Success Response (200 OK):

{
  "status": "success",
  "results": 25,
  "data": {
    "countries": [
      {
        "id": "us",
        "name": "United States",
        "code": "US"
      },
      {
        "id": "sg",
        "name": "Singapore",
        "code": "SG"
      }
    ]
  }
}

Error Responses:

401 Unauthorized - Invalid API credentials

Error Response Example:

{
  "success": false,
  "error": "Error message details"
}

GET /api/vouchers/delivery-types

Get Voucher Delivery Types

Returns a list of all available voucher delivery types.

Request Headers:

X-API-Key (required) - Your API key
X-API-Secret (required) - Your API secret

Example Request:

curl -X GET \
  https://vouchermint.xyz/api/vouchers/delivery-types \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-API-Secret: YOUR_API_SECRET'

Success Response (200 OK):

{
  "status": "success",
  "results": 2,
  "data": {
    "deliveryTypes": [
      "delayed",
      "realtime"
    ],
    "displayDeliveryTypes": [
      {
        "id": "delayed",
        "name": "delayed",
        "displayName": "Delayed"
      },
      {
        "id": "realtime",
        "name": "realtime",
        "displayName": "Realtime"
      }
    ],
    "deliveryTypeMap": {
      "delayed": "Delayed",
      "realtime": "Realtime"
    }
  }
}

Error Responses:

401 Unauthorized - Invalid API credentials

Error Response Example:

{
  "success": false,
  "error": "Error message details"
}

Exchange Rate Endpoints

GET /api/exchange-rates

Get Exchange Rates

Returns the latest currency exchange rates used for voucher pricing and conversions.

Request Headers:

X-API-Key (required) - Your API key
X-API-Secret (required) - Your API secret

Example Request:

curl -X GET \
  https://vouchermint.xyz/api/exchange-rates \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-API-Secret: YOUR_API_SECRET'

Success Response (200 OK):

{
  "success": true,
  "data": {
    "base": "INR",
    "rates": {
      "USD": 0.012,
      "INR": 1,
      "EUR": 0.011
    },
    "lastUpdated": "2025-11-24T14:23:37.386Z",
    "nextUpdate": "2025-11-24T15:23:37.386Z",
    "cached": true,
    "remainingRequests": 1480
  }
}

Error Responses:

401 Unauthorized - Invalid API credentials
500 Internal Server Error - Failed to fetch exchange rates

Error Response Example:

{
  "success": false,
  "error": "Error message details"
}

GET /api/exchange-rates/convert

Convert Currency

Converts an amount from one currency to another using the latest available exchange rates.

Request Headers:

X-API-Key (required) - Your API key
X-API-Secret (required) - Your API secret

Request Parameters:

amount (number, required) - Amount to convert
from (string, required) - Source currency code (e.g., USD)
to (string, required) - Target currency code (e.g., INR)

Example Request:

curl -X GET \
  https://vouchermint.xyz/api/exchange-rates/convert?amount=100&from=USD&to=INR \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-API-Secret: YOUR_API_SECRET'

Success Response (200 OK):

{
  "success": true,
  "data": {
    "amount": 100,
    "from": "USD",
    "to": "INR",
    "convertedAmount": 8300,
    "rate": 83
  }
}

Error Responses:

400 Bad Request - Invalid or missing amount
400 Bad Request - Both from and to currency codes are required
401 Unauthorized - Invalid API credentials
500 Internal Server Error - Currency conversion failed

Error Response Example:

{
  "success": false,
  "error": "Error message details"
}

Order Endpoints

POST /api/orders/place

Place a New Order

Creates a new voucher order. Request must be sent as JSON (Content-Type: application/json).

Request Headers:

X-API-Key (required) - Your API key
X-API-Secret (required) - Your API secret
Content-Type - application/json

Request Body:

{
  "productId": 48730,
  "denomination": 5,
  "email": "[email protected]",
  "recipientPhone": "+91-9971616604"
}

Required Fields:

productId (integer) - The ID of the voucher product
denomination (number) - The voucher amount (must be a valid denomination for the product)

Optional Fields:

email (string) - Recipient email address. If provided, voucher details are emailed automatically.
recipientPhone (string) - Recipient phone number (required for some vouchers).
notifyReceiverEmail (boolean) - Set to false to disable email notification. Defaults to true when email is provided.

Important Notes:

Content-Type header must be set to application/json
Do NOT wrap string values in quotes while testing in postman (e.g., use [email protected] not "[email protected]")
Quantity is always 1 per request (technical limitation) - do not include quantity in request
If email is provided, a voucher notification email is sent automatically
To disable email notification, explicitly set notifyReceiverEmail to false
Certain brands require a phone number. Refer to the voucher field isPhoneNumberMandatory and pass the phone number in recipientPhone.

Example Request:

curl -X POST \
  https://vouchermint.xyz/api/orders/place \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-API-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "productId": 48730,
    "denomination": 5,
    "email": "[email protected]",
    "recipientPhone": "+91-9971616604"
  }'

Success Response (200 OK):

{
  "success": true,
  "message": "Order placed successfully",
  "order": {
    "poNumber": "PO-208172-TXDM",
    "productId": "48730",
    "quantity": 1,
    "denomination": 5,
    "orderTotal": 5,
    "status": "1",
    "tenantId": "685e489f68c0e19d5246138b",
    "voucherCode": "XOXOINTLTEST5635",
    "voucherType": "codePin",
    "voucherStatus": "issued",
    "voucherValue": 5,
    "voucherCurrency": "SGD",
    "baseCurrencyAmount": 351.99,
    "baseCurrency": "INR",
    "exchangeRate": 70.398,
    "voucherName": "FreshKon Cosmetic Contact Lenses",
    "orderId": 6562929,
    "displayOrderId": "ORD-6562929",
    "createdAt": "2025-11-24T14:23:37.386Z",
    "id": "69246a618b2269f68b8623dd"
  }
}

Error Responses:

401 Unauthorized - Invalid API credentials
402 Payment Required - Insufficient tenant balance
400 Bad Request - Invalid request parameters or insufficient provider balance
404 Not Found - Voucher not found
500 Internal Server Error - Server error during order processing

Error Response Example:

{
  "success": false,
  "error": "Error message details"
}

POST /api/orders/status

Check Order Status

Check the status of an order using poNumber or orderId.

Request Headers:

X-API-Key (required) - Your API key
X-API-Secret (required) - Your API secret
Content-Type - application/json

Request Body:

{
  "poNumber": "PO-123456-ABCD",
  "orderId": 1751009861681
}

Required Fields:

poNumber or orderId (any) - Either the purchase order number or the order ID

Example Request:

curl -X POST \
  https://vouchermint.xyz/api/orders/status \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-API-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "poNumber": "PO-123456-ABCD",
    "orderId": 1751009861681
  }'

Success Response (200 OK):

{
  "success": true,
  "message": "Order details retrieved",
  "order": {
    "poNumber": "PO-208172-TXDM",
    "productId": "48730",
    "quantity": 1,
    "denomination": 5,
    "orderTotal": 5,
    "status": "1",
    "voucherCode": "XOXOINTLTEST5635",
    "voucherType": "codePin",
    "voucherStatus": "issued",
    "voucherValue": 5,
    "voucherCurrency": "SGD",
    "baseCurrencyAmount": 351.99,
    "baseCurrency": "INR",
    "exchangeRate": 70.398,
    "voucherName": "FreshKon Cosmetic Contact Lenses",
    "voucherCountry": "Singapore",
    "orderId": 6562929,
    "displayOrderId": "ORD-6562929",
    "createdAt": "2025-11-24T14:23:37.386Z",
    "id": "69246a618b2269f68b8623dd"
  }
}

Error Responses:

401 Unauthorized - Invalid API credentials
400 Bad Request - Invalid request parameters
404 Not Found - Order not found

Error Response Example:

{
  "success": false,
  "error": "Error message details"
}