بررسی مالکیت کارت پیش از واریز: کجا و چند بار

بررسی مالکیت کارت را باید در لحظهٔ ثبت کارت انجام بدهید، نه در لحظهٔ واریز. در لحظهٔ واریز، کاربر از قبل منتظر پول است و هر خطایی یعنی یک تیکت؛ در لحظهٔ ثبت، همان خطا یک پیام کنار فیلد است.

این نوشته برای کسی است که می‌خواهد تطابق کد ملی و کارت را در پرداخت پاداش، بازگشت وجه یا تسویه به کار ببرد، و می‌پرسد: کجا، چند بار، و چه چیزی را نگه دارم؟

سه ورودی، و یکی که فراموش می‌شود

سرویس کد ملی، شماره کارت و تاریخ تولد می‌گیرد. اولی و دومی را همه انتظار دارند. سومی را بیشتر تیم‌ها در طراحی اولیهٔ فرم ندارند و بعد از اولین invalid_input به آن می‌رسند. اگر محصول شما تاریخ تولد نمی‌گیرد، پیش از قول‌دادن به تیم محصول بدانید که باید اضافه شود؛ این تغییر فرم است، نه تغییر یک خط کد.

برای کاربر هم باید توجیه داشته باشد. جملهٔ «برای اطمینان از اینکه کارت به نام شماست، تاریخ تولدتان را هم لازم داریم» کافی است و راست هم هست.

کجای جریان؟

سه نقطهٔ ممکن هست.

هنگام ثبت کارت. کاربر کارت را در پنل وارد می‌کند، شما همان لحظه می‌سنجید. اگر منفی بود، همان‌جا اصلاح می‌کند. این را پیشنهاد می‌کنم.

هنگام درخواست برداشت. کاربر کارت را از مدت‌ها پیش ثبت کرده و حالا پول می‌خواهد. اگر این‌جا بسنجید و منفی شد، کاربر معطل شده است.

پیش از هر واریز. ایمن‌ترین، گران‌ترین. برای واریز مکرر و پرتعداد معنا ندارد؛ برای واریزهای نادر و بزرگ شاید.

ترکیب معقول: هنگام ثبت بسنجید، نتیجه را ذخیره کنید، و فقط وقتی کارت عوض شد دوباره بسنجید. کارتی که تغییر نکرده، دلیلی برای پرسش دوباره ندارد.

چه چیزی ذخیره شود

نتیجه را ذخیره کنید، نه ورودی را. یک رکورد مثل این کافی است: شناسهٔ کاربر، چهار رقم آخر کارت، تاریخ بررسی، نتیجه. شماره کامل کارت را فقط اگر برای کار دیگری لازم دارید نگه دارید، و آن‌وقت هم حفاظتش با شماست. تاریخ تولد را برای بررسی بعدی هم نگه ندارید، مگر اینکه خودتان به آن نیاز داشته باشید.

یک چیز را هم ثبت کنید: کدام نسخهٔ قاعده. اگر روزی تصمیم گرفتید برای واریزهای بالای حدی دوباره بسنجید، می‌خواهید بدانید کدام کارت‌ها قبل از آن قاعده تأیید شده‌اند.

سه جواب، سه عمل

ردیف سوم را از دومی جدا نگه دارید. در سرویس مرجع، کارتی که وجود ندارد با کد CARD_NOT_FOUND برمی‌گردد و در API ما به‌صورت «نتیجه‌ای یافت نشد» با HTTP ۲۰۰ و ok: false دیده می‌شود. این پاسخ معتبر است و هزینه دارد، چون پرسش انجام شده. اما برای کاربر دلیلش فرق دارد: در حالت دوم کارت هست و مال کس دیگری است؛ در حالت سوم کارت یا تایپی است یا شماره‌اش وجود ندارد.

پیش از رسیدن به این حالت‌ها، شماره کارت با الگوریتم کنترلی (لوهن) و طول شانزده رقم سنجیده می‌شود. شمارهٔ بدشکل invalid_input می‌گیرد و هزینه ندارد. بهتر است همین سنجش را در فرم خودتان هم انجام دهید.

نمونه درخواست

