Authentication

Toman uses OAuth 2.0 to authorize API requests. We will provide you with the required Username, Password, Client ID, and Client Secret required for the process of token acquirement.

Each endpoint in our project has none, one, or more scope requirements, which can be found in the endpoint documentation. Note that you have to had included the required scopes in your authentication process in order to be allowed to use them.

The authentication process URL for our staging and productions servers are:

Environment	Auth URL
Production	`https://accounts.qbitpay.org/oauth2/token/`
Staging	`https://auth.qbitpay.org/oauth2/token/`

The acquired token should be included among request headers with the prefix Bearer:

Authorization: Bearer 5OGgq1FQS7jPITItICRwlDYZv5P91A

Get Access Token

To acquire your access token, you need to send your username, password, client_id, and client_secret to the auth endpoint.

Request Data Example (Without Basic Authentication)

import requests

auth_url = "https://auth.qbitpay.org/oauth2/token/"
username = "MY_USERNAME"
password = "MY_PASSWORD"
client_id = "MY_CLIENT_ID"
client_secret = "MY_CLIENT_SECRET"

response = requests.request(
    "POST",
    auth_url,
    data={
        "client_id": client_id,
        "client_secret": client_secret,
        "username": username,
        "password": password,
        "grant_type": "password",
        "scope": "settlement.wallet.retrieve"
    },
)
token = response.json()["access_token"]
refresh_token = response.json()["refresh_token"]

authorization_header = {
    "Authorization": f"Bearer {token}"
}

endpoint_response = requests.request(
    "GET",
    "https://settlement-staging.qbitpay.org/wallets/deposits/summary/",
    headers=authorization_header
)

print(endpoint_response.json())

curl -X POST -d "username=$USERNAME" \
             -d "password=$PASSWORD" \
             -d "client_id=$CLIENT_ID" \
             -d "client_secret=$CLIENT_SECRET" \
             -d "grant_type=password" \
             -d "scope=settlement.wallet.retrieve" \
             $AUTH_URL

curl -H "Authorization: Bearer $TOKEN" $API_ENDPOINT

POST /oauth2/token/ HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: auth.qbitpay.org

grant_type=password&
client_id=MY_CLIENT_ID&
client_secret=MY_CLIENT_SECRET&
username=MY_USERNAME&
password=MY_PASSWORD&
scope=settlement.single.submit%20settlement.single.verify

Request Data Example (Using Basic Authentication)

import requests

auth_url = "https://auth.qbitpay.org/oauth2/token/"
username = "MY_USERNAME"
password = "MY_PASSWORD"
client_id = "MY_CLIENT_ID"
client_secret = "MY_CLIENT_SECRET"

response = requests.request(
    "POST",
    auth_url,
    data={
        "username": username,
        "password": password,
        "grant_type": "password",
        "scope": "settlement.wallet.retrieve"
    },
    # this is how requests handles the basic http authentication
    auth=(client_id, client_secret)
)
token = response.json()["access_token"]
refresh_token = response.json()["refresh_token"]

authorization_header = {
    "Authorization": f"Bearer {token}"
}

endpoint_response = requests.request(
    "GET",
    "https://settlement-staging.qbitpay.org/wallets/deposits/summary/",
    headers=authorization_header
)

print(endpoint_response.json())

curl -u $CLIENT_ID:$CLIENT_SECRET -X POST -d "username=$USERNAME" \
                                          -d "password=$PASSWORD" \
                                          -d "grant_type=password" \
                                          -d "scope=settlement.wallet.retrieve" \
                                          $AUTH_URL

curl -H "Authorization: Bearer $TOKEN" $API_ENDPOINT

POST /oauth2/token/ HTTP/1.1
Authorization: Basic TVlfQ0xJRU5UX0lEOk1ZX0NMSUVOVF9TRUNSRVRF
Content-Type: application/x-www-form-urlencoded
Host: auth.qbitpay.org

grant_type=password&
username=MY_USERNAME&
password=MY_PASSWORD&
scope=settlement.single.submit%20settlement.single.verify

Response Data Example

HTTP/1.1 200 OK
Content-Type: application/json

{
"access_token":"5OGgq1FQS7jPITItICRwlDYZv5P91A",
"expires_in":86400,
"token_type":"Bearer",
"scope":"settlement.single.submit settlement.single.verify",
"refresh_token":"upTFapSZfpJISYeo0YsZVjf8X29SBy"
}

