منو

مقدمه

نحوه استفاده از وب سرویس ها

تمامی سرویس‌های معرفی شده در این سند بر پایه پروتکل ارتباطی REST طراحی شده است و آدرس پایه همه سرویس‌ها به صورت زیر خواهد بود:

محیط تستی (Staging) : https://uat.mydigipay.info/digipay/api

محیط عملیاتی (Live) : https://api.mydigipay.com/digipay/api

سرویس لاگین

مستند پیش رو درباره نحوه استفاده از سرویس احراز هویت دیجی‌پی است. این سرویس بر پایه پروتکل استاندارد OAuth2 بنا نهاده شده و خروجی آن شامل دو مقدار access_token و refresh_token می‌باشد. برای استفاده از هر سرویسی در دیجی‌پی همیشه لازم است مقدار access_token در هدر درخواست ارسال شود تا هویت استفاده کننده سرویس برای سیستم مشخص شده و دسترسی‌های او به بخش‌های مختلف سیستم کنترل شود. مقدار access_token برای مدت زمان مشخصی معتبر است. برای تمدید این توکن میتوان از دیتای refresh_token استفاده کرد که جزییات پیاده سازی و نحوه فراخوانی وب سرویس آن در ادامه توضیح داده می‌شود.

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

در ادامه این مستند ابتدا توضیح داده می شود که چگونه می توانید با مشخصات کاربری خود لاگین کرده و توکن دریافت کنید، سپس یک مورد استفاده از توکن مثال زده می شود و در انتها سرویس رفرش توکن مورد بررسی قرار می‌گیرد.

بدنه درخواست

نمونه cURL درخواست برای این سرویس به صورت زیر است:

curl --location --request POST 'https://uat.mydigipay.info/digipay/api/oauth/token' \
--header 'Authorization: Basic aXV5cml3eTg4OmpoczY1ZGZn' \
--form 'username=sampleUsername' \
--form 'password=samplePassword' \
--form 'grant_type=password'

آدرس : ‍‍/oauth/token (POST)

بدنه این رکویست http باید به صورت form-data ارسال شود و فیلد‌های آن به شرح زیر است :

نام پارامتر مثال توضیح نوع
username sampleUserName نام کاربری string
password samplePassword رمز عبور string
grantType password شیوه احراز هویت string

در این سرویس علاوه بر مقادیری که در Body ریکویست فرستاده می‌شود، فیلدی با عنوان Authorization در Header ریکویست قرار میگیرد که مقدار آن بر اساس client_id و client_secret ای که در اختیارتان قرار داده میشود به دست می آید. برای ساخت این فیلد ابتدا مقادیر client_id و client_secret را به صورت زیر با یک “:” به یکدیگر متصل کنید:

client_id:client_secret

برای مثال اگر کلاینت آی دی برابر iuyriwy88 و کلاینت سکرت برابر jhs65dfg باشد، محتوای ترکیب شده برابر iuyriwy88:jhs65dfg خواهد بود. پس از ترکیب این دو فیلد با کاراکتر دونقطه، کل این رشته باید به صورت base64، encode شود.

محتوای encode شده برای مثال بالا برابر aXV5cml3eTg4OmpoczY1ZGZn خواهد بود. در نهایت فیلد Authorization در هدر برابر با مقدار زیر خواهد شد:

Basic aXV5cml3eTg4OmpoczY1ZGZn

پاسخ

نمونه ای از پاسخ این سرویس در قالب JSON به صورت زیر است:

{
    "access_token": "lIjoiMTY4MDhlNGYtMDc4ZC00MDQ0LTgxNmQtNzQ3NTYw",
    "token_type": "bearer",
    "refresh_token": "YtMDc4ZC00MDQ0LTgxNmQtNzQ3NTYwOTU0Y2M3IiwiYX",
    "expires_in": 3599,
    "scope": "USER",
    "jti": "441c434f-076a-48a4-b816-fc9060817aa2"
}

درصورتی که اطلاعات ارسالی صحیح باشد کد http ریسپانس این سرویس برابر 200 و در صورتی که اطلاعات نامعتبر باشد برابر 401 خواهد بود. ریسپانس موفق این سرویس شامل فیلد های زیر است :

