Documentation EpicPay

1. Introduction

The EpicPay public API lets you show your shop offer on your own website, launcher or bot, create an order and check its status. Base URL: https://api.epicpay.eu/v1. Responses are JSON, amounts are in Polish złoty (PLN).

• Limit: 120 requests per minute per IP address. Above it the API returns 429 - wait a moment and try again.
• An interactive version of the docs (Swagger) where you can send requests is at https://api.epicpay.eu/docs, and the OpenAPI specification at https://api.epicpay.eu/v1/openapi.json.
• You point to a shop with its UUID ({uuid} in the path). You find it in the panel: Shop settings → Plugin (shop_uuid).

2. Keys and authentication

Most endpoints (shop offer, orders, vouchers) need no key - they return only data a player can see in the shop anyway. Generate a key again in the panel if it leaks; the old one stops working.

curl -H "Authorization: Bearer YOUR_PUBLIC_API_KEY" \
     https://api.epicpay.eu/v1/shops/SHOP-UUID/transactions

3. Selling from your own website

1. Get the products: GET /shops/{uuid}/packages (or the products of one game mode).
2. Get the enabled gateways: GET /shops/{uuid}/gateways.
3. Create an order: POST /shops/{uuid}/orders with package_id, the player nickname (nickname) and the gateway (gateway).
4. Redirect the player to the returned payment_url.
5. Check the status: GET /shops/{uuid}/orders/{token} or receive webhooks. Once paid, the plugin delivers the purchase on your server.

const res = await fetch('https://api.epicpay.eu/v1/shops/SHOP-UUID/orders', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
  body: JSON.stringify({ package_id: 42, nickname: 'Steve123', gateway: 'cashbill' }),
});
const { data } = await res.json();
location.href = data.payment_url;

4. Public endpoints

All endpoints below use the base URL https://api.epicpay.eu/v1.

5. Shop information - GET /shops/{uuid}

GET https://api.epicpay.eu/v1/shops/{uuid}

Returns public shop information: name, logo, colour settings, social media links and active payment gateways.

Parameters

{
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "EpicCraft Store",
    "logo_url": "https://r2.epicpay.eu/logos/abc.png",
    "server_ip": "play.epiccraft.pl",
    "accent_color": "#FF6B00",
    "button_text_color": "#FFFFFF",
    "discord_url": "https://discord.gg/epiccraft",
    "youtube_url": null,
    "tiktok_url": null,
    "terms_url": null,
    "gateways": [
      {
        "type": "cashbill",
        "label": "CashBill"
      }
    ]
  }
}

6. Category list - GET /shops/{uuid}/categories

GET https://api.epicpay.eu/v1/shops/{uuid}/categories

Returns all visible categories (game modes) of the shop in creation order.

Parameters

{
  "data": [
    {
      "id": 1,
      "name": "SkyBlock",
      "description": "Rangi i przedmioty na SkyBlock",
      "icon": "🏝️",
      "slug": "skyblock"
    },
    {
      "id": 2,
      "name": "Survival",
      "description": "Tryb przetrwania",
      "icon": "🌲",
      "slug": "survival"
    }
  ]
}

7. Products in a category - GET /shops/{uuid}/categories/{categoryId}/packages

GET https://api.epicpay.eu/v1/shops/{uuid}/categories/{categoryId}/packages

Returns the category and its visible products. categoryId can be a numeric ID or a text slug.

Parameters

8. All shop products - GET /shops/{uuid}/packages

GET https://api.epicpay.eu/v1/shops/{uuid}/packages

Returns all visible products from every category of the shop.

Parameters

9. Active payment gateways - GET /shops/{uuid}/gateways

GET https://api.epicpay.eu/v1/shops/{uuid}/gateways

Returns the active payment gateways of the shop. Use it to show the available payment methods on your website.

Important: The response never contains credentials (API keys, secrets) - only public metadata.

Parameters

{
  "data": [
    {
      "type": "cashbill",
      "label": "CashBill",
      "enabled": true,
      "created_at": "2025-01-15T10:30:00+01:00"
    }
  ]
}

10. Shop announcements - GET /shops/{uuid}/announcements

GET https://api.epicpay.eu/v1/shops/{uuid}/announcements

Returns the active shop announcements, newest first.

Parameters

11. Top players - GET /shops/{uuid}/top-players

GET https://api.epicpay.eu/v1/shops/{uuid}/top-players

Returns the 10 players who spent the most in the shop.

Parameters

12. Recent purchases - GET /shops/{uuid}/recent-purchases

GET https://api.epicpay.eu/v1/shops/{uuid}/recent-purchases

Returns the 20 most recently completed transactions in the shop.

Parameters

13. Create an order - POST /shops/{uuid}/orders

POST https://api.epicpay.eu/v1/shops/{uuid}/orders

Creates a new order and returns the payment page URL. Redirect the player to payment_url to complete the payment.

