Get API Key Support
Enterprise-Grade API

G2Bulk Public API Documentation

Professional gaming top-up and digital voucher services. Secure, reliable, and lightning-fast API designed for developers and businesses. Support for PUBG Mobile, Mobile Legends, Free Fire, and more.

https://api.g2bulk.com/v1/

Last Updated: 27 November 2025 12:00 PM UTC

⚡
99.9%
Uptime
🔒
Secure
API Authentication
🎮
10+
Games Supported
🚀
<200ms
Avg Response Time

Quick Navigation

Authentication User Endpoints Products & Categories Orders Games & Top-up Transactions Plans & Subscriptions Rate Limiting Error Handling

Authentication

API Key Authentication

Protected endpoints require authentication using an API key. Include your API key in the request header for all authenticated requests.

Request Header 
X-API-Key: your_api_key_here
Get Your API Key: Obtain an API key instantly from our Telegram Bot
Security Warning: Multiple failed authentication attempts will trigger a permanent IP ban. Keep your API key secure and never share it publicly.

User Endpoints

GET /v1/getMe Authentication Required

Retrieve authenticated user details including balance, username, and user ID.

Response Example 
{
    "success": true,
    "user_id": 123456789,
    "username": "johndoe",
    "first_name": "John Doe",
    "balance": 8.74
}

Products & Categories

GET /v1/category Public

Retrieve all available product categories with product counts.

Response Example 
{
    "success": true,
    "categories": [
        {
            "id": 1,
            "title": "PUBG Mobile UC Vouchers",
            "description": "",
            "product_count": 11
        },
        {
            "id": 2,
            "title": "Razer Gold Accounts",
            "description": "",
            "product_count": 5
        }
    ]
}
GET /v1/products Public

Retrieve all available products with pricing and stock information.

Response Example 
{
    "success": true,
    "products": [
        {
            "id": 1,
            "title": "60 UC Voucher",
            "description": "",
            "category_id": 1,
            "category_title": "PUBG Mobile UC Vouchers",
            "unit_price": 0.84,
            "stock": 1006
        }
    ]
}
GET /v1/products/:id Public

Retrieve detailed information about a specific product.

GET /v1/category/:id Public

Retrieve all products from a specific category.

POST /v1/products/:id/purchase Authentication Required

Purchase a product with specified quantity. Balance is automatically deducted.

Request Body 
{
    "quantity": 5
}
Response Example 
{
    "success": true,
    "order_id": 123,
    "transaction_id": 456,
    "product_id": 1,
    "product_title": "60 UC Voucher",
    "delivery_items": ["KEY1", "KEY2", "KEY3"]
}

Orders

GET /v1/orders Authentication Required

Retrieve complete order history for the authenticated user.

Response Example 
{
    "success": true,
    "orders": [
        {
            "id": 1,
            "user_id": 123456789,
            "product_id": 1,
            "product_title": "60 UC Voucher",
            "quantity": 1,
            "total_price": 0.84,
            "status": "COMPLETED",
            "description": "Purchase from G2Bulk Bot"
        }
    ]
}
GET /v1/orders/:id Authentication Required

Retrieve detailed information about a specific order.

Games & Top-up Services

GET /v1/games Public

Retrieve all supported games for top-up services.

Response Example 
{
    "success": true,
    "games": [
        {
            "id": 1,
            "code": "pubg_mobile",
            "name": "PUBG Mobile",
            "image_url": "/images/pubg_mobile.png"
        },
        {
            "id": 2,
            "code": "free_fire",
            "name": "Free Fire",
            "image_url": "/images/free_fire.png"
        }
    ]
}
POST /v1/games/fields Public

Get required input fields for a specific game (e.g., user ID, server ID).

Request Body 
{
    "game": "mlbb"
}
Response Example 
{
    "code": "200",
    "info": {
        "fields": ["userid", "serverid"],
        "notes": "Not available for Indonesia users"
    }
}
POST /v1/games/servers Public

Get available server list for a specific game. Some games require server selection during top-up. If a game doesn't have predefined servers, this endpoint returns a 403 error indicating servers are not required.

Request Body 
{
    "game": "mlbb"
}
Response (With Servers) 
{
    "code": "200",
    "servers": {
        "SouthEast Asia": "SouthEast Asia",
        "America": "America",
        "Europe": "Europe"
    }
}
Response (No Servers Required) 
{
    "detail": {
        "code": "403",
        "message": "Game does not requires any servers"
    }
}
Note: A 403 response doesn't mean the game is invalid. It indicates that the game doesn't have predefined servers. Always check required fields using /v1/games/fields endpoint.
POST /v1/games/checkPlayerId Public

Validate a player ID before placing an order. Returns player name if valid.

