Payment Intent

Příklady z praxe

1. 01

   Vytvoření platby na serveru a potvrzení v prohlížeči

   E-shop vytvoří Payment Intent na svém backendu ve chvíli, kdy zákazník klikne na Zaplatit. Částku i měnu určuje server z dat košíku, frontend dostane pouze client secret. Prohlížeč pak platbu potvrdí a v případě potřeby zobrazí 3-D Secure okno vydavatele karty.

   // server (Node.js)
   const intent = await stripe.paymentIntents.create(
     {
       amount: 249000, // 2 490 Kč v haléřích
       currency: 'czk',
       automatic_payment_methods: { enabled: true },
       metadata: { order_id: 'OBJ-2024-1187' },
     },
     { idempotencyKey: 'OBJ-2024-1187' }
   );
   
   res.json({ clientSecret: intent.client_secret });

2. 02

   Blokace prostředků u zboží skladem na objednávku

   Prodejce nábytku peníze při objednávce jen zablokuje, protože kus se teprve dováží. Payment Intent se vytvoří s odloženým zúčtováním a zůstane v autorizovaném stavu. Ve chvíli expedice server zavolá capture, případně na část částky, pokud zákazník jednu položku stornoval. Neprovedená blokace po několika dnech sama vyprší.

   // autorizace bez stržení
   await stripe.paymentIntents.create({
     amount: 1890000,
     currency: 'czk',
     capture_method: 'manual',
   });
   
   // při expedici, klidně jen část
   await stripe.paymentIntents.capture(intentId, {
     amount_to_capture: 1590000,
   });

Časté omyly

MýtusKdyž prohlížeč po potvrzení vrátí succeeded, mám hotovo a můžu odbavit objednávku.

Ve skutečnostiOdpověď v prohlížeči je jen indikace pro uživatelské rozhraní. Zákazník může zavřít okno, ztratit signál nebo mít pomalou síť. Autoritativní je stav objektu na straně brány, který se na server dostane webhookem nebo dotazem na aktuální stav.

MýtusPro každý pokus o zaplacení jedné objednávky je potřeba nový Payment Intent.

Ve skutečnostiJeden Payment Intent zvládne několik pokusů. Když karta selže, objekt se vrátí do stavu, kdy lze připojit jinou platební metodu a potvrdit znovu. Zakládání nového objektu pro každý pokus komplikuje párování a reporting.

MýtusČástku můžu bezpečně poslat z frontendu, brána si to ohlídá.

Ve skutečnostiPayment Intent se záměrně vytváří na serveru právě proto, že částka z prohlížeče je pod kontrolou útočníka. Klientský klíč umožňuje platbu potvrdit a číst, nikoli měnit částku nebo měnu.

Časté dotazy

Jak dlouho zůstává Payment Intent platný?

Payment Intent není určený k dlouhodobému skladování. Nepotvrzený objekt brány obvykle po několika dnech neaktivity samy zruší, protože už neodpovídá aktuálnímu košíku ani ceně. U dvoufázových plateb je limit přísnější: autorizovaná blokace na kartě má omezenou životnost danou pravidly karetní asociace, typicky v řádu dnů, a pokud obchodník nestihne částku strhnout, blokace propadne a peníze se zákazníkovi uvolní. V praxi se proto objekt vytváří až ve chvíli zahájení placení, ne při vkládání zboží do košíku.

Co dělat, když se částka objednávky změní po vytvoření Payment Intentu?

Payment Intent lze aktualizovat, dokud nebyl úspěšně potvrzený. Změna částky nebo měny se tedy provede běžnou úpravou objektu na serveru, načež se prohlížeči pošle aktualizovaný stav. Jakmile platba skončí ve stavu úspěšně zaplaceno, částka už měnitelná není a rozdíl se řeší refundací nebo doplatkem jako samostatnou transakcí. U dvoufázového režimu existuje třetí možnost: strhnout jen část zablokované částky a zbytek uvolnit.

Potřebuje projekt Payment Intent, když používá hostovanou platební stránku?

