NAV Navbar
cURL PHP Node Go

مقدمه

این راهنما نحوه اتصال برنامه نویسان به درگاه های پرداخت از طریق API آیدی پی را توضیح میدهد.

API آیدی پی به روش REST سازماندهی شده است. همچنین بدنه درخواست ها و پاسخ ها با فرمت JSON می‌باشد.

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

احراز هویت

برای استفاده از API های آیدی پی نیاز به یک API KEY است. شما می‌توانید به داشبورد خود در آیدی پی رفته و در بخش وب سرویس‌های من، یک وب سرویس جدید ایجاد کنید.

بعد از ایجاد وب سرویس، API KEY خود را دریافت می‌کنید و می‌توانید برای فراخوانی API از آن استفاده کنید.

برای ارسال تمام درخواست ها باید API KEY را مانند مثال زیر در header ارسال نمایید:

X-API-KEY: 965b0483-4519-46b0-aca0-1a6971dc2781

پارامتر نوع ضروری توضیحات
X-API-KEY string بله کلید منحصر بفرد جهت احراز هویت ؛ به طول 35 کاراکتر

آزمایشگاه

برای تست 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: 965b0483-4519-46b0-aca0-1a6971dc2781' \
  -H 'X-SANDBOX: true' \
  -d '{
  "order_id": 101,
  "amount": 10000,
  "phone": "09382198592",
  "desc": "توضیحات پرداخت کننده",
  "callback": "https://example.com/callback"
}'
<?php

$url = 'https://api.idpay.ir/v1/payment';

$params = array(
  'order_id' => '101',
  'amount' => 10000,
  'phone' => '09382198592',
  'desc' => 'توضیحات پرداخت کننده',
  'callback' => 'https://example.com/callback',
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
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: 965b0483-4519-46b0-aca0-1a6971dc2781',
  'X-SANDBOX: true'
));

$result = curl_exec($ch);
curl_close($ch);

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': '965b0483-4519-46b0-aca0-1a6971dc2781',
    '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", "965b0483-4519-46b0-aca0-1a6971dc2781")
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 کاراکتر

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

{
  "id": "d2e353189823079e1e4181772cff5292",
  "link": "https://idpay.ir/p/ws-sandbox/d2e353189823079e1e4181772cff5292"
}

وضعیت پاسخ

کد توضیحات
201 تراکنش ایجاد شد
403 API Key نامعتبر است
403 IP درخواست نامعتبر است
403 سرویس پرداخت تایید نشده است
403 دریافت کننده مسدود شده است
403 حساب بانکی سرویس تایید نشده است
404 سرویس پرداخت یافت نشد
406 پارامتر ارسالی نامعتبر است (شماره سفارش، مبلغ، شماره تلفن همراه در صورت ارسال، آدرس بازگشت)
406 سرویس در حال حاضر غیرفعال است

پاسخ

درصورتیکه درخواست موفق باشد، وضعیت 201 Created اعلام خواهد شد.

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

پارامتر نوع توضیحات
id string کلید منحصر بفرد تراکنش
link string لینک پرداخت برای انتقال خریدار به آن

بازگشت به سایت پذیرنده

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

همچنین پارامترهای زیر به آدرس callback تعریف شده در مرحله ایجاد تراکنش POST می‌شود.

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

پارامتر نوع توضیحات
status integer وضعیت تراکنش
track_id integer کد رهگیری آیدی پی
id string کلید منحصر بفرد تراکنش که در مرحله ایجاد تراکنش دریافت شده است
order_id string شماره سفارش پذیرنده که در مرحله ایجاد تراکنش ارسال شده است
amount integer مبلغ ثبت شده هنگام ایجاد تراکنش
date timestamp زمان پرداخت تراکنش

استعلام وضعیت تراکنش

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

curl -X POST https://api.idpay.ir/v1/payment/inquiry \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: 965b0483-4519-46b0-aca0-1a6971dc2781' \
  -H 'X-SANDBOX: true' \
  -d '{
  "id": "d2e353189823079e1e4181772cff5292",
  "order_id": "101"
}'
<?php

$url = 'https://api.idpay.ir/v1/payment/inquiry';

$params = array(
  'id' => 'd2e353189823079e1e4181772cff5292',
  'order_id' => '101',
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
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: 965b0483-4519-46b0-aca0-1a6971dc2781',
  'X-SANDBOX: true',
));

$result = curl_exec($ch);
curl_close($ch);

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': '965b0483-4519-46b0-aca0-1a6971dc2781',
    '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", "965b0483-4519-46b0-aca0-1a6971dc2781")
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 بله شماره سفارش پذیرنده که در مرحله ایجاد تراکنش ارسال شده است

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

{
  "status": "1",
  "track_id": "10012",
  "id": "d2e353189823079e1e4181772cff5292",
  "order_id": "101",
  "amount": "10000",
  "date": "1533559373"
}

وضعیت پاسخ

کد توضیحات
200 پاسخ دریافت شد
403 API Key نامعتبر است
403 IP درخواست نامعتبر است
403 سرویس پرداخت تایید نشده است
403 دریافت کننده مسدود شده است
404 سرویس پرداخت یافت نشد
406 پارامتر ارسالی نامعتبر است (شماره سفارش، کلید منحصر بفرد تراکنش)

پاسخ

پارامتر نوع توضیحات
status integer وضعیت تراکنش
track_id integer کد رهگیری آیدی پی
id string کلید منحصر بفرد تراکنش که در مرحله ایجاد تراکنش دریافت شده است
order_id string شماره سفارش پذیرنده که در مرحله ایجاد تراکنش ارسال شده است
amount integer مبلغ ثبت شده هنگام ایجاد تراکنش
date timestamp زمان پرداخت تراکنش

وضعیت تراکنش

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

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