مستندات فنی نسخه ۲ (V-2.0.1)
» مقدمه
این راهنما، نحوهی اتصال برنامهنویسان به درگاههای پرداخت ملّی پی از طریق وب سرویس را توضیح میدهد. وب سرویس ملّی پی به روش REST سازماندهی شدهاست. همچنین بدنهی درخواستها و پاسخها با فرمت JSON میباشد.
شما میتوانید نمونه کدها را در ستون سمت چپ صفحه مشاهده کنید و درصورت تمایل میتوانید از طریق تبهای بالای صفحه، نمونه کدهای زبانهای برنامهنویسی مختلف را انتخاب کنید. در صورت نیاز به پشتیبانی فنی، میتوانید از طریق پنل کاربری خود، درخواست پشتیبانی فنی ارسال نمایید.
» اتصال به وب سرویس
برای تمامی درخواستها، میبایست ابتدا یک درگاه پرداخت برای خود ایجاد نمایید. پس از تایید درگاه پرداخت در سامانهی ملّی پی توسط کارشناسان مربوطه، به شما یک کلید و رمز وب سرویس که کاملا محرمانه میباشد، داده میشود که بایستی در تمامی اقدامات خود، آنها را در هدر درخواست برای API ارسال نمایید.
تمامی درخواستها میبایست به صورت POST ارسال گردد و پاسخها به صورت HTTP با ساختار JSON برای شما بازگردانده میشوند. در صورت صحیح بودن درخواست، با وضعیت کدهای 200 و 201 به شما پاسخ داده خواهد شد و در صورت خطا، با وضعیتهای مشخصشده در جدول خطاها پاسخ داده میشود. در صورت بروز خطا دو مقدار error_no برای کد وضعیت خطا و message برای پیام خطای رویداده با ساختار JSON پاسخ داده میشود.
در صورتی که نیاز به تست وب سرویس دارید، مقدار sand-box را برابر با true قرار دهید. تمامی مراحل انجام تراکنش برای شما در محیط شبیه سازی انجام می گیرد و پس از ورود به محیط پرداخت با انتخاب انصراف از پرداخت یا تایید پرداخت می توانید بقیه مراحل را طی نمایید.
آدرس پایه برای ارسال درخواست در زیر قرار گرفتهاست :
import requests
import json
url = "https://mellipay.ir/api/v2/payment/"
payload = json.dumps({
your data
})
headers = {
'api-key': '****************',
'secret-key': '****************',
'sand-box': false,
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://mellipay.ir/api/v2/payment/');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
'follow_redirects' => TRUE
));
$request->setHeader(array(
'api-key' => '***********',
'secret-key' => '***********',
'sand-box' => false,
'Content-Type' => 'application/json'
));
$request->setBody('{your data}');
try {
$response = $request->send();
if ($response->getStatus() == 200) {
echo $response->getBody();
}
else {
echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
$response->getReasonPhrase();
}
}
catch(HTTP_Request2_Exception $e) {
echo 'Error: ' . $e->getMessage();
}
var client = new RestClient("https://mellipay.ir/api/v2/payment/");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("api-key", "***********");
request.AddHeader("secret-key", "****************");
request.AddHeader("sand-box", false);
request.AddHeader("Content-Type", "application/json");
var body = @"{" your data "}";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
» ایجاد تراکنش
https://mellipay.ir/api/v2/payment/
برای هر تراکنش، بایستی ابتدا آن را ایجاد نمایید. با استفاده از آدرس بالا و اطلاعات خواسته شده، میتوانید درخواست ساخت تراکنش را به API بدهید.
توضیحات متغیرها در جدول زیر قابل مشاهدهاست:
متغیر | نوع | ضروری | تعریف |
---|---|---|---|
transaction_id | عدد صحیح | بله |
یک شناسه عددی است که از طرف پذیرنده برای ما ارسال میشود و در دفعات بعد باید از آن استفاده کند. |
amount | عدد صحیح | بله |
مبلغ مورد نظر به ریال که بایستی بین 100000 و 1000000000 باشد. |
custom_field | جی سان | خیر |
اگر نیاز به ارسال داده هایی دارید که می خواهید بعد از انجام تراکنش آنها را دریافت کنید، می توانید متغیرهای خود را به صورت جی سان ارسال کنید. |
callback_url | رشته یا متن | بله |
آدرسی است که اطلاعات مربوطه، در پاسخ به انجام تراکنش، به آن ارسال میشود و بایستی در همان URL باشد که درگاه پرداخت ساخته شدهاست. |
در پاسخ به این درخواست، در صورت ساخته شدن تراکنش، کد درخواست 201 (به معنای ایجاد شدن تراکنش) برای شما ارسال میگردد که اطلاعات برگشتی در data به صورت زیر خواهد بود. در غیر این صورت، کدهای درخواست مربوط به خطا، همراه با دادههای آن ارسال خواهد شد.
متغیر | نوع | تعریف |
---|---|---|
tracking_code | رشته یا متن |
کدی که از طرف ما برای پذیرنده ارسال میشود. همچنین این کد، برای پیگیری تراکنش و ارسال کاربر به درگاه پرداخت استفاده میشود. |
transaction_id | عدد صحیح |
کدی که از پذیرنده در زمان درخواست، دریافت شدهاست. |
link | رشته یا متن |
لینک ارسال کاربر به درگاه پرداخت میباشد. |
import requests
import json
url = "https://mellipay.ir/api/v2/payment/"
payload = json.dumps({
"transaction_id": 12345,
"amount":1000000,
"custom_field": {
"name": "a",
"phone": "09171111111"
},
"callback_url":"https://your.site/callback/url"
})
headers = {
'api-key': '****************',
'secret-key': '****************',
'sand-box': false,
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://mellipay.ir/api/v2/payment/',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"transaction_id": 1,
"amount":1000000,
"callback_url":"https://your.site/callback/url",
"custom_field":{
"name":"name",
"phone":"09171111111"
}
}',
CURLOPT_HTTPHEADER => array(
'api-key: xxxxxxxxxxxxxx',
'secret-key: xxxxxxxxxxxxxx',
'sand-box: false',
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
var client = new RestClient("https://mellipay.ir/api/v2/payment/");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("api-key", "xxxxxxxxxxxxxx");
request.AddHeader("secret-key", "xxxxxxxxxxxxxx");
request.AddHeader("sand-box", "false");
request.AddHeader("Content-Type", "application/json");
var body = @"{" + "\n" +
@" ""transaction_id"": 1," + "\n" +
@" ""amount"":1000000," + "\n" +
@" ""callback_url"":""https://your.site/callback/url""," + "\n" +
@" ""custom_field"":{" + "\n" +
@" ""name"":""name""," + "\n" +
@" ""phone"":""09171111111""" + "\n" +
@" }" + "\n" +
@"}";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
{
"error": false,
"status": 201,
"error_no": "",
"message": "",
"data": {
"tracking_code": "5d7629993db4fd721093923430a9ba26e3d8cb260d7b0dd764a41c171d3c827d",
"transaction_id": 1,
"link": "https://mellipay.ir/api/v2/payment/start/5d7629993db4fd721093923430a9ba26e3d8cb260d7b0dd764a41c171d3c827d/",
"custom_field": {
"name": "a",
"phone": "09171111111"
},
}
}
» ارسال کاربر به درگاه پرداخت
پس از ساخت تراکنش، یک آدرس دریافت میکنید که حاوی آدرس بالا همراه با توکن آن تراکنش است. در وبسایت خود، بایستی کاربر را به این آدرس راهنمایی کنید تا به درگاه پرداخت برود. در انتها، پس از پایان تراکنش، نتیجهی آن برای شما از طریق آدرسی که در مرحله قبل به API دادهاید؛ ارسال میگردد. نتیجهی ارسالشده در صورت انجام صحیح تراکنش، با کد درخواست 200 ارسال خواهد شد. در صورت تکراری بودن تراکنشها، پاسخ به صورت کد 200 و با پیغام تراکنش تکراری برای آدرس شما ارسال میگردد. این خطا ممکن است در اثر کپی کردن لینک و استفاده چند باره از آن رخ دهد.
» برگشت از درگاه
پس از انجام تراکنش، با هر وضعیتی، کاربر به آدرسی که در ابتدای ساخت تراکنش، معرفی کردهاید؛ برگشت داده میشود و اطلاعات به صورت جی سان ارسال میگردد.
در جدول زیر، توضیحات هر یک از پارامترها آمدهاست:
پارامتر ها | نوع | توضیح |
---|---|---|
status | عدد |
عدد 3 به معنی موفق و عدد ۷ به معنی انصراف از پرداخت میباشد. |
transaction_id | عدد |
شناسهی تراکنشی که در ابتدا ارسال کردهاید. |
customer_ref_num | عدد | کد رهگیری تراکنش |
tracking_code | رشته حروف |
کد رهگیری که پس از ساخت تراکنش از سمت ملّی پی به شما داده شدهاست. |
amount | عدد | مبلغ اصلی تراکنش |
card_hash_pan | رشته حروف | مقدار هش شده کارت بانکی |
card_mask_pan | رشته حروف | مقدار پوشیده شده شماره کارت بانکی |
back_time | عدد | زمان انجام تراکنش به میلی ثانیه |
date_field | رشته حروف | زمان انجام تراکنش به هجری شمسی |
custom_field | جی سان | اطلاعات اضافه ای که پذیرنده در ابتدا ارسال کرده است. |
درصورتیکه وضعیت تراکنش، عدد 3 بود؛ به این معنی است که تراکنش به درستی انجام شده و نیاز به تایید دارد.
این نکته را به خاطر بسپارید که تمامی تراکنشهایی که با موفقیت انجام میشوند؛ ۱۰ دقیقه فرصت دارند تا تایید شوند؛ در غیر این صورت، تراکنش، برگشت خواهد خورد. تا زمانیکه وضعیت تراکنش عدد ۱ نباشد؛ هیچ پولی به حساب شما واریز نمیشود.
در مرحله بعد تایید تراکنش آمدهاست.
{
0: "در انتظار پرداخت",
1: "پرداخت تایید شده",
2: "اتصال به پایانه",
3: "در انتظار تایید",
4: "برگشت به پرداخت کننده",
5: "منقضی شده",
6: "نامشخص",
7: "انصراف از پرداخت",
8: "به حساب پذیرنده واریز شده",
}
{
"status": "3",
"transaction_id": "1",
"customer_ref_num": "1111111111",
"tracking_code": "231d80fc822ec522cbe37bd72542d8969ca332aeed1373c7dd86f7f208683a43",
"amount": "1000000",
"card_hash_pan": "2b773d1c905ef179d05e53fe3b57998fe15967832f5d26e3d5fd2248adf5a577",
"card_mask_pan": "603769********5815",
"back_time": "1688826562063",
"date_field": "1402/04/17 17:59:12",
"custom_field": ""
}
» تایید تراکنش
بعد از انجام هر تراکنش، نتیجهی آن برای شما ارسال میشود. درصورتیکه نتیجه مبنی بر موفق بودن تراکنش بود؛ بایستی شما این تراکنش را حداکثر تا 15 دقیقه تایید کنید. در غیر این صورت، تراکنش انجام شده به کارت کاربر برگشت داده میشود. برای تایید با استفاده از آدرس تعریف شده، اطلاعات زیر را ارسال نمایید.
پارامتر ها | نوع | توضیح |
---|---|---|
tracking_code | رشته |
کدی است که از طرف API بعد از انجام تراکنش برای شما ارسال شدهاست. |
transaction_id | عدد |
شناسهای است که در ابتدای ساخت تراکنش برای ما ارسال کردهاید. |
در صورت تایید تراکنش، اطلاعات زیر به شما پاسخ داده میشود:
پارامتر ها | نوع | توضیح |
---|---|---|
status | عدد |
وضعیت تراکنش (که در صورت تایید ۱ خواهد بود) |
transaction_id | عدد |
شناسهی تراکنشی که در ابتدا ارسال کردهاید. |
customer_ref_num | عدد | کد رهگیری تراکنش |
tracking_code | رشته حروف |
کد رهگیری که پس از ساخت تراکنش از سمت ملّی پی به شما داده شدهاست. |
amount | عدد | مبلغ اصلی تراکنش |
card_hash_pan | رشته حروف | مقدار هش شده کارت بانکی |
card_mask_pan | رشته حروف | مقدار پوشیده شده شماره کارت بانکی |
back_time | عدد | زمان انجام تراکنش به میلی ثانیه |
date_field | رشته حروف | زمان انجام تراکنش به هجری شمسی |
custom_field | جی سان | اطلاعات اضافه ای که پذیرنده در ابتدا ارسال کرده است. |
import requests
import json
url = "https://mellipay.ir/api/v2/payment/verify/"
payload = json.dumps({
"transaction_id": 1,
"tracking_code": "*************************"
})
headers = {
'api-key': 'xxxxxxxxxxx',
'secret-key': 'xxxxxxxxxxx',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://mellipay.ir/api/v2/payment/verify/',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"transaction_id": 1,
"tracking_code":"*************************"
}',
CURLOPT_HTTPHEADER => array(
'api-key: xxxxxxxxxxx',
'secret-key: xxxxxxxxxxx',
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
var client = new RestClient("https://mellipay.ir/api/v2/payment/verify/");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("api-key", "xxxxxxxxxxx");
request.AddHeader("secret-key", "xxxxxxxxxxx");
request.AddHeader("Content-Type", "application/json");
var body = @"{" + "\n" +
@" ""transaction_id"": 1," + "\n" +
@" ""tracking_code"":""*************************""" + "\n" +
@"}";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
{
"error": false,
"status": 200,
"error_no": "",
"message": "در انتظار تایید",
"data": {
"status": 3,
"transaction_id": 1,
"tracking_code": "49a09b370d98abdd656458cc858db59e4f14dfa39aadbb152ba073524bd00cbb",
"amount": 1000000,
"ref_num": "11111111111",
"customer_ref_num": "1111111111",
"card_hash_pan": "2b773d1c905ef179d05e53fe3b57998fe15967832f5d26e3d5fd2248adf5a577",
"card_mask_pan": "603769********5815",
"date_field": "1402/04/17 16:18:03",
"custom_field": {
"name": "alirj",
"phone": "09173200701"
},
"back_time": 1688820514485
}
}
» پیگیری تراکنش نامعلوم
درصورتیکه تراکنشی را ایجاد کرده و کاربر را به سمت آدرس پرداخت هدایت کردهاید اما جوابی دریافت نکردهاید؛ میتوانید از لینک بالا استفاده کرده و اطلاعات تراکنش را در صورت موجود بودن، دریافت کنید. اگر کاربر، تراکنش را انجام داده باشد؛ اطلاعات بهروز شده و برای شما ارسال میگردد. در غیر این صورت، خطای 400 به شما برگشت داده خواهد شد که در پیام آن، علت خطا مشخص شدهاست. برای این کار، به اطلاعات زیر نیاز است:
پارامتر ها | نوع | توضیح |
---|---|---|
tracking_code | رشته |
کدی است که از طرف API بعد از انجام تراکنش برای شما ارسال شدهاست. |
transaction_id | عدد |
شناسهای است که در ابتدای ساخت تراکنش برای ما ارسال کردهاید. |
import requests
import json
url = "https://mellipay.ir/api/v2/payment/inquiry/"
payload = json.dumps({
"transaction_id": 1,
"tracking_code": "*************************"
})
headers = {
'api-key': 'xxxxxxxxxxxxxx',
'secret-key': 'xxxxxxxxxxxxxx',
'sand-box': 'false',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://mellipay.ir/api/v2/payment/inquiry/',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"transaction_id": 1,
"tracking_code":"*************************"
}',
CURLOPT_HTTPHEADER => array(
'api-key: xxxxxxxxxxxxxx',
'secret-key: xxxxxxxxxxxxxx',
'sand-box: false',
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
var client = new RestClient("https://mellipay.ir/api/v2/payment/inquiry/");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("api-key", "xxxxxxxxxxxxxx");
request.AddHeader("secret-key", "xxxxxxxxxxxxxx");
request.AddHeader("sand-box", "false");
request.AddHeader("Content-Type", "application/json");
var body = @"{" + "\n" +
@" ""transaction_id"": 1," + "\n" +
@" ""tracking_code"":""*************************""" + "\n" +
@"}";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
{
"error": false,
"status": 200,
"error_no": "",
"message": "در انتظار تایید",
"data": {
"status": 3,
"transaction_id": 1,
"tracking_code": "49a09b370d98abdd656458cc858db59e4f14dfa39aadbb152ba073524bd00cbb",
"amount": 1000000,
"ref_num": "11111111111",
"customer_ref_num": "1111111111",
"card_hash_pan": "2b773d1c905ef179d05e53fe3b57998fe15967832f5d26e3d5fd2248adf5a577",
"card_mask_pan": "603769********5815",
"date_field": "1402/04/17 16:18:03",
"custom_field": {
"name": "alirj",
"phone": "09173200701"
},
"back_time": 1688820514485
}
}
{
"error": false,
"status": 200,
"error_no": "",
"message": "در انتظار پرداخت",
"data": {
"status": 0,
"transaction_id": 1,
"tracking_code": "979febddba507644e82e37c535fc8540a2a7d600c9a27d8f02ca2d12e2b59635",
"amount": 1000000,
"ref_num": null,
"customer_ref_num": null,
"card_hash_pan": null,
"card_mask_pan": null,
"date_field": "1402/04/18 10:06:20",
"custom_field": {
"name": "ابجد",
"phone": "09171111111"
},
"back_time": 0
}
}
» لیست خطاها
کد درخواست | کد وضعیت | وضعیت | توضیحات |
---|
» افزونه ها و پلاگین ها
عنوان | درباره | آخرین بروزرسانی | لینک ها |
---|---|---|---|
افزونه WHMCS | نسخه 2.0.3 افزونه پنل مدیریت سرور و دامنه WHMCS |
1 سال،4 ماه پیش | دانلود |
افزونه ووکامرس | افزونه درگاه پرداخت ملی پی برای ووکامرس نسخه 2.0.1 |
1 سال،4 ماه پیش | دانلود |
افزونه گراویتی فرم | افزونه گراویتی فرم برای وردپرس نسخه 2.0.1 |
1 سال،4 ماه پیش | دانلود |
نمونه کد postman | فایل نمونه ارسال درخواست توسط postman |
1 سال،4 ماه پیش | دانلود |