آشنایی با درگاه

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

  • تمامی پرداخت ها کاملا امن و anonymous انجام می شود.
  • استفاده از وب سرویس های مبتنی بر http که به شما این امکان را می دهد در هر بستری به راحتی از درگاه جیب استفاده نمایید.
  • تمام تراکنش ها توسط Token ها مدیریت می شوند به همین دلیل امنیت و راحتی کار با درگاه جیب دوچندان می شود.
قبل از شروع به موارد زیر توجه نمایید:
  • کلیه API ها JSON Base می باشند. پس هنگام ارسال اطلاعات و فراخوانی API ها به این موضوع توجه نمایید.
  • منطقه زمانی (Time Zone) کلیه واحد های زمانی متناسب با تظیمات پذیرنده در پنل مدیریت می باشد.
  • Signature یا امضای پذیرنده محرمانه می باشد به هیچ عنوان در اختیار کاربران وب سایت خود قرار ندهید.
  • کلیه تراکنش های ایجاد شده به دلیل نوسانات ارزش بیت کوین، دارای تاریخ انقضا می باشند. به این معنا که کاربر می بایست در مدت معینی اقدام به انجام تراکنش نماید.

در صورتی که نیاز به هرگونه راهنمایی داشتید، همکاران ما در بخش پشتیبانی منتظر شما هستند.

روش های پیاده سازی

برای کار با درگاه جیب شما دو انتخاب کلی دارید:

  • تراکنش درون وب سایت پذیرنده
  • تراکنش درون وب سایت جیب

تراکنش دورن وب سایت پذیرنده

منظور از تراکنش درون وب سایت پذیرنده، این است که شما نیاز نیست کاربر را به وب سایت جیب انتقال دهید. شما می توانید تمامی مراحل پرداخت را درون وب سایت خود داشته باشید. تنها کافیست به API های جیب متصل شوید.

مزایا و معایب:
  • دیگر نیاز نیست کاربر را به درگاه انتقال دهید.
  • شما می توانید به سادگی در هر پلتفرمی، با UI متناسب با ساختار نرم افزار خود، بخش تراکنش را پیاده سازی نمایید.
  • افراد سود جو، نمی توانند api های ارتباطی بین پذیرنده و درگاه جیب را پیدا کنند.
  • افزایش زمان پیاده سازی درگاه.
  • سخت
مراحل اجرایی:
  • با استفاده از متد issue یک تراکنش تولید کنید
  • فیلد addr را از نتیجه issue به کاربر نمایش دهید. ( در نظر داشته باشید که کاربر تنها در مدت زمان معینی می تواند تراکنش خود را انجام دهد در صورتی که این مدت زمان به اتمام برسد تراکنش از سمت ما قابل پیگیری نخواهد بود. زمانی که تراکنش باطل می شود در فیلد expiretionTime قرار می گیرد. )
  • در این مرحله پذیرنده می بایست منتظر اعلان وضعیت ارسالی از طریق notificationUrl از سمت ما باشد که دو وضعیت را مشخص می کند:
    • stateId = 3 به معنی انکه تراکنش از سمت کاربر انجام شده است و ما منتظر تاییده آن هستیم
    • stateId = 5 به معنی آنکه زمان تعیین شده تراکنش به اتمام رسیده. در صورتی که کاربر قصد پرداخت دارد می بایست مجددا از مرحله اول اقدام نماید
  • در صورتی که پذیرنده اعلان با stateId برابر 3 دریافت کرد، می بایست کاربر را از تراکنش موفق خود مطلع کند. منتها دقت کنید که کار به اینجا ختم نخواهد شد و پذیرنده می بایست منتظر اعلان جدید با وضعیت 4 باشد.
  • پس از دریافت اعلان با stateId برابر با 4، شما می توانید مطمئن باشید که این تراکنش با موفقیت به اتمام رسیده است
  • در این مرحله شما باید وضعیت تراکنش و سبد خرید خود را بررسی کنید، در صورتی که تمام شرایط مناسب بود، توسط متد confirm تراکنش را تایید نهایی نمایید. ( دقیت کنید که هر تراکنش تنها یکبار می تواند از سمت پذیرنده تایید شود. پس برای جلو گیری از double payment، تنها در صورتی که در خروجی این متد خطایی اعلام نشده بود، سفارش خود را نهایی سازی کنید)

تراکنش درون وب سایت پذیرنده

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

در این روش نیز مانند روش قبل ما همچنان پذیرنده را از طریق notificationUrl و ارسال اعلان، از وضعیت تراکنش مطلع خواهیم ساخت.

