مستندات

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

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

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

قبل از شروع به موارد زیر توجه نمایید:

• آدرس پایه کلیه API ها https://core.jeeb.io می باشد.
• کلیه API ها مبتنی بر JSON می باشند. پس هنگام ارسال اطلاعات و فراخوانی API ها به این موضوع توجه نمایید.
• توسعه دهندگان می توانند از تست نت ها برای تست ارتباطات و منطق درگاه پرداخت خود استفاده نمایند.
• منطقه زمانی (Time Zone) کلیه واحد های زمانی متناسب با تظیمات پذیرنده در پنل مدیریت می باشد. منطقه زمانی پیش فرض UTC می باشد.
• Signature یا امضای پذیرنده محرمانه می باشد به هیچ عنوان در اختیار کاربران وب سایت خود قرار ندهید.
• تمامی پرداخت ها به دلیل نوسانات ارزش ارز های دیجیتال، دارای تاریخ انقضا می باشند. به این معنا که کاربر می بایست در مدت معینی اقدام به انجام تراکنش نماید، که این مدت زمان در حال حاضر 15 دقیقه پس از ایجاد تراکنش است. در صورتی که این زمان به پایان برسد، پرداخت به صورت خودکار باطل خواهد شد و اگر تراکنش بعد از این مدت زمان در شبکه دیده شود، به صورت واریز عادی پردازش می شود.
• خروجی تمام API های بخش پرداخت، به صورت یک دیتا مدل مشخص می باشد، که مقدار خروجی در فیلد result قرار می گیرد:

با توجه به جدول فوق، مقادیر ممکن برای errorCode و توضیحات مربوط به آن در جدول زیر شرح داده شده است:

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

پرداخت زمانی مالتی کوین می شود که هنگام ایجاد پرداخت، کوین های قابل پرداخت در فیلد coins درج شده باشد. برای مثال اگر مقدار btc/ltc/bch را در فیلد مذکور در API ایجاد پرداخت وارد کنید، 3 آدرس بر روی 3 کوین مختلف ایجاد می شود. مبلغ هر کدام از این کوین ها نیز با توجه به فیلد value که واحد آن بیت کوین می باشد تنظیم می شود. حال پرداخت کننده می تواند بین 3 کوین مختلف انتخاب کند و تراکنش را فقط بر روی یک کوین انجام دهد.

• پرداخت در جیب می تواند چندین وضعیت داشته باشد که کد و معنای آن در جدول زیر شرح داده شده است:

این وضعیت ها در فیلد stateId، در دیتا مدل های متد های بخش پرداخت قابل دسترسی خواهند بود.

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

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

1- کنترل پروسه پرداخت توسط جیب و انتقال کاربر به صفحه پرداخت جیب

2- کنترل پروسه پرداخت توسط جیب و عدم انتقال کاربر به صفحه پرداخت جیب

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

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

ولی برخلاف درگاه های بانکی، کار به اینجا ختم نمی شود، با توجه به اینکه در ارز هایی دیجیتال ( مثل بیت کوین و اتریم و... ) نیاز به دریافت تاییدیه می باشد، پذیرنده می بایست منتظر دریافت اعلان از طرف جیب باشد تا مطمئن شود که پرداخت با موفقیت تایید شده پس از آن سفارش را نهایی سازد. این نوع اعلان از طریق webhookUrl برای پذیرنده ارسال می شود. تنها با استناد بر دیتای دریافت شده در callbackUrl شرط کافی برای نهایی سازی سفارش نمی باشد.

مزایا و معایب:

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

مراحل اجرایی:

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

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

جهت انتقال به صفحه پرداخت جیب می بایست کاربر را به همراه token به صفحه پرداخت جیب redirect کنید.

مشخصات:

- آدرس: api/payments/invoice

- نوع درخواست: POST

دیتا مدل ورودی:

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

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

مزایا و معایب:

• دیگر نیاز نیست کاربر را به درگاه انتقال دهید
• شما می توانید با این روش در هر پلتفرمی، با UI متناسب با ساختار نرم افزار خود، بخش تراکنش را پیاده سازی نمایید
• افراد سود جو، نمی توانندAPI های ارتباطی بین پذیرنده و درگاه جیب را پیدا کنند
• افزایش زمان پیاده سازی درگاه

