payfyio
Providers

İyzico

Full İyzico integration reference — payments, checkout forms, subscriptions, and more.

İyzico is a Turkish payment provider with a REST/JSON API and HMAC-SHA256 authentication.

Getting your credentials

  1. Sign up / sign in to the İyzico Merchant Panel (sandbox: sandbox-merchant.iyzipay.com).
  2. Go to Settings → API Keys (Ayarlar → API Anahtarları).
  3. Copy the API key and Secret key:
    • apiKeyAPI key
    • secretKeySecret key

Sandbox and production have separate panels and separate keys; match them to the mode you pass.

Configuration

iyzico: {
  enabled: true,
  config: {
    apiKey: process.env.IYZICO_API_KEY!,
    secretKey: process.env.IYZICO_SECRET_KEY!,
    locale: 'tr', // optional, default: 'tr'
  },
}

baseUrl defaults to https://sandbox-api.iyzipay.com (sandbox mode) or https://api.iyzipay.com (production mode).

Direct Payment (2D)

const result = await payment.iyzico.createPayment({
  price: '100.00',
  paidPrice: '100.00',
  currency: Currency.TRY,
  installment: 1,
  paymentCard: { cardHolderName, cardNumber, expireMonth, expireYear, cvc },
  buyer: { id, name, surname, email, identityNumber, ip, /* ... */ },
  shippingAddress: { contactName, city, country, address },
  billingAddress: { contactName, city, country, address },
  basketItems: [{ id, name, category1, itemType, price }],
});

3D Secure

Initialize:

const init = await payment.iyzico.initThreeDSPayment({
  ...paymentRequest,
  callbackUrl: 'https://yoursite.com/payment/callback',
});
// Redirect user to: init.htmlContent (rendered in iframe or redirect)

Complete (in callback endpoint):

const result = await payment.iyzico.completeThreeDSPayment({
  paymentId: body.paymentId,
  conversationId: body.conversationId,
});

Checkout Form

İyzico's hosted checkout form — no PCI DSS scope for card data.

// Initialize
const form = await payment.iyzico.initCheckoutForm({
  ...paymentRequest,
  callbackUrl: 'https://yoursite.com/checkout/callback',
  enabledInstallments: [1, 2, 3, 6, 9],
});
// form.checkoutFormContent — embed as HTML
// form.token — save for retrieve step

// Retrieve result (in callback)
const result = await payment.iyzico.retrieveCheckoutForm({
  token: body.token,
});

Handler endpoints:

  • POST /api/pay/iyzico/checkout/init
  • POST /api/pay/iyzico/checkout/retrieve

PWI (Protected Wire Transfer)

İyzico's bank transfer payment method.

const init = await payment.iyzico.initPWIPayment({ ...request });
const result = await payment.iyzico.retrievePWIPayment({ token: init.token });

Handler endpoints:

  • POST /api/pay/iyzico/pwi/init
  • POST /api/pay/iyzico/pwi/retrieve

Installment Info

Query available installment options for a BIN.

const info = await payment.iyzico.installmentInfo({
  binNumber: '552879',
  price: '100.00',
  currency: 'TRY',
});
// info.installmentDetails[].installmentPrices[]

Handler endpoint: POST /api/pay/iyzico/installment

BIN Check

const bin = await payment.iyzico.binCheck('552879');
// bin.cardType, bin.cardAssociation, bin.cardFamily

Handler endpoint: POST /api/pay/iyzico/bin-check

Refund & Cancel

// refund takes the payment id (sent to İyzico as paymentTransactionId) + ip.
await payment.iyzico.refund({
  paymentId: 'transaction-id',
  price: '50.00',
  currency: 'TRY',
  ip: '85.34.78.112',
});

await payment.iyzico.cancel({ paymentId: 'payment-id', ip: '85.34.78.112' });

Subscriptions (v2 API)

İyzico's full subscription management API.

// Initialize subscription
await payment.iyzico.initializeSubscription({ /* ... */ });

// Manage
await payment.iyzico.cancelSubscription({ subscriptionReferenceCode });
await payment.iyzico.upgradeSubscription({ /* ... */ });
await payment.iyzico.retrieveSubscription({ subscriptionReferenceCode });
await payment.iyzico.updateSubscriptionCard({ /* ... */ });

// Product & pricing plan management
await payment.iyzico.createSubscriptionProduct({ name, description });
await payment.iyzico.createPricingPlan({ productReferenceCode, /* ... */ });

Handler endpoints:

  • POST /api/pay/iyzico/subscription/initialize
  • POST /api/pay/iyzico/subscription/cancel
  • POST /api/pay/iyzico/subscription/upgrade
  • POST /api/pay/iyzico/subscription/retrieve
  • POST /api/pay/iyzico/subscription/card-update
  • POST /api/pay/iyzico/subscription/product
  • POST /api/pay/iyzico/subscription/pricing-plan

Testing

Set mode: 'sandbox' and use your sandbox panel keys. İyzico publishes test cards in its sandbox docs — e.g. 5528790000000008 (Halkbank, success). Run a 3D Secure init, complete the challenge page, then confirm completeThreeDSPayment returns success. Successful test charges appear in the sandbox merchant panel.

On this page