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

اصطلاحات

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

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

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

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/v2/settlement

پس از گرفتن دسترسی به حساب بانکی، برای انتقال وجه باید وبسرویس بالا را با متد POST فراخوانی کنيد.

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

نام فیلد	نوع داده	شرح	اجباری
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	شناسه واریز (در صورتی که حساب مقصد شناسه دار باشد وارد کردن این فیلد الزامی می باشد)
reason	integer	بابت (در صورت ارسال نشدن، به صورت پیشفرض نوع پرداخت قرض و تادیه دیون در نظر گرفته می شود) جدول نوع ReasonType

جدول نوع ReasonType

مقدار	شرح
1	واریز حقوق
2	امور بیمه خدمات
3	امور درمانی
4	امور سرمایه گذاری و بورس
5	امور ارزی در چارچوب ضوابط و مقررات
6	پرداخت قرض و تادیه دیون (قرض الحسنه، بدهی)
7	امور بازنشستگی
8	معاملات اموال منقول
9	معاملات اموال غیر منقول
10	مدیریت نقدینگی
11	عوارض گمرکی
12	تسویه مالیاتی
13	سایر خدمات دولتی
14	تسهیلات و تعهدات
15	تودیع وثیقه
16	هزینه عمومی و امور روزمره
17	کمکهای خیریه
18	خرید کالا
19	خرید خدمات

نمونه کد (php) :

<?php

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

$application_id = 'your_application_id';

$bank = '016';

$access_password = 'your_access_password';

$transfers = [

[

'amount' => 100000,

'deposit' => 'your_deposit_account',

'destination_account' => 'your_destination_account',

'destination_firstname' => 'destination_firstname',

'destination_lastname' => 'destination_lastname',

'track_id' => 'your_unique_track_id',

'pay_id' => 'your_pay_id'

]

];

$body_params = [

'application_id' => $application_id,

'access_password' => $access_password,

'transfers' => $transfers

];

$body_params_json = json_encode($body_params);

$curl = curl_init();

curl_setopt_array($curl, [

CURLOPT_URL => $url,

CURLOPT_RETURNTRANSFER => true,

CURLOPT_POST => true,

CURLOPT_POSTFIELDS => $body_params_json,

CURLOPT_HTTPHEADER => [

'Accept: application/json',

'Content-Type: application/json'

]

]);

$response = curl_exec($curl);

curl_close($curl);

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

?>

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

using System;

using RestSharp;

using Newtonsoft.Json;

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

var client = new RestClient(options);

string applicationId = "your_application_id";

string bank = "016";

string accessPassword = "your_access_password";

var transfers = new[] {

new {

amount = 100000,

deposit = "your_deposit_account",

destination_account = "your_destination_account",

destination_firstname = "destination_firstname",

destination_lastname = "destination_lastname",

track_id = "your_unique_track_id",

pay_id = "your_pay_id"

}

};

var requestBody = new {

application_id = applicationId,

access_password = accessPassword,

transfers = transfers

};

string jsonBody = JsonConvert.SerializeObject(requestBody);

var request = new RestRequest("/api/bank-transfer/v2/settlement", Method.Post);

request.AddJsonBody(jsonBody);

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

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/v2/settlement"

application_id = 'your_application_id'

bank = '016'

access_password = 'your_access_password'

transfers = [{

'amount': 100000,

'deposit': 'your_deposit_account',

'destination_account': 'your_destination_account',

'destination_firstname': 'destination_firstname',

'destination_lastname': 'destination_lastname',

'track_id': 'your_unique_track_id',

'pay_id': 'your_pay_id'

}]

data = {

'application_id': application_id,

'access_password': access_password,

'transfers': transfers

}

response = requests.post(url, json=data, headers={"Content-Type": "application/json"})

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

print(output)

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

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

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

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

نام فیلد	نوع داده	شرح	اجباری
application_id	string	شناسه اپلیکیشن	بله
access_password	string	رمز دسترسی اپلیکیشن	بله
deposit	string	شماره حساب بانک که در اپلیکیشن ثبت شده است	خیر
track_id	string	کد رهگیری	خیر
limit	integer	تعداد رکورد‌های پاسخ	درصورت وارد کردن skip
skip	integer	تعدادرکورد‌هایی که رد شوند	درصورت وارد کردن limit

نمونه کد (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)	بله
to_date	string	تاریخ میلادی پایان بازه صورتحساب (Y-m-d)	خیر

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

عنوان	نوع داده	شرح
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)