Custom Payment Options

Available in Dealerships v2.0 or newer.

This guide explains how to add custom payment methods to your dealership, such as VIP Coins, Tokens, or any other currency from your server.

---

Quick Start

1. Open framework/sv-currencies.lua

2. Scroll to the bottom of the file

3. Find the commented example (-- VIP Coins)

4. Copy and modify it for your currency

---

Step-by-Step Guide

Step 1: Open the File

Open framework/sv-currencies.lua in any text editor.

Scroll all the way to the bottom. You'll see a commented-out example that looks like this:

-- ============================================================================
-- EXAMPLE: VIP Coins Custom Currency
-- Uncomment and modify this to add your own custom currency!
-- ============================================================================

-- Currencies.Server.Register({
--   id = "vip_coins",
--   ...
-- })

Step 2: Copy the Example

Copy the entire example block and paste it below. Remove the -- comment markers to activate it.

Step 3: Fill in the Fields

Here's what each field means:

Field	Required?	What it does
id	✅ Yes	Unique identifier (e.g., "vip_coins", "tokens")
label	✅ Yes	Display name shown to players (e.g., "VIP Coins")
format	✅ Yes	How to display amounts (see examples below)
conversionRate	✅ Yes*	How much 1 unit is worth in dollars
flatCost	❌ No	Fixed cost per purchase (overrides conversionRate)
allowFinance	✅ Yes	Can players finance with this currency?
fetchBalance	✅ Yes	Function to get player's balance
addBalance	✅ Yes	Function to add to player's balance
removeBalance	✅ Yes	Function to remove from player's balance

*Required unless using flatCost

---

Understanding the Fields

format - How Prices Are Displayed

The %s is replaced with the number:

Format	Example Output
"$%s"	$1,500
"%s coins"	1,500 coins
"%s Tokens"	1,500 Tokens
"💎 %s"	💎 1,500

conversionRate - Currency Value

This determines how much 1 unit of your currency is worth in base dollars:

Rate	Meaning	$50,000 car costs...
1	1 coin = $1	50,000 coins
100	1 coin = $100	500 coins
10000	1 coin = $10,000	5 coins
50000	1 coin = $50,000	1 coin

flatCost - Fixed Price Per Purchase (Optional)

If you want every vehicle to cost the same amount regardless of its price, use flatCost:

flatCost = 1,  -- Every vehicle costs 1 token

With flatCost = 1:

• A $10,000 car costs 1 token

• A $500,000 car costs 1 token

Note: When using flatCost, set allowFinance = false (you can't split 1 token into payments!)

allowFinance - Financing Support

• true = Players can use this currency for financed purchases

• false = Full payment only

Must be false if using flatCost

---

Balance Functions

You need to tell the system how to check and modify player balances. This depends on how your currency is stored.

Example: Using a Database Table

If you store coins in a player_coins table:

fetchBalance = function(src)
  local identifier = Framework.Server.GetPlayerIdentifier(src)
  local result = MySQL.scalar.await(
    "SELECT coins FROM player_coins WHERE identifier = ?",
    { identifier }
  )
  return tonumber(result) or 0
end,

addBalance = function(src, amount)
  local identifier = Framework.Server.GetPlayerIdentifier(src)
  MySQL.update.await(
    "UPDATE player_coins SET coins = coins + ? WHERE identifier = ?",
    { amount, identifier }
  )
  return true
end,

removeBalance = function(src, amount)
  local identifier = Framework.Server.GetPlayerIdentifier(src)
  MySQL.update.await(
    "UPDATE player_coins SET coins = coins - ? WHERE identifier = ?",
    { amount, identifier }
  )
  return true
end,

Example: Using an Export from Another Resource

If another script manages your currency:

fetchBalance = function(src)
  return exports["my-coin-system"]:GetPlayerCoins(src) or 0
end,

addBalance = function(src, amount)
  return exports["my-coin-system"]:AddCoins(src, amount)
end,

removeBalance = function(src, amount)
  return exports["my-coin-system"]:RemoveCoins(src, amount)
end,

---

Complete Examples

Example 1: VIP Coins (Conversion Rate)

1 VIP Coin = $10,000

Currencies.Server.Register({
  id = "vip_coins",
  label = "VIP Coins",
  format = "%s coins",
  conversionRate = 10000,
  allowFinance = false,

  fetchBalance = function(src)
    return exports["vip-system"]:GetCoins(src) or 0
  end,

  addBalance = function(src, amount)
    exports["vip-system"]:AddCoins(src, amount)
    return true
  end,

  removeBalance = function(src, amount)
    exports["vip-system"]:RemoveCoins(src, amount)
    return true
  end,
})

Example 2: Car Tokens (Flat Cost)

1 Token = 1 Vehicle (any price)

Currencies.Server.Register({
  id = "car_token",
  label = "Car Token",
  format = "%s Token(s)",
  conversionRate = 1,
  flatCost = 1,
  allowFinance = false,

  fetchBalance = function(src)
    local identifier = Framework.Server.GetPlayerIdentifier(src)
    local result = MySQL.scalar.await(
      "SELECT tokens FROM player_tokens WHERE identifier = ?",
      { identifier }
    )
    return tonumber(result) or 0
  end,

  addBalance = function(src, amount)
    local identifier = Framework.Server.GetPlayerIdentifier(src)
    MySQL.update.await(
      "UPDATE player_tokens SET tokens = tokens + ? WHERE identifier = ?",
      { amount, identifier }
    )
    return true
  end,

  removeBalance = function(src, amount)
    local identifier = Framework.Server.GetPlayerIdentifier(src)
    MySQL.update.await(
      "UPDATE player_tokens SET tokens = tokens - ? WHERE identifier = ?",
      { amount, identifier }
    )
    return true
  end,
})

Example 3: Premium Points (with Financing)

1 Point = $1,000, supports financing

Currencies.Server.Register({
  id = "premium_points",
  label = "Premium Points",
  format = "%s pts",
  conversionRate = 1000,
  allowFinance = true,

  fetchBalance = function(src)
    return exports["premium-shop"]:GetPoints(src) or 0
  end,

  addBalance = function(src, amount)
    exports["premium-shop"]:AddPoints(src, amount)
    return true
  end,

  removeBalance = function(src, amount)
    exports["premium-shop"]:RemovePoints(src, amount)
    return true
  end,

  -- Required for financing: offline balance functions
  fetchBalanceOffline = function(identifier)
    local result = MySQL.scalar.await(
      "SELECT points FROM premium_points WHERE identifier = ?",
      { identifier }
    )
    return tonumber(result) or 0
  end,

  removeBalanceOffline = function(identifier, amount)
    MySQL.update.await(
      "UPDATE premium_points SET points = points - ? WHERE identifier = ?",
      { amount, identifier }
    )
    return true
  end,
})

---

Enabling Your Currency at a Dealership

After adding your currency, you need to enable it for each dealership:

1. Open the Admin Panel (/dealership-admin)

2. Go to Locations

3. Click on a dealership

4. Go to the Advanced tab

5. Enable your new payment method in the Payment Methods section

6. Save

---

Troubleshooting

Currency not showing in the dealership

• Make sure you've enabled the currency in the dealership's Advanced settings

• Restart the resource after adding a new currency

Wrong price showing

• Check your conversionRate value

• If using flatCost, make sure it's set correctly

Payment fails even with enough balance

• Check your fetchBalance function returns the correct number

• Check your removeBalance function returns true on success

• Check the server console for errors

Financing doesn't work with my currency

• Make sure allowFinance = true

• Make sure flatCost is NOT set (flat cost currencies can't be financed)

• Add fetchBalanceOffline and removeBalanceOffline functions for automatic payments