راهنمای وب سرویس

مقدمه

این راهنما نحوه اتصال برنامه نویسان به درگاه های پرداخت از طریق API تاباپی را توضیح میدهد.
شما می‌توانید نمونه کدها را در ستون سمت چپ صفحه مشاهده کنید و درصورت تمایل می‌توانید از طریق تب های بالای صفحه،
نمونه کدهای زبان های برنامه نویسی مختلف را انتخاب کنید.

احراز هویت

برای استفاده از API های تاباپی نیاز به یک merchant است.
شما می‌توانید به داشبورد خود در تاباپی رفته و در بخش درگاه پرداخت، مرچنت درگاه ایجاد شده خود را مشاهده و آن را تحت عنوان Authorization در header، برای ما ارسال نمایید:

Authorization: Bearer aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
توضیحات ضروری نوع پارامتر
کلید منحصر بفرد جهت احراز هویت به طول 36 کاراکتر بله string Authorization

ایجاد تراکنش

با استفاده از آدرس زیر می‌توانید یک تراکنش در محیط تست ایجاد کنید.
محیط تست https://api.tabapay.ir/v1/sandbox/create
با استفاده از آدرس زیر می‌توانید یک تراکنش در محیط عملیاتی ایجاد کنید.
محیط عملیاتی https://api.tabapay.ir/v1/create
پارامترهای مورد نیاز
توضیحات ضروری نوع پارامتر
مبلغ مورد نظر بین 100,000 ریال تا 500,000,000 ریال باشد بله number amount
آدرس بازگشت به سایت پذیرنده به طول حداکثر 2048 کاراکتر بله string callbackURL
تلفن همراه پرداخت کننده به طول 11 کاراکتر مانند 09123456789 خیر string mobile
پست الکترونیک پرداخت کننده به طول حداکثر 255 کاراکتر خیر string email
نام و نام خانوادگی پرداخت کننده به طول حداکثر 255 کاراکتر خیر string name
ارسال پیامک به پرداخت کننده در صورتی که مقدار 1 ارسال شود خیر number sms
شماره کارت مشتری به طول 16 کارکتر که در صورت ارسال با شماره کارت پرداخت کننده تطابق داده می شود خیر number cardNumber
مقادیر ارسالی دلخواه تراکنش به طول حداکثر 500 کاراکتر به صورت جیسون خیر string additionalData
کد ملی پرداخت کننده به طول حداکثر 10 کاراکتر خیر number nationalCode
توضیح تراکنش به طول حداکثر 300 کاراکتر خیر string description
پاسخ موفق {
"responseCode" : 1,
"status": "success",
"token": "05d3f1d4-82e1-11ee-8f0e-d82429616d01",
"url": "https://api.tabapay.ir/pay/05d3f1d4-82e1-11ee-8f0e-d82429616d01"
}
پاسخ موفق (محیط تست) {
"responseCode" : 1,
"status": "success",
"token": "05d3f1d4-82e1-11ee-8f0e-d82429616d01",
"url": "https://api.tabapay.ir/sandbox/pay/05d3f1d4-82e1-11ee-8f0e-d82429616d01"
}
پاسخ ناموفق {
"status": "error",
"responseCode": -33,
"message": "درگاه پرداخت پیدا نشد"
}
برای مشاهده تمامی خطاها به بخش لیست خطاها مراجعه کنید : لیست کدهای پاسخ
  • PHP
  • Python
  • NodeJS
  • C#
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.tabapay.ir/v1/create',
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 => array('amount' => '10000','callbackURL' => 'https://test.ir','mobile' => '09900000000','email' => 'info@test.ir'),
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
import requests
url = "https://api.tabapay.ir/v1/create"
payload = {'amount': '10000',
'callbackURL': 'https://test.ir',
'mobile': '09900000000',
'email': 'info@test.ir'}
files=[
]
headers = {
'Authorization': 'Bearer aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'
}
response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)
var request = require('request');
var options = {
'method': 'POST',
'url': 'https://api.tabapay.ir/v1/create',
'headers': {
'Authorization': 'Bearer aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'
},
formData: {
'amount': '10000',
'callbackURL': 'https://test.ir',
'mobile': '09900000000',
'email': 'info@test.ir'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.tabapay.ir/v1/create");
request.Headers.Add("Authorization", "Bearer aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee");
var content = new MultipartFormDataContent();
content.Add(new StringContent("10000"), "amount");
content.Add(new StringContent("https://test.ir"), "callbackURL");
content.Add(new StringContent("09900000000"), "mobile");
content.Add(new StringContent("info@test.ir"), "email");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

ایجاد تراکنش به همراه صدور فاکتور

با استفاده از آدرس زیر می‌توانید یک تراکنش در محیط تست ایجاد کنید.
محیط تست https://api.tabapay.ir/v1/sandbox/create
با استفاده از آدرس زیر می‌توانید یک تراکنش در محیط عملیاتی ایجاد کنید.
محیط عملیاتی https://api.tabapay.ir/v1/create
پارامترهای مورد نیاز
توضیحات ضروری نوع پارامتر
مبلغ مورد نظر بین 100,000 ریال تا 500,000,000 ریال باشد بله number amount
آدرس بازگشت به سایت پذیرنده به طول حداکثر 2048 کاراکتر بله string callbackURL
تلفن همراه پرداخت کننده به طول 11 کاراکتر مانند 09123456789 بله string mobile
پست الکترونیک پرداخت کننده به طول حداکثر 255 کاراکتر خیر string email
نام و نام خانوادگی پرداخت کننده به طول حداکثر 255 کاراکتر بله string name
آدرس پرداخت کننده به طول حداکثر 255 کاراکتر بله string address
شماره اقتصادی پرداخت کننده به طول حداقل 10 تا 15 کاراکتر بله string economicCode
نوع پرداخت کننده حقیق/حقوقی شامل [Natural, Legal] بله string buyerType
شناسه محصول در پروفایل مؤدیان متصل به درگاه حداکثر 255 کاراکتر بله json invoiceProductId
ارسال پیامک به پرداخت کننده در صورتی که مقدار 1 ارسال شود خیر number sms
شماره کارت مشتری به طول 16 کارکتر که در صورت ارسال با شماره کارت پرداخت کننده تطابق داده می شود خیر number cardNumber
مقادیر ارسالی دلخواه تراکنش به طول حداکثر 500 کاراکتر به صورت جیسون خیر string additionalData
کد ملی پرداخت کننده به طول حداکثر 10 کاراکتر بله number nationalCode
توضیح تراکنش به طول حداکثر 300 کاراکتر خیر string description
توضیحات اضافه
جهت استفاده از قابلیت صدور خودکار فاکتور مؤدیان لازم است اطلاعات کالا یا خدمات فروخته شده را در فیلد invoiceProductId ارسال نمایید.

ساختار این فیلد به صورت زیر می‌باشد:
invoiceProductId => {مجموع مبلغ مربوط به هر شناسه کالا : "شناسه کالا یا خدمت"}

توجه داشته باشید که در بسیاری از موارد ممکن است چندین محصول در سایت شما به یک شناسه کالا در سامانه مؤدیان متصل باشند. در این حالت لازم است مجموع مبلغ تمام محصولاتی که به یک شناسه کالا مربوط هستند محاسبه شده و در قالب یک مقدار در این فیلد ارسال گردد.

مثال:
فرض کنید در سایت شما دو شناسه کالا در سامانه مؤدیان تعریف شده است:
شناسه 1234 برای «پوشاک»
شناسه 5678 برای «کالای دیجیتال»

ممکن است در سایت شما چندین محصول مختلف به هر یک از این شناسه‌ها متصل باشند. برای مثال:
چند محصول پوشاک → متصل به شناسه 1234
چند محصول کالای دیجیتال → متصل به شناسه 5678

حال اگر سبد خرید مشتری شامل 5 محصول مختلف باشد و مجموع مبالغ آن‌ها به صورت زیر باشد:
محصولات مربوط به پوشاک: 100,000 ریال
محصولات مربوط به کالای دیجیتال: 50,000 ریال

در این حالت مقدار ارسالی باید به شکل زیر باشد:
{100000 : "1234", 50000 : "5678"}

به عبارت دیگر، ابتدا باید مبلغ محصولات بر اساس شناسه کالا تجمیع شده و سپس در قالب ساختار فوق ارسال گردد.

همچنین در صورتی که در لیست شناسه‌های ارسال شده، کالا یا خدمتی به صورت نوع یک تعریف شده باشد، ارسال اطلاعات مشتری شامل فیلدهای زیر الزامی خواهد بود در غیر این صورت اختیاری می‌باشد:
mobile ، name ، address ، economicCode ، nationalCode

پاسخ موفق {
"responseCode" : 1,
"status": "success",
"token": "05d3f1d4-82e1-11ee-8f0e-d82429616d01",
"url": "https://api.tabapay.ir/pay/05d3f1d4-82e1-11ee-8f0e-d82429616d01"
}
پاسخ موفق (محیط تست) {
"responseCode" : 1,
"status": "success",
"token": "05d3f1d4-82e1-11ee-8f0e-d82429616d01",
"url": "https://api.tabapay.ir/sandbox/pay/05d3f1d4-82e1-11ee-8f0e-d82429616d01"
}
پاسخ ناموفق {
"status": "error",
"responseCode": -33,
"message": "درگاه پرداخت پیدا نشد"
}
برای مشاهده تمامی خطاها به بخش لیست خطاها مراجعه کنید : لیست کدهای پاسخ
  • PHP
  • Python
  • NodeJS
  • C#
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.tabapay.ir/v1/create',
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 => array('amount' => '100000',
'callbackURL' => 'https://test.ir',
'mobile' => '09900000000',
'email' => 'info@test.ir',
'invoiceProductId' => {"1234":10000,"5678":90000},
'buyerType' => 'Natural',
'economicCode' => '10802463540001',
'address' => 'آدرس پذیرنده',
'name' => 'نام و نام خانوادگی پذیرنده',
'nationalCode' => '1080246354')
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
import requests
url = "https://api.tabapay.ir/v1/create"
payload = {'amount': '10000',
'callbackURL': 'https://test.ir',
'mobile' : '09900000000',
'email' : 'info@test.ir',
'invoiceProductId' : {"1234":10000,"5678":90000},
'buyerType' : 'Natural',
'economicCode' : '10802463540001',
'address' : 'آدرس پذیرنده',
'name' : 'نام و نام خانوادگی پذیرنده',
'nationalCode' : '1080246354'
'email': 'info@test.ir'}
files=[
]
headers = {
'Authorization': 'Bearer aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'
}
response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)
var request = require('request');
var options = {
'method': 'POST',
'url': 'https://api.tabapay.ir/v1/create',
'headers': {
'Authorization': 'Bearer aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'
},
formData: {
'amount': '10000',
'callbackURL': 'https://test.ir',
'mobile': '09900000000',
'invoiceProductId' : {"1234":10000,"5678":90000},
'buyerType' : 'Natural',
'economicCode' : '10802463540001',
'address' : 'آدرس پذیرنده',
'name' : 'نام و نام خانوادگی پذیرنده',
'nationalCode' : '1080246354'
'email': 'info@test.ir'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.tabapay.ir/v1/create");
request.Headers.Add("Authorization", "Bearer aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee");
var content = new MultipartFormDataContent();
content.Add(new StringContent("10000"), "amount");
content.Add(new StringContent("https://test.ir"), "callbackURL");
content.Add(new StringContent("09900000000"), "mobile");
content.Add(new StringContent("{"1234":10000,"5678":90000}"), "invoiceProductId");
content.Add(new StringContent("Natural"), "buyerType");
content.Add(new StringContent("10802463540001"), "economicCode");
content.Add(new StringContent("آدرس پذیرنده"), "address");
content.Add(new StringContent("نام و نام خانوادگی پذیرنده"), "name");
content.Add(new StringContent("1080246354"), "nationalCode");
content.Add(new StringContent("info@test.ir"), "email");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

بازگشت به سایت پذیرنده

بعد از اتمام عملیات پرداخت، پرداخت کننده به آدرسی که پذیرنده در callbackURL مشخص کرده بود، با متد GET، منتقل می‌شود.
پاسخ موفق {
"responseCode": 1,
"status": "success",
"token": "05d3f1d4-82e1-11ee-8f0e-d82429616d01",
"amount": 10000
}
پاسخ ناموفق {
"responseCode": -1,
"status": "error",
"token": "05d3f1d4-82e1-11ee-8f0e-d82429616d01",
"amount": 10000
}

تایید تراکنش

با استفاده از آدرس زیر می‌توانید تراکنش ایجاد شده در محیط تست را تایید کنید.
محیط تست https://api.tabapay.ir/v1/sandbox/verify
با استفاده از آدرس زیر می‌توانید تراکنش ایجاد شده در محیط عملیاتی را تایید کنید.
محیط عملیاتی https://api.tabapay.ir/v1/verify
توضیحات نوع پارامتر
کلید منحصر بفرد تراکنش string token
مبلغ مورد نظر بین 100,000 ریال تا 500,000,000 ریال باشد number amount
پاسخ موفق {
"responseCode": 1,
"status": "success",
"message": "تراکنش باموفقیت تایید شد",
"token": "05d3f1d4-82e1-11ee-8f0e-d82429616d01",
"shaparakRefNumber": "111122223333",
"trackingCode": 40,
"amount": 10000,
"finalAmount": 8700,
"cardNumber": "1234-56**-****-7890",
"hashedCardNumber": "23ab2fbc4074a49874ca7a8349ad9a11b8d845c2451f7c289d8f08181c6b8123",
"ip": "127.0.0.1",
"date":"1402/01/01 12:10"
}
پاسخ ناموفق {
"responseCode": -101,
"status": "error",
"message": "تراکنش انجام نشد",
"token": "05d3f1d4-82e1-11ee-8f0e-d82429616d01",
"trackingCode": 40,
"amount": "10000",
"finalAmount": 8700,
"additionalData": null,
"ip": "127.0.0.1",
"date":"1402/01/01 12:10"
}
  • PHP
  • Python
  • NodeJS
  • C#
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.tabapay.ir/v1/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 => array('token' => '05d3f1d4-82e1-11ee-8f0e-d82429616d01','amount' => '10000'),
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
import requests
url = "https://api.tabapay.ir/v1/verify"
payload = {'token': '05d3f1d4-82e1-11ee-8f0e-d82429616d01',
'amount': '10000'}
files=[
]
headers = {
'Authorization': 'Bearer aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'
}
response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)
var request = require('request');
var options = {
'method': 'POST',
'url': 'https://api.tabapay.ir/v1/create',
'headers': {
'Authorization': 'Bearer aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'
},
formData: {
'amount': '10000',
'callbackURL': 'https://test.ir',
'mobile': '09900000000',
'email': 'info@test.ir'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.tabapay.ir/v1/verify");
request.Headers.Add("Authorization", "Bearer aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee");
var content = new MultipartFormDataContent();
content.Add(new StringContent("05d3f1d4-82e1-11ee-8f0e-d82429616d01"), "token");
content.Add(new StringContent("10000"), "amount");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

تایید خودکار تراکنش

با استفاده از قابلیت تایید خودکار تراکنش، در صورتی که تراکنش توسط وبسایت پذیرنده تایید نشود،
تاباپی بین 10 تا 15 دقیقه پس از انجام تراکنش اطلاعات مربوط به تایید و پردازش تراکنش را با متد POST به همان آدرس ارسالی CallbackURL ارسال خواهد کرد.
توضیحات امنیتی نوع پارامتر
کد مرچنت هش شده (MD5) در هدر string HTTP_AUTHORIZE
درخواست ارسالی {
"responseCode": 1,
"status": "success",
"message": "تراکنش باموفقیت تایید شد",
"token": "05d3f1d4-82e1-11ee-8f0e-d82429616d01",
"shaparakRefNumber": "111122223333",
"trackingCode": 40,
"amount": 10000,
"finalAmount": 8700,
"cardNumber": "1234-56**-****-7890",
"hashedCardNumber": "23ab2fbc4074a49874ca7a8349ad9a11b8d845c2451f7c289d8f08181c6b8123",
"ip": "127.0.0.1",
"date":"1402/01/01 12:10"
}

لیست کدهای پاسخ

توضیحات کد پاسخ
موفق 1
تایید شده 2
خطای سیستمی 1-
ارسال پارامتر نامعتبر 9-
کد مرچنت اجباری است 10-
کد مرچنت نامعتبر است 11-
مبلغ اجباری است 12-
حداقل مبلغ : 100,000ریال 13-
حداکثر مبلغ : 500,000,000ریال 14-
لینک بازگشت اجباری است 15-
لینک بازگشت نامعتبر است 16-
شماره موبایل نامعتبر است 17-
ایمیل نامعتبر است 18-
پارامتر ورودی برای کد ملی نامعتبر است 19-
پارامتر ورودی برای شماره کارت بانکی نامعتبر است 20-
توضیحات کد پاسخ
حداکثر طول مجاز توضیحات 300 کاراکتر است 21-
فرمت پارامتر دیتا اختیاری باید Json باشد 22-
حداکثر طول مجاز برای دیتا اختیاری 500 کاراکتر است 23-
پارامتر ورودی ارسال پیامک نامعتبر است 24-
نام نامعتبر است 25-
در صورتی که ارسال پیامک فعال باشد، پارامتر شماره موبایل نمی تواند خالی باشد 26-
دامنه فعلی با دامنه تایید شده تطابق ندارد 27-
پذیرنده درگاه غیر فعال شده است 28-
درگاه پرداخت غیر فعال شده است 29-
درگاه پرداخت پیدا نشد 30-
تراکنش نامعتبر 31-
شناسه محصول های ارسال شده در پرونده مالیاتی یافت نشد 32-
پرونده مالیاتی به این درگاه متصل نمی باشد 33-
فیلد نوع خریدار در فاکتور نوع یک اجباری می باشد 34-
فیلد نوع خریدار در فاکتور نوع یک باید یکی از مقادیر [Natural, Legal, Civic, Foreigners, FinalConsumer] باشد 35-
فیلد (شناسه ملی/شماره ملی/کد فیدا) در فاکتور نوع یک برای شناسه 1234 اجباری می باشد 36-
فیلد شماره اقتصادی در فاکتور نوع یک برای شناسه 1234 اجباری می باشد 37-
فیلد نام خریدار در فاکتور نوع یک برای شناسه 1234 اجباری می باشد 38-
فیلد آدرس خریدار در فاکتور نوع یک برای شناسه 1234 اجباری می باشد 39-
فیلد موبایل خریدار در فاکتور نوع یک برای شناسه 1234 اجباری می باشد 40-
فرمت ارسالی شناسه محصول معتبر نمی باشد 41-
شناسه محصول 1234 در پرونده مالیاتی یافت نشد 42-
مجموع مبالغ فاکتور ها از مبلغ تراکنش بیشتر است 43-
شماره کارت پرداختی با شماره کارت درخواستی تطابق ندارد 100-
تراکنش ناموفق 101-
تراکنش منقضی شده است 102-

Postman

برای راحتی کار و بررسی سریعتر API تاباپی می‌توانید فایل زیر را دریافت کنید و آن را در برنامه Insomnia استفاده نمایید.
دانلود : Postman - API V1

Insomnia

برای راحتی کار و بررسی سریعتر API تاباپی می‌توانید فایل زیر را دریافت کنید و آن را در برنامه Insomnia استفاده نمایید.
دانلود : Insomnia - API - V1