Skip to main content

درگاه پرداخت اینترنتی(پرداخت‌یاری)

آموزش ویدئویی اتصال به درگاه پراخت : https://paystar.ir/help#

مقدمه#

این مستند جهت ارائه به پذیرندگان پی استار جهت اتصال به درگاه پرداخت میباشد. در حالت کلی پذیرنده ابتدا میبایست یک درخواست ایجاد تراکنش ارسال و برای آغاز تراکنش یک توکن یکبار مصرف دریافت و آن را برای انجام تراکنش به سایت پست نماید. بعد از بازگشت مشتری از درگاه، اطلاعات وضعيت تراکنش به سمت پذیرنده برگشت داده میشود و پذیرنده پس از دریافت اطلاعات میبایست نسبت به verify کردن تراکنش اقدام نماید.

نکته 1 : سرویسها به صورت REST با متد POST و فرمت json قابل استفاده میباشد.

نکته 2: :آدرس پایه برای اتصال به تمامی وبسرویسها https://core.paystar.ir/api/pardakht میباشد. این آدرس را به ابتدای آدرس های نسبی معرفی شده در مستند بيافزایيد. به عنوان مثال آدرس وبسریس create به شکل زیر تبدیل میشود.

  • https://core.paystar.ir/api/pardakht/create

سرویس Create#

این سرویس جهت ایجاد تراکنش به کار میرود و پذیرنده با دادن اطلاعات مورد نياز ایجاد تراکنش یک توکن یکبار مصرف دریافت میکند

keyvalue
Content-Typeapplication/json
AuthorizationBearer <YOUR_GATEWAY_ID>

توجه: به جای <ID_GATEWAY_YOUR> مقدار شناسه درگاه خود که در پنل پی استار وجود دارد را قرار دهيد.

پارامترهای ورودی

نام فیلدنوع دادهشرحاجباری
amountdoubleمبلغ تراکنشبله
order_idstringشناسه سفارسبله
callbackstringآدرس برگشتبله
signstringامضاءبله
namestringنام پرداخت کنندهخیر
phonestringتلفن پرداخت کنندهخیر
mailstringایمیل پرداخت کنندهخیر
descriptionstringتوضیحات پرداختخیر
allotmentarrayتسهیم در هر تراکنشخیر
method_callbackintegerمتد انتخابی برای بازگشت کاربر به سایت پذیرندهخیر

توجه:

• مبلغ تراکنش میبایست به ریال باشد و حداقل 5,000 ریال و حداکثر 500,000,000 ریال است. همچنين با توجه به تنظيمات کارمزد پایانه، سهم کارمزد پرداخت کننده به مبلغ افزوده خواهد شد.

• یکتایی شناسه سفارش در سامانه بررسی نمیشود. بهتر است به منظور جلوگيری از بروز خطا از شناسه یکتا استفاده شود. طول شناسه سفارش حداقل 1 و حداکثر 50 کاراکتر و شامل حروف و اعداد میباشد.

• آدرس برگشت باید با فرمت https://yoursite.ir/your/callback/url باشد. دامنه برگشت، باید دامنه اصلی سامانه که در هنگام ایجاد درگاه ثبت کردهاید باشد.

• برای ساخت امضا از متد HMAC و الگوریتم رمزنگاری SHA512 استفاده کنيد. کليد مورد نياز برای رمزنگاری، در هنگام ساخت درگاه در اختيار شما قرار میگيرد. آماده سازی دادهها برای امضا به صورت زیر میباشد:

amount#order_id#callback

پارامتر های خروجی (درصورت مجاز بودن درگاه برای تراکنش)

عنواننوع دادهشرح
statusintجدول وضعيت
messagestringپيام سيستم
dataPardakhtCreateDataجدول نوع داده PardakhtCreateData

پارامتر های خروجی (درصورت غیر مجاز بودن درگاه برای تراکنش)

عنواننوع دادهشرح
statusstringمقدار ثابت unauthenticated
actionstringمقدار ثابت PardakhtCreate
tagstringمقدار ثابت unauthenticated
messagestringپیام سیستم
dataarrayآرایه خالی
api_versionstringنسخه API

جدول نوع داده PardakhtCreateData

عنواننوع دادهشرح
tokenstringتوکن یکبار مصرف تراکنش
ref_numstringشناسه یکتای رهگيری تراکنش
order_idstringشناسه سفارش
payment_amountdoubleمبلغ نهایی پرداختی کاربر با اعمال کارمزد

توجه:

• مقدار ref_num را در دیتابيس ذخيره کنيد. از این شناسه در وبسرویس تایيد تراکنش استفاده خواهد شد.

• در صورت دریافت کد وضعیت -1 ،میبایست خطاهای برگشتی در فیلد data را مورد بررسی قرار داده و با اصلاح پارامترهای ورودی مجددا سرویس را فراخوانی نمایید.

