v3 Released — BetterPayment API

One API.
Three providers.
Zero repetition.

better-payment unifies İyzico, PayTR, and Parampos under a single type-safe interface. Switch providers without rewriting your integration.

Get Started Star on GitHub
$npm install better-payment
3
Providers
1
Dependency
100%
TypeScript
MIT
License
lib/payment.ts
1
2
3
4
5
6
7
8
9
10
import { BetterPayment } from "better-payment"
 
const payment = new BetterPayment({
defaultProvider: "iyzico",
providers: { iyzico: { enabled: true }, paytr: { enabled: true } },
});
 
// Switch providers on demand — same API
await payment.use("paytr").initThreeDSPayment(opts);
await payment.use("iyzico").initThreeDSPayment(opts);▋

Works with any Node.js framework

Next.js
Express
NestJS
Fastify
Hono
Bun

The Problem

Every gateway has a
completely different API.

Switching providers means rewriting your entire payment stack — different request shapes, different error codes, different auth flows. better-payment eliminates that entirely.

integration/payments.ts
Without
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// iyzico setup
import Iyzipay from "iyzipay";
const iyzico = new Iyzipay({
apiKey: process.env.IYZICO_API_KEY,
secretKey: process.env.IYZICO_SECRET,
uri: "https://sandbox-api.iyzipay.com",
});
 
// PayTR setup (completely different API)
// ... 50+ lines of form-encoded setup
 
// Parampos setup (SOAP, totally different)
// ... another 60+ lines of config
 
// Each provider: different request shape,
// different response format, different
// error codes. Maintain 3 integrations.
lib/payment.ts
With better-payment
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import { BetterPayment } from "better-payment";
 
const payment = new BetterPayment({
defaultProvider: "iyzico",
providers: {
iyzico: { enabled: true, config: { ... } },
paytr: { enabled: true, config: { ... } },
},
});
 
// Unified API — works identically
// across every provider
await payment.use("iyzico").createPayment(opts);
await payment.use("paytr").createPayment(opts);
 
// Switch providers without any code change.
One interface for all providersTypeScript-firstUnified error handlingSwitch providers in one line

Features

Everything you need,
nothing you don't.

Unified API surface

One consistent method set across every provider. createPayment, refund, cancel — all providers respond the same way.

100% TypeScript

Full type definitions shipped out of the box. Catch payment errors at compile time, not in production.

Minimal dependencies

Only axios as a peer dependency. Keeps your bundle lean and your dependency tree clean.

Secure by default

HMAC-SHA256 signature validation, 3D Secure support, and no credential exposure in transport.

Auto HTTP handler

BetterPaymentHandler turns your config into a full REST API with zero boilerplate — drop-in for Next.js or Express.

Multi-provider switching

Configure all providers upfront, then switch at runtime with payment.use("paytr"). A/B test gateways without code changes.

All payment methods

Card, 3DS, EFT/IBAN, hosted checkout, installments, subscriptions — fully unified across the provider surface.

Subscription billing

İyzico subscription APIs — product creation, pricing plans, card update — all available through the unified handler.

Supported Providers

Three gateways,
one integration.

İyzico

İyzico

Turkey's leading gateway

Full-featured integration covering V2 auth, hosted checkout, PWI (IBAN payments), subscriptions, BIN check, and installment inquiry.

Capabilities

  • V2 Auth & 3D Secure
  • Hosted Checkout Form
  • PWI (IBAN/EFT Payments)
  • Subscription & Recurring
  • BIN Check & Installments
  • Card Tokenization

Example usage

checkout.ts
// Checkout form (hosted payment page)
const result = await payment.use("iyzico")
  .initCheckoutForm({
    price: "100.00", currency: "TRY",
    callbackUrl: "https://yoursite.com/callback",
    buyer: { ... },
    basketItems: [ ... ]
  });

Direct Bank Integrations

Native bank APIs,
zero abstraction cost.

Direct integrations with Turkish bank virtual POS systems — no third-party gateway, full control over your settlement.

Akbank

Akbank

Sanal POS · Direct Integration

Direct integration with Akbank's Sanal POS JSON API. HMAC-SHA512 signed requests, signature-verified 3D Secure (3D_PAY) callbacks, refunds, voids and order status queries — no intermediary gateway.

HMAC-SHA512

Signed requests & callbacks

2D & 3D Secure

Both flows supported

Verified Callbacks

3D results checked with your key

Direct API

No third-party middleware

View Akbank docs

Integration example

lib/akbank.ts
import { BetterPayment } from "better-payment";

const payment = new BetterPayment({
  providers: {
    akbank: {
      enabled: true,
      config: {
        merchantSafeId: process.env.AKBANK_MERCHANT_SAFE_ID!,
        terminalSafeId: process.env.AKBANK_TERMINAL_SAFE_ID!,
        secretKey:      process.env.AKBANK_SECRET_KEY!,
      },
    },
  },
});

// 3D Secure initialization
const init = await payment.akbank.initThreeDSPayment({
  price: "250.00",
  paidPrice: "250.00",
  currency: "TRY",
  conversationId: "ORDER123",
  callbackUrl: "https://yoursite.com/api/pay/akbank/payment/complete-3ds",
  paymentCard: { ... },
  buyer: { ... },
  ...
});

// Complete in callback route: pass the bank's POST body as is
const result = await payment.akbank.completeThreeDSPayment(body);

More banks coming soon

GA
Garanti BBVA
İŞ
İş Bankası
YA
Yapı Kredi
ZI
Ziraat Bankası

Quick Start

Up and running
in minutes.

01

Install the package

terminal
$ npm install better-payment
02

Configure your providers

lib/payment.ts
import { BetterPayment, ProviderType } from "better-payment";

const payment = new BetterPayment({
  defaultProvider: ProviderType.IYZICO,
  providers: {
    iyzico: {
      enabled: true,
      config: {
        apiKey: process.env.IYZICO_API_KEY!,
        secretKey: process.env.IYZICO_SECRET_KEY!,
        baseUrl: process.env.IYZICO_BASE_URL!,
      },
    },
  },
});

export default payment;
03

Process your first payment

app/checkout.ts
import payment from "@/lib/payment";

// Unified API — works identically for every provider
const result = await payment.createPayment({
  price: "100.00",
  currency: "TRY",
  buyer: { id: "usr-123", ... },
  basketItems: [ ... ],
});

// Or switch to a different provider at runtime
const checkout = await payment.use("paytr").initThreeDSPayment({ ... });
View full documentation→

Open Source · MIT License

Stop rewriting
payment logic.

One package, three providers, full TypeScript support. Install once and unify your entire Turkish payment stack.

$npm install better-payment
Read the Docs View on GitHub