مستندات

مستندات وب سرویس های درگاه پرداخت جیب

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

درگاه پرداخت جیب -Jeeb Payment Gateway- یک سرویس اینترنتی است که هدف آن پردازش تراکنش های بلاکچین و ایجاد یک درگاه پرداخت بر روی آن است. اشخاص می توانند با استفاده از درگاه پرداخت جیب، در کنار دیگر ارزهای رایج کشور، ارزهای دیجیتال (از جمله بیت کوین) را نیز در فروشگاه ها و یا سرویس های آنلاین خود بپذیرند. بدین وسیله شما می توانید با تمامی نقاط جهان - بدون نگرانی از مشکلاتی مانند مسدود شدن حساب و ... - تجارت کنید و در لحظه تسویه حساب نمایید.

برخی از مزایای استفاده از درگاه پرداخت جیب و وب سرویس های آن:

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

نام فیلد نوع فیلد اجباری شرح
hasError boolean * در صورتی که true باشد خطایی رخ داده است
errorMessage string پیام مربوط به خطای رخ داده
errorCode number شماره شناسه خطا
result object/value در صورتی که خطایی رخ داده باشد این فیلد null است

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

مقدار errorCode شرح خطا
0 خطای داخلی رخ داده است
1 امضای پذیرنده اشتباه یا پذیرنده تایید نشده است
2 مقادیر ارسالی اشتباه است
3 کد رهگیری وارد شده اشتباه است
4 پرداخت در وضعیت نهایی نمی باشد
5 پرداخت قبلا از سمت پذیرنده تایید شده است
6 token پرداخت اشتباه است
7 پرداخت منقضی یا باطل شده است
8 پرداخت بسته شده است
کد عنوان وضعیت
btc بیت کوین فعال
tbtc بیت کوین تست نت فعال
ltc لایت کوین فعال
tltc لایت کوین تست نت فعال
eth ایتریوم به زودی
xrp ریپل به زودی
bch بیت کوین کش به زودی
xmr مونرو به زودی

برای استفاده از تست نت ها می توانید از لینک های زیر استفاده نمایید:

عنوان لینک
بیت کوین تست نت https://coinfaucet.eu/en/btc-testnet
لایت کوین تست نت http://testnet.litecointools.com

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

کد وضعیت پرداخت شرح
01 وضعیت اولیه
02 در انتظار تراکنش
03 در انتظار دریافت تاییده از شبکه
04 تراکنش در جیب نهایی شده است
05 پرداخت منقضی و یا توسط کاربر باطل شده است
06 مبلغ پرداخت شده از مبلغ درخواستی کمتر است (استرداد پرداخت)
07 مبلغ پرداخت شده از مبلغ درخواستی بیشتر است (استرداد پرداخت)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

انتقال کاربر به درگاه

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

انتقال با روش Redirect:

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

مشخصات:

- آدرس: api/payments/invoice?:token

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

انتقال با روش ارسال Form:

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

مشخصات:

- آدرس: api/payments/invoice

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

- نوع دیتا: FORM

دیتا مدل ورودی:
نام فیلد نوع فیلد اجباری شرح
token string * token ایجاد شده برای پرداخت

وب سرویس ها

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

از این وب سرویس جهت ایجاد یک پرداخت در جیب استفاده کنید. پس از فراخوانی این وب سرویس، به ازای هر کوین قابل پرداخت درخواست شده در فیلد coins، آدرسی ایجاد می شود که برای پرداخت در حالت رزو قرار می گیرد. در صورتی که در مدت زمان تعیین شده در فیلد expiration، تراکنشی به یکی از آدرس های ارائه شده در شبکه دیده شود، پرداخت انجام شده تلقی می گردد. در غیر این صورت، پس از گذشت مدت زمان تعیین شده، تراکنش منقضی می شود و آدرس های ارائه شده از حالت رزرو خارج می شوند. هرگونه تراکنش به آدرس های ارائه شده پس از منقضی شدن پرداخت، به صورت واریز عادی تلقی و مستقیم به کیف پول پذیرنده در جیب منتقل می شود.

آدرس های ارائه شده در این وب سرویس الزاما منحصر به فرد نیستند. آدرس های ارائه شده در پرداخت ها یا جدید ایجاد شده اند یا از آدرس های قدیمی (که حداقل 7 روز از تاریخ ایجاد آنها می گذرد) مجدد استفاده شده است.

