API و وب سرویس تبدیل کارت به شبا
شمارهٔ شبا، نام بانک و نام صاحب کارت را از روی یک شمارهٔ کارت شانزدهرقمی برمیگرداند، تا به‌جای کارت بتوانید شبا را نگه دارید.
این سرویس چه می‌کند
این وب سرویس یک شمارهٔ کارت میگیرد و سه مقدار برمیگرداند: شبا در فیلد IBAN، نام بانک در bank_name و نام صاحب کارت در name. بعد از یک فراخوان می‌توانید شبا را ذخیره کنید و دیگر نیازی به نگه‌داشتن شمارهٔ کارت نیست.
این تفاوت در عمل مهم است. کارت گم میشود، تمدید میشود یا با کارت دیگری از همان حساب عوض میشود، ولی شبا به حساب وصل است. سامانه‌ای که فقط شمارهٔ کارت نگه داشته، با هر تعویض کارت باید دوباره از کاربر بپرسد.
چرا شبا را به‌جای کارت ذخیره کنید
ذخیرهٔ شمارهٔ کارت برای تسویه‌های تکراری ریسک نگه‌داری داده‌ای را بالا می‌برد و فایدهٔ تازه‌ای ندارد، چون واریز پایا و ساتنا به شبا نیاز دارد. الگوی معمول این است که کاربر کارتش را یک بار بدهد، شما یک بار تبدیل کنید، شبا و نام را نگه دارید و شمارهٔ کارت را دور بریزید.
ورودی فقط شانزده رقم است
فیلد cardNumber باید شانزده رقم باشد و از الگوریتم لان بگذرد. رقم اشتباه همان‌جا پیش از تماس با سرویس مرجع رد میشود و پاسخ invalid_input میگیرد، بدون هزینه. همین کنترل را پیش از فراخوان سمت خودتان هم بگذارید تا کاربر خطا را در لحظهٔ تایپ ببیند.
وقتی به شبا نمی‌رسید
کارت پیدا نشد، کارت منقضی شده، مفقودی ثبت شده، کارت غیرفعال است یا حساب متصل به آن غیرفعال است: سرویس مرجع این وضعیت‌ها را با یک پاسخ معتبر اعلام می‌کند. نتیجه not_found با HTTP ۲۰۰ است و هزینه دارد، چون استعلام انجام شده.
برای کاربر، هر وضعیت پیام جدای خودش را می‌خواهد. «کارت منقضی شده» او را به اقدام درست می‌رساند؛ پیام کلی «استعلام ناموفق بود» او را به پشتیبانی می‌فرستد.
نامی که برمیگردد برای چیست
name نام صاحب کارت است و برای نمایش به کاربر و تأیید او مناسب است. اینکه شبای برگشتی «مال همین کاربر شما» باشد را ثابت نمی‌کند، چون فقط نام ثبت‌شده در بانک را می‌بینید و نه کد ملی را.
آنچه این سرویس نمی‌کند
مالکیت را با کد ملی نمی‌سنجد و موجودی یا گردش حساب نمی‌دهد. شمارهٔ حساب هم برنمی‌گرداند؛ برای آن سرویس تبدیل کارت به حساب هست. اگر باید بدانید کارت به نام فردِ مشخصی است، سرویس تطابق کارت و نام جواب مستقیم‌تری می‌دهد.
کجا به کار می‌آید
- ثبت‌نام پیک و راننده در اپلیکیشن حمل‌ونقلراننده فقط شمارهٔ کارتش را می‌دهد؛ سامانه شبا را میگیرد، نام را برای تأیید به او نشان می‌دهد و تسویهٔ هفتگی را روی شبا تنظیم می‌کند.
- بازپرداخت وام‌های خردشرکت تأمین مالی به‌جای شمارهٔ کارت، شبای مشتری را در پرونده نگه می‌دارد تا با تعویض کارت، دستور واریز یا بازپرداخت دوباره نیاز به ثبت نداشته باشد.
- پاک‌سازی پایگاه دادهٔ فروشندگان قدیمیفروشگاه آنلاینی که سال‌ها فقط کارت فروشندگان را ثبت کرده، یک‌بار فهرست را تبدیل می‌کند و ستون کارت را از پایگاه داده حذف می‌کند.
ورودی و خروجی
ورودی
cardNumberstringشمارهٔ کارتشانزده رقم، بی فاصله یا با فاصله.خروجی
IBANstringIRXXXXXXXXXXXbank_namestringآیندهnamestringنام صاحب کارتقیمت و شرط پرداخت
قیمت هر فراخوان API تبدیل کارت به شبا ۱٬۱۰۰ تومان است.
| تعداد استعلام در ماه | قیمت هر استعلام |
|---|---|
| همهٔ فراخوان‌ها | ۱٬۱۰۰ تومان |
آخرین تغییر قیمت:
مبلغ پیش از تماس با سرویس مرجع از موجودی پنل قفل میشود و اگر پاسخی نیاید، آزاد میشود. ورودی نامعتبر، در دسترس نبودن سرویس مرجع و عبور از سقف نرخ هزینه‌ای ندارند. «رکوردی یافت نشد» یک پاسخ معتبر است و هزینه دارد.
کمترین مبلغ شارژ پنل: ۵۰۰٬۰۰۰ تومان
پرسش‌های متداول
تبدیل شماره کارت به شبا چطور انجام میشود؟
شمارهٔ کارت شانزدهرقمی را در فیلد cardNumber میفرستید و در پاسخ شبا (IBAN)، نام بانک و نام صاحب کارت برمیگردد. هیچ ورودی دیگری لازم نیست.
برای تبدیل کارت به شبا رمز یا CVV2 لازم است؟
خیر. فقط شمارهٔ کارت گرفته میشود. رمز، CVV2 و تاریخ انقضا نه لازم است و نه باید از کاربر خواسته شود.
آیا تبدیل کارت به شبا برای همهٔ بانک‌ها جواب می‌دهد؟
جواب به وضعیت کارت و حساب در سرویس مرجع بستگی دارد. اگر نتیجه‌ای نباشد، پاسخ not_found میگیرید. برای هر بانکی که جواب نداد، مسیر جایگزین مثل گرفتن شبا از خود کاربر را در سامانه‌تان بگذارید.
اگر کارت منقضی یا مفقود شده باشد چه میشود؟
پاسخ not_found با HTTP ۲۰۰ میگیرید و پیام سرویس مرجع نوع وضعیت را میگوید: منقضی، مفقودی، غیرفعال یا حساب غیرفعال. این پاسخ هزینه دارد.
شماره کارت اشتباه تایپ شود هزینه کسر میشود؟
خیر. کارتی که شانزده رقم نباشد یا از الگوریتم لان نگذرد پاسخ invalid_input با HTTP ۴۰۰ میگیرد و هزینه‌ای کسر نمیشود.
بهتر است شبا را ذخیره کنم یا هر بار دوباره تبدیل کنم؟
شبا را ذخیره کنید. شبا به حساب وصل است و با تعویض کارت عوض نمیشود، و تبدیل مجدد هر بار یک فراخوان هزینه‌دار است.
آیا با این سرویس میشود مالکیت کارت را تأیید کرد؟
خیر. نام صاحب کارت برگردانده میشود ولی با کد ملی کاربر شما مقایسه نمیشود. برای تأیید مالکیت باید از سرویس تطابق کارت و نام یا کد ملی استفاده کنید.
حد نرخ وب سرویس تبدیل کارت به شبا چقدر است؟
پیشفرض ۶۰ فراخوان در دقیقه برای هر سرویس است. عبور از آن پاسخ ۴۲۹ با هدر Retry-After میگیرد و هزینه ندارد. برای حجم بیشتر باید سقف حساب شما بالا برده شود.
فرق تبدیل کارت به شبا با تبدیل کارت به حساب چیست؟
اولی شبا برمیگرداند و دومی شمارهٔ حساب. هر دو نام بانک و نام صاحب کارت را هم میدهند. برای واریز با پایا یا ساتنا شبا لازم است.