راهنمای اتصال به درگاه رمزارزی بیتا

مرحله صفر: ثبت نام و تعریف فروشگاه

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

مرحله یک: ارسال دیتا

در مرحله اول شما می بایست پارامترهای موجود در جدول زیر رو با متد POST به آدرسی که مشخص شده ارسال کنید.

نکته: تمامی داده های برگشتی از بیتا به صورت json می باشد

 لطفا به کوچک یا بزرگ بودن حروف پارامترها دقت کنید.

https://bita.hamrasta.com/api/order/newpath
POST - content-type=x-www-form-urlendcodedMethod
شناسه یکتای فروشگاه که در پنل قابل مشاهده استapiKey
مبلغ مورد نظر بصورت ریالamount
شناسه یکتای هر پرداخت که از سمت پذیرنده برای هر تراکنش تخصیص داده میشه.shareId
یکی از مقادیر: IOS, ANDROID, WEB, OTHERmode
جهت تست و در نظر نگرفتن تراکنش رمزارزی این پارامتر را true تنظیم نمایید.test

پاسخ دریافتی در صورت بروز خطا

جدول خطاها
Api Key نامعتبر است۴۰۴۱۹
وضعیت این فروشگاه مسدود شده است۴۰۴۲۲
وضعیت این فروشگاه در انتظار تایید است ۴۰۴۲۳
وضعیت این فروشگاه غیرفعال است۴۰۴۲۴
خطای دسترسی۴۰۱۳
وضعیت کاربر جاری مسدود است۴۰۱۱۷
وضعیت احراز هویت کاربر باید تایید شده باشد۴۰۶۱۰۶

مرحله دوم: انتقال کاربر به صفحه پرداخت

بعد از مرحله یک، کاربر به صفحه ی پرداخت بیتا (Redirect) هدایت می شه که تو اون صفحه، باید ایمیلش رو وارد کنه و مراحل پرداخت رو انجام بده. نمونه کد فراخوانی این متد رو هم میتونید در انتها دانلود کنید. چون تایید تراکنش های رمزارزی در شبکه مدتی زمان میبره، برخلاف درگاه های ریالی، کاربر از این صفحه به وبسایت پذیرنده برنمیگرده.

مرحله سه: ارسال پاسخ تراکنش از سمت بیتا

بعد از دریافت رمزارز از مشتری، بیتا آدرس بازگشت (Callback URL) فروشگاه رو که تو زمان تعریف فروشگاه مشخص شده رو با پارامترهای زیر فراخوانی میکند و در جواب هم لازمه HTTP/1.1 200 OK برای بیتا ارسال بشه.

نکته: شما باید یک وب سرویس POST و با پارامترهای زیر بصورت json در سمت وبسایت فروشگاهتون پیاده سازی کنید.

** تراکنش های رمزارزی نیاز به تایید در شبکه دارند که بصورت پیشفرض ۳ تایید شبکه (Confirmation) رو در نظر گرفتیم. این فراخوانی تایید تراکنش، در هر بار تایید تراکنش در شبکه رمزارز دوباره فراخوانی میشه، مگر اینکه:

۱- قبلا فراخوانی شده باشد و پاسخ ۲۰۰ OK هم از وبسایت پذیرنده گرفته باشیم.

۲- تایید تراکنش (مرحله چهار) هم صدا زده شده باشه.

 

POSTMethod
شناسه‌ی یکتایی که قبل از سمت پذیرنده برای هر تراکنش اختصاص داده شده است.shareId
شماره ردیف تراکنش که عددی ترتیبی بین بیتا و وبسایت فروشگاه رد و بدل می شود.seq
در صورتیکه در مرحله یک، پارامتر test=true تنظیم شده باشد، این پارامتر هم در فراخوانی بیتا با مقدار true مجدد ارسال خواهد شد.test

مرحله چهار: تایید تراکنش

بعد از اینکه کاربر پرداخت رو انجام میده، بیتا با فراخوانی آدرس بازگشتی (Callback URL) تو مرحله سه، پاسخ تراکنش رو برای پذیرنده ارسال میکنه. بعد از اون، پذیرنده لازمه که تایید تراکنش رو به بیتا اعلام کنه. برای این کار باید این متد با پارامترهای زیر فراخوانی بشه که در جواب اون، وضعیت و اطلاعات تراکنش ارسال خواهد شد.

نکته: پذیرنده بعد از این مرحله میتونه همیشه برای دریافت آخرین وضعیت تراکنش استفاده کنه.

GETMethod
https://bita.hamrasta.com/api/order/verify/{seq}Path
شماره ردیف تراکنش که در مرحله سوم توسط بیتا ارسال شدهseq
شناسه یکتای فروشگاهapiKey
در صورتیکه در مرحله یک، پارامتر test=true تنظیم شده باشد، این پارامتر هم در فراخوانی بیتا با مقدار true مجدد ارسال خواهد شد.test
Response
شناسه یکتای هر پرداخت که از سمت پذیرنده برای هر تراکنش تخصیص داده میشه.shareId
ANDROID,IOS,WEB,OTHERmode
شماره ردیف تراکنش که در مرحله سوم توسط بیتا ارسال شدهseq
مبلغ به ریالamount
مبلغ به رمزارزcoinAmount
تعداد تاییدها در شبکه بلاکچینconfirmations
نوع Bitcoin/BitcoinCash/Ethereum/TethercoinType

پاسخ دریافتی در صورت بروز خطا

جدول خطاها
Api Key نامعتبر است۴۰۴۱۹
وضعیت این فروشگاه مسدود شده است۴۰۴۲۲
وضعیت این فروشگاه در انتظار تایید است۴۰۴۲۳
وضعیت این فروشگاه غیرفعال است ۴۰۴۲۴
خطای دسترسی۴۰۱۳
وضعیت کاربر جاری مسدود است۴۰۱۱۷
وضعیت احراز هویت کاربر باید تایید شده باشد۴۰۶۱۰۶
سفارش مورد نظر یافت نشد۴۰۴۴۱
خطای دسترسی۴۰۳۳

نمونه کد جاوا اسکریپت

function paymentRequest(apiKey, amount, shareId, mode, test) {

   var form = document.createElement("form");
   form.setAttribute("method", "post");
   form.setAttribute("action", "https://bita.hamrasta.com/api/order/new");
   form.setAttribute("target", "view");

   var iapi = document.createElement("input");
   iapi.setAttribute("type", "hidden");
   iapi.setAttribute("name", "apiKey");
   iapi.setAttribute("value", apiKey);
   form.appendChild(iapi);

   var iamount = document.createElement("input");
   iamount.setAttribute("type", "hidden");
   iamount.setAttribute("name", "amount");
   iamount.setAttribute("value", amount);
   form.appendChild(iamount);

   var ishare = document.createElement("input");
   ishare.setAttribute("type", "hidden");
   ishare.setAttribute("name", "shareId");
   ishare.setAttribute("value", shareId);
   form.appendChild(ishare);

   var imode = document.createElement("input");
   imode.setAttribute("type", "hidden");
   imode.setAttribute("name", "mode");
   imode.setAttribute("value", mode);
   form.appendChild(imode);

   var itest = document.createElement("input");
   itest.setAttribute("type", "hidden");
   itest.setAttribute("name", "test");
   itest.setAttribute("value", test);
   form.appendChild(itest);

   document.body.appendChild(form);
   window.open('', 'view');
   form.submit();
   document.body.removeChild(form);
}