medusa-payment-iyzico

iyzico payment provider for Medusa v2 with full 3DS (3-Domain Secure) support.

Quick Start

npm install medusa-payment-iyzico

Then in your medusa-config.ts:

import { IyzicoPaymentService } from "medusa-payment-iyzico"

module.exports = defineConfig({
  // ... other config
  modules: {
    payment: {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: IyzicoPaymentService,
            options: {
              apiKey: process.env.IYZICO_API_KEY,
              secretKey: process.env.IYZICO_SECRET_KEY,
              callbackUrl: process.env.IYZICO_CALLBACK_URL,
              sandbox: process.env.IYZICO_SANDBOX === "true",
            },
          },
        ],
      },
    },
  },
})

Installation

npm install medusa-payment-iyzico

This package has @medusajs/framework as a peer dependency. If using Medusa v2, it's already installed. Otherwise:

npm install @medusajs/framework

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | IYZICO_API_KEY | Yes | iyzico API key from dashboard | | IYZICO_SECRET_KEY | Yes | iyzico secret key from dashboard | | IYZICO_CALLBACK_URL | Yes | 3DS callback URL (your domain) | | IYZICO_SANDBOX | No | Set to "true" for sandbox testing | | IYZICO_DEBUG | No | Set to "true" for debug logging |

See .env.example for all variables.

medusa-config.ts Registration

import { IyzicoPaymentService } from "medusa-payment-iyzico"
import { defineConfig } from "@medusajs/framework/utils"

module.exports = defineConfig({
  modules: {
    payment: {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: IyzicoPaymentService,
            options: {
              apiKey: process.env.IYZICO_API_KEY,
              secretKey: process.env.IYZICO_SECRET_KEY,
              callbackUrl: process.env.IYZICO_CALLBACK_URL,
              sandbox: process.env.IYZICO_SANDBOX === "true",
              debug: process.env.IYZICO_DEBUG === "true",
            },
          },
        ],
      },
    },
  },
})

IyzicoOptions Reference

All configuration options:

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | apiKey | string | Yes | — | iyzico API key | | secretKey | string | Yes | — | iyzico secret key | | callbackUrl | string | Yes | — | 3DS callback URL | | sandbox | boolean | No | false | Use sandbox API | | debug | boolean | No | false | Enable debug logging |

3DS Flow

This provider implements the full 3-Domain Secure flow:

1. Initialize — Customer initiates payment, provider calls /payment/3dsecure/initialize
2. Redirect — Customer redirected to iyzico 3DS page
3. Callback — iyzico POSTs to your callbackUrl with auth result
4. Complete — Your storefront extracts conversationData, completes the payment

See 3DS-GUIDE.md for complete callback handler integration.

Sandbox Testing

Get Test Credentials

1. Sign up at sandbox.iyzipay.com
2. Go to API Settings → Test Keys
3. Copy API Key and Secret Key

Set Up ngrok (for 3DS callback)

# Install ngrok
brew install ngrok  # or download from ngrok.com

# Expose your local Medusa port
ngrok http 9000

# Use the ngrok URL as callbackUrl
IYZICO_CALLBACK_URL=https://your-ngrok-url.ngrok-free.app/payment/iyzico/callback

Test Cards

Use these test cards in sandbox:

| Card Number | Result | |------------|--------| | 4242424242424242 | Success | | 5000000000000009 | Decline | | 3000000000000004 | 3DS Required |

See iyzico docs for full test card list.

Run Integration Tests

# Set test credentials
export IYZICO_TEST_API_KEY=your_sandbox_api_key
export IYZICO_TEST_SECRET_KEY=your_sandbox_secret_key

# Run tests
npm test
# or
npx jest __tests__/integration.spec.ts

Tests automatically skip if credentials are missing (no failures).

Debug Mode

Set IYZICO_DEBUG=true or pass debug: true in options to see request/response logs:

IYZICO_DEBUG=true

Debug output includes redacted versions of sensitive data.

Troubleshooting

Common Errors

| Error | Cause | Solution | |-------|-------|----------| | AUTH_ERROR | Invalid API key/secret | Check dashboard keys | | 3DS_TIMEOUT | Customer didn't complete 3DS | Default timeout is 10 min | | CALLBACK_FAILED | No callback received | Check ngrok/firewall | | CONVERSATION_MISMATCH | Wrong conversationId | Verify ID matches |

Enable Debug

# Via environment
IYZICO_DEBUG=true

# Or in config
options: {
  debug: true,
}

Verify Configuration

# Test your credentials
npm run build
node -e "
const { IyzicoClient } = require('./dist/client');
const client = new IyzicoClient({
  apiKey: process.env.IYZICO_API_KEY,
  secretKey: process.env.IYZICO_SECRET_KEY,
  callbackUrl: 'http://localhost/callback',
  sandbox: true,
  debug: true
});
console.log('Client initialized successfully');
"

API Reference

This package provides:

• IyzicoPaymentService — Medusa PaymentProviderPlugin interface
• IyzicoClient — Internal HTTP client (not exported)

Payment Methods

All supported via Medusa payment session API:

• initializePayment — Create 3DS session
• authorizePayment — Complete 3DS auth
• capturePayment — Capture authorized payment
• refundPayment — Submit refund
• cancelPayment — Cancel payment

License

MIT — see LICENSE file.