{"id":27879,"library":"iyzipay","title":"iyzico Payment Gateway Node.js Client","description":"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.","status":"active","version":"2.0.67","language":"javascript","source_language":"en","source_url":"https://github.com/iyzico/iyzipay-node","tags":["javascript","iyzico","iyzipay","iyzico.com","iyzipay node.js","iyzipay api","iyzipay api node.js client","iyzipay api node.js","payment processing"],"install":[{"cmd":"npm install iyzipay","lang":"bash","label":"npm"},{"cmd":"yarn add iyzipay","lang":"bash","label":"yarn"},{"cmd":"pnpm add iyzipay","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for running tests; dev dependency but required to run sample/test scripts.","package":"mocha","optional":true}],"imports":[{"note":"This package is CommonJS only; ES module import will fail.","wrong":"import Iyzipay from 'iyzipay';","symbol":"Iyzipay","correct":"const Iyzipay = require('iyzipay');"},{"note":"If no options are passed, defaults are read from environment variables IYZIPAY_API_KEY, IYZIPAY_SECRET_KEY, IYZIPAY_URI.","wrong":"new Iyzipay(); // without env vars, credentials will be undefined","symbol":"Iyzipay (instance)","correct":"const iyzipay = new Iyzipay({ apiKey: '...', secretKey: '...', uri: 'https://sandbox-api.iyzipay.com' });"},{"note":"Use the constants from the Iyzipay constructor; raw strings may not be accepted by all API versions.","wrong":"locale: 'TR'","symbol":"Iyzipay.LOCALE.TR","correct":"locale: Iyzipay.LOCALE.TR"}],"quickstart":{"code":"const Iyzipay = require('iyzipay');\n\nconst iyzipay = new Iyzipay({\n  apiKey: process.env.IYZIPAY_API_KEY ?? 'your api key',\n  secretKey: process.env.IYZIPAY_SECRET_KEY ?? 'your secret key',\n  uri: process.env.IYZIPAY_URI ?? 'https://sandbox-api.iyzipay.com'\n});\n\nconst request = {\n  locale: Iyzipay.LOCALE.TR,\n  conversationId: '123456789',\n  price: '1',\n  paidPrice: '1.2',\n  currency: Iyzipay.CURRENCY.TRY,\n  installment: '1',\n  basketId: 'B67832',\n  paymentChannel: Iyzipay.PAYMENT_CHANNEL.WEB,\n  paymentGroup: Iyzipay.PAYMENT_GROUP.PRODUCT,\n  paymentCard: {\n    cardHolderName: 'John Doe',\n    cardNumber: '5528790000000008',\n    expireMonth: '12',\n    expireYear: '2030',\n    cvc: '123',\n    registerCard: '0'\n  },\n  buyer: {\n    id: 'BY789',\n    name: 'John',\n    surname: 'Doe',\n    gsmNumber: '+905350000000',\n    email: 'email@email.com',\n    identityNumber: '74300864791',\n    lastLoginDate: '2015-10-05 12:43:35',\n    registrationDate: '2013-04-21 15:12:09',\n    registrationAddress: 'Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1',\n    ip: '85.34.78.112',\n    city: 'Istanbul',\n    country: 'Turkey',\n    zipCode: '34732'\n  },\n  shippingAddress: {\n    contactName: 'Jane Doe',\n    city: 'Istanbul',\n    country: 'Turkey',\n    address: 'Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1',\n    zipCode: '34742'\n  },\n  billingAddress: {\n    contactName: 'Jane Doe',\n    city: 'Istanbul',\n    country: 'Turkey',\n    address: 'Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1',\n    zipCode: '34742'\n  },\n  basketItems: [\n    { id: 'BI101', name: 'Binocular', category1: 'Collectibles', category2: 'Accessories', itemType: Iyzipay.BASKET_ITEM_TYPE.PHYSICAL, price: '0.3' },\n    { id: 'BI102', name: 'Game code', category1: 'Game', category2: 'Online Game Items', itemType: Iyzipay.BASKET_ITEM_TYPE.VIRTUAL, price: '0.5' },\n    { id: 'BI103', name: 'Usb', category1: 'Electronics', category2: 'Usb / Cable', itemType: Iyzipay.BASKET_ITEM_TYPE.PHYSICAL, price: '0.2' }\n  ]\n};\n\niyzipay.payment.create(request, function (err, result) {\n  if (err) console.error(err);\n  else console.log(result);\n});","lang":"javascript","description":"Initializes the client with environment variables and creates a payment request using test card information."},"warnings":[{"fix":"Always pass price, paidPrice, etc. as strings, e.g., '1.00'.","message":"All monetary amounts must be strings, not numbers (e.g., '1' not 1).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Wrap calls in a Promise or use util.promisify.","message":"The package uses callbacks, not Promises. No promise support or async/await built-in.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade Node.js to a maintained version (>=10.x recommended).","message":"Node.js v0.10.0 is no longer supported by Node.js itself; the package may still work but security updates are missing.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Always provide apiKey, secretKey, and uri explicitly or ensure environment variables are set.","message":"Using Iyzipay() without credentials will fail silently if env vars are not set.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refer to iyzico API documentation for required formats.","message":"Some fields (e.g., identityNumber) have length or format constraints; invalid values cause non-descriptive errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use a .d.ts file or import from @types/iyzipay if available (none currently).","message":"The library does not include TypeScript definitions; types must be manually added.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Use camelCase option names: apiKey, secretKey, uri instead of api_key, secret_key, etc.","message":"Version 2.0 changed the constructor options format; old v1 options (api_key) no longer work.","severity":"breaking","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Run 'npm install iyzipay' and ensure no type in the require statement.","cause":"Package not installed or require path wrong.","error":"Error: Cannot find module 'iyzipay'"},{"fix":"Correct initialization: const iyzipay = new Iyzipay({...});","cause":"Forgot to call 'new Iyzipay()' before using the instance.","error":"TypeError: iyzipay.payment.create is not a function"},{"fix":"Double-check apiKey and secretKey in constructor or environment variables.","cause":"Credentials are invalid or missing.","error":"Error: Unauthorized. Check your API key and secret key."},{"fix":"Ensure uri exactly is 'https://sandbox-api.iyzipay.com' or correct production URL.","cause":"Invalid URI or network issue.","error":"RequestError: getaddrinfo ENOTFOUND sandbox-api.iyzipay.com"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}