نام پارامتر مثال توضیح نوع
access_token eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXV توکن اصلی string
refresh_token G9yaXRpZXMiOiItMTAxLDAsLTEsLTI1MS رفرش توکن string
token_type bearer نوع توکن string
expires_in 3599 زمان منقضی شدن توکن اصلی به ثانیه int
scope USER جهت استفاده داخلی دیجی‌پی string
sti 441c434f-076a-48a4-b816-fc9060817aa2 جهت استفاده داخلی دیجی‌پی string

فیلد expires_in نشان میدهد که توکن اصلی تا چه مدت زمانی معتبر است. در صورتی که این زمان به صورت کامل سپری شود، توکن اصلی منقضی میشود و باید با استفاده از محتوای رفرش توکن داده شده اقدام به گرفتن توکن جدید نمود. (جزییات این سرویس در ادامه توضیح داده شده است)

درصورتی که توکن منقضی شده باشد و یا معتبر نباشد، کد خطای http فراخوانی وب سرویس با این توکن برابر 401 خواهد شد.

سرویس رفرش توکن

نمونه cURL درخواست برای این سرویس به صورت زیر است :

curl --location --request POST 'https://uat.mydigipay.info/digipay/api/oauth/token' \
--header 'Authorization: Basic aXV5cml3eTg4OmpoczY1ZGZn' \
--form 'grant_type=refresh_token' \
--form 'refresh_token=YtMDc4ZC00MDQ0LTgxNmQtNzQ3NTYwOTU0Y2M3IiwiYX'

پس از سپری شدن زمان expires_in نیاز است تا با فراخوانی این سرویس توکن جدیدی دریافت شود. آدرس فراخوانی، فرمت بدنه ریکویست و پارامتر های موجود در هدر ریکویست برابر با همان موارد ذکر شده در سرویس قبلی می باشد. اما فیلدهای ارسالی در بدنه http این سرویس متفاوت است و جزییات آن به شرح زیر است :

نام پارامتر مثال توضیح نوع
grantType refresh_token شیوه احراز هویت string
refresh_token G9yaXRpZXMiOiItMTAxLDAsLTEsLTI1MS رفرش توکن int

جواب این سرویس کاملا مطابق جدول بالا می باشد و از داخل این پاسخ میتوان refresh_token جدید را با access_token قبلی جایگزین نمود. در صورتی که این سرویس با مقدار رفرش توکن داده شده خطای 401 را برگرداند، باید سرویس لاگین فراخوانی و استفاده شود. چرا که خود رفرش توکن نیز پس از مدت زمانی نسبتا طولانی منقضی خواهد شد.

درگاه پرداخت

در این مستند فرآیند خرید با گرفتن تیکت آغاز میشود. در فراخوانی سرویس تیکت، مشخصات کاربر و اطلاعات پرداختی ارسال میشود و یک آدرس پرداخت اینترنتی در پاسخ این سرویس داده میشود. پس از آن کاربر به صفحه ای هدایت میشود که میتواند از بین گزینه های مختلف پرداختی نظیر پرداخت با IPG، پرداخت با کیف پول و یا پرداخت با درگاه خرید اقساطی، یکی را انتخاب کند و پروسه خرید خود را انجام دهد.

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

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

سرویس دریافت تیکت خرید

نمونه cURL درخواست برای این سرویس به صورت زیر است :

curl --location --request POST 'https://uat.mydigipay.info/digipay/api/businesses/ticket?type=11' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 7bd1a8db-6d6f-4ce9-958a-2e1a81d0053d' \
--data-raw '{
    "amount": 150000,
    "cellNumber":"09121234567",
    "providerId": "Jjhhd585ff",
    "redirectUrl": "http://www.example.com/payresult",
    "userType":0
}'

آدرس : /businesses/ticket?type=11 (POST)

بدنه این رکویست http باید بر اساس فرمت json ارسال شود و مقادیر فیلد های آن به صورت زیر است :