The Content-Type of get token request should be application/x-www-form-urlencoded.
`Content-Type: application/x-www-form-urlencoded`

You can obtain a single token and use it for multiple endpoints by specifying different scopes separated by whitespace. For instance: > scope=settlement.single.submit payment.create.

Refresh Token

Since every access token has an expiration date (see expires_in), you need to acquire a new access token after it expires. The Oauth2 standard, is to use refresh tokens.

To refresh your access token, you need to send your refresh_token, client_id, and client_secret to the auth endpoint with grant_type=refresh_token. The expiration time of the refresh token itself is one week. please notice in the response body of the refresh-token process, a new refresh token will be generated, so we suggest replacing the newly generated refresh token with the old one, for future refresh requests.

response = requests.request(
    "POST",
    auth_url,
    data={
        "grant_type": "refresh_token",
        "refresh_token": refresh_token,
        "client_id": client_id,
        "client_secret": client_secret,
    }
)
access_token = response.json()["access_token"]
new_refresh_token = response.json()["refresh_token"]

curl -X POST -d "refresh_token=$REFRESH_TOKEN"\
             -d "client_id=$CLIENT_ID" \
             -d "client_secret=$CLIENT_SECRET" \
             -d "grant_type=refresh_token" \
             $AUTH_URL

Request Data Example

POST /oauth2/token/ HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: auth.qbitpay.org

grant_type=refresh_token&
refresh_token=upTFapSZfpJISYeo0YsZVjf8X29SBy&
client_id=MY_CLIENT_ID&
client_secret=MY_CLEINT_SECRET

Response Data Example

HTTP/1.1 200 OK
Content-Type: application/json

{
"access_token":"mAGJQqnhLBEZ5UMVAvHVNruOzAyZVs",
"expires_in":86400,
"token_type":"Bearer",
"scope":"settlement.single.submit settlement.single.verify",
"refresh_token":"BLVE2AleqqLHPBmGad4HAQEmqkPr4b"
}

Error Handling

In this section we will list some of the errors that you may encounter while trying to obtian or refresh your tokens.

400_INVALID_SCOPE

{"error": "invalid_scope"}

Reasons

You're acquiring a token with a scope that is not defined. (e.g. wrong scope name)
One or more of the scopes in your request is unavailable for your user.

400_INVALID_GRANT

{
    "error"
:
    "invalid_grant", "error_description"
:
    "..."
}

Reasons

You have specified the username or password in your request incorrectly.

401_INVALID_CLIENT

{
    "error"
:
    "invalid_client"
}

Reasons

The client_id specified in your request is not correct.
The client_secret specified in your request is not correct.

Permissions

To access the Corporate Banking API service, you must obtain a token associated with a username that has the corporate-banking:api permission. Please reach out to the Toman team to request access to this permission.

ACCOUNTS

Each account has specific permissions, as outlined below:

Permission	Description
has view	View account details
has view balance	View account balance
has view statement	View account statements
has create transfer	Create a transfer
max amount per transfer	Maximum transfer amount
max amount per day	Maximum transfer amount per day

Please contact Toman to request these permissions for the user.

Workflow

The workflow is a process that enables the creation, signing, and execution of a transfer before its completion. This feature supports multiple policies based on different transfer amount ranges. Each policy defines the required number of users from specific groups to sign a transfer. A transfer can only be executed once the necessary approvals from each group have been obtained.

Please contact Toman to request access to this feature.

Base URLs

The base URLs for our staging and production API servers are as follows:

Environment	URL
Production	`https://dbank.toman.ir/api/v1`
Staging	`https://dbank-staging.qcluster.org/api/v1`

Note: Please ensure that you include the trailing slash at the end of the URLs for all endpoints.

Models

This section introduces the models used in the Corporate Banking service for responses throughout the API.

Account

The entity representing an account.

