Introduction

This is Toman's Settlement API Reference.

Models

Settlement

The entity representing the request to transfer a specific amount of cash to an account.

Parameter	Type	Description	Example
uuid	String	A UUID 4 string which uniquely identifies the transaction. This field is generated by Toman when the partner submits a new settlement	"dc5f4898-2d82-4263-b2da-47171304cb96"
description	String	The description of the transaction	"تسویه حساب ارزی"
full_name	String	The full name of the account owner	"احمد احمدی"
amount	Int	The transfer amount (in Rials)	250000000
bank_id	Int	The ID of the destination bank. Is one of values in the Bank IDs section	4
iban	String	The IBAN of the destination account	"IR123456789012345678901234"
account_number	String (Nullable)	The account number of the destination account.	"1234567890123456"
card_number	String (Nullable)	The card number of the destination account.	"6037123456789012"
bank_followup_code	String (Nullable)	The transaction's follow up code provided by the bank	1
status	Int	The transaction's status code. Is one of Status codes	3
create_timestamp	String (ISO-8601 Date)	The exact time of the creation of this settlement	"2020-05-29T08:02:27.912352Z"
update_timestamp	String (ISO-8601 Date)	The exact time of the last modification on this settlement	"2020-05-29T08:02:27.912510Z"
verify_timestamp	String (ISO-8601 Date)	The exact time of the verification of this settlement	"2020-05-29T08:02:29.912510Z"
detail	String (Nullable)	The details of the last response/error came back from bank server for this transaction	"Read Timeout"
tracker_id	String (Nullable)	The identifier of this settlement, assigned by partner upon its creation. Note that the uniqueness of this field's value is not guaranteed.	"trx7238"
jalali_verify_datetime	String (ISO-8601 Date) (Nullable)	The date of verifcation of settlement in Jalali Calendar	1401/11/03 11:53:48
commission	Int (Nullable)	The amount of the commission for each settlement which is currently only calculated and has a display mode (The commission in not deducted from partner wallet)

SettlementChangeLog

The entity representing each Status change of a Settlement entity from a final status to any status.

Parameter	Type	Description	Example
uuid	String	A UUID 4 string which uniquely identifies the entity. This field is generated by Toman when a Settlement Status changes from a final status to any status	"dc5f4898-2d82-4263-b2da-47171304cb96"
from_status	Int	The status code that the change is happened from. Is one of final Status codes	3
to_status	Int	The status code that the change is happened to. Is one of Status codes	2
settlement	Settlement	The Settlement that the change is happened on
changed_timestamp	String (ISO-8601 Date)	The exact time of the creation of this change log	"2020-05-29T08:02:27.912510Z"

Bulk

The entity representing a group of Settlements.

Parameter	Type	Description	Example
uuid	String	A UUID 4 string which uniquely identifies the bulk. This field is generated by Toman when the partner submits a new bulk settlement	"34fe1773-040e-4bb0-8198-0cd72510c03b"
description	String	The description of the bulk of transactions	"تراکنش توضیحات"
bank_id	String	The ID of the destination bank. Is one of values in the Bank IDs section.	9
tracker_id	String (Nullable)	The identifier of this bulk, assigned by partner upon its creation. Note that the uniqueness of this field's value is not guaranteed.	"trx7238"
status	String	The bulk's overall status code. Is one of Status codes	0
create_timestamp	String (ISO-8601 Date)	The exact time of the creation of this bulk settlement	"2020-05-29T08:02:27.912352Z"
update_timestamp	String (ISO-8601 Date)	The exact time of the last modification on this bulk settlement	"2020-05-29T08:02:27.912510Z"
settlements	Array[Settlement]	List of Settlements in this bulk

Wallet

The entity representing the credit of a partner in a specific bank.

Parameter	Type	Description	Example
bank_id	Int	The ID of the related bank. Is one of values in the Bank IDs section	183
balance	Int	The current balance of the wallet (in Rials)	1200000000
balance_warning_threshold	Int	The threshold from which if the balance value drops lower, the partner will be notified	100000000

Bank

The entity representing state of a bank service in our system

Parameter	Type	Description	Example
id	Int	The ID of the related bank. Is one of values in the Bank IDs section	1
bank_name	String	The human readable name of the bank	"shahr"
is_active	Boolean	Whether the bank is currently active	true
last_down_time	String (ISO-8601 Date) (Nullable)	Last time the bank was inactive	"2020-05-29T08:02:27.912352Z"
queue_available	Boolean	Whether the requests to this bank will be queued in case of an outage	true

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	رفاه کارگران	6
Pasargad	پاسارگاد	7
Sepah	سپه	8
Saderat	صادرات	9
Resalat	رسالت	10
Ayande	آینده	13
Maskan	مسکن	14
Saman	سامان	15
Parsian	پارسیان	18
Paya	پایا	100