نام پارامتر مثال توضیح نوع
amount* 150000 مبلغ تراکنش long
cellNumber 09121234567 .برابر عدد 0 باشد اجباری است userType شماره همراه کاربر- این فیلد در حالتی که فیلد string
providerId* Jjhhd585ff شناسه یکتای تراکنش – این شناسه باید توسط مصرف کننده سرویس تولید شود و برای هر تراکنش متفاوت باشد. string
redirectUrl* http://www.example.com/payresult آدرس بازگشت به سایت – نتیجه پرداخت به این آدرس برگشت داده خواهد شد. string
userType* 0 نوع کاربر int

درصورتی که شماره تلفن همراه وارد نشود، تنها گزینه خرید با IPG برای کاربر نمایش داده خواهد شد و دیگر درگاه های پرداختی پشتیبانی نخواهد شد.

عنوان مقدار توضیحات
identified 0 برای کاربرانی که شماره همراه آنها در سیستم مشخص است، این مقدار باید انتخاب شود و فیلد شماره تلفن برای آنها پر شود.
refresh_token 2 کاربر مهمان بدون شماره تلفن همراه

نمونه ای از پاسخ سرویس تیکت در قالب json به صورت زیر است :

{
    "result": {
        "status": 0,
        "message": "Success",
        "level": "INFO"
    },
    "payUrl": "https://uatweb.mydigipay.info/web-pay/upg/9ec4ffd981544e0f98b58b808ef9f5f1",
    "ticket": "9ec4ffd981544e0f98b58b808ef9f5f1"
}

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

نام پارامتر مثال توضیح نوع
result - نتیجه فراخوانی (جدول بعدی) object
payUrl https://uatweb.mydigipay.info/web-pay/upg/9ec4ffd981544e0f98b58b808ef9f5f1 آدرس پرداختی که کاربر باید به آن هدایت شود string
ticket 9ec4ffd981544e0f98b58b808ef9f5f1 تیکت خرید string

جدول مقادیر فیلد result:

نام پارامتر مثال توضیح نوع
Level BLOCKER داخلی دیجی‌پی string
Message عملیات با موفقیت انجام شد توضیح فارسی نتیجه string
Status 0 کد یکتای نتیجه (شرح در جدول مربوطه) string
Title Success عنوان نتیجه string

در صورت موفق بودن پاسخ، کاربر باید به آدرس payUrl هدایت شود. در این آدرس کاربر میتواند یکی از درگاه های مورد نظر را انتخاب نماید و پرداخت خود را انجام دهد. لازم به ذکر است فیلد providerId که در اطلاعات ریکویست این سرویس آمده است از سمت درخواست دهنده باید ذخیره شود تا هنگام برگشت نتیجه پرداخت، تراکنش قابل رهگیری باشد.

برگشت نتیجه پرداخت

پس از مدتی که کاربر پرداخت خود را انجام داد، نتیجه پرداخت در قالب application/x-www-form-urlencoded به آدرس redirectUrl ارسال میشود (آدرسی که در فراخوانی سرویس تیکت داده شده است).

پارامتر های این پاسخ به شرح زیر است :

نام پارامتر مثال توضیح نوع
result SUCCESS نتیجه پرداخت(جدول بعدی) string
providerId Jjhhd585ff شناسه یکتای تراکنش string
trackingCode 15547930631614167567972 کدرهگیری string
amount 150000 مبلغ تراکنش long
مقدار توضیحات
SUCCESS ‌ تراکنش موفق
FAILURE ‌ خطا در انجام تراکنش
IPG_FAILURE ‌ خطا در انجام تراکنش آی پی جی
CANCELED ‌ پرداخت لغو شده
INTERNAL_ERROR ‌خطای سیستمی
INVALID_TICKET ‌ تیکت نامعتبر / پرداخت در وضعیت نامعتبر

نمونه ای از دیتای نتیجه پرداخت به صورت زیر میباشد :

result=SUCCESS&providerId=Jjhhd585ff&trackingCode=15547930631614167567972&amount=150000

سرویس تایید تراکنش خرید

این سرویس فاقد بدنه http می باشد و نمونه curl آن به این صورت است :