مشخصات:

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

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

دیتا مدل ورودی:
ردیف نام فیلد نوع فیلد اجباری شرح
1 orderNo string * شماره سفارش در سیستم پذیرنده
2 value number * مبلغ تراکنش به بیت کوین. مبلغ پایه تمام تراکنش ها به بیت کوین محاسبه می شود و می تواند شامل 8 رقم اعشار باشد.
3 coins string * لیست کوین های قابل پرداخت. شما می توانید هر تعداد کوینی که می خواهید در این فیلد وارد کنید، ولی در حال حاضر تنها 3 کوین اول پردازش می شوند. برای مشاهده لیست کوین ها به جدول کوین ها مراجعه کنید. این فیلد می بایست به صورت زیر وارد شود.
coin1/coin2/coin3/.....
4 callbackUrl string آدرس بازگشت به وب سایت پذیرنده (اجباریست در صورتی که از روش اول پیاده سازی استفاده می کنید)
5 webhookUrl string * آدرس ارسال اعلان ها به وب سایت پذیرنده
6 language string جهت انتخاب زبان بخش پرداخت استفاده می شود، که در حال حاضر فقط en ، fa و null قابل قبول است. در صورتی که مقداری وارد نشود، بر اساس موقعیت حدودی پرداخت کننده، جیب تصمیم می گیرد که بخش پرداخت با چه زبانی بارگزاری شود.
7 expiration number مقدار اولیه 15 (دقیقه)
جهت افزایش زمان انقضای پرداخت استفاده می شود. این فیلد می تواند مقداری بین 15 تا 2880 داشته باشد.
8 allowReject boolean مقدار اولیه true
اگر true باشد و کاربر دقیقا مبلغ درخواست شده را واریز نکرده باشد، تراکنش پس از دریافت تاییدیه، از وضعیت 3 به 6 و یا 7 ختم شده و مبلغ واریز شده با کسر فی شبکه مسترد می شود.
9 allowTestNet boolean مقدار اولیه false
تنها در صورتی که این فیلد true باشد، امکان پردازش تست کوین ها در فیلد coins خواهد بود. توجه داشته باشید که تست کوین ها تنها برای برنامه نویس ها و به جهت تست ارتباطات ارائه شده اند و به هیچ عنوان نباید در نسخه نهایی استفاده شوند.
دیتا مدل خروجی (فیلد result):
ردیف نام فیلد نوع فیلد اجباری شرح
1 referenceNo string * شماره رهگیری پرداخت در جیب
2 addresses array * آرایه ای از Object هایی که شامل آدرس و مبلغ درخواستی می باشد
3 expirationTime date * تاریخ و زمان انقضای پرداخت
4 token string * token پرداخت

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

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

مشخصات:

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

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

دیتا مدل ورودی:
ردیف نام فیلد نوع فیلد اجباری شرح
1 token string * token پرداخت
دیتا مدل خروجی (فیلد result):
ردیف نام فیلد نوع فیلد اجباری شرح
1 isConfirmed boolean * این فیلد در خروجی حتما باید true باشد در غیر این صورت پذیرنده نباید سفارش را نهایی کند.
2 referenceNo string * شماره رهگیری پرداخت در جیب
3 orderNo string * شماره سفارش در سیستم پذیرنده
4 stateId number * کد وضعیت پرداخت
5 baseValue number * مبلغ پایه به بیت کوین، این فیلد برابر است با فیلد value در ورودی وب سرویس issue
6 coin string کوینی که کاربر بر روی آن تراکنش انجام داده است
7 value number مبلغ درخواستی بر روی کوین انتخابی
8 paidValue number مبلغ پرداختی بر روی کوین انتخابی
9 rate number نرخ تبدیل مبلغ پایه به مبلغ درخواستی کوین انتخابی
10 expirationTime date * تاریخ و زمان انقضای پرداخت
11 finalizedTime date تاریخ و زمان نهایی شدن پرداخت

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

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

مشخصات:

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

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

