» مقدمه

این راهنما، نحوه‌ی اتصال برنامه‌نویسان به درگاه‌های پرداخت ملّی پی از طریق وب سرویس را توضیح می‌دهد. وب سرویس ملّی پی به روش 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 پاسخ داده می‌شود.

آدرس پایه برای ارسال درخواست در زیر قرار گرفته‌است :

https://mellipay.ir/api/v1/

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 و با پیغام تراکنش تکراری برای آدرس شما ارسال می‌گردد. این خطا ممکن است در اثر کپی کردن لینک و استفاده چند باره از آن رخ دهد.

html

<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 به شما برگشت داده خواهد شد که در پیام آن، علت خطا مشخص شده‌است. برای این کار، به اطلاعات زیر نیاز است: