Doporučené postupy
Odpovídá běžné architektuře platebních backendů: tajemství na serveru, celočíselné částky, idempotentní callbacky a jasná sémantika chyb.
1. Přihlašovací údaje jen na serveru
Nikdy nevystavujte clientSecret ani backendové údaje ve frontend bundle.
- SDK inicializujte jen v backendových službách
- Údaje čtěte z proměnných prostředí nebo secret manageru
- Pravidelně rotujte přihlašovací údaje
2. Unikátní čísla objednávek
order_number je unikátní obchodní identifikátor.
- Vložte interní ID objednávky
- Vyhněte se náhodným hodnotám bez vazby na vaše systémy
- Udržujte stabilní mapování mezi objednávkou a ID platby GoPay
3. Částky v minor jednotkách
GoPay odesílá částky v minor jednotkách měny.
10000 minor jednotek CZK = 100,00 CZK- Vyhněte se float aritmetice pro částky
- Preferujte celočíselné výpočty
4. Asynchronní dokončení platby
Vytvoření platby a přesměrování je jen část toku.
- Uživatel může opustit checkout
- Návrat z prohlížeče může selhat
- Konečný stav ověřte na serveru
Doporučený postup:
- Vytvořit platbu
- Přesměrovat na
gw_url
- Zpracovat notifikaci na backendu
- Ověřit stav pomocí
getPayment
- Označit objednávku jako zaplacenou až po terminálním úspěšném stavu
5. Rozlišení opakovatelných a neopakovatelných chyb
Používejte metadata GoPayApiError:
status — třída HTTPerrors — detaily políendpoint — diagnostika a logy
Strategie:
- Opakovat přechodné chyby infrastruktury (timeouty, 5xx) s backoffem
- Neopakovat slepě validační/obchodní chyby (4xx)
6. Sdílet instance klienta
Dlouho žijící instance klienta na konfiguraci obchodníka místo instance na každý request.
- Lepší využití cache tokenů
- Méně zátěže na token endpoint
- Nižší latence běžných operací
7. Ladění timeoutů
timeoutMs podle sítě a infrastruktury:
- příliš nízké: zbytečná selhání při jitteru
- příliš vysoké: pomalá zpětná vazba a zaseknuté zdroje
Začněte výchozí hodnotou a upravte podle měření.
8. Vlastní transport pro observabilitu
Vlastní HttpTransport pro:
- trasovací ID požadavků
- metriky (latence, stavy)
- strukturované logy
- proxy / interní síť
Viz Rozšiřitelnost.
9. Integrační testy obchodního toku
Testy knihovny pokrývají SDK izolovaně; vaše aplikace by měla testovat také:
- mapování objednávka → platba
- zpracování callbacku a idempotenci
- přechody stavů ve vašem datovém modelu
10. Aktualizace verze SDK
- Připněte
gopay-sdk na explicitní semver rozsah (v produkci ne *).
- Při upgrade čtěte
CHANGELOG.md.
- Po upgrade spusťte integrační testy proti sandboxu.
Viz také Kontrolní seznam pro produkci.