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

ملّی پی

ورود / ثبت نام

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

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

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

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

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

9 ماه،1 هفته پیش دانلود
نمونه کد postman

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

9 ماه،1 هفته پیش دانلود