Request Body 
{
    "game": "mlbb",
    "user_id": "123456789",
    "server_id": "2001"
}
Response (Valid) 
{
    "valid": "valid",
    "name": "John Doe",
    "openid": "41581795132966184"
}
GET /v1/games/:code/catalogue Public

Get all available denominations/packages for a specific game with current prices.

Response Example 
{
    "success": true,
    "game": {
        "code": "pubgm",
        "name": "PUBG Mobile",
        "image_url": "/images/pubgm.png"
    },
    "catalogues": [
        {
            "id": 1,
            "name": "60 UC",
            "amount": 0.88
        },
        {
            "id": 2,
            "name": "120 UC",
            "amount": 1.75
        }
    ]
}
Prices are automatically updated every 5 minutes to ensure accuracy.
POST /v1/games/:code/order Authentication Required

Place a game top-up order. Player ID is validated automatically and balance is checked before processing.

Request Body 
{
    "catalogue_name": "60 UC",
    "player_id": "5679523421",
    "server_id": "2001",
    "remark": "Optional note",
    "callback_url": "https://your-domain.com/webhook/order-status"
}

Callback URL (Optional)

You can provide an optional callback_url to receive automatic notifications when the order status changes. This is particularly useful for automating your workflow without polling for order status.

Property Details
Method POST request with JSON body
Timeout 10 seconds
Retry Policy Single retry on timeout or failure
When Called Whenever the order status changes (PENDING → PROCESSING → COMPLETED/FAILED)

Callback Payload

Your callback URL will receive a POST request with the following JSON structure:

Callback POST Body 
{
    "order_id": 42,
    "game_code": "pubgm",
    "game_name": "PUBG Mobile",
    "player_id": "5679523421",
    "player_name": "PlayerName",
    "server_id": "2001",
    "denom_id": "60 UC",
    "price": 0.88,
    "status": "COMPLETED",
    "message": "Order completed successfully",
    "remark": "your order remark",
    "timestamp": "2024-01-15T10:30:00Z"
}
Important: Your callback endpoint should respond with HTTP status 200-299 within 10 seconds. Failed callbacks will be retried once. Ensure your endpoint can handle duplicate notifications gracefully.
Response (Success) 
{
    "success": true,
    "message": "Order created successfully. We are processing your order.",
    "order": {
        "order_id": 42,
        "game": "PUBG Mobile",
        "catalogue": "60 UC",
        "player_id": "5679523421",
        "player_name": "PlayerName",
        "price": 0.88,
        "status": "PENDING",
        "callback_url": "https://your-domain.com/webhook/order-status"
    }
}

Order Status Values

Status Description
PENDING Order created and waiting to be processed
PROCESSING Order is currently being processed
COMPLETED Order completed successfully, items delivered
FAILED Order failed, balance automatically refunded
POST /v1/games/order/status Authentication Required

Check the current status of a specific game order.

Request Body 
{
    "order_id": 42,
    "game": "pubgm"
}
GET /v1/games/orders Authentication Required

Retrieve complete game top-up order history for the authenticated user.

Legacy PUBG Mobile Endpoints

