مقدمه
این راهنما نحوه اتصال برنامه نویسان به درگاه های پرداخت از طریق API آیدی پی را توضیح میدهد.
API آیدی پی به روش REST سازماندهی شده است. همچنین بدنه درخواست ها و پاسخ ها با فرمت JSON میباشد.
شما میتوانید نمونه کدها را در ستون سمت چپ صفحه مشاهده کنید و درصورت تمایل میتوانید از طریق تب های بالای صفحه، نمونه کدهای زبان های برنامه نویسی مختلف را انتخاب کنید.
احراز هویت
برای استفاده از API های آیدی پی نیاز به یک API KEY است. شما میتوانید به داشبورد خود در آیدی پی رفته و در بخش وب سرویسهای من، یک وب سرویس جدید ایجاد کنید.
بعد از ایجاد وب سرویس، API KEY خود را دریافت میکنید و میتوانید برای فراخوانی API از آن استفاده کنید.
برای ارسال تمام درخواست ها باید API KEY را مانند مثال زیر در header ارسال نمایید:
X-API-KEY: 6a7f99eb-7c20-4412-a972-6dfb7cd253a4
پارامتر | نوع | ضروری | توضیحات |
---|---|---|---|
X-API-KEY | string | بله | کلید منحصر بفرد جهت احراز هویت به طول 36 کاراکتر |
آزمایشگاه
برای تست API و نحوه کارکرد آن میتوانید در header درخواست های خود کلید X-SANDBOX
را ارسال کنید.
در صورتیکه مقدار این پارامتر true
باشد، تمام فرایندهای بعدی بصورت آزمایشی ایجاد و شبیه سازی میشوند.
همچنین در این حالت حساسیت IP در درخواست های ارسال شده اعمال نمیشود، و میتوان درخواست ها را از هر IPی اجرا کرد.
مقدار پیش فرض این پارامتر false
است.
X-SANDBOX: true
پارامتر | نوع | ضروری |
---|---|---|
X-SANDBOX | boolean | خیر |
تراکنش
ایجاد تراکنش
با استفاده از آدرس زیر میتوانید یک تراکنش جدید ایجاد کنید.
curl -X POST https://api.idpay.ir/v1/payment \
-H 'Content-Type: application/json' \
-H 'X-API-KEY: 6a7f99eb-7c20-4412-a972-6dfb7cd253a4' \
-H 'X-SANDBOX: true' \
-d '{
"order_id": 101,
"amount": 10000,
"phone": "09382198592",
"desc": "توضیحات پرداخت کننده",
"callback": "https://example.com/callback"
}'
<?php
$params = array(
'order_id' => '101',
'amount' => 10000,
'phone' => '09382198592',
'desc' => 'توضیحات پرداخت کننده',
'callback' => 'https://example.com/callback',
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.idpay.ir/v1/payment');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'X-API-KEY: 6a7f99eb-7c20-4412-a972-6dfb7cd253a4',
'X-SANDBOX: true'
));
$result = curl_exec($ch);
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($httpcode);
var_dump($result);
var request = require('request');
var options = {
method: 'POST',
url: 'https://api.idpay.ir/v1/payment',
headers: {
'Content-Type': 'application/json',
'X-API-KEY': '6a7f99eb-7c20-4412-a972-6dfb7cd253a4',
'X-SANDBOX': true,
},
body: {
'order_id': '101',
'amount': 10000,
'phone': '09382198592',
'desc': 'توضیحات پرداخت کننده',
'callback': 'https://example.com/callback',
},
json: true,
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});
url := "https://api.idpay.ir/v1/payment"
data := map[string]string{
"order_id": "101",
"amount": "10000",
"phone": "09382198592",
"desc": "توضیحات پرداخت کننده",
"callback": "https://example.com/callback",
}
payload, _ := json.Marshal(data)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-KEY", "6a7f99eb-7c20-4412-a972-6dfb7cd253a4")
req.Header.Set("X-SANDBOX", "true")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(string(body))
آدرس درخواست
POST https://api.idpay.ir/v1/payment
پارامترهای مورد نیاز
پارامتر | نوع | ضروری | توضیحات |
---|---|---|---|
order_id | string | بله | شماره سفارش پذیرنده به طول حداکثر 50 کاراکتر |
amount | integer | بله | مبلغ قابل پرداخت به ریال مبلغ باید بین 1,000 ریال تا 500,000,000 ریال باشد |
phone | string | خیر | تلفن همراه پرداخت کننده به طول 11 کاراکتر مثل 09382198592 |
desc | string | خیر | توضیح تراکنش به طول حداکثر 255 کاراکتر |
callback | string | بله | آدرس بازگشت به سایت پذیرنده به طول حداکثر 255 کاراکتر |
وضعیت پاسخ
کد وضعیت | توضیحات |
---|---|
201 | تراکنش با موفقیت ایجاد شد |
403 | لیست خطاها |
405 | لیست خطاها |
406 | لیست خطاها |
وضعیت 200: با اجرای دستور بالا پاسخی مشابه متن زیر با فرمت JSON دریافت میشود:
{
"id": "d2e353189823079e1e4181772cff5292",
"link": "https://idpay.ir/p/ws-sandbox/d2e353189823079e1e4181772cff5292"
}
وضعیت 406: در صورت بروز خطا پاسخی مشابه متن زیر با فرمت JSON دریافت میشود:
{
"error_code": 32,
"error_message": "شماره سفارش `order_id` نباید خالی باشد."
}
پاسخ
درصورتیکه درخواست موفق باشد، وضعیت پاسخ 201 Created
اعلام خواهد شد.
در پاسخ، مقادیر id
و link
باز میگردد که بهتر است آنها را در دیتابیس خود ذخیره کنید.
بعد از ذخیره اطلاعات دریافتی، پرداخت کننده باید به لینک دریافت شده منتقل شود.
پارامتر | نوع | توضیحات |
---|---|---|
id | string | کلید منحصر بفرد تراکنش |
link | string | لینک پرداخت برای انتقال خریدار به درگاه پرداخت |
بازگشت به سایت پذیرنده
بعد از اتمام عملیات پرداخت، درصورتیکه پرداخت با موفقیت انجام شده باشد، پرداخت کننده به آدرسی که پذیرنده در callback
مشخص کرده بود منتقل میشود.
همچنین پارامترهای زیر به آدرس callback
تعریف شده در مرحله ایجاد تراکنش POST
میشود.
پارامترهای ارسالی
پارامتر | نوع | توضیحات |
---|---|---|
status | integer | وضعیت تراکنش |
track_id | integer | کد رهگیری آیدی پی |
id | string | کلید منحصر بفرد تراکنش که در مرحله ایجاد تراکنش دریافت شده است |
order_id | string | شماره سفارش پذیرنده که در مرحله ایجاد تراکنش ارسال شده است |
amount | integer | مبلغ ثبت شده هنگام ایجاد تراکنش |
card_no | string | شماره کارت پرداخت کننده با فرمت 123456******1234 |
hashed_card_no | string | هش شماره کارت پرداخت کننده با الگوریتم SHA256 |
date | timestamp | زمان پرداخت تراکنش |
استعلام وضعیت تراکنش
با استفاده از آدرس زیر میتوانید آخرین وضعیت یک تراکنش را دریافت نمایید.
curl -X POST https://api.idpay.ir/v1/payment/inquiry \
-H 'Content-Type: application/json' \
-H 'X-API-KEY: 6a7f99eb-7c20-4412-a972-6dfb7cd253a4' \
-H 'X-SANDBOX: true' \
-d '{
"id": "d2e353189823079e1e4181772cff5292",
"order_id": "101"
}'
<?php
$params = array(
'id' => 'd2e353189823079e1e4181772cff5292',
'order_id' => '101',
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.idpay.ir/v1/payment/inquiry');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'X-API-KEY: 6a7f99eb-7c20-4412-a972-6dfb7cd253a4',
'X-SANDBOX: true',
));
$result = curl_exec($ch);
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($httpcode);
var_dump($result);
var request = require('request');
var options = {
method: 'POST',
url: 'https://api.idpay.ir/v1/payment/inquiry',
headers: {
'Content-Type': 'application/json',
'X-API-KEY': '6a7f99eb-7c20-4412-a972-6dfb7cd253a4',
'X-SANDBOX': true,
},
body: {
'id': 'd2e353189823079e1e4181772cff5292',
'order_id': '101',
},
json: true,
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});
url := "https://api.idpay.ir/v1/payment/inquiry"
data := map[string]string{
"id": "d2e353189823079e1e4181772cff5292",
"order_id": "101",
}
payload, _ := json.Marshal(data)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-KEY", "6a7f99eb-7c20-4412-a972-6dfb7cd253a4")
req.Header.Set("X-SANDBOX", "true")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(string(body))
آدرس درخواست
POST https://api.idpay.ir/v1/payment/inquiry
پارامترهای مورد نیاز
پارامتر | نوع | ضروری | توضیحات |
---|---|---|---|
id | string | بله | کلید منحصر بفرد تراکنش که در مرحله ایجاد تراکنش دریافت شده است |
order_id | string | بله | شماره سفارش پذیرنده که در مرحله ایجاد تراکنش ارسال شده است |
وضعیت پاسخ
کد وضعیت | توضیحات |
---|---|
200 | استعلام با موفقیت پاسخ داده شد |
400 | لیست خطاها |
403 | لیست خطاها |
406 | لیست خطاها |
با اجرای دستور بالا پاسخی مشابه متن زیر با فرمت JSON دریافت میشود:
{
"status": "1",
"track_id": "10012",
"id": "d2e353189823079e1e4181772cff5292",
"order_id": "101",
"amount": "10000",
"card_no": "610433******1064",
"hashed_card_no": "D6933ABC18DE6DAB26A401738D0F4269EC2836B69F87E51933B012F9A8C6D9DB",
"date": "1533559373"
}
وضعیت 406: در صورت بروز خطا پاسخی مشابه متن زیر با فرمت JSON دریافت میشود:
{
"error_code": 32,
"error_message": "شماره سفارش `order_id` نباید خالی باشد."
}
پاسخ
پارامتر | نوع | توضیحات |
---|---|---|
status | integer | وضعیت تراکنش |
track_id | integer | کد رهگیری آیدی پی |
id | string | کلید منحصر بفرد تراکنش که در مرحله ایجاد تراکنش دریافت شده است |
order_id | string | شماره سفارش پذیرنده که در مرحله ایجاد تراکنش ارسال شده است |
amount | integer | مبلغ ثبت شده هنگام ایجاد تراکنش |
card_no | string | شماره کارت پرداخت کننده با فرمت 123456******1234 |
hashed_card_no | string | هش شماره کارت پرداخت کننده با الگوریتم SHA256 |
date | timestamp | زمان پرداخت تراکنش |
وضعیت تراکنش
وضعیت تراکنش دارای کدهای زیر است که توضیح هر یک در جدول زیر آمده است:
کد وضعیت تراکنش | توضیحات |
---|---|
1 | پرداخت انجام نشده است |
2 | پرداخت ناموفق بوده است |
3 | خطا رخ داده است |
100 | پرداخت تایید شده است |
لیست خطاها
لیست خطاها دارای کدهای زیر است که توضیح هر یک در جدول زیر آمده است:
وضعیت | کد خطا | توضیح خطا |
---|---|---|
500 | -1 | خطای غیر منتظره |
403 | 11 | کاربر مسدود شده است. |
403 | 12 | API Key یافت نشد. |
403 | 13 | درخواست شما از {ip} ارسال شده است. این IP با IP های ثبت شده در وب سرویس همخوانی ندارد. |
403 | 14 | وب سرویس تایید نشده است. |
403 | 21 | حساب بانکی متصل به وب سرویس تایید نشده است. |
404 | 22 | وب سریس یافت نشد. |
401 | 23 | اعتبار سنجی وب سرویس ناموفق بود. |
403 | 24 | حساب بانکی مرتبط با این وب سرویس غیر فعال شده است. |
406 | 31 | کد تراکنش id نباید خالی باشد. |
406 | 32 | شماره سفارش order_id نباید خالی باشد. |
406 | 33 | مبلغ amount نباید خالی باشد. |
406 | 34 | مبلغ amount باید بیشتر از {min-amount} ریال باشد. |
406 | 35 | مبلغ amount باید کمتر از {max-amount} ریال باشد. |
406 | 36 | مبلغ amount بیشتر از حد مجاز است. |
406 | 37 | آدرس بازگشت callback نباید خالی باشد. |
406 | 38 | درخواست شما از آدرس {domain} ارسال شده است. دامنه آدرس بازگشت callback با آدرس ثبت شده در وب سرویس همخوانی ندارد. |
406 | 39 | آدرس بازگشت callback نامعتبر است. |
406 | 44 | فیلتر تراکنش صحیح نمی باشد. |
405 | 51 | تراکنش ایجاد نشد. |
400 | 52 | استعلام نتیجه ای نداشت. |