Skip to main content

Tutorial: Creating and processing transactions

This article will describe the lifecycle of a transaction as it's created and processed by a Spigot plugin written in Java. For an overview of how $WRLD payments work, refer to this section.

Creating plugin, initializing wallet

public class WRLDPaymentsCommands extends JavaPlugin {
private static WRLDPaymentsCommands plugin;
private static WalletAPI wallet;

public static WRLDPaymentsCommands getInstance() {
return plugin;
public static WalletAPI getPayments() {
return wallet;

public void onEnable() {
plugin = this;
wallet = new WalletAPI();

// We create this event handler below
getServer().getPluginManager().registerEvents(new PlayerTransactEventListener(), this);


Defining transaction types and payloads

Transactions are defined by a payload class which is automatically associated with the transaction and sent back to the server when the player completes payment. Payload classes serve two purposes:

  1. They allow the server to differentiate between multiple transaction types.
  2. Developers can store any arbitrary data they want and associate it with their transaction.
public class PlayerBuyItemPayload {
public ItemStack items;

public PlayerBuyItemPayload(ItemStack items) {
this.items = items;

Creating a payment request

PlayerBuyItemPayload payload = new PlayerBuyItemPayload(new ItemStack(Material.APPLE, 64));
double price = 15.0;
price, Network.POLYGON, "Purchasing an apple", payload
Javadocs for this example

Writing a transaction handler

Incoming transactions are processed by a Spigot event handler like the one below:

public class PlayerTransactEventListener implements Listener {

public void onPlayerTransact(PlayerTransactEvent<?> e) {
if (e.getPayload() instanceof PlayerBuyItemPayload payload) {
e.getPlayer().sendMessage("Transaction complete!");

Player Wallets & Live Payment Testing

If you want to test live payments, you need to connect your wallet that will spend $WRLD to your Minecraft account for NFT Worlds. You can do that through your NFT Worlds account page:

Connecting your wallet allows the NFT Worlds ecosystem to globally recognize your player UUID and the wallet address(es) associated with it. This is how payment receipt & the target player who paid is determined by the wrld payments api.