مستندات فنی نسخه ۱ (V-1.0.1)
» مقدمه
این راهنما، نحوهی اتصال برنامهنویسان به درگاههای پرداخت ملّی پی از طریق وب سرویس را توضیح میدهد. وب سرویس ملّی پی به روش REST سازماندهی شدهاست. همچنین بدنهی درخواستها و پاسخها با فرمت JSON میباشد.
شما میتوانید نمونه کدها را در ستون سمت چپ صفحه مشاهده کنید و درصورت تمایل میتوانید از طریق تبهای بالای صفحه، نمونه کدهای زبانهای برنامهنویسی مختلف را انتخاب کنید. در صورت نیاز به پشتیبانی فنی، میتوانید از طریق پنل کاربری خود، درخواست پشتیبانی فنی ارسال نمایید.
» اتصال به وب سرویس
برای تمامی درخواستها، میبایست ابتدا یک درگاه پرداخت برای خود ایجاد نمایید. پس از تایید درگاه پرداخت در سامانهی ملّی پی توسط کارشناسان مربوطه، به شما یک کلید و رمز وب سرویس که کاملا محرمانه میباشد، داده میشود که بایستی در تمامی اقدامات خود، آنها را در هدر درخواست برای API ارسال نمایید.
headers = {
'M-Api-Key': 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'M-Sec-Key': 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'Content-Type': 'application/json'
}
تمامی درخواستها میبایست به صورت POST ارسال گردد و پاسخها به صورت HTTP با ساختار JSON برای شما بازگردانده میشوند. در صورت صحیح بودن درخواست، با وضعیت کدهای 200 و 201 به شما پاسخ داده خواهد شد و در صورت خطا، با وضعیتهای مشخصشده در جدول خطاها پاسخ داده میشود. در صورت بروز خطا دو مقدار error_no برای کد وضعیت خطا و error_message برای پیام خطای رویداده با ساختار JSON پاسخ داده میشود.
آدرس پایه برای ارسال درخواست در زیر قرار گرفتهاست :
import requests
import json
url = "https://mellipay.ir/api/v1/payment/"
payload = json.dumps({
your data
})
headers = {
'M-Api-Key': '****************',
'M-Sec-Key': '****************',
'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/v1/payment/');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
'follow_redirects' => TRUE
));
$request->setHeader(array(
'M-Api-Key' => '***********',
'M-Sec-Key' => '***********',
'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/v1/payment/");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("M-Api-Key", "***********");
request.AddHeader("M-Sec-Key", "****************");
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/v1/payment/
برای هر تراکنش، بایستی ابتدا آن را ایجاد نمایید. با استفاده از آدرس بالا و اطلاعات خواسته شده، میتوانید درخواست ساخت تراکنش را به API بدهید.
{
"TransactionId": 12345,
"Amount":1000000,
"CallBackUrl":"https://your.site/callback/url"
}
توضیحات متغیرها در جدول زیر قابل مشاهدهاست:
متغیر | نوع | ضروری | تعریف |
---|---|---|---|
TransactionId | عدد صحیح | بله |
یک شناسه عددی است که از طرف پذیرنده برای ما ارسال میشود و در دفعات بعد باید از آن استفاده کند. |
Amount | عدد صحیح | بله |
مبلغ مورد نظر به ریال که بایستی بین 100000 و 1000000000 باشد. |
CallBackUrl | رشته یا متن | بله |
آدرسی است که اطلاعات مربوطه، در پاسخ به انجام تراکنش، به آن ارسال میشود و بایستی در همان URL باشد که درگاه پرداخت ساخته شدهاست. |
در پاسخ به این درخواست، در صورت ساخته شدن تراکنش، کد درخواست 201 (به معنای ایجاد شدن تراکنش) برای شما ارسال میگردد که اطلاعات برگشتی به صورت زیر خواهد بود. در غیر این صورت، کدهای درخواست مربوط به خطا، همراه با دادههای آن ارسال خواهد شد.
متغیر | نوع | تعریف |
---|---|---|
status | عدد صحیح |
مقدار عددی وضعیت است که در جدول خطاها در پایین صفحه موجود است. |
error_no | عدد صحیح |
شماره خطا است که زیر مجموعهای از خطاهای اصلی میباشد و توضیح آن در جدول خطاها آمدهاست. |
error_message | رشته یا متن |
پیامی مبنی بر توضیح خطا است. |
Mellipay_Tracking_Code | رشته یا متن |
کدی که از طرف ما برای پذیرنده ارسال میشود. همچنین این کد، برای پیگیری تراکنش و ارسال کاربر به درگاه پرداخت استفاده میشود. |
TransactionId | عدد صحیح |
کدی که از پذیرنده در زمان درخواست، دریافت شدهاست. |
link | رشته یا متن |
لینک ارسال کاربر به درگاه پرداخت میباشد. |
import requests
import json
url = "https://mellipay.ir/api/v1/payment/"
payload = json.dumps({
"TransactionId": 1,
"Amount": 1000000,
"CallBackUrl": "https://yoursite.tld/callbackurl/"
})
headers = {
'M-Api-Key': '****************',
'M-Sec-Key': '****************',
'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/v1/payment/');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
'follow_redirects' => TRUE
));
$request->setHeader(array(
'M-Api-Key' => '***********',
'M-Sec-Key' => '***********',
'Content-Type' => 'application/json'
));
$request->setBody('{\n "TransactionId": 1,\n "Amount":1000000,\n "CallBackUrl":"https://yoursite.tld/callbackurl/"\n}');
try {
$response = $request->send();
if ($response->getStatus() == 201) {
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/v1/payment/");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("M-Api-Key", "***********");
request.AddHeader("M-Sec-Key", "****************");
request.AddHeader("Content-Type", "application/json");
var body = @"{" + "\n" +
@" ""TransactionId"": 1," + "\n" +
@" ""Amount"":1000000," + "\n" +
@" ""CallBackUrl"":""https://yoursite.tld/callbackurl/""" + "\n" +
@"}";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
» ارسال کاربر به درگاه پرداخت
پس از ساخت تراکنش، یک آدرس دریافت میکنید که حاوی آدرس بالا همراه با توکن آن تراکنش است. در وبسایت خود، بایستی کاربر را به این آدرس راهنمایی کنید تا به درگاه پرداخت برود. در انتها، پس از پایان تراکنش، نتیجهی آن برای شما از طریق آدرسی که در مرحله قبل به API دادهاید؛ ارسال میگردد. نتیجهی ارسالشده در صورت انجام صحیح تراکنش، با کد درخواست 200 ارسال خواهد شد. در صورت تکراری بودن تراکنشها، پاسخ به صورت کد 200 و با پیغام تراکنش تکراری برای آدرس شما ارسال میگردد. این خطا ممکن است در اثر کپی کردن لینک و استفاده چند باره از آن رخ دهد.
<form action="https://mellipay.ir/api/v1/payment/start/xxxxxxxxxxxx/" method="post" id="toGateWay">
<input type="hidden" name="token" value="{Mellipay_Tracking_Code}">
</form>
<script>
document.getElementById("toGateWay")).submit();
</script>
» برگشت از درگاه
پس از انجام تراکنش، با هر وضعیتی، کاربر به آدرسی که در ابتدای ساخت تراکنش، معرفی کردهاید؛ برگشت داده میشود و اطلاعات زیر به صورت جی سان ارسال میگردد.
{
"Status":1,
"RefNum":1,
"CustomerRefNum":1,
"tracking_code":1,
"transactionAmount":100000,
"CardHashPan":xxxxxxxxxxxxxxxxxxxxxxxxxx,
"CardMaskPan": 1234xxxxxxxx1234,
"datefield":1614253614
}
در جدول زیر، توضیحات هر یک از پارامترها آمدهاست:
پارامتر ها | نوع | توضیح |
---|---|---|
Status | عدد |
عدد 3 به معنی موفق و عدد ۷ به معنی انصراف از پرداخت میباشد. |
RefNum | عدد |
شناسهی تراکنشی که در ابتدا ارسال کردهاید. |
CustomerRefNum | عدد | کد رهگیری تراکنش |
tracking_code | رشته حروف |
کد رهگیری که پس از ساخت تراکنش از سمت ملّی پی به شما داده شدهاست. |
transactionAmount | عدد | مبلغ اصلی تراکنش |
CardHashPan | رشته حروف | مقدار هش شده کارت بانکی |
CardMaskPan | رشته حروف | مقدار پوشیده شده شماره کارت بانکی |
datefield | عدد | زمان انجام تراکنش |
درصورتیکه وضعیت تراکنش، عدد 3 بود؛ به این معنی است که تراکنش به درستی انجام شده و نیاز به تایید دارد.
این نکته را به خاطر بسپارید که تمامی تراکنشهایی که با موفقیت انجام میشوند؛ ۱۰ دقیقه فرصت دارند تا تایید شوند؛ در غیر این صورت، تراکنش، برگشت خواهد خورد. تا زمانیکه وضعیت تراکنش عدد ۱ نباشد؛ هیچ پولی به حساب شما واریز نمیشود.
در مرحله بعد تایید تراکنش آمدهاست.
» تایید تراکنش
بعد از انجام هر تراکنش، نتیجهی آن برای شما ارسال میشود. درصورتیکه نتیجه مبنی بر موفق بودن تراکنش بود؛ بایستی شما این تراکنش را حداکثر تا 15 دقیقه تایید کنید. در غیر این صورت، تراکنش انجام شده به کارت کاربر برگشت داده میشود. برای تایید با استفاده از آدرس تعریف شده، اطلاعات زیر را ارسال نمایید
{
'Mellipay_Tracking_Code' : "xxxxxxx",
'TransactionId': 12345
}
که در آن:
پارامتر ها | نوع | توضیح |
---|---|---|
Mellipay_Tracking_Code | رشته |
کدی است که از طرف API بعد از انجام تراکنش برای شما ارسال شدهاست. |
TransactionId | عدد |
شناسهای است که در ابتدای ساخت تراکنش برای ما ارسال کردهاید. |
در صورت تایید تراکنش، اطلاعات زیر به شما پاسخ داده میشود:
پارامتر ها | نوع | توضیح |
---|---|---|
status | عدد | وضعیت تراکنش |
transactionid | عدد | شناسه تراکنش |
tracking_code | رشته | کد تراکنش |
Amount | عدد | مبلغ |
cardHashPan | رشته | کد هش شده شماره کارت واریز کننده |
cardMaskPan | رشته | شماره کارت واریز کننده به صورت پوشیده شده چند عدد |
datefield | عدد |
زمان انجام تراکنش که تا 10 دقیقه بعد از آن فرصت دارید؛ تراکنش را تایید کنید. |
import requests
import json
url = "https://mellipay.ir/api/v1/payment/verify/"
payload = json.dumps({
"TransactionId": 1,
"Mellipay_Tracking_Code": "xxxxxxxx"
})
headers = {
'M-Api-Key': '****************',
'M-Sec-Key': '****************',
'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/v1/payment/verify/');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
'follow_redirects' => TRUE
));
$request->setHeader(array(
'M-Api-Key' => '******',
'M-Sec-Key' => '******',
'Content-Type' => 'application/json'
));
$request->setBody('{\n "TransactionId": 1,\n "Mellipay_Tracking_Code":"xxxxxxxx"\n}');
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/v1/payment/verify/");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("M-Api-Key", "******");
request.AddHeader("M-Sec-Key", "******");
request.AddHeader("Content-Type", "application/json");
var body = @"{" + "\n" +
@" ""TransactionId"": 1," + "\n" +
@" ""Mellipay_Tracking_Code"":""xxxxxxxx""" + "\n" +
@"}";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
» پیگیری تراکنش نامعلوم
درصورتیکه تراکنشی را ایجاد کرده و کاربر را به سمت آدرس پرداخت هدایت کردهاید اما جوابی دریافت نکردهاید؛ میتوانید از لینک بالا استفاده کرده و اطلاعات تراکنش را در صورت موجود بودن، دریافت کنید. اگر کاربر، تراکنش را انجام داده باشد؛ اطلاعات بهروز شده و برای شما ارسال میگردد. در غیر این صورت، خطای 400 به شما برگشت داده خواهد شد که در پیام آن، علت خطا مشخص شدهاست. برای این کار، به اطلاعات زیر نیاز است:
{
'Mellipay_Tracking_Code' : "xxxxxxx",
'TransactionId': 12345
}
import requests
import json
url = "https://mellipay.ir/api/v1/payment/inquiry/"
payload = json.dumps({
"TransactionId": "-",
"Mellipay_Tracking_Code": "xxxxxxxxxxx"
})
headers = {
'M-Api-Key': '**********',
'M-Sec-Key': '**********',
'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/v1/payment/inquiry/');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
'follow_redirects' => TRUE
));
$request->setHeader(array(
'M-Api-Key' => '**********',
'M-Sec-Key' => '**********',
'Content-Type' => 'application/json'
));
$request->setBody('{\n "TransactionId": "-",\n "Mellipay_Tracking_Code":"xxxxxxxxxxx"\n}');
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/v1/payment/inquiry/");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("M-Api-Key", "**********");
request.AddHeader("M-Sec-Key", "**********");
request.AddHeader("Content-Type", "application/json");
var body = @"{" + "\n" +
@" ""TransactionId"": ""-""," + "\n" +
@" ""Mellipay_Tracking_Code"":""xxxxxxxxxxx""" + "\n" +
@"}";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
» لیست خطاها
کد درخواست | کد وضعیت | وضعیت | توضیحات |
---|
» افزونه ها و پلاگین ها
عنوان | درباره | آخرین بروزرسانی | لینک ها |
---|---|---|---|
مستندات اتصال به وب سرویس | فایل مستندات استفاده از وب سرویس پرداخت یاری ملی پی |
2 سال،3 ماه پیش | دانلود |
افزونه WHMCS | نسخه 1.0.2 افزونه پنل مدیریت سرور و دامنه WHMCS |
1 سال،10 ماه پیش | دانلود |
افزونه ووکامرس | افزونه درگاه پرداخت ملی پی برای ووکامرس نسخه 1.0.2 |
1 سال،10 ماه پیش | دانلود |
افزونه گراویتی فرم | افزونه گراویتی فرم برای وردپرس |
1 سال،10 ماه پیش | دانلود |
نمونه کد postman | فایل نمونه ارسال درخواست توسط postman |
1 سال،10 ماه پیش | دانلود |