DocsDeveloper SectionIran-Specific Features

🇮🇷 Comprehensive Guide to Iran-Specific Features

The Next-Strapi-Medusa project provides native, production-grade support for Iranian e-commerce infrastructure. By enabling the ENABLE_IRAN_FEATURES=true flag, mobile number login and SMS OTP, Shetab/Shaparak bank gateways (Zarinpal), live Iran Post shipping rate calculation, and Toman pricing conversions are activated without modifying the Medusa core.

Native Support Without Modifying Medusa Core

All Iranian modules (payment gateway, SMS OTP, and Iran Post shipping) are architected as isolated modules adhering to Medusa v2 standards, ensuring clean updates without breaking changes.

1. Global ENABLE_IRAN_FEATURES Flag

To activate all Iran-specific features across the entire stack (Medusa backend, Strapi CMS, and Next.js Storefront), set the following variables in your .env and docker-compose.yml files:

.env

env

ENABLE_IRAN_FEATURES=true
NEXT_PUBLIC_ENABLE_IRAN_FEATURES=true
DEFAULT_REGION=IR
DEFAULT_LOCALE=fa-IR

2. Mobile Number & SMS OTP Login (Phone Auth & OTP)

The dedicated phone authentication module is implemented under store-admin/src/modules/auth/providers/otp. It normalizes Iranian phone numbers, generates secure 4-6 digit temporary verification codes, and incorporates rate limiting.

Multiple format support: Automatically accepts 0912xxxxxxx and +98912xxxxxxx.
Countdown timer & rate limiting: Prevents repeated SMS requests with a 120-second cooldown.
Auto Registration: Automatically creates a customer account for newly verified phone numbers.

store-admin/medusa-config.ts (phone-auth section)

typescript

{
  resolve: "./src/modules/auth/providers/otp",
  id: "phone-auth",
  options: {
    jwtSecret: process.env.JWT_SECRET,
  },
}

3. Iranian SMS Gateways (Kavenegar & SMS.ir)

The SMS dispatch service supports fast pattern webhooks (service lines) to deliver verification codes in under 5 seconds, even to advertising-blocked numbers:

.env (SMS Gateway Configuration)

env

# Provider: sms-ir or kavenegar
SMS_PROVIDER=sms-ir
SMS_API_KEY=your_sms_ir_api_key
SMS_OTP_TEMPLATE_ID=100000 # Verification pattern template ID
SMS_ORDER_PLACED_TEMPLATE_ID=200000 # Order confirmation pattern template ID

4. Zarinpal Online Payment Gateway

The Zarinpal module integrates directly into Medusa's Payment Sessions system, enabling transactions via Shetab debit cards with test mode (Sandbox) support:

.env (Zarinpal Settings)

env

ZARINPAL_MERCHANT_ID=your-merchant-id-xxxx-xxxx
ZARINPAL_SANDBOX=false # Set to true in development

5. Live Iran Post Rate Calculation (Iran Post Fulfillment)

The medusa-fulfillment-iran-post plugin dynamically calculates express (Pishtaz) and standard (Sefareshi) postal rates during checkout based on origin, destination province, and parcel weight, supporting 24-digit tracking codes in the order dashboard.

store-admin/medusa-config.ts (shipping module section)

typescript

{
  resolve: "./src/modules/fulfillment/providers/iran-post",
  id: "iran-post",
  options: {
    originProvince: "تهران",
    originCity: "تهران",
    defaultPackagingWeight: 150, // گرم
  },
}

6. Automatic Currency Conversion to Toman (convertToToman)

Prices are stored in Rials inside Medusa database for Shaparak compliance. In Strapi, enabling the convertToToman option in Storefront Settings removes a zero and formats numbers with thousand separators in Toman on the frontend.

Frontend price conversion (store/src/lib/util/prices.ts)

typescript

export function formatPrice(amount: number, currencyCode: string, convertToToman = false) {
  if (currencyCode.toLowerCase() === 'irr' && convertToToman) {
    const tomanAmount = Math.round(amount / 10);
    return `${new Intl.NumberFormat('fa-IR').format(tomanAmount)} تومان`;
  }
  return new Intl.NumberFormat('fa-IR', { style: 'currency', currency: currencyCode }).format(amount);
}