مزایا و معایب:
  • پیاده سازی راحت و سریع ارتباط درگاه.
  • برون سپاری بخش نظارت بر پرداخت به جیب در بسیاری از موارد باعث افزایش امنیت خواهد شد.
  • عملیات عیب یابی و تست نسبتا راحت می باشد.
مراحل اجرایی:
  • با استفاده از متد issue یک تراکنش تولید کنید ( در این روش ارسال callBackUrl اجباریست)
  • با استفاده از token ایجاد شده برای این تراکنش، کاربر را به آدرس https://jeeb.io/invoice/payment با متد POST انتقال دهید.
  • در صورتی که پرداخت در مدت زمان تعیین شده انجام شود، ما کاربر را با stateId برابر با 3 از طریق callBackUrl به وب سایت پذیرنده انتقال خواهیم داد در غیر این صورت مقدار stateIdبرابر با 5، به معنی ابطال تراکنش خواهد بود که به اطلاع پذیرنده خواهد رسید.
  • در صورتی که پذیرنده اعلان با stateId ای برابر 3 دریافت کرد، می بایست کاربر را از تراکنش موفق خود مطلع کند. منتها دقت کنید که کار به اینجا ختم نخواهد شد و پذیرنده می بایست منتظر اعلان جدید با وضعیت 4 باشد.
  • پس از دریافت اعلان با stateId برابر با 4، شما می توانید مطمئن باشید که این تراکنش با موفقیت به اتمام رسیده است
  • در این مرحله شما باید وضعیت تراکنش و سبد خرید خود را بررسی کنید، در صورتی که تمام شرایط مناسب بود، توسط متد confirm تراکنش را تایید نهایی نمایید. ( دقیت کنید که هر تراکنش تنها یکبار می تواند از سمت پذیرنده تایید شود. پس برای جلو گیری از double payment، تنها در صورتی که در خروجی این متد خطایی اعلام نشده بود، سفارش خود را نهایی سازی کنید)

برای پیاده سازی روش دوم، شما می بایست کاربر را به درگاه جیب انتقال دهید، برای این منظور با ایجاد یک تراکنش و دریافت token ، کاربر را redirect کنید به آدرس درگاه.

مشخصات:
  • آدرس: api/invoice/payment/
  • نوع درخواست: POST
ردیف نام پارامتر نوع پارامتر اجباری توضیح
1 token string * token ایجاد شده برای تراکنش

ایجاد تراکنش

برای شروع فرآیند یک تراکنش پذیرنده می بایست ابتدا از طریق این API یک تراکنش ایجاد نمایید.

مشخصات:
  • آدرس: api/bitcoin/issue/:signature
  • نوع درخواست: POST
پارامتر های ورودی
ردیف نام پارامتر نوع پارامتر اجباری توضیح
1 orderNo string * شماره سفارش
2 requestAmount number * مبلغی که کاربر می بایست واریز کند به BTC
3 notificationUrl string * آدرس ارسال اعلان ها
4 callBackUrl string آدرس بازگشت به وب سایت پذیرنده ( اجباریست در صورتی که از روش دوم پیاده سازی استفاده می کنید)
6 allowReject boolean * در صورتی که true باشد، اگر کاربر دقیقا مبلغ اعلام شده را واریز نکند، مبلغ واریز شده بازگشت خواهد خورد.
پارامتر های خروجی
ردیف نام پارامتر نوع پارامتر توضیح
1 hasError boolean در صورتی که True باشد خطایی رخ داده است
2 errorMessage string پیام مربوط به خطای رخ داده
3 errorCode int شماره شناسه خطا
4 result object در صورتی که خطایی رخ نداده باشد، شامل یک شی است

وضعیت خروجی پارامتر Result

ردیف نام پارامتر نوع پارامتر توضیح
1 token string token ایجاد شده برای این تراکنش
2 referenceNo string شماره پیگیری تراکنش در جیب
3 addr string آدرسی که کاربر می بایست مبلغ درخواستی پدیرنده را به آن واریز کند
4 expirationTime string تاریخ و زمان انقضای این تراکنش ( تبدیل شده به واحد زمانی انتخاب شده توسط پذیرنده )

وضعیت های خروجی errorCode

مقدار خروجی توضیح
0 خطای داخلی رخ داده است.
1 امضای پذیرنده اشتباه است.
2 مقادیر ارسالی اشتباه است.

تایید کردن تراکنش

پس از اینکه اعلانی با stateIdبرابر با 4، مبنی بر نهایی شدن تراکنش دریافت شد، شما مجاز هستید که تنها یک بار آن تراکنش را تایید نمایید.

  • آدرس: api/bitcoin/confirm/:signature
  • نوع درخواست: POST
محدودیت ها:
  • تنها تراکنش هایی قابل تایید هستند که در وضعیت نهایی قرار گرفته باشند
  • هر تراکنش تنها یکبار قابل تایید می باشد
