مستندات API درگاه پرداخت نوبیتکس
درگاه پرداخت نوبیتکس یک درگاه پرداخت رمز ارزی است. به اینصورت که کاربران شما میتوانند توسط ارزهای رمز پایه مثل بیتکوین، ریپل،لایت کوین و ... پول خود را پرداخت کنند.
برای کار با این درگاه و اتصال آن به وبسایت و یا اپلیکیشن خود، میتوانید از این داکیومنت استفاده کنید. داکیومنت پیش رو، تمامی مراحل اتصال، پرداخت و تایید را قدم به قدم به شما توضیح خواهد داد.
در صورت ناقص یا مبهم بودن توضیحات APIها یا هرگونه پیشنهاد دیگر در این خصوص، میتوانید در مخزن گیتهاب مستندات نوبیتکس API
مورد (issue) جدیدی را ایجاد نمایید یا مستقیما روی این لینک کلیک کنید و مشکل مد نظرتان را با ما در میان بگذارید.
احراز هویت
برای استفاده از APIهای درگاه شما نیاز به دو متغیر
api
و
api-secret
دارید.این دو مقدار داخل پنل نوبیتکس شما قرار داشته و بعد از تایید درخواست شما برای دریافت درگاه پرداخت در اختیار شما قرار خواهد گرفت. در واقع با این دو مقدار نوبیتکس متوجه میشود که درخواست از سمت شما بوده است یا نه. این دو مقدار، بسیار حساس بوده و باید در حفظ و نگه داری آن ها بکوشید.
زمان ارسال درخواست، مقدار api
باید در body درخواست موجود باشد.
api-secret
در هیچ درخواستی ارسال نمیشود و برای احراز اصالت جواب مورد استفاده قرار میگیرد. در واقع برای اینکه شما متوجه شوید که جواب نهایی از سمت نوبیتکس بوده یا نه. این مورد در بخش دیگر به صورت کامل توضیح داده خواهد شد.
مراحل اتصال به درگاه
برای اتصال وبسایت خود به درگاه رمزارز نوبیتکس، شما بایستی چهار مرحلهی زیر را انجام دهید.
۱- ارسال درخواست ساخت صورتحساب
برای ایجاد صورتحساب و توکن پرداخت برای کاربر خود به این صورت پارامترهای مربوطه را با متد POST
ارسال فرمایید:
curl 'https://api.nobitex.ir/pg/send/' \
-X POST \
-H "content-type: application/json" \
--data '{"api":"DemoApiKey","amount":1000000,"callbackURL":"https://www.nobitex.ir/app/callback-gateway/", "currencies": "btc,ltc"}'
import requests
url = "https://api.nobitex.ir/pg/send/"
payload = "{\"api\":\"DemoApiKey\",\"amount\":1000000,\"callbackURL\":\"https://www.nobitex.ir/app/callback-gateway/\", \"currencies\": \"btc,ltc\"}"
headers = {
'content-type': "application/json",
'cache-control': "no-cache",
}
response = requests.request("POST", url, data=payload, headers=headers)
print(response.text)
var settings = {
"async": true,
"crossDomain": true,
"url": "https://api.nobitex.ir/pg/send/",
"method": "POST",
"headers": {
"content-type": "application/json",
"cache-control": "no-cache",
},
"data": "{\"api\":\"DemoApiKey\",\"amount\":1000000,\"callbackURL\":\"https://www.nobitex.ir/app/callback-gateway/\", \"currencies\": \"btc,ltc\"}"
}
$.ajax(settings).done(function (response) {
console.log(response);
});
var client = new RestClient("https://api.nobitex.ir/pg/send/");
var request = new RestRequest(Method.POST);
request.AddHeader("cache-control", "no-cache");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\"api\":\"DemoApiKey\",\"amount\":1000000,\"callbackURL\":\"https://www.nobitex.ir/app/callback-gateway/\", \"currencies\": \"btc,ltc\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
<?php
$request = new HttpRequest();
$request->setUrl('https://api.nobitex.ir/pg/send/');
$request->setMethod(HTTP_METH_POST);
$request->setHeaders(array(
'cache-control' => 'no-cache',
'content-type' => 'application/json'
));
$request->setBody('{"api":"DemoApiKey","amount":1000000,"callbackURL":"https://www.nobitex.ir/app/callback-gateway/", "currencies": "btc,ltc"}');
try {
$response = $request->send();
echo $response->getBody();
} catch (HttpException $ex) {
echo $ex;
}
require 'uri'
require 'net/http'
url = URI("https://api.nobitex.ir/pg/send/")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["cache-control"] = 'no-cache'
request.body = "{\"api\":\"DemoApiKey\",\"amount\":1000000,\"callbackURL\":\"https://www.nobitex.ir/app/callback-gateway/\", \"currencies\": \"btc,ltc\"}"
response = http.request(request)
puts response.read_body
POST /pg/send/ HTTP/1.1
Host: api.nobitex.ir
Content-Type: application/json
cache-control: no-cache
{"api":"DemoApiKey","amount":1000000,"callbackURL":"https://www.nobitex.ir/app/callback-gateway/", "currencies": "btc,ltc"}
در صورت فراخوانی درست، پاسخ به این صورت خواهد بود:
{
"status": "success",
"token": "e9282e56c83f93eb077043e5ad8b6cf5b3ff7568"
}
در صورت رخداد هر گونه خطا، پاسخ به این صورت فرستاده میشود:
{
"status": "failed",
"code": ERROR_CODE,
"message": ERROR_MESSAGE
}
برای اطلاعات بیشتر به بخش خطاها مراجعه کنید.
آدرس
POST API_URL/pg/send
پارامترها
پارامتر | نوع | پیشفرض | توضیحات | نمونه |
---|---|---|---|---|
api | string | الزامی | API key | DemoApiKey |
amount | integer | الزامی | مقدار ریالی صورتحساب حداقل ۱۰۰۰۰ ریال | 1000000 |
callbackURL | string | الزامی | لینک برگشت بعد از پرداخت(حتما schema url آورده شود) باید با آدرس تایید شده بر روی یک دامنه باشد. | https://Your_Callback_URL |
factorNumber | string | اختیاری | شماره فاکتور برای نشاندادن به مشتری | Nobitex1234 |
mobile | string | اختیاری | شمارهی همراه مشتری | 09123456789 |
description | string | توضیحات(حداکثر ۲۵۵ کاراکتر) | اختیاری | Test Payment with Nobitex |
currencies | string | btc,ltc |
لیست رمزارزهای مورد قبول برای پرداخت. آپشنهای مورد قبول: btc و ltc . برای انتخاب چند روش پرداخت انتخابها را با ویرگول جدا نمایید. |
btc |
۲- انتقال به درگاه
در صورت موفقیتآمیز بودن مرحلهی قبل، به شما یک {{ token }}
داده میشود و شما بایستی کاربر را به درگاه ریدایرکت کنید.
برای این کار توکن دریافت شده {{ token }}
را همانند زیر در انتهای URL قرار داده و کاربر را به این آدرس ریدایرکت فرمایید.
آدرس
GET https://nobitex.ir/app/paygate/{{ token }}
۳- بازگشت از درگاه
کاربر در زمان بازگشت از درگاه، به پارامتر callbackURL در مرحلهی اول بهصورت زیر ریدارکت میشود. اگر مقدار status برابر با 1 بود، تراکنش موفقیتآمیز بوده است.
آدرس
GET https://Your-Callback_URL?status={transaction_status}&token={token}
۴- تایید پرداخت
در صورت بازگشت کاربر با status
مساوی ۱
بایستی احراز اصالت این پرداخت صورت بگیرد. برای تایید پرداخت کاربر، شما بایستی درخواست خود را با آدرس و پارامترهای زیر ارسال فرمایید:
curl 'https://api.nobitex.ir/pg/verify/' \
-X POST \
-H "content-type: application/json" \
--data '{"api":"DemoApiKey","token":"e9282e56c83f93eb077043e5ad8b6cf5b3ff7568"}'
import requests
url = "https://api.nobitex.ir/pg/verify/"
payload = "{\"api\":\"DemoApiKey\",\"token\":\"e9282e56c83f93eb077043e5ad8b6cf5b3ff7568\"}"
headers = {
'content-type': "application/json",
'cache-control': "no-cache",
}
response = requests.request("POST", url, data=payload, headers=headers)
print(response.text)
var settings = {
"async": true,
"crossDomain": true,
"url": "https://api.nobitex.ir/pg/verify/",
"method": "POST",
"headers": {
"content-type": "application/json",
"cache-control": "no-cache",
},
"data": "{\"api\":\"DemoApiKey\",\"token\":\"e9282e56c83f93eb077043e5ad8b6cf5b3ff7568\"}"
}
$.ajax(settings).done(function (response) {
console.log(response);
});
var client = new RestClient("https://api.nobitex.ir/pg/verify/");
var request = new RestRequest(Method.POST);
request.AddHeader("cache-control", "no-cache");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\"api\":\"DemoApiKey\",\"token\":\"e9282e56c83f93eb077043e5ad8b6cf5b3ff7568\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
<?php
$request = new HttpRequest();
$request->setUrl('https://api.nobitex.ir/pg/verify/');
$request->setMethod(HTTP_METH_POST);
$request->setHeaders(array(
'cache-control' => 'no-cache',
'content-type' => 'application/json'
));
$request->setBody('{"api":"DemoApiKey","token":"e9282e56c83f93eb077043e5ad8b6cf5b3ff7568"}');
try {
$response = $request->send();
echo $response->getBody();
} catch (HttpException $ex) {
echo $ex;
}
require 'uri'
require 'net/http'
url = URI("https://api.nobitex.ir/pg/verify/")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["cache-control"] = 'no-cache'
request.body = "{\"api\":\"DemoApiKey\",\"token\":\"e9282e56c83f93eb077043e5ad8b6cf5b3ff7568\"}"
response = http.request(request)
puts response.read_body
POST /pg/verify/ HTTP/1.1
Host: api.nobitex.ir
content-type: application/json
cache-control: no-cache
{"api":"DemoApiKey","token":"e9282e56c83f93eb077043e5ad8b6cf5b3ff7568"
در صورت فراخوانی درست، پاسخ به این صورت خواهد بود:
{
{
'status': "success" [string],
'amount': Amount in rial [integer],
'cryptoAmount': Exchanged amount in crypto [float],
'txHash': Hash of (token, amount, api-secret) [string],
'factorNumber': Factor number (optional) [string],
'mobile': Mobile number (optional) [string],
'description': Description (optional) [string],
}
}
در صورت رخداد هر گونه خطا، پاسخ به این صورت فرستاده میشود:
{
"status": "failed",
"code": ERROR_CODE,
"message": ERROR_MESSAGE
}
برای اطلاعات بیشتر به بخش خطاها مراجعه کنید.
آدرس
POST API_URL/pg/verify/
پارامترها
پارامتر | نوع | پیشفرض | توضیحات | نمونه |
---|---|---|---|---|
api | string | الزامی | API key | DemoApiKey |
token | string | الزامی | Token | e9282e56c83f93eb077043e5ad8b6cf5b3ff7568 |
تایید صحت پاسخ نوبیتکس
پس از تایید پرداخت در مرحله 4 بخش قبل، جواب درخواست باید از سمت نوبیتکس باشد. حملاتی تحت عنوان "مرد میانی" یا به اختصار "MIMT" وجود دارد که ممکن است جواب در خواست از سمت دیگری غیر از نوبیتکس برای شما ارسال شود.
برای جلوگیری از این حملات، و تشخیص تمامی درخواستهای غیر معتبر دیگر، شما باید مقدار txHash موجود در پاسخ سرور را به این صورت مقایسه کنید:
مقدار txHash برابر است با (md5(token + str(amount) + api-secret)
توجه شود که ترتیب قرارگیری مقادیر مهم میباشد.
شبکه اصلی و تستنت
بهمنظور فراهم کردن بستر تست برای توسعهدهندگان، شبکه تستنت درگاه نوبیتکس در کنار شبکهی اصلی طراحی شدهاست که به شبکههای تستنت رمزارزها متصل است. اگر میخواهید بدون نیاز به انتقال رمزارز یا پول واقعی کد درگاه پرداخت را تست کنید، از شبکه تستنت درگاه پرداخت نوبیتکس استفاده کنید. در واقع شما با استفاده از شبکه تست نت نوبیتکس میتوانید(مثلا اگر درگاه شما بیتکوین میپذیرد) از شبکه تست نت بیتکوین، پرداخت کنید. شبکه تست نت بیتکوین کوین هایی را در اختیار شما قرار میدهد که ارزش پولی نداشته و برای تست به وجود آمده اند. بدیهی است که درگاه تست نوبیتکس با شبکه های واقعی کار نکرده و فقط با شبکه های تست نت کوین مورد نظر کار خواهد کرد.
آدرسها در شبکه تستنت
API_URL = https://testnetapi.nobitex.ir
SITE_URL = https://testnet.nobitex.ir
آدرسها در شبکه اصلی
API_URL = https://api.nobitex.ir
SITE_URL = https://nobitex.ir
توضیح پیامهای خطا
کد خطا | متن خطا | توضیحات |
---|---|---|
1- |
API parameter is required | پارامتر api ارسال نشده است |
2- |
API not found | کاربری با مشخصات شما یافت نشده است. |
3- |
API is restricted | شما در سیستم محدود شدهاید. |
4- |
API is invalid | پارامتر API با فرمت نادرستی ارسال شدهاست. |
5- |
Amount parameter is required | پارامتر amount ارسال نشده است |
6- |
Amount must be integer | پارامتر amount باید int باشد |
7- |
Amount min value is 10000 rls | پارامتر amount باید از ۱۰۰۰۰ بیشتر باشد |
8- |
callbackURL parameter is required | پارامتر callbackURL ارسال نشده است |
9- |
callbackURL CORPS error | پارامتر callbackURL با دامنه ثبت شده برای شما مطابقت ندارد. |
10- |
callbackURL format is invalid. Please use this format: https://domain.com/path/to/redirect | پارامتر callbackURL با فرمت درستی ارسال نشدهاست |
11- |
Description must be less than 255 character | پارامتر description بایستی کمتر از ۲۵۵ کاراکتر باشد |
21- |
Invalid token | توکن فرستاده شده، اشتباه است |
22- |
Token not found | توکن فرستاده شده یافت نمیشود |
23- |
Token is required | پارامتر token نیاز است. |
31- |
Unverified | پرداخت معتبر نیست |
32- |
Verified before | پرداخت قبلا تایید شدهاست |
41- |
Invalid currency | رمزارز فرستادهشده معتبر نیست |
پلاگینها
در این بخش میتوانید لیست پلاگینهای نوشته شده درگاه نوبیتکس را مشاهده و مستندات آن را مطالعه بفرمایید.
وردپرس
ووکامرس
مستندات درگاه نوبیتکس برای فروشگاه ساز ووکامرس و همچنین لینک دانلود پلاگین از طریق لینک زیر قابل دسترسی میباشد. مستندات ووکامرس
مبدل قیمت
مبدل قیمت نوبیتکس، یک پلاگین مختص فروشگاه ساز ووکامرس بوده که میتوانید با استفاده از آن قیمت تمام محصولات خود را به ارزهای دیجیتال تبدیل کنید. مستندات پلاگین مبدل قیمت