GenzShop Buyer API

The official API by GenzShop for partners selling products automatically on their own website, app or bot.

Quick start

  1. Use the API key issued by GenzShop (contact admin to get a key).
  2. Fetch products with GET /products.php.
  3. Check the wallet balance with GET /balance.php.
  4. Purchase with POST /purchase.php.
  5. On success, take the data in deliveredAccounts and deliver it to the customer.

Keep in mind

  • Endpoint URLs must end with .php (e.g. /products.php). Missing .php returns an HTML 404 page instead of JSON.
  • Production must be called over HTTPS — the key travels in headers so it must go through an encrypted channel. Plain HTTP calls are rejected (HTTPS_REQUIRED).
  • Each customer order must have its own idempotency_key.
  • When resubmitting the same order, keep the original idempotency_key — the system returns the already-created order with replay: true and does not charge again.
  • On purchase, the system charges the wallet balance (VND) of the account linked to the key.
  • If a product is temporarily out of stock, the purchase call returns an OUT_OF_STOCK error.
  • On error, read errorCode to know how to handle it.

Base URL & Authentication

Base URL:

https://genzshop.vn/api/partner/v1

Every request must include the auth header (recommended: X-API-Key):

X-API-Key: YOUR_API_KEY

Or use the Bearer standard (equivalent):

Authorization: Bearer YOUR_API_KEY
On production, the API only accepts HTTPS connections.
GET /products.php

Get the list of products currently on sale, with reseller pricing and stock.

curl "https://genzshop.vn/api/partner/v1/products.php" \
  -H "X-API-Key: YOUR_API_KEY"

Response (abbreviated):

{
  "success": true,
  "walletCurrency": "VND",
  "products": [
    {
      "product_id": "CUR-0001",
      "name": "Cursor Pro 1 tháng",
      "description": "Tài khoản Cursor Pro dùng 1 tháng",
      "type": "cursor",
      "walletCurrency": "VND",
      "walletPricing": 120000,
      "walletPricingText": "120.000 VND",
      "available": 38
    }
  ]
}

Use product_id (the SKU) to purchase. If a product is temporarily out of stock, the purchase call returns an OUT_OF_STOCK error.

GET /balance.php

View the current wallet balance of the account linked to the API key.

curl "https://genzshop.vn/api/partner/v1/balance.php" \
  -H "X-API-Key: YOUR_API_KEY"
{
  "success": true,
  "walletCurrency": "VND",
  "balance": 5000000,
  "balanceText": "5.000.000 VND"
}
POST /purchase.php

Buy and receive accounts instantly. Charges the wallet balance and returns accounts in deliveredAccounts.

curl -X POST "https://genzshop.vn/api/partner/v1/purchase.php" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "CUR-0001",
    "quantity": 1,
    "idempotency_key": "don-khach-0001"
  }'

Body parameters:

ParameterTypeDescription
product_idstringProduct SKU, e.g. CUR-0001 (required)
quantityintegerQuantity 1..1000 (required)
idempotency_keystring8..128 chars [A-Za-z0-9._:-] (required)
customer_emailstringYour customer email for reconciliation (optional)

Success response:

{
  "success": true,
  "walletCurrency": "VND",
  "orderCode": "GZ260724CUR3F9A2B",
  "productType": "cursor",
  "quantity": 1,
  "amount": 120000,
  "amountText": "120.000 VND",
  "balance": 4880000,
  "balanceText": "4.880.000 VND",
  "deliveredAccounts": [
    {
      "productItemId": "1024",
      "user": "[email protected]",
      "password": "example-password",
      "verifyEmail": "[email protected]"
    }
  ]
}

If you resubmit with an already-used idempotency_key, the response keeps the original order and adds "replay": true — no second charge.

Errors & error codes (errorCode)

All errors return JSON in a fixed shape (HTTP status ≥ 400):

{
  "success": false,
  "errorCode": "INSUFFICIENT_BALANCE",
  "detail": "Số dư ví không đủ. Cần 120.000 VND, số dư hiện tại 50.000 VND."
}
HTTPerrorCodeMeaning
400INVALID_BODYBody is not valid JSON
401MISSING_API_KEYMissing X-API-Key header (or Authorization: Bearer)
401INVALID_API_KEYKey is wrong or has been revoked
402INSUFFICIENT_BALANCEInsufficient wallet balance
403HTTPS_REQUIREDCalled over HTTP in production — HTTPS is required
403IP_NOT_ALLOWEDIP is not in the key allowlist
404PRODUCT_NOT_FOUNDProduct not found
405METHOD_NOT_ALLOWEDWrong HTTP method for the endpoint
409PRODUCT_INACTIVEProduct is not currently on sale
409OUT_OF_STOCKNot enough stock
422INVALID_PRODUCT_IDMissing or invalid product_id
422INVALID_QUANTITYQuantity out of range 1..1000
422INVALID_IDEMPOTENCY_KEYInvalid idempotency_key format
422INVALID_CUSTOMER_EMAILInvalid customer_email
429RATE_LIMITEDCalling too fast (by IP or by key), try again later
500INTERNAL_ERRORSystem error, no charge made

When RATE_LIMITED is hit on the per-key limit, the response includes Retry-After, X-RateLimit-Limit and X-RateLimit-Remaining headers — wait the seconds in Retry-After before retrying.

Zalo Telegram