پارامترهای تبادلی میان سایت فروشنده و سامانه پی استار#

درصورتی که پاسخ دریافتی از وبسرویس مرحله قبل (ایجاد تراکنش) موفق باشد و توکن یکبار مصرف را دریافت کرده باشيد، میتوانيد مشتری را با توکن دریافتی به سمت پی استار به آدرس زیر هدایت کنيد

  • https://core.paystar.ir/api/pardakht/payment

پارامترهای ورودی

نام فیلدنوع دادهشرحاجباری
tokenstringتوکن دریافتی از وبسرویس createبله

توجه:

• برای هدایت کاربر به این صفحه میتوانید از متد GET یا POST استفاده کنید.

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

پس از انجام تراکنش، کاربر به صفحه CallBack پذیرنده که در زمان ایجاد تراکنش مشخص شده، با ارسال فيلدهای زیر به صورت form-data هدایت خواهد شد. اگر در هنگام فراخوانی وبسرویس create ،پارامتر callback_method با مقدار عددی 1 ارسال شود، بازگشت به سایت پذیرنده با متد GET انجام میشود. در غیر اینصورت بازگشت به سایت پذیرنده با متد POST خواهد بود. بنابراین میبایست متد CallBack خود را با در نظر گرفتن این شرایط پیاده سازی و در وبسایت یا نرم افزار خود قرار دهید.

پارامترهای خروجی

عنواننوع دادهشرح
statusintجدول وضعیت
order_idstringشناسه سفارش (ارسال شده توسط پذیرنده)
ref_numstringشناسه یکتای رهگیری تراکنش
transaction_idstringشناسه تراکنش (موجود در پنل پی استار)
card_numberstringشماره کا رت پرداخت کننده
tracking_codestringکد رهگیری بانکی

توجه:

• درصورتی که وضعيت تراکنش ناموفق باشد ( پرداخت انجام نشده باشد ) فيلدهای card_number و tracking_code برگشت داده نمیشود.

سرویس verify#

پذیرنده بعد از گرفتن دادههای برگشتی از درگاه، درصورت موفق بودن تراکنش، از این سرویس جهت تایيدیه تراکنش ارسالی استفاده میکند. نکته مهم این است که پذیرنده نباید تا زمان دریافت وضعيت موفق از این سرویس، تراکنش را موفق در نظر بگيرد. درصورتی که تا 10 دقيقه بعد از تراکنش، این وبسرویس فراخوانی نشود، وضعيت تراکنش به صورت خودکار به ناموفق تغيير ميکند و مبلغ کسر شده از حساب مشتری طی 72 ساعت به حساب مشتری برگشت داده میشود. توجه داشته باشيد در صورتی که یکبار از این وبسریس پاسخ موفق دریافت کنيد، دیگر امکان فراخوانی وبسرویس را نخواهيد داشت و در صورت فراخوانی با پيام خطا مواجه خواهيد شد.

Header درخواست

keyvalue
Content-Typeapplication/json
AuthorizationBearer <YOUR_GATEWAY_ID>

توجه:

• به جای <YOUR_GATEWAY_ID> مقدار شناسه درگاه خود که در پنل پی استار وجود دارد را قرار دهيد.

پارامترهای ورودی

نام فیلدنوع دادهشرحاجباری
ref_numstringشناسه یکتای رهگیری تراکنشبله
amountdoubleمبلغ تراکنشبله
signstringامضاءبله

توجه:

• برای ساخت امضا از متد HMAC و الگوریتم رمزنگاری SHA512 استفاده کنيد. کليد مورد نياز برای رمزنگاری، در هنگام ساخت درگاه در اختيار شما قرار میگيرد. آماده سازی دادهها برای امضا به صورت زیر میباشد:

amount#ref_num#card_number#tracking_code

پارامترهای خروجی (درصورت مجاز بودن درگاه)

عنواننوع دادهشرح
statusintجدول وضعیت
messagestringپیام سیستم
dataPardakhtVerifyDataجدول نوع داده PardakhtVerifyData

پارامترهای خروجی (درصورت غیر مجاز بودن درگاه)

عنواننوع دادهشرح
statusstringمقدار ثابت unauthenticated
actionstringمقدار ثابت PardakhtCreate
tagstringمقدار ثابت unauthenticated
messagestringپیام سیستم
dataarrayآرایه خالی
api_versionstringنسخه API

جدول نوع داده PardakhtVerifyData

عنواننوع دادهشرح
pricedoubleمبلغ تراکنش
ref_numstringشناسه یکتای رهگيری تراکنش

تسهیم در تراکنش

علاوه بر تسهیم ایستا که برای همه ی تراکنشها به صورت یکسان اعمال میگردد و از طریق پنل کاربری قابل تنظیم است، میتوان برای هر تراکنش تسهیم متفاوت ایجاد کرد. برای این منظور باید در هنگام فراخوانی سرویس create فیلد allotment را که به فرمت زیر است، در بدنه درخواست ارسال کنید.