دیتا مدل ورودی:
ردیف نام فیلد نوع فیلد اجباری شرح
1 token string * token پرداخت
دیتا مدل خروجی (فیلد result):
ردیف نام فیلد نوع فیلد اجباری شرح
1 isConfirmed boolean * نمایانگر این است که آیا پرداخت توسط پذیرنده تایید شده است یا خیر
2 referenceNo string * شماره رهگیری پرداخت در جیب
3 orderNo string * شماره سفارش در سیستم پذیرنده
4 stateId number * کد وضعیت پرداخت
5 baseValue number * مبلغ پایه به بیت کوین، این فیلد برابر است با فیلد value در ورودی وب سرویس issue
6 coin string کوینی که کاربر بر روی آن تراکنش انجام داده است
7 value number مبلغ درخواستی بر روی کوین انتخابی
8 paidValue number مبلغ پرداختی بر روی کوین انتخابی
9 rate number نرخ تبدیل مبلغ پایه به مبلغ درخواستی کوین انتخابی
10 expirationTime date * تاریخ و زمان انقضای پرداخت
11 finalizedTime date تاریخ و زمان نهایی شدن پرداخت

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

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

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

مشخصات:

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

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

- نوع دیتا: FORM

دیتا مدل ارسالی در بازگشت:
ردیف نام فیلد نوع فیلد اجباری شرح
1 referenceNo string * شماره رهگیری پرداخت در جیب
2 orderNo string * شماره سفارش در سیستم پذیرنده
3 stateId number * کد وضعیت پرداخت
4 baseValue number * مبلغ پایه به بیت کوین، این فیلد برابر است با فیلد value در ورودی وب سرویس issue
5 coin string کوینی که کاربر بر روی آن تراکنش انجام داده است
6 value number مبلغ درخواستی بر روی کوین انتخابی
7 paidValue number مبلغ پرداختی بر روی کوین انتخابی
8 rate number نرخ تبدیل مبلغ پایه به مبلغ درخواستی کوین انتخابی

اعلان - webhook:

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

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

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

مشخصات:

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

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

- نوع دیتا: JSON

دیتا مدل ارسالی در اعلان:
ردیف نام فیلد نوع فیلد اجباری شرح
2 attempts number * تعداد دفعات ارسال اعلان
2 referenceNo string * شماره رهگیری پرداخت در جیب
3 orderNo string * شماره سفارش در سیستم پذیرنده
4 stateId number * کد وضعیت پرداخت
5 baseValue number * مبلغ پایه به بیت کوین، این فیلد برابر است با فیلد value در ورودی وب سرویس issue
6 coin string کوینی که کاربر بر روی آن تراکنش انجام داده است
7 value number مبلغ درخواستی بر روی کوین انتخابی
8 paidValue number مبلغ پرداختی بر روی کوین انتخابی
9 rate number نرخ تبدیل مبلغ پایه به مبلغ درخواستی کوین انتخابی
10 expirationTime date * تاریخ و زمان انقضای پرداخت
11 finalizedTime date تاریخ و زمان نهایی شدن پرداخت
11 token string * token پرداخت
12 signature string * امضای دیجیتال درگاه
13 webhookUrl string * webhook url تنظیم شده برای پرداخت
14 callbackUrl string callback url تنظیم شده برای پرداخت

واحد های مالی

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

ردیف کد عنوان نوع ارز وضعیت
1 BTC بیت کوین ارز دیجیتال فعال
2 ETH اتریوم ارز دیجیتال فعال
3 LTC لایت کوین ارز دیجیتال فعال
4 XRP ریپل ارز دیجیتال فعال
5 BCH بیت کوین کش ارز دیجیتال فعال
6 XMR مونرو ارز دیجیتال فعال
7 IRR ریال ایران ارز پایه فعال
8 USD دلار آمریکا ارز پایه فعال
9 EUR یورو ارز پایه فعال
10 GBP پوند انگلیس ارز پایه فعال
11 CAD دلار کانادا ارز پایه فعال
12 AUD دلار استرالیا ارز پایه فعال
12 AED درهم امارات ارز پایه فعال
13 TRY لیر ترکیه ارز پایه فعال
14 CNY یوان چین ارز پایه فعال
15 JPY ین ژاپن ارز پایه فعال

نرخ ارز ها:

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

مشخصات:

- آدرس: api/currency/rates

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

دیتا مدل خروجی (فیلد result):
ردیف نام فیلد نوع فیلد اجباری شرح
1 pair string * نمایانگر مارکت
2 sellRate number * قیمت فروش
3 buyRate number * قیمت خرید
4 averageRate number * قیمت متوسط

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

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

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

مشخصات:

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

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

- نوع دیتا: JSON

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

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