NAV
cURL Python

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

400_INVALID_GRANT

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

Reasons

401_INVALID_CLIENT

{
    "error"
:
    "invalid_client"
}

Reasons

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 Integer Transfer Reason 1
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

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

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": 1,
  "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": 1,
      "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": 1,
      "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": 1,
    "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": 1,
    "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 Integer Transfer Reason 1
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": 1,
  "tracker_id": "1112",
  "checkout_uuid": "2e30029e-620b-41e6-8be5-ab69b421cec3"
}

4.4 Generate Receipt

To generate a pdf receipt for a transaction.

Sample Code

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.

cURL Python