خانه درگاه پرداخت مستندات API راهنمای استفاده افزونه‌ها

# احراز هویت

احراز هویت در پنل زرین‌پال، تحت پرتکل oAuth 2.0 (opens new window) و استاندارد REST انجام می‌شود. قبل از شروع روند احراز هویت، باید مشخصات کلاینت خودتان از جمله client_id و client_secret را از پشتیبانی زرین‌پال دریافت کنید.

# ثبت نام (register)

برای شروع روند ثبت نام ، ابتدا باید یک درخواست POST با فرمت application/json به آدرس زیر ارسال کنید:

 https://next.zarinpal.com/api/oauth/register

لیست پارامترهای قابل‌پذیرش توسط این مقصد عبارت‌اند از:

نام نوع قابل‌قبول الزامی است؟ توضیحات
first_name string بله نام
last_name string بله نام خانوادگی
cell_number Integer بله شماره تلفن همراه

مقالی برای عضویت :

$ curl 'https://next.zarinpal.com/api/oauth/register' \
  -H 'Content-Type: application/json' \
  --data-binary '{"first_name": "علیرضا","last_name": "یوسفی","cell_number":"0912356789"}'

# پاسخ

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

{
    "user_id": 945298
}

در صورتی که کاربر قبلا ثبت نام شده باشد خطای موجود بودن آن دریافت می شود

# شروع کار (Initialization)

# درخواست

برای شروع روند احراز هویت، ابتدا باید یک درخواست POST با فرمت application/json به آدرس زیر ارسال کنید:

https://next.zarinpal.com/api/oauth/initialize

لیست پارامترهای قابل‌پذیرش توسط این مقصد عبارت‌اند از:

نام نوع قابل‌قبول الزامی است؟ مقدار پیش‌فرض توضیحات
username string بله آدرس ایمیل یا شماره‌ی همراه کاربر
channel string('ussd', 'sms') خیر 'ussd' کانال دریافت رمز یک‌بار مصرف کاربر

برای مثال، ما می‌خواهیم کاربری با شماره‌ی موبایل 09123456789 را با استفاده از کد USSD احراز هویت کنیم:

$ curl 'https://next.zarinpal.com/api/oauth/initialize' \
  -H 'Content-Type: application/json' \
  --data-binary '{"username":"0912356789","channel":"ussd"}'

curl -X POST \
  https://next.zarinpal.com/api/oauth/initialize \
  -H 'content-type: application/json' \
  -d '{"username":"09375115259","channel":"sms"}'

# پاسخ

در پاسخ به این درخواست، پاسخی به این شکل ارسال می‌شود:

{
  "avatar": "https:\/\/gravatar.com\/avatar\/{EMAIL_HASH}",
  "channel": "ussd",
  "ussd_code": "*733*4*97*2#",
  "waiting_time": 120,
  "otp_time_diff": 900
}

لیست پاسخ‌های ارسال‌شده به این صورت هستند:

نام نوع الزامی است؟ توضیحات
avatar string بله URL آواتار کاربر (معمولاً به Gravatar اشاره می‌کند)
channel string('ussd', 'sms') بله کانالی که از طریق آن رمز یک‌بار مصرف در اختیار کاربر قرار می‌گیرد
ussd_code string خیر شماره‌ی USSD که کاربر باید با شماره‌گیری آن، رمزش را دریافت کند؛ مقدار این کلید، در صورتی که channel برابر sms باشد، یک رشته‌ی خالی خواهد بود
waiting_time int بله زمان به ثانیه قبل از این که کاربر بتواند دوباره درخواستی برای ارسال رمز یک‌بار مصرف بدهد
otp_time_diff int بله @todo

# تأیید رمز (Verification)

پس از این‌ که کاربر رمز یک‌بار مصرفش را وارد کرد، صحت و اعتبار رمز می‌بایستی تأیید شود. بعد از تأیید موفقیت‌آمیز رمز، یک Access Token و یک Refresh Token برای استفاده از امکانات API در پاسخ ارسال می‌شود.

# درخواست