Flow:

1. Get the product list (GET /shops/{uuid}/packages)
2. Create an order with package_id, the player nickname and gateway
3. Redirect the player to the returned payment_url
4. After payment check the status with GET /shops/{uuid}/orders/{token}

Parameters

Request body (JSON)

{
  "data": {
    "order_token": "550e8400-e29b-41d4-a716-446655440111",
    "status": "pending",
    "package_name": "Ranga VIP",
    "player_nickname": "Steve123",
    "price": 19.99,
    "payment_url": "https://pay.epicpay.eu/p/550e8400-e29b-41d4-a716-446655440111"
  }
}

14. Order status - GET /shops/{uuid}/orders/{token}

GET https://api.epicpay.eu/v1/shops/{uuid}/orders/{token}

Check the current order status by its token. Possible statuses: - pending - waiting for payment - success - paid and delivered - failed - failed - expired - expired

Parameters

15. Validate a voucher - POST /shops/{uuid}/vouchers/validate

POST https://api.epicpay.eu/v1/shops/{uuid}/vouchers/validate

Checks whether a voucher code is valid for a player and, optionally, for a specific product.

Parameters

Request body (JSON)

{
  "valid": true,
  "message": "Voucher jest ważny - 100% zniżki.",
  "data": {
    "voucher_id": 5,
    "code": "GRATIS2025"
  }
}

16. Shop info + statistics - GET /shops/{uuid}/me

GET https://api.epicpay.eu/v1/shops/{uuid}/me

Requires the Authorization: Bearer <public_api_key> header (Pro plan or higher).

Returns full shop data with financial statistics. Requires Authorization: Bearer <public_api_key> (Pro plan).

Parameters

{
  "data": {
    "uuid": "550e8400-...",
    "name": "EpicCraft Store",
    "stats": {
      "transactions_count": 1240,
      "total_earned": 12489.5,
      "categories_count": 4,
      "packages_count": 32
    }
  }
}

17. Transaction list - GET /shops/{uuid}/transactions

GET https://api.epicpay.eu/v1/shops/{uuid}/transactions

Requires the Authorization: Bearer <public_api_key> header (Pro plan or higher).

Returns a paginated list of shop transactions. Requires Authorization: Bearer <public_api_key> (Pro plan).

Parameters

18. Webhooks

Webhooks (Business plan; set them up in Shop settings → Webhooks) send shop events to your app address with POST and a JSON body. The test button in the panel sends a test event.

{
  "event": "purchase.completed",
  "sent_at": "2026-10-21T12:00:00+00:00",
  "shop": {
    "uuid": "9b1c6f1e-…",
    "name": "EpicCraft"
  },
  "transaction": {
    "id": 1234,
    "player": "Steve123",
    "package_id": 42,
    "package": "Ranga VIP",
    "quantity": 1,
    "price": 19.99,
    "currency": "PLN",
    "method": "cashbill",
    "created_at": "2026-10-21T11:59:30+00:00",
    "delivered_at": null
  }
}

Answer with a 2xx code within 10 seconds. On a 5xx or 429 answer EpicPay retries after 10 s, 1 min and 5 min. Always check the signature:

$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, $webhookSecret);
if (!hash_equals($expected, $_SERVER['HTTP_X_EPICPAY_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}
$event = json_decode($body, true);

import crypto from 'node:crypto';

const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-epicpay-signature'] ?? ''));

19. Plugin API (deliveries)

The EpicPay plugin uses these endpoints. They are described here for your own integrations, e.g. a plugin for another server engine. Authentication: the shop_uuid and secret parameters (the shop api_secret). Base URL: https://api.epicpay.eu.

GET https://api.epicpay.eu/deliveries/pending?shop_uuid=UUID&secret=API_SECRET[&mode_uuid=MODE_UUID]

{
  "deliveries": [
    {
      "id": 1234,
      "player_nickname": "Steve123",
      "package_name": "Ranga VIP",
      "quantity": 1,
      "commands": [
        "lp user Steve123 parent addtemp vip 30d"
      ],
      "purchased_at": "2026-10-21T11:59:30.000000Z"
    }
  ]
}

The commands already have {player} and {quantity} filled in. With mode_uuid you get only the purchases of one game mode. After running the commands, confirm the delivery - otherwise the purchase comes back in the next fetch:

POST https://api.epicpay.eu/deliveries/1234/confirm?shop_uuid=UUID&secret=API_SECRET
→ {"ok": true, "confirmed": 1}

POST https://api.epicpay.eu/deliveries/confirm?shop_uuid=UUID&secret=API_SECRET[&mode_uuid=MODE_UUID]
→ confirms all pending ones (up to 500 at once)

20. Errors

API errors are JSON with an error field (code) and message (description in Polish), e.g. {"error": "shop_not_found", "message": "Sklep o podanym UUID nie istnieje."}.