Status

The status of each settlement is represented as a number. Different possible statuses for a settlement can be find below.

Status	Code	Description
Unknown	-1	There was an error, but the state cannot be determined automatically
Created	0	Transaction has been created (available only for two-step transactions)
Failed	1	Transaction has failed
Pending	2	Transaction is still in progress
Success	3	Transaction has completed successfully
Canceled	4	Transaction has been cancelled by the user (available only for two-step transactions)
Expired	5	Transaction is expired (available only for two-step transactions)
Disapproved	6	Transaction was disapproved by user (available only for two-step transactions)
Denied	8	There is an error in the transaction; e.g. account number is wrong

Bank Status

Parameter	Type	Description	Example
id	Integer	This is the ID of the Bank. See Bank ID's	1
*bank_name*	String	This is the name of the Bank.	"pasargad"
is_active	Boolean	Whether the Bank is active or inactive.	true
queue_available	Boolean	Whether the Bank queues up the requests when it is unavailable to process them when it's available again.	true
last_down_time	String (ISO-8601 Date)	This is the last time the Bank was down.	"2023-01-20T20:10:00.031696Z"
active_since	String (ISO-8601 Date)	This the time the Bank has been active since.	"2023-01-20T20:35:00.415698Z"

Endpoints

Base URLs

The base URLs for our staging and productions API servers are:

Environment	URL
Production	`https://settlement.tomanpay.net`
Staging	`https://settlement-staging.qbitpay.org`

Settlements and transactions in both services are REAL.

Response Schema

Page

All settlement endpoint responses, follow the page pattern, structured in a paginated response.

Parameter	Type	Description	Example
count	Int	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://tomanpay.net/api/settlements/?page=3"
previous	String (Nullable)	The URL of the next page containing items after this page's items	"https://tomanpay.net/api/settlements/?page=1"
results	Array[Object]	The array containing the items of this page

Submit Single Settlement (Two-Step)

Creates a new Two-Step Settlement.

For Two-Step Settlements, you need to verify them later to start processing them, using the verify API.

import requests
import json

url = f"{base_url}/settlements/"

payload = json.dumps(
    {
        "description": "تسویه حساب ارزی",
        "bank_id": 9,
        "tracker_id": "5bd4b902-a8f8-4440-b514-d12ce7c53db0",
        "full_name": "احمد احمدی",
        "amount": 10000,
        "iban": "IR123456789012345678901234",
        "account_number": "1234567890123456"
    }
)

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}

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

curl --location -g --request POST "$BASE_URL/settlements/" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" \
--data-raw '{
    "description": "تسویه حساب ارزی",
    "bank_id": 9,
    "tracker_id": "5bd4b902-a8f8-4440-b514-d12ce7c53db0",
    "full_name": "احمد احمدی",
    "amount": 10000,
    "iban": "IR123456789012345678901234",
    "account_number": "1234567890123456",
}'

`POST /settlements/`

Scope

settlement.single.submit

Request Body

Parameter	Type	Description	Example
amount	Int	The transfer amount (in Rials)	250000000
account_number	String (Optional)	The account number of the destination account.	"1234567890123456"
iban	String	The IBAN of the destination account	"IR123456789012345678901234"
bank_id	String (Optional)	The ID of the destination bank. Is one of values in the Bank IDs section.	9
tracker_id	String (Optional, Unique)	The identifier of this settlement, assigned by partner upon its creation. Note that the uniqueness of this field's value will be checked if not be Null.We recommend using the UUID as the value.	"5bd4b902-a8f8-4440-b514-d12ce7c53db0"
full_name	String (Optional)	The full name of the account owner	"احمد احمدی"
description	String (Optional)	The description of the settlement	"تراکنش توضیحات"

Response Body

Parameter	Type	Description	Example
uuid	String	A UUID 4 string which uniquely identifies the transaction. This field is generated by Toman when the partner submits a new settlement	"dc5f4898-2d82-4263-b2da-47171304cb96"
description	String	The description of the transaction	"تسویه حساب ارزی"
full_name	String	The full name of the account owner	"احمد احمدی"
amount	Int	The transfer amount (in Rials)	250000000
bank_id	Int	The ID of the destination bank. Is one of values in the Bank IDs section	4
iban	String	The IBAN of the destination account	"IR123456789012345678901234"
account_number	String (Nullable)	The account number of the destination account.	"1234567890123456"
card_number	String (Nullable)	The card number of the destination account.	"6037123456789012"
bank_followup_code	String (Nullable)	The transaction's follow up code provided by the bank	1
status	Int	The transaction's status code. Is one of Status codes	3
create_timestamp	String (ISO-8601 Date)	The exact time of the creation of this settlement	"2020-05-29T08:02:27.912352Z"
update_timestamp	String (ISO-8601 Date)	The exact time of the last modification on this settlement	"2020-05-29T08:02:27.912510Z"
verify_timestamp	String (ISO-8601 Date)	The exact time of the verification of this settlement	"2020-05-29T08:02:29.912510Z"
detail	String (Nullable)	The details of the last response/error came back from bank server for this transaction	"Read Timeout"
tracker_id	String (Optional, Unique)	The identifier of this settlement, assigned by partner upon its creation.	"5bd4b902-a8f8-4440-b514-d12ce7c53db0"
receipt_link	String (Nullable)	The public URL of the settlement which you can give to your customers.	"https://settlement.toman.ir/receipt/settlement/6b15ae8c-ebc1-456d-8889-843654240600:Av34rD87a3dr326123asdfuwersdfvawBGEsJKLGaweLKJG"
displayed_commission	Int (Nullable)	The amount of commission which is not deducted from partner's wallet and has a display mode

Request Data Example

{
  "bank_id": 1,
  "amount": 1000,
  "iban": "IR123456789012345678901234",
  "account_number": "1234567890123456",
  "description": "test"
}

Recommended Request Data Example

{
  "amount": 1000,
  "iban": "IR123456789012345678901234",
  "tracker_id": "5bd4b902-a8f8-4440-b514-d12ce7c53db0"
}

The most concise possible request body example that allows Toman service to consider the best decision for making a transaction is as mentioned above (recommended request body).

Response Data Example


{
  "uuid": "997cbaf2-f405-493d-acfc-107fd1ae8914",
  "description": "test",
  "full_name": null,
  "amount": 1000,
  "bank_id": 1,
  "iban": "IR123456789012345678901234",
  "account_number": "1234567890123456",
  "bank_follow_up_code": null,
  "status": 0,
  "create_timestamp": "2023-01-17T11:41:14.001474Z",
  "update_timestamp": "2023-01-17T11:41:14.001537Z",
  "detail": null,
  "bulk_row_id": null,
  "tracker_id": "5bd4b902-a8f8-4440-b514-d12ce7c53db0",
  "jalali_verify_datetime": null,
  "displayed_commission": 100
}

Exception

{
  "detail": "value of tracker_id is duplicated."
}

If the tracker_id value be duplicated, the 400 status will be return with the above body.

Verify Single Settlement (Two-Step)

You need to verify a two-step settlement for it to start to process. This Endpoint will verify an already created settlement.

import requests

url = f"{base_url}/settlements/<uuid>/verify"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}

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

curl --location -g --request POST "$BASE_URL/settlements/<uuid>/verify" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json"

`POST /settlements/\<UUID\>/verify`

Scope

settlement.single.verify

Request Body

Empty

Response Body

Parameter	Type	Description	Example
uuid	String	A UUID 4 string which uniquely identifies the transaction. This field is generated by Toman when the partner submits a new settlement	"dc5f4898-2d82-4263-b2da-47171304cb96"
description	String	The description of the transaction	"تسویه حساب ارزی"
full_name	String	The full name of the account owner	"احمد احمدی"
amount	Int	The transfer amount (in Rials)	250000000
bank_id	Int	The ID of the destination bank. Is one of values in the Bank IDs section	4
iban	String	The IBAN of the destination account	"IR123456789012345678901234"
account_number	String (Nullable)	The account number of the destination account.	"1234567890123456"
card_number	String (Nullable)	The card number of the destination account.	"6037123456789012"
bank_followup_code	String (Nullable)	The transaction's follow up code provided by the bank	1
status	Int	The transaction's status code. Is one of Status codes	3
create_timestamp	String (ISO-8601 Date)	The exact time of the creation of this settlement	"2020-05-29T08:02:27.912352Z"
update_timestamp	String (ISO-8601 Date)	The exact time of the last modification on this settlement	"2020-05-29T08:02:27.912510Z"
verify_timestamp	String (ISO-8601 Date)	The exact time of the verification of this settlement	"2020-05-29T08:02:29.912510Z"
detail	String (Nullable)	The details of the last response/error came back from bank server for this transaction	"Read Timeout"
tracker_id	String (Nullable)	The identifier of this settlement, assigned by partner upon its creation.	"5bd4b902-a8f8-4440-b514-d12ce7c53db0"
jalali_verify_datetime	String (ISO-8601 Date) (Nullable)	The date of verifcation of settlement in Jalali Calendar	1401/11/03 11:53:48
receipt_link	String (Nullable)	The public URL of the settlement which you can give to your customers.	"https://settlement.toman.ir/receipt/settlement/6b15ae8c-ebc1-456d-8889-843654240600:Av34rD87a3dr326123asdfuwersdfvawBGEsJKLGaweLKJG"
displayed_commission	Int (Nullable)	The amount of commission which is not deducted from partner's wallet and has a display mode

