مقدمات و پیشنیازها
به راهنمای سرویس اتصال به درگاه پرداخت اینترنتی ایران درگاه خوش آمدید. این مستندات، جهت راهنمایی شما در استفاده از وب سرویس ایران درگاه تهیه شده است. در صورت وجود هرگونه سوال یا اشکال در هر مرحله میتوانید با ما تماس بگیرید. لطفا قبل از پیادهسازی به نکات زیر توجه نمایید:
تمامی درخواستها به صورت REST میباشند.
در صورت دریافت هرگونه خطا، ابتدا پارامترهای ارسالی خود را بررسی نمایید. پس از بررسی، در صورتی که همچنان خطا رفع نشده باشد، پارامترهای ارسالی را به همراه تصویر خطا برای ما ارسال کنید تا در اسرع وقت توسط تیم فنی بررسی و مشکل شما رفع شود.
درگاه پرداخت
راهنمای کلی
جهت اتصال به درگاه پرداخت، تنها کافیست چهار مرحله زیر را پس از دریافت کد مرچنت پیاده کنید:
ایجاد تراکنش: در این مرحله، اطلاعات تراکنش خود را برای ما ارسال کنید تا در پاسخ به شما، شناسه یکتا یا
authority
بازگردانده شود. شناسه یکتا را حتما نزد خود نگه دارید (آن را در پایگاه داده خود ذخیره نمایید) تا در ادامه مراحل با مشکل مواجه نشوید.هدایت کاربر به درگاه: با استفاده از
authority
دریافت شده، کاربر را به آدرس مشخص شده هدایت کنید تا کاربر شما به درگاه رفته و عملیات پرداخت را انجام دهد.بازگشت اطلاعات: در این مرحله، کاربر پس از انجام تراکنش یا انصراف از تراکنش به صفحه فروشگاه هدایت خواهد شد که اطلاعات تراکنش به صورت
POST
به آدرسcallbackURL
که در مرحله اول ارسال کردهاید، ارسال میشوند.تایید تراکنش: در این مرحله، اطلاعات تراکنش که قبلا به آدرس
callbackURL
ارسال شده بود، بازگردانده میشود. در صورتی که تراکنش موفقیتآمیز بوده باشد، برای تکمیل تراکنش، حتما باید متد تایید تراکنش را فراخوانی کنید تا کد پیگیری تراکنش برای شما ارسال گردد.
ایجاد تراکنش
curl 'https://dargaah.com/sandbox/payment' \
-H 'Content-Type: application/json' \
-d '{
"merchantID": "TEST",
"amount": 500000,
"callbackURL": "https://example.com",
"orderId": "1234",
"cardNumber" : "1234123412341234"
}'
$data = [
"merchantID" => "TEST",
"amount" => 500000,
"callbackURL" => "https://example.com",
"orderId" => "1234",
"cardNumber" => "1234123412341234"
];
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://dargaah.com/sandbox/payment',
CURLOPT_RETURNTRANSFER => true,
# if you get SSL error (curl error 60) add 2 lines below
CURLOPT_SSL_VERIFYHOST => 0,
CURLOPT_SSL_VERIFYPEER => 0,
# end SSL error
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_HTTPHEADER => [
'Content-Type: application/json'
],
));
$response = curl_exec($curl);
curl_close($curl);
var_dump($response);
const axios = require("axios");
const data = {
merchantID: "TEST",
amount: 500000,
callbackURL: "https://example.com",
orderId: "1234",
cardNumber: "1234123412341234",
};
const url = "https://dargaah.com/sandbox/payment";
axios
.post(url, data)
.then((response) => {
console.log(response.data);
})
.catch((error) => {
console.error(error);
});
import requests
import json
data = {
"merchantID": "TEST",
"amount": 500000,
"callbackURL": "https://example.com",
"orderId": "1234",
"cardNumber": "1234123412341234"
}
url = "https://dargaah.com/sandbox/payment"
payload = json.dumps(data)
headers = {
'Content-Type': 'application/json'
}
response = requests.post(url, data=payload, headers=headers)
response_content = response.json()
print(response_content)
var data = new
{
merchantID = "TEST",
amount = 500000,
callbackURL = "https://example.com",
orderId = "1234",
cardNumber = "1234123412341234"
};
var url = "https://dargaah.com/sandbox/payment";
// Install the Newtonsoft.Json NuGet package first
var json = Newtonsoft.Json.JsonConvert.SerializeObject(data);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var client = new HttpClient();
var response = await client.PostAsync(url, content);
var responseContent = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseContent);
import (
"bytes"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
data := map[string]interface{}{
"merchantID": "TEST",
"amount": 500000,
"callbackURL": "https://example.com",
"orderId": "1234",
"cardNumber": "1234123412341234",
}
url := "https://dargaah.com/sandbox/payment"
jsonData, err := json.Marshal(data)
if err != nil {
fmt.Println("Error marshaling JSON:", err)
return
}
response, err := http.Post(url, "application/json", bytes.NewBuffer(jsonData))
if err != nil {
fmt.Println("Error sending request:", err)
return
}
defer response.Body.Close()
responseData, err := ioutil.ReadAll(response.Body)
if err != nil {
fmt.Println("Error reading response:", err)
return
}
fmt.Println(string(responseData))
دستور بالا در صورت موفقیت آمیز بودن، کدی با فرمت JSON مانند زیر برمیگرداند:
{
"message": "اتصال به درگاه بانک با موفقیت انجام شده است.",
"status": 200,
"authority": "20230912094118ZY"
}
با استفاده از ارسال اطلاعات به صورت POST
به آدرس درخواست، تراکنش را ایجاد نمایید.
آدرس درخواست
https://dargaah.com/payment
آدرس درخواست محیط سندباکس
https://dargaah.com/sandbox/payment
پارامترهای ارسالی
پارامتر | نوع | الزامی | توضیحات |
---|---|---|---|
merchantID |
string | بله | مرچنت کد دریافتی داخل پنل کاربری برای اتصال به درگاه (برای محیط سندباکس، مقدار TEST را قرار دهید) |
amount |
integer | بله | مبلغ تراکنش به ریال بدون اعشار و بزرگتر یا مساوی ۱۰،۰۰۰ |
callbackURL |
string | بله | آدرس بازگشتی که باید به صورت urlencode ارسال شود و باید با آدرس سایت تایید شده در هنگام دریافت درگاه یکسان ﺑﺎﺷﺪ |
orderId |
string | بله | شماره سفارش فروشگاه شما |
cardNumber |
string | خیر | شماره کارت خریدار است که این شماره کارت بعد از انجام عملیات پرداخت با شماره کارت دریافتی از بانک تطابق داده میشود و در صورتی که یکسان نباشد، مبلغ تراکنش به حساب پرداخت کننده برمیگردد (برای محیط سندباکس، مقدار 1234123412341234 را قرار دهید) |
mobile |
string | خیر | شماره همراه پرداخت کننده تراکنش |
description |
string | خیر | توضیحات تراکنش |
پاسخ
پارامتر | نوع | توضیحات |
---|---|---|
message |
string | پیام وضعیت تراکنش |
status |
integer | کد وضعیت تراکنش |
authority |
string | شناسه یکتای تراکنش جهت اتصال به درگاه |
هدایت کاربر به درگاه
در صورتی که پاسخ ایجاد تراکنش موفقیتآمیز باشد، میتوانید با استفاده از authority
دریافتی، کاربر را به درگاه پرداخت هدایت نمایید.
آدرس هدایت به درگاه
https://dargaah.com/ird/startpay/{authority}
آدرس هدایت به محیط سندباکس
https://dargaah.com/sandbox/ird/startpay/{authority}
بازگشت اطلاعات
در این مرحله، کاربر پس از انجام تراکنش یا انصراف از تراکنش به صفحه فروشگاه هدایت خواهد شد.
پارامترهای دریافتی
پارامتر | نوع | توضیحات |
---|---|---|
code |
integer | کد وضعیت پرداخت تراکنش |
message |
string | پیام مربوط به وضعیت تراکنش |
authority |
string | شناسه مربوط به تراکنش |
amount |
integer | مبلغ تراکنش انجام شده به ریال |
orderId |
string | شماره سفارش ارسالی در مرحله اول |
تایید تراکنش
curl 'https://dargaah.com/sandbox/verification' \
-H 'Content-Type: application/json' \
-d '{
"merchantID": "TEST",
"authority": "20230912094118ZY",
"amount": 500000,
"orderId": "1234"
}'
$data = [
"merchantID" => "TEST",
"authority" => "20230912094118ZY",
"amount" => 500000,
"orderId" => "1234"
];
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://dargaah.com/sandbox/verification',
CURLOPT_RETURNTRANSFER => true,
# if you get SSL error (curl error 60) add 2 lines below
CURLOPT_SSL_VERIFYHOST => 0,
CURLOPT_SSL_VERIFYPEER => 0,
# end SSL error
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_HTTPHEADER => [
'Content-Type: application/json'
],
));
$response = curl_exec($curl);
curl_close($curl);
var_dump($response);
const axios = require("axios");
const data = {
merchantID: "TEST",
authority: "20230912094118ZY",
amount: 500000,
orderId: "1234",
};
const url = "https://dargaah.com/sandbox/verification";
axios
.post(url, data)
.then((response) => {
console.log(response.data);
})
.catch((error) => {
console.error(error);
});
import requests
import json
data = {
"merchantID": "TEST",
"authority": "20230912094118ZY",
"amount": 500000,
"orderId": "1234"
}
url = "https://dargaah.com/sandbox/verification"
payload = json.dumps(data)
headers = {
'Content-Type': 'application/json'
}
response = requests.post(url, data=payload, headers=headers)
response_content = response.json()
print(response_content)
var data = new
{
merchantID = "TEST",
authority = "20230912094118ZY",
amount = 500000,
orderId = "1234"
};
var url = "https://dargaah.com/sandbox/verification";
// Install the Newtonsoft.Json NuGet package first
var json = Newtonsoft.Json.JsonConvert.SerializeObject(data);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var client = new HttpClient();
var response = await client.PostAsync(url, content);
var responseContent = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseContent);
import (
"bytes"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
data := map[string]interface{}{
"merchantID": "TEST",
"authority": "20230912094118ZY",
"amount": 500000,
"orderId": "1234",
}
url := "https://dargaah.com/sandbox/verification"
jsonData, err := json.Marshal(data)
if err != nil {
fmt.Println("Error marshaling JSON:", err)
return
}
response, err := http.Post(url, "application/json", bytes.NewBuffer(jsonData))
if err != nil {
fmt.Println("Error sending request:", err)
return
}
defer response.Body.Close()
responseData, err := ioutil.ReadAll(response.Body)
if err != nil {
fmt.Println("Error reading response:", err)
return
}
fmt.Println(string(responseData))
دستور بالا در صورت موفقیت آمیز بودن، کدی با فرمت JSON مانند زیر برمیگرداند:
{
"message": "تراکنش با موفقیت انجام شده است.",
"status": 100,
"refId": "1234567890",
"orderId": "1234",
"cardNumber": "123412******1234"
}
پس از انجام این مرحله، عملیات پرداخت، در پنل فروشگاه تایید خواهد شد.
آدرس درخواست
https://dargaah.com/verification
آدرس درخواست محیط سندباکس
https://dargaah.com/sandbox/verification
پارامترهای ارسالی
پارامتر | نوع | الزامی | توضیحات |
---|---|---|---|
merchantID |
string | بله | مرچنت کد دریافتی داخل پنل کاربری برای اتصال به درگاه (برای محیط سندباکس، مقدار TEST را قرار دهید) |
authority |
string | بله | شناسه یکتای تراکنش |
amount |
integer | بله | مبلغ تراکنش به ریال، بدون اعشار و بزرگتر یا مساوی ۱۰،۰۰۰ |
orderId |
string | بله | شماره سفارش فروشگاه شما |
پاسخ
پارامتر | نوع | توضیحات |
---|---|---|
message |
string | پیام مربوط به وضعیت تایید تراکنش |
status |
integer | وضعیت تایید تراکنش |
refId |
string | شماره پیگیری تراکنش |
orderId |
string | شماره سفارش فروشگاه شما |
cardNumber |
string | شماره کارت پرداخت کننده تراکنش (Mask شده) |
نشان اعتماد ایران درگاه
<script src="https://trust.irandargah.com/index.js">
با توجه به لزوم جلب اعتماد مشتریان جهت انجام پرداختی امن و سریع، میتوانید با قراردادن کد روبرو در قسمتی از وبسایت خود، که برای کاربران قابل مشاهده باشد (مانند فوتر وبسایت)، مشتریان را از پردازش پرداخت توسط ایران درگاه، مطمئن سازید.
جدول وضعیتها
کد وضعیت تراکنشها در جدول زیر آمده است:
کد | پیام |
---|---|
۱۰۰ | تراکنش با موفقیت انجام شده است |
۱۰۱ | تراکنش قبلا وریفای شده است |
۲۰۰ | اتصال به درگاه بانک با موفقیت انجام شده است |
۲۰۱ | در حال پرداخت در درگاه بانک |
۴۰۳ | کد مرچنت صحیح نمیباشد |
۴۰۴ | تراکنش یافت نشد |
-۱ | کاربر از انجام تراکنش منصرف شده است |
-۲ | اطلاعات ارسالی صحیح نمیباشد |
-۱۰ | مبلغ تراکنش کمتر از ۱۰،۰۰۰ ریال است |
-۱۱ | مبلغ تراکنش با مبلغ پرداخت، یکسان نیست. مبلغ برگشت خورد |
-۱۲ | شماره کارتی که با آن، تراکنش انجام شده است با شماره کارت ارسالی، مغایرت دارد. مبلغ برگشت خورد |
-۱۳ | تراکنش تکراری است |
-۲۰ | شناسه تراکنش یافت نشد |
-۲۱ | مدت زمان مجاز، جهت ارسال به بانک گذشتهاست |
-۲۲ | تراکنش برای بانک ارسال شده است |
-۲۳ | خطا در اتصال به درگاه بانک |
-۳۰ | اشکالی در فرایند پرداخت ایجاد شده است. مبلغ برگشت خورد |
-۳۱ | خطای ناشناخته |