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

در صورتی که سرویس شما نیاز دارد از کاربران پی‌پینگ دسترسی بگیرد تا از API های پرداخت، فاکتور و ... از جانب آنها استفاده نماید، نیاز دارید تا پس از معرفی و ساخت یک توکن oAuth2.0، مراحل زیر را برای دریافت دسترسی از کاربر برای دریافت توکن طی کنید.

دریافت client-id و client-secret

ابتدا به بخش توکن در پنل شخصیتان بروید و از منوی بغل بخش oAuth2.0 را انتخاب کنید. برای دریافت توکن فرم را تکمیل کنید (به راهنمای هر فیلد توجه کنید) و client-id و client-secret اپلیکیشن‌تان را دریافت کنید.

دریافت دسترسی OAuth2

در پی‌پینگ از AuthorizationCode with PKCE به عنوان oAuth flow اصلی احراز هویت استفاده می شود. برای دریافت توکن به این روش مراحل زیر بترتیب انجام می شود :

ساخت Code Verifier

ابتدا شما نیاز به تولید و ذخیره یک Code Verifier دارید. برای این منظور می‌توانید از قطعه کد زیر استفاده کنید (حداقل ۳۲ کاراکتر و حداکثر ۶۴):

function base64URLEncode(str) {
return str.toString('base64')
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=/g, '');
}
var verifier = base64URLEncode(crypto.randomBytes(32));


CodeVerifier را برای استفاده در مراحل بعدی باید برای هر کاربر ذخیره کنید

ساخت Code Challenge

در این مرحله با استفاده از Code Verifier که در مرحله قبل ساخته شده، یک Code Challenge ساخته که از آن به عنوان پارامتر ارسالی در درخواست احراز هویت استفاده می‌شود.

function sha256(buffer) {
return crypto.createHash('sha256').update(buffer).digest();
}
var challenge = base64URLEncode(sha256(verifier));


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

دریافت Authorization Code

در قدم اول برای شروع روند دریافت Authorization code، باید کاربر را روی مرورگر به این آدرس هدایت کنید

https://oauth.payping.ir/connect/authorize?
scope=SCOPES&
response_type=code&
client_id=YOUR_CLIENT_ID&
code_challenge=CODE_CHALLENGE&
code_challenge_method=S256&
redirect_uri=https://YOUR_CALLBACK_URL&
state=YOUR_CUTOM_VALUE


توضیح مقادیر ارسالی

scope : حوزه‌های دسترسی که شما برای احراز هویت به آن نیاز دارید. شما در درخواست خود می‌توانید از حوزه‌های توضیح داده شده در بخش بعدی بنا به نیاز خود ارسال کنید. برای ارسال چند scope از فاصله بعنوان جدا کننده استفاده می شود.
response_type : این مقدار نمایش‌دهنده نوع پاسخگویی به درخواست شما می‌باشد. در اینجا بنا به درخواست شما همیشه باید مقدار code بگیرد.
client_id : مقدار کلاینت‌آیدی اپلیکیشن شما می‌باشد. برای پیدا کردن این مقدار به کنسول توسعه‌دهندگان مراجعه کنید.
redirect_uri : آدرسی که پس از احراز هویت، مرورگر کاربر به آن هدایت می‌شود. مقدار Authorization code در Url داخل پارامتر code موجود می‌باشد. همینطور باید در نظر داشته باشید که این آدرس باید در کنسول توسعه‌دهندگان هنگام ثبت این اپلیکیشن مشخص شده باشد.
code_challenge : مقداری که در گام قبلی از Code Verifier بدست آمده.
code_challenge_method : متدی که با آن challenge ساخته می‌شود که در اینجا باید از S256 استفاده کنید.
state : پارامتر دلخواه که در صورت پر شدن همین مقدار در صفحه callback با querystring به نام state به شما بازگشت دادمی‌شود. بطور مثال می‌توانید این مقدار را با نام کاربری کاربر در سرویس خود پر کنید تا هنگام بازگشت به سایت شما بتوانید تشخیص دهید توکن دریافتی برای کدام کاربر شماست.

مقدار redirect_uri باید همیشه به شکل Decode شده باشد

scope ها

openid - اجباری برای تمام درخواست‌ها
profile - دسترسی مرتبط با تمام اطلاعات یک کاربر
email - دسترسی به مشاهده ایمیل
nationalcode - دسترسی به مشاهده کدملی کاربر
birthday - دسترسی به مشاهده تاریخ تولد کاربر
shaba - دسترسی به مشاهده شبای بانکی کاربر
phone - دسترسی به مشاهده شماره تماس کاربر
pay:read - دسترسی فقط خواندنی در سرویس پرداخت
pay:write - دسترسی نوشتن و تغییرات در سرویس پرداخت
product:read - دسترسی فقط خواندنی در سرویس آیتم‌های مالی
product:write - دسترسی نوشتن و تغییرات در سرویس آیتم‌های مالی
invoice:read - دسترسی فقط خواندنی به سرویس فاکتور ها
invoice:write - دسترسی نوشتن و تغییرات در سرویس فاکتور ها
upload:write - دسترسی مرتبط با سرویس بارگذاری فایل‌ها

