ملّی پی | پرداخت‌یار شبکه شاپرک بانک مرکزی

ملّی پی

ورود / ثبت نام

مستندات فنی نسخه ۱ (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);

» لیست خطاها

کد درخواست کد وضعیت وضعیت توضیحات

» افزونه ها و پلاگین ها

عنوان درباره آخرین بروزرسانی لینک ها
مستندات اتصال به وب سرویس

فایل مستندات استفاده از وب سرویس پرداخت یاری ملی پی

1 سال،5 ماه پیش دانلود
افزونه WHMCS

نسخه 1.0.2 افزونه پنل مدیریت سرور و دامنه WHMCS

1 سال،1 ماه پیش دانلود
افزونه ووکامرس

افزونه درگاه پرداخت ملی پی برای ووکامرس نسخه 1.0.2

1 سال،1 ماه پیش دانلود
افزونه گراویتی فرم

افزونه گراویتی فرم برای وردپرس

1 سال،1 ماه پیش دانلود
نمونه کد postman

فایل نمونه ارسال درخواست توسط postman

1 سال،1 ماه پیش دانلود