Parameter	Type	Description	Example
id	Integer	Account Identifier.	2
bank_id	Integer	ID of the bank where the account is registered. Bank IDs section.	15
iban	String	The IBAN number (شماره شبا) of the account.	"IR460170000000111111130001"
account_number	String	The account number for the account.	"0111111130001"
account_owner	String	The name of the account owner.	"elecom"
active	Boolean	Indicates if the account is active.	true
credential	Array of Integers	List of credential IDs associated with this account.	[1, 2, 3]
opening_date	String (Date)	The date when the account was opened.	"2022-10-04"
balance	Integer	The current balance in the account, expressed in IRR.	200000
last_update_balance_at	String (Date)	The datetime that account balance was updated.	"2022-10-04"
pinned	Boolean	Indicates if the account is pinned.	true

Transfer

Parameter	Type	Description	Example
uuid	String (36)	Unique identifier for the transfer.	"2e30029e-620b-41e6-8be5-ab69b421cec3"
bank_id	Integer	Payment paid at this bank ID.	15
account	Integer	ID of the account to transfer money from.	11
account_number_source	String	The account number (شماره حساب) of the source account.	"0228939030001"
iban_source	String	The IBAN number (شماره شبا) of the source account.	"IR460170000000228939030001"
transfer_type	Integer	Transfer types	1
status	Integer	Status of the transfer	8
amount	Integer	Amount of the transfer.	1000
iban_destination	String	The IBAN number (شماره شبا) of the destination account. This field may be left empty if transferring to a card or account number.	""
account_number_destination	String	The account number (شماره حساب) of the destination account. This field may be left empty if transferring to a card or IBAN.	""
card_number_destination	String	The card number of the destination account. This field may be left empty if transferring to an account number or IBAN.	""
description	String	Additional details or description of the transfer.	"description"
first_name	String	First name of the recipient.	"mohamad"
last_name	String	Last name of the recipient.	"akbari"
reason	Integer	Transfer Reason	1
tracker_id	String (max 36)	Tracker ID that you can follow your transfer with.	"1112"
created_at	datetime	date time created the transfer.	"2024-12-08T12:52:46.244217Z"
created_by	Integer	ID of the user who created the transfer.	1
creation_type	Integer	Creation type	4
bank_id_destination	Integer	Bank ID of the destination account. Bank IDs	2
follow_up_code	String	The follow up code received from the bank for the transfer.	"12345"
payment_id	String (max 36)	The payment ID of the transfer. (supported for these banks only)	"123456"

statement

In the statement, the following fields are available for each transaction:

Field Name	Type	Description
amount	BigInteger	The transaction amount, negative for debit and positive for credit.
side	Boolean	Specifies the transaction type: `True` for credit, `False` for debit.
tracing_number	CharField	The tracing number assigned by the bank.
transaction_datetime	DateTimeField	The date and time when the transaction was recorded by the bank.
payment_id	CharField	A unique identifier for the payment linked to the transaction.
source_account	CharField	The account from which the transaction was initiated.

Note: Each bank may provide additional fields in their statements, but the fields listed above are standardized across all banks.

Pagination Schema

All responses for Corporate Banking service endpoints follow the page pattern, which structures the response in a paginated format.

Parameter	Type	Description	Example
count	Integer	The total number of objects across all pages	183
next	String (Nullable)	The URL of the next page containing items after the current page	"https://dbank.toman.ir/api/v1/account/?page=3"
previous	String (Nullable)	The URL of the previous page containing items before the current page	"https://dbank.toman.ir/api/v1/account/?page=1"
results	Array[Object]	An array containing the items for the current page

Enums

1. Bank IDs

Each bank has a unique numeric identifier. The mapping is as follows.

Name	Persian Name	Code
Shahr	شهر	1
Melli	ملی	2
Mellat	ملت	3
Tejarat	تجارت	4
Keshavarzi	کشاورزی	5
Refah Kargaran	رفاه کارگران	6
Pasargad	پاسارگاد	7
Sepah	سپه	8
Saderat	صادرات	9
Resalat	رسالت	10
Ayande	آینده	13
Maskan	مسکن	14
Saman	سامان	15
Parsian	پارسیان	18

2. Transfer types

Name	Persian Name	Code
A2A	حساب به حساب	0
Paya	پایا	1
Satna	ساتنا	2

3. Transfer Status

The statuses follow the sequence in which they are applied during the transaction process.

Status Code	Status Description	Persian Description
0	Created	ایجاد شده
16	Pending Signature	در انتظار امضا
18	Pending Execution	در انتظار اجرا
14	Executing	در حال اجرا
2	Submitted	ارسال شده
4	Verified	تایید شده
6	Transferred	منتقل شده
8	Failed	ناموفق
9	System Failed	خطای سیستمی
10	Canceled	لغو شده
12	Unknown	نا معلوم

