Withdraw API

---

Overview

The Withdraw API enables external plugins to interact with PhantomDungeons withdraw system. Create withdraw notes, validate and redeem withdraw items, perform player withdrawals, inspect configured currencies, and react to the module's lifecycle events.

---

Getting Started

Follow these steps to integrate with the withdraw system.

1

Get the Instance

Access the singleton API instance from the static provider.

Example.java

import me.fergs.phantomdungeons.modules.withdraw.api.WithdrawAPI;

// Get the singleton instance
WithdrawAPI withdrawAPI = WithdrawAPI.get();

Note: Ensure PhantomDungeons is listed as a dependency in your plugin.yml so the Withdraw module is initialized before your plugin loads.

2

Cache for Performance

Store the API instance in your plugin for easier repeated access.

MyPlugin.java

import me.fergs.phantomdungeons.modules.withdraw.api.WithdrawAPI;
import me.fergs.phantomdungeons.modules.withdraw.api.WithdrawAPIProvider;

public class MyPlugin extends JavaPlugin {
    private WithdrawAPI withdrawAPI;
    
    @Override
    public void onEnable() {
        if (!WithdrawAPIProvider.isAvailable()) {
            getLogger().warning("Withdraw module not loaded!");
            return;
        }

        this.withdrawAPI = WithdrawAPI.get();
        getLogger().info("Hooked into withdraw!");
    }
    
    public WithdrawAPI getWithdrawAPI() {
        return withdrawAPI;
    }
}

3

Safe Availability Checks

WithdrawAPI exposes get(), while availability is checked through WithdrawAPIProvider.

ExampleCheck.java

import me.fergs.phantomdungeons.modules.withdraw.api.WithdrawAPI;
import me.fergs.phantomdungeons.modules.withdraw.api.WithdrawAPIProvider;

if (!WithdrawAPIProvider.isAvailable()) {
    getLogger().warning("Withdraw API not available!");
    return;
}

WithdrawAPI api = WithdrawAPI.get();

---

Core Operations

1

Checking Available Currencies

Configured withdraw currencies are cached in memory and can be queried synchronously.

Set<String> currencies = withdrawAPI.getAvailableCurrencies();
boolean canWithdrawMoney = withdrawAPI.canWithdraw("money");
boolean enabled = withdrawAPI.isEnabled();

2

Reading Limits

Each currency can define its own minimum and maximum withdraw amounts.

double minMoney = withdrawAPI.getMinAmount("money");
double maxMoney = withdrawAPI.getMaxAmount("money");

3

Creating Withdraw Items

Generate a withdraw note manually without deducting currency.

ItemStack note = withdrawAPI.createWithdrawItem("money", 1000.0);
if (note != null) {
    player.getInventory().addItem(note);
}

If you want to provide your own UUID, use the overload with a custom identifier.

UUID customId = UUID.randomUUID();
ItemStack note = withdrawAPI.createWithdrawItem("money", 5000.0, customId);

4

Reading Withdraw Item Metadata

Use the API to inspect items instead of reading NBT yourself.

if (!withdrawAPI.isWithdrawItem(item)) {
    return;
}

String currencyId = withdrawAPI.getCurrencyFromItem(item);
double amount = withdrawAPI.getAmountFromItem(item);
UUID withdrawUuid = withdrawAPI.getUuidFromItem(item);

5

Withdrawing Currency

The withdraw flow is asynchronous. It validates config, bounds, balance, cooldown, and inventory space before giving the item.

withdrawAPI.withdraw(player, "money", 2500.0)
    .thenAccept(success -> {
        if (!success) {
            player.sendMessage("failed");
            return;
        }

        Bukkit.getScheduler().runTask(plugin, () ->
            player.sendMessage("done"));
    });

Tip: This API returns only true / false. If you need detailed fail reasons, you would need to integrate deeper with the internal manager rather than the public API.

6

Redeeming Withdraw Items

Redeeming is also asynchronous and credits the stored amount back into the player's economy balance.

