G2Bulk Public API Documentation

Quick Navigation

Authentication User Endpoints Products & Categories Orders Games & Top-up Transactions 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": "",
            "image_url": "https://example.com/pubg.png",
            "custom_emoji_id": "5368324170671202286",
            "product_count": 11
        },
        {
            "id": 2,
            "title": "Razer Gold Accounts",
            "description": "",
            "image_url": null,
            "custom_emoji_id": null,
            "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,
            "image_url": null,
            "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.

Idempotency Key (Optional — Recommended): Send a X-Idempotency-Key UUID header to enable duplicate protection. If present and the same key is reused within 30 minutes, the original response is returned without re-processing — preventing duplicate charges on retries or network failures. If omitted, the request proceeds normally with no deduplication.

Request Headers

X-API-Key: your_api_key_here
X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000  # optional

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 paginated order history for the authenticated user, sorted by most recent.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	50	Items per page (max 100)
`search`	string	-	Search in description, status, product title

Response Example

{
    "success": true,
    "orders": [
        {
            "id": 1,
            "user_id": 123456789,
            "product_id": 1,
            "product_title": "60 UC Voucher",
            "quantity": 1,
            "total_price": "0.840",
            "status": "COMPLETED",
            "description": "Purchase from G2Bulk Bot",
            "created_at": "2025-10-19T05:30:00Z"
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 50,
        "total": 120,
        "total_pages": 3
    }
}

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/eta Public New

Get an estimated completion time for a specific game top-up denomination. Useful for showing users how long their order might take.

Parameter	Type	Description
`game_code`	Body (JSON)	Game code (e.g., `pubgm`, `mlbb`)
`denom_id`	Body (JSON)	Catalogue name (e.g., `60`, `First Purchase Pack`)

Request Body

{
    "game_code": "pubgm",
    "denom_id": "60"
}

Response Example (With Data)

{
    "success": true,
    "estimated_time": {
        "label": "less_than_5_minutes",
        "display": "Less than 5 minutes",
        "median_seconds": 187
    }
}

Response Example (Insufficient Data)

{
    "success": true,
    "estimated_time": {
        "label": "no_data",
        "display": "No estimate available",
        "median_seconds": null
    }
}

ETA Labels

Label	Display Text	Time Range
`instant`	Instant	Less than 30 seconds
`less_than_1_minute`	Less than 1 minute	30s – 1 minute
`less_than_2_minutes`	Less than 2 minutes	1 – 2 minutes
`less_than_5_minutes`	Less than 5 minutes	2 – 5 minutes
`less_than_10_minutes`	Less than 10 minutes	5 – 10 minutes
`less_than_30_minutes`	Less than 30 minutes	10 – 30 minutes
`more_than_30_minutes`	More than 30 minutes	Over 30 minutes
`no_data`	No estimate available	Not enough data to estimate

Note: The estimate may not be available for newly added catalogues. When no estimate is available, the label will be no_data.

POST /v1/games/:code/order Authentication Required

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

Idempotency Key (Optional — Recommended): Send a X-Idempotency-Key UUID header to enable duplicate protection. If present and the same key is reused within 30 minutes, the original response is returned without placing a new order — preventing duplicate top-ups on retries or network failures. If omitted, the request proceeds normally with no deduplication.

Request Headers

X-API-Key: your_api_key_here
X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000  # optional

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 paginated game top-up order history for the authenticated user, sorted by most recent.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	50	Items per page (max 100)
`search`	string	-	Search in game code, nickname, player ID, status, remark

Response Example

{
    "success": true,
    "orders": [
        {
            "order_id": 42,
            "game_code": "pubgm",
            "game_name": "PUBG Mobile",
            "player_id": "5123456789",
            "player_name": "PlayerOne",
            "server_id": "",
            "denom_id": "60",
            "price": 0.84,
            "status": "completed",
            "is_refunded": false,
            "remark": "",
            "message": "Top-up successful",
            "callback_url": null,
            "created_at": "2025-10-19T05:30:00Z",
            "completed_at": "2025-10-19T05:31:00Z"
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 50,
        "total": 85,
        "total_pages": 2
    }
}

Legacy Endpoints

DISABLED: These legacy endpoints have been disabled and are no longer available. Please migrate to the unified /v1/games/* endpoints for all game top-up operations.

GET /v1/topup/freeFire/offers Public

❌ DISABLED - Get available Free Fire top-up offers.

GET /v1/topup/pubgMobile/offers Public

❌ DISABLED - Get available PUBG Mobile top-up offers.

POST /v1/topup/pubgMobile/checkPlayerId Public

❌ DISABLED - Validate PUBG Mobile player ID.

POST /v1/topup/pubgMobile/purchase Authentication Required

❌ DISABLED - Purchase PUBG Mobile top-up.

GET /v1/topup/pubgMobile/status Authentication Required

❌ DISABLED - Check PUBG Mobile top-up status.

GET /v1/topups Authentication Required

❌ DISABLED - Get all PUBG Mobile top-up history.

Transactions

GET /v1/transactions Authentication Required

Retrieve paginated transaction history including balance additions, charges, and refunds. Sorted by most recent.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	50	Items per page (max 100)
`search`	string	-	Search in description, transaction type, status

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"
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 50,
        "total": 200,
        "total_pages": 4
    }
}

Transaction Types

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

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"
}