NAV
cURL Python

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

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
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.

Sample Code

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"

Request Data Example

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

{
  "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
}

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.

Sample Code

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"

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"
}

Submit Single Settlement (Single-Step)

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

Sample Code

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"

Request Data Example

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

{
  "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"
}

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.

Get Settlements List

Retrieves a list of all of your settlements.

Sample Code

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"
    },
    {
      "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"
    },
    {
      "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"
    }
  ]
}

Get Settlement by UUID

Retrieves a Settlement with the given uuid.

Sample Code

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"
}

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.

Sample Code

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"
}

Errors

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

Get Wallets List

Retrieves a list of all of your wallets.

Sample Code

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!

Sample Code

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"
  }
]
cURL Python