دریافت اجازه دسترسی از کاربر:

پس از اینکه کاربر لاگین می کند به کاربر سطح دسترسی هایی که لازم دارد نمایش داده می شود و پس از تایید به آدرسی که شما بعنوان returnUrl داده اید بهمراه code هدایت می شود.



دریافت Access Token

در این مرحله می‌بایست با استفاده از code که در مرحله قبل دریافت کردید، درخواست جدیدی برای دریافت Access token ارسال کنید. شما با این Access token می‌توانید از وب‌سرویس‌های مختلف پی‌پینگ استفاده کنید.

به آدرس زیر یک درخواست POST از نوع form-data با پارامترهای نمایش داده‌شده زده می شود:

curl --request POST \
--url 'https://oauth.payping.ir/connect/token' \
--data ' \
{ \
"grant_type":"authorization_code", \
"client_id": "YOUR_CLIENT_ID", \
"client_secret" : "YOUR_CLIENT_SECRET", \
"code_verifier": "YOUR_GENERATED_CODE_VERIFIER", \
"code": "YOUR_AUTHORIZATION_CODE", \
"redirect_uri": "YOUR_REDIRECT_URL", \
}'


پارامترهای ارسالی:

grant_type : این مقدار باید برابر با authorization_code باشد.
client_id : مقدار Client Id اپلیکیشن شما که در کنسول توسعه‌دهندگان دریافت کردید.
client_secret : مقدار Client secret اپلیکیشن ما که از کنسول توسعه‌دهندگان دریافت کرده‌اید.
code : مقدار Authorization code که در گام قبلی دریافت کردید.
code_verifier : مقدار Code Verifier که در گام اول ساخته و ذخیره کرده‌اید.
redirect_uri : مقدار آدرس بازگشتی که در گام اول برای دریافت Authorization code ارسال کرده‌اید.

در پاسخ یک json با فرمت زیر دریافت میکنید:

{
"access_token": "USER_ACCESS_TOKEN",
"expires_in": 3600,
"token_type": "Bearer"
}


در نهایت برای ارسال تمامی درخواست‌های خود به سمت وب‌سرویس‌های پی‌پینگ و احراز هویت آنها با دسترسی‌های خواسته شده می‌بایست در Header خود مقدار Authorization را به صورت زیر ارسال نمایید:

--header 'authorization : bearer {ACCESS_TOKEN}'

نمونه کد برای زبان‌های مختلف

برای مشاهده نمونه کد این فرآیند می‌توانید به این مخزن بر روی گیت‌هاب مراجعه کنید.

دریافت اطلاعات کاربر

برای دسترسی به اطلاعات کاربر نیاز است شما در بخش سطح دسترسی scope ها ، موارد مورد نیازتان را از کاربر دسترسی بگیرید. scope های profile email nationalcode birthday shaba phone دسترسی هایی است که شما می‌توانید از کاربر دریافت کنید. برای دریافت اطلاعات کاربر باید از متد زیر استفاده کنید :

curl -X GET \
\https://oauth.payping.ir/connect/userinfo \
-H 'Authorization: Bearer ACCESS_TOKEN' \


که پاسخ آن بسته به اینکه چه scope هایی دسترسی دارند بصورت زیر بصورت زیر می‌باشد :

{
"username": "USERNAME",
"firstname": "نام",
"lastname": "نام خانوادگی",
"profilepicture": "profile pic url",
"email": "email@example.com",
"email_verified": true,
"phone": "0912....",
"phone_verified: true,
"shaba": "IR000...",
"shaba_verified: true,
"nationalcode": "0920....",
"nationalcode_verified: true,
"birthday": "1367/01/01",
"birthday_verified": true
}


دکمه ورود با پی‌پینگ

برای استفاده از الگوی دکمه ورود با پی‌پینگ می‌توانید فایل css زیر را در صفحه وارد کنید و از نمونه HTML آن برای نمایش دکمه استفاده کنید

<link rel="stylesheet" href="https://cdn.payping.ir/statics/paypingLogin.css">

<div class="PayPingLoginDark">
<span class="PayPingText">ورود با پِی‌پینگ</span>
<span class="PayPingIcon"></span>
</div>


با دادن کلاس های PayPingLoginDark و یا PayPingLoginLight می‌توانید تم‌های تیره و روشن را برای سایت خودتان استفاده کنید.



مستندات API ها

برای مشاهده تمامی مستندات API ‌های پی‌پینگ به docs.payping.ir مراجعه کنید
این مقاله مفید بود؟
لغو
خیلی ممنون!