Introduction
A unified, type-safe payment gateway library for Node.js and Turkish payment providers.
Better Payment lets you integrate Turkish payment providers — iyzico, PayTR, Akbank, Parampos, Sipay, Kuveyt Türk and the EST banks (İş Bankası, Ziraat, Halkbank, TEB, Şekerbank) — through one TypeScript API.
0.0.1 is a fresh start. The version history was reset. Releases 1.x–3.x contained incorrect provider integrations and callback checks that could be bypassed, and are deprecated. Read What's New in 0.0.1 for what changed and how to migrate.
Why Better Payment?
Every payment provider has its own SDK, request format, signature scheme and error model. Better Payment hides those differences behind one interface.
Single API
createPayment, initThreeDSPayment, refund, cancel and getPayment work the same way for every provider.
Verified callbacks
3D Secure callbacks are checked with your own credentials before any result is trusted.
Secure HTTP handler
Framework-agnostic handler that exposes only what you enable, with authorize and server-side amount hooks.
Multi-Provider
Enable several providers at once and pick one per request.
Plugins
Payment events, provider routing and more come as plugins. Write your own in a few lines.
Supported Providers
| Provider | Non-3D | 3D Secure | Refund | Cancel | Status | BIN | Installments |
|---|---|---|---|---|---|---|---|
| iyzico | |||||||
| PayTR | ¹ | iFrame | ² | ||||
| Akbank | 3D_PAY | — | — | ||||
| Parampos | (TRY) | ||||||
| Sipay | ⁴ | paySmart3D | ⁴ | ||||
| Kuveyt Türk | — | KT Pay Gate | ³ | — | — | ||
| EST (İş Bankası, Ziraat, Halkbank, TEB, Şekerbank) | 3D / 3D Pay / 3D Host | — | — |
¹ Your PayTR account must be approved for non-3D payments.
² PayTR has no void endpoint, so cancel() issues a full refund.
³ Kuveyt Türk cancels on the same day, before end of day; after that, use refund().
⁴ Sipay has no void endpoint: cancel() refunds the rest of the payment, which Sipay processes as a void on the same day. Sipay must also approve your account for non-3D payments.
Quick Example
import { betterPayment, iyzico } from 'better-payment';
const payment = betterPayment({
mode: 'sandbox',
providers: {
iyzico: iyzico({
apiKey: process.env.IYZICO_API_KEY!,
secretKey: process.env.IYZICO_SECRET_KEY!,
}),
},
});
const result = await payment.initThreeDSPayment({
price: '100.00',
paidPrice: '100.00',
currency: 'TRY',
basketId: 'B1',
callbackUrl: 'https://yoursite.com/api/pay/iyzico/payment/complete-3ds',
paymentCard: { /* ... */ },
buyer: { /* ... */ },
shippingAddress: { /* ... */ },
billingAddress: { /* ... */ },
basketItems: [{ /* ... */ }],
});
// Render result.threeDSHtmlContent in the customer's browser