iyzico Payment Gateway Node.js Client

2.0.67 verified Sat May 09 auth: no javascript

iyzipay is the official Node.js client for the iyzico payment gateway, used for processing online payments primarily in Turkey. Version 2.0.67 is the latest stable release, with frequent updates (many releases per year) and long-term support for Node.js v0.10.0+. It supports all iyzico API features including payment creation, recurring billing, refunds, and 3D secure. Key differentiators vs alternative Turkish payment libraries include official maintenance by iyzico, broad coverage of iyzico API endpoints, and built-in support for sandbox and production environments. The package uses callbacks, not Promises or async/await, and configures credentials either via constructor options or environment variables.

Common errors

error Error: Cannot find module 'iyzipay' ↓

cause Package not installed or require path wrong.

fix

Run 'npm install iyzipay' and ensure no type in the require statement.

error TypeError: iyzipay.payment.create is not a function ↓

cause Forgot to call 'new Iyzipay()' before using the instance.

fix

Correct initialization: const iyzipay = new Iyzipay({...});

error Error: Unauthorized. Check your API key and secret key. ↓

cause Credentials are invalid or missing.

fix

Double-check apiKey and secretKey in constructor or environment variables.

error RequestError: getaddrinfo ENOTFOUND sandbox-api.iyzipay.com ↓

cause Invalid URI or network issue.

fix

Ensure uri exactly is 'https://sandbox-api.iyzipay.com' or correct production URL.

Warnings

gotcha All monetary amounts must be strings, not numbers (e.g., '1' not 1). ↓

fix Always pass price, paidPrice, etc. as strings, e.g., '1.00'.

gotcha The package uses callbacks, not Promises. No promise support or async/await built-in. ↓

fix Wrap calls in a Promise or use util.promisify.

deprecated Node.js v0.10.0 is no longer supported by Node.js itself; the package may still work but security updates are missing. ↓

fix Upgrade Node.js to a maintained version (>=10.x recommended).

gotcha Using Iyzipay() without credentials will fail silently if env vars are not set. ↓

fix Always provide apiKey, secretKey, and uri explicitly or ensure environment variables are set.

gotcha Some fields (e.g., identityNumber) have length or format constraints; invalid values cause non-descriptive errors. ↓

fix Refer to iyzico API documentation for required formats.

gotcha The library does not include TypeScript definitions; types must be manually added. ↓

fix Use a .d.ts file or import from @types/iyzipay if available (none currently).

breaking Version 2.0 changed the constructor options format; old v1 options (api_key) no longer work. ↓

fix Use camelCase option names: apiKey, secretKey, uri instead of api_key, secret_key, etc.

Install

npm install iyzipay

yarn add iyzipay

pnpm add iyzipay

Imports

Iyzipay
wrong
```
import Iyzipay from 'iyzipay';
```
correct
```
const Iyzipay = require('iyzipay');
```
This package is CommonJS only; ES module import will fail.

Iyzipay (instance)

wrong

new Iyzipay(); // without env vars, credentials will be undefined

correct

const iyzipay = new Iyzipay({ apiKey: '...', secretKey: '...', uri: 'https://sandbox-api.iyzipay.com' });

If no options are passed, defaults are read from environment variables IYZIPAY_API_KEY, IYZIPAY_SECRET_KEY, IYZIPAY_URI.

Iyzipay.LOCALE.TR
wrong
```
locale: 'TR'
```
correct
```
locale: Iyzipay.LOCALE.TR
```
Use the constants from the Iyzipay constructor; raw strings may not be accepted by all API versions.

Quickstart

Initializes the client with environment variables and creates a payment request using test card information.

const Iyzipay = require('iyzipay');

const iyzipay = new Iyzipay({
  apiKey: process.env.IYZIPAY_API_KEY ?? 'your api key',
  secretKey: process.env.IYZIPAY_SECRET_KEY ?? 'your secret key',
  uri: process.env.IYZIPAY_URI ?? 'https://sandbox-api.iyzipay.com'
});

const request = {
  locale: Iyzipay.LOCALE.TR,
  conversationId: '123456789',
  price: '1',
  paidPrice: '1.2',
  currency: Iyzipay.CURRENCY.TRY,
  installment: '1',
  basketId: 'B67832',
  paymentChannel: Iyzipay.PAYMENT_CHANNEL.WEB,
  paymentGroup: Iyzipay.PAYMENT_GROUP.PRODUCT,
  paymentCard: {
    cardHolderName: 'John Doe',
    cardNumber: '5528790000000008',
    expireMonth: '12',
    expireYear: '2030',
    cvc: '123',
    registerCard: '0'
  },
  buyer: {
    id: 'BY789',
    name: 'John',
    surname: 'Doe',
    gsmNumber: '+905350000000',
    email: 'email@email.com',
    identityNumber: '74300864791',
    lastLoginDate: '2015-10-05 12:43:35',
    registrationDate: '2013-04-21 15:12:09',
    registrationAddress: 'Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1',
    ip: '85.34.78.112',
    city: 'Istanbul',
    country: 'Turkey',
    zipCode: '34732'
  },
  shippingAddress: {
    contactName: 'Jane Doe',
    city: 'Istanbul',
    country: 'Turkey',
    address: 'Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1',
    zipCode: '34742'
  },
  billingAddress: {
    contactName: 'Jane Doe',
    city: 'Istanbul',
    country: 'Turkey',
    address: 'Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1',
    zipCode: '34742'
  },
  basketItems: [
    { id: 'BI101', name: 'Binocular', category1: 'Collectibles', category2: 'Accessories', itemType: Iyzipay.BASKET_ITEM_TYPE.PHYSICAL, price: '0.3' },
    { id: 'BI102', name: 'Game code', category1: 'Game', category2: 'Online Game Items', itemType: Iyzipay.BASKET_ITEM_TYPE.VIRTUAL, price: '0.5' },
    { id: 'BI103', name: 'Usb', category1: 'Electronics', category2: 'Usb / Cable', itemType: Iyzipay.BASKET_ITEM_TYPE.PHYSICAL, price: '0.2' }
  ]
};

iyzipay.payment.create(request, function (err, result) {
  if (err) console.error(err);
  else console.log(result);
});