withdrawAPI.redeem(player, item)
    .thenAccept(success -> {
        if (success) {
            Bukkit.getScheduler().runTask(plugin, () ->
                player.sendMessage("Withdraw note redeemed!"));
        }
    });

---

Cooldown Access

1

Checking Cooldowns

Use these helpers if your plugin needs to preview or enforce withdraw pacing.

if (withdrawAPI.isOnCooldown(player)) {
    int remainingSeconds = withdrawAPI.getRemainingCooldown(player);
    player.sendMessage("You must wait " + remainingSeconds + "s before withdrawing again.");
}

---

Config & Item Behavior

The public API intentionally stays small, but it maps directly to the withdraw item configs in withdraw/items/*.yml.

1

Configured Item Variables

Generated withdraw items can render placeholders such as:

• %amount%

• %formatted_amount%

• %currency%

• %signer%

• %source%

• %date%

Example item config:

display-name: '&6&l$%amount% &eWithdraw Note'
lore:
  - ' &6 → &eAmount: &f$%formatted_amount%'
  - ' &6 → &eSigned by: &f%signer%'
  - ' &6 → &eDate: &f%date%'
material: PAPER
glow: true

2

Configured Bounds

Per-currency configs can override global withdraw limits.

# withdraw/items/money.yml
min-amount: 100.0
max-amount: 10000000.0

Those values are what getMinAmount(...) and getMaxAmount(...) expose.

---

Events API

The withdraw module exposes two Bukkit events for external integrations.

1

WithdrawCreatedEvent

Fired when a player creates a withdraw item. The event includes the player, currency ID, amount, and generated withdraw UUID.

@EventHandler
public void onWithdrawCreated(WithdrawCreatedEvent event) {
    if (event.getCurrencyId().equalsIgnoreCase("money") && event.getAmount() >= 1_000_000) {
        event.getPlayer().sendMessage("Large withdraw detected!");
    }
}

Available data:

Method	Returns
getPlayer()	The player creating the withdraw item
getCurrencyId()	Withdraw currency ID
getAmount()	Withdraw amount
getWithdrawUuid()	Unique identifier stored on the created note
isCancelled() / setCancelled()	Cancellation state

2

WithdrawRedeemedEvent

Fired when a player redeems a withdraw note back into balance.

@EventHandler
public void onWithdrawRedeemed(WithdrawRedeemedEvent event) {
    event.getPlayer().sendMessage(
        "Redeemed " + event.getAmount() + " of " + event.getCurrencyId()
    );
}

Available data:

Method	Returns
getPlayer()	The redeeming player
getCurrencyId()	Currency stored in the note
getAmount()	Redeemed amount
getWithdrawUuid()	Note UUID
getItem()	The ItemStack being redeemed
isCancelled() / setCancelled()	Cancellation state

Cancellation note: Both events implement Cancellable, but the manager dispatches them through the Bukkit scheduler during the async flow. If you rely on cancellation to block a withdraw or redeem, test that behavior on your server setup.

---

FAQ

Are withdraw operations async?

Yes. withdraw(...) and redeem(...) return CompletableFuture<Boolean> because they perform validation, economy access, and inventory work through the module's async flow.

Can I create a withdraw note without charging a player?

Yes. createWithdrawItem(...) only builds the item. It does not remove balance.

How do I check whether an item is a real withdraw note?

Use isWithdrawItem(item) and then inspect it with getCurrencyFromItem(...), getAmountFromItem(...), and getUuidFromItem(...).

What happens if the currency is not configured for withdraw?

canWithdraw(...) returns false, and createWithdrawItem(...) returns null.

Can I access signer or source metadata from the public API?

Not directly through WithdrawAPI. The public API exposes currency, amount, and UUID. Extra metadata like signer, source, and timestamp is handled internally by the module.

Do I need to parse NBT manually?

No. Use the provided item helper methods from WithdrawAPI instead of reading item metadata yourself.

---