A unified, type-safe payment gateway library for Node.js — 13 global and regional payment providers behind one API.

payfyio is a unified payment gateway library that lets you integrate 13 payment providers — global gateways (Stripe, PayPal), crypto and hosted checkout (Coinbase, Polar, Lemon Squeezy), Turkish gateways (İyzico, PayTR, Parampos), and five Turkish bank Virtual POS integrations (Akbank, Garanti, İş Bankası, Yapı Kredi, Ziraat) — through a single, consistent TypeScript API.

Why payfyio?

Every payment provider has its own SDK, request format, authentication scheme, and error model. Switching providers or supporting multiple ones requires writing adapter code for each. payfyio abstracts all of that.

Single API

One interface for all providers — createPayment, refund, cancel work the same regardless of which provider processes the transaction.

Type-Safe

Full TypeScript types for every request and response. No more guessing at field names or response shapes.

Framework Agnostic

Built-in HTTP handler works with any Node.js framework. Native integrations for Next.js, Express, and more.

Multi-Provider

Use multiple providers simultaneously. Route specific payment methods to specific providers.

Supported Providers

Card gateways (direct & 3D Secure)

Provider	2D Payment	3D Secure	Refund	Cancel	Installment
İyzico	✅	✅	✅	✅	✅
PayTR	⚠️	✅	✅	⚠️	✅
Parampos	✅	✅	✅	✅	❌
Stripe	✅	✅	✅	✅	❌
PayPal	⚠️	✅	✅	✅	❌

Turkish bank Virtual POS

Akbank, Garanti BBVA, İş Bankası, Yapı Kredi, and Ziraat Bankası — direct card and 3D Secure through the same contract.

⚠️ Bank 3DS verification: Garanti, İş Bankası, Yapı Kredi, and Ziraat completeThreeDSPayment currently fail closed (return failure) until per-bank response-hash verification is implemented against each bank's sandbox. See the security notes before enabling them in production.

Hosted checkout (redirect / crypto / merchant-of-record)

Provider	Flow	Refund	Cancel	Notes
Coinbase	Hosted crypto charge	❌ (dashboard)	✅	BTC · ETH · USDC, hosted-only
Polar	Hosted checkout	✅	✅	Digital products & subscriptions
Lemon Squeezy	Hosted checkout	✅	⚠️	Merchant-of-record — tax collected & remitted

⚠️ PayTR Cancel: PayTR does not support voids. cancel() returns an error; use refund() with the original amount instead. PayTR and PayPal are 3DS/hosted flows — direct 2D card charge is not their primary path.

Hosted providers (Coinbase, Polar, Lemon Squeezy) are redirect flows — createPayment (direct card) is intentionally unsupported; use initThreeDSPayment to create the hosted checkout.

Quick Example

import { Payfyio, ProviderType } from '@fyio/payfyio';

const payment = new Payfyio({
  defaultProvider: ProviderType.IYZICO,
  providers: {
    iyzico: {
      enabled: true,
      config: {
        apiKey: process.env.IYZICO_API_KEY!,
        secretKey: process.env.IYZICO_SECRET_KEY!,
        baseUrl: 'https://sandbox-api.iyzipay.com',
      },
    },
  },
});

const result = await payment.createPayment({
  price: '100.00',
  paidPrice: '100.00',
  currency: Currency.TRY,
  buyer: { /* ... */ },
  shippingAddress: { /* ... */ },
  billingAddress: { /* ... */ },
  basketItems: [{ /* ... */ }],
  paymentCard: { /* ... */ },
});

Introduction