جدول نوع داده allotment

عنواننوع دادهشرح
idstringشناسه شریک تجاری
sheba_idstringشناسه شماره شبا شریک تجاری
shareintegerدرصد تسهیم )اجباری در صورت نبود amount
amountintegerمبلغ تسهیم )اجباری در صورت نبود share)

به عنوان مثال:

"allotment": [
{
"id": "شناسه شریک تجاری اول",
"id_sheba" : "شناسه شبای شریک",
"share": 40
},
{
"id": "شناسه شریک تجاری دوم",
"id_sheba" : "شناسه شبای شریک",
"amount": 10000
}
]

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

جدول کد های وضعیت#

عنوانdescriptionتوضیحات
1Okموفق
1-invalidRequestدرخواست نامعتبر (خطا در پارامترهای ورودی)
2-inactiveGatewayدرگاه فعال نیست
3-retryTokenتوکن تکراری است
4-amountLimitExceedمبلغ بیشتر از سقف مجاز درگاه است
5-invalidRefNumشناسه ref_num معتبر نیست
6-retryVerificationتراکنش قبلا وریفای شده است
7-badDataپارامترهای ارسال شده نامعتبر است
8-trNotVerifiableتراکنش را نمیتوان وریفای کرد
9-trNotVerifiedتراکنش وریفای نشد
98-paymentFailedتراکنش ناموفق
99-errorخطای سامانه

نمونه کد#

C# - RestSharp#

var client = new RestClient("https://core.paystar.ir/api/pardakht/create");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer YOUR_TERMINAL_ID");
request.AddHeader("Content-Type", "application/json");
var body = @"{
" + "\n" +
@" ""amount"": amount,
" + "\n" +
@" ""order_id"": ""order_id"",
" + "\n" +
@" ""callback"": ""https://site.ir/callback"",
" + "\n" +
@" ""sign"": ""sign""
" + "\n" +
@"}";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

Dart - http#

var headers = {
'Authorization': 'Bearer YOUR_TERMINAL_ID',
'Content-Type': 'application/json'
};
var request = http.Request('POST', Uri.parse('https://core.paystar.ir/api/pardakht/create'));
request.body = '''{\r\n "amount": amount,\r\n "order_id": "order_id",\r\n "callback": "https://site.ir/callback",\r\n "sign": "sign"\r\n}''';
request.headers.addAll(headers);
http.StreamedResponse response = await request.send();
if (response.statusCode == 200) {
print(await response.stream.bytesToString());
}
else {
print(response.reasonPhrase);
}

Go - Native#

package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://core.paystar.ir/api/pardakht/create"
method := "POST"
payload := strings.NewReader(`{`+"
"+`
"amount": amount,`+"
"+`
"order_id": "order_id",`+"
"+`
"callback": "https://site.ir/callback",`+"
"+`
"sign": "sign"`+"
"+`
}`)
client := &http.Client {
}
req, err := http.NewRequest(method, url, payload)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Authorization", "Bearer YOUR_TERMINAL_ID")
req.Header.Add("Content-Type", "application/json")
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := ioutil.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}

Java - Unirest#

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://core.paystar.ir/api/pardakht/create")
.header("Authorization", "Bearer YOUR_TERMINAL_ID")
.header("Content-Type", "application/json")
.body("{\r\n \"amount\": amount,\r\n \"order_id\": \"order_id\",\r\n \"callback\": \"https://site.ir/callback\",\r\n \"sign\": \"sign\"\r\n}")
.asString();

JavaScript - jQuery#

var settings = {
"url": "https://core.paystar.ir/api/pardakht/create",
"method": "POST",
"timeout": 0,
"headers": {
"Authorization": "Bearer YOUR_TERMINAL_ID",
"Content-Type": "application/json"
},
"data": "{\r\n \"amount\": amount,\r\n \"order_id\": \"order_id\",\r\n \"callback\": \"https://site.ir/callback\",\r\n \"sign\": \"sign\"\r\n}",
};
$.ajax(settings).done(function (response) {
console.log(response);
});

PHP-cURL#

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://core.paystar.ir/api/pardakht/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 =>'{
"amount": amount,
"order_id": "order_id",
"callback": "https://site.ir/callback",
"sign": "sign"
}',
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer YOUR_TERMINAL_ID',
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Python - Requests#

import requests
import json
url = "https://core.paystar.ir/api/pardakht/create"
payload = "{\r\n \"amount\": amount,\r\n \"order_id\": \"order_id\",\r\n \"callback\": \"https://site.ir/callback\",\r\n \"sign\": \"sign\"\r\n}"
headers = {
'Authorization': 'Bearer YOUR_TERMINAL_ID',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)