Dokumentace

Platební URL a jak funguje platba

Technická dokumentace k sestavování platebních odkazů, ověřování adres a potvrzování plateb na blockchainu.

Platební URL

Platební předpis se vytvoří otevřením stránky https://paythat.online/pay s URL parametry. Existují dva režimy — režim obchodníka (s merchant_id) a anonymní režim (jen s wallet adresou).

Základní formát

/pay?amount=ČÁSTKA&currency=MĚNA&merchant_id=IDENTIFIKÁTOR&order_id=OBJEDNÁVKA&wallet=ADRESA

Povinné parametry

ParametrPopis
amountČástka ve fiat měně (kladné číslo, např. 100 nebo 2500.50)
currencyKód fiat měny podle ISO 4217 (např. CZK, EUR, USD)
merchant_id
nebo wallet		Veřejný identifikátor obchodníka nebo Bitcoin adresa — je potřeba alespoň jeden z nich

Volitelné parametry

ParametrPopis
order_idIdentifikátor objednávky od obchodníka. Pouze v režimu obchodníka (s merchant_id). V anonymním režimu se nezobrazuje.
walletBitcoin adresa (mainnet). V režimu obchodníka určuje, na kterou adresu se platba pošle. V anonymním režimu je povinný.

Režim obchodníka (merchant_id)

Obchodník má účet v PayThat s přiřazenými Bitcoin adresami. Zákazník platí na adresu, kterou systém automaticky přiřadí z adres obchodníka.

/pay?merchant_id=muj-eshop&order_id=OBJ-2026-001&amount=1500&currency=CZK

V tomto režimu se platba zaznamená do databáze, systém sleduje blockchain a po potvrzení transakce automaticky označí předpis jako zaplacený.

Anonymní režim (jen wallet)

Pokud v URL není merchant_id, ale jen wallet, vytvoří se platební předpis bez účtu obchodníka. Na řádku „Komu" se zobrazí „Anonymní platební požadavek". Kurz se načte z API a cachuje se v prohlížeči, ale platba se neukládá do databáze a blockchain se nekontroluje.

/pay?wallet=bc1qxy2kgdygjrsqtzq2n0nyrfw9363p0g7z2z2z2&amount=50&currency=EUR

Když URL obsahuje jak merchant_id, tak wallet

Pokud jsou v URL oba parametry, systém se chová podle toho, zda adresa patří obchodníkovi:

Adresa patří obchodníkovi — použije se přesně tato adresa. Umožňuje obchodníkovi vybrat konkrétní peněženku pro konkrétní objednávku.

Adresa obchodníkovi nepatří — parametr wallet se ignoruje a systém přiřadí první volnou adresu z účtu obchodníka. Platba se nezarekne na cizí adresu.

/pay?merchant_id=muj-eshop&order_id=OBJ-001&amount=100&currency=USD&wallet=bc1q...

Jak funguje platební stránka

  1. 1
    Načtení kurzu — systém stáhne aktuální BTC/fiat kurz z Coinbase a vytvoří kurzový snapshot (quote) s platností 15 minut.
  2. 2
    Zobrazení QR kódu — zákazník vidí QR kód s Bitcoin URI (adresa + částka), odpočet do konce platnosti kurzu a přepočet fiat → BTC → satoshi.
  3. 3
    Obnovení kurzu — po vypršení platnosti se automaticky stáhne nový kurz a odpočet se restartuje. V režimu obchodníka se kurz může uzamknout na první quote (dle nastavení).
  4. 4
    Sledování blockchainu — při vypršení odpočtu (každých 15 min) systém před načtením nového kurzu zkontroluje blockchain, zda na adresu nepřišla platba. V anonymním režimu se blockchain nekontroluje.

Ověření adresy na blockchainu

Při zobrazení platebního předpisu systém ověří, zda zadaná Bitcoin adresa skutečně existuje na blockchainu. Dotazuje se Blockchain.com API na transakce adresy:

Adresa existuje — platební předpis se zobrazí normálně (QR kód, odpočet, přepočet na BTC).

Adresa neexistuje — místo QR kódu se zobrazí červený čtverec s vykřičníkem a varovným textem:

„Pozor, zjistili jsme, že tato peněženka neexistuje, kontaktujte obchodníka. Na uvedenou adresu neposílejte platbu."

Adresa se vypíše v červeném poli s odkazem na blockchain prohlížeč, aby si uživatel mohl sám ověřit, že adresa skutečně neexistuje. Odpočet se vypne a fiat měna se nepřepočítává na BTC.

Ověření, že je předpis zaplacený

Ověření probíhá pouze v režimu obchodníka (s merchant_id). Anonymní režim blockchain nekontroluje.

  1. 1
    Pravidelný sken — background worker prochází otevřené předpisy každých 15 minut jako batch operaci (seskupeno podle adresy pro minimalizaci API volání) a stahuje transakce z Blockchain.com API.
  2. 2
    Párování podle satoshi — pro každou příchozí transakci systém porovná skutečnou částku v satoshi s očekávanou částkou z kurzového snapshotu. Platba musí přesně odpovídat — síťový poplatek (miner fee) se platí navíc, neodečítá se z odesílané částky.
  3. 3
    Stavy předpisu — předpis může být v jednom z těchto stavů:
    • open — čeká na platbu
    • paid — platba potvrzena na blockchainu (částka sedí)
    • mismatch — platba přijata, ale v nesprávné částce
    • expired — předpis vypršel (24 hodin bez platby od poslední návštěvy zákazníka)
    • cancelled — předpis zrušen obchodníkem
  4. 4
    Notifikace — když je platba potvrzena, obchodník dostane e-mail (pokud má notifikace zapnuté v nastavení).

Máte dotazy? Kontaktujte nás

FAQ