مستند سرویس‌های پیمان
روال فراخوانی سرویس‌های پیمان
لیست شناسه بانک‌ها
در سرویس‌های پیمان بانک‌ها، از طریق شناسه آنها تفکیک خواهند شد که در این قسمت
لیست بانکهای فعال و شناسه آنها مشخص شده است:</span >
| ردیف | نام بانک | شناسه بانک |
| 1 | ملی | MELIIR |
| 2 | ملت | BKMTIR |
| 3 | کشاورزی | KESHIR |
| 4 | دی | DAYBIR |
| 5 | سینا | SINAIR |
| 6 | سامان | SABCIR |
| 7 | اقتصاد نوین | BEGNIR |
| 8 |
مهر ایران |
MEHRIR |
| 9 | ایران زمین | IRZAIR |
| 10 | سرمایه | SRMBIR |
| 11 | پست بانک | PBIRIR |
| 12 | بلو بانک | BLUBIR |
| 13 | تجارت | BTEJIR |
سرویس لاگین (Login service)
آدرس:
https://payman2.sandbox.faraboom.co/oauth/token
متد: (POST)
برای فراخوانی سرویس های پیمان لازم است ابتدا با نام کاربری و پسوردی که هنگام ثبت نام در اختیار شما قرار داده شده است لاگین کرده و یک توکن دریافت کنید.هنگام فراخوانی دیگر سرویس‌های پیمان لازم است توکن دریافتی سرویس لاگین پیمان را، اینگونه قرار دهید:
Authorization: "Bearer {accessToken}"
توکن دریافت شده از خروجی این سرویس، از نوع Bearer است. برای فراخوانی این سرویس
پارامتر های جدول پارامترهای ورودی را در بدنه درخواست ارسال نمایید، پس از اجرای
درخواست پاسخی با پارامترهای جدول خروجی دریافت می‌کنید.
پارامترهای بدنه درخواست:
| شرح | نوع داده | نام |
| نام کاربری | String | Client_id* |
| رمزعبور | String | Client_secret* |
| نوع احراز هویت که برابر با client_credentials قرار می‌گیرد | String | Grant_type* |
| شرح | نوع داده | نام |
| اکسس توکن | String | Access_token |
| نوع توکن | String | Token_type |
| اسکوپهای دسترسی | String | Scope |
| مدت اعتبار توکن به ثانیه | Long | Expires_in |
curl --location 'https://payman2.sandbox.faraboom.co/oauth/token'--header 'Content-Type: application/x-www-form -urlencoded'
--header 'Cookie: cookiesession1=678A8C341A085F7AF93FECC7B44ACDFF'
--data-urlencode 'Client_id=demopayman'
--data-urlencode 'Client_secret=!8cr?40V'
--data-urlencode 'Grant_type=client_credentials'
نمونه ورودی سرویس
نمونه خروجی سرویس
سرویس ایجاد پیمان Create Payman
آدرس:
https://payman2.sandbox.faraboom.co/v1/payman/create
متد: (POST)
سرویس ایجاد پیمان، یک قرارداد مابین موسسه و کاربر نهایی ایجاد خواهد کرد. مطابق
مفاد این قرارداد موسسه امکان برداشت وجه از سپرده کاربر نهایی را خواهد داشت. پس
از ارسال درخواست برای این سرویس و در صورت موفقیت آمیز بودن فراخوانی سرویس،
نتیجه code status برابر با 302 خواهد بود و آدرس صفحه لاگین در location در بخش
Header پاسخ سرویس بازگردانده خواهد شد که کاربر از طریق این URL به صفحه لاگین
بانکی منتقل خواهد شد. در نهایت پس از لاگین موفق و تایید مفاد قرارداد، کاربر به
همراه کد پیمان و نتیجه ایجاد پیمان به آدرسی که در مقدار URL-Redirect درخواست
ثبت شده، منتقل خواهد شد.
مفاد این قرارداد موسسه امکان برداشت وجه از سپرده کاربر نهایی را خواهد داشت. پس
از ارسال درخواست برای این سرویس و در صورت موفقیت آمیز بودن فراخوانی سرویس،
نتیجه code status برابر با 302 خواهد بود و آدرس صفحه لاگین در location در بخش
Header پاسخ سرویس بازگردانده خواهد شد که کاربر از طریق این URL به صفحه لاگین
بانکی منتقل خواهد شد. در نهایت پس از لاگین موفق و تایید مفاد قرارداد، کاربر به
همراه کد پیمان و نتیجه ایجاد پیمان به آدرسی که در مقدار URL-Redirect درخواست
ثبت شده، منتقل خواهد شد.
نمونهURLی که کاربر به آن Redirect خواهد شد بصورت زیر است:
http://sample.com/redirect/url?payman_code=1546857554hd5&status=CREATED
در صورت بروز خطا:
http://sample.com/redirect/url?payman_code=1546857554hd5&status=INTERNAL_ERROR&code=2035
در این مرحله موسسه می بایست کد پیمان را از طریق سرویس دریافت شناسه پیمان ارسال
کند و شناسه پیمان را دریافت نماید، لازم به ذکر است که وضعیت پیمان بعد از
فرایند ایجاد پیمان و تا زمانی که سرویس دریافت شناسه پیمان فراخوانی شود در حالت
“در انتظار تایید” باقی خواهد ماند.
پارامترهای Header درخواست:
| شرح | نام |
| شناسه موسسه | App-key* |
| شناسه سخت افزار کاربر | Client-Device-Id* |
| آدرس IP سیستم کاربر | Client-Ip-Address* |
| مشخصات سخت افزار کاربر | Client-User-Agent* |
| شماره همراه کاربر | Client-User-Id |
| نوع سیستم عامل کاربر(Windows,Android,IOS,Web) | Client-Platform-Type* |
| Application/json | Content-Type* |
| شماره همراه صاحب حساب | Mobile-no* |
| کدملی صاحب حساب | National-code* |
| توکن دریافتی از سرویس لاگین | Authorization* |
پارامترهای ستاره دار اجباری است.
نکته: صفحه OAuth حتما باید در مرورگر باز شود و امکان استفاده در حالت وب ویو وجود دارد.
نکته: در این سرویس Content-Type برابر با Application/x-www-from-urlencoded است.
- برای فراخوانی این سرویس پارامتر های جدول پارامترهای ورودی را در بدنه درخواست ارسال نمایید.
- پس از اجرای درخواست پاسخی با پارامترهای جدول خروجی دریافت می کنید.
| شرح | نوع داده | نام |
| محدودیت‌ها و اطلاعات پیمان در این آبجکت دریافت می‌شود (توضیحات در جدول Payman) | Object | Payman* |
| آدرس بازگشتی (کاربر پس از وارد کردن اطلاعات در صفحه OAuth به این آدرس هدایت خواهد شد) | String | Redirect_url* |
| شماره پیگیری ایجاد پیمان | String | Trace_id* |
پارامترهای ستاره دار اجباری است.
نکته: درخصوص آدرس بازگشتی باید به این نکته توجه کرد که آدرس حتما به فرابوم معرفی گردد تا در لیست آدرس‌های بازگشتی معتبر اضافه گردد. یک موسسه می تواند بیش از یک آدرس بازگشتی معرفی کند و یک آدرس بازگشتی پیش فرض معرفی کند. در صورتی که آدرس بازگشتی ارسال شده در درخواست با آدرس های بازگشتی موسسه در ریکوئست همخوانی نداشته باشد، پیمان کاربر را به آدرس بازگشتی پیش فرض هدایت خواهد کرد.
نکته: صفحه OAuth حتما باید در مرورگر باز شود و امکان استفاده در حالت وب ویو وجود دارد.
نکته: به آدرس بازگشتی می توان یک یا چند کوئری پارام اضافه کرد و پس از هدایت کاربر به آدرس بازگشتی موسسه مقدار مورد نظر خود را دریافت کند. نمونه:
https://snappay.com/?userID=123456 جدول Payman| شرح | نوع داده | نام |
| شناسه بانک | String | Bank_code* |
| شناسه کاربر نزد موسسه | String | User_id* |
| اطلاعات قرارداد (جدول contract) | Object | Contract* |
| لیستی از شناسه دسترسی های موسسه (جدول Permissions) | Enum | Permission_ids* |
پارامترهای ستاره دار اجباری است.
جدول Contract
| شرح | نوع داده | نام |
| تاریخ اتمام قرارداد | DateTime | Expiration_date* |
| سقف تعداد تراکنش روزانه | int | Max_daily_transaction_count* |
| سقف تعداد تراکنش ماهانه | int | Max_monthly_transaction_count |
| سقف مبلغ هر تراکنش | Decimal | Max_transaction_amount* |
| تاریخ شروع قرارداد | DateTime | Start_date |
| سقف مبلغ روزانه هر تراکنش | Decimal | Daily_max_transaction_amount |
پارامترهای ستاره دار اجباری است.
جدول دسترسی‌های موسسه (Permissions)
| شرح | نام |
| برداشت وجه | 1 |
| پرداخت قبض | 2 |
نکته: لازم به ذکر است دسترسی برای همه‌ی موسسه‌ها فقط بر روی سرویس برداشت وجه با مقدار 1 است.
پارامترهای خروجی پاسخ این سرویس در header پاسخ و در پارامتر location باز می گردد. پاسخ یک آدرس است که موسسه می‌بایست کاربر را به آن هدایت کند. در صورت فراخوانی موفق این سرویس 302 status http دریافت می‌شود.| شرح | نوع داده | نام |
| آدرس OAuth فرابوم یا بانک | String | Location |
آدرس ایجاد شده مطابق نمونه زیر خواهد بود و کاربر را به صفحه اوآت بانک
هدایت خواهد کرد:
https://oauth.sandbox.faraboom.co/oauth/authorize?bank_id=SINAIR&boom_token=0JLFX6eAh32a6Gisr5SJeX2DWoFODODwAAD6G6EMMu7EFMU1sQkT6htFuqRBOSaBdywQq8cwf6bOujP530pfIJWVBM&redirect_uri=https%3a%2f%2fpayman2.sandbox.faraboom.co%2ffa%2foauth%2freturn&response_type=code&state=ow_NbTlWKxwm7yEHNJqILA~~&client_id=12594&device_id=192.168.1.1&mobile=09352673656&amount=500000&national_code=0082205388&contract=7htCpP3T/TmMK4qk4Tty4KXNntjxiWGQD8JoVhS5u1H+N8QFntkG/NMF/rn143CX45j8R63uDea40ySnpclnFFt4UBu8H3Dmyg9teS72GzE9VtPftOr9i+o+NXSlVHUyBaUsIBgAOPE5LHUpm0+mq97ZKKpox5O7m5NntHuwmcuDq1AGPJBAW6ROaGmP4fiFm0mSX1D8/YBV1RoSkYcjE+phE9mrZOkpzn6MNZdig3WIv6CCzQ7segAPAneg8xc+VRF10peAJEeZtZ0h1HOrfHQI0b93JhIRoD/g/203tw5SvfdNtEkwQSaci+s8T6pb7CCONO8696Ysjy+hOSc1n9ydxr4dpeFO6wl0ox/xeUs=
نمونه صفحه OAuth
در صفحه OAuth بانک کاربر اطلاعات احراز هویت خود را وارد می کند و در صورت صحت اطلاعات به آدرس بازگشتی موسسه هدایت خواهد شد.
نکته: صفحه OAuth حتما باید در مرورگر باز شود و امکان استفاده در حالت وب ویو وجود دارد.
وضعیت‌های دریافتی در آدرس بازگشتی OAuth مطابق جدول زیر خواهد بود.
| شرح | وضعیت |
| ایجاد موفقیت آمیز پیمان | Created |
| پیمان لغو شده است | Canceled |
| خطای داخلی | InternalError |
| پاسخی دریافت نشده است | Timeout |
نمونه CURL درخواست:
curl --location 'https://payman2.sandbox.faraboom.co/v1/payman/create' \
--header 'app-key: demopayman' \
--header 'Client-Ip-Address: 127.0.0.1' \
--header 'Client-Platform-Type: web' \
--header 'Client-Device-Id: 169.254.75.178' \
--header 'Client-User-Id: 09352673656' \
--header 'Client-User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.117 Safari/537.36' \
--header 'Content-Type: application/json' \
--header 'Mobile-no: 09352673656' \
--header 'National-code: 0082205388' \
--header 'Authorization: Bearer HjS5tzmChsfngBZKEMpxl4KzFYfWfY6ABSKmI9pB1faSZPMWmRFfAh2BsHJXHJaBGPszpL3BQJGQSAXBAz5H3y3gI' \
--header 'Cookie: cookiesession1=678A8C341A085F7AF93FECC7B44ACDFF' \
--data '{
"payman": {
"bank_code": "SINAIR",
"user_id": "demopayman",
"permission_ids": [
1
],
"contract": {
"expiration_date": "2025-01-15T01:28:09.5662061+04:30",
"max_daily_transaction_count": 50,
"max_monthly_transaction_count": 100,
"max_transaction_amount": 500000,
"start_date": "2024-01-15T08:28:09.5662061+04:30"
}
},
"redirect_url": "http://localhost/",
"trace_id": "cdklcdke-b7jk-5hg-997c-b991acdac3b2"
}'
نمونه ورودی سرویس
نمونه خروجی سرویس
لیست کد خطاهای سرویس ایجاد پیمان
| خطا | شرح خطا |
| 071 | ورودی ها صحیح نیستند. |
| 133 | شناسه مشتری تکراری است. |
| 1028 | کد ملی نامعتبر است. |
| 2000 | خطای داخلی بوم |
| 2001 | خطای سرور |
| 2002 | شناسه مورد نظر یافت نشد/نامعتبر است. |
| 2006 | قرارداد پیمان منقضی شده است. |
| 2008 | تاریخ نامعتبر است. |
| 2013 | تعداد تراکنش ها بیش از حد مجاز است. |
| 2014 | واگذاری یافت نشد/نامعتبر است. |
| 2015 | وضعیت موسسه نامعتبر است. |
| 2017 | مقدار ثابت وارد شده نامعتبر است. |
| 2023 | بانک مورد نظر یافت نشد. |
| 2024 | وضعیت بانک نامعتبر است. |
| 2026 | کاربر مجاز به انجام عملیات نیست. |
| 2046 | این پیمان قبلا فعال شده است. |
| 2049 | شماره پیگیری تکراریست. |
| 2050 | گروه متناظر برای این موسسه غیر فعال است. |
| 2051 | خطا در دریافت توکن بانک رخ داده است. |
| 2053 | خطای دسترسی موسسه رخ داده است. |
| 2055 | واگذاری مورد نظر به موسسه جاری تعلق ندارد. |
| 2066 | اطلاعات مورد نیاز در هدر ارسال نشده است. |
| 2074 | دریافت اطلاعات حساب مشتری با خطا مواجه شده است. |
| 2077 | شماره موبایل الزامیست. |
| 2078 | شماره موبایل نامعتبر است. |
| 2081 | وضعیت واگذاری در حالت انتظار نمی‌باشد. |
| 2085 | وضعیت واگذاری در حالت ایجاد شده نمی‌باشد. |
| 2087 | ذخیره مشخصات مشتری با خطا مواجه شده است. |
| 2089 | موسسه مورد نظر با بانک مربوطه قرارداد پیشفرضی ندارد. |
| 2090 | موسسه مورد نظر قرارداد پیشفرض ندارد. |
| 2108 | مبلغ تراکنش روزانه برای این کاربر از مقدار مجاز تعریف شده، بیشتر است. |
| 2110 | شماره حساب فعالی برای این کاربر یافت نشد. |
| 2122 | شناسه قرارداد نباید خالی باشد. |
| 2126 | حداکثر مقدار مجاز تراکنش روزانه باید بزرگتر از حداکثر مقدار مجاز هر تراکنش باشد. |
| 2130 | شماره سپرده خالی است. |
| 2156 | کنسل شدن پیمان توسط کاربر در صفحه OAuth |
| 2167 | بازه پیمان در این بانک نمی تواند بیشتر از یک سال باشد. |
| 2182 | خطا در تغییر وضعیت قرارداد پیمان |
| 2184 | تغییر واگذارکننده در قرارداد پیمان با خطا مواجه شد. |
| 2187 | شماره قرارداد موسسه برای بلو بانک یافت نشد. |
| 2197 | ذخیره شماره کارت در قرارداد پیمان با خطا مواجه شد. |
| 2203 | آدرس بازگشتی وارد شده یافت نشد. |
| 2205 | موسسه به بانک مورد نظر دسترسی ندارد. |
| 2226 | مقادیر حداکثر مقدار مجاز هر تراکنش و حداکثر مقدار مجاز تراکنش روزانه نمیتوانند همزمان خالی باشند. |
لیست کد خطاهای مرحله بازگشت به موسسه (Redirection)
| خطا | شرح خطا |
| 2001 | خطای سرور |
| 2051 | خطا در توکن بانک رخ داده است. |
| 2087 | ذخیره اطلاعات مشتری با خطا مواجه شده است. |
| 2110 | امکان ایجاد قرارداد بر روی حساب های مشترک و جاری وجود ندارد. |
| 2156 | کنسل توسط کاربر در صفحه OAuth |
| 2203 | آدرس بازگشتی وارد شده یافت نشد. |
سرویس دریافت شناسه پیمان (Payman Get ID)
آدرس:
https://payman2.sandbox.faraboom.co/v1/payman/getId?payman_code={sampleCode}
متد : (GET)
در آدرس بازگشتی موسسه که کاربر به آن هدایت شده است پارامتری به نام payman_code وجود دارد. در صورتی که وضعیت نمایش داده شده در این آدرس برابر با CREATED بود می بایست جهت فعالسازی پیمان، سرویس دریافت شناسه پیمان فراخوانی گردد.
در این سرویس، موسسه با وارد کردن کد پیمان (payman_code) می تواند شناسه پیمان
هایی که وضعیت آنها در انتظار تایید (WATING_FOR_CONFIRM) است و هنوز منقضی نشده
اند را به وضعیت ACTIVE تبدیل کند. پارامترهای Header درخواست
پارامترهای ستاره دار اجباری است. پارامترهای بدنه درخواست متد این درخواست GET است
و پیمان کد بصورت کوئری پارام ارسال خواهد شد.
پارامترهای ستاره دار اجباری است. پارامترهای خروجی
| شرح | نام |
| شناسه موسسه | App-key* |
| توکن دریافتی از سرویس لاگین | Authorization* |
| شرح | نوع داده | نام |
| پیمان کد | String | Payman_code* |
| شرح | نوع داده | نام |
| شناسه پیمان | String | Payman_id |
| وضعیت پیمان (در این سرویس همیشه ACTIVE بازمی‌گردد) | String | Status |
| شماره حساب | String | Deposit |
پس از فراخوانی موفق این سرویس، امکان برداشت از حساب کاربر با استفاده از سرویس
برداشت وجود خواهد داشت.
نمونه CURL درخواست
curl --location
'https://payman2.sandbox.faraboom.co/v1/payman/getId?payman_code=2gZ04Yx9iHEP'--header
'Authorization: Bearer
HjS5tzmChsfngBZKEMpxl4KzFYfWfY6ABSKmI9pB1faSZPMWmRFfAh2BsHJXHJaBGPszpL3BQJGQSAXBAz5H3y3gI'
--header 'App-Key: demopayman' --header 'Cookie:
cookiesession1=678A8C341A085F7AF93FECC7B44ACDFF'
نمونه ورودی سرویس
نمونه خروجی سرویس
لیست کد خطاهای سرویس دریافت شناسه پیمان
| خطا | شرح خطا |
| 071 | پارامترهای ورودی به درستی وارد نشده‌اند. |
| 2001 | خطای سرور |
| 2002 | شناسه موسسه مورد نظر یافت نشده/نامعتبر است. |
| 2006 | پیمان منقضی شده است. |
| 2010 | وضعیت پیمان نامعتبر است. |
| 2014 | کد پیمان مورد نظر یافت نشد/نامعتبر است. |
| 2066 | اطلاعات مورد نیاز در هدر ارسال نشده است. |
سرویس پیگیری ایجاد پیمان (Trace Payman)
آدرس:
https://payman2.sandbox.faraboom.co/v1/payman/create/trace?trace-id={trace-id}
متد: (GET)
توضیحات
از این سرویس جهت پیگیری وضعیت و دریافت اطلاعات یک پیمان استفاده می‌گردد.
پارامترهای Header درخواست
پارامترهای ستاره دار اجباری است. پارامترهای بدنه درخواست: متد این درخواست GET
است و شناسه پیگیری بصورت کوئری پارام ارسال خواهد شد.
پارامترهای ستاره دار اجباری است. پارامتر ورودی سرویس پیگیری ایجاد یک پیمان
trace-id است که این مقدار توسط موسسه در سرویس ایجاد پیمان ارسال شده است.
پارامترهای خروجی
جدول Contract
جدول دسترسی‌های موسسه (Permissions)
| شرح | نام |
| شناسه موسسه | App-key* |
| شناسه سخت افزار کاربر | Client-Device-Id* |
| آدرس IP سیستم کاربر | Client-Ip-Address* |
| مشخصات سخت افزار کاربر | Client-User-Agent* |
| شماره همراه کاربر | Client-User-Id |
| نوع سیستم عامل کاربر(Windows,Android,IOS,Web) | Client-Platform-Type* |
| توکن دریافتی از سرویس لاگین | Authorization* |
| شرح | نوع داده | نام |
| شناسه پیگیری | String | Trace-id* |
| شرح | نوع داده | نام |
| شناسه بانک | String | Bank_code |
| شناسه کاربر نزد موسسه | String | User_id |
| شناسه پیمان | String | Payman_id |
| وضعیت پیمان | String | Status |
| آخرین وضعیت پیمان | String | Internal_status |
| لیست دسترسی‌های موسسه | Enum | Permission_ids |
| اطلاعات قرارداد (جدول Contract) | Object | Contract |
| شرح | نوع داده | نام |
| تاریخ اتمام قرارداد | int | Expiration_date |
| سقف تعداد تراکنش روزانه | int | Max_daily_transaction_count |
| سقف تعداد تراکنش ماهانه | int | Max_monthly_transaction_count |
| سقف مبلغ هر تراکنش | Decimal | Max_transaction_amount |
| تاریخ شروع قرارداد | int | Start_date |
| شرح | نام |
| برداشت وجه | 1 |
| پرداخت قبض | 2 |
وضعیت‌های یک پیمان
| شرح | نام |
| در حال ایجاد | INITIALIZING |
| فعال | ACTIVE |
| غیرفعال | DEACTIVE |
| در انتظار تایید | WATING_FOR_CONFIRM |
| لغو شده | CANCELLED |
| منقضی شده | EXPIRED |
INITIALIZING: از زمان ارسال درخواست ایجاد
پیمان تا زمانی که کاربر بر روی دکمه تایید کلیک میکند وضعیت پیمان در این
حالت قرار دارد.
ACTIVE: پس از فراخوانی موفق سرویس دریافت
شناسه پیمان، وضعیت پیمان به ACTIVE تغییر پیدا میکند.
DEACTIVE: در صورتی که موسسه با استفاده از
سرویس تغییر وضعیت یک پیمان یا کاربر از طریق پنل پیمان اقدام به غیرفعالسازی
کند وضعیت به غیرفعال تغییر میکند.
WATING_FOR_CONFIRM: پس از تایید کاربر تا
زمان فراخوانی سرویس دریافت شناسه پیمان، وضعیت پیمان در این حالت خواهد بود.
CANCELLED: در صورتی که حین فرآیند ایجاد
پیمان و یا فراخوانی سرویس تغییر وضعیت پیمان و یا لغو پیمان توسط کاربر وضعیت
پیمان به CANCELLED تغییر پیدا می کند.
EXPIRED: در صورتی که زمان انقضای پیمان فرا
برسد، وضعیت پیمان به این حالت تغییر میکند.
نمونه CURL درخواست:
curl --location 'https://payman2.sandbox.faraboom.co/v1/payman/create/trace?trace-id=cdklcdke-b7jk-5hg-997c-b991acdac3b2'--header 'Authorization: Bearer HjS5tzmChsfngBZKEMpxl4KzFYfWfY6ABSKmI9pB1faSZPMWmRFfAh2BsHJXHJaBGPszpL3BQJGQSAXBAz5H3y3gI'
--header 'App-Key: demopayman'
--header 'Client-Ip-Address: 127.0.0.1'
--header 'Client-Platform-Type: WEB'
--header 'Client-Device-Id: 127.0.0.1'
--header 'Client-User-Id: 09352673656'
--header 'Client-User-Agent: firefox5.0'
--header 'Cookie: cookiesession1=678A8C341A085F7AF93FECC7B44ACDFF'
نمونه ورودی سرویس
نمونه خروجی سرویس
لیست کد خطاهای سرویس پیگیری ایجاد یک پیمان:
| خطا | شرح خطا |
| 071 | پارامترهای ورودی به درستی وارد نشده اند. |
| 2001 | خطای سرور |
| 2002 | شناسه موسسه مورد نظر یافت نشد/نامعتبر است. |
| 2014 | واگذاری یافت نشد. |
| 2021 | شماره پیگیری یافت نشد. |
| 2066 | اطلاعات مورد نیاز در هدر ارسال نشده است. |
سرویس برداشت وجه مستقیم (Payman Pay)
آدرس:
https://payman2.sandbox.faraboom.co/v1/payman/pay
متد: (POST)
پس از فعالسازی پیمان، با استفاده از سرویس برداشت وجه مستقیم امکان برداشت از حساب
کاربر در بازه محدودیت های تعیین شده در سرویس ایجاد پیمان امکان پذیر خواهد بود.
پارامترهای Header درخواست
| شرح | نام |
| شناسه موسسه | App-key* |
| Application/json | Content-Type* |
| توکن دریافتی از سرویس لاگین | Authorization* |
| شرح | نوع داده | نام |
| شماره پیگیری تراکنشی که موسسه ارسال میکند | String | Trace_id* |
| شناسه پیمان | String | Payman_id* |
| مبلغ | Decimal | Amount* |
| شرح تراکنش | String | Description* |
| تاریخ ارسال تراکنش | DateTime | Client_transaction_date* |
| شناسه پرداخت، در صورتی که روش پرداخت موسسه شناسه‌دار باشد | String | Pay_id |
| کارمزد تراکنش، در صورتی که نوع برداشت آنی باشد این پارامتر ارسال گردد. | Decimal | Commission_amount |
| شرح | نوع داده | نام |
| شماره پیگیری بانک | String | Reference_id |
| شماره پیگیری موسسه | String | Trace_id |
| مبلغ تراکنش | Decimal | Transaction_amount |
| زمان تراکنش (Epoch) | DateTime | Transaction_time |
| دسته تراکنش | Long | Batch_id |
| مبلغ کارمزد | Decimal | Commission_amount |
| وضعیت تراکنش (جدول Status) | Enum | Status |
| لیستی از تراکنشها | <List> | Details |
| شرح | نوع داده | نام |
| شماره پیگیری بانک | String | Reference_id |
| شماره پیگیری موسسه | String | Trace_id |
| مبلغ تراکنش | Decimal | amount |
| زمان تراکنش (Epoch) | DateTime | Transaction_time |
| نوع تراکنش (PAYMAN_COMMISSION/MAIN) | Enum | Transaction_detail_type |
| وضعیت تراکنش (جدول Status) | Enum | Status |
| شرح | نام |
| در حال پردازش | IN_PROGRESS |
| ناموفق | FAILED |
| موفق | SUCCEED |
| برگشت خورده | REVERSED |
| پاسخی از بانک دریافت نشد | TIMEOUT |
curl --location 'https://payman2.sandbox.faraboom.co/v1/payman/pay' --header
'Authorization: Bearer
HjS5tzmChsfngBZKEMpxl4KzFYfWfY6ABSKmI9pB1faSZPMWmRFfAh2BsHJXHJaBGPszpL3BQJGQSAXBAz5H3y3gI'
--header 'App-Key: demopayman' --header 'Content-Type: application/json'
--header 'Cookie: cookiesession1=678A8C341A085F7AF93FECC7B44ACDFF' --data '{
"trace_id": "djlgmnae-b85e-5hg-s97c-b991acdacdfg", "payman_id":
"vDZsJGKXPIVS", "amount": 300000, "description": "Transfer for user",
"client_transaction_date": "2024-01-17T18:46:11.000Z" }'
نمونه خروجی سرویس
لیست کد خطاهای سرویس برداشت وجه مستقیم
| خطا | شرح خطا |
| 002 | ارز مبدا مقصد یکسان نیست/کد ارز مورد نظر در سیستم تعریف نشده. |
| 003 | موجودی سپرده کافی نیست. |
| 004 | سپرده متعلق به کاربر نیست/عدم امکان دسترسی به سپرده/عدم وجود حق برداشت/برداشت امکان پذیر نیست. |
| 027 | مبلغ ورودی نامعتبر است. |
| 032 | شماره سپرده نامعتبر است. |
| 071 | پارامترهای ورودی به درستی وارد نشده اند. |
| 1515 | شناسه پرداخت باید خالی باشد. |
| 1516 | مقدار کارمزد باید خالی باشد. |
| 2000 | خطای داخلی بوم |
| 2001 | خطاهای داخلی پیمان |
| 2002 | شناسه موسسه مورد نظر یافت نشده/نامعتبر است. |
| 2003 | محدودیت تعداد تراکنش روزانه برای این واگذاری رعایت نشده است. |
| 2004 | محدودیت تعداد تراکنش ماهانه برای این واگذاری رعایت نشده است. |
| 2005 | زمان پیمان شروع نشده است. |
| 2006 | واگذاری منقضی شده است. |
| 2007 | واگذار کننده به عنوان مشتری بانک موردنظر ثبت نشده است. |
| 2010 | وضعیت واگذاری نامعتبر است. |
| 2011 | شماره پیگیری تکراری/نامعتبر است. |
| 2012 | زمان انجام تراکنش برای این واگذاری نامعتبر است. |
| 2013 | تعداد تراکنش ها بیش از حد مجاز است. |
| 2014 | شماره واگذاری یافت نشد/نامعتبر است. |
| 2015 | وضعیت موسسه نامعتبر است. |
| 2023 | بانک مورد نظر یافت نشد. |
| 2036 | مبلغ تراکنش از مقدار مجاز تعریف شده، بیشتر است. |
| 2049 | شماره پیگیری تکراریست. |
| 2059 | زمان تراکنش قبل از زمان مورد توافق در واگذاری است. |
| 2060 | زمان تراکنش بعد از زمان مورد توافق در واگذاری است. |
| 2061 | مقدار تراکنش از مقدار توافق شده کمتر است. |
| 2063 | تعداد تراکنش های انجام شده از تعداد مجاز روزانه بیشتر است. |
| 2064 | تعداد تراکنش های انجام شده از تعداد مجاز ماهانه بیشتر است. |
| 2066 | اطلاعات مورد نیاز در هدر ارسال نشده است. |
| 2135 | کارت منقضی شده است/ کارت بسته شده است |
| 2149 | موسسه مورد نظر در بانک انتخابی، حساب بانکی ندارد. |
| 2150 | کارمزد اجباری است. |
| 2052 | خطای دسترسی واگذاری رخ داده است. |
| 2053 | خطای دسترسی موسسه رخ داده است. |
| 2055 | واگذاری مورد نظر به موسسه جاری تعلق ندارد. |
| 2057 | بانک مبدا فعال نیست. |
| 2058 | واگذاری مورد نظر فعال نیست. |
| 2062 | مبلغ برداشت مستقیم بیشتر از حداکثر مبلغ برداشت در پیمان است. |
| 2082 | پیمان در بانک مربوطه حساب ثبت شده ای ندارد. |
| 2108 | مبلغ تراکنش روزانه برای این کاربر از مقدار مجاز تعریف شده ، بیشتر است. |
| 2148 | برداشت آنی برای بانک های با حساب واسط قابل انجام نیست. |
| 2154 | این پیمان در بانک لغو شده است. |
| 2056 | موسسه مورد نظر فعال نیست. |
| 2065 | سقف مبلغ برداشت برای این موسسه پر شده است. |
| 2121 | زمان مجاز برای اجرا به پایان رسیده است. |
| 2175 | شناسه پرداخت الزامی است. |
| 10005 | توکن بانکی نامعتبر |
| 10110 | شماره سپرده مورد نظر وجود ندارد. |
| 20950 | حداکثر تعداد برداشت روزانه بیش از محدودیت در نظر گرفته شده در SLA است. |
| 20953 | حداکثر مبلغ هر برداشت بیش از محدودیت در نظر گرفته شده در SLA است. |
سرویس پیگیری برداشت وجه مستقیم Pay Trace))
آدرس:
https://payman2.sandbox.faraboom.co/v1/payman/pay/trace?trace-id={trace-id}
متد:(GET)
توضیحات:
با استفاده از این سرویس می‌توان وضعیت یک برداشت را پیگیری کرد. پارامترهای Header
درخواست
پارامترهای ستاره دار اجباری است. پارامترهای بدنه درخواست: متد این درخواست GET
است و پارامترها به صورت کوئری پارام ارسال خواهد شد.
پارامترهای ستاره دار اجباری است.
پارامترهای خروجی:
جدول نوع تراکنش (Transaction_type)
نکته: برای بانکهای ملت، ملی، کشاورزی، بلو تراکنش از نوع
PAYMAN_PAYMENT است. جدول وضعیت (Status)
نمونه CURL درخواست
| شرح | نام |
| شناسه موسسه | App-key* |
| شناسه سخت افزار کاربر | Client-Device-Id* |
| آدرس IP سیستم کاربر | Client-Ip-Address* |
| مشخصات سخت افزار کاربر | Client-User-Agent* |
| شماره همراه کاربر | Client-User-Id |
| نوع سیستم عامل کاربر(Windows,Android,IOS,Web) | Client-Platform-Type* |
| توکن دریافتی از سرویس لاگین | Authorization* |
| شرح | نوع داده | نام |
| شماره پیگیری تراکنش که موسسه ارسال میکند | String | Trace_id* |
| تاریخ تراکنش | DateTime | Date* |
| شرح | نوع داده | نام |
| ارز | String | Currency |
| شرح تراکنش | String | Description |
| بانک مقصد | String | Destination_bank |
| سپرده مقصد | String | Destination_deposit |
| بانک مبدا | String | Source_bank |
| سپرده مبدا | String | Source_deposit |
| نوع تراکنش(جدول Transaction_type) | Enum | Transaction_type |
| شماره پیگیری تراکنش | String | Reference_id |
| شماره پیگیری موسسه | String | Trace_id |
| مبلغ تراکنش | Decimal | Transaction_amount |
| زمان تراکنش (Epoch) | DateTime | Transaction_time |
| دسته تراکنش | Long | Batch_id |
| کارمزد تراکنش | Decimal | Commision_amount |
| وضعیت تراکنش (جدول Status) | Enum | Status |
| شناسه قبض | String | Bill_id |
| شناسه پرداخت | String | Pay_id |
| شرح | نام |
| انتقال وجه داخلی | NORMAL |
| انتقال وجه پایا | ACH |
| انتقال وجه ساتنا | RTGS |
| پرداخت قبض | BILL_PAYMENT |
| تراکنش بازگشت وجه | REVERSE |
| برداشت پیمان | PAYMAN_PAYMENT |
| تراکنش تسویه | PAYMAN_SETTLEMENT |
| تراکنش از اعتبار هدیه | BY_WALLET |
| تراکنش آنی با کارمزد | INSTANT_WITHDRAWAL_WITH_COMISSION |
| تراکنش آنی | INSTANT_WITHDRAWAL |
| شرح | نام |
| در حال پردازش | IN_PROGRESS |
| ناموفق | FAILED |
| موفق | SUCCEED |
| برگشت خورده | REVERSED |
| پاسخی از بانک دریافت نشد | TIMEOUT |
curl --location
'https://payman2.sandbox.faraboom.co/v1/payman/pay/trace?trace-id=ddvbdfde-b72e-5hg-997c-b991acdacdfg&date=2023-10-18'
--header 'Authorization: Bearer
HjS5tzmChsfngBZKEMpxl4KzFYfWfY6ABSKmI9pB1faSZPMWmRFfAh2BsHJXHJaBGPszpL3BQJGQSAXBAz5H3y3gI'
--header 'App-Key: demopayman' --header 'Client-Ip-Address: 127.0.0.1'
--header 'Client-Platform-Type: WEB' --header 'Client-Device-Id: 127.0.0.1'
--header 'Client-User-Id: 09352673656' --header 'Client-User-Agent:
firefox5.0' --header 'Cookie: cookiesession1=678A8C341A085F7AF93FECC7B44ACDFF'
نمونه ورودی سرویس
نمونه خروجی سرویس
لیست کد خطاهای سرویس پیگیری برداشت وجه مستقیم
| خطا | شرح خطا |
| 071 | پارامترهای ورودی به درستی وارد نشده اند. |
| 2001 | خطاهای داخلی پیمان |
| 2002 | شناسه موسسه مورد نظر یافت نشده/نامعتبر است. |
| 2021 | شماره پیگیری یافت نشد/نامعتبر است. |
| 2244 | شناسه بازپرداخت یافت نشد. |
| 2045 | دسته (Batch) یافت نشد. |
| 2066 | اطلاعات مورد نیاز در هدر ارسال نشده است. |
سرویس بروزرسانی پیمان (Update Payman)
آدرس:
https://payman2.sandbox.faraboom.co/v1/payman/update
متد: (POST)
توضیحات از طریق سرویس بروزرسانی پیمان، قرارداد موجود با کاربر نهایی
را می توان ویرایش کرد. این سرویس مشابه ایجاد پیمان است. موسسه پس از ارسال مواردی
از قرارداد که می خواهد تغییر کنند، پاسخ با code status برابر با 302 خواهد گرفت و
آدرس صفحه لاگین در location در بخش Header پاسخ سرویس بازگردانده خواهد شد که
کاربر از طریق این URL به صفحه لاگین بانکی منتقل خواهد شد. در نهایت پس از الگین
موفق و تایید مفاد قرارداد جدید، کاربر به همراه شناسه پیمان و نتیجه ویرایش پیمان
به آدرسی که هنگام ایجاد پیمان در مقدار URL-Redirect ثبت شده، منتقل خواهد شد.
پارامترهای Header درخواست
| شرح | نام |
| شناسه موسسه | App-key* |
| شناسه سخت افزار کاربر | Client-Device-Id* |
| آدرس IP سیستم کاربر | Client-Ip-Address* |
| مشخصات سخت افزار کاربر | Client-User-Agent* |
| شماره همراه کاربر | Client-User-Id |
| نوع سیستم عامل کاربر(Windows,Android,IOS,Web) | Client-Platform-Type* |
| Application/json | Content-Type* |
| شماره همراه صاحب حساب | Mobile-no* |
| کدملی صاحب حساب | National-code* |
| توکن دریافتی از سرویس لاگین | Authorization* |
پارامترهای ستاره دار اجباری است.
نکته: صفحه OAuth حتما باید در مرورگر باز شود و امکان استفاده در
حالت وب ویو وجود دارد.
نکته: در این سرویس Content-Type برابر با
Application/x-www-from-urlencoded است.
- برای فراخوانی این سرویس پارامتر های جدول پارامترهای ورودی را در بدنه درخواست
ارسال نمایید. - پس از اجرای درخواست پاسخی با پارامترهای جدول خروجی دریافت می کنید.
پارامترهای بدنه درخواست
| شرح | نوع داده | نام |
| شناسه پیمان | String | Payman_id* |
| تاریخ اتمام قرارداد | DateTime | expiration_date |
| سقف تعداد تراکنش روزانه | int | max_daily_transaction_count |
| سقف تعداد تراکنش ماهانه | int | max_monthly_transaction_count |
| سقف مبلغ هر تراکنش | Decimal | max_transaction_amount |
| سقف مبلغ روزانه هر تراکنش | Decimal | daily_max_transaction_amount |
| آدرس بازگشتی موسسه | String | Redirect_url |
پارامترهای ستاره دار اجباری است.
نکته: درخصوص آدرس بازگشتی باید به این نکته توجه کرد که آدرس
حتما به پیمان معرفی گردد تا در لیست آدرس‌های بازگشتی معتبر اضافه گردد. یک موسسه
می‌تواند بیش از یک آدرس بازگشتی معرفی کند و یک آدرس بازگشتی را به عنوان آدرس
پیشفرض تعیین کند. در صورتی که آدرس بازگشتی ارسال شده در درخواست با آدرس های
بازگشتی موسسه در ریکوئست همخوانی نداشته باشد، پیمان کاربر را به آدرس بازگشتی پیش
فرض هدایت خواهد کرد.
نکته: صفحه OAuth حتما باید در مرورگر باز شود و امکان استفاده در
حالت وب ویو وجود دارد. پارامترهای خروجی پاسخ این سرویس در header پاسخ و در
پارامتر location باز می گردد. پاسخ یک آدرس است که موسسه می‌بایست کاربر را به آن
هدایت کند. در صورت فراخوانی موفق این سرویس 302 status http دریافت می‌شود.
| شرح | نوع داده | نام |
| آدرس OAuth فرابوم یا بانک | String | location |
در صفحه OAuth بانک کاربر اطلاعات احراز هویت خود را وارد می کند و در صورت صحت
اطلاعات به آدرس بازگشتی موسسه هدایت خواهد شد.
نکته: صفحه OAuth حتما باید در مرورگر باز شود و امکان استفاده در
حالت وب ویو وجود دارد.
نکته: بعد از بروزرسانی پیمان نیازی به فراخوانی مجدد سرویس
دریافت شناسه پیمان نیست و می‌توان با شناسه پیمان دریافتی در هنگام ایجاد پیمان،
از سرویس‌ها استفاده کرد. وضعیت‌های دریافتی در آدرس بازگشتی OAuth مطابق جدول زیر
خواهد بود.
| شرح | وضعیت |
| بروزرسانی موفق پیمان | Updated |
| پیمان لغو شده است | Canceled |
| خطای داخلی | InternalError |
| پاسخی دریافت نشده است | Timeout |
نمونه CURL درخواست
curl --location 'https://payman2.sandbox.faraboom.co/v1/payman/update'
--header 'Authorization: Bearer HjS5tzmChsfngBZKEMpxl4KzFYfWfY6ABSKmI9pB1faSZPMWmRFfAh2BsHJXHJaBGPszpL3BQJGQSAXBAz5H3y3gI'
--header 'app-key: demopayman'
--header 'Content-Type: application/json'
--header 'Client-Ip-Address: 127.0.0.1'
--header 'Client-Platform-Type: web'
--header 'Client-Device-Id: 169.254.75.178'
--header 'Client-User-Id: 09352673656'
--header 'Client-User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.117 Safari/537.36'
--header 'mobile-no: 09352673656'
--header 'national-code: 0082205388'
--header 'Cookie: cookiesession1=678A8C341A085F7AF93FECC7B44ACDFF'
--data '{
"payman_id": "vf8jwZ4PK9jq",
"expiration_date": "2024-12-30T11:41:53.871Z",
"max_daily_transaction_count": 14,
"max_monthly_transaction_count": 300,
"max_transaction_amount": 2000000,
"redirect_url": "http://localhost/"
}'
نمونه ورودی سرویس
نمونه خروجی سرویس
لیست کد خطاهای سرویس بروزرسانی پیمان
| خطا | شرح خطا |
| 004 | سپرده متعلق به کاربر نیست/عدم امکان دسترسی به سپرده/عدم وجود حق برداشت/برداشت امکان پذیر نیست. |
| 071 | پارامترهای ورودی به درستی وارد نشده اند. |
| 2000 | خطای داخلی بوم |
| 2001 | خطاهای داخلی پیمان |
| 2002 | شناسه موسسه مورد نظر یافت نشد/نامعتبر است. |
| 2008 | تاریخ ورودی برای این قرارداد نامعتبر است. |
| 2010 | وضعیت واگذاری نامعتبر است. |
| 2011 | شماره پیگیری مورد نظر یافت نشد/نامعتبر است. |
| 2013 | تعداد تراکنش ها بیش از حد مجاز است. |
| 2014 | شماره پیمان یافت نشد/نامعتبر است. |
| 2015 | وضعیت موسسه نامعتبر است. |
| 2017 | مقدار نآدرست برای مقادیر ثابت. |
| 2023 | بانک مورد نظر یافت نشد. |
| 2024 | وضعیت بانک نامعتبر است. |
| 2026 | کاربر مجاز به انجام عملیات نیست. |
| 2035 | کدملی که برای صاحب شماره موبایل ثبت شده است، با کدملی لاگ‌این کننده مغایرت دارد. |
| 2066 | اطلاعات مورد نیاز در هدر ارسال نشده است. |
| 2098 | عدم تطابق شماره موبایل رخ داده است. |
| 2097 | عدم تطابق کد ملی رخ داده است. |
| 2108 | مبلغ تراکنش روزانه برای این کاربر از مقدار مجاز تعریف شده ، بیشتر است. |
| 2126 | حداکثر مقدار مجاز تراکنش روزانه باید بزرگتر از حداکثر مقدار مجاز هر تراکنش باشند. |
| 2226 | مقادیر حداکثر مقدار مجاز هر تراکنش و حداکثر مقدار مجاز تراکنش روزانه نمیتوانند همزمان خالی باشند. |
| 10110 | شماره سپرده مورد نظر وجود ندارد. |
| 20952 | مجوز برداشت مستقیم قبلا لغو شده است. |
سرویس تغییر وضعیت پیمان (Payman Status Change)
آدرس:
https://payman2.sandbox.faraboom.co/v1/payman/status/change
متد:(POST)
توضیحات
با استفاده از این سرویس موسسه می‌تواند وضعیت یک پیمان را تغییر دهد. پارامترهای
Header درخواست
| شرح | نام |
| شناسه موسسه | App-key* |
| شناسه سخت افزار کاربر | Client-Device-Id* |
| آدرس IP سیستم کاربر | Client-Ip-Address* |
| مشخصات سخت افزار کاربر | Client-User-Agent* |
| شماره همراه کاربر | Client-User-Id |
| نوع سیستم عامل کاربر(Windows,Android,IOS,Web) | Client-Platform-Type* |
| Application/json | Content-Type* |
| توکن دریافتی از سرویس لاگین | Authorization* |
پارامترهای ستاره دار اجباری است. پارامترهای بدنه درخواست
| شرح | نوع داده | نام |
| وضعیت جدید پیمان (جدول new status) | String | New_status* |
| شناسه پیمان | String | Payman_id* |
پارامترهای ستاره دار اجباری است. جدول وضعیت جدید (New_status)
| شرح | نام |
| فعال | ACTIVE |
| غیرفعال | DEACTIVE |
| لغو | CANCELLED |
نمودار تغییر وضعیت پیمان
پارامترهای خروجی
| شرح | نوع داده | نام |
| شناسه پیمان | String | Payman_id |
| وضعیت | String | Status |
پارامترهای ستاره دار اجباری است.
نمونه CURL درخواست
curl --location
'https://payman2.sandbox.faraboom.co/v1/payman/status/change'--header
'Authorization: Bearer
HjS5tzmChsfngBZKEMpxl4KzFYfWfY6ABSKmI9pB1faSZPMWmRFfAh2BsHJXHJaBGPszpL3BQJGQSAXBAz5H3y3gI'
--header 'App-Key: demopayman' --header 'Content-Type: application/json'
--header 'Client-Ip-Address: 127.0.0.1' --header 'Client-Platform-Type: WEB'
--header 'Client-Device-Id: 127.0.0.1' --header 'Client-User-Id: 09352673656'
--header 'Client-User-Agent: firefox5.0' --header 'Cookie:
cookiesession1=678A8C341A085F7AF93FECC7B44ACDFF' --data '{ "new_status":
"deactive", "payman_id": "73v47Uja2XM8" }'
نمونه ورودی سرویس
نمونه خروجی سرویس
لیست کدخطاهای سرویس تغییر وضعیت پیمان
| خطا | شرح خطا |
| 071 | پارامترهای ورودی به درستی وارد نشده اند. |
| 2001 | خطاهای داخلی پیمان |
| 2002 | شناسه موسسه مورد نظر یافت نشده/نامعتبر است. |
| 2014 | شماره پیمان مورد نظر یافت نشد/نامعتبر است. |
| 2016 | وضعیت این پیمان قابل تغییر نیست. |
| 2017 | مقدار نادرست برای مقادیر ثابت. |
| 2026 | کاربر مجاز به انجام عملیات نیست. |
| 2055 | واگذاری مورد نظر به موسسه جاری تعلق ندارد. |
| 2066 | اطلاعات مورد نیاز در هدر ارسال نشده است. |
| 2165 | مقدار فیلد زمان انقضا می بایست بزرگتر از زمان فعلی باشد. |
| 2183 | مقدار new Status نامعتبر است. |
| 2185 | قرارداد پیمان قبلا لغو شده است. |
سرویس گزارش آماری یک پیمان (Payman Statistic Report)
آدرس:
https://payman2.sandbox.faraboom.co/v1/payman/report/{paymanId}
متد:(GET)
توضیحات
این سرویس برای دریافت اطلاعات آماری یک پیمان است. پارامترهای Header درخواست
پارامترهای ستاره دار اجباری است. پارامترهای بدنه درخواست متد این درخواست GET است
و پارامتر به صورت پت پارام ارسال می‌گردد.
پارامترهای ستاره دار اجباری است. پارامترهای خروجی
نمونه CURL درخواست
| شرح | نام |
| شناسه برنامه | App-key* |
| آدرس IP سرور برنامه | Device-Id* |
| شناسه سخت افزار کاربر | Client-Device-ID* |
| آدرس IP سیستم کاربر | Client-IP-Address* |
| مشخصات سخت افزار کاربر | Client-User-Agent* |
| شماره همراه کاربر | Client-User-ID* |
| نوع سیستم عامل کاربر(Windows,Android,IOS,Web) | Client-Platform-Type* |
| شرح | نوع داده | نام |
| شناسه پیمان | String | Payman-id |
| شرح | نوع داده | نام |
| شناسه پیمان | String | Payman_id |
| تاریخ انقضای پیمان (Epoch) | DateTime | Expiration_date |
| تاریخ شروع پیمان (Epoch) | DateTime | Start_date |
| تعداد تراکنش‌های باقیمانده در روز | Int | Remaining_daily_transaction_count |
| تعداد تراکنش‌های باقیمانده در ماه | Int | Remaining_monthly_transaction_count |
| زمان پایان ماه جاری (Epoch) | DateTime | End_of_current_month |
| حداکثر تعداد تراکنش روزانه | Int | Max_daily_transactions_count |
| حداکثر تعداد تراکنش ماهانه | Int | Max_monthly_transactions_count |
| تعداد روز باقیمانده | Int | Remaining_days |
| مبلغ باقیمانده روزانه | Decimal | Remaining_daily_transaction_amount |
curl --location
'https://payman2.sandbox.faraboom.co/v1/payman/report/73v47Uja2XM8' \ --header
'Authorization: Bearer
HjS5tzmChsfngBZKEMpxl4KzFYfWfY6ABSKmI9pB1faSZPMWmRFfAh2BsHJXHJaBGPszpL3BQJGQSAXBAz5H3y3gI'
\ --header 'App-Key: demopayman' --header 'Client-Ip-Address: 127.0.0.1'
--header 'Client-Platform-Type: WEB' --header 'Client-Device-Id: 127.0.0.1'
--header 'Client-User-Id: 09352673656' --header 'Client-User-Agent:
firefox5.0' --header 'Cookie: cookiesession1=678A8C341A085F7AF93FECC7B44ACDFF'
نمونه ورودی سرویس
نمونه خروجی سرویس
سرویس تراکنش‌های یک پیمان (Payman Transactions)
آدرس:
https://payman2.sandbox.faraboom.co/v1/payman/transactions
متد: (POST)
توضیحات
این سرویس برای دریافت اطلاعات تراکنشها روی پیمان‌های مختلف، برای کاربران مختلف،
بر حسب فیلتر اطلاعات تراکنش است. پارامترهای Header درخواست
پارامترهای ستاره دار اجباری است.
| شرح | نام |
| شناسه برنامه | App-key* |
| آدرس IP سرور برنامه | Device-Id* |
| شناسه سخت افزار کاربر | Client-Device-ID* |
| آدرس IP سیستم کاربر | Client-IP-Address* |
| مشخصات سخت افزار کاربر | Client-User-Agent* |
| شماره همراه کاربر | Client-User-ID* |
| نوع سیستم عامل کاربر(Windows,Android,IOS,Web) | Client-Platform-Type* |
| application/json | Content-Type* |
پارامترهای بدنه درخواست
پارامترهای ستاره دار اجباری است.
| شرح | نوع داده | نام |
| اولین رکورد | Int | Offset* |
| تعداد رکورد بازگشتی | Int | Length* |
| مجموعه از فیلترها (جدول Filter) | Object | Filter* |
جدول فیلتر (Filter)
| شرح | نوع داده | نام |
| لیستی از پیمان‌ها | <List> | Payman_ids |
| لیستی از شناسه‌های کاربر | <List> | User_ids |
| شماره پیگیری تراکنش موسسه | String | Trace_id |
| شماره پیگیری بانک | String | Reference_id |
| نوع تراکنش (جدول Transaction_type) | Enum | Transaction_type |
| مبلغ تراکنش از | Decimal | From_transaction_amount |
| مبلغ تراکنش تا | Decimal | To_transaction_amount |
| تاریح تراکنش از (Epoch) | DateTime | From_transaction_date |
| تاریخ تراکنش تا (Epoch) | DateTime | To_transaction_date |
| شرح | String | Note |
| بانک مبداء | String | Source_bank_code |
| بانک مقصد | String | Destination_bank_code |
| لیستی از وضعیت پیمان‌ها (جدول Payman_statuses) | <List> | Payman_statuses |
| لیستی از وضعیت تراکنشها (جدول Transaction_statuses) | <List> | Transaction_statuses |
جدول نوع تراکنش (Transaction_type)
نکته: برای بانکهای ملت، ملی، کشاورزی، بلو تراکنش از نوع
PAYMAN_PAYMENT است.
| شرح | نام |
| انتقال وجه داخلی | NORMAL |
| انتقال وجه پایا | ACH |
| انتقال وجه ساتنا | RTGS |
| پرداخت قبض | BILL_PAYMENT |
| تراکنش بازگشت وجه | REVERSE |
| برداشت پیمان | PAYMAN_PAYMENT |
| تراکنش تسویه | PAYMAN_SETTLEMENT |
| تراکنش از اعتبار هدیه | BY_WALLET |
| تراکنش آنی با کارمزد | INSTATNT_WITHDRAWAL_WITH_COMISSION |
| تراکنش آنی | INSTANT_WITHDRAWAL |
جدول وضعیت پیمان‌ها (Payman_statuses)
| شرح | نام |
| در حال ایجاد | INITIALIZING |
| فعال | ACTIVE |
| غیرفعال | DEACTIVE |
| در انتظار تایید | WATING_FOR_CONFIRM |
| لغو شده | CANCELLED |
| منقضی شده | EXPIRED |
جدول وضعیت تراکنشها (Transaction_statuses)
| شرح | نام |
| در حال پردازش | IN_PROGRESS |
| ناموفق | FAILED |
| موفق | SUCCEED |
| برگشت خورده | REVERSED |
| پاسخی از بانک دریافت نشد | TIMEOUT |
پارامترهای خروجی
| شرح | نوع داده | نام |
| لیستی از تراکنشها (جدول Result) | Object | Result |
نتایج (جدول Result)
نمونه CURL درخواست | شرح | نوع داده | نام |
| ارز | String | Currency |
| بانک مقصد | String | Destination_bank_code |
| بانک مبدا | String | Source_bank_code |
| نوع تراکنش(جدول Transaction_type) | Enum | Transaction_type |
| شماره پیگیری تراکنش | String | Reference_id |
| شماره پیگیری موسسه | String | Trace_id |
| مبلغ تراکنش | Decimal | Transaction_amount |
| زمان تراکنش (Epoch) | DateTime | Transaction_time |
| کارمزد تراکنش | Decimal | Commision_amount |
| وضعیت تراکنش (جدول Status) | Enum | Status |
| شناسه قبض | String | Payman_id |
curl --location 'https://payman2.sandbox.faraboom.co/v1/payman/transactions/'
--header 'App-Key: demopayman' --header 'Content-Type: application/json'
--header 'Client-Ip-Address: 127.0.0.1' --header 'Client-Platform-Type: WEB'
--header 'Client-Device-Id: 127.0.0.1' --header 'Client-User-Id: 09352673656'
--header 'Client-User-Agent: firefox5.0Content-Type:application/json' --header
'Authorization: Bearer
HjS5tzmChsfngBZKEMpxl4KzFYfWfY6ABSKmI9pB1faSZPMWmRFfAh2BsHJXHJaBGPszpL3BQJGQSAXBAz5H3y3gI'
--header 'Cookie: cookiesession1=678A8C341A085F7AF93FECC7B44ACDFF' --data '{
"filter": { "transaction_type": "DIRECT_DEBIT", "from_transaction_amount":
"1", "to_transaction_amount": "20000" }, "length": "900", "offset": "0" }'
نمونه ورودی سرویس
نمونه خروجی سرویس
سرویس لیست پیمان‌ها (Payman’s List)
آدرس:
https://payman2.sandbox.faraboom.co/v1/payman/search
متد:(POST)
توضیحات
با استفاده از این سرویس و ارسال فیلتر می‌توان لیست پیمان‌های موسسه را مشاهده
کرد. پارامترهای Header درخواست
| شرح | نام |
| شناسه برنامه | App-key* |
| آدرس IP سرور برنامه | Device-Id* |
| شناسه سخت افزار کاربر | Client-Device-ID* |
| آدرس IP سیستم کاربر | Client-IP-Address* |
| مشخصات سخت افزار کاربر | Client-User-Agent* |
| شماره همراه کاربر | Client-User-ID* |
| نوع سیستم عامل کاربر(Windows,Android,IOS,Web) | Client-Platform-Type* |
| application/json | Content-Type* |
پارامترهای ستاره دار اجباری است. پارامترهای بدنه درخواست
| شرح | نوع داده | نام |
| اولین رکورد | Int | Offset* |
| تعداد رکورد بازگشتی | Int | Length* |
| مجموعه از فیلترها (جدول Filter) | Object | Filter* |
پارامترهای ستاره دار اجباری است. جدول فیلتر (Filter)
| شرح | نوع داده | نام |
| شناسه بانک | String | Bank_code |
| تاریخ انقضا از | DateTime | Expiration_date_from |
| تاریخ انقضا تا | DateTime | Expiration_date_to |
| حداکثر تراکنش روزانه از | Int | Max_daily_transactions_count_from |
| حداکثر تراکنش روزانه تا | Int | Max_daily_transactions_count_to |
| حداکثر تراکنش ماهانه از | Int | Max_monthly_transactions_count_from |
| حداکثر تراکنش ماهانه تا | Int | Max_monthly_transactions_count_to |
| تاریخ شروع از | DateTime | Start_date_from |
| تاریخ شروع تا | DateTime | Start_date_to |
| وضعیت پیمان (جدول Statuses) | <List> | Statuses |
| حداکثر مبلغ تراکنش از | Decimal | Transaction_max_amount_from |
| حداکثر مبلغ تراکنش تا | Decimal | Transaction_max_amount_to |
| شناسه پیمان | String | Payman_id |
| لیستی از شناسه‌های مشتری نزد موسسه | <List> | User_ids |
| لیست دسترسی‌های موسسه (جدول Permissions) | <List> | Permission_ids |
جدول وضعیت پیمان‌ها (Statuses)
| شرح | نام |
| در حال ایجاد | INITIALIZING |
| فعال | ACTIVE |
| غیرفعال | DEACTIVE |
| در انتظار تایید | WATING_FOR_CONFIRM |
| لغو شده | CANCELLED |
| منقضی شده | EXPIRED |
جدول دسترسی‌های موسسه (Permissions)
| شرح | نام |
| برداشت وجه | 1 |
| پرداخت قبض | 2 |
پارامترهای خروجی
| شرح | نوع داده | نام |
| لیستی از پیمان‌ها و مشخصات پیمان (جدول Results) | <List> | Results |
نتایج (جدول Results)
| شرح | نوع داده | نام |
| شناسه پیمان | String | Payman_id |
| شناسه بانک | String | Bank_code |
| شناسه مشتری نزد موسسه | String | User_id |
| وضعیت پیمان (جدول Statuses) | String | Status |
| نام موسسه | String | Creditor_title |
| شناسه پیگیری ایجاد پیمان | String | Trace_id |
| شناسه موسسه | String | Creditor_id |
| لیست دسترسی‌های موسسه | <List> | Permission_ids |
| تاریخ ثبت پیمان (Epoch) | DateTime | Registration_date |
| اطلاعات قرارداد (جدول Contract) | Object | Contract |
جدول Contract
| شرح | نوع داده | نام |
| تاریخ اتمام قرارداد | DateTime | expiration_date |
| تاریخ شروع قرارداد | DateTime | start_date |
| سقف تعداد تراکنش روزانه | int | max_daily_transaction_count |
| سقف تعداد تراکنش ماهانه | int | max_monthly_transaction_count |
| سقف مبلغ هر تراکنش | Decimal | max_transaction_amount |
| ارز | String | Currency |
جدول دسترسی‌های موسسه (Permissions)
| شرح | نام |
| برداشت وجه | 1 |
| پرداخت قبض | 2 |
نمونه CURL درخواست
curl --location 'https://payman2.sandbox.faraboom.co/v1/payman/search'
--header 'Authorization: Bearer
HjS5tzmChsfngBZKEMpxl4KzFYfWfY6ABSKmI9pB1faSZPMWmRFfAh2BsHJXHJaBGPszpL3BQJGQSAXBAz5H3y3gI'
--header 'Content-Type: application/json' --header 'app-key: demopayman'
--header 'Client-Ip-Address: 127.0.0.1' --header 'Client-Platform-Type: WEB'
--header 'Client-Device-Id: 127.0.0.1' --header 'Client-User-Id: 09352673656'
--header 'Client-User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
AppleWebKit/537.36 (KHTML, like Gecko) Chrome/66.0.3359.181 Safari/537.36'
--header 'Cookie: cookiesession1=678A8C341A085F7AF93FECC7B44ACDFF' --data '{
"filter": {}, "offset": 0, "length": 15 }'
نمونه ورودی سرویس
نمونه خروجی سرویس
سرویس گزارش تراکنشها در بازه زمانی خاص (Merchant Transactions)
آدرس:
https://payman2.sandbox.faraboom.co/v1/reports/transactions
متد:(POST)
توضیحات
این سرویس برای دریافت اطلاعات تراکنشها روی پیمان های مختلف در بازه‌های زمانی
متفاوت و بر روی بانکهای مختلف است. پارامترهای Header درخواست
| شرح | نام |
| شناسه برنامه | App-key* |
| آدرس IP سرور برنامه | Device-Id* |
| شناسه سخت افزار کاربر | Client-Device-ID* |
| آدرس IP سیستم کاربر | Client-IP-Address* |
| مشخصات سخت افزار کاربر | Client-User-Agent* |
| شماره همراه کاربر | Client-User-ID* |
| نوع سیستم عامل کاربر(Windows,Android,IOS,Web) | Client-Platform-Type* |
| application/json | Content-Type* |
پارامترهای ستاره دار اجباری است. پارامترهای بدنه درخواست
| شرح | نوع داده | نام |
| اولین رکورد | Int | Offset* |
| تعداد رکورد بازگشتی | Int | Length* |
| از تاریخ | DateTime | Start_date* |
| تا تاریخ | DateTime | End_date* |
| شناسه بانک | String | Bank_code* |
پارامترهای ستاره دار اجباری است. پارامترهای خروجی خروجی شامل لیستی از تراکنشها
است.
| شرح | نوع داده | نام |
| مبلغ کارمزد | Decimal | Commision_amount |
| ارز | String | Currency |
| شرح | String | Description |
| بانک مقصد | String | Destination_bank |
| شماره پیگیری تراکنش از بانک | String | Reference_id |
| بانک مبدا | String | Source_bank |
| وضعیت تراکنش (جدول Status) | Enum | Status |
| شماره پیگیری موسسه | String | Trace_id |
| مبلغ تراکنش | Decimal | Transaction_amount |
| شناسه پیمان | String | Payman_id |
| نوع تراکنش(جدول Transaction_type) | Enum | Transaction_type |
| تاریخ ثبت در سرور | DateTime | Server_date |
| تاریخ درخواست برداشت از سمت کلاینت | DateTime | Client_date |
جدول وضعیت تراکنشها (Status)
| شرح | نام |
| در حال پردازش | IN_PROGRESS |
| ناموفق | FAILED |
| موفق | SUCCEED |
| برگشت خورده | REVERSED |
| پاسخی از بانک دریافت نشد | TIMEOUT |
جدول نوع تراکنش (Transaction_type)
| شرح | نام |
| انتقال وجه داخلی | NORMAL |
| انتقال وجه پایا | ACH |
| انتقال وجه ساتنا | RTGS |
| پرداخت قبض | BILL_PAYMENT |
| تراکنش بازگشت وجه | REVERSE |
| برداشت پیمان | PAYMAN_PAYMENT |
| تراکنش تسویه | PAYMAN_SETTLEMENT |
| تراکنش از اعتبار هدیه | BY_WALLET |
| تراکنش آنی با کارمزد | INSTATNT_WITHDRAWAL_WITH_COMISSION |
| تراکنش آنی | INSTANT_WITHDRAWAL |
نکته: برای بانکهای ملت، ملی، کشاورزی، بلو تراکنش از نوع
PAYMAN_PAYMENT است.
نمونه CURL درخواست
curl --location 'https://payman2.sandbox.faraboom.co/v1/reports/transactions'
--header 'Authorization: Bearer
HjS5tzmChsfngBZKEMpxl4KzFYfWfY6ABSKmI9pB1faSZPMWmRFfAh2BsHJXHJaBGPszpL3BQJGQSAXBAz5H3y3gI'
--header 'Client-Device-Id: 192.168.1.1' --header 'Client-Ip-Address:
127.0.0.1' --header 'Client-Platform-Type: WEB' --header 'Client-User-Agent:
127.0.0.1' --header 'Client-User-Id: 123456789' --header 'Content-Type:
application/json' --header 'app-key: demopayman' --header 'Cookie:
cookiesession1=678A8C341A085F7AF93FECC7B44ACDFF' \ --data '{ "offset": 0,
"length": 20, "start_date": "2022-01-14T08:30:00.000Z", "end_date":
"2024-12-14T08:30:00.000Z", "bank_code": "SINAIR" }'
نمونه ورودی سرویس
نمونه خروجی سرویس
سرویس گزارش آماری تراکنش‌های موسسه (Merchant Transactions Report)
آدرس:
https://payman2.sandbox.faraboom.co/v1/reports/transactions/statistics
متد:(POST)
توضیحات
این سرویس برای دریافت آمار تعداد تراکنش های موسسه بر روی هر بانک است. پارامترهای
Header درخواست
پارامترهای ستاره دار اجباری است. پارامترهای بدنه درخواست
پارامترهای ستاره دار اجباری است. پارامترهای خروجی
نتایج (جدول Results)
جدول نوع تراکنش (Transaction_type)
نکته: برای بانکهای ملت، ملی، کشاورزی، بلو تراکنش از نوع
PAYMAN_PAYMENT است. نمونه CURL درخواست
| شرح | نام |
| شناسه برنامه | App-key* |
| آدرس IP سرور برنامه | Device-Id* |
| شناسه سخت افزار کاربر | Client-Device-ID* |
| آدرس IP سیستم کاربر | Client-IP-Address* |
| مشخصات سخت افزار کاربر | Client-User-Agent* |
| شماره همراه کاربر | Client-User-ID* |
| نوع سیستم عامل کاربر(Windows,Android,IOS,Web) | Client-Platform-Type* |
| application/json | Content-Type* |
| شرح | نوع داده | نام |
| از تاریخ | DateTime | Start_date* |
| تا تاریخ | DateTime | End_date* |
| شرح | نوع داده | نام |
| مجموع حجم تراکنش‌های موسسه | Decimal | Total_amount |
| مجموع تعداد تراکنش‌های موسسه | Int | Total_records |
| لیستی از آمار تراکنش‌های موسسه بر روی بانک خاص (جدول Results) | <List> | Results |
| شرح | نوع داده | نام |
| شناسه بانک | String | Bank_code |
| نوع تراکنش (جدول Transaction_type) | Enum | Transaction_type |
| مجموع حجم تراکنش | Decimal | Total_amount |
| مجموع تعداد تراکنش | Int | Total_count |
| شرح | نام |
| انتقال وجه داخلی | NORMAL |
| انتقال وجه پایا | ACH |
| انتقال وجه ساتنا | RTGS |
| پرداخت قبض | BILL_PAYMENT |
| تراکنش بازگشت وجه | REVERSE |
| برداشت پیمان | PAYMAN_PAYMENT |
| تراکنش تسویه | PAYMAN_SETTLEMENT |
| تراکنش از اعتبار هدیه | BY_WALLET |
| تراکنش آنی با کارمزد | INSTATNT_WITHDRAWAL_WITH_COMISSION |
| تراکنش آنی | INSTANT_WITHDRAWAL |
curl --location
'https://payman2.sandbox.faraboom.co/v1/reports/transactions/statistics'
--header 'Authorization: Bearer
HjS5tzmChsfngBZKEMpxl4KzFYfWfY6ABSKmI9pB1faSZPMWmRFfAh2BsHJXHJaBGPszpL3BQJGQSAXBAz5H3y3gI'
--header 'Client-Device-Id: 192.168.1.1' --header 'Client-Ip-Address:
127.0.0.1' --header 'Client-Platform-Type: WEB' --header 'Client-User-Agent:
127.0.0.1' --header 'Client-User-Id: 09122857387' --header 'Content-Type:
application/json' --header 'app-key: demopayman' --header 'Cookie:
cookiesession1=678A8C341A085F7AF93FECC7B44ACDFF' --data '{ "start_date":
"2022-09-13T00:00:00.000Z", "end_date": "2024-12-17T23:59:59.000Z" }'
نمونه ورودی سرویس
نمونه خروجی سرویس
