GamesDrop.io API - Merchant Guide

Welcome to the GamesDrop.io Partner API documentation! This guide provides everything you need to integrate your reseller platform with the GamesDrop network. By integrating, you gain access to our catalog of over 10,000 digital products, ranging from mobile operator top-ups to in-game currency for popular mobile games. Start here to streamline your product offerings and connect your customers to a world of digital goods.

Table of Contents

1. Authorization
   • Getting a Token
   • Token Security
2. Core Concepts
   • Order Statuses
   • Error Handling
3. API Endpoints
   • Balance Management
     • Check Balance
     • Transaction History
   • Manage Products
   • Manage Orders
   • Player Validation
4. API Testing
   • Test Product
5. Integration Recommendations
6. Support

Authorization

Getting a Token

How to get it

1. Log in to your merchant account
2. Create a new store
3. After creating the store, you will receive a unique token
4. Token format: abcdef1234567890abcdef1234567890

Token Security

• 🔒 The token is confidential information
• ⚠️ Do not share the token with third parties
• 📝 The token cannot be recovered after creation
• 🔄 If necessary, you can generate a new token (the old one will become invalid)

Core Concepts

Order Statuses

Possible Errors

API Endpoints

Balance Management

Check Balance

HTTP
GET /api/v1/balance
Authorization: {{token}}

Response:

JSON
{
  "balance": 500.00,
  "draftBalance": 50.00,
  "currency": {
    "id": 3,
    "code": "USD"
  }
}

Response fields description:

Transaction History

HTTP
GET /api/v1/balance/transactions?page=1&limit=20
Authorization: {{token}}

Response:

JSON
{
  "transactions": [
    {
      "id": 12,
      "amount": -75.00,
      "type": "PURCHASE",
      "description": "API Purchase - Virtual credits",
      "balanceAfter": 425.00,
      "createdAt": "2025-07-28T05:21:46.121Z"
    },
    {
      "id": 11,
      "amount": -50.00,
      "type": "PURCHASE", 
      "description": "Test Purchase - Mobile game credits",
      "balanceAfter": 500.00,
      "createdAt": "2025-07-28T05:16:23.718Z"
    }
  ],
  "total": 25
}

Request fields description:

Response fields description:

Getting Product Information

HTTP
POST /api/v1/offers/find-one
Authorization: {{token}}

{
  "offerId": 1001
}

Response:

JSON
{
  "offerId": 1001,
  "productName": "PUBG MOBILE GIFT",
  "offerName": "60 UC",
  "count": 1,
  "price": 560.10,
  "currency": "RUB",
  "isReturnDataForCustomer": true
}

Request fields description:

Response fields description:

Creating an Order

HTTP
POST /api/v1/offers/create-order
Authorization: {{token}}

{
  "offerId": 1001,
  "price": 560.10,
  "transactionId": "test112321124214",
  "customer": {
    "email": "user@gmail.com",
    "gameUserId": "52357322414"
  }
}

Request fields description:

Response:

JSON
{
  "orderId": 10222502,
  "count": 1,
  "price": 560.10,
  "currency": "RUB",
  "offerId": 1001,
  "productName": "PUBG MOBILE GIFT",
  "offerName": "60 UC",
  "status": "COMPLETED",
  "isReturnDataForCustomer": true,
  "key": "001434249936",
  "createdAt": "2024-05-28 10:08:04.296+00"
}

Response fields description:

Check Order Status

HTTP
POST /api/v1/offers/order-status
Authorization: {{token}}

{
  "orderId": 10222502
}

Request fields description:

Response:

JSON
{
  "orderId": 10222502,
  "count": 1,
  "price": 560.10,
  "currency": "RUB",
  "offerId": 1001,
  "productName": "PUBG MOBILE GIFT",
  "offerName": "60 UC",
  "status": "COMPLETED",
  "isReturnDataForCustomer": true,
  "key": "001434249936",
  "createdAt": "2024-05-28 10:08:04.296+00"
}

