درگاه اینترنتی( مستقیم PSP )
مقدمه#
این مستند جهت ارائه به پذیرندگان پی استار جهت اتصال به درگاه پرداخت می باشد. در حالت کلی پذیرنده ابتدا می بایست یک درخواست ایجاد تراکنش ارسال و برای آغاز تراکنش یک توکن یکبار مصرف دریافت و آن را برای انجام تراکنش به سایت پست نماید. بعداز بازگشت مشتری از درگاه، اطلاعات وضعیت تراکنش به سمت پذیرنده برگشت داده می شود و پذیرنده پس از دریافت اطلاعات می بایست نسبت به verify کردن تراکنش اقدام نماید.
نکته 1 : سرویسها به صورت REST با متد POST و فرمت json قابل استفاده میباشد.
نکته 2 : آدرس پایه برای اتصال به تمامی وبسرویسها https://core.paystar.ir/api/direct میباشد. این آدرس را به ابتدای آدرس های نسبی معرفی شده در مستند بیافزایید. به عنوان مثال آدرس وبسریس create به شکل زیر تبدیل میشود.
https://core.paystar.ir/api/direct/create
سرویس Create#
این سرویس جهت ایجاد تراکنش به کار میرود و پذیرنده با دادن اطلاعات مورد نياز ایجاد تراکنش یک توکن یکبار مصرف دریافت میکند
| key | value |
|---|---|
| Content-Type | application/json |
| Authorization | Authorization |
توجه: به جای <YOUR_GATEWAY_ID> مقدار شناسه درگاه خود که در پنل پی استار وجود دارد را قرار دهيد.
پارامترهای ورودی
| نام فیلد | نوع داده | شرح | اجباری |
|---|---|---|---|
| amount | double | مبلغ تراکنش | بله |
| order_id | string | شناسه سفارس | بله |
| callback | string | آدرس برگشت | بله |
| sign | string | امضاء | بله |
| name | string | نام پرداخت کننده | خیر |
| phone | string | تلفن پرداخت کننده | خیر |
| string | ایمیل پرداخت کننده | خیر | |
| description | string | توضیحات پرداخت | خیر |
| callback_method | integer | متد انتخابی برای بازگشت کاربر به سایت پذیرنده | خیر |
توجه:
• مبلغ تراکنش میبایست به ریال باشد و حداقل 5,000 ریال و حداکثر 500,000,000 ریال است. همچنين با توجه به تنظيمات کارمزد پایانه، سهم کارمزد پرداخت کننده به مبلغ افزوده خواهد شد.
• یکتایی شناسه سفارش در سامانه بررسی نمیشود. بهتر است به منظور جلوگيری از بروز خطا از شناسه یکتا استفاده شود. طول شناسه سفارش حداقل 1 و حداکثر 50 کاراکتر و شامل حروف و اعداد میباشد.
• آدرس برگشت باید با فرمت https://yoursite.ir/your/callback/url باشد. دامنه برگشت، باید دامنه اصلی سامانه که در هنگام ایجاد درگاه ثبت کرده اید باشد.
• برای ساخت امضا از متد HMAC و الگوریتم رمزنگاری SHA512 استفاده کنيد. کليد مورد نياز برای رمزنگاری، در هنگام ساخت درگاه در اختيار شما قرار میگيرد. آماده سازی داده ها برای امضا به صورت زیر میباشد:
amount#order_id#callback
پارامتر های خروجی (درصورت مجاز بودن درگاه برای تراکنش)
| عنوان | نوع داده | شرح |
|---|---|---|
| status | int | جدول وضعيت |
| message | string | پيام سيستم |
| Data | PardakhtCreateData | جدول نوع داده PardakhtCreateData |
پارامتر های خروجی (درصورت غیر مجاز بودن درگاه برای تراکنش)
| عنوان | نوع داده | شرح |
|---|---|---|
| status | string | مقدار ثابت unauthenticated |
| action | string | مقدار ثابت PardakhtCreate |
| tag | string | مقدار ثابت unauthenticated |
| message | string | پیام سیستم |
| data | array | آرایه خالی |
| api_version | string | نسخه API |
جدول نوع داده PardakhtCreateData
| عنوان | نوع داده | شرح |
|---|---|---|
| token | string | توکن یکبار مصرف تراکنش |
| ref_num | string | شناسه یکتای رهگيری تراکنش |
| order_id | string | شناسه سفارش |
| payment_amount | double | مبلغ نهایی پرداختی کاربر با اعمال کارمزد |
توجه:
• مقدار ref_num را در دیتابيس ذخيره کنيد. از این شناسه در وبسرویس تایيد تراکنش استفاده خواهد شد.
پارامترهای تبادلی میان سایت فروشنده و سامانه پی استار#
درصورتی که پاسخ دریافتی از وبسرویس مرحله قبل (ایجاد تراکنش) موفق باشد و توکن یکبار مصرف را دریافت کرده باشيد، میتوانيد مشتری را با توکن دریافتی به سمت پی استار به آدرس زیر هدایت کنيد
https://core.paystar.ir/api/direct/payment
پارامترهای ورودی
| نام فیلد | نوع داده | شرح | اجباری |
|---|---|---|---|
| token | string | توکن دریافتی از وبسرویس create | بله |
توجه:
• برای هدایت کاربر به این صفحه میتوانید از متد GET یا POST استفاده کنید.
برگشت از درگاه به سایت پذیرنده
پس از انجام تراکنش ، کاربر به صفحه CallBack پذیرنده که در زمان ایجاد تراکنش مشخص شده، با ارسال فیلدهای زیر به صورت form-data و با متد POST هدایت خواهد شد. اگر در هنگام فراخوانی وبسرویس create ،پارامتر callback_method با مقدار عددی 1 ارسال شود، بازگشت به سایت پذیرنده با متد GET انجام میشود. در غیر اینصورت بازگشت به سایت پذیرنده با متد POST خواهد بود. بنابراین میبایست متد CallBack خود را با در نظر گرفتن این شرایط پیاده سازی و در وبسایت یا نرم افزار خود قرار دهید.
پارامترهای خروجی
| عنوان | نوع داده | شرح |
|---|---|---|
| status | int | جدول وضعیت |
| order_id | string | شناسه سفارش (ارسال شده توسط پذیرنده) |
| ref_num | string | شناسه یکتای رهگیری تراکنش |
| transaction_id | string | شناسه تراکنش (موجود در پنل پی استار) |
| card_number | string | شماره کا رت پرداخت کننده |
| tracking_code | string | کد رهگیری بانکی |
| sign | string | داده های امضا شده |
توجه:
• درصورتی که وضعیت تراکنش ناموفق باشد(پرداخت انجام نشده باشد) فیلدهای sign , tracking_code , card_number برگشت داده نمی شود
سرویس verify#
پذیرنده بعد از گرفتن دادههای برگشتی از درگاه، درصورت موفق بودن تراکنش، از این سرویس جهت تایيدیه تراکنش ارسالی استفاده میکند. نکته مهم این است که پذیرنده نباید تا زمان دریافت وضعيت موفق از این سرویس، تراکنش را موفق در نظر بگيرد. درصورتی که تا 10 دقيقه بعد از تراکنش، این وبسرویس فراخوانی نشود، وضعيت تراکنش به صورت خودکار به ناموفق تغيير ميکند و مبلغ کسر شده از حساب مشتری طی 72 ساعت به حساب مشتری برگشت داده میشود. توجه داشته باشيد در صورتی که یکبار از این وبسریس پاسخ موفق دریافت کنيد، دیگر امکان فراخوانی وبسرویس را نخواهيد داشت و در صورت فراخوانی با پيام خطا مواجه خواهيد شد.
Header درخواست
| key | value |
|---|---|
| Content-Type | application/json |
| Authorization | Authorization |
توجه:
• به جای <YOUR_GATEWAY_ID> مقدار شناسه درگاه خود که در پنل پی استار وجود دارد را قرار دهيد.
پارامترهای ورودی
| نام فیلد | نوع داده | شرح | اجباری |
|---|---|---|---|
| ref_num | string | شناسه یکتای رهگیری تراکنش | بله |
| amount | double | مبلغ تراکنش | بله |
| sign | string | امضاء | بله |
توجه:
• برای ساخت امضا از متد HMAC و الگوریتم رمزنگاری SHA512 استفاده کنيد. کليد مورد نياز برای رمزنگاری، در هنگام ساخت درگاه در اختيار شما قرار میگيرد. آماده سازی دادهها برای امضا به صورت زیر میباشد:
amount#ref_num#card_number#tracking_code
پارامترهای خروجی (درصورت مجاز بودن درگاه)
| عنوان | نوع داده | شرح |
|---|---|---|
| status | int | جدول وضعیت |
| message | string | پیام سیستم |
| data | PardakhtVerifyData | جدول نوع داده PardakhtVerifyData |
پارامترهای خروجی (درصورت غیر مجاز بودن درگاه)
| عنوان | نوع داده | شرح |
|---|---|---|
| status | string | مقدار ثابت unauthenticated |
| action | string | مقدار ثابت PardakhtCreate |
| tag | string | مقدار ثابت unauthenticated |
| message | string | پیام سیستم |
| data | array | آرایه خالی |
| api_version | string | نسخه API |
جدول نوع داده PardakhtVerifyData
| عنوان | نوع داده | شرح |
|---|---|---|
| price | double | مبلغ تراکنش |
| ref_num | string | شناسه یکتای رهگيری تراکنش |
جدول کد های وضعیت#
| عنوان | description | توضیحات |
|---|---|---|
| 1 | Ok | موفق |
| 101- | invalidRequest | درخواست نامعتبر (خطا در پارامترهای ورودی) |
| 102- | inactiveGateway | درگاه فعال نیست |
| 103- | retryToken | توکن تکراری است |
| 104- | amountLimitExceed | مبلغ بیشتر از سقف مجاز درگاه است |
| 105- | invalidRefNum | شناسه ref_num معتبر نیست |
| 106- | retryVerification | تراکنش قبلا وریفای شده است |
| 107- | badData | پارامترهای ارسال شده نامعتبر است |
| 108- | trNotVerifiable | تراکنش را نمیتوان وریفای کرد |
| 109- | trNotVerified | تراکنش وریفای نشد |
| 198- | paymentFailed | تراکنش ناموفق |
| 199- | error | خطای سامانه |