سرویس های انتقال وجه

اصطلاحات

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

کاربر/ پذیرنده: شخصی که در پنل پی استار حساب کاربری ایجاد کرده است.

اپليکيشن:برای فراخوانی وبسرویس‌های انتقال وجه، نياز به ایجاد اپليکيشن مي‌باشد که به این منظور باید از طریق پنل کاربری برای ایجاد آن اقدام نمایید.

apiKey :یک توکن برای احراز هویت کاربر و دسترسی به اپليکيشن، به منظور فراخوانی وبسرویس‌های دریافت دسترسی حساب و انتقال وجه است. این توکن باید در تمامی وبسرویس‌ها به عنوان توکن bearer در هدر authorization ارسال شود.

refreshToken :توکن apiKey به مدت 24 ساعت معتبر است. لذا برای ایجاد apiKey جدید به refreshToken نياز مي‌باشد.

applicationId : شناسه اپليکيشن، که بعد از ایجاد اپليکيشن در اختيار کاربر قرار مي‌گيرد.

accessPassword :رمز دسترسی به اپليکيشن، که بعد از ایجاد اپليکيشن در اختيار کاربر قرار مي‌گيرد.

accessIp :آی پی های مجاز برای فراخوانی وبسرویس‌ها که در اپليکيشن تنظيم شده اند.

وبسرویس refresh api key

• https://core.paystar.ir/api/application/refresh-api-key

برای‌ دریافت apiKey جدید ،سرویس بالا با متد POST فراخوانی شود.

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

نام فیلد	نوع داده	شرح	اجباری
application_id	string	شناسه اپلیکیشن	بله
access_password	string	رمز دسترسی اپلیکیشن	بله
refresh_token	string	توکن بازیابی API key	بله

درصورت فرخوانی موفق، پاسخ با وضعيت ok و در صورت فراخوانی ناموفق با وضعيت fail دریافت ميکنيد. نمونه پاسخ موفق به شکل زیر مي‌باشد.

{

“status”: "ok",

“data”: {

“api_key”: “...”,

“api_key_expire_date”: “...”

},

}

وبسرویس دریافت لیست درخواست‌های انتقال وجه

• https://core.paystar.ir/api/bank-transfer/settlement-requests

جهت دریافت ليست درخواست‌های انتقال وجه ،سرویس بالا با متد GET فراخوانی گردد:

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

نام فیلد	نوع داده	شرح	اجباری
application_id	string	شناسه اپلیکیشن	بله
access_password	string	رمز دسترسی اپلیکیشن	بله
source_accounts	array	شماره حساب های مبدا	خیر
track_id	string	کد رهگیری	خیر
destination_account	string	شماره حساب یا شبا مقصد	خیر
transaction_id	string	شناسه یکتای تراکنش	خیر
min_amount	integer	حداقل مبلغ	خیر
max_amount	integer	حداکثر مبلغ	خیر
transfer_type	integer	روش انتقال (جدول نوع TransferType)	خیر
from_date	string	تاریخ شمسی شروع بازه صورتحساب (Y-m-d,Y-m-dH:i:s)	خیر
to_date	string	تاریخ شمسی پایان بازه صورتحساب (Y-m-d,Y-m-dH:i:s)	خیر
limit	integer	تعداد رکورد‌های پاسخ	درصورت وارد کردن skip
skip	integer	تعدادرکورد‌هایی که رد شوند	درصورت وارد کردن limit

وبسرویس انتقال وجه بانکی (نسخه جدید)

• https://core.paystar.ir/api/bank-transfer/v3/settlement

پس از گرفتن دسترسی به حساب بانکی، برای انتقال وجه باید وبسرویس بالا را با متد POST فراخوانی کنيد. تفاوت این نوع ورژن با ورژن قبلی این می باشد مبلغ انتقال وجه هر رکورد transfer بعد از عبور کردن از حداکثر مبلغ، مبلغ را به تراکنش های خورد کرده و بعد سمت بانک ارسال می گردد. تفاوت دیگر این نسخه با نسخه قبلی اضاف شده فیلد های type و فیلد transfer_type می باشد. که به ترتیب بیان گر نوع انتقال وجه(درون بانکی، پایا و ساتنا) و نحوه ارسال به سمت سرویس دهنده (مستقیم یا به صورت صف) که در ادامه با آنها خواهیم پرداخت.در نظر داشته باشید پاسخ موفق این وبسرویس به معنای موفق بودن تراکنش نمی باشد.

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

نام فیلد	نوع داده	شرح	اجباری
application_id	string	شناسه اپلیکیشن	بله
access_password	string	رمز دسترسی اپلیکیشن	بله
transfers	array	آرایه‌ای از لیست درخواست‌های انتقال وجه که هر درخواست یک object به فرمت جدول زیر می‌باشد	بله

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

