Guides
Changelog
Release history and breaking changes for better-payment.
The version history was reset. 0.0.1 is the first release of the reworked package. Releases 1.x–3.x had incorrect provider integrations and callback checks that could be bypassed. Do not use them. See What's New in 0.0.1 for the reasoning and a step-by-step migration guide.
0.0.1
Security
- Parampos: the 3D callback hash is verified only with the GUID from your configuration. Earlier versions read the GUID from the callback payload, which let anyone forge a successful payment.
- Parampos / Akbank: a 3D callback no longer counts as a successful payment on its own. Parampos finalizes with
TP_WMD_Pay; Akbank uses the 3D_PAY model with an HMAC-signed result. A missing result code is no longer treated as success. - HTTP handler: secure by default. By default it exposes only callbacks and card queries. Refund, cancel, payment lookup and subscription management require an
authorizehook. - Retries only re-send idempotent requests, so a timeout can no longer cause a double charge or double refund.
- Signatures are compared in constant time.
Provider fixes
- PayTR: requests are signed with
merchant_key, withmerchant_saltappended to the signed data.user_basketis base64 JSON with TL prices.merchant_oidmust be alphanumeric.test_modefollows sandbox mode. Refund amounts are in TL. Status queries use/odeme/durum-sorgu. Notifications are answered with plainOK. Secrets are no longer sent in request bodies. - Parampos: uses
TP_WMD_UCD/TP_WMD_Pay, comma-decimal amounts and the documented hash. Refunds and cancels useTP_Islem_Iptal_Iade_Kismi2, status queriesTP_Islem_Sorgulama4and BIN lookupsBIN_SanalPos. Made-up installment rates were removed. - Akbank: rewritten against the Akbank Sanal POS JSON API.
- iyzico: Checkout Form and PWI results report the payment's own status (
paymentStatus). 3DS completion requiresmdStatus=1.retrieveSubscriptionuses GET.
Breaking changes (compared with 3.x)
| Area | Before | Now |
|---|---|---|
| PayTR config | apiKey, secretKey, merchantId, merchantSalt | merchantId, merchantKey, merchantSalt, testMode? |
| Akbank config | merchantId, terminalId, storeKey, … | merchantSafeId, terminalSafeId, secretKey |
| Parampos config | also required apiKey/secretKey | clientCode, clientUsername, clientPassword, guid |
paymentId (PayTR/Akbank/Parampos) | provider token / transaction GUID | your order id |
| Timeouts | failure | pending + errorCode: 'NETWORK_ERROR' |
| Handler | every route public, always HTTP 200 | opt-in routes, authorize, 422 on failure |
| Unsupported currency | silently TRY | error |