یک کلید API پرداخت مانند کارت نقدی بدون رمز عمل میکند. هر کسی که آن را ارسال کند می‌تواند صورتحساب بسازد، داده‌های پرداخت شما را بخواند و، اگر از پرداختهای خروجی استفاده می‌کنید، پول را از موجودی شما خارج کند. بنابراین امنیت API پرداخت به سه عادت خلاصه میشود: کلید را روی سرورهای خودتان نگه دارید، اجازه دهید API فقط از نشانی‌های همان سرورها آن را بپذیرد، و پیش از اقدام، هر وبهوک را با خواندن دوباره پرداخت تأیید کنید.
این راهنما برای مدیران مهندسی و سرپرستان بخش پرداخت در ارائه‌دهندگان خدمات پرداخت (PSP)، موسسات پول الکترونیک (EMI)، بانک‌ها و پذیرندگان است که یک API پرداخت رمزارزی را متصل می‌کنند که به یورو تسویه میشود. این راهنما نشان می‌دهد که چگونه کلید را با نشانی IP و محدوده CIDR محدود کنید، کلید باید کجا نگهداری شود، وب‌هوک‌ها چگونه بررسی شوند و کدام کنترل‌ها باید پیرامون پرداختهای خروجی قرار گیرند. مثال‌ها از API و داشبورد ItisPay استفاده می‌کنند (داده‌های نمایشی).
لحظه‌های کلیدی
به‌طور خلاصه
- کلید API یک اعتبارنامه حامل است. GitGuardian در سال 2025 در کامیت‌های عمومی GitHub، 28٫65 میلیون رمز مخفی سخت‌کدشده جدید شمارش کرد؛ بنابراین برای نشت کلید برنامه‌ریزی کنید، نه فقط برای حفظ امنیت آن.
- فهرست مجاز IP باعث میشود کلید لو رفته خارج از شبکه شما بی‌اثر باشد. کوچک‌ترین محدوده‌های IPv4 یا IPv6 را فهرست کنید که نشانی‌های خروجی واقعی شما را پوشش دهند؛ فهرست خالی به هر نشانی اجازه می‌دهد.
- وبهوک یک اعلان است، نه اثبات. پیش از ارسال کالا یا شارژ حساب، صورتحساب را با شناسه‌اش و با کلید خود دوباره بخوانید.
- پرداختهای خروجی به کنترل‌های انسانی در سمت شما نیاز دارند: ورود دومرحلهای، شماره IBAN و کیف‌پول‌های ذخیره‌شدهٔ ذی‌نفع، و یک تأییدکنندهٔ دوم برای مبالغ بالاتر از سقف تعیین‌شده.
چرا لو رفتن کلید API پرداخت این‌قدر خطرناک است؟#
لو رفتن کلید API پرداخت خطرناک است، زیرا کلید کل هویت یکپارچه‌سازی شما است. API ItisPay، مانند بیشتر API های پرداخت، هر درخواست را با یک هدر، یعنی Api-key، احراز هویت میکند و همین احراز هویت صورتحساب‌ها، پرداختهای خروجی به IBAN یا کیف‌پول و برداشت‌های رمزارزی به یک نشانی بیرونی را پوشش می‌دهد. به همین دلیل مستندات از این موضوع می‌خواهد که کلید «در کد سمت کلاینت یا مخازن عمومی افشا نشود.»
در عمل کلیدها از جاهای معمولی نشت می‌کنند: کد، لاگ‌ها و گفتگوها. بر اساس گزارش «وضعیت پراکندگی رمزهای مخفی 2026» از GitGuardian (مارس 2026)، در سال 2025 در کامیت‌های عمومی GitHub، 28٫65 میلیون رمز مخفی سخت‌کدشدهٔ جدید اضافه شد که 34 درصد بیشتر از یک سال قبل بود. وقتی GitGuardian رمزهایی را که در سال 2022 لو رفته بودند دوباره آزمود، بیش از 64 درصد آن‌ها در ژانویه 2026 هنوز معتبر بودند. تیم‌ها کلیدها را منتشر می‌کنند و سپس تعویض آن‌ها را فراموش می‌کنند.
فهرست ده خطر برتر امنیت API از OWASP (نسخه 2023) «Broken Authentication» را در رتبه دوم قرار می‌دهد و هشدار می‌دهد که «مکانیزم احراز هویت هدفی آسان برای مهاجمان است، زیرا در معرض دید همه قرار دارد.» گزارش بررسی نقض داده 2025 از Verizon، سوءاستفاده از اعتبارنامه را رایج‌ترین بردار حمله اولیه با 22 درصد نام می‌برد. یک رشتهٔ رمز تنها دفاع ضعیفی است، بنابراین بقیهٔ این راهنما لایه‌هایی را اضافه میکند که حتی پس از افشای آن رشته همچنان برقرار بمانند.
چگونه فهرست مجاز IP از کلید API محافظت میکند؟#
فهرست مجاز IP، که گاهی فهرست سفید IP نامیده میشود، کلید را با متصل کردن آن به مکان‌ها و نه فقط به یک رشته، محافظت میکند. API تنها زمانی کلید را می‌پذیرد که درخواست از نشانی‌ای بیاید که شما فهرست کرده‌اید؛ کپی کلید روی لپ‌تاپ یک توسعه‌دهنده، در لاگ CI یا در یک سایت اشتراک‌گذاری متن کار نمی‌کند.
در داشبورد ItisPay این تنظیم زیر Projects، سپس Settings، سپس Security و در فیلد API Allowed IPs قرار دارد. این فیلد فهرستی با کاما جدا شده از نشانی‌های تکی و بلوک‌های CIDR می‌پذیرد. متن راهنمای آن می‌گوید: «برای مجاز کردن همه IP ها خالی بگذارید. هم IPv4 و هم IPv6 پشتیبانی میشوند.» همین فهرست را می‌توان هنگام ایجاد پروژه از طریق API، در فیلد api_allowed_ips تنظیم کرد و یک ورودی نامعتبر مانند 256.256.256.256 با خطای اعتبارسنجی رد میشود و ذخیره نمی‌شود.
پیش‌فرض خالی اهمیت دارد. یک پروژه جدید کلید خود را از هر جایی می‌پذیرد تا زمانی که کسی این فیلد را پر کند؛ بنابراین این مرحله را در فهرست آماده‌سازی برای راه‌اندازی بگذارید، نه در فهرست کارهایی که بعداً مرتب میشوند. مقادیر نمایشی در تصویر، 203.0.113.10 و 198.51.100.0/24، از محدوده‌هایی هستند که RFC 5737 برای مستندات رزرو کرده است؛ فهرست شما نشانی‌های عمومی واقعی خودتان را در بر خواهد داشت. هر پروژه کلید 64 نویسه‌ای و فهرست مخصوص خود را دارد، بنابراین تولید می‌تواند فقط به دو یا سه سرور محدود بماند، در حالی که یک پروژه آزمایشی مجموعهٔ گسترده‌تری را می‌پذیرد.
چگونه محدوده‌های CIDR را برای IPv4 و IPv6 بنویسیم؟#
کوچک‌ترین محدوده‌ای را بنویسید که هر نشانی‌ای را که سرورهایتان واقعاً برای رسیدن به API استفاده می‌کنند پوشش دهد. بیشتر مشکلات فهرست مجاز از یک محدوده بسیار گسترده یا از یک مسیر خروجی که کسی آن را فراموش کرده، ناشی میشوند.
خواندن پیشوند#
یک بلوک CIDR نشانی‌ای است که با یک اسلش و طول پیشوند دنبال میشود. RFC 4632 طول پیشوند را تعداد بیت‌های معنادار تعریف میکند: 192.168.99.0/24، 24 بیت اول را ثابت میکند و 8 بیت را آزاد می‌گذارد که 256 نشانی می‌دهد. هر بیتی که از پیشوند کم کنید، بلوک را دو برابر میکند. یک /32 یک نشانی IPv4 است، یک /29 شامل 8 نشانی، یک /24 شامل 256 نشانی و یک /16 شامل 65 536 نشانی است.
IPv6 با 128 بیت به همین شکل کار میکند. یک /128 یک نشانی است. RFC 4291 بخش میزبان اکثر نشانی‌های IPv6 را 64 بیت تعیین میکند، بنابراین شبکهٔ یک سرور معمولاً /64 است و میزبان می‌تواند نشانی خود را در داخل آن تغییر دهد، برای نمونه زمانی که سیستم‌عامل نشانی‌های موقت تولید میکند. اگر نشانی IPv6 میزبان شما تغییر میکند و آن /64 فقط متعلق به خودتان است، /64 را فهرست کنید نه یک /128 منفرد. محدودهٔ مستندات برای مثال‌های IPv6 برابر 2001:db8::/32 است (RFC 3849)، بنابراین هرگز آن را در یک فهرست مجاز واقعی کپی نکنید.
یافتن نشانی خروجی واقعی شما#
نشانی مهم، نشانی‌ای است که API می‌بیند، نه نشانی‌ای که سرور شما درباره خودش گزارش می‌دهد. پشت یک دروازه NAT ابری یا فایروال شرکتی، ماشین‌های زیادی یک یا دو نشانی عمومی مشترک دارند. توابع بدون سرور اغلب از یک استخر مشترک خارج میشوند، مگر این‌که آن‌ها را از طریق یک خروجی ثابت هدایت کنید. از هر محیط با فراخوانی یک سرویس «IP من چیست» بررسی کنید، یا نشانی مبدأ را در لاگ‌های فایروال خود بخوانید و سپس دقیقاً همان را فهرست کنید.
| راه‌اندازی | آنچه باید فهرست شود | نتیجه |
|---|---|---|
| یک سرور با نشانی IPv4 عمومی و ثابت | همان نشانی به‌صورت /32 یا به‌صورت ساده | کار میکند |
| چند سرور پشت یک دروازه NAT ابری | نشانی‌های عمومی دروازه NAT | کار میکند |
| میزبان IPv6 با نشانی‌های متغیر | /64 خود میزبان، در صورتی که کس دیگری از آن استفاده نکند | بستگی دارد |
| شبکه دفتر برای آزمایش دستی | نشانی ثابت دفتر، در صورتی که ارائه‌دهنده آن را تضمین کند | بستگی دارد |
| توابع بدون‌سرور بدون خروجی ثابت | ابتدا آن‌ها را از طریق NAT با نشانی ثابت مسیریابی کنید | نه |
| کل محدوده منطقه‌ای یک ارائه‌دهنده ابری | هیچ‌چیز؛ زیرا مشتریان دیگر را هم پوشش می‌دهد | نه |
قبل از ذخیره هر تغییر، ابتدا نشانی جدید را اضافه کنید، استقرار دهید، مطمئن شوید ترافیک جریان دارد، و تنها پس از آن نشانی قدیمی را حذف کنید. ذخیره فهرستی که سرورهای فعال شما را جا بگذارد، صندوق پرداخت خودتان را مسدود میکند.
کلید API باید کجا نگهداری شود و چه کسی آن را می‌بیند؟#
کلید باید روی سرورهای شما، در یک مخزن رازها و نه جای دیگری نگهداری شود. هرگز آن را داخل صفحه مرورگر یا برنامه موبایل قرار ندهید، زیرا هر کسی می‌تواند آن را در آنجا بخواند. آن را از URLها هم دور نگه دارید: راهنمای OWASP REST Security Cheat Sheet هشدار می‌دهد که کلیدی که در URL باشد می‌تواند در لاگ‌های وب سرور ثبت و ربوده شود. صفحه پرداخت شما با بک‌اند شما صحبت میکند؛ بک‌اند با API پرداخت صحبت میکند.
کلید را هنگام راه‌اندازی از یک مدیر رازها یا متغیرهای محیطی بارگذاری کنید، نه از یک فایل پیکربندی داخل مخزن کد. اگر کدتان را در GitHub میزبانی می‌کنید، محافظت هنگام push را روشن کنید: طبق مستندات GitHub، وقتی «هنگام تلاش برای push یک راز احتمالی را تشخیص دهد، push را مسدود خواهد کرد.»
برای هر محیط یک کلید نگه دارید. هر پروژه ItisPay کلید و فهرست مجاز مخصوص خود را دارد، بنابراین جدا کردن پروژههای تولید و آزمایشی به این معناست که کلید آزمایشی لو رفته نمی‌تواند به پرداختهای واقعی آسیب بزند. دسترسی به کلید تولید را محدود کنید. دستورالعمل‌های EBA در سال 2019 درباره امنیت ICT قاعده دسترسی «نیاز به دانستن» را با «حداقل حقوق دسترسی» تعیین کرده است، از جمله برای کاربران فنی؛ از سال 2025 به این سو DORA این تکلیف را برای بیشتر شرکت‌های پرداخت الزامی کرده است.
سپس، پیش از آنکه به آن نیاز پیدا کنید، بنویسید که چگونه کلید را جایگزین می‌کنید. راهنمای OWASP Cryptographic Storage Cheat Sheet توصیه میکند کلیدها پس از یک دوره مشخص و هر زمان که احتمال افشا وجود دارد چرخانده شوند، و مطمئن شوید که «کد و فرایندهای لازم برای چرخاندن کلید، پیش از نیاز به آن‌ها آماده باشند.»
چگونه وب‌هوک‌های یک API پرداخت را تأیید کنید؟#
با وبهوک مانند اعلان تغییر وضعیت رفتار کنید، و هرگز آن را دلیلی بر دریافت پرداخت ندانید. هر کسی که نشانی callback شما را بداند می‌تواند پیام جعلی «تکمیل‌شده» برای آن بفرستد. الگوی ایمن این است که فاکتور را با کلید خودتان از API بخوانید و بر اساس آنچه API بازمی‌گرداند عمل کنید.
هنگام ایجاد فاکتور ItisPay، فیلد callback_url نشانی به‌روزرسانی‌های وضعیت را تعیین میکند. وقتی وب‌هوکی میرسد، شناسه فاکتور را از آن بردارید، با GET و بر اساس همان شناسه فاکتور را فراخوانی کنید، و تنها در صورتی کالا را ارسال کنید یا اعتبار را شارژ کنید که پاسخ، وضعیت مورد انتظار و مبلغی را که قیمت‌گذاری کرده‌اید نشان دهد. مستندات این نقطه پایانی را چنین توصیف میکند که وضعیت پرداخت و جزئیات بلاک‌چین را «برای نمایش به کاربران یا تأیید» بازمی‌گرداند.
چند قاعده، مدیریت وبهوک را ساده نگه می‌دارد:
- وب‌هوک‌ها را فقط از طریق HTTPS بپذیرید و HTTP ساده را رد کنید.
- مدیریت را ایدمپوتنت کنید. شناسه و وضعیت هر فاکتور پردازش‌شده را ذخیره کنید و موارد تکراری را رد کنید، زیرا ارائه‌دهندگان اعلان‌ها را دوباره ارسال می‌کنند.
- سریع پاسخ دهید و کار را در یک صف انجام دهید، تا یک پایگاه داده کُند باعث تلاش‌های مجدد نشود.
- اگر ارائه‌دهنده وب‌هوک‌هایش را با HMAC امضا میکند، که یک هش کلیددار تعریف‌شده در RFC 2104 است، امضا را دوباره محاسبه کنید و آن را با یک تابع زمان‌ثابت مقایسه کنید. راهنمای امنیت وبهوک OWASP صریح است: «هرگز از == استفاده نکنید: این کار اطلاعات زمانی را درز می‌دهد و می‌تواند نقطه پایانی را به یک اوراکل امضا تبدیل کند.» پیام‌هایی را که زمان امضاشده‌شان بیش از حد قدیمی است رد کنید.
پیش از راه‌اندازی آزمایش کنید. ItisPay یک نقطه پایانی دارد که تغییر وضعیت را برای یک فاکتور آزمایشی واقعی شبیه‌سازی میکند، و نقطه پایانی دیگری که آخرین وبهوک یک فاکتور یا شناسه سفارش را دوباره ارسال میکند، تا بتوانید تلاش‌های مجدد و موارد تکراری را بدون پول واقعی بررسی کنید.
چگونه پرداخت‌ها و دسترسی به داشبورد را ایمن کنید؟#
پرداخت‌ها جایی هستند که یک کلید دزدیده‌شده به از دست رفتن پول تبدیل میشود، پس کنترل‌های انسانی را پیرامون آن‌ها قرار دهید. از طریق نقطه پایانی پرداختهای ItisPay، پرداخت فیات به یک IBAN ذی‌نفع و پرداخت رمزارزی به یک نشانی کیف‌پول ارسال میشود، و هر دو از موجودی قابل‌استفاده شما انجام میشوند. API آنچه را درخواست می‌گوید انجام می‌دهد؛ تشخیص مشروع بودن درخواست بر عهده شماست.
کنترل‌هایی که در سمت شما کار می‌کنند:
- ورود دومرحلهای برای همه کسانی که به داشبورد یا دسترسی پرداخت دارند. قانون پرداخت اتحادیه اروپا از قبل همین ایده را برای کاربران پرداخت به کار می‌برد: قواعد PSD2 درباره احراز هویت قوی مشتری حداقل دو عامل مستقل از میان دانش، مالکیت و ویژگی ذاتی را الزامی میکند. همین استاندارد را برای کارکنان خودتان اعمال کنید.
- ذی‌نفعان ذخیره‌شده. فهرست خودتان از IBANها و نشانی‌های کیف‌پول تأییدشده را نگه دارید، و اجازه دهید سرویس پرداختتان فقط به مواردی از آن فهرست ارسال کند. یک ذی‌نفع جدید باید از یک تأیید جداگانه عبور کند، ترجیحاً همراه با یک دوره انتظار.
- تأییدکننده دوم بالاتر از یک آستانه. یک نفر آماده میکند و نفر دیگری تأیید میکند. مبلغ آستانه را بر اساس میزان ریسک‌پذیری خودتان تعیین کنید.
- سرویس پرداخت جدا. پرداخت‌ها را از یک سرویس با نشانی ثابت خودش که در فهرست مجاز است اجرا کنید، جدا از سرورهای صندوق پرداخت که فاکتورها را ایجاد می‌کنند.
| کنترل | آنچه جلوی آن را می‌گیرد | نتیجه |
|---|---|---|
| فهرست مجاز IP روی کلید | استفاده از کلید لو رفته از بیرون شبکه شما | کار میکند |
| کلید فقط روی سرور | سرقت کلید از مرورگرها، برنامه‌ها و مخازن کد | کار میکند |
| خواندن مجدد فاکتور پس از وبهوک | اعلان‌های جعلی «پرداخت شد» | کار میکند |
| ذی‌نفعان ذخیره‌شده و تأییدکننده دوم | واریز به IBAN یا کیف پول مهاجم | کار میکند |
| هر کدام از این‌ها به‌تنهایی در برابر سرور هک‌شده‌ای که داخل فهرست است | سرقت توسط فردی که از قبل در داخل است | خیر |
DORA و PCI DSS از دسترسی API چه انتظاری دارند؟#
اگر شما یک شرکت مالی تحت نظارت در اتحادیه اروپا هستید، این کنترل‌ها امکانات اختیاری نیستند. قانون تاب‌آوری عملیاتی دیجیتال (Digital Operational Resilience Act، با نام کوتاه DORA، مقررات (EU) 2022/2554) از 17 ژانویه 2025 اجرایی شده است، طبق اعلام EBA. ماده 9 این قانون از شرکت‌ها می‌خواهد «سیاست‌هایی اجرا کنند که دسترسی فیزیکی یا منطقی» به دارایی‌های ICT را محدود کند و «سیاست‌ها و پروتکل‌هایی برای مکانیسم‌های احراز هویت قوی» اجرا کنند. یک کلید فقطرویسرور با فهرست مجاز و برنامه چرخش دوره‌ای، همان نوع شواهدی است که حسابرس درخواست میکند ببیند.
PCI DSS به داده‌های کارت مربوط میشود، نه فاکتورهای رمزارزی. اگر همان تیم پرداخت کارت هم اجرا میکند، الزام 8.4.2 احراز هویت چندعاملی را برای تمام دسترسی‌ها به محیط داده صاحب کارت می‌خواهد و الزامات آینده‌نگر نسخه 4.0 از 31 مارس 2025 الزامی شدند.
کنترل‌های امنیت API پرداخت کجا دیگر اثر ندارند؟#
این کنترل‌ها راه‌های ورود را محدود می‌کنند. به‌تنهایی یک یکپارچه‌سازی را امن نمی‌کنند. حتی برای فرستندگان وبهوک، برگه راهنمای وبهوک OWASP فهرست‌بندی IP را «لایه اضافی فقط» می‌نامد، زیرا «یک IP خروجی مشترک، اثبات هویت نیست».
کجا کمکی نمی‌کند
- سرور هک‌شده‌ای که در فهرست مجاز است. مهاجم با کلید واقعی و از یک آدرس مورد اعتماد درخواست می‌فرستد.
- آدرسهای خروجی مشترک. اگر سایر مشتریان از همان آدرس NAT در فضای ابری خارج شوند، فهرست مجاز نمی‌تواند شما را از آن‌ها تشخیص دهد.
- رمز عبور سرقت‌شده داشبورد بدون ورود دومرحلهای. مهاجم کل API را دور می‌زند.
- داده‌های شخصی در فیلدهای فاکتور. نقطه پایانی عمومی فاکتور ItisPay بدون کلید، جزئیات کامل فاکتورهای باز را برمی‌گرداند، پس نام و ایمیل مشتریان را در نام سفارش قرار ندهید.
چطور یک یکپارچه‌سازی امن را در یک بعدازظهر شروع کنید؟#
اگر ترتیب ثابتی را دنبال کنید، می‌توانید بخش فنی یک یکپارچه‌سازی امن را در یک بعدازظهر تمام کنید. مراحل زیر از ItisPay استفاده می‌کنند؛ همین ترتیب با هر ارائه‌دهنده‌ای کار میکند.
- یک پروژه آزمایشی و یک پروژه جداگانه برای محیط واقعی بسازید که هرکدام کلید مخصوص خود را داشته باشند.
- هر دو کلید را در مدیر رازهای خود ذخیره کنید و فقط روی سرور بارگذاری کنید.
- آدرس عمومی خروجی هر محیط را پیدا کنید و آن را در API Allowed IPs وارد کنید.
- فاکتور را از بک‌اند بسازید: درخواست POST به https://api.itispay.com/api/v1/invoices با هدر Api-key، یک order_id یکتا، fiat_amount همراه با fiat_currency برابر EUR، ارز رمزارزی در currency، و callback_url خود.
- کنترل‌کننده وبهوک را بسازید: فقط HTTPS، idempotent، و پیش از هر اقدامی فاکتور را با شناسه دوباره بخوانید.
- شبیه‌سازی وبهوک را برای هر وضعیتی که مدیریت می‌کنید اجرا کنید، سپس نقطه پایانی ارسال مجدد را برای آزمایش موارد تکراری اجرا کنید.
- پرداختهای خروجی را در آخر فعال کنید، همراه با ذی‌نفعان ذخیره‌شده و تأییدکننده دوم.
برای شروع سریع، دستیار Ask AI در داشبورد، در صورت درخواست، کد نمونه می‌نویسد؛ برای مثال یک فراخوانی فاکتور در Node.js با هدر Api-key از پیش قرار داده شده. آن را پیش‌نویس در نظر بگیرید: پیش از انتشار، نام فیلدها را با مرجع API بررسی کنید، زیرا قرارداد معتبر مرجع است، نه یک مثال تولیدشده. ItisPay همچنین یک کلاینت رسمی TypeScript را در npm با نام @itispay/typescript-client منتشر میکند.
اگر این را در یک زیرساخت گسترده‌تر هماهنگ‌سازی پرداخت وصل می‌کنید، به هر ارائه‌دهنده کلید، فهرست مجاز و کنترل‌کننده وبهوک جداگانه بدهید. همان رکورد که با شناسه دوباره خوانده میشود، برای تیم مالی شما تطبیق پرداختهای رمزارزی را نیز تغذیه میکند.
اگر می‌خواهید پرداخت با استیبل‌کوین را بپذیرید و بدون ساختن زیرساخت خودتان یورو دریافت کنید، ItisPay از API، صدور فاکتور، وب‌هوک‌ها و تطبیق پرداخت‌ها و همچنین نخستین لایه امنیت API پرداخت را فراهم میکند: کلیدهایی که می‌توانید به آدرسهای IP خودتان محدود کنید. صدور مجوز، KYC و تسویه به IBAN شما از طریق شریک ما، یک CASP و مؤسسه پرداخت (Payment Institution) دارای مجوز در اتحادیه اروپا، انجام میشود و بیشتر تیم‌ها از KYB تا نخستین تراکنش کمتر از یک هفته فاصله دارند.
این مقاله صرفاً به‌منظور اطلاع‌رسانی است و مشاوره حقوقی یا نظارتی محسوب نمی‌شود.
