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)
Sample Code (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)
Sample Code (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"
}
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.
Sample Code
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
orpassword
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.
Models
This section introduces the models used in the Corporate Banking service for requests and 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 |
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 | String | The reason for the transfer. | "test" |
tracker_id | String (36) | Tracker ID that you can follow your transfer with. | "1112" |
created_by | Integer | ID of the user who created the transfer. | 1 |
created_at | datetime | date time created the transfer. | 1 |
Enums
1. Bank IDs
Each bank has a unique numeric identifier. The mapping is as follows.
Name | Persian Name | Code |
---|---|---|
Melli | ملی | 2 |
Saman | سامان | 15 |
2. Transfer types
Name | Persian Name | Code |
---|---|---|
A2A | حساب به حساب | 0 |
Paya | پایا | 1 |
Satna | ساتنا | 2 |
3. Transfer Status
Name | Code |
---|---|
created | 0 |
submitted | 2 |
verified | 4 |
transferred | 6 |
failed | 8 |
APIs
1. Base URLs
The base URLs for our staging and production API servers are
Environment | URL |
---|---|
Production | https://dbank.toman.ir/api/v1/ |
Staging | https://dbank-staging.qcluster.org/api/v1/ |
Note: Please pay attention to trailing slash at the end of the urls for all endpoints.
2. Pagination Schema
All Corporate Banking service endpoints responses follow the page pattern, structured in a paginated response.
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 this page's items | "https://dbank.toman.ir/api/v1/account/?page=3" |
previous | String (Nullable) | The URL of the next page containing items after this page's items | "https://dbank.toman.ir/api/v1/account/?page=1" |
results | Array[Object] | The array containing the items of this page |
3. Account
3.1 Get a Account
Use to retrieve an existence Account record by id.
Sample Code
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",
"partner": 1,
"balance": 200000
}
3.2 Get List of Accounts
Use to get all Accounts record with pagination.
Sample Code
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
},
{
"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
},
{
"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
}
]
}
4. Transfer
4.1 Get a Transfer
Use to retrieve a Transfer record by uuid.
Sample Code
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": "test",
"tracker_id": "ed526da7-073e-4f41-bb2c-c811d8ad727a"
}
4.2 Get List of Transfers
Use to get all Transfers record with pagination.
Sample Code
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 | /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 |
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,
"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": "test",
"checkout_uuid": "63ea0707-7de2-447e-ae3a-cae8b7680fe8",
"tracker_id": "ed526da7-073e-4f41-bb2c-c811d8ad727a"
},
{
"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": "test",
"checkout_uuid": "63ea0707-7de2-447e-ae3a-cae8b7680fe8",
"tracker_id": "ed526da7-073e-4f41-bb2c-c811d8ad727a"
}
]
}
4.3 Create a Transfer
To create a Transfer request.
Sample Code
import requests
url = "https://dbank.toman.ir/api/v1/transfer/"
payload = {
"transfer_type": 1,
"bank_id": 1,
"amount": 1000,
"tracker_id": "1112",
"account": 11,
"card_number_destination": "124321",
"account_number_destination": "",
"iban_destination": "",
"first_name": "mohamad",
"last_name": "akbari",
"reason": "test",
"description": "decscription"
}
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 '{
"transfer_type": 1,
"bank_id": 1,
"amount": 1000,
"tracker_id": "1112",
"account": 11,
"card_number_destination": "124321",
"account_number_destination": "",
"iban_destination": "",
"first_name": "mohamad",
"last_name": "akbari",
"reason": "test",
"description": "decscription"
}'
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 | String | The reason for the transfer. | "test" |
tracker_id | String (36) | Tracker ID to follow the transfer (must be 36 characters). | "5641316546aaa" |
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": "test",
"tracker_id": "1112",
"checkout_uuid": "2e30029e-620b-41e6-8be5-ab69b421cec3"
}