Przewodnik rozwiązywania problemów

🔴 Płatność nie została wykryta

Objawy: Klient twierdzi, że wysłał płatność, ale nie pojawia się ona w twoim panelu.

Najczęstsze przyczyny:

• Transakcja nie otrzymała jeszcze potwierdzeń (normalne dla nowych transakcji)
• Wysłano nieprawidłową kwotę (niedopłata o ponad 1%)
• Płatność wysłana na zły adres (błąd klienta)
• Przeciążenie sieci opóźniające potwierdzenie

Rozwiązania:

1. Sprawdź transakcję w eksploratorze blockchaina:
   • Bitcoin: blockchair.com/bitcoin
   • Ethereum: etherscan.io
   • Litecoin: blockchair.com/litecoin
2. Sprawdź, czy adres docelowy zgadza się z tym pokazanym w żądaniu płatności GriffNode
3. Poczekaj na potwierdzenia: Większość problemów rozwiązuje się, gdy transakcja otrzyma 1-2 potwierdzenia
4. Jeśli transakcja jest potwierdzona, ale wciąż się nie pojawia: Skontaktuj się z pomocą techniczną, podając identyfikator transakcji

⚠️ Płatność utknęła w stanie „Oczekująca”

Objawy: Płatność jest wyświetlana jako „Oczekująca” dłużej, niż się spodziewano.

Najczęstsze przyczyny:

• Niska opłata transakcyjna powodująca powolne potwierdzanie
• Przeciążenie sieci (zwłaszcza Bitcoina w okresach dużego ruchu)
• Nie osiągnięto jeszcze wymaganej liczby potwierdzeń

Rozwiązania:

1. Sprawdź liczbę potwierdzeń: Przejdź do szczegółów transakcji w panelu
2. Oczekiwane czasy potwierdzeń:
   • BTC: 2-6 potwierdzeń (20-60 minut)
   • ETH: 12-35 potwierdzeń (2-7 minut)
   • LTC/DASH: 4-6 potwierdzeń (10-15 minut)
3. Jeśli płatność utknęła na wiele godzin: Transakcja może mieć niewystarczającą opłatę. Klient może spróbować RBF (Replace-By-Fee) lub CPFP (Child-Pays-For-Parent), jeśli jego portfel to obsługuje
4. Dla sprzedawców: Możesz ręcznie zatwierdzić transakcje o niskiej wartości z 1 potwierdzeniem, jeśli akceptujesz ryzyko

❌ Płatność oznaczona jako „Niedopłacona”

Objawy: Transakcja otrzymana, ale oznaczona jako niedopłacona, status zablokowany.

Najczęstsze przyczyny:

• Portfel klienta nie uwzględnił opłat sieciowych
• Klient ręcznie wpisał kwotę zamiast zeskanować kod QR
• Kurs przeliczeniowy zmienił się pomiędzy utworzeniem faktury a płatnością

Rozwiązania:

1. Sprawdź wysokość niedopłaty: Panel pokazuje dokładny niedobór
2. Jeśli niedobór wynosi < 1%: Możesz ręcznie zatwierdzić transakcję
3. Jeśli niedopłata jest znaczna: Opcje:
   • Poproś klienta o dopłatę (wygeneruj nową fakturę na różnicę)
   • Zaakceptuj płatność częściową i dostosuj zamówienie
   • Zwróć transakcję
4. Zapobiegaj przyszłym problemom: Zwracaj klientom uwagę, aby skanowali kod QR lub kopiowali dokładną kwotę

⏰ Płatność wygasła

Objawy: Okno płatności zamknęło się, zanim klient dokończył transakcję.

Najczęstsze przyczyny:

• Domyślny czas wygaśnięcia 15 minut był zbyt krótki dla klienta
• Klient niedoświadczony w obsłudze portfeli kryptowalutowych
• Przeciążenie sieci powodujące opóźnienia

Rozwiązania:

1. Wygeneruj nowe żądanie płatności z tym samym lub wydłużonym czasem wygaśnięcia
2. Zwiększ domyślny czas wygaśnięcia: Panel → Ustawienia → Ustawienia płatności → Czas wygaśnięcia (maks. 24 godziny)
3. Jeśli klient wysłał już środki na wygasły adres: Płatność może mimo to zostać wykryta i zaksięgowana (skontaktuj się z pomocą techniczną w celu weryfikacji)
4. Dla transakcji o wysokiej wartości: Użyj dłuższego czasu wygaśnięcia (60+ minut), aby zmniejszyć presję na klientów

🔌 Wtyczka nie łączy się z GriffNode

Objawy: Wtyczka e-commerce (WooCommerce, WordPress) pokazuje błędy połączenia.

Najczęstsze przyczyny:

• Nieprawidłowy klucz API lub sekret
• Klucz API trybu testowego użyty na produkcji (lub odwrotnie)
• Zapora serwera blokująca połączenia wychodzące do GriffNode
• Wtyczka nieaktualizowana do najnowszej wersji

Rozwiązania:

1. Zweryfikuj dane uwierzytelniające API:
   • Panel → Programiści → Klucze API
   • Upewnij się, że używasz właściwego środowiska (testowego lub produkcyjnego)
   • Klucz API powinien zaczynać się od cgk_live_ lub cgk_test_
2. Przetestuj połączenie ręcznie:
   curl -X GET "https://api.griffnode.com/v1/ping" \ -H "Authorization: Bearer YOUR_API_KEY" // Expected response: {"status":"ok"}
3. Sprawdź wymagania serwera:
   • PHP 7.4+ (dla wtyczek opartych na PHP)
   • Włączony cURL lub file_get_contents
   • Dozwolone wychodzące połączenia HTTPS
4. Zaktualizuj wtyczkę: Upewnij się, że korzystasz z najnowszej wersji
5. Sprawdź dzienniki błędów: Większość wtyczek zapisuje błędy w wp-content/debug.log (WordPress) lub podobnym pliku

🔒 Błędy CORS (zablokowane żądanie z innej domeny)

Objawy: Konsola przeglądarki pokazuje błędy zasad CORS podczas wykonywania żądań API.

Najczęstsze przyczyny:

• Wykonywanie żądań API bezpośrednio z frontendowego JavaScriptu (niedozwolone)
• Domena niedodana do listy dozwolonych w ustawieniach API

Rozwiązania:

1. Żądania API muszą pochodzić z twojego serwera backendowego, a nie bezpośrednio z JavaScriptu w przeglądarce
2. Prawidłowa architektura:
   • ❌ Przeglądarka → API GriffNode (powoduje błąd CORS)
   • ✅ Przeglądarka → twój serwer → API GriffNode
3. Jeśli potrzebujesz żądań z frontendu: Użyj naszego SDK dla JavaScriptu, które automatycznie obsługuje przekierowanie żądań:
   // Install SDK npm install @griffnode/js-sdk // Initialize with public key only (safe for frontend) import GriffNode from '@griffnode/js-sdk'; const cg = new GriffNode({ publicKey: 'cgk_pub_...', // Public key, not secret key! mode: 'test' });
4. Nigdy nie ujawniaj swojego tajnego klucza API w kodzie frontendowym!

📦 Niepowodzenia instalacji SDK

Objawy: npm install, composer install lub pip install kończy się niepowodzeniem.

Rozwiązania według platformy:

JavaScript/Node.js:

PHP:

Python:

401 Unauthorized

Komunikat o błędzie: {"error": "Invalid API key"}

Najczęstsze przyczyny:

• Nieprawidłowy lub wygasły klucz API
• Użycie klucza testowego w środowisku produkcyjnym
• Brak nagłówka Authorization
• Nieprawidłowy format nagłówka

Rozwiązania:

1. Zweryfikuj format klucza API:
   // Correct format Authorization: Bearer cgk_live_1234567890abcdef... // ❌ Wrong: Missing "Bearer" Authorization: cgk_live_1234567890abcdef... // ❌ Wrong: Extra spaces Authorization: Bearer cgk_live_1234567890abcdef...
2. Wygeneruj klucz API ponownie: Panel → Programiści → Klucze API → Wygeneruj ponownie
3. Sprawdź środowisko: Upewnij się, że klucze cgk_test_ trafiają do testowego API, a cgk_live_ na produkcję

429 Too Many Requests

Komunikat o błędzie: {"error": "Rate limit exceeded"}

Limity zapytań:

Rozwiązania:

1. Zastosuj wykładnicze ponawianie (exponential backoff):
   async function requestWithRetry(url, options, maxRetries = 3) { for (let i = 0; i < maxRetries; i++) { const response = await fetch(url, options); if (response.status === 429) { const retryAfter = response.headers.get('Retry-After') || (2 ** i); await new Promise(resolve => setTimeout(resolve, retryAfter * 1000)); continue; } return response; } throw new Error('Max retries exceeded'); }
2. Buforuj odpowiedzi: Nie pobieraj wielokrotnie tych samych danych
3. Używaj webhooków zamiast odpytywania: Otrzymuj powiadomienia o zdarzeniach zamiast wielokrotnie je sprawdzać
4. Skontaktuj się z pomocą techniczną w sprawie wyższych limitów, jeśli masz uzasadnione potrzeby dużego ruchu

422 Unprocessable Entity

Komunikat o błędzie: {"error": "Validation failed", "details": {...}}

Najczęstsze przyczyny:

• Brak wymaganych pól
• Nieprawidłowy format pola (np. nieprawidłowy adres e-mail, ujemna kwota)
• Wartość pola poza dozwolonym zakresem

Rozwiązania:

1. Sprawdź szczegóły błędu: Pole details dokładnie wskazuje, co jest nie tak
2. Najczęstsze błędy walidacji:
   • amount: Musi być liczbą dodatnią, maksymalnie 2 miejsca po przecinku
   • currency: Musi być jedną z: BTC, ETH, LTC, DASH, DOGE
   • email: Musi mieć poprawny format adresu e-mail
   • webhook_url: Musi być poprawnym adresem URL z HTTPS
3. Zwaliduj dane przed wysłaniem:
   // Example validation const paymentData = { amount: parseFloat(amount).toFixed(2), // Ensure 2 decimals currency: currency.toUpperCase(), // Ensure uppercase email: email.trim().toLowerCase() // Normalize email };

500 Internal Server Error

Komunikat o błędzie: {"error": "Internal server error"}

To wskazuje na problem po naszej stronie.

Rozwiązania:

1. Sprawdź stronę statusu: status.griffnode.com pod kątem trwających awarii
2. Ponów próbę z wykładniczym ponawianiem: Tymczasowe problemy zwykle ustępują w ciągu kilku sekund
3. Jeśli problem się utrzymuje: Skontaktuj się z pomocą techniczną, podając:
   • Identyfikator żądania (z nagłówka X-Request-ID)
   • Znacznik czasu
   • Adres URL punktu końcowego
   • Ładunek żądania (oczyszczony z danych wrażliwych)

📡 Webhooki nie są odbierane

Objawy: Płatność została zrealizowana, ale twój serwer nigdy nie otrzymał powiadomienia webhook.

Najczęstsze przyczyny:

• Adres URL webhooka nie został skonfigurowany
• Zapora serwera blokująca żądania przychodzące
• Błędy certyfikatu HTTPS na twoim serwerze
• twój punkt końcowy zwraca kod statusu inny niż 200

Rozwiązania:

1. Zweryfikuj adres URL webhooka: Panel → Programiści → Webhooki
2. Przetestuj punkt końcowy webhooka:
   curl -X POST https://yourdomain.com/webhooks/griffnode \ -H "Content-Type: application/json" \ -d '{"event":"test","data":{}}' // Should return HTTP 200
3. Sprawdź dzienniki webhooków: Panel pokazuje próby dostarczenia i odpowiedzi
4. Najczęstsze problemy:
   • Punkt końcowy musi używać HTTPS (nie HTTP)
   • Musi mieć poprawny certyfikat SSL
   • Musi odpowiedzieć w ciągu 30 sekund
   • Musi zwracać kod statusu 2xx (200, 201, 204)
5. Przetestuj za pomocą webhook.site: Skorzystaj tymczasowo z webhook.site, aby zweryfikować, że GriffNode wysyła webhooki

🔐 Weryfikacja podpisu webhooka kończy się niepowodzeniem

Objawy: Otrzymujesz webhooki, ale walidacja podpisu kończy się niepowodzeniem.

Najczęstsze przyczyny:

• Użycie nieprawidłowego sekretu webhooka
• Modyfikowanie treści żądania przed weryfikacją
• Nieprawidłowe obliczenie podpisu

Rozwiązania:

1. Prawidłowy proces weryfikacji:
   // Node.js example const crypto = require('crypto'); function verifyWebhook(payload, signature, secret) { const hash = crypto .createHmac('sha256', secret) .update(payload) // Raw body, not parsed JSON! .digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(hash) ); } // Express.js middleware app.post('/webhooks', express.raw({type: 'application/json'}), (req, res) => { const signature = req.headers['x-griffnode-signature']; const payload = req.body.toString('utf8'); if (verifyWebhook(payload, signature, WEBHOOK_SECRET)) { const data = JSON.parse(payload); // Process webhook... res.sendStatus(200); } else { res.sendStatus(401); } });
2. Pobierz sekret webhooka: Panel → Programiści → Webhooki → Pokaż sekret
3. Najczęstsze błędy:
   • ❌ Użycie klucza API zamiast sekretu webhooka
   • ❌ Parsowanie JSON przed weryfikacją
   • ❌ Użycie SHA1 zamiast SHA256
   • ❌ Brak porównania odpornego na ataki czasowe

🔄 Wyczerpano próby ponowienia webhooka

Objawy: Panel pokazuje, że dostarczenie webhooka nie powiodło się po wszystkich próbach.

Harmonogram ponawiania:

• Próba 1: Natychmiast
• Próba 2: +1 minuta
• Próba 3: +5 minut
• Próba 4: +15 minut
• Próby 5-10: +1 godzina każda

Rozwiązania:

1. Napraw problemy ze swoim punktem końcowym (patrz wyżej)
2. Ręczne ponowne odtworzenie: Panel → Webhooki → Wybierz zdarzenie → Odtwórz ponownie
3. Pobierz pominięte zdarzenia przez API:
   // Get recent events GET /v1/events?since=2024-01-01T00:00:00Z // Process events your webhook handler missed
4. Zaimplementuj idempotentność: Obsługuj zduplikowane webhooki w sposób bezpieczny (wysyłamy klucze idempotentności)

🔑 Nie mogę się zalogować

Najczęstsze przyczyny:

• Nieprawidłowe hasło
• Kod 2FA wygasł lub jest błędny
• Konto zablokowane z powodu nieudanych prób logowania
• Adres e-mail nie został zweryfikowany

Rozwiązania:

1. Zresetuj hasło: Kliknij „Nie pamiętam hasła” na stronie logowania
2. Problemy z 2FA:
   • Upewnij się, że zegar urządzenia jest zsynchronizowany (TOTP wymaga dokładnego czasu)
   • Spróbuj kodów zapasowych, jeśli aplikacja uwierzytelniająca nie działa
   • Skontaktuj się z pomocą techniczną, jeśli utraciłeś zarówno aplikację uwierzytelniającą, jak i kody zapasowe
3. Konto zablokowane: Poczekaj 30 minut lub skontaktuj się z pomocą techniczną
4. Adres e-mail niezweryfikowany: Sprawdź folder ze spamem w poszukiwaniu wiadomości weryfikacyjnej lub poproś o nową

📧 Nie otrzymuję wiadomości e-mail

Objawy: Nie otrzymujesz wiadomości weryfikacyjnych, resetujących hasło ani powiadomień.

Rozwiązania:

1. Sprawdź folder ze spamem/niechcianymi wiadomościami
2. Dodaj do bezpiecznych nadawców: [email protected] oraz [email protected]
3. Zweryfikuj adres e-mail: Panel → Ustawienia konta → E-mail
4. Wypróbuj innego dostawcę poczty: Niektórzy dostawcy agresywnie filtrują wiadomości związane z kryptowalutami
5. Sprawdź dzienniki poczty: Panel → Ustawienia → Dzienniki poczty (pokazują status dostarczenia)

💰 Błąd „Nieprawidłowy adres”

Objawy: Nie można zapisać adresu portfela w panelu.

Najczęstsze przyczyny:

• Format adresu nie pasuje do kryptowaluty (np. adres BTC dla ETH)
• Literówka w adresie
• Użycie adresu testnetu na produkcji
• Adres zawiera nieprawidłowe znaki

Rozwiązania:

1. Zweryfikuj format adresu:
   • Bitcoin: Zaczyna się od 1, 3 lub bc1 (39-42 znaki)
   • Ethereum: Zaczyna się od 0x (42 znaki)
   • Litecoin: Zaczyna się od L lub M (34-43 znaki)
   • Dash: Zaczyna się od X (34 znaki)
   • Dogecoin: Zaczyna się od D (34 znaki)
2. Skopiuj adres bezpośrednio ze swojego portfela — nie wpisuj go ręcznie
3. Zweryfikuj sumę kontrolną: Użyj narzędzi do walidacji adresów, aby upewnić się, że jest poprawny
4. Brak spacji i znaków nowej linii na początku/końcu adresu

🔒 Nie mogę zmienić adresu portfela

Objawy: Panel nie pozwala zaktualizować adresu portfela.

Najczęstsze przyczyny:

• 2FA nie jest włączone (wymagane przy zmianach portfela)
• Niedawna zmiana adresu (24-godzinny okres karencji)
• Oczekujące transakcje korzystające z bieżącego adresu

Rozwiązania:

1. Włącz 2FA: Panel → Bezpieczeństwo → Uwierzytelnianie dwuskładnikowe
2. Poczekaj na zakończenie okresu karencji: Funkcja bezpieczeństwa zapobiegająca nieautoryzowanym zmianom
3. Poczekaj na zakończenie oczekujących transakcji
4. W pilnych przypadkach: Skontaktuj się z pomocą techniczną, dołączając dokumenty weryfikacyjne

⚡ Wysokie opłaty sieciowe

Objawy: Klienci skarżą się na wysokie opłaty transakcyjne.

To normalne w okresach przeciążenia sieci. Opłaty są ustalane przez sieci blockchain, a nie przez GriffNode.

Rozwiązania:

1. Używaj szybszych, tańszych monet: Litecoin i Dash zwykle mają niższe opłaty niż Bitcoin
2. W przypadku Bitcoina:
   • Używaj adresów SegWit (zaczynających się od bc1), aby uzyskać ~30% niższe opłaty
   • Grupuj transakcje, gdy to możliwe
   • Przyjmuj płatności w okresach mniejszego ruchu (weekendy często są tańsze)
3. Sprawdź bieżące stawki opłat: mempool.space (Bitcoin)
4. Oferuj szacowanie opłat: Nasze API udostępnia szacunki opłat dla różnych prędkości potwierdzania