Response fields description:

Player Validation

HTTP
POST /api/v1/offers/check-game-data
Authorization: {{token}}

{
  "offerId": 1001,
  "gameUserId": "52357322414",
  "gameServerId": "1234"
}

Request fields description:

Successful response:

JSON
{
  "status": "VALID",
  "gameUserLogin": "JJJ"
}

Successful response fields description:

Error response:

JSON
{
  "status": "INVALID"
}

Error response fields description:

API Testing

Test Product

For testing API integration, a special test product is available:

• Product ID: 999
• Name: Steam US
• Offer Name: TEST OFFER GROUP
• Price: 23.09 KZT (important to use exact value)
• Returns Key: Yes

Example request for test product information:

HTTP
POST /api/v1/offers/find-one
Authorization: {{token}}

{
  "offerId": 999
}

Example creating test order:

HTTP
POST /api/v1/offers/create-order
Authorization: {{token}}

{
  "offerId": 999,
  "price": 23.09,
  "transactionId": "test_123456",
  "customer": {
    "email": "test@example.com",
    "gameUserId": "123456789"
  }
}

Test product features:

• Always returns successful response with correct parameters
• Generates test activation key
• Creates order with COMPLETED status
• Player validation always returns VALID for test product
• Works in test mode without real fund deduction

Balance Management Examples

Check balance before purchase:

JAVASCRIPT
// 1. Check current balance
const balanceResponse = await fetch('/api/v1/balance', {
  headers: { 'Authorization': 'your-token-here' }
});
const { balance } = await balanceResponse.json();

