[hegedustibor]

Mi változott

A csomag eddig több végponton nem azokat a mezőket küldte, amelyeket a hivatalos SimplePay SDK és dokumentáció vár; ezek egy része valószínűleg nem is működhetett. Mostantól minden kérés a hivatalos minták mezőneveit követi:

• Fizetés indítása (start): a szállítási díj shippingCost néven megy, eddig shippingPrice volt, így a SimplePay nem adta hozzá a fizetendő összeghez. A tétel leírása desc néven megy, eddig description volt.
• Minden kérés: sdkVersion megy (12 kérésből hiányzott, az AutoPayment pedig más értéket küldött). A kártya és a token lekérdezése és törlése currency-t is küld.
• OneClick (do): cardSecret, type, threeDSReqAuthMethod, browser és methods. A nem létező transactionId nem kerül a kérésbe.
• Ismétlődő fizetés (dorecurring): bekerült a token, amely eddig hiányzott, így a kártya nem volt azonosítható. Token nélkül a kérés már elküldés előtt InvalidArgumentException-t dob. A kártyaregisztráló start válaszának tokenjei mostantól a $response->tokens-ben elérhetők, eddig a csomag eldobta őket.
• AutoPayment: a böngészőadat browser kulccsal és a hivatalos mezőnevekkel megy, ip-vel kiegészítve. Új mezők: url, threeDSReqAuthMethod, language.
• Request to Pay:
  • start: language, deadline, additionalInfo. A határidő alapértéke a hivatalos minta szerinti 2 óra 5 perc, megadott timeout esetén annyi másodperc; eddig a kártyás fizetés 10 perces timeoutja volt. A RTP-nél nem értelmezett timeout mező már nem megy;
  • köteg: packageRef és transactions;
  • query: transactionIds, orderRefs vagy packageRef;
  • refund: refundTotal, originalTotal, currency;
  • reverse: currency.
• Apple Pay: a start domain-t (alapból az app.url hostja), language-et és timeout-ot küld, a do a tokent applePayToken kulccsal. Ha a domain nem állapítható meg, a kérés érthető InvalidArgumentException-t dob, ahelyett hogy a kötelező mező csendben kimaradna.
• qvik: eamType (alapból 1, QR), language, timeout.
• Naplózás: bekapcsolt SIMPLEPAY_LOG_CHANNEL mellett a naplóba már nem kerül kártyaszám, lejárat, CVC, cardSecret és token.

A változás visszafelé kompatibilis, ezért v2.1.0 lehet. A meglévő paraméterek maradnak; a do- és a recurring-kérés transactionId-je elavult, ?int lett, és nem kerül a kérésbe. Az új mezők opcionálisak.

Ellenőrzés

• A composer test zöld PHP 8.4-en, Laravel 13 alatt: Larastan 0 hiba, Pint, 100%-os típuslefedettség, 110 teszt.
• Az új RequestPayloadTest végpontonként a hivatalos mintákhoz rögzíti a mezőket; a javítás előtt mind elbukott. A változás nélkül ezek elbuknak.
• Reflection-alapú szkripttel ellenőriztem a dokumentált hívásokat. A két nyitott PR helyben próbamerge-elve ütközés nélkül egyesül, és együtt minden példa létező, kötelező paramétereket használ.
• A független review (reviewer agent) blokkoló hibát nem talált. Jelzett még négy eltérést (shippingCost, desc, az RTP határideje, az Apple Pay domain), ezeket elbukó tesztekkel kezdve javítottam.
• Nem ellenőriztem valódi SimplePay sandbox-hívással, mert nincs hozzáférésem; a mezők a hivatalos SDK-minták és dokumentáció alapján készültek. Kiadás előtt érdemes sandboxban kipróbálni a OneClick, a recurring, az AutoPayment, az RTP és az Apple Pay hívásokat. A CI-mátrixot az első futás mutatja meg.

Megjegyzések a review-hoz

• Hivatkozások:
  • Payment SDK 2.1.5: a Base::prepare() minden hívásba sdkVersion-t tesz;
  • CardStorage SDK 1.3: do.php, dorecurring.php;
  • AutoPayment SDK 2.4: auto.php;
  • RTP SDK 0.9: rtpstart.php, rtpdo.php, rtpquery.php, rtprefund.php.
• Alapértékek:
  • az RTP start deadline-ja 2 óra 5 perc, vagy megadott timeout esetén annyi másodperc, mint a hivatalos mintában;
  • az RTP köteg deadline-ja 30 nap, mint a hivatalos mintában;
  • a packageRef-et a csomag generálja, ha nincs megadva;
  • az Apple Pay domain az app.url hostja.
• A token nélküli RecurringRequest és a domain nélküli ApplePayStartRequest InvalidArgumentException-t dob. Ez viselkedésváltozás, de ezek a kérések eddig sem működhettek; a release notes-ba is bekerül.
• Nyitva maradt, sandbox nélkül nem eldönthető pontok:
  • Az RTP query currency nélkül megy, a dokumentáció mintája szerint. A hivatalos SDK a merchantAccount alapján visszaírja.
  • Az RTP refund originalTotal-ja opcionális maradt, hogy a meglévő hívások ne törjenek; a hivatalos minta mindig küldi, ezért a példák is így mutatják.
  • Az Apple Pay start url-t, a do orderRef-et is küld; ez a korábbi viselkedés, a dokumentáció mintájában nem szerepel.
• A dokumentáció érintett részei (kártyatárolás, recurring, Apple Pay, AutoPayment, qvik, RTP) ebben a PR-ben frissültek, a többi példa a Fix documented examples that do not match the package API #4 PR-ben javul. A kettő ütközés nélkül egyesül.