bash curl -X POST 'https://example.com/api/v1/card-national-id-match/' \ -H 'Authorization: Bearer melli_live_…' \ -H 'Content-Type: application/json' \ -d '{"nationalCode":"0013542419","birthDate":"1370/01/05","cardNumber":"6037990000000014"}'

اعداد این نمونه ساختگی‌اند. کلید واقعی را از متغیر محیطی بخوانید و هیچ‌وقت در سمت مرورگر نگذارید؛ مستندات API دلیلش را آورده است.

واریز به کارت شخص ثالث: چرا مهم است

فرض کنید یک مارکت‌پلیس پول فروشنده را به کارتی که او ثبت کرده می‌ریزد. اگر فروشنده کارت پدرش را بگذارد، چه می‌شود؟ در بهترین حالت هیچ. در بدترین حالت، مارکت‌پلیس بخشی از زنجیره‌ای می‌شود که نمی‌خواهد. بررسی مالکیت، سدی در برابر همین است.

اما سد کامل نیست. اگر قاعدهٔ شما «فقط کارت به نام خود فروشنده» است، باید برای کسب‌وکارهای کوچکی که کارت خانوادگی دارند راه استثنا هم بگذارید: همان مسیر مدرک و بررسی دستی. پاسخ منفی را رد قطعی نکنید، مگر اینکه واقعاً سیاست‌تان این باشد.

اگر پرسش جواب نداد

گاهی سرویس مرجع در دسترس نیست. در این حالت پاسخ ناموفق است و هزینه‌ای کسر نمی‌شود. دو کار نکنید: کارت را «تأییدنشده» نگذارید و کاربر را مقصر نشان ندهید. وضعیت «در انتظار بررسی» بگذارید و بعداً دوباره بپرسید. برای واریز، منتظر بمانید تا بررسی تمام شود؛ واریز بدون بررسی همان خطری است که این سرویس را برایش می‌گیرید.

یک پیشنهاد عملی دیگر: بررسی را بیرون از درخواست وب کاربر انجام دهید، در یک صف پس‌زمینه، و نتیجه را با اعلان یا در پنل نشان دهید. پاسخ سرویس ممکن است چند ثانیه طول بکشد و کاربر نباید پشت یک اسپینر بماند.

پرسش‌هایی که پیش از شروع باید جواب داشته باشند

• اگر کاربر کارت‌های متعدد دارد، همه را می‌سنجید یا فقط کارت اصلی را؟
• اگر کاربر کارتش را عوض کرد، نتیجهٔ قبلی را باطل می‌کنید؟
• اگر پاسخ منفی بود، چند بار اجازهٔ تلاش مجدد می‌دهید؟
• کسی که تاریخ تولدش را نمی‌داند یا ندارد، چه مسیری دارد؟

هیچ‌کدام جوابِ یگانه ندارند؛ به محصول شما بستگی دارند. ولی اگر جواب ندارند، پیش از نوشتن کد از تیم بپرسید.

آنچه این سرویس نمی‌کند

• موجودی، سقف تراکنش یا مسدودی کارت را نمی‌گوید.
• انقضای کارت را نمی‌سنجد.
• نام صاحب کارت را برنمی‌گرداند. جواب فقط بله یا خیر است.
• نمی‌گوید کارت فعال است. «کارت به نام این آدم است» با «می‌شود به آن واریز کرد» یکی نیست.
• برای حساب حقوقی (شرکت) با کد ملی شخص حقیقی معنا ندارد.

اگر می‌خواهید واریز را به شبا انجام دهید، سرویس مشابه برای شبا هست: تطابق کد ملی و شبا. در راهنمای انتخاب بین کارت، حساب و شبا می‌گوییم کدام را کجا بگذارید.

نکتهٔ آخر

برای شروع، یک مسیر کوچک بسازید: ثبت کارت، بررسی در پس‌زمینه، نمایش نتیجه. بعد از آنکه این کار کرد، بقیه (کارت‌های متعدد، بررسی دوباره) را اضافه کنید.

با تطابق کارت و کد ملی تاریخ تولد را به فرم اضافه کنید، هنگام ثبت کارت بسنجید، نتیجه را ذخیره کنید (نه ورودی را)، و پاسخ منفی را از «کارت یافت نشد» جدا کنید. بقیه‌اش جزئیات پیاده‌سازی است.