// 2. Get product information
const offerResponse = await fetch('/api/v1/offers/find-one', {
  method: 'POST',
  headers: { 
    'Authorization': 'your-token-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ offerId: 1001 })
});
const { price } = await offerResponse.json();

// 3. Check sufficient funds
if (balance >= price) {
  // Create order
  console.log('Sufficient balance, creating order...');
} else {
  console.log('Insufficient balance, need to top up');
}

Get transaction history:

JAVASCRIPT
const transactionsResponse = await fetch('/api/v1/balance/transactions', {
  headers: { 'Authorization': 'your-token-here' }
});
const { transactions, total } = await transactionsResponse.json();

console.log(`Total transactions: ${total}`);
transactions.forEach(tx => {
  console.log(`${tx.createdAt}: ${tx.type} ${tx.amount} (Balance: ${tx.balanceAfter})`);
});

Integration Recommendations

💰 Balance Management

• Regularly check balance before large purchases
• Keep track of transactions for reconciliation with your system
• Notify users about need to top up when funds are insufficient
• Use pagination when requesting transaction history

🔍 Before Creating an Order

• Get up-to-date product information
• Check balance to ensure sufficient funds
• Check player validity (for direct top-up)

📝 When Creating an Order

• Use a unique transactionId
• Specify the current price
• Specify offerId as number, not string
• Fill in all required fields for the product type

✅ After Creating an Order

• Save the orderId
• Check the order status
• Upon COMPLETED status, receive the key/product

⚠️ When Errors Occur

• Check the token
• Ensure data correctness and request format
• Create a new order if necessary

Support

If you have any questions, please contact technical support:

• 📧 Email: support@gamesdrop.io
• 💬 Telegram: @gamesdrop_support

Error Handling Recommendations

🔍 Pre-Request Checks

• Token validation
• Product ID verification
• Price accuracy
• Uniqueness of transaction_id
• Correct data format (especially offerId as number)

🛠 Response Handling

• Handle all error codes
• Log errors
• Implement retry mechanism

📊 Order Management

• Save order IDs
• Monitor statuses
• Update data

Telegram Stars

🌟 GamesDrop has integrated Telegram Stars support! Now you can send Telegram Stars to users through the same standard API endpoints.

Available Telegram Stars Products

How pricing works:

• A6-Gateway gets the current TON/USD rate from kernel currency API
• Price is calculated based on Fragment.com coefficients (100 Stars ≈ 0.3 TON)
• Prices are updated in real-time with each request

Using the Same Endpoints

1. Getting Telegram Stars information:

HTTP
POST /api/v1/offers/find-one
Authorization: {{token}}

{
  "offerId": "telegram_stars_100"
}

Response:

JSON
{
  "offerId": "telegram_stars_100",
  "productName": "Telegram Stars",
  "offerName": "100 Stars",
  "count": 1,
  "price": 0.77,
  "currency": "USD",
  "isReturnDataForCustomer": true
}

2. Creating an order for Telegram Stars:

HTTP
POST /api/v1/offers/create-order
Authorization: {{token}}

{
  "offerId": "telegram_stars_100",
  "price": 0.77,
  "transactionId": "tg_stars_12345",
  "customer": {
    "email": "user@example.com",
    "gameUserId": "143594291"
  }
}

Response on successful delivery:

JSON
{
  "orderId": 10228901,
  "count": 1,
  "price": 0.78,
  "currency": "USD",
  "offerId": "telegram_stars_100",
  "productName": "Telegram Stars",
  "offerName": "100 Stars",
  "status": "COMPLETED",
  "isReturnDataForCustomer": true,
  "fulfillmentData": {
    "telegram_user_id": 143594291,
    "stars_amount": 100,
    "transaction_id": "tg_tx_abc123",
    "delivery_status": "completed"
  },
  "createdAt": "2025-08-26T12:30:15.234Z"
}

Response on delivery failure:

JSON
{
  "orderId": 10228902,
  "status": "CANCELED",
  "message": "Failed to deliver Stars: user not found",
  "fulfillmentData": {
    "telegram_user_id": 123456789,
    "stars_amount": 100,
    "delivery_status": "failed",
    "error_message": "user not found"
  },
  "createdAt": "2025-08-26T12:30:15.234Z"
}

🔑 Important Telegram Stars Features

gameUserId requirements:

• gameUserId must be a numeric Telegram User ID for order creation
• Get User ID in two ways:
  1. 📞 Via @userinfobot in Telegram
  2. 🆕 Via our API validation (see section below)
• Example: "gameUserId": "143594291"
• ❌ NOT username (@username) for order creation

Delivery statuses:

• COMPLETED - Stars successfully delivered to user
• CANCELED - Failed to deliver (invalid user ID, blocked bot, etc.)

Typical delivery errors:

• "user not found" - invalid Telegram User ID
• "STARGIFT_INVALID" - user cannot receive Stars (restrictions)
• "bot was blocked by user" - user blocked the bot

🆔 Telegram User Validation

🎯 New endpoint for validating username and getting User ID!

If your users only know their @username, use this endpoint to get User ID before creating an order.

Validation endpoint:

HTTP
POST https://gamesdrop.io/api/aggregator/a6/telegram/user-info
Authorization: {{token}}
Content-Type: application/json

{
  "username": "@igoryan34"
}

Response on successful validation:

JSON
{
  "valid": true,
  "username": "igoryan34",
  "userInfo": {
    "id": 143594291,
    "first_name": "Igor",
    "username": "igoryan34",
    "photo_url": "AQADAgADRKgxGzMTjwgABCAI..."
  },
  "message": "User account verified successfully"
}

Response when User ID cannot be obtained:

JSON
{
  "valid": true,
  "username": "igoryan34",
  "userInfo": {
    "username": "igoryan34",
    "first_name": "igoryan34"
  },
  "message": "Username format is valid, but user details are not publicly available. Full verification requires user interaction with the bot."
}

Request fields description:

Response fields description:

⚠️ Important features:

• Endpoint returns User ID only if user has interacted with the bot
• If userInfo.id is missing, ask user to message @gamesdrop_api_bot
• Can pass as "@username" or "username"
• Can also pass User ID to get additional information

📱 Developer Integration Examples

Complete flow example with username validation in JavaScript:

JAVASCRIPT
// 1. Validate username and get User ID
const validateTelegramUser = async (username) => {
  const response = await fetch('https://gamesdrop.io/api/aggregator/a6/telegram/user-info', {
    method: 'POST',
    headers: {
      'Authorization': 'your-token-here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ username })
  });

  const result = await response.json();

  if (result.valid && result.userInfo && result.userInfo.id) {
    return {
      userId: result.userInfo.id,
      firstName: result.userInfo.first_name,
      username: result.userInfo.username
    };
  } else {
    throw new Error('Unable to get User ID. Please ask user to message @gamesdrop_api_bot first.');
  }
};

// 2. Get current price
const getStarsPrice = async (starsAmount) => {
  const response = await fetch('/api/v1/offers/find-one', {
    method: 'POST',
    headers: {
      'Authorization': 'your-token-here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      offerId: `telegram_stars_${starsAmount}`
    })
  });
  return response.json();
};

// 3. Send Stars to user
const sendStarsByUsername = async (usernameOrId, starsAmount) => {
  // First get User ID if username was passed
  let userId;
  if (isNaN(usernameOrId)) {
    // This is username, need to get User ID
    const userInfo = await validateTelegramUser(usernameOrId);
    userId = userInfo.userId;
    console.log(`✅ Validated user: ${userInfo.firstName} (@${userInfo.username}) - ID: ${userId}`);
  } else {
    // This is already User ID
    userId = parseInt(usernameOrId);
  }

  // Get price
  const { price } = await getStarsPrice(starsAmount);

  // Create order
  const response = await fetch('/api/v1/offers/create-order', {
    method: 'POST',
    headers: {
      'Authorization': 'your-token-here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      offerId: `telegram_stars_${starsAmount}`,
      price: price,
      transactionId: `stars_${Date.now()}`,
      customer: {
        email: "optional@example.com",
        gameUserId: userId.toString()
      }
    })
  });

  const result = await response.json();

  if (result.status === 'COMPLETED') {
    console.log(`✅ Successfully sent ${starsAmount} Stars to User ID ${userId}`);
    return result;
  } else {
    console.error(`❌ Failed to send Stars: ${result.message}`);
    throw new Error(result.message);
  }
};