پارامتر های ورودی
ردیف نام پارامتر نوع پارامتر اجباری توضیح
1 token string * token ایجاد شده برای تراکنش

پارامتر های خروجی

ردیف نام پارامتر نوع پارامتر توضیح
1 hasError boolean در صورتی که True باشد خطایی رخ داده است
2 errorMessage string پیام مربوط به خطای رخ داده
3 errorCode int شماره شناسه خطا
4 result object در صورتی که خطایی رخ نداده باشد، شامل یک شی است

وضعیت خروجی پارامتر Result

ردیف نام پارامتر نوع پارامتر توضیح
1 referenceNo string شماره پیگیری تراکنش در جیب
2 orderNo string شماره سفارش
3 stateId number
  • تراکنش تازه تولید شده است.
  • تراکنش در صف انتظار پرداختی می باشد.
  • تراکنش منتظر تایید در شبکه می باشد.
  • تراکنش تایید نهایی شده است.
  • مدت زمان انجام پرداخت برای تراکنش به اتمام رسیده است ( منقضی شده )
  • پرداختی بیشتر از حد می باشد.
  • پرداختی کمتر از حد می باشد.
4 requestAmount number مبلغ درخواستی اولیه
5 value number مبلغ واریز شده در این تراکنش
6 finalizedTime string زمان نهایی شدن تراکنش در جیب
7 expirationTime string زمان انقضای تراکنش
8 isConfirmed boolean وضعیت تایید از وب سایت پذیرنده

وضعیت های خروجی errorCode

مقدار خروجی توضیح
0 خطای داخلی رخ داده است.
1 امضای پذیرنده اشتباه است.
2 پارامتر های ورودی اشتباه است.
4 تراکنش در وضعیت نهایی نمی باشد، در نتیجه confirm کردن آن بی معنی خواهد بود
5 تراکنش قبلا confirm شده است.
6 token ارسالی اشتباه است.

دریافت وضعیت تراکنش

این متد امکان این را به شما خواهد داد که در هر زمانی که نیاز بود، وضعیت تراکنش های خود را بررسی کنید.

  • آدرس: api/bitcoin/status/:signature
  • نوع درخواست: POST
پارامتر های ورودی
ردیف نام پارامتر نوع پارامتر اجباری توضیح
1 token string * token ایجاد شده برای تراکنش

پارامتر های خروجی

ردیف نام پارامتر نوع پارامتر توضیح
1 hasError boolean در صورتی که True باشد خطایی رخ داده است
2 errorMessage string پیام مربوط به خطای رخ داده
3 errorCode int شماره شناسه خطا
4 result object در صورتی که خطایی رخ نداده باشد، شامل یک شی است

وضعیت خروجی پارامتر Result

ردیف نام پارامتر نوع پارامتر توضیح
1 referenceNo string شماره پیگیری تراکنش در جیب
2 orderNo string شماره سفارش
3 stateId number
  • تراکنش تازه تولید شده است.
  • تراکنش در صف انتظار پرداختی می باشد.
  • تراکنش منتظر تایید در شبکه می باشد.
  • تراکنش تایید نهایی شده است.
  • مدت زمان انجام پرداخت برای تراکنش به اتمام رسیده است ( منقضی شده )
  • پرداختی بیشتر از حد می باشد.
  • پرداختی کمتر از حد می باشد.
4 requestAmount number مبلغ درخواستی اولیه
5 value number مبلغ واریز شده در این تراکنش
6 finalizedTime string زمان نهایی شدن تراکنش در جیب
7 expirationTime string زمان انقضای تراکنش
8 isConfirmed boolean وضعیت تایید از وب سایت پذیرنده

وضعیت های خروجی errorCode

مقدار خروجی توضیح
0 خطای داخلی رخ داده است.
1 امضای پذیرنده اشتباه است.
2 پارامتر های ورودی اشتباه است.
6 token ارسالی اشتباه است.

اعلان و بازگشت

بازگشت (Call Backs)

هنگامی که تراکنش کاربر انجام می شود یا تراکنش منقضی می شود، کاربر با درخواست بازگشت به وب سایت پذیرنده به callBackUrl ارسال می شود.

مشخصات:
  • نوع درخواست: POST
اطلاعات ارسالی:
ردیف نام پارامتر نوع پارامتر توضیح
1 signature string امضای پذیرنده جهت احراز هویت
2 referenceNo string شماره پیگیری تراکنش در جیب
3 orderNo string شماره سفارش
4 stateId number
  • تراکنش تازه تولید شده است.
  • تراکنش در صف انتظار پرداختی می باشد.
  • تراکنش منتظر تایید در شبکه می باشد.
  • تراکنش تایید نهایی شده است.
  • مدت زمان انجام پرداخت برای تراکنش به اتمام رسیده است ( منقضی شده )
  • پرداختی بیشتر از حد می باشد.
  • پرداختی کمتر از حد می باشد.
