NAV Navbar
cURL PHP Node Go

مقدمه

این راهنما نحوه اتصال برنامه نویسان به درگاه های پرداخت از طریق 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 بله مبلغ قابل پرداخت به ریال
مبلغ باید بین 10,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
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",
  "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
date timestamp زمان پرداخت تراکنش

وضعیت تراکنش

وضعیت تراکنش دارای کدهای زیر است که توضیح هر یک در جدول زیر آمده است:

کد وضعیت تراکنش توضیحات
1 پرداخت انجام نشده است
2 پرداخت ناموفق بوده است
3 خطا رخ داده است
100 پرداخت تایید شده است

لیست خطاها

لیست خطاها دارای کدهای زیر است که توضیح هر یک در جدول زیر آمده است:

وضعیت کد خطا توضیح خطا
403 11 کاربر مسدود شده است.
403 12 API Key یافت نشد.
403 13 درخواست شما از {ip} ارسال شده است. این IP با IP های ثبت شده در وب سرویس همخوانی ندارد.
403 14 وب سرویس تایید نشده است.
403 21 حساب بانکی متصل به وب سرویس تایید نشده است.
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 با آدرس ثبت شده در وب سرویس همخوانی ندارد.
405 51 تراکنش ایجاد نشد.
400 52 استعلام نتیجه ای نداشت.