// Usage:
// With username:
sendStarsByUsername('@igoryan34', 100)
  .then(order => console.log('Order created:', order.orderId))
  .catch(error => console.error('Delivery failed:', error));

// With User ID:
sendStarsByUsername('143594291', 100)
  .then(order => console.log('Order created:', order.orderId))
  .catch(error => console.error('Delivery failed:', error));

💼 B2B Use Cases

1. Game rewards:

JAVASCRIPT
// Reward player for achievement
await sendStars(userTelegramId, 50);

2. Promo campaigns:

JAVASCRIPT
// Send Stars to all contest winners
const winners = [143594291, 987654321, 456789123];
for (const userId of winners) {
  await sendStars(userId, 100);
}

3. Cashback programs:

JAVASCRIPT
// Return part of purchase as Stars
const cashbackAmount = Math.floor(purchaseAmount * 0.05); // 5% cashback
const starsAmount = Math.min(cashbackAmount * 100, 1000); // convert to Stars
await sendStars(userTelegramId, starsAmount);

⚡ Performance and Limits

• Rate limiting: 30 requests per second on Telegram API
• Minimum amount: 1 Star
• Maximum amount: 2500 Stars per transaction
• Retry logic: Automatic retries on temporary errors
• Delivery time: Instant delivery (< 3 seconds)

🛡️ Security

• Telegram User ID validation before sending
• GamesDrop balance check before order creation
• Logging of all operations for audit
• Duplicate transaction protection via transactionId