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

Parametr	Popis
amount	Částka ve fiat měně (kladné číslo, např. `100` nebo `2500.50`)
currency	Kó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

Parametr	Popis
order_id	Identifikátor objednávky od obchodníka. Pouze v režimu obchodníka (s merchant_id). V anonymním režimu se nezobrazuje.
wallet	Bitcoin 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
Načtení kurzu — systém stáhne aktuální BTC/fiat kurz z Coinbase a vytvoří kurzový snapshot (quote) s platností 15 minut.
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
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
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
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
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
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
Notifikace — když je platba potvrzena, obchodník dostane e-mail (pokud má notifikace zapnuté v nastavení).

Vložení platební stránky do iframe

Stránku /pay lze vložit přímo do vašeho e-shopu nebo webu pomocí elementu <iframe>. Iframe se automaticky přizpůsobí šířce svého kontejneru a doporučená výška pokrývá celý platební panel včetně QR kódu a odpočtu.

Základní iframe

<iframe
  src="https://paythat.online/pay?merchant_id=muj-eshop&order_id=OBJ-2026-001&amount=1500&currency=CZK"
  style="width: 100%; max-width: 480px; height: 640px; border: 0; border-radius: 12px;"
  title="PayThat – Bitcoin platba"
  loading="lazy">
</iframe>

Responzivní iframe

Pro plně responzivní chování zabalte iframe do kontejneru, který řídí maximální šířku. Iframe pak vyplní dostupný prostor a na mobilech se přizpůsobí celé šířce obrazovky:

<div style="width: 100%; max-width: 480px; margin: 0 auto;">
  <iframe
    src="https://paythat.online/pay?merchant_id=muj-eshop&order_id=OBJ-2026-001&amount=1500&currency=CZK"
    style="width: 100%; min-height: 640px; border: 0; border-radius: 12px; display: block;"
    title="PayThat – Bitcoin platba"
    loading="lazy">
  </iframe>
</div>

Důležité: Aby bylo možné stránku vložit do iframe, musí být v dashboardu aplikace (Security → Security headers) povolena doména, na které bude iframe zobrazen, v hlavičce frame-ancestors. Jinak prohlížeč vložení zablokuje.

Platební tlačítko

Místo přímého odkazu můžete na svém webu použít tlačítko, které zákazníka přenese na platební stránku. Tlačítko je běžný HTML odkaz (<a>), který obsahuje platební URL a zobrazuje číslo objednávky a částku s měnou. Níže jsou čtyři vizuální návrhy — vyberte ten, který ladí s vaším webem.

1. Bitcoin oranžové

Zaplatit BitcoinemOBJ-2026-001 · 1500 CZK

<a href="https://paythat.online/pay?merchant_id=muj-eshop&order_id=OBJ-2026-001&amount=1500&currency=CZK"
   target="_blank"
   style="display: inline-flex; flex-direction: column; align-items: center; gap: 4px;
          padding: 16px 32px; border-radius: 12px; background: #f7931a; color: #0a0a0b;
          font-family: sans-serif; font-weight: 600; text-decoration: none;
          box-shadow: 0 0 16px rgba(247,147,26,.3);">
  <span style="font-size: 16px;">Zaplatit Bitcoinem</span>
  <span style="font-size: 12px; opacity: .8;">OBJ-2026-001 · 1500 CZK</span>
</a>

2. Tmavé minimální

Zaplatit BitcoinemOBJ-2026-001 · 1500 CZK

<a href="https://paythat.online/pay?merchant_id=muj-eshop&order_id=OBJ-2026-001&amount=1500&currency=CZK"
   target="_blank"
   style="display: inline-flex; flex-direction: column; align-items: center; gap: 4px;
          padding: 16px 32px; border-radius: 12px; background: #26262b; color: #fafafa;
          font-family: sans-serif; font-weight: 600; text-decoration: none;
          border: 1px solid #3a3a40;">
  <span style="font-size: 16px;">Zaplatit Bitcoinem</span>
  <span style="font-size: 12px; color: #999;">OBJ-2026-001 · 1500 CZK</span>
</a>

3. Obrysové

Zaplatit BitcoinemOBJ-2026-001 · 1500 CZK

<a href="https://paythat.online/pay?merchant_id=muj-eshop&order_id=OBJ-2026-001&amount=1500&currency=CZK"
   target="_blank"
   style="display: inline-flex; flex-direction: column; align-items: center; gap: 4px;
          padding: 16px 32px; border-radius: 12px; background: transparent; color: #f7931a;
          font-family: sans-serif; font-weight: 600; text-decoration: none;
          border: 2px solid #f7931a;">
  <span style="font-size: 16px;">Zaplatit Bitcoinem</span>
  <span style="font-size: 12px; opacity: .8;">OBJ-2026-001 · 1500 CZK</span>
</a>

4. Gradient

Zaplatit BitcoinemOBJ-2026-001 · 1500 CZK

<a href="https://paythat.online/pay?merchant_id=muj-eshop&order_id=OBJ-2026-001&amount=1500&currency=CZK"
   target="_blank"
   style="display: inline-flex; flex-direction: column; align-items: center; gap: 4px;
          padding: 16px 32px; border-radius: 12px;
          background: linear-gradient(135deg, #f7931a 0%, #e8590c 100%); color: #fff;
          font-family: sans-serif; font-weight: 600; text-decoration: none;">
  <span style="font-size: 16px;">Zaplatit Bitcoinem</span>
  <span style="font-size: 12px; opacity: .9;">OBJ-2026-001 · 1500 CZK</span>
</a>

Tip: Měňte order_id a amount dynamicky podle konkrétní objednávky. Parametr target="_blank" otevře platební stránku v nové záložce — pokud chcete platbu vložit přímo na stránce, použijte iframe z předchozí sekce.

Máte dotazy? Kontaktujte nás

FAQ