مستندات

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مشخصات:

- آدرس: api/payments/invoice

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

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

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

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

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

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

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

وب سرویس ها

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

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

مشخصات:

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

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

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

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

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

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

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

پس از اینکه اعلانی با 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 تاریخ و زمان نهایی شدن این تراکنش ( تبدیل شده به منطقه زمانی انتخابی پذیرنده )

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

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

مشخصات:

- آدرس: 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 یورو ارز پایه فعال

نرخ ارز ها:

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

مشخصات:

- آدرس: api/currency/rates

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

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

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

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

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

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

مشخصات :

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

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

- نوع دیتا: JSON

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

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