نام فیلد	نوع داده	شرح	اجباری
amount	integer	مبلغ تراکنش	بله
deposit	string	شماره حساب مبداء	بله
destination_account	string	شماره حساب مقصد که میتوانید شماره حساب بانکی یا شماره شبا (26 کاراکتر) باشد (اگر حساب شما در بانک شامل کاراکتر اضافه مانند خط تیره میباشد با همان فرمت در پارامتر استفاده کنید)	بله
destination_firstname	string	نام صاحب حساب مقصد	بله
destination_lastname	string	نام خانوادگی صاحب حساب مقصد	بله
track_id	string	میتوانید با track id یکتا، از ایجاد دوباره یک تراکنش جلوگیری کنید. در صورت ورود track id تکراری خطا دریافت میکنید.	بله
pay_id	string	شناسه واریز (در صورتی که حساب مقصد شناسه دار باشد وارد کردن این فیلد الزامی می باشد)	بله
type	integer	نوع انتقال بانکی می باشد(داخلی، پایا، ساتنا) درصورت پر نکردن سیستم خودکار تشخصیص خواهد داد.	خیر
transfer_type	integer	بیان گر نوع انتقال می باشد. (مستقیم یا صف) که به سمت بانک ارسال گردد.	خیر
reason	integer	بابت (در صورت ارسال نشدن، به صورت پیشفرض نوع پرداخت قرض و تادیه دیون در نظر گرفته می شود) جدول نوع ReasonType	خیر

جدول type

• در صورت عدم وارد کردن این تایپ سیستم به صورت خودکار تشخیص خواهد که نوع انتقال به چه صورت است.
• اگر نوع ارسالی با شماره حساب مبدا و مقصد یکسان نباشد سیستم به صورت خودکار تشخیص و اصلاح خواهد نمود.
• انتقال وجه ساتنا فقط تا ساعت 14 هر روز کاری انجام خواهد شدو حدود 30 دقیقه زمان بر خواهد بود همچنین توجه داشته باشید حداقل مبلغ انتقال وجه ساتنا 100 میلیون تومان می باشد.

نوع داده	شرح
1	انتقال وجه داخلی(داخل بانکی)
2	انتقال وجه پایا ( بین بانکی)
3	انتقال ساتنا (بین بانکی و آنی که در ساعات مشخص امکان پذیر است.)

جدول transfer_type

• در صوت عدم پر کردن این فیلد سیستم به صورت خودکار نوع انتقال را مستقیم لحاظ می کند.
• توجه داشته باشید در صورت انتخاب نوع مستقیم امکان لغو انتقال وجود ندارد.
• در صورت انتخاب به صورت نوع صف امکان لغو تراکنش تا 15 دقیقه بعد از انتقال وجود دارد در غیر این صورت امکان‌پذیر نیست.

نوع داده	شرح
1	مستقیم
2	به صورت صف

نمونه کد (php) :

<?php

$api_key = 'your_api_key';

$application_id = 'your_application_id';

$access_password = 'your_access_password';

$deposit = 'your_deposit_account'; // Optional

$track_id = 'your_track_id'; // Optional

$limit = 10; // Optional

$skip = 0; // Optional

$url = 'https://core.paystar.ir/api/bank-transfer/settlement-requests';

$body_params = [

'application_id' => $application_id,

'access_password' => $access_password,

'deposit' => $deposit,

'track_id' => $track_id,

'limit' => $limit,

'skip' => $skip

];

$query_params = http_build_query(array_filter($body_params)); // remove null values

$curl = curl_init();

curl_setopt_array($curl, [

CURLOPT_URL => $url . "?" . $query_params,

CURLOPT_RETURNTRANSFER => true,

CURLOPT_HTTPGET => true,

CURLOPT_HTTPHEADER => [

'Content-Type: application/json',

'Accept: application/json',

'Authorization: Bearer ' . $api_key

],

]

);

$response = curl_exec($curl);

curl_close($curl);

print_r(json_decode($response, true, JSON_PRETTY_PRINT));

?>