curl --location --request POST 'https://uat.mydigipay.info/digipay/api/purchases/verify/15547930631614167567972' \
--header 'Authorization: Bearer  7bd1a8db-6d6f-4ce9-958a-2e1a81d0053d' \
--data-raw ''

آدرس: /purchases/verify/{trackingCode} (POST)

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

در آدرس این سرویس فیلد trackingCode ای وجود دارد که در واقع برابر با همان کد رهگیری در پاسخ نتیجه پرداخت است.

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

{
    "result": {
        "status": 0,
        "message": "Success",
        "level": "INFO"
    },
    "trackingCode": "15547930631614167567972",
    "providerId": "Jjhhd585ff",
    "terminalId": "44579180",
    "rrn": "724101640673",
    "maskedPan": "502229******7467",
    "pspCode": "002",
    "pspName": "PARSIAN",
    "amount": 15000,
    "paymentGateway": 0
}

در نهایت تایید تراکنش در قالب json و با پارامتر های زیر پاسخ داده میشود :

نام پارامتر مثال توضیح نوع
result - نتیجه فراخوانی object
providerId Jjhhd585ff شناسه یکتای تراکنش string
trackingCode 15547930631614167567972 کدرهگیری string
amount 150000 مبلغ تراکنش long
paymentGateway 0 نوع درگاه پرداخت (جدول مربوطه) int
rrn 5489895121 شماره ارجاع بانکی string
maskedPan 502229******2158 شماره کارت پرداختی ( در صورت پرداخت با کارت ) string
pspName PARSIAN نام پی‌اس‌پی انتخاب شده (جدول مربوطه) – در صورت پرداخت با درگاه بانکی string
pspCode 002 کد psp انتخاب شده (جدول مربوطه) – در صورت پرداخت با درگاه بانکی string
terminalId 44752156 شناسه ترمینال – در صورت پرداخت با درگاه بانکی string

لیست انواع درگاه‌های پرداخت

لیست انواع درگاه‌های پرداخت به شرح زیر هستند: عنوان | شماره | توضیح ----- | ----- | ----- IPG | 0 | درگاه اینترنتی DPG | 1 |درگاه چهارپارامتری WALLET | 3 | درگاه کیف پول CPG | 4 | درگاه خرید اعتباری

همچنین لیست زیر انواع PSP‌های پشتبیانی‌شده در درگاه پرداخت هوشمند دیجی‌پی را شرح می‌دهد:

عنوان شماره توضیح
SAMAN 001 سامان کیش
PARSIAN 002 تجارت الکترونیک پارسیان
MELLAT 003 به پرداخت ملت
ENOVIN 004 پرداخت نوین آرین
PASARGAD 005 پرداخت الکترونیک پاسارگاد
FANAVA 006 فن آوا
MELLI 007 سداد
IRKISH 008 ایران کیش
POD 009 پاد

لیست کد‌های نتیجه

کد‌های خطایی که ممکن است در خروجی سرویس‌های این مجموعه دریافت کنید، آورده شده‌ است. منظور از کد نتیجه در جدول زیر، همان مقدار فیلد status در آبجکت result می‌باشد.

کد نتیجه توضیحات
0 ‌ عملیات با موفقیت انجام شد
1054 ‌ اطلاعات ورودی اشتباه می باشد
9000 ‌ اطلاعات خرید یافت نشد
9001 توکن پرداخت معتبر نمی باشد
9003 ‌ خرید مورد نظر منقضی شده است
9004 ‌ خرید مورد نظر درحال انجام است
9005 خرید قابل پرداخت نمی باشد
9006 ‌ خطا در برقراری ارتباط با درگاه پرداخت
9007 خرید با موفقیت انجام نشده است
9008 ‌ این خرید با داده های متفاوتی قبلا ثبت شده است
9009 ‌ محدوده زمانی تایید تراکنش گذشته است
9010 ‌ تایید خرید ناموفق بود
9011 ‌ نتیجه تایید خرید نامشخص است
9012 وضعیت خرید برای این درخواست صحیح نمی باشد
9030 ‌ ورود شماره همراه برای کاربران ثبت نام شده الزامی است
9031 ‌ اعطای تیکت برای کاربر مورد نظر امکان پذیر نمی‌باشد