Response Data Example

{
  "uuid": "997cbaf2-f405-493d-acfc-107fd1ae8914",
  "description": "test",
  "full_name": null,
  "amount": 1000,
  "bank_id": 1,
  "iban": "IR123456789012345678901234",
  "account_number": "1234567890123456",
  "bank_follow_up_code": null,
  "status": 2,
  "create_timestamp": "2023-01-17T11:41:14.001474Z",
  "update_timestamp": "2023-01-17T11:41:14.001537Z",
  "detail": null,
  "bulk_row_id": null,
  "tracker_id": null,
  "jalali_verify_datetime": null,
  "receipt_link": "https://settlement.toman.ir/receipt/settlement/6b15ae8c-ebc1-456d-8889-843654240600:Av34rD87a3dr326123asdfuwersdfvawBGEsJKLGaweLKJG",
  "displayed_commission": 100
}

To check the state, at any time, use your own provided tracker_id or the uuid in the response to get the settlement object using [Get Settlement by Tracker-ID](#get-settlement-by-tracker_id) or [Get Settlement by UUID](#get-settlement-by-uuid) API's.

Submit Single Settlement (Single-Step)

A single-step settlement starts to be processed immediately after it has been created, and does not require verification.

import requests
import json

url = f"{base_url}/settlements/v2/"

payload = json.dumps({
    "description": "تسویه حساب ارزی",
    "bank_id": 9,
    "tracker_id": "5bd4b902-a8f8-4440-b514-d12ce7c53db0",
    "full_name": "احمد احمدی",
    "amount": 10000,
    "iban": "IR123456789012345678901234",
    "account_number": "1234567890123456",
})

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}

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

curl --location -g --request POST "$BASE_URL/settlements/v2/" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" \
--data-raw '{
    "description": "تسویه حساب ارزی",
    "bank_id": 9,
    "tracker_id": "5bd4b902-a8f8-4440-b514-d12ce7c53db0",
    "full_name": "احمد احمدی",
    "amount": 10000,
    "iban": "IR123456789012345678901234",
    "account_number": "1234567890123456",
}'

`POST /settlements/v2/`

Scope

settlement.single.submit settlement.single.verify

Request Body

Parameter	Type	Description	Example
description	String (Optional)	The description of the settlement	"تراکنش توضیحات"
bank_id	String (Optional)	The ID of the destination bank. Is one of values in the Bank IDs section.	9
tracker_id	String (Optional, Unique)	The identifier of this settlement, assigned by partner upon its creation. Note that the uniqueness of this field's value will be checked if not be Null.We recommend using the UUID as the value.	"5bd4b902-a8f8-4440-b514-d12ce7c53db0"
full_name	String (Optional)	The full name of the account owner	"احمد احمدی"
amount	Int	The transfer amount (in Rials)	250000000
iban	String	The IBAN of the destination account	"IR123456789012345678901234"
account_number	String (Optional)	The account number of the destination account.	"1234567890123456"

Response Body

Parameter	Type	Description	Example
uuid	String	A UUID 4 string which uniquely identifies the transaction. This field is generated by Toman when the partner submits a new settlement	"dc5f4898-2d82-4263-b2da-47171304cb96"
description	String	The description of the transaction	"تسویه حساب ارزی"
full_name	String	The full name of the account owner	"احمد احمدی"
amount	Int	The transfer amount (in Rials)	250000000
bank_id	Int	The ID of the destination bank. Is one of values in the Bank IDs section	4
iban	String	The IBAN of the destination account	"IR123456789012345678901234"
account_number	String (Nullable)	The account number of the destination account.	"1234567890123456"
card_number	String (Nullable)	The card number of the destination account.	"6037123456789012"
bank_followup_code	String (Nullable)	The transaction's follow up code provided by the bank	1
status	Int	The transaction's status code. Is one of Status codes	3
create_timestamp	String (ISO-8601 Date)	The exact time of the creation of this settlement	"2020-05-29T08:02:27.912352Z"
update_timestamp	String (ISO-8601 Date)	The exact time of the last modification on this settlement	"2020-05-29T08:02:27.912510Z"
verify_timestamp	String (ISO-8601 Date)	The exact time of the verification of this settlement	"2020-05-29T08:02:29.912510Z"
detail	String (Nullable)	The details of the last response/error came back from bank server for this transaction	"Read Timeout"
tracker_id	String (Nullable)	The identifier of this settlement, assigned by partner upon its creation.	"5bd4b902-a8f8-4440-b514-d12ce7c53db0"
jalali_verify_datetime	String (ISO-8601 Date) (Nullable)	The date of verification of settlement in Jalali Calendar	1401/11/03 11:53:48
receipt_link	String (Nullable)	The public URL of the settlement which you can give to your customers.	"https://settlement.toman.ir/receipt/settlement/6b15ae8c-ebc1-456d-8889-843654240600:Av34rD87a3dr326123asdfuwersdfvawBGEsJKLGaweLKJG"
displayed_commission	Int (Nullable)	The amount of commission which is not deducted from partner's wallet and has a display mode

Request Data Example

{
  "bank_id": 1,
  "amount": 1000,
  "iban": "IR123456789012345678901234",
  "account_number": "1234567890123456",
  "description": "test",
  "tracker_id": "my_unique_tracker_id"
}

Recommended Request Data Example

{
  "amount": 1000,
  "iban": "IR123456789012345678901234",
  "tracker_id": "5bd4b902-a8f8-4440-b514-d12ce7c53db0"
}

The most concise possible request body example that allows Toman service to consider the best decision for making a transaction is as mentioned above (recommended request body).

Response Data Example


{
  "uuid": "997cbaf2-f405-493d-acfc-107fd1ae8914",
  "description": "test",
  "full_name": null,
  "amount": 1000,
  "bank_id": 1,
  "iban": "IR123456789012345678901234",
  "account_number": "1234567890123456",
  "bank_follow_up_code": null,
  "status": 0,
  "create_timestamp": "2023-01-17T11:41:14.001474Z",
  "update_timestamp": "2023-01-17T11:41:14.001537Z",
  "detail": null,
  "bulk_row_id": null,
  "tracker_id": "my_unique_tracker_id",
  "jalali_verify_datetime": null,
  "receipt_link": "https://settlement.toman.ir/receipt/settlement/6b15ae8c-ebc1-456d-8889-843654240600:Av34rD87a3dr326123asdfuwersdfvawBGEsJKLGaweLKJG",
  "displayed_commission": 100
}

Exception

{
  "detail": "value of tracker_id is duplicated."
}

If the tracker_id value is duplicate, the 400 status will be returned with the above body.

The settlement will be created in pending state. When the transaction is processed by the corresponding bank, the state will change into a final one.

Get Settlements List

Retrieves a list of all of your settlements.

import requests

url = f"{base_url}/settlements/"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}

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

curl --location -g --request GET "$BASE_URL/settlements/" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json"

`GET /settlements/`

Scope

settlement.single.list

Query Parameters

Parameter	Type	Description	Example
create_before	String (ISO-8601 Date) (Nullable)	The maximum time for the settlement creation (exclusive)	"2021-05-29T08:02:27.912352Z"
create_after	String (ISO-8601 Date) (Nullable)	The minimum time for the settlement creation (exclusive)	"2020-05-29T08:02:27.912352Z"

Request Body

Empty

Response Body

A Page of Settlements.

Response Data Example

    {
  "count": 3,
  "next": "http://settlement-staging.qbitpay.org/settlements/?create_before=2023-01-17T00%3A00%3A00&page=2",
  "previous": null,
  "results": [
    {
      "uuid": "dcff88e8-2be1-43a3-afd6-3b730d61b4f2",
      "description": "test",
      "full_name": null,
      "amount": 1000,
      "bank_id": 1,
      "iban": "IR123456789012345678901234",
      "account_number": "1234567890123456",
      "bank_follow_up_code": null,
      "status": 0,
      "create_timestamp": "2023-01-16T23:51:05.001256Z",
      "update_timestamp": "2023-01-17T00:05:45.006577Z",
      "detail": null,
      "bulk_row_id": null,
      "tracker_id": null,
      "jalali_verify_datetime": null,
      "receipt_link": "https://settlement.toman.ir/receipt/settlement/6b15ae8c-ebc1-456d-8889-843654240600:Av34rD87a3dr326123asdfuwersdfvawBGEsJKLGaweLKJG",
      "displayed_commission": 100
    },
    {
      "uuid": "dcff88e8-2be1-43a3-afd6-3b730d61b4f2",
      "description": "test",
      "full_name": null,
      "amount": 1000,
      "bank_id": 1,
      "iban": "IR123456789012345678901234",
      "account_number": "1234567890123456",
      "bank_follow_up_code": null,
      "status": 0,
      "create_timestamp": "2023-01-16T21:54:16.001253Z",
      "update_timestamp": "2023-01-16T22:51:24.001732Z",
      "detail": null,
      "bulk_row_id": null,
      "tracker_id": null,
      "jalali_verify_datetime": null,
      "receipt_link": "https://settlement.toman.ir/receipt/settlement/6b15ae8c-ebc1-de56-7546-843654240600:Av34rD87a3dr326123asdfabcDefGhIGsJKLGaweLKJG",
      "displayed_commission": 100
    },
    {
      "uuid": "0bd6520c-0c9c-4f3a-aef7-91d6e72f4cc2",
      "description": "test",
      "full_name": null,
      "amount": 1000,
      "bank_id": 1,
      "iban": "IR123456789012345678901234",
      "account_number": "1234567890123456",
      "bank_follow_up_code": null,
      "status": 0,
      "create_timestamp": "2023-01-16T10:23:14.001474Z",
      "update_timestamp": "2023-01-17T11:41:14.001537Z",
      "detail": null,
      "bulk_row_id": null,
      "tracker_id": null,
      "jalali_verify_datetime": null,
      "receipt_link": "https://settlement.toman.ir/receipt/settlement/12ge3ge-ebc1-456d-8889-843654240600:Av34rD8a12GHe32GGHHEFersdfvawBGEsJKLGaweLKJG",
      "displayed_commission": 100
    }
  ]
}

Get Settlement by UUID

Retrieves a Settlement with the given uuid.

import requests

url = f"{base_url}/settlements/<uuid>"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}

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

curl --location -g --request GET "$BASE_URL/settlements/<uuid>" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json"

`GET /settlements/<uuid>`

Scope

settlement.single.list

Path Parameters

Parameter	Type	Description	Example
uuid	String	The UUID of the desirable Settlement	"997cbaf2-f405-493d-acfc-107fd1ae8914"

Request Body

Empty

Response Body

A Settlement Object

Response Data Example

    {
  "uuid": "997cbaf2-f405-493d-acfc-107fd1ae8914",
  "description": "test description",
  "full_name": null,
  "amount": 1000,
  "bank_id": 1,
  "iban": "IR260610001000800934059234",
  "account_number": "800934059234",
  "bank_follow_up_code": null,
  "status": 0,
  "create_timestamp": "2023-01-21T10:21:14.918851Z",
  "update_timestamp": "2023-01-21T10:21:14.918909Z",
  "detail": null,
  "bulk_row_id": null,
  "tracker_id": "my_unique_tracker_id",
  "jalali_verify_datetime": null,
  "receipt_link": "https://settlement.toman.ir/receipt/settlement/6b15ae8c-ebc1-456d-8889-843654240600:Av34rD87a3dr326123asdfuwersdfvawBGEsJKLGaweLKJG",
  "displayed_commission": 100
}

Errors

Code	Description
404	Could not find a settlement with the given `uuid`

Get Settlement by tracker_id

Retrieves a Settlement with the given tracker_id.

import requests

url = f"{base_url}/settlements/tracking/<tracker_id>"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}

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

curl --location -g --request GET "$BASE_URL/settlements/tracking/<tracker_id>" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json"

`GET /settlements/tracking/<tracker_id>`

Scope

settlement.single.list

Path Parameters

Parameter	Type	Description	Example
tracker_id	String	The Tracker ID of the desirable Settlement	"my_unique_tracker_id"

Request Body

Empty

Response Body

A Settlement Object

Response Data Example

    {
  "uuid": "997cbaf2-f405-493d-acfc-107fd1ae8914",
  "description": "test description",
  "full_name": null,
  "amount": 1000,
  "bank_id": 1,
  "iban": "IR260610001000800934059234",
  "account_number": "800934059234",
  "bank_follow_up_code": null,
  "status": 0,
  "create_timestamp": "2023-01-21T10:21:14.918851Z",
  "update_timestamp": "2023-01-21T10:21:14.918909Z",
  "detail": null,
  "bulk_row_id": null,
  "tracker_id": "my_unique_tracker_id",
  "jalali_verify_datetime": null,
  "receipt_link": "https://settlement.toman.ir/receipt/settlement/6b15ae8c-ebc1-456d-8889-843654240600:Av34rD87a3dr326123asdfuwersdfvawBGEsJKLGaweLKJG",
  "displayed_commission": 100
}

Since the uniqueness of the tracker_id is not checked, if there are more than one settlement with the given tracker_id, the result could be either one of them. It is highly recommended to use a random tracker_id to avoid collisions.

Errors

Code	Description
404	Could not find a settlement with the given `tracker_id`

Get Settlement Change Log List

Retrieves a list of all of your SettlementChangeLog.

import requests

url = f"{base_url}/settlements/reconciliation"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}

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

curl --location -g --request GET "$BASE_URL/settlements/reconciliation" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json"

`GET /settlements/reconciliation`

Scope

settlement.single.list

Query Parameters

Parameter	Type	Description	Example
timestamp__lt	String (ISO-8601 Date) (Nullable)	The maximum time for the change log creation (exclusive)	"2021-05-29T08:02:27.912352Z"
timestamp__gt	String (ISO-8601 Date) (Nullable)	The minimum time for the change log creation (exclusive)	"2020-05-29T08:02:27.912352Z"
from_status	Int (Nullable)	The status code that the change log happened from	3
to_status	Int (Nullable)	The status code that the change log happened to	2

Request Body

Empty

Response Body

A Page of SettlementChangeLogs.

Response Data Example

    {
  "count": 3,
  "next": "http://settlement-staging.qbitpay.org/settlements/reconciliation?timestamp__lt=2023-01-17T00%3A00%3A00&page=2",
  "previous": null,
  "results": [
    {
      "from_status": 3,
      "to_status": 2,
      "settlement": "dcff88e8-2be1-43a3-afd6-3b730d61b4f2",
      "changed_timestamp": "2023-01-16T23:51:05.001256Z"
    },
    {
      "from_status": 3,
      "to_status": 2,
      "settlement": "dcff88e8-2be1-43a3-afd6-3b730d61b4f2",
      "changed_timestamp": "2023-01-16T23:51:05.001256Z"
    },
    {
      "from_status": 3,
      "to_status": 2,
      "settlement": "dcff88e8-2be1-43a3-afd6-3b730d61b4f2",
      "changed_timestamp": "2023-01-16T23:51:05.001256Z"
    }
  ]
}

Get Settlement Change Log List V2

Retrieves a list of all of your SettlementChangeLog. UUID is also added to the response.

import requests

url = f"{base_url}/settlements/reconciliation/v2"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}

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

curl --location -g --request GET "$BASE_URL/settlements/reconciliation/v2" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json"

`GET /settlements/reconciliation/v2`

Scope

settlement.single.list

Query Parameters

Parameter	Type	Description	Example
timestamp__lt	String (ISO-8601 Date) (Nullable)	The maximum time for the change log creation (exclusive)	"2021-05-29T08:02:27.912352Z"
timestamp__gt	String (ISO-8601 Date) (Nullable)	The minimum time for the change log creation (exclusive)	"2020-05-29T08:02:27.912352Z"
from_status	Int (Nullable)	The status code that the change log happened from	3
to_status	Int (Nullable)	The status code that the change log happened to	2

Request Body

Empty

Response Body

A Page of SettlementChangeLogs.

Response Data Example

    {
  "count": 3,
  "next": "http://settlement-staging.qbitpay.org/settlements/reconciliation/v2?timestamp__lt=2023-01-17T00%3A00%3A00&page=2",
  "previous": null,
  "results": [
    {
      "from_status": 3,
      "to_status": 2,
      "settlement": "dcff88e8-2be1-43a3-afd6-3b730d61b4f2",
      "changed_timestamp": "2023-01-16T23:51:05.001256Z",
      "uuid": "a8b4609e-bc10-48c6-aa53-b940039bc5b3"
    },
    {
      "from_status": 3,
      "to_status": 2,
      "settlement": "dcff88e8-2be1-43a3-afd6-3b730d61b4f2",
      "changed_timestamp": "2023-01-16T23:51:05.001256Z",
      "uuid": "a8b4609e-bc10-48c6-aa53-b940039bc5b3"
    },
    {
      "from_status": 3,
      "to_status": 2,
      "settlement": "dcff88e8-2be1-43a3-afd6-3b730d61b4f2",
      "changed_timestamp": "2023-01-16T23:51:05.001256Z",
      "uuid": "a8b4609e-bc10-48c6-aa53-b940039bc5b3"
    }
  ]
}

Get Wallets List

Retrieves a list of all of your wallets.

import requests

url = f"{base_url}/wallets/"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}

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

curl --location -g --request GET "$BASE_URL/wallets/" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json"

`GET /wallets/`

Scope

settlement.wallet.retrieve

Request Body

Empty

Response Body

A Page of Wallets.

Response Data Example

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "bank_id": 1,
      "balance": 20000000,
      "balance_warning_threshold": 10000,
      "usable_for_inter_wallet_transfer": true,
      "inter_wallet_transfer_limit": 0
    },
    {
      "bank_id": 2,
      "balance": 7000000,
      "balance_warning_threshold": 0,
      "usable_for_inter_wallet_transfer": true,
      "inter_wallet_transfer_limit": 0
    }
  ]
}

Check Banks Status

Retrieves a list of the statuses of all banks. You can use this endpoint to check the availability of banks and whether they are currently active or not. Notice this endpoint will return all banks status without any pagination!

import requests

url = f"{base_url}/v2/banks/detail/"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}

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

curl --location -g --request GET "$BASE_URL/v2/banks/detail/" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json"

`GET /v2/banks/detail/`

Scope

Not need any specific scopes, but you need be authenticated, then just send any valid token. -

Request Body

Empty

Response Body

An Array of Bank Statuses.

Request Example

Response Example

[
  {
    "id": 1,
    "bank_name": "shahr",
    "is_active": true,
    "queue_available": true,
    "last_down_time": "2023-01-20T20:09:59.847089Z",
    "active_since": "2023-01-20T20:34:59.963388Z"
  },
  {
    "id": 2,
    "bank_name": "melli",
    "is_active": true,
    "queue_available": true,
    "last_down_time": "2023-01-20T20:09:59.896372Z",
    "active_since": "2023-01-20T20:37:07.237913Z"
  },
  {
    "id": 3,
    "bank_name": "mellat",
    "is_active": false,
    "queue_available": false,
    "last_down_time": "2022-11-28T12:31:06.739045Z",
    "active_since": null
  },
  {
    "id": 4,
    "bank_name": "tejarat",
    "is_active": true,
    "queue_available": true,
    "last_down_time": "2023-01-20T20:09:59.943809Z",
    "active_since": "2023-01-20T20:35:00.343166Z"
  },
  {
    "id": 5,
    "bank_name": "keshavarzi",
    "is_active": true,
    "queue_available": true,
    "last_down_time": "2023-01-20T20:09:59.983672Z",
    "active_since": "2023-01-20T20:35:00.378729Z"
  },
  {
    "id": 7,
    "bank_name": "pasargad",
    "is_active": true,
    "queue_available": true,
    "last_down_time": "2023-01-20T20:10:00.031696Z",
    "active_since": "2023-01-20T20:35:00.415698Z"
  },
  {
    "id": 8,
    "bank_name": "sepah",
    "is_active": true,
    "queue_available": false,
    "last_down_time": "2023-01-20T20:10:00.069828Z",
    "active_since": "2023-01-20T20:35:00.452281Z"
  },
  {
    "id": 9,
    "bank_name": "saderat",
    "is_active": true,
    "queue_available": true,
    "last_down_time": "2023-01-20T19:29:59.660040Z",
    "active_since": "2023-01-21T03:45:18.832231Z"
  },
  {
    "id": 10,
    "bank_name": "resalat",
    "is_active": true,
    "queue_available": true,
    "last_down_time": "2023-01-20T20:10:00.140342Z",
    "active_since": "2023-01-20T20:35:00.489149Z"
  },
  {
    "id": 13,
    "bank_name": "aayande",
    "is_active": true,
    "queue_available": true,
    "last_down_time": "2023-01-20T20:10:00.190205Z",
    "active_since": "2023-01-20T20:35:00.526791Z"
  },
  {
    "id": 14,
    "bank_name": "maskan",
    "is_active": true,
    "queue_available": true,
    "last_down_time": "2023-01-20T20:10:00.225371Z",
    "active_since": "2023-01-20T20:35:00.557891Z"
  },
  {
    "id": 15,
    "bank_name": "saman",
    "is_active": true,
    "queue_available": true,
    "last_down_time": "2023-01-20T20:10:00.258453Z",
    "active_since": "2023-01-20T20:35:00.592607Z"
  },
  {
    "id": 18,
    "bank_name": "parsian",
    "is_active": true,
    "queue_available": true,
    "last_down_time": "2023-01-20T20:10:00.303164Z",
    "active_since": "2023-01-20T20:35:00.628976Z"
  },
  {
    "id": 100,
    "bank_name": "paya",
    "is_active": true,
    "queue_available": true,
    "last_down_time": "2023-01-20T20:10:00.140342Z",
    "active_since": "2023-01-20T20:35:00.489149Z"
  }
]