نمونه کد (C# .net) :

using RestSharp;

using Newtonsoft.Json;

var options = new RestClientOptions("https://core.paystar.ir");

var client = new RestClient(options);

string api_key = "your-api-key";

string application_id = "your_application_id";

string access_password = "your_access_password";

string deposit = "your_deposit_account"; // Optional

string track_id = "your_track_id"; // Optional

int limit = 10; // Optional

int skip = 0; // Optional

var requestBody = new {

application_id = application_id,

access_password = access_password,

deposit = deposit,

track_id = track_id,

limit = limit,

skip = skip

};

var queryParams = string.Join("&", requestBody.GetType().GetProperties()

.Where(p => p.GetValue(requestBody) != null)

.Select(p => $"{p.Name}={p.GetValue(requestBody)}"));

var request = new RestRequest($"/api/bank-transfer/settlement-requests?{queryParams}", Method.Get);

request.AddHeader("Accept", "application/json");

request.AddHeader("Content-Type", "application/json");

request.AddHeader("Authorization", "Bearer " + api_key);

RestResponse response = client.Execute(request);

var res = response.Content;

Console.WriteLine(res);

نمونه کد (Python) :

import json

import requests

url = "https://core.paystar.ir/api/bank-transfer/settlement-requests"

api_key = 'your-api-key'

header = {

"Accept": "application/json",

"Authorization": "Bearer " + api_key,

"Content-Type": "application/json",

}

params = {

'application_id': 'your_application_id',

'access_password': 'your_access_password',

'deposit': 'your_deposit_account', # Optional

'track_id': 'your_track_id', # Optional

'limit': 10, # Optional

'skip': 0, # Optional

}

response = requests.get(url, headers=header, params={k: v for k, v in params.items() if v is not None})

output = json.dumps(response.json(), indent=4, ensure_ascii=False)

print(output)

وبسرویس دریافت موجودی حساب

• https://core.paystar.ir/api/open-banking/service/balance

جهت دریافت موجودی حساب بانکی ،سرویس بالا با متد GET فراخوانی گردد:

(در حال حاضر وبسرویس موجودی فقط برای بانک صادرات در دسترس است.)

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

نام فیلد	نوع داده	شرح	اجباری
application_id	string	شناسه اپلیکیشن	بله
access_password	string	رمز دسترسی اپلیکیشن	بله
account_number	string	شماره حساب بانک که در اپلیکیشن ثبت شده است	بله

پارامتر های خروجی (درصورت موفق بودن درخواست)

عنوان	نوع داده	شرح
available_balance	int	مانده در دسترس
effective_balance	int	مانده موثر
account	string	شماره حساب

نمونه کد (php) :

<?php

$api_key = 'your_api_key';

$application_id = 'your_application_id';

$access_password = 'your_access_password';

$account_number = 'your_deposit_account';

$url = 'https://core.paystar.ir/api/open-banking/service/balance';

$body_params = [

'application_id' => $application_id,

'access_password' => $access_password,

'account_number' => $account_number

];

$query_params = http_build_query(array_filter($body_params));

$curl = curl_init();

curl_setopt_array($curl, [

CURLOPT_URL => $url . "?" . $query_params,

CURLOPT_RETURNTRANSFER => true,

CURLOPT_HTTPGET => true,

CURLOPT_HTTPHEADER => [

'Content-Type: application/json',

'Accept: application/json',

'Authorization: Bearer ' . $api_key

],

]

);

$response = curl_exec($curl);

curl_close($curl);

print_r(json_decode($response, true, JSON_PRETTY_PRINT));

?>

نمونه کد (C# .net) :

using RestSharp;

using Newtonsoft.Json;

var options = new RestClientOptions("https://core.paystar.ir");

var client = new RestClient(options);

string api_key = "your-api-key";

string application_id = "your_application_id";

string access_password = "your_access_password";

string account_number = "your_deposit_account";

var requestBody = new {

application_id = application_id,

access_password = access_password,

account_number = account_number

};

var queryParams = string.Join("&", requestBody.GetType().GetProperties()

.Where(p => p.GetValue(requestBody) != null)

.Select(p => $"{p.Name}={p.GetValue(requestBody)}"));

var request = new RestRequest($"/api/open-banking/service/balance?{queryParams}", Method.Get);

request.AddHeader("Accept", "application/json");

request.AddHeader("Content-Type", "application/json");

request.AddHeader("Authorization", "Bearer " + api_key);

RestResponse response = client.Execute(request);

var res = response.Content;

Console.WriteLine(res);

نمونه کد (Python) :

import json

import requests

url = "https://core.paystar.ir/api/open-banking/service/balance"

api_key = 'your-api-key'

header = {

"Accept": "application/json",

"Authorization": "Bearer " + api_key,

"Content-Type": "application/json",

}

params = {

'application_id': 'your_application_id',

'access_password': 'your_access_password',

'account_number': 'your_deposit_account',

}

response = requests.get(url, headers=header, params={k: v for k, v in params.items() if v is not None})

output = json.dumps(response.json(), indent=4, ensure_ascii=False)

print(output)

وبسرویس دریافت صورتحساب

• https://core.paystar.ir/api/open-banking/service/v2/invoice

جهت دریافت صورتحساب بانکی ،سرویس بالا با متد GET فراخوانی گردد:

(در حال حاضر وبسرویس صورتحساب فقط برای بانک صادرات در دسترس است.)

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

نام فیلد	نوع داده	شرح	اجباری
application_id	string	شناسه اپلیکیشن	بله
access_password	string	رمز دسترسی اپلیکیشن	بله
account_number	string	شماره حساب بانک که در اپلیکیشن ثبت شده است	بله
from_date	string	تاریخ میلادی شروع بازه صورتحساب (Y-m-d,Y-m-dH:i:s)	بله
to_date	string	تاریخ میلادی پایان بازه صورتحساب (Y-m-d,Y-m-dH:i:s)	خیر

پارامتر های خروجی (درصورت موفق بودن درخواست)

عنوان	نوع داده	شرح
status	int	جدول وضعيت
message	string	پيام سيستم
data	array Transaction	جدول نوع داده Transaction

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

عنوان	نوع داده	شرح
transaction_date_time	jalalidatetime	تاریخ شمسی تراکنش
amount	int	مبلغ
description	string	کد شرح بانکی تراکنش
balance	int	مانده پس از تراکنش
transaction_trace	string	کد رهگیری
branch_code	string	شعبه انجام تراکنش
transaction_identity	string	uuid تراکنش انتقال مربوطه
statement_status	string	وضعیت تراکنش
source_account	string	حساب مبدا
destination_account	string	حساب مقصد
document_id	string	شناسه سند انتقال مربوطه
customer_description	string	شرح تراکنش
operation_code	string	کد تراکنش
payment_id	string	شناسه واریز
transaction_type	string	نوع تراکنش (جدول نوع TransactionType)
transfer_type	int	روش انتقال (جدول نوع TransferType)

جدول نوع TransactionType

مقدار	شرح
CREDIT	واریز
DEBIT	برداشت

جدول نوع TransferType

مقدار	شرح
1	پایا
2	ساتنا
3	حساب به حساب
4	کارت به کارت
5	پل
6	انتقالی(نامشخص)
7	خرید
8	کارمزد بانک
9	اصلاحی
10	خودپرداز
11	دستگاه پوز
12	نقدی
13	تسویه شاپرکی
14	قبض

نمونه کد (php) :

<?php

$api_key = 'your_api_key';

$application_id = 'your_application_id';

$access_password = 'your_access_password';

$account_number = 'your_deposit_account';

$url = 'https://core.paystar.ir/api/open-banking/service/invoice';

$body_params = [

'application_id' => $application_id,

'access_password' => $access_password,

'account_number' => $account_number,

'from_date' => '2024-12-24',

'to_date' => '2024-12-25'

];

$query_params = http_build_query(array_filter($body_params));

$curl = curl_init();

curl_setopt_array($curl, [

CURLOPT_URL => $url . "?" . $query_params,

CURLOPT_RETURNTRANSFER => true,

CURLOPT_HTTPGET => true,

CURLOPT_HTTPHEADER => [

'Content-Type: application/json',

'Accept: application/json',

'Authorization: Bearer ' . $api_key

],

]

);

$response = curl_exec($curl);

curl_close($curl);

print_r(json_decode($response, true, JSON_PRETTY_PRINT));

?>

نمونه کد (C# .net) :

using RestSharp;

using Newtonsoft.Json;

var options = new RestClientOptions("https://core.paystar.ir");

var client = new RestClient(options);

string api_key = "your-api-key";

string application_id = "your_application_id";

string access_password = "your_access_password";

string account_number = "your_deposit_account";

string from_date = "2024-12-22";

string to_date = "2024-12-23";

var requestBody = new {

application_id = application_id,

access_password = access_password,

account_number = account_number,

from_date = from_date,

to_date = to_date

};

var queryParams = string.Join("&", requestBody.GetType().GetProperties()

.Where(p => p.GetValue(requestBody) != null)

.Select(p => $"{p.Name}={p.GetValue(requestBody)}"));

var request = new RestRequest($"/api/open-banking/service/invoice?{queryParams}", Method.Get);

request.AddHeader("Accept", "application/json");

request.AddHeader("Content-Type", "application/json");

request.AddHeader("Authorization", "Bearer " + api_key);

RestResponse response = client.Execute(request);

var res = response.Content;

Console.WriteLine(res);

نمونه کد (Python) :

import json

import requests

url = "https://core.paystar.ir/api/open-banking/service/invoice"

api_key = 'your-api-key'

header = {

"Accept": "application/json",

"Authorization": "Bearer " + api_key,

"Content-Type": "application/json",

}

params = {

'application_id': 'your_application_id',

'access_password': 'your_access_password',

'account_number': 'your_deposit_account',

'from_date': '2024-11-22',

'from_date': '2024-11-23',

}

response = requests.get(url, headers=header, params={k: v for k, v in params.items() if v is not None})

output = json.dumps(response.json(), indent=4, ensure_ascii=False)

print(output)