مشابه مرحله‌ی قبل، یک درخواست POST با فرمت application/json به آدرس زیر ارسال کنید:

https://next.zarinpal.com/api/oauth/token

لیست پارامترهای قابل‌پذیرش توسط این مقصد برای دریافت توکن (بدون Refresh Token) عبارت‌اند از:

نام نوع قابل‌قبول الزامی است؟ مقدار پیش‌فرض توضیحات
grant_type string بله 'password' نوع ورودی کاربر، در این مرحله باید برابر با 'password' باشد
client_id int بله آی‌دی کلاینت شما که از زرین‌پال دریافت کرده‌اید
client_secret string بله کلید کلاینت شما که از زرین‌پال دریافت کرده‌اید
username string بله آدرس ایمیل یا شماره‌ی موبایل کاربر
password string بله رمز یک‌بار مصرف که کاربر وارد کرده است
scope string بله '*' @todo

برای مثال، در ادامه‌ی مثال قبل، کاربری با شماره‌ی موبایل 09123456789، رمزِ 12345678 را وارد کرده است:

$ curl 'https://next.zarinpal.com/api/oauth/token' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "grant_type": "password",
    "client_id": 100,
    "client_secret": "$ecreT",
    "username": "0912356789",
    "password": "12345678",
    "scope": "*"
  }'

# پاسخ

پاسخ این در درخواست (در صورت صحیح‌بودن داده‌ی ارسالی، بخش خطاها را ببینید) به صورت زیر خواهد بود:

{
  "token_type": "Bearer",
  "expires_in": 1296000,
  "access_token": "{ACCESS_TOKEN}",
  "refresh_token": "{REFRESH_TOKEN}"
}

لیست جزئیات پاسخ‌های ارسال‌شده به این صورت هستند:

نام نوع الزامی است؟ توضیحات
token_type string بله نوع توکن ارسالی رو مشخص می‌کند؛ نوع توکن‌های زرین‌پال Bearer هستند
expires_in int بله طول عمر توکن را به ثانیه مشخص می‌کند
access_token string بله Access Token برای کارکردن با امکانات سرور GraphQL؛ این توکن با استاندارد JWT (opens new window) ایجاد می‌شود
refresh_token string بله ‍Refresh Token برای دریافت توکن جدید بعد از منقضی‌شدن توکن قبلی؛ بخش Refresh Token را ببینید

# Refresh Token

بعد از این که Access Token دریافتی پس از مدتی که در فیلد expires_in مشخص شده منقضی شد، لازم است که با استفاده از refresh_token داده‌شده در مرحله‌ی قبل، یک Access Token جدید دریافت کنید.

# درخواست

برای دریافت توکن جدید، مشابه مرحله‌ی قبلی، یک درخواست POST با فرمت application/json به آدرس زیر ارسال کنید:

https://next.zarinpal.com/api/oauth/token

لیست پارامترهای قابل‌پذیرش به منظور دریافت توکن جدید با Refresh Token برای این مقصد به این صورت است:

نام نوع قابل‌قبول الزامی است؟ مقدار پیش‌فرض توضیحات
grant_type string بله 'refresh_token' نوع ورودی کاربر، در این مرحله باید برابر با 'refresh_token' باشد
client_id int بله آی‌دی کلاینت شما که از زرین‌پال دریافت کرده‌اید
client_secret string بله کلید کلاینت شما که از زرین‌پال دریافت کرده‌اید
refresh_token string بله مقدار Refresh Token که از مرحله‌ی قبل دریافت کردید
scope string بله '' @todo

# پاسخ

جزئیات و انواع فیلدهای دریافتی در پاسخ، دقیقاً مانند مرحله‌ی قبل هستند.

# خطاها

در صورتی که در هر یک از مراحل بالا، خطایی رخ دهد یا داده‌ی ارسال‌شده در درخواست، نامعتبر باشند؛ فیلد errors در پاسخ دریافتی حاوی یک آرایه خواهد بود که خطاهای درخواست در آن مشخص می‌شوند و فیلد data نیز مقدار null خواهد داشت.

در این صفحه