4. Transfer Reason

Name	Persian Name	Code
salary deposit	واریز حقوق	1
insurance services	امور بیمه خدمات	2
medical services	امور درمانی	3
investment and stock	امور سرمایه گذاری و بورس	4
foreign currency operations	امور ارزی در چهارچوب ضوابط و مقررات	5
bill payment debt settlement	پرداخت قبض و تادیه دیون(قرض الحسنه، بدهی، ...)	6
retirement services	امور بازنشستگی	7
movable asset transactions	معاملات اموال منقول	8
immovable asset transactions	معاملات اموال غیر منقول	9
liquidity management	مدیریت نقدینگی	10
customs duties	عوارض گمرکی	11
tax settlement	تسویه مالیاتی	12
other government services	سایر خدمات دولتی	13
facilities commitments	تسهیلات و تعهدات	14
collateral deposit	تودیع وثیقه	15
general expenses daily affairs	هزینه عمومی و امور روزمره	16
charitable donations	کمک های خیریه	17
goods purchase	خرید کالا	18
services purchase	خرید خدمات	19

5. Payment_id supporting banks

Only the banks listed below support the use of payment IDs.

Name	Code
Saman	15

6. Creation type

Code	Type	Persian Description
0	Single by API	انتقال تکی از طریق API
4	Single by Web	انتقال تکی از طریق وب
8	Bulk by API	انتقال گروهی از طریق API
12	Bulk by Web	انتقال گروهی از طریق وب

APIs

1. Account

1.1 Get List of Accounts

Use to get all Accounts record with pagination.

import requests

url = "https://dbank.toman.ir/api/v1/account/"

payload = {}
headers = {
    'Authorization': 'Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'
}

response = requests.request("GET", url, headers=headers, data=payload)

curl --location 'https://dbank.toman.ir/api/v1/account/' \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'

`GET /account/`

Scope

digital_banking.account.read

Request Body

Without any request body.

Response Body

The response of this endpoint is as following:

It is in pagination schema with results that is an array of account

Query Parameters

Parameter	Type	Description	Example
bank_id	int	Filter by bank id	/account/?bank_id=15
iban	str	Filter by IBAN	/account/?iban=IR460170000000111111130001
search	str	Search by iban	/account/?search=IR460170000000111111130001

Response Data Example

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "bank_id": 2,
      "iban": "IR460170000000111111130001",
      "account_number": "0111111130001",
      "account_owner": "elecom 1 ",
      "active": true,
      "last_update_balance_at": "2022-10-04",
      "pinned": true,
      "balance": 200000,
      "credential": [
        1,
        2
      ],
      "opening_date": "2024-08-07"
    },
    {
      "id": 2,
      "bank_id": 2,
      "iban": "IR460170000000111111130002",
      "account_number": "0111111130002",
      "account_owner": "elecom 2 ",
      "active": true,
      "last_update_balance_at": "2022-10-04",
      "pinned": false,
      "balance": 200000,
      "credential": [
        1,
        2
      ],
      "opening_date": "2024-08-07"
    },
    {
      "id": 3,
      "bank_id": 2,
      "iban": "IR460170000000111111130003",
      "account_number": "0111111130003",
      "account_owner": "elecom 3 ",
      "active": true,
      "last_update_balance_at": "2022-10-04",
      "pinned": false,
      "balance": 200000,
      "credential": [
        1,
        2
      ],
      "opening_date": "2024-08-07"
    }
  ]
}

1.2 Get an Account

Use to retrieve an existence Account record by ID.

import requests

url = "https://dbank.toman.ir/api/v1/account/12/"

payload = {}
headers = {
    'Authorization': 'Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'
}

response = requests.request("GET", url, headers=headers, data=payload)

curl --location 'https://dbank.toman.ir/api/v1/account/12/' \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'

`GET /account/<id>/`

Scope

digital_banking.account.read

Request Body

Without any request body.

Response Body

The response of this endpoint is as follows:

Response body is account

Response Data Example