Hostovaná platební stránka nebo checkout session objekt typu Payment Intent obvykle vytvoří sama na pozadí, takže vývojář s ním nemusí pracovat přímo. Práce s Payment Intentem se vyplatí tam, kde je potřeba vlastní platební formulář, dvoufázová autorizace, dělené platby marketplace nebo jemná kontrola nad opakováním neúspěšných pokusů. Pro běžný e-shop bez těchto požadavků bývá hostovaná stránka rychlejší cesta i s ohledem na PCI DSS.

Jak Payment Intent souvisí s chargebackem?

Payment Intent končí svůj životní cyklus úspěšnou platbou, chargeback přichází až potom jako samostatná událost od vydavatele karty. Identifikátor Payment Intentu ale slouží jako spojnice: reklamovaná transakce se odkazuje na konkrétní platbu, takže obchodník podle něj dohledá objednávku, doručenku i výsledek 3-D Secure ověření. Právě proto se do metadat objektu ukládá číslo objednávky, které pak výrazně zrychlí sestavení podkladů pro rozporování.

Zdroje

1. Stripe API Reference(otevře se v novém okně)Stripe
2. Payments documentation(otevře se v novém okně)Stripe
3. EMV 3-D Secure(otevře se v novém okně)EMVCo
4. Směrnice (EU) 2015/2366 o platebních službách na vnitřním trhu (PSD2)(otevře se v novém okně)Úřad pro publikace EU, 2015

Související pojmy

• 3-D Secure3-D Secure je protokol, který u online platby kartou ověří, že platí skutečně její držitel, typicky potvrzením v bankovní aplikaci. Při úspěšném ověření se zároveň přenáší odpovědnost za podvodnou transakci z obchodníka na vydavatele karty.
• ChargebackChargeback je zpětné zúčtování karetní platby, při kterém držitel karty zpochybní transakci u své banky a obchodník může přijít o původně připsané peníze. Probíhá podle pravidel karetních schémat, často přes acquirera a platební bránu, a rozhoduje se podle důkazů o autorizaci, doručení, komunikaci a případném podvodu.
• IdempotenceIdempotence je vlastnost operace, u které opakované provedení se stejnými vstupy skončí ve stejném stavu jako provedení jediné. Je to základní pojistka proti dvojímu zaúčtování, když se požadavek kvůli výpadku sítě odešle dvakrát.
• PCI DSSPCI DSS je bezpečnostní standard pro ochranu dat platebních karet, který vydává PCI Security Standards Council a vynucují ho karetní asociace jako Visa a Mastercard. Vztahuje se na každou organizaci, která údaje z karet přijímá, zpracovává, přenáší nebo ukládá, a definuje konkrétní technická i procesní pravidla včetně způsobu jejich doložení.
• WebhookWebhook je způsob, jak aplikace automaticky oznámí jiné aplikaci událost pomocí HTTP požadavku na předem zadanou adresu. Místo průběžného dotazování odešle zdrojový systém zprávu ve chvíli, kdy se něco stane, například po zaplacení objednávky, změně stavu úlohy nebo vytvoření záznamu.
• ACIDACID je sada čtyř vlastností databázové transakce: atomicity, consistency, isolation a durability. Zaručuje, že skupina zápisů proběhne jako jeden celek, neporuší definovaná pravidla databáze, nebude se nebezpečně míchat s jinými transakcemi a po potvrzení přežije pád systému, například při převodu peněz.
• AcquirerAcquirer je finanční instituce nebo platební poskytovatel, který obchodníkovi umožňuje přijímat karetní platby a předává transakce do karetních schémat. V online platbách stojí mezi platební bránou, vydavatelem karty a obchodníkem, zajišťuje autorizaci, zúčtování, vyplacení peněz a část řízení rizik.
• Adaptive IconAdaptivní ikona je formát ikony aplikace na Androidu, který se místo jedné hotové bitmapy skládá z oddělených vrstev: pozadí a popředí. Systém výsledný tvar sám ořízne podle masky výrobce zařízení a může vrstvy animovat nebo přebarvit. Vývojář tak dodá jeden zdroj a launcher z něj vytvoří kruh, čtverec i squircle.