Deprecated: These endpoints are maintained for backward compatibility. Please use the unified /v1/games/* endpoints for new integrations.
GET /v1/topup/pubgMobile/offers Public

Get available PUBG Mobile top-up offers.

POST /v1/topup/pubgMobile/checkPlayerId Public

Validate PUBG Mobile player ID.

POST /v1/topup/pubgMobile/purchase Authentication Required

Purchase PUBG Mobile top-up.

GET /v1/topup/pubgMobile/status Authentication Required

Check PUBG Mobile top-up status.

GET /v1/topups Authentication Required

Get all PUBG Mobile top-up history.

Transactions

GET /v1/transactions Authentication Required

Retrieve complete transaction history including balance additions, charges, and refunds.

Response Example 
{
    "success": true,
    "data": [
        {
            "id": 45,
            "user_id": 123456789,
            "transaction_type": "charge_balance",
            "amount": "1.126",
            "balance_before": "10.000",
            "balance_after": "8.874",
            "status": "success",
            "description": "Purchase PUBG Mobile 60 UC",
            "created_at": "2025-10-19T05:30:00Z"
        }
    ]
}

Transaction Types

Type Description
add_balance Balance added (manual addition or refund)
charge_balance Balance deducted (purchase or top-up)

Plans & Subscriptions

Subscription System: Users can subscribe to plans with recurring benefits. Balance is automatically deducted when creating a subscription, and users can only have one active subscription at a time.
GET /v1/plans Public

Retrieve all available subscription plans with pricing and duration information.

Response Example 
{
    "success": true,
    "plans": [
        {
            "ID": 1,
            "CreatedAt": "2025-11-27T10:00:00Z",
            "UpdatedAt": "2025-11-27T10:00:00Z",
            "DeletedAt": null,
            "name": "Basic Plan",
            "description": "Basic subscription with standard features",
            "price": 9.99,
            "duration_days": 30
        },
        {
            "ID": 2,
            "CreatedAt": "2025-11-27T10:00:00Z",
            "UpdatedAt": "2025-11-27T10:00:00Z",
            "DeletedAt": null,
            "name": "Premium Plan",
            "description": "Premium subscription with all features",
            "price": 29.99,
            "duration_days": 30
        }
    ]
}
GET /v1/plans/:id Public

Get detailed information about a specific subscription plan.

Response Example 
{
    "success": true,
    "plan": {
        "ID": 1,
        "CreatedAt": "2025-11-27T10:00:00Z",
        "UpdatedAt": "2025-11-27T10:00:00Z",
        "DeletedAt": null,
        "name": "Basic Plan",
        "description": "Basic subscription with standard features",
        "price": 9.99,
        "duration_days": 30
    }
}
POST /v1/subscriptions Authentication Required

Create a new subscription for the authenticated user. The plan price will be automatically deducted from the user's balance. Users can only have one active subscription at a time.

Request Body 
{
    "plan_id": 1
}
Response Example 
{
    "success": true,
    "subscription": {
        "ID": 1,
        "CreatedAt": "2025-11-27T12:00:00Z",
        "UpdatedAt": "2025-11-27T12:00:00Z",
        "DeletedAt": null,
        "user_id": 123456,
        "plan_id": 1,
        "start_date": "2025-11-27T12:00:00Z",
        "end_date": "2025-12-27T12:00:00Z",
        "status": "active",
        "plan": {
            "ID": 1,
            "name": "Basic Plan",
            "description": "Basic subscription with standard features",
            "price": 9.99,
            "duration_days": 30
        }
    }
}
Requirements:
  • User must have sufficient balance
  • User cannot have an existing active subscription
  • A transaction record is automatically created
GET /v1/subscriptions Authentication Required

Retrieve all subscriptions (past and present) for the authenticated user.

Response Example 
{
    "success": true,
    "subscriptions": [
        {
            "ID": 1,
            "CreatedAt": "2025-11-27T12:00:00Z",
            "UpdatedAt": "2025-11-27T12:00:00Z",
            "DeletedAt": null,
            "user_id": 123456,
            "plan_id": 1,
            "start_date": "2025-11-27T12:00:00Z",
            "end_date": "2025-12-27T12:00:00Z",
            "status": "active",
            "plan": {
                "ID": 1,
                "name": "Basic Plan",
                "price": 9.99,
                "duration_days": 30
            }
        }
    ]
}
GET /v1/subscriptions/active Authentication Required

Get the currently active subscription for the authenticated user.

Response (Active Found) 
{
    "success": true,
    "subscription": {
        "ID": 1,
        "user_id": 123456,
        "plan_id": 1,
        "start_date": "2025-11-27T12:00:00Z",
        "end_date": "2025-12-27T12:00:00Z",
        "status": "active",
        "plan": {
            "ID": 1,
            "name": "Basic Plan",
            "price": 9.99,
            "duration_days": 30
        }
    }
}
Response (No Active Subscription) 
{
    "success": false,
    "message": "No active subscription found"
}
POST /v1/subscriptions/:id/cancel Authentication Required

Cancel a subscription. Users can only cancel their own subscriptions. The subscription status will be changed to "cancelled" but no refund is issued.

Response Example 
{
    "success": true,
    "message": "Subscription cancelled successfully"
}
Note: Cancelling a subscription does not provide a refund. The subscription remains cancelled and cannot be reactivated.

Subscription Status Values

Status Description
active Subscription is currently active and valid
cancelled Subscription has been cancelled by user or admin
expired Subscription has expired (past end_date)

Rate Limiting

Rate Limit: 1000 requests per 10 seconds per API key.
Warning: Multiple failed requests to protected endpoints will trigger a permanent IP ban. Ensure your API key is valid before making requests.

Best Practices

  • Implement exponential backoff for retries
  • Cache responses when appropriate
  • Monitor your API usage regularly
  • Use batch operations when available

Error Handling

HTTP Status Codes

Status Code Meaning Description
200 OK Request successful
400 Bad Request Invalid request format or parameters
401 Unauthorized Authentication failed or API key invalid
404 Not Found Requested resource does not exist
429 Too Many Requests Rate limit exceeded
500 Internal Server Error An unexpected error occurred

Error Response Format

Error Response 
{
    "success": false,
    "message": "Detailed error message",
    "error_code": "ERROR_CODE_HERE"
}