{
  "id": 2,
  "bank_id": 2,
  "iban": "IR460170000000111111130001",
  "account_number": "0111111130001",
  "account_owner": "elecom",
  "active": true,
  "credential": [
    1,
    2,
    3
  ],
  "opening_date": "2022-10-04",
  "last_update_balance_at": "2024-10-04",
  "balance": 200000,
  "pinned": false
}

1.3 Retrieve an account's statements

Used to retrieve the statement records of an existing account by its ID.

import requests

url = "https://dbank.toman.ir/api/v1/account/12/statement/"

payload = {}
headers = {
    'Authorization': 'Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'
}

response = requests.request("GET", url, headers=headers, data=payload)

curl --location 'https://dbank.toman.ir/api/v1/account/12/statement/' \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'

`GET /account/<id>/statement/`

Scope

digital_banking.statement.read

Query Parameters

Parameter	Type	Description	Example
page_size	int	Number of records per page	/statement/?page_size=50
page	int	Page number for pagination	/statement/?page=2
amount__lte	int	Filter by maximum transaction amount	/statement/?amount__lte=1000000
amount__gte	int	Filter by minimum transaction amount	/statement/?amount__gte=500
side	string	Filter by transfer side (e.g., `credit` or `debit`)	/statement/?side=True
transaction_datetime_from	string	Filter transactions from this datetime	/statement/?transaction_datetime_from=2025-01-01T00:00:00
transaction_datetime_to	string	Filter transactions until this datetime	/statement/?transaction_datetime_to=2025-01-01T23:59:59
created_at__lte	string	Filter by Toman fetch time	/statement/?created_at__lte=2025-01-01T23:59:59
created_at__gte	string	Filter by Toman fetch time	/statement/?created_at__gte=2025-01-01T00:00:00

Response Data Example

{
  "count": 123456,
  "next": "{base_url}/account/12345/statement/?page=3&page_size=5",
  "previous": "{base_url}/account/12345/statement/?page_size=5",
  "results": [
    {
      "id": 1234,
      "amount": -213213,
      "side": false,
      "tracing_number": "B0331231231649623307",
      "transaction_datetime": "2055-01-05T03:33:13Z",
      "created_at": "2025-01-05T02:37:22.414085Z",
      "payment_id": null,
      "source_account": null
    },
    {
      "id": 6892011,
      "amount": -624100,
      "side": false,
      "tracing_number": "B0310165010649622835",
      "transaction_datetime": "2025-01-05T03:32:38Z",
      "created_at": "2025-01-05T03:37:22.414121Z",
      "is_normalized": false,
      "payment_id": null,
      "source_account": null
    },
    {
      "id": 6892012,
      "amount": -954400,
      "side": false,
      "tracing_number": "B0310165010649622638",
      "transaction_datetime": "2025-01-05T03:32:22Z",
      "created_at": "2025-01-05T03:37:22.414156Z",
      "is_normalized": false,
      "payment_id": null,
      "source_account": null
    },
    {
      "id": 6892013,
      "amount": -228600,
      "side": false,
      "tracing_number": "B0310165010649622148",
      "transaction_datetime": "2025-01-05T03:31:47Z",
      "created_at": "2025-01-05T03:37:22.414192Z",
      "is_normalized": false,
      "payment_id": null,
      "source_account": null
    },
    {
      "id": 6892014,
      "amount": -1083600,
      "side": false,
      "tracing_number": "B0310165010649618996",
      "transaction_datetime": "2025-01-05T03:27:42Z",
      "created_at": "2025-01-05T03:37:22.414226Z",
      "is_normalized": false,
      "payment_id": null,
      "source_account": null
    }
  ]
}

1.4 Retrieve an Account's Statements as CSV

Used to retrieve the statement records of an existing account in CSV format by its ID.

import requests

url = "https://dbank.toman.ir/api/v1/account/12/statement_as_csv/"

payload = {}
headers = {
    'Authorization': 'Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'
}

response = requests.request("GET", url, headers=headers, data=payload)

curl --location 'https://dbank.toman.ir/api/v1/account/12/statement_as_csv/' \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'

`GET /account/<id>/statement_as_csv/`

Scope

digital_banking.statement.read

Request Body

Response Body

Response Data Example

1.5 Retrieve All Banks Summary

This endpoint retrieves a summary of all banks, including the total balance and the number of accounts for each bank. The response includes:

