Dokumentacja EpicPay

1. Wprowadzenie

Publiczne API EpicPay pozwala pobrać ofertę sklepu na własną stronę, do launchera albo bota, utworzyć zamówienie i sprawdzić jego status. Adres bazowy: https://api.epicpay.eu/v1. Odpowiedzi są w formacie JSON, kwoty w złotych (PLN).

• Limit: 120 zapytań na minutę z jednego adresu IP. Po przekroczeniu API zwraca 429 - poczekaj chwilę i spróbuj ponownie.
• Interaktywną wersję dokumentacji (Swagger) z możliwością wysłania zapytania znajdziesz pod https://api.epicpay.eu/docs, a specyfikację OpenAPI pod https://api.epicpay.eu/v1/openapi.json.
• Sklep wskazujesz jego UUID ({uuid} w ścieżce). Znajdziesz go w panelu: Ustawienia sklepu → Plugin (shop_uuid).

2. Klucze i uwierzytelnianie

Większość endpointów (oferta sklepu, zamówienia, vouchery) nie wymaga klucza - zwracają tylko dane, które gracz i tak widzi w sklepie. Klucze generujesz ponownie w panelu, gdy wyciekną; stary przestaje wtedy działać.

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

3. Zakup z własnej strony

1. Pobierz produkty: GET /shops/{uuid}/packages (albo produkty jednego trybu gry).
2. Pobierz włączone bramki: GET /shops/{uuid}/gateways.
3. Utwórz zamówienie: POST /shops/{uuid}/orders z package_id, nickiem gracza (nickname) i bramką (gateway).
4. Przekieruj gracza na zwrócony payment_url.
5. Sprawdzaj status: GET /shops/{uuid}/orders/{token} albo odbieraj webhooki. Po opłaceniu plugin sam wyda zakup na serwerze.

const res = await fetch('https://api.epicpay.eu/v1/shops/UUID-SKLEPU/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. Endpointy publiczne

Wszystkie endpointy poniżej mają adres bazowy https://api.epicpay.eu/v1.

5. Informacje o sklepie - GET /shops/{uuid}

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

Zwraca publiczne informacje o sklepie: nazwę, logo, konfigurację kolorów, linki social media i aktywne bramki płatności.

Parametry

{
  "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. Lista kategorii - GET /shops/{uuid}/categories

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

Zwraca wszystkie widoczne kategorie (tryby) sklepu posortowane chronologicznie.

Parametry

{
  "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. Produkty w kategorii - GET /shops/{uuid}/categories/{categoryId}/packages

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

Zwraca informacje o kategorii oraz listę widocznych produktów. categoryId może być numerycznym ID lub slugiem tekstowym.

Parametry

8. Wszystkie produkty sklepu - GET /shops/{uuid}/packages

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

Zwraca wszystkie widoczne produkty ze wszystkich kategorii danego sklepu.

Parametry

9. Aktywne bramki płatności - GET /shops/{uuid}/gateways

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

Zwraca listę aktywnych bramek płatności dostępnych w sklepie. Używaj tego endpointu aby dynamicznie wyświetlać dostępne metody płatności na swojej stronie.

Ważne: Odpowiedź nigdy nie zawiera danych uwierzytelniających (kluczy API, sekretów) - tylko publiczne metadane.

Parametry

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

10. Ogłoszenia sklepu - GET /shops/{uuid}/announcements

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

Zwraca aktywne ogłoszenia sklepu posortowane od najnowszego.

Parametry

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

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

Zwraca 10 graczy z największymi wydatkami w sklepie.

Parametry

12. Ostatnie zakupy - GET /shops/{uuid}/recent-purchases

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

Zwraca 20 ostatnio zakończonych transakcji w sklepie.

Parametry

13. Utwórz zamówienie - POST /shops/{uuid}/orders

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

Tworzy nowe zamówienie i zwraca URL do strony płatności. Gracz powinien zostać przekierowany na payment_url aby dokończyć płatność.

Przepływ:

1. Pobierz listę produktów (GET /shops/{uuid}/packages)
2. Utwórz zamówienie podając package_id, nickname gracza i gateway
3. Przekieruj gracza na zwrócony payment_url
4. Po płatności sprawdź status przez GET /shops/{uuid}/orders/{token}

Parametry

Treść zapytania (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. Status zamówienia - GET /shops/{uuid}/orders/{token}

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

Sprawdź aktualny status zamówienia po tokenie. Możliwe statusy: - pending - oczekuje na płatność - success - opłacone i dostarczone - failed - nieudane - expired - wygasło

Parametry

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

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

Sprawdza czy podany kod vouchera jest ważny dla danego gracza i opcjonalnie dla konkretnego produktu.

Parametry

Treść zapytania (JSON)

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

16. Info o sklepie + statystyki - GET /shops/{uuid}/me

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

Wymaga nagłówka Authorization: Bearer <public_api_key> (pakiet Pro lub wyższy).

Zwraca pełne dane sklepu wraz ze statystykami finansowymi. Wymaga Authorization: Bearer <public_api_key> (subskrypcja Pro).

Parametry

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

17. Lista transakcji - GET /shops/{uuid}/transactions

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

Wymaga nagłówka Authorization: Bearer <public_api_key> (pakiet Pro lub wyższy).

Zwraca paginowaną listę transakcji sklepu. Wymaga Authorization: Bearer <public_api_key> (subskrypcja Pro).

Parametry

18. Webhooki

Webhooki (pakiet Business; ustawiasz je w Ustawieniach sklepu → Webhooki) wysyłają zdarzenia ze sklepu na adres Twojej aplikacji metodą POST z treścią JSON. Przycisk testu w panelu wysyła zdarzenie test.

{
  "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
  }
}

Odpowiedz kodem 2xx w ciągu 10 sekund. Przy błędzie 5xx albo 429 EpicPay ponowi wysyłkę po 10 s, 1 min i 5 min. Zawsze sprawdzaj podpis:

$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, $sekretWebhookow);
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. API pluginu (dostawy)

Z tych endpointów korzysta plugin EpicPay. Opisujemy je dla własnych integracji, np. pluginu na inny silnik serwera. Uwierzytelnienie: parametry shop_uuid i secret (api_secret sklepu). Adres bazowy: https://api.epicpay.eu.

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

{
  "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"
    }
  ]
}

Komendy mają już podstawione {player} i {quantity}. Z mode_uuid dostajesz tylko zakupy z jednego trybu gry. Po wykonaniu komend potwierdź dostawę - inaczej zakup wróci w kolejnym pobraniu:

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=UUID_TRYBU]
→ potwierdza wszystkie oczekujące (do 500 naraz)

20. Błędy

Błędy API mają postać JSON z polem error (kod) i message (opis po polsku), np. {"error": "shop_not_found", "message": "Sklep o podanym UUID nie istnieje."}.