Stripe

Poskytovateľ Stripe (id stripe) overuje podpisy webhookov natívne — HMAC-SHA256 nad t.payload z hlavičky Stripe-Signature, porovnanie v konštantnom čase a konfigurovateľná tolerancia časovej pečiatky — a REST objekty číta s pripnutou verziou API:

use RoundlyConsulting\Purchases\Providers\Stripe\Stripe;

$stripe = app(Stripe::class);

$event = $stripe->notification($request);   // verifies Stripe-Signature, returns StripeEvent
$event->type;                               // EventType, e.g. EventType::InvoicePaid
$event->object;                             // array — the event's data.object

$stripe->paymentIntent('pi_123');           // PaymentIntent
$stripe->subscription('sub_123');           // Subscription
$stripe->session('cs_123');                 // CheckoutSession
$stripe->invoice('in_123');                 // Invoice

Podporované udalosti

Stavy predplatného

Platby za predplatné sa neukladajú ako nákupy: Checkout v režime subscription alebo setup a faktúra predplatného sa len zaznamenajú do auditu a stav predplatného určujú jeho vlastné udalosti customer.subscription.*. Tie nesú začiatok a koniec aktuálneho obdobia a koniec skúšobného obdobia; cenu nenesú. Len do auditu sa zaznamená aj PaymentIntent, ktorý uhrádza akúkoľvek faktúru — obnova patrí k svojmu predplatnému a jednorazová faktúra sa už raz uložila z invoice.paid.

Ktorú faktúru PaymentIntent uhrádza

Od verzie API 2025-03-31 (vrátane pripnutej 2026-05-27.dahlia) PaymentIntent už neuvádza, ktorú faktúru uhrádza, preto sa balík pri udalosti payment_intent.* bez poľa invoice opýta Invoice Payments API v Stripe (GET /v1/invoice_payments). Na to potrebuje PURCHASES_STRIPE_SECRET: bez neho sa taká udalosť odmietne (VerificationException, routa vráti 400, takže ju Stripe zopakuje), namiesto hádania — odhad by každú obnovu uložil ako nový jednorazový nákup.

Spory

Spor je chargeback len dovtedy, kým sú peniaze preč: otázka (warning_*) ani charge.dispute.updated nič nezmenia a prehratý spor zostane jediným chargebackom zaznamenaným pri charge.dispute.created (kľúčovaným podľa id sporu). Spor uzavretý ako vyhraný aktualizuje ten istý záznam a obnoví refundovaný nákup, s ktorým bol prepojený (PurchaseCompleted) — vlastné údaje o platbe sa zachovajú a obnoví sa len nákup, ktorý balík uložil: vyhraný spor platby, z ktorej nikdy nevznikol Purchase (napríklad obnovy predplatného), žiadny nevytvorí a nič nespustí.

Callbacky z klienta

Stripe::callback() načíta Checkout Session zo vstupu session_id alebo PaymentIntent zo vstupu payment_intent — praktické na stránke po úspešnom presmerovaní:

// GET /checkout/success?session_id=cs_123
$session = app(Stripe::class)->callback($request);   // CheckoutSession (PaymentIntent for ?payment_intent=pi_123)

$session->paymentStatus;   // 'paid'
$session->amountTotal;     // ?Money
$session->subscription;    // ?string — the subscription id, for subscription checkouts

Špeciálne meny

Sumy sa čítajú v najmenšej jednotke meny Stripe a preškálujú sa tam, kde sa Stripe odchyľuje od ISO 4217 — ISK a UGX prichádzajú s dvoma desatinnými miestami, MGA bez nich (StripeAmount::SCALE_EXCEPTIONS). Float alebo zlomková suma v reťazci sa odmietne, nikdy sa neoreže.