results: An array of objects, each containing a bank's ID, total balance across all accounts, and the number of accounts associated with that bank. bank_id_list: A list of all the bank IDs included in the summary. sum_balance: The total balance across all banks. account_count: The total number of active accounts across all banks.

import requests

url = "https://dbank.toman.ir/api/v1/account/general_info/"

payload = {}
headers = {
    'Authorization': 'Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'
}

response = requests.request("GET", url, headers=headers, data=payload)

curl --location 'https://dbank.toman.ir/api/v1/account/general_info/' \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'

`GET /account/general_info/`

Scope

digital_banking.statement.read

Response Data Example

{
  "results": [
    {
      "bank_id": 2,
      "sum_balance": 18332710854,
      "account_count": 1
    },
    {
      "bank_id": 18,
      "sum_balance": 8506105885,
      "account_count": 1
    },
    {
      "bank_id": 15,
      "sum_balance": 2702822298,
      "account_count": 4
    },
    {
      "bank_id": 10,
      "sum_balance": 126229126,
      "account_count": 1
    },
    {
      "bank_id": 1,
      "sum_balance": 10805665753,
      "account_count": 1
    }
  ],
  "bank_id_list": [
    2,
    18,
    15,
    10,
    1
  ],
  "sum_balance": 40473533916,
  "account_count": 8
}

1.6 Retrieve a Bank Summary

This endpoint retrieves a summary of a specific bank, including the total balance and the number of accounts for that bank. The response includes:

balance: The total balance across all accounts for the specified bank. count: The total number of connected accounts for the specified bank.

import requests

url = "https://dbank.toman.ir/api/v1/account/bank/<id>/"

payload = {}
headers = {
    'Authorization': 'Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'
}

response = requests.request("GET", url, headers=headers, data=payload)

curl --location 'https://dbank.toman.ir/api/v1/account/bank/<id>/' \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'

`GET /account/bank/<id>/`

Scope

digital_banking.statement.read

Response Data Example

{
  "balance": 18324565054,
  "count": 1
}

2. Transfer

2.1 Get List of Transfers

Use to get all Transfers record with pagination.

import requests

url = "https://dbank.toman.ir/api/v1/transfer/"

headers = {
    'Authorization': 'Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'
}

response = requests.request("GET", url, headers=headers)

curl --location 'https://dbank.toman.ir/api/v1/transfer/' \
--header '
Authorization : Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'

`GET /transfer/`

Scope

digital_banking.transfer.read

Request Body

Without any request body.

Query Parameters

Parameter	Type	Description	Example
bank_id	int	Filter by bank id. Refer to Bank Ids	/transfer/?bank_id=15
transfer_type	int	Filter by transfer type. Refer to Transfer types	/transfer/?transfer_type=1
account	int	Filter by account id	/transfer/?account=11
status__in	int	Filter by status	/transfer/?status__in=8
search	str	Search by uuid, account_number_destination, iban_destination, account__account_number and account__iban	/transfer/?search=1234
creation_type__in	int	Filter by creation type	/transfer/?creation_type__in=4
iban_destination	str	Filter by iban_destination	/transfer/?iban_destination=IR460170000000111111130003
account_number_destination	str	Filter by account_number_destination	/transfer/?account_number_destination=0228939030001

Response Body

The response of this endpoint is as following:

It is in pagination schema with results that is an array of transfer

Response Data Example

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "uuid": "2e30029e-620b-41e6-8be5-ab69b421cec3",
      "bank_id": 1,
      "transfer_type": 1,
      "status": 8,
      "amount": 1000,
      "created_by": 1,
      "iban_destination": "",
      "account_number_destination": "",
      "card_number_destination": "",
      "description": "decscription",
      "first_name": "mohamad",
      "last_name": "akbari",
      "reason": 1,
      "tracker_id": "ed526da7-073e-4f41-bb2c-c811d8ad727a",
      "account_number_source": "0228939030001",
      "iban_source": "IR460170000000228939030001",
      "created_at": "2024-12-08T12:52:46.244217Z",
      "creation_type": 4,
      "bank_id_destination": 2,
      "follow_up_code": null,
      "payment_id": null
    },
    {
      "uuid": "2e30029e-620b-41e6-8be5-ab69b421cec3",
      "bank_id": 1,
      "transfer_type": 1,
      "status": 8,
      "amount": 1000,
      "created_by": 1,
      "iban_destination": "",
      "account_number_destination": "",
      "card_number_destination": "",
      "description": "decscription",
      "first_name": "mohamad",
      "last_name": "akbari",
      "reason": 1,
      "tracker_id": "ed526da7-073e-4f41-bb2c-c811d8ad727a",
      "account_number_source": "0228939030001",
      "iban_source": "IR460170000000228939030001",
      "created_at": "2024-12-08T12:52:46.244217Z",
      "creation_type": 4,
      "bank_id_destination": 2,
      "follow_up_code": null,
      "payment_id": null
    }
  ]
}

