Najpierw architektura: CoinGate jest payment railem, nie domeną produktu
Najczystsza integracja CoinGate umieszcza payment-orchestration layer pomiędzy domeną biznesową a providerem. Faktura lub order nie powinny stawać się obiektem CoinGate. Mają własny lifecycle i referencję do osobnego payment intent.
Praktyczny łańcuch danych:
Business Order → Payment Intent → CoinGate Order → Payment Callback → Product Ledger → Settlement/Reconciliation.
Krok 1: utwórz product-owned payment intent
Przed wywołaniem CoinGate utwórz internal record zawierający klienta, obiekt biznesowy, expected price amount/currency, dozwoloną metodę, expiry policy i stabilny idempotency/reference key.
Nie używaj provider ID jako głównego identyfikatora biznesowego. Provider migration i retry są dużo łatwiejsze, gdy system posiada własną referencję.
Krok 2: utwórz CoinGate order
Create Order przyjmuje price amount/currency, settlement receive_currency, callback URL, return URLs i merchant-defined token. Zwraca payment_url do hosted checkoutu.
W typowym B2B cena handlowa może pozostać w EUR, a klient wybiera USDC w checkout providera. Settlement przebiega zgodnie z konfiguracją merchanta i capabilities providera.
Rekomendowany mapping
| Twoje pole | CoinGate | Cel |
|---|---|---|
| paymentIntentId | order_id/title/reference | Korelacja systemów |
| amountDue | price_amount | Kwota handlowa |
| currency | price_currency | Commercial source-of-truth |
| settlementPreference | receive_currency | Target settlement |
| callbackSecret | token | Wsparcie walidacji callbacku |
Krok 3: hosted checkout
Hosted checkout jest zwykle najlepszy dla pierwszej wersji produkcyjnej, bo provider kontroluje prezentację wspieranych aktywów/sieci i instrukcje płatnicze. Aplikacja nie hardcoduje network-specific address/amount UX.
Krok 4: callbacki przetwarzaj idempotentnie
CoinGate dokumentuje callbacki po zmianach stanu oraz retry do chwili, gdy merchant endpoint zwróci sukces. Udostępnia również callback replay w dashboardzie. Duplikaty są więc oczekiwaną cechą systemu.
Callback handler powinien:
- uwierzytelnić/zweryfikować event zgodnie z integracją,
- zapisać external event ID lub deduplication key,
- transakcyjnie pobrać payment intent,
- zweryfikować provider order, state, amount i currency context,
- wykonać idempotentne state transition,
- zapisać audit event,
- zwrócić sukces dopiero po trwałym zapisie.
Krok 5: mapuj status CoinGate do product state
CoinGate dokumentuje obecnie m.in. new, pending, confirming, paid, invalid, expired, canceled i stany refundów. Nie kopiuj ich 1:1 jako jedynego modelu produktu.
| Provider | Product payment | Akcja |
|---|---|---|
| new/pending | AWAITING_PAYMENT | Brak entitlement |
| confirming | PAYMENT_DETECTED | Tylko progress |
| paid | PAID | Credit ledger / unlock według polityki |
| invalid | MANUAL_REVIEW lub FAILED | Bez automatycznego credit |
| expired/canceled | CLOSED | Nowy intent, jeśli potrzebny |
Krok 6: weryfikuj przed credit
Dla krytycznych płatności callback powinien inicjować state verification, nie blind trust. Get Order zwraca szczegółowe informacje, w tym payment amounts, conversion data, fees, refunds i blockchain transaction data.
Krok 7: aktualizuj internal ledger
Gdy firma akceptuje płatność, twórz immutable ledger event powiązany z customerem, fakturą/orderem, payment intent i provider order. Provider status i product credit trzymaj osobno.
Model danych opisuje przewodnik internal ledger.
Krok 8: refund to osobny lifecycle
Refund nie oznacza „cofnij payment status do unpaid”. To nowe zdarzenie finansowe z własną kwotą, walutą, destination, provider refund ID, statusem i audit trailem. CoinGate ma osobne refund APIs i callbacki statusów refundu.
Krok 9: uzgadniaj provider ledger i settlement
Callback informuje o zmianie stanu. Reconciliation dowodzi, że financial movements się zgadzają. CoinGate udostępnia ledger transactions z filtrami m.in. po dacie, walucie, transaction type i source.
Daily job powinien porównywać:
- product payments zaakceptowane w oknie,
- CoinGate orders i ledger transactions,
- provider fees i refunds,
- withdrawal/settlement records,
- bank evidence przy fiat settlement.
Zobacz pełny przewodnik reconciliation.
Testing checklist
- normalna płatność USDC,
- duplicate callback,
- callback out of order,
- expired payment,
- invalid/manual review,
- aplikacja zwraca 500 i callback jest replayed,
- amount/reference mismatch,
- pełny i częściowy refund,
- reconciliation mismatch,
- czasowa niedostępność API providera.
Anti-patterns
„Callback = paid”
Callback jest inputem. System decyduje, czy transition jest prawidłowe.
„Status CoinGate = cały payment model”
Provider state jest węższy niż business state. Produkt potrzebuje czasem osobnego entitlement, settlement, refund i manual review.
„Nie potrzebujemy ledgera, provider ma raporty”
Provider reporting nie zastępuje zapisu, dlaczego customer został credited.
„Reconciliation zrobimy później”
Później zwykle oznacza dopiero po pojawieniu się wolumenu, przy którym brakujące referencje są kosztowne.
Monitoring i observability
Wystaw metryki dla created orders, checkout conversion, płatności stuck in confirming, callback failures, callback processing latency, invalid payments, refund failures i settlement mismatches. Provider IDs powinny być wyszukiwalne w operator panel, aby support mógł przejść od customer/invoice do dokładnego provider object bez ręcznego querying production DB.
Security boundary
CoinGate API token trzymaj server-side, poza kodem browsera, i ograniczaj dostęp zgodnie z konfiguracją dostępną dla konta. Callback endpoint jest publicznym HTTPS endpointem, ale nie może przyjmować business mutations z dowolnego payloadu. Authentication, reference validation i idempotency muszą wydarzyć się przed product credit.
Sandbox-to-production rollout
Sandbox służy do weryfikacji integration contracts, ale przed pierwszą live payment potrzebny jest production runbook. Powinien obejmować callback replay, provider outage, failed refund, settlement delay, manual status verification i escalation ownership. Przed rolloutem na wszystkich klientów wykonaj low-value live transactions.
Gdzie CoinGate pasuje najlepiej
CoinGate pasuje tam, gdzie produkt chce managed crypto checkout i provider-side settlement, ale business logic, entitlement i reconciliation pozostają w aplikacji. Samą decyzję architektoniczną opisuje gateway vs custom wallet infrastructure.