better-payment
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 authorize hook.
  • 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, with merchant_salt appended to the signed data. user_basket is base64 JSON with TL prices. merchant_oid must be alphanumeric. test_mode follows sandbox mode. Refund amounts are in TL. Status queries use /odeme/durum-sorgu. Notifications are answered with plain OK. 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 use TP_Islem_Iptal_Iade_Kismi2, status queries TP_Islem_Sorgulama4 and BIN lookups BIN_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 requires mdStatus=1. retrieveSubscription uses GET.

Breaking changes (compared with 3.x)

AreaBeforeNow
PayTR configapiKey, secretKey, merchantId, merchantSaltmerchantId, merchantKey, merchantSalt, testMode?
Akbank configmerchantId, terminalId, storeKey, …merchantSafeId, terminalSafeId, secretKey
Parampos configalso required apiKey/secretKeyclientCode, clientUsername, clientPassword, guid
paymentId (PayTR/Akbank/Parampos)provider token / transaction GUIDyour order id
Timeoutsfailurepending + errorCode: 'NETWORK_ERROR'
Handlerevery route public, always HTTP 200opt-in routes, authorize, 422 on failure
Unsupported currencysilently TRYerror

On this page