2.2 Get a Transfer

Use to retrieve a Transfer record by uuid.

import requests

url = "https://dbank.toman.ir/api/v1/transfer/2e30029e-620b-41e6-8be5-ab69b421cec3"

headers = {
    'Authorization': 'Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'
}

response = requests.request("POST", url, headers=headers)

curl --location 'https://dbank.toman.ir/api/v1/transfer/2e30029e-620b-41e6-8be5-ab69b421cec3' \
--header ' Authorization : Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'

`GET /transfer/<uuid>/`

Scope

digital_banking.transfer.read

Request Body

Without any request body.

Response Body

The response of this endpoint is transfer

Response Data Example

{
  "uuid": "2e30029e-620b-41e6-8be5-ab69b421cec3",
  "bank_id": 1,
  "account": 11,
  "transfer_type": 1,
  "status": 8,
  "amount": 1000,
  "created_by": 1,
  "iban_destination": "",
  "account_number_destination": "",
  "card_number_destination": "",
  "description": "decscription",
  "first_name": "mohamad",
  "last_name": "akbari",
  "reason": 1,
  "tracker_id": "ed526da7-073e-4f41-bb2c-c811d8ad727a",
  "account_number_source": "0228939030001",
  "iban_source": "IR460170000000228939030001",
  "created_at": "2024-12-08T12:52:46.244217Z",
  "creation_type": 4,
  "bank_id_destination": 2,
  "follow_up_code": "1234",
  "payment_id": "ABCD"
}

2.3 Create a Transfer

Used to create a transfer request.

import requests

url = "https://dbank.toman.ir/api/v1/transfer/"

payload = {
    "bank_id": 1,
    "account": 11,
    "transfer_type": 1,
    "amount": 1000,
    "iban_destination": "",
    "card_number_destination": "124321",
    "account_number_destination": "",
    "description": "decscription",
    "first_name": "mohamad",
    "last_name": "akbari",
    "reason": 1,
    "tracker_id": "1112",
    "payment_id": "12345",
}
headers = {
    'Authorization': 'Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'
}

response = requests.request("POST", url, headers=headers, data=payload)

curl --location 'https://dbank.toman.ir/api/v1/transfer/' \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'
 --data '{
    "bank_id": 1,
    "account": 11,
    "transfer_type": 1,
    "amount": 1000,
    "iban_destination": "",
    "card_number_destination": "124321",
    "account_number_destination": "",
    "description": "decscription",
    "first_name": "mohamad",
    "last_name": "akbari",
    "reason": 1,
    "tracker_id": "1112",
    "payment_id": "12345",
    }'

`POST /transfer/`

Scope

digital_banking.transfer.create

Request Body

Parameter	Type	Description	Example
bank_id	Integer	Payment made at this bank ID. Must be one of the values in the Bank IDs section.	15
account	Integer	ID of the account to transfer money from.	2
transfer_type	Integer	Transfer types	1
amount	Integer	Amount of Transfer.	1500000
iban_destination [Optional]	String	The IBAN number (شماره شبا) of the destination account. Leave empty if transferring to a card or account number.	""
account_number_destination [Optional]	String	Account number (شماره حساب) of the destination account. Leave empty if transferring to a card or IBAN	""
card_number_destination [Optional]	String	The Card number (شماره کارت) of the destination account. Leave empty if transferring to a account or IBAN.	""
description [Optional]	String	Additional details or description of the transfer.	"description"
first_name [Optional]	String	First name of the recipient.	"mohamad"
last_name [Optional]	String	Last name of the recipient.	"akbari"
reason [Optional]	Integer	Transfer Reason	1
payment_id [Optional]	String	Payment ID.	"12345"

Response Body

The response of this endpoint is transfer

Response Data Example