5 requestAmount number مبلغ درخواستی اولیه
6 value number مبلغ واریز شده در این تراکنش
7 notificationUrl string
8 callBackUrl string

اعلان (Notification)

هرگونه تغییر در وضعیت تراکنش، به پذیرنده از طریق notificationUrlارسال می شود.

توجه داشته باشید که سرور جیب هنگام ارسال اعلان، در خروجی منتظر کد وضعیت OK-200 می باشد. در صورتی که کد وضعیت مقدار دیگری داشته باشد، تا حداکثر 10 بار درخواست را با فاصله زمانی متغییر ارسال می کند.

مشخصات:
  • نوع درخواست: POST
اطلاعات ارسالی:
ردیف نام پارامتر نوع پارامتر توضیح
1 signature string امضای پذیرنده جهت احراز هویت
2 referenceNo string شماره پیگیری تراکنش در جیب
3 orderNo string شماره سفارش
4 stateId number
  • تراکنش تازه تولید شده است.
  • تراکنش در صف انتظار پرداختی می باشد.
  • تراکنش منتظر تایید در شبکه می باشد.
  • تراکنش تایید نهایی شده است.
  • مدت زمان انجام پرداخت برای تراکنش به اتمام رسیده است ( منقضی شده )
  • پرداختی بیشتر از حد می باشد.
  • پرداختی کمتر از حد می باشد.
5 requestAmount number مبلغ درخواستی اولیه
6 value number مبلغ واریز شده در این تراکنش
7 notificationUrl string
8 callBackUrl string

تبدیل واحد های مالی

تمام API های جیب در حال حاضر با واحد بیت کوین کار می کنند. به همین دلیل شما می توانید برای تبدیل واحد ریال یا دلار به بیت کوین یا بلعکس از API های ارائه شده استفاده نمایید.

در صورتی که ارز مورد نظر شما غیر از ریال و یا دلار می باشد، لطفا به پشتیبانی وب سایت جیب اطلاع دهید تا در اولین فرصت در سیستم تعریف شود.

توجه داشته باشید، در صورتی که در تنظیمات پذیرنده خود، پرداخت هزینه های جانبی بر عهده پرداخت کننده باشد، بر روی تبدیل واحد های مالی و ارزی، تاثیر گذار خواهد بود.

برای مثال اگر پرداخت هزینه های جانبی به عهده پذیرنده باشد، مبلغ معادل بیت کوین، 100000 تومان، 0.01 BTC و در صورتی که پرداخت هزینه های بر عهده پرداخت کننده باشد مبلغ معادل 0.0101 BTC می شود که به پذیرنده اعلام خواهد شد.

تبدیل به بیت کوین

مشخصات:
  • آدرس: api/convert/:signature/:value/:baseCurrency/btc
  • نوع درخواست: GET
توضیحات:

برای کار با این API شما می بایست به جای :signature امضای پذیرنده، :value مبلغ مورد نظر خود و به جای :baseCurrency کد ارز مبدا ( USD, IRR ) را جایگذاری کنید.

پارامتر های خروجی
ردیف نام پارامتر نوع پارامتر توضیح
1 hasError boolean در صورتی که True باشد خطایی رخ داده است
2 errorMessage string پیام مربوط به خطای رخ داده
3 errorCode int شماره شناسه خطا
4 result number مبلغ معادل در واحد بیت کوین

وضعیت های خروجی errorCode

مقدار خروجی توضیح
0 خطای داخلی رخ داده است.
100 خطا در تعریف کد واحد ارزی مبدا

تبدیل از بیت کوین

مشخصات:
  • آدرس: api/convert/:signature/:value/btc/:targetCurrency
  • نوع درخواست: GET
توضیحات:

برای کار با این API شما می بایست به جای :signature امضای پذیرنده، :value مبلغ مورد نظر خود و به جای :targetCurrency کد ارز مقصد ( USD, IRR ) را جایگذاری کنید.

پارامتر های خروجی
ردیف نام پارامتر نوع پارامتر توضیح
1 hasError boolean در صورتی که True باشد خطایی رخ داده است
2 errorMessage string پیام مربوط به خطای رخ داده
3 errorCode int شماره شناسه خطا
4 result number مبلغ معادل در واحد ارزی درخواستی

وضعیت های خروجی errorCode

مقدار خروجی توضیح
0 خطای داخلی رخ داده است.
100 خطا در تعریف کد واحد ارزی مقصد