مراحل اجرایی:

• با استفاده از متد issue یک پرداخت تولید کنید ( در این روش تنها ارسال webhookUrl اجباریست )
• مقادیر خروجی در فیلد addresses را به کاربر نمایش دهید. کاربر می تواند به دلخواه بر روی هر کدام از آدرس های ایجاد شده تراکنش انجام دهد. ( در نظر داشته باشید که کاربر تنها در مدت زمان معینی می تواند تراکنش خود را انجام دهد در صورتی که این مدت زمان به اتمام برسد، هر گونه تراکنش به آدرس ها ارائه شده به صورت واریز عادی پردازش می شود. )
• در این مرحله پذیرنده می بایست منتظر اعلان های دریافتی بر روی webhookUrl باشد. این اعلان ها شامل stateId می باشد که مشخص می کند که پرداخت چه وضعیتی دارد.
• پس از دریافت تاییدیه تراکنش، در صورتی که شرایط استرداد تراکنش وجود نداشت، جیب اعلانی شامل stateId برابر با 4 برای پذیرنده ارسال می کند. پذیرنده پس از دریافت این اعلان، می بایست وضعیت سفارش را مجددا بررسی کند، اگر تمام شرایط مناسب بود، توسط متد confirm پرداخت را تایید نهایی کند. (دقت کنید که هر تراکنش تنها یکبار می تواند از سمت پذیرنده تایید شود. پس برای جلو گیری از double payment، تنها در صورتی که در خروجی این متد خطایی اعلام نشده بود، سفارش خود را نهایی سازی کنید)

وب سرویس ها

ایجاد پرداخت:

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

مشخصات:

- آدرس: api/payments/:signature/issue

- نوع درخواست: POST

دیتا مدل ورودی:

دیتا مدل خروجی ( فیلد result ):

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

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

مشخصات:

- آدرس: api/payments/:signature/confirm

- نوع درخواست: POST

دیتا مدل ورودی:

دیتا مدل خروجی ( فیلد result ):

وضعیت پرداخت:

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

مشخصات:

- آدرس: api/payments/:signature/status

- نوع درخواست: POST

دیتا مدل ورودی:

دیتا مدل خروجی ( فیلد result ):

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

بازگشت به پذیرنده (callback):

callback در روش پیاده سازی اول، هنگام بازگشت کاربر به وب سایت پذیرنده مورد استفاده قرار میگیرد.

مشخصات:

- آدرس: توسط پذیرنده در متد issue تنظیم می شود

- نوع درخواست: POST

نوع دیتا: FORM

دیتا مدل ارسالی در بازگشت:

اعلان (webhook):

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

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

جهت افزایش امنیت به موارد زیر توجه کنید:

• حتما بررسی کنید که درخواست ارسالی از domain یا sub-domain جیب (https://*.jeeb.io) ارسال شده است.
• دیتا مدل ارسالی شامل امضای درگاه نیز میشود، حتما بررسی کنید که امضای ارسال شده با امضای ثبت شده برابر باشد.
• پیشنهاد می شود webhook url ها برای هر سفارش یا پرداخت، متفاوت باشد. برای مثال از query param های خاص منظوره برای هر پرداخت استفاده کنید.

مشخصات :

- آدرس: توسط پذیرنده در متد issue تنظیم می شود

- نوع درخواست: POST

- نوع دیتا: JSON

دیتا مدل ارسالی در اعلان:

واحد های مالی:

در حال حاضر در جیب ارز های زیر تعریف شده اند و به صورت لحظه ای نرخ ها به روز رسانی می شوند.

نرخ ارز ها:

با استفاده از این متد می توانید نرخ ارز های فعال جیب را واکشی کنید.

مشخصات:

- آدرس: api/currency/rates

- نوع درخواست: GET

دیتا مدل خروجی ( فیلد result ):

تبدیل قیمت ها:

شما می تواند از این متد جهت تبدیل تمام ارز ها به یکدیگر استفاده نمایید.

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

مشخصات :

- آدرس: api/currency?:base&:target&:value

- نوع درخواست: GET

- نوع دیتا: JSON

دیتا مدل خروجی (result):

در این بخش مدل خروجی object نخواهد بود و نوع آن number می باشد که خروجی این درخواست می باشد.