{
  "uuid": "2e30029e-620b-41e6-8be5-ab69b421cec3",
  "bank_id": 1,
  "account": 11,
  "transfer_type": 1,
  "status": 8,
  "amount": 1000,
  "description": "decscription",
  "first_name": "mohamad",
  "last_name": "akbari",
  "reason": 1,
  "tracker_id": "1112",
  "account_number_source": "0228939030001",
  "iban_source": "IR460170000000228939030001",
  "iban_destination": null,
  "account_number_destination": "826-40-2900665-1",
  "card_number_destination": null,
  "created_at": "2024-12-10T13:44:36.748997Z",
  "created_by": 2,
  "creation_type": 4,
  "bank_id_destination": 2,
  "follow_up_code": null,
  "payment_id": null
}

Potential Errors

In addition to standard errors, the following error codes may be encountered during operations:

Error Code	Description
`unsupported_payment_id`	The `payment_id` feature is supported only by specific banks.
`account_not_belong_to_partner`	The source account does not belong to the associated partner.
`transfer_integrity_exception`	The `tracker_id` provided is not unique; each `tracker_id` must be unique per partner.
`selected_account_does_not_belong_to_this_bank`	The source account does not match the specified `bank_id`.
`account_not_found`	The specified source account could not be found under the partner's ownership.
`can_not_transfer_from_inactive_account`	Transfers cannot be initiated from an inactive account.
`Transfer_from_Account_permission_denied`	You do not have the required permission to perform transfers from this account.
`max_amount_transfer_denied`	The transfer amount exceeds the maximum permissible limit.
`max_amount_per_day_transfer_denied`	The total transfer amount for the day has exceeded the allowed limit.

2.4 Sign Transfer

Used to sign a transfer request.

import requests

url = "https://dbank.toman.ir/api/v1/transfer/2e30029e-620b-41e6-8be5-ab69b421cec3/sign/"

headers = {
    'Authorization': 'Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'
}

response = requests.request("POST", url, headers=headers)

curl --location 'https://dbank.toman.ir/api/v1/transfer/2e30029e-620b-41e6-8be5-ab69b421cec3/sign/' \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'

`POST /transfer/<uuid>/sign/`

Scope

digital_banking.transfer.sign

Request Body

Without any request body.

Response Body

The response of this endpoint is a confirmation of the transfer signing.

Response Data Example

{
  "detail": "Transfer signed."
}

2.5 Execute Transfer

Used to execute a transfer request after it has been signed.

import requests

url = "https://dbank.toman.ir/api/v1/transfer/2e30029e-620b-41e6-8be5-ab69b421cec3/execute/"

headers = {
    'Authorization': 'Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'
}

response = requests.request("POST", url, headers=headers)

curl --location 'https://dbank.toman.ir/api/v1/transfer/2e30029e-620b-41e6-8be5-ab69b421cec3/execute/' \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'

`POST /transfer/<uuid>/execute/`

Scope

digital_banking.transfer.execute

Response Data Example

{
  "detail": "Transfer executed."
}

2.6 Cancel Transfer

Used to cancel an existing transfer request.


import requests

url = "https://dbank.toman.ir/api/v1/transfer/2e30029e-620b-41e6-8be5-ab69b421cec3/cancel/"

headers = {
    'Authorization': 'Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'
}

response = requests.request("POST", url, headers=headers)

curl --location 'https://dbank.toman.ir/api/v1/transfer/2e30029e-620b-41e6-8be5-ab69b421cec3/cancel/' \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'

`POST /transfer/<uuid>/cancel/`

Scope

digital_banking.transfer.cancel

Response Data Example

{
  "detail": "Transfer canceled."
}

2.7 Generate Receipt

To generate a pdf receipt for a transaction.

import requests

url = "https://dbank.toman.ir/api/v1/transfer/5c00a051-cb80-4602-9f99-e1a3b4d5c1db/generate-receipt/"

headers = {
    'Authorization': 'Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'
}

response = requests.request("POST", url, headers=headers)

curl --location 'https://dbank.toman.ir/api/v1/transfer/5c00a051-cb80-4602-9f99-e1a3b4d5c1db/generate-receipt/' \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'

`POST /transfer/<uuid>/generate-receipt/`

Scope

digital_banking.transfer.generate_receipt

Response Body

The response of this endpoint is a pdf file.