> For the complete documentation index, see [llms.txt](https://abdulkadir-aktas.gitbook.io/qadr_docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://abdulkadir-aktas.gitbook.io/qadr_docs/qadr-ingame-tebex-shop.md).

# Qadr Ingame Tebex Shop

{% embed url="<https://www.youtube.com/watch?v=kvYhM6gxVXM>" %}

### 📋 Table of Contents

1. [Overview](#overview)
2. [Installation](#installation)
3. [Configuration](#configuration)
4. [Usage](#usage)
5. [API Reference](#api-reference)
6. [Examples](#examples)
7. [Troubleshooting](#troubleshooting)
8. [FAQ](#faq-frequently-asked-questions)

***

### 🎯 Overview

**QADR Tebex Shop** is a professional Tebex payment system integration developed for RedM servers. This script allows your players to securely shop from the in-game store and automatically receive their rewards.

#### ✨ Features

* ✅ **Secure Payment System**: Safe payment processing with Tebex infrastructure
* ✅ **Automatic Product Delivery**: Products are automatically delivered to players upon payment completion
* ✅ **Multi-Package Support**: Multiple packages can be purchased in a single transaction
* ✅ **Browser Integration**: Seamless payment experience through Steam overlay
* ✅ **Real-time Status Tracking**: Track payment status in real-time
* ✅ **Multi-Language Support**: English and Turkish language support
* ✅ **Database Management**: All transactions are stored in the database
* ✅ **Cancel and Rollback**: Players can cancel the transaction at any time

#### 🔧 Technical Requirements

* **RedM Server** (prerelease build)
* **MySQL Database** (mysql-async or oxmysql)
* **RedEM Roleplay Framework**
* **Tebex Account** (with Creator API access)

***

### 📦 Installation

#### Step 1: Script Download and Placement

1. Copy the script files to your server's `resources` folder
2. Make sure the folder name is `qadr_tebex_shop`

```
resources/
└── qadr_tebex_shop/
    ├── fxmanifest.lua
    ├── client/
    ├── server/
    ├── shared/
    ├── html/
    └── lang/
```

#### Step 2: Database Setup

The script will automatically create the required table on first startup. However, if you want to create it manually:

```sql
CREATE TABLE IF NOT EXISTS qadr_tebex_shop_orders (
    id INT AUTO_INCREMENT PRIMARY KEY,
    playeridentifier VARCHAR(255) NOT NULL,
    basketident VARCHAR(255) NOT NULL,
    `status` ENUM('waiting', 'canceled', 'completed') DEFAULT 'waiting',
    qadr_tebex_shop_id VARCHAR(255) NOT NULL,
    ordernumber VARCHAR(255),
    INDEX idx_playeridentifier (playeridentifier),
    INDEX idx_basketident (basketident),
    INDEX idx_qadr_tebex_shop_id (qadr_tebex_shop_id),
    INDEX idx_ordernumber (ordernumber)
);
```

#### Step 3: server.cfg Configuration

Add the following line to your `server.cfg` file:

```cfg
ensure qadr_tebex_shop
```

**Important:** Make sure the script starts after `redem_roleplay` and database resource:

```cfg
ensure mysql-async
ensure redem_roleplay
ensure qadr_tebex_shop
```

#### Step 4: Database Connection

If you're using **oxmysql**, edit the `fxmanifest.lua` file:

```lua
server_script {
    '@oxmysql/lib/MySQL.lua', -- Use this line instead of mysql-async
    "server/server_conf.lua",
    "server/verification.lua",
    "server/server.lua",
}
```

***

### ⚙️ Configuration

#### Tebex API Settings

Edit the `server/server_conf.lua` file:

```lua
qadr_tebex_shop_variable = {
    projectId = "YOUR_PROJECT_ID",  -- Tebex Project ID
    privateKey = "YOUR_PRIVATE_KEY",  -- Tebex Private Key
    publicToken = "YOUR_PUBLIC_TOKEN",  -- Tebex Public Token
    loginReturnUrl = "https://yourdomain.com/redirect.html"  -- Post-login return URL
}
```

**Getting Tebex API Keys**

1. Log in to [Tebex Creator Panel](https://creator.tebex.io/developers/api-keys)
2. Go to **Developers > API Keys** section
3. Copy the following information:
   * **Project ID**: Your project number
   * **Private API Key**: Your private API key
   * **Public Token**: Your public token

> ⚠️ **Security Warning**: Never share your `privateKey` and `publicToken` publicly!

#### General Settings

Edit the `shared/conf.lua` file:

```lua
lang = {}
qadr_tebex_shop_lang = "en"  -- Language: "en" or "tr"
qadr_tebex_shop_payment_timeout = 5  -- Payment timeout (minutes)
```

**Language Settings**

The script supports the following languages:

* `en` - English
* `tr` - Turkish

You can create a new file in the `lang/` folder to add a new language.

***

### 🚀 Usage

#### Basic Usage

To allow players to shop from the store, you need to initiate a checkout process. This is usually triggered by a command, menu, or NPC interaction.

#### Starting Checkout

```lua
RegisterCommand("checkout", function(src, args, raw)
    local packages = {
        ["6301329"] = { -- Tebex Package ID
            addItem = {
                {
                    itemName = "bandage",
                    itemCount = 1,
                    metaData = {}
                },
                {
                    itemName = "water",
                    itemCount = 1,
                    metaData = {}
                }
            },
            addMoney = 5000,
        }
    } 
    TriggerServerEvent("qadr_tebex_shop:createBasket", packages)
end)
```

#### Flow Diagram

```
1. Player uses /checkout command
   ↓
2. Client sends package information to server
   ↓
3. Server creates basket on Tebex
   ↓
4. Browser opens for player to log in
   ↓
5. Player logs in on Tebex
   ↓
6. Products are added to basket
   ↓
7. Player makes payment
   ↓
8. Server verifies payment
   ↓
9. Rewards are automatically given to player
```

***

### 📚 API Reference

#### Client-Side Events

**`qadr_tebex_shop:changestatus`**

Updates payment status and changes UI.

**Parameters:**

```lua
{
    status = "pending" | "success" | "Error" | "firstOpening",
    text = "Error message",  -- Only for Error status
    base_price = 0.00,       -- Total price
    ident = "basket_ident",  -- Basket ID
    user = "username",       -- Username
    rewards = {}             -- Reward list
}
```

**`qadr_tebex_shop:paymentSuccess`**

Triggered when payment is successful.

**Parameters:**

```lua
basket_data = {
    country = "TR",
    currency = "USD",
    username = "buyer_name",
    email = "buyer@email.com",
    base_price = 10.00,
    total_price = 10.00,
    complete = true,
    packages = {...}
}
```

#### NUI Callbacks

**`closePanel`**

Closes the payment panel and cancels the transaction.

```javascript
fetch(`https://${GetParentResourceName()}/closePanel`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({})
});
```

***

### 💡 Examples

#### Example 1: Simple Single Package Sale

```lua
RegisterCommand("buygold", function()
    local packages = {
        ["6301329"] = {
            addItem = {
                {itemName = "gold", itemCount = 10, metaData = {}}
            },
            addMoney = 0
        }
    }
    TriggerServerEvent("qadr_tebex_shop:createBasket", packages)
end)
```

#### Example 2: Multi-Package Sale

```lua
RegisterCommand("buystarter", function()
    local packages = {
        ["6301329"] = {  -- Starter Package
            addItem = {
                {itemName = "water", itemCount = 5, metaData = {}},
                {itemName = "bread", itemCount = 5, metaData = {}},
                {itemName = "bandage", itemCount = 3, metaData = {}}
            },
            addMoney = 100
        },
        ["6301327"] = {  -- Extra Bonus
            addItem = {
                {itemName = "rope", itemCount = 1, metaData = {}}
            },
            addMoney = 50
        }
    }
    TriggerServerEvent("qadr_tebex_shop:createBasket", packages)
end)
```

#### Example 3: Money Only

```lua
RegisterCommand("buymoney", function()
    local packages = {
        ["6301330"] = {
            addItem = {},
            addMoney = 10000
        }
    }
    TriggerServerEvent("qadr_tebex_shop:createBasket", packages)
end)
```

#### Example 4: Item with Metadata

```lua
RegisterCommand("buyweapon", function()
    local packages = {
        ["6301331"] = {
            addItem = {
                {
                    itemName = "weapon_pistol",
                    itemCount = 1,
                    metaData = {
                        durability = 100,
                        ammo = 50,
                        quality = "legendary"
                    }
                }
            },
            addMoney = 0
        }
    }
    TriggerServerEvent("qadr_tebex_shop:createBasket", packages)
end)
```

#### Example 5: Menu Integration

```lua
-- With MenuAPI or similar menu system
function OpenTebexShop()
    local elements = {
        {label = "Starter Package - $5.00", value = "starter"},
        {label = "Gold Package - $10.00", value = "gold"},
        {label = "VIP Package - $25.00", value = "vip"}
    }
    
    MenuData.Open('default', GetCurrentResourceName(), 'tebex_shop', {
        title = "Tebex Store",
        align = "top-left",
        elements = elements
    }, function(data, menu)
        if data.current.value == "starter" then
            TriggerServerEvent("qadr_tebex_shop:createBasket", {
                ["6301329"] = {
                    addItem = {{itemName = "water", itemCount = 5}},
                    addMoney = 100
                }
            })
        elseif data.current.value == "gold" then
            -- Gold package code
        end
        menu.close()
    end)
end

RegisterCommand("shop", function()
    OpenTebexShop()
end)
```

#### Example 6: Listening to Payment Success Event

```lua
RegisterNetEvent("qadr_tebex_shop:paymentSuccess")
AddEventHandler("qadr_tebex_shop:paymentSuccess", function(basket_data)
    -- You can perform custom operations
    print("✅ Payment successful!")
    print("User: " .. basket_data.username)
    print("Total: $" .. basket_data.total_price)
    
    -- Example: Thank you message to player
    TriggerEvent("redem_roleplay:showNotification", {
        type = "success",
        text = "Your purchase has been completed! Thank you.",
        time = 5000
    })
    
    -- Discord webhook notification
    TriggerServerEvent("sendDiscordWebhook", {
        username = basket_data.username,
        amount = basket_data.total_price
    })
end)
```

***

### 🔧 Troubleshooting

#### Common Errors

**1. "Code Used" Error**

**Cause:** Transaction ID has been used before.

**Solution:**

* A new transaction ID is generated for each payment
* Check database: `SELECT * FROM qadr_tebex_shop_orders WHERE ordernumber = 'TXN_ID'`

**2. "Code Wrong" Error**

**Cause:** Transaction ID is invalid or payment is not completed.

**Solution:**

* Verify payment is completed from Tebex panel
* Make sure the transaction ID is correct

**3. Item Not Given**

**Cause:** Item name or metadata is incorrect.

**Solution:**

```lua
-- Correct usage
{itemName = "water", itemCount = 1, metaData = {}}

-- Wrong usage
{item = "water", count = 1}  -- ❌ Wrong key names
```

**4. Database Error**

**Cause:** Table not created or connection issue.

**Solution:**

* Make sure MySQL service is running
* Run table creation SQL manually
* Check `server.log` file

***

### ❓ FAQ (Frequently Asked Questions)

#### Technical Questions

**Q: Is it compatible with other inventory systems?** A: No, it currently only works with RedEM Roleplay inventory system.

**Q: Can a player start multiple checkouts?** A: No, a player can only have one checkout process at a time.

**Q: Can I change the payment timeout duration?** A: Yes, change the `qadr_tebex_shop_payment_timeout` value in `shared/conf.lua` file.

#### Security Questions

**Q: Are my API keys safe?** A: Yes, API keys are only used server-side and are never sent to the client.

**Q: Can fake payments be made?** A: No, all payments are verified through Tebex API and recorded in the database.

**Q: Can transaction IDs be reused?** A: No, each transaction ID can only be used once. The system performs duplicate checks.

#### Customization Questions

**Q: Can I add a new language?** A: Yes, you can create a new language file in the `lang/` folder:

```lua
lang["de"] = {
    codeUsed = "Code verwendet",
    codeWrong = "Code falsch",
    -- ... other translations
}
```

Then in `shared/conf.lua` file:

```lua
qadr_tebex_shop_lang = "de"
```

***

### 📞 Support and Contact

#### Bug Report

If you find a bug, please report it with the following information:

1. **Server.log** output
2. **Step-by-step** description of how the error occurs
3. **Expected** behavior vs **actual** behavior
4. Server **version** and **other scripts used**

***

### 📝 License and Copyright

This script uses the Tebex Limited API. You must comply with Tebex's terms of service.

**Important Notes:**

* You cannot redistribute this script without permission
* You cannot modify files under escrow protection
* All payment transactions are managed by Tebex Limited

***

### 🔄 Version History

#### v1.0.0

* ✅ First stable release
* ✅ Basic payment system
* ✅ Multi-package support
* ✅ TR/EN language support

***

**Last Update:** November 4, 2025 **Document Version:** 1.0.0