Introduction

Leading Digital Gift Card & Voucher API Platform

The easiest way for enterprises to order digital gift cards & vouchers.

ZPay provides a comprehensive suite of APIs that allow you to order digital gift cards, check wallet balances, browse products, and manage orders — all through a secure, authenticated REST API.

Quick Start

Jump right in — download our ready-to-use Postman collection to explore all endpoints, or browse the sections in the sidebar.

ZPay API — Postman Collection

Pre-configured with all endpoints, headers, and example payloads.

Products — List, Details
Orders — Create, Status, Details, List
Wallet — Account balance

Why Choose ZPay?

Secure API Key Authentication

All requests are authenticated using a unique API key tied to your company.

Wallet & Balance Management

Check your wallet balance and currency at any time using the wallet account endpoint.

Complete Order Lifecycle

Create orders, check status, and retrieve voucher codes — all through simple REST endpoints.

Authentication

How to authenticate your API requests

API Key Header

Every request must include your API key in the x-api-key header.

HEADER x-api-key: YOUR_API_KEY_HERE

How to get your API key

API keys are issued by ZPay Software Solution. Contact your account manager or support team to receive a unique key.

api_3f7b9d1c8e2a4f6b5d0c7e8a9b1f2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b

Replace the dummy key above with the one provided by ZPay.

Example Request

cURL

curl --location 'https://api.99gift.ae/super-admin/api/v1/api-user/wallet/account' \
--header 'x-api-key: api_3f7b9d1c8e2a4f6b5d0c7e8a9b1f2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b'

Important: This is a dummy key. Never share your real API key publicly.

Postman Collection

Import all ZPay endpoints into Postman with one click

What's Included

The official ZPay Postman Collection contains every endpoint documented here — pre-configured with headers, URLs, and example request bodies.

Products

Product List & Product Details endpoints with x-api-key header pre-set.

Orders

Create Order (with example JSON body), Order Details, Order Status, and Order List.

Wallet

Wallet Account endpoint for checking balance and currency.

Download the Collection

Click below to download the JSON file, then in Postman go to File → Import and select the file.

zpay-api-doc.postman_collection.json

Compatible with Postman v10+ and Insomnia (via import).

How to Import

Download the collection

Click the "Download JSON" button above to save the file to your computer.

Open Postman

Launch Postman and click File → Import (or press Ctrl/Cmd + O).

Select the file

Drag and drop the JSON file, or browse to select zpay-api-doc.postman_collection.json.

Start testing

Replace the dummy x-api-key values with your real key and send requests.

Wallet Account

Retrieve your wallet balance and currency

Endpoint

GET /wallet/account

Example Request

cURL

curl --location 'https://api.99gift.ae/super-admin/api/v1/api-user/wallet/account' \
--header 'x-api-key: api_3f7b9d1c8e2a4f6b5d0c7e8a9b1f2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b'

Response Example

JSON

{
  "success": true,
  "data": {
    "currency": "AED",
    "balance": 1185726.57
  }
}

List Products

Retrieve a paginated list of all available products.

Endpoint

GET /products/list

Query Parameters

search (optional)

Search products by name. Example: ?search=Noon

page / limit (optional)

Pagination controls. Default: page=1&limit=20

Example Request

cURL

curl --location 'https://api.99gift.ae/super-admin/api/v1/api-user/products/list' \
--header 'x-api-key: api_3f7b9d1c8e2a4f6b5d0c7e8a9b1f2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b'

Response Example

JSON

{
  "success": true,
  "data": {
    "products": [
      {
        "publicId": "24b61004-0eb2-4eb1-92a0-61a20290dbe4",
        "name": "Deira International School E Gift Card",
        "slug": "al-futtaim-deira-international-school-uae-e-gift-card",
        "description": "As a diversified organisation, we bring the quality...",
        "sku": "EGCGBALFUAE022",
        "status": "ACTIVE",
        "usageLocation": "OFFLINE",
        "tnc": "1.This card can be used across Al Futtaim brands...",
        "region": "AE",
        "redemptionInfo": "",
        "groupId": null,
        "logo": null,
        "currency": {
          "publicId": "38f2722f-ea5f-4b0a-b65a-b8fd9c855f2d",
          "code": "AED",
          "name": "UAE Dirham",
          "rate": 1,
          "isBaseCurrency": false,
          "isActive": true
        },
        "brand": {
          "publicId": "a8f7f15b-3ec6-4ce2-a49f-b2885437b71a",
          "name": "Al Futtaim",
          "logo": "https://ik.imagekit.io/emmufi2tro/brand_logos/..."
        },
        "categories": [
          {
            "publicId": "4775820b-f2dd-4069-8cae-cc113a763de3",
            "name": "Others",
            "slug": "others",
            "logo": "https://ik.imagekit.io/emmufi2tro/category_logos/..."
          }
        ],
        "images": [
          {
            "publicId": "7df6165f-d152-4c56-89fa-eb8e1de9c426",
            "url": "https://ik.imagekit.io/emmufi2tro/product_images/...",
            "altText": "Diera International School.webp",
            "isPrimary": true
          }
        ],
        "seo": null,
        "denominations": [
          {
            "publicId": "4de97849-3e10-43f6-b74f-23b9d5c4509c",
            "displayAmount": 0,
            "value": 0,
            "valueType": "PERCENTAGE",
            "exchangeRate": 1,
            "stockCount": 0,
            "status": "ACTIVE",
            "type": "RANGE",
            "minAmount": 100,
            "maxAmount": 5000,
            "convertedAmount": 0,
            "currency": "AED"
          }
        ],
        "createdAt": "2026-09-23T10:50:00.393Z",
        "updatedAt": "2026-09-28T12:41:33.239Z"
      }
    ],
    "pagination": {
      "totalItems": 139,
      "totalPages": 7,
      "current": 1,
      "limit": 20,
      "hasNext": true,
      "hasPrev": false,
      "nextPage": 2
    }
  }
}

The denomination type (RANGE or FIXED) determines the order payload structure. See Orders → Create Order for details.

Product Details

Get detailed information about a specific product by its public ID.

Endpoint

GET /products/:id

Path Parameters

id (required)

The public ID of the product. Example: 24b61004-0eb2-4eb1-92a0-61a20290dbe4

Example Request

cURL

curl --location 'https://api.99gift.ae/super-admin/api/v1/api-user/products/ed4bd48d-22ec-40d6-8c64-7ffcaf54189c' \
--header 'x-api-key: api_3f7b9d1c8e2a4f6b5d0c7e8a9b1f2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b'

Response Example

JSON

{
  "success": true,
  "data": {
    "publicId": "24b61004-0eb2-4eb1-92a0-61a20290dbe4",
    "name": "Deira International School E Gift Card",
    "slug": "al-futtaim-deira-international-school-uae-e-gift-card",
    "description": "As a diversified organisation, we bring the quality...",
    "sku": "EGCGBALFUAE022",
    "status": "ACTIVE",
    "usageLocation": "OFFLINE",
    "tnc": "1.This card can be used across Al Futtaim brands and stores...",
    "region": "AE",
    "redemptionInfo": "",
    "groupId": null,
    "logo": null,
    "currency": {
      "publicId": "38f2722f-ea5f-4b0a-b65a-b8fd9c855f2d",
      "code": "AED",
      "name": "UAE Dirham",
      "rate": 1,
      "isBaseCurrency": false,
      "isActive": true
    },
    "brand": {
      "publicId": "a8f7f15b-3ec6-4ce2-a49f-b2885437b71a",
      "name": "Al Futtaim",
      "logo": "https://ik.imagekit.io/emmufi2tro/brand_logos/..."
    },
    "categories": [
      {
        "publicId": "4775820b-f2dd-4069-8cae-cc113a763de3",
        "name": "Others",
        "slug": "others",
        "logo": "https://ik.imagekit.io/emmufi2tro/category_logos/..."
      }
    ],
    "images": [
      {
        "publicId": "7df6165f-d152-4c56-89fa-eb8e1de9c426",
        "url": "https://ik.imagekit.io/emmufi2tro/product_images/...",
        "altText": "Diera International School.webp",
        "isPrimary": true
      }
    ],
    "denominations": [
      {
        "publicId": "4de97849-3e10-43f6-b74f-23b9d5c4509c",
        "displayAmount": 0,
        "value": 0,
        "valueType": "PERCENTAGE",
        "exchangeRate": 1,
        "stockCount": 0,
        "status": "ACTIVE",
        "type": "RANGE",
        "minAmount": 100,
        "maxAmount": 5000,
        "convertedAmount": 0,
        "currency": "AED"
      }
    ],
    "seo": null,
    "createdAt": "2026-09-23T10:50:00.393Z",
    "updatedAt": "2026-09-28T12:41:33.239Z"
  }
}

Use the publicId from this response when creating an order with a specific denomination.

Create Order

Create a new order for digital gift cards or vouchers.

Endpoint

POST /orders/create

Range Type Denomination

Use selectedAmount when the denomination is of range type (flexible value).

cURL

curl --location 'https://api.99gift.ae/super-admin/api/v1/api-user/orders/create' \
--header 'x-api-key: api_3f7b9d1c8e2a4f6b5d0c7e8a9b1f2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b' \
--header 'Content-Type: application/json' \
--data '{
  "productId": "d8a7458e-3eb4-4770-be88-168ef1d1e59e",
  "denominations": [
    {
      "denominationId": "160a99e5-f59e-4463-b6f9-89aed8da77e0",
      "quantity": 1,
      "selectedAmount": 10
    }
  ],
  "referenceId": "TestFromAPI1478",
  "currency": "AED"
}'

Fixed Type Denomination

For fixed denominations, omit selectedAmount.

cURL

curl --location 'https://api.99gift.ae/super-admin/api/v1/api-user/orders/create' \
--header 'x-api-key: api_3f7b9d1c8e2a4f6b5d0c7e8a9b1f2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b' \
--header 'Content-Type: application/json' \
--data '{
  "productId": "d8a7458e-3eb4-4770-be88-168ef1d1e59e",
  "denominations": [
    {
      "denominationId": "160a99e5-f59e-4463-b6f9-89aed8da77e0",
      "quantity": 1
    }
  ],
  "referenceId": "TestFromAPI1478",
  "currency": "AED"
}'

Request Body — JSON

JSON

{
  "productId": "d8a7458e-3eb4-4770-be88-168ef1d1e59e",
  "denominations": [
    {
      "denominationId": "160a99e5-f59e-4463-b6f9-89aed8da77e0",
      "quantity": 1,
      "selectedAmount": 10
    }
  ],
  "referenceId": "TestFromAPI1478",
  "currency": "AED",
  "customer": {
    "email": "99giftae@gmail.com",
    "phone": "82738278372"
  }
}

Response Example

JSON

{
  "success": true,
  "message": "Order received and is being processed. 1 item(s) in this order.",
  "data": {
    "orderId": "f1fef10c-42f8-4679-bb26-818ba26eb25e",
    "orderNumber": "342809",
    "referenceId": "TestFromAPI1478",
    "status": "PENDING",
    "paymentStatus": "PENDING",
    "createdAt": "2026-09-13T17:54:17.555Z",
    "totalOrders": 1,
    "estimatedCompletion": "2026-09-13T17:54:47.555Z",
    "statusCheckUrl": "/api/orders/f1fef10c-42f8-4679-bb26-818ba26eb25e"
  }
}

Note: The order is created as PENDING and processed asynchronously. Use the Order Status or Order Details endpoint to poll for completion and retrieve vouchers.

Completed Order Response (after processing)

Once processing finishes, the same order reference will return completed vouchers via the Order Details endpoint:

JSON

{
  "success": true,
  "data": {
    "order": {
      "publicId": "f1fef10c-42f8-4679-bb26-818ba26eb25e",
      "orderNumber": "342809",
      "referenceId": "TestFromAPI1478",
      "status": "COMPLETED",
      "totalAmount": 9.65,
      "currency": "AED",
      "paymentMethod": "WALLET",
      "paymentStatus": "PAID",
      "createdAt": "2026-09-13T17:54:17.555Z",
      "customer": {
        "email": "99giftae@gmail.com",
        "phone": "82738278372"
      },
      "product": {
        "publicId": "d8a7458e-3eb4-4770-be88-168ef1d1e59e",
        "name": "Noon UAE",
        "sku": "3063480"
      },
      "quantity": 1,
      "totalOrders": 1,
      "vouchers": [
        {
          "publicId": "7f4733f3-e8de-4c71-af65-9750dc52e557",
          "code": "1100170408923516",
          "pin": "8774",
          "status": "SOLD",
          "expiresAt": "2027-09-13T17:54:20.000Z",
          "deliveredAt": "2026-09-13T17:54:51.602Z",
          "denomination": {
            "amount": 10,
            "currency": "AED",
            "publicId": "160a99e5-f59e-4463-b6f9-89aed8da77e0"
          }
        }
      ],
      "orderBreakdown": [
        {
          "orderId": "f1fef10c-42f8-4679-bb26-818ba26eb25e",
          "orderNumber": "342809",
          "totalAmount": "9.65",
          "status": "COMPLETED",
          "quantity": 1,
          "denominationAmount": "0",
          "selectedAmount": 10,
          "voucherCount": 1,
          "createdAt": "2026-09-13T17:54:17.555Z"
        }
      ],
      "invoice": {
        "publicId": "4cd6f57e-dab4-4828-b31f-2f24591582cb",
        "invoiceNumber": "INV-1789322057537",
        "totalAmount": "9.65",
        "status": "PAID",
        "paidAt": "2026-09-13T17:54:51.612Z"
      },
      "transaction": {
        "publicId": "4cd9405f-09c9-457f-a26e-266e0aa7e42c",
        "amount": "9.65",
        "status": "SUCCESS",
        "createdAt": "2026-09-13T17:54:17.550Z"
      }
    }
  }
}

Order Status

Check the current status of an order using its reference ID.

Endpoint

GET /orders/status/:referenceId

Example Request

cURL

curl --location 'https://api3.gzonic.com/super-admin/api/v1/api-user/orders/status/TestFromAPI114' \
--header 'x-api-key: api_3f7b9d1c8e2a4f6b5d0c7e8a9b1f2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b'

Response Example

JSON

{
  "success": true,
  "data": {
    "orderId": "b32bb8be-5a6e-4748-bec0-366cecdae94b",
    "orderNumber": "396037",
    "referenceId": "TestFromAPI114",
    "status": "COMPLETED",
    "paymentStatus": "PAID",
    "createdAt": "2026-06-18T06:32:20.614Z",
    "updatedAt": "2026-06-18T06:34:23.298Z",
    "hasVouchers": true,
    "invoiceStatus": "PAID",
    "paidAt": "2026-06-18T06:34:23.300Z",
    "denominationAmount": "40",
    "denominationCurrency": "AED",
    "totalItemsInOrder": 1,
    "message": "Order completed successfully! Your vouchers are ready.",
    "vouchers": [
      {
        "code": "5f74a063f2b24eb38479c94153af39b8",
        "pin": "745",
        "expiresAt": "2027-06-18T06:32:21.745Z"
      }
    ]
  }
}

When status: "COMPLETED" and hasVouchers: true, voucher codes are available in the response.

Order Details

Retrieve full order details including voucher codes by order reference ID.

Endpoint

GET /orders/:referenceId

Example Request

cURL

curl --location 'https://api.99gift.ae/super-admin/api/v1/api-user/orders/26D3A01B' \
--header 'x-api-key: api_3f7b9d1c8e2a4f6b5d0c7e8a9b1f2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b'

Response Example

JSON

{
  "success": true,
  "data": {
    "order": {
      "publicId": "f1fef10c-42f8-4679-bb26-818ba26eb25e",
      "orderNumber": "342809",
      "referenceId": "26D3A01B",
      "status": "COMPLETED",
      "totalAmount": 9.65,
      "currency": "AED",
      "paymentMethod": "WALLET",
      "paymentStatus": "PAID",
      "createdAt": "2026-09-13T17:54:17.555Z",
      "customer": {
        "email": "99giftae@gmail.com",
        "phone": "82738278372"
      },
      "product": {
        "publicId": "d8a7458e-3eb4-4770-be88-168ef1d1e59e",
        "name": "Noon UAE",
        "sku": "3063480"
      },
      "quantity": 1,
      "totalOrders": 1,
      "vouchers": [
        {
          "publicId": "7f4733f3-e8de-4c71-af65-9750dc52e557",
          "code": "1100170408923516",
          "pin": "8774",
          "status": "SOLD",
          "expiresAt": "2027-09-13T17:54:20.000Z",
          "deliveredAt": "2026-09-13T17:54:51.602Z",
          "denomination": {
            "amount": 10,
            "currency": "AED",
            "publicId": "160a99e5-f59e-4463-b6f9-89aed8da77e0"
          }
        }
      ],
      "orderBreakdown": [
        {
          "orderId": "f1fef10c-42f8-4679-bb26-818ba26eb25e",
          "orderNumber": "342809",
          "totalAmount": "9.65",
          "status": "COMPLETED",
          "quantity": 1,
          "denominationAmount": "0",
          "selectedAmount": 10,
          "voucherCount": 1,
          "createdAt": "2026-09-13T17:54:17.555Z"
        }
      ],
      "invoice": {
        "publicId": "4cd6f57e-dab4-4828-b31f-2f24591582cb",
        "invoiceNumber": "INV-1789322057537",
        "totalAmount": "9.65",
        "status": "PAID",
        "paidAt": "2026-09-13T17:54:51.612Z"
      },
      "transaction": {
        "publicId": "4cd9405f-09c9-457f-a26e-266e0aa7e42c",
        "amount": "9.65",
        "status": "SUCCESS",
        "createdAt": "2026-09-13T17:54:17.550Z"
      }
    }
  }
}

Returns full order details including voucher codes, invoice, and transaction info.

Order List

Retrieve a paginated list of all orders for your account.

Endpoint

GET /orders/list

Query Parameters

page / limit (optional)

Pagination controls. Default: page=1&limit=20

status (optional)

Filter by order status. Example: ?status=COMPLETED

Example Request

cURL

curl --location 'https://api.99gift.ae/super-admin/api/v1/api-user/orders/list' \
--header 'x-api-key: api_3f7b9d1c8e2a4f6b5d0c7e8a9b1f2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b'

Response Example

JSON

{
  "success": true,
  "data": {
    "orders": [
      {
        "orderId": "71b73766-d557-41cf-afe6-ae4410e5419e",
        "orderNumber": "692403",
        "referenceId": "15CADD6F",
        "status": "COMPLETED",
        "paymentStatus": "PAID",
        "totalAmount": 10,
        "currency": "AED",
        "quantity": 1,
        "customer": {
          "email": "99giftae@gmail.com",
          "phone": "82738278372"
        },
        "product": {
          "publicId": "d8a7458e-3eb4-4770-be88-168ef1d1e59e",
          "name": "Noon UAE",
          "sku": "3063480"
        },
        "denomination": {
          "publicId": "160a99e5-f59e-4463-b6f9-89aed8da77e0",
          "amount": 0,
          "currency": "AED",
          "type": "RANGE"
        },
        "invoice": {
          "publicId": "7038805a-3311-485d-83d4-b7fbc8305c22",
          "invoiceNumber": "INV-1790241028709",
          "status": "PAID",
          "paidAt": "2026-09-24T09:11:02.848Z"
        },
        "voucherCount": 1,
        "deliveredVouchers": 1,
        "createdAt": "2026-09-24T09:10:28.719Z",
        "updatedAt": "2026-09-24T09:11:02.844Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "totalCount": 218,
      "totalPages": 11,
      "hasNextPage": true,
      "hasPrevPage": false,
      "nextPage": 2
    }
  }
}