API kryptoplatební brány: faktury, webhooky, výplaty a white label

Co dělá API kryptoplatební brány?

API skrývá blockchain před vaším kódem. Místo provozu nodů, odvozování adres a počítání potvrzení zavoláte endpoint pro vytvoření faktury, uložíte si identifikátor brány a čekáte na notifikace. Brána vyčíslí směnný kurz, sleduje sítě, provádí AML kontrolu a vypořádává na váš zůstatek.

Většina bran nabízí stejné stavební kameny pod různými názvy: faktury nebo objednávky pro příchozí platby, IPN nebo callbacky pro notifikace, endpointy pro konverzi a zůstatky a výplaty či výběry pro odchozí převody. Sandbox mají u většiny poskytovatelů, například samostatný sandbox host u CoinGate a sandbox účet u NOWPayments, a je vhodné ho použít před jakýmkoli testem na mainnetu.

• Invoice API: vytvoření, čtení a zrušení platebních požadavků s fiat cenou, přijímanými coiny, referencí objednávky a callback URL
• Notifikace: webhooky nebo IPN při každé změně stavu, obvykle podepsané
• Payouts API: odeslání kryptoměny nebo fiat zákazníkům, partnerům či do vlastní peněženky
• Kurzy a měny: seznam podporovaných coinů, sítí, minimálních částek a aktuálních kotací
• Pluginy a SDK: hotové moduly pro e-commerce platformy nad stejným API

Jak funguje životní cyklus faktury?

Každá brána má vlastní model stavů, proto je před psaním obchodní logiky namapujte na malou sadu interních stavů. Zboží smí uvolnit jen konečný stav zaplaceno; mezistavy existují proto, že transakci lze na blockchainu vidět dlouho předtím, než je bezpečné ji přijmout.

Tabulka mapuje dva zveřejněné modely stavů na stavy, které potřebuje většina platforem. CoinGate například nezaplacenou fakturu nechá vypršet po 20 minutách od chvíle, kdy zákazník zvolil coin, a platby zachycené AML kontrolou vede jako neplatné.

Jak ověřovat krypto webhooky a IPN?

Každou notifikaci považujte za nedůvěryhodnou, dokud ji neověříte. Brány používají různá schémata: NOWPayments podepisuje seřazené JSON tělo pomocí HMAC-SHA512 a posílá podpis v hlavičce x-nowpayments-sig, CoinGate posílá token, který nastavíte na objednávce, a BitPay doporučuje po každé notifikaci načíst fakturu z API místo důvěry v její tělo.

Nejbezpečnější vzor kombinuje obojí: ověřte podpis, poté načtěte fakturu z API a jednejte podle této odpovědi. Stojí to jeden požadavek na změnu stavu a chrání vás to před falešnými nebo přehranými callbacky.

• Podpisy ověřujte porovnáním v konstantním čase a nepodepsané požadavky odmítejte
• Před změnou stavu objednávky znovu načtěte fakturu podle jejího ID u brány
• Rychle vracejte HTTP 200 a zpracovávejte asynchronně; brány při chybě opakují
• Každou notifikaci ukládejte s událostí či stavem, aby se duplicity ignorovaly
• Nikdy nevěřte částkám a měnám odeslaným v přesměrování z prohlížeče

Jak řešit podplacení, přeplacení a pozdní platby?

Peněženky a burzy strhávají poplatky za výběr a zákazníci částky opisují nepřesně, takže na přesnou platbu se nelze spoléhat. Před spuštěním definujte toleranci a pravidlo pro každý případ a výsledek zpřístupněte pracovníkům podpory.

Jak fungují idempotence a párování plateb?

Faktury vytvářejte s vlastní referencí objednávky a volání proveďte tak, aby šlo bezpečně opakovat: pokud požadavek vyprší, před vytvořením další faktury ji vyhledejte podle reference, nebo použijte idempotentní klíč tam, kde ho brána podporuje. Stejné pravidlo platí pro výplaty, kde duplicitní požadavek pošle skutečné peníze dvakrát.

Pro párování ukládejte ID faktury u brány, hash transakce, fiat částku, krypto částku, kurz a poplatek. Reporty vypořádání uvádějí výplaty po dávkách, takže párování probíhá od objednávky přes fakturu k výplatě, nikoli od objednávky k řádku na bankovním výpisu.

Co potřebuje Payouts API kvůli Travel Rule?

Výplatní endpointy posílají krypto ze zůstatku u brány na adresu, často po dávkách pro provize partnerů, prodejce na tržišti nebo výběry zákazníků. Většina vyžaduje whitelist adres, dvoufázové schválení nebo API klíč se samostatným oprávněním pro výplaty.

V EU nařízení (EU) 2023/1113 ukládá bráně předávat s každým převodem údaje o odesílateli a příjemci a nad 1 000 EUR ověřovat vlastnictví vlastních (self-hosted) peněženek. Počítejte s tím, že požadavky na výplatu budou obsahovat jméno příjemce a typ adresy, a naplánujte převody, které na tyto údaje čekají.

Jaké jsou možnosti white label kryptoplatební brány?

Platformy, které platby přeprodávají vlastním obchodníkům, často chtějí platební stránku pod vlastní značkou. Existují tři úrovně a cena roste s mírou kontroly. Plisio například uvádí 0,5 % za API a 1,5 % za white label a NOWPayments prodává samostatný white-label produkt.

Plný white label přesouvá nejen branding, ale i odpovědnost. Pokud sami onboardujete obchodníky a držíte jejich zůstatky, můžete potřebovat vlastní povolení podle MiCA; model sub-merchantů u autorizované brány drží tuto povinnost u brány.

Jak napojit API kryptobran přes OrsunPay?

OrsunPay sjednocuje stavy kryptobran, webhooky a vratky do jednoho API vedle vašich karetních a bankovních poskytovatelů, a to na vašich vlastních účtech u bran. Krypto nedrží ani nevyplácí z vlastního zůstatku; směruje požadavky na bránu, kterou zvolíte, a vrací podepsané, deduplikované události.

Jak integrovat API platební brány pro kryptoměny

1. Založte sandbox účty Vytvořte u brány sandbox i produkční účet, vygenerujte samostatné API klíče pro faktury a výplaty a nastavte tajný klíč IPN.
2. Namapujte stavy Přeložte stavy brány na své interní stavy a rozhodněte, který z nich uvolňuje zboží.
3. Vytvářejte faktury idempotentně Odešlete fiat částku, měnu, referenci objednávky a callback URL; před opakováním volání, které vypršelo, vyhledejte fakturu podle reference.
4. Ověřujte notifikace Zkontrolujte podpis, znovu načtěte fakturu z API a událost zpracujte jen jednou.
5. Ošetřete okrajové případy Implementujte toleranci, doplatek, vratku a expiraci a každý scénář otestujte v sandboxu.
6. Párujte vypořádání U každé faktury ukládejte hash transakce, kurz a poplatek a denně párujte dávky výplat s objednávkami.