NAV
cURL Python

Introduction

This is Toman's PID (Payment identifier) API Reference. This service is responsible to serve unique payment identifier (in Farsi called Shenas-e-Variz) for each IBAN, from now on we call it PID.

In this document there is four roles:

Activate service

To use this service, you need to provide the following items. Then contact Toman support and provide them with the desired items.

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

In this section, you will get to know the models available in the PID service, which are used in other parts of this model (for requests and responses).

PID

The entity representing a PaymentID from the moment it's created is called PID.

Parameter Type Description Example
uuid String A UUID 4 string which uniquely identifies the PID. This field is generated by Toman when the PID has been created. "dc5f4898-2d82-4263-b2da-47171304cb96"
payment_identifier String Your client's payment identifier. Using this PID your client can deposit on the bank side. "00000000121456987"
ibans List[String] Your client's IBANs List. ["IR123456789012345678901234",
"IR234567890123456789012345"]
tracker_id String (Nullable) The identifier of this pid, assigned by partner upon its creation. max length 40 characters. "trx7238"
phone_number String Your client's phone number. Valid formats are +989.. or 091... or 989.... "+989121234567"
national_type Enum national_type Your client type. (حقیقی), (اتباع), (حقوقی). 0
national_id String Your client's national id (کد ملی), (شناسه ملی), (فراگیر اتباع). "0039001199"
birthday String (exact 10 long) YYYY-MM-DD Your client's birth date or registration date (هجری شمسی). "1342-01-22"
ref_1 String (190) nullable Reference 1 that prepared for you to add any value. "this is my reference 1 for this PID"
ref_2 String (190) nullable Reference 2 that prepared for you to add any value. "123456789"
ref_3 String (190) nullable Reference 3 that prepared for you to add any value. null
created_at String (ISO-8601 Date) The exact time PID created in ISO-8601 format. "2020-05-29T08:02:29.912510Z"
destination_detail Object An object of the destination model that specifies information related to account information. The your client must deposit money into this account.

Destination

Representing detail of destination bank accounts that your client must deposit into. For example, your client must deposit into account 2165445645 at bank Saderat that account owners is الکام-توسعه آماد,هادی-علوی and the payment identifier is 00000000121456987.

Parameter Type Description Example
bank_id Integer The destination's bank ID, that is one of the values in the Bank IDs section. 9
iban String The destination's IBAN (This account will be belong to Toman). "IR590120000000004595173456"
account_number String The destination's account number in the bank (Will be Toman account number). "2165445645"
account_owners String The destination's account owners. Owners are comma separated, and first and last name of each owner is seperated by dash-. "الکام-توسعه آماد, هادی-علوی"

Identifier

This model is representing meta-data that help other services know about the resource of each object. For instance Toman wants to let Partner know about new client payment, In this scenario Toman will prepare an instance of payment and then will add identifer key to it. By this way partner will be known about the resource of Payment.

Parameter Type Description Example
uuid String UUID of PID which automatically generate by Toman. This UUID will be unique "dc5f4898-2d82-4263-b2da-47171304cb96"
ibans List[String] Your client's IBANs List. ["IR123456789012345678901234",
"IR234567890123456789012345"]
tracker_id String (Nullable) The identifier of this pid, assigned by partner upon its creation. max length 40 characters. "trx7238"
payment_identifier String The Partner's client payment-identifier (شناسه واریز). Using this PID the client can deposit on the bank side. "000000654456654108"
phone_number String(exact 11 long) Partner's client phone number. "+989121234567"
ref_1 String (190) nullable Reference 1 that Partner give us during creation of two-step PID. "this is my reference-1 for this PID"
ref_2 String (190) nullable Reference 2 that Partner give us during creation of two-step PID. "123456789"
ref_3 String (190) nullable Reference 3 that Partner give us during creation of two-step PID. null
masked_birthday String(10) The masked client's birthday or registration date "1376-**-*4"
masked_national_id String The masked client's National ID (کد ملی), (شناسه ملی), (فراگیر اتباع). "5030****61"
national_type Enum national_type National type 0
created_at String (ISO-8601 Date) The exact time of the creation this PID. "2020-05-29T08:02:29.912510Z"
client_account_owners String(190) The full name of client's account owners. Owners name are comma separated, and first and last name of each owner is seperated by dash-. "مصطفی-صدرالدینی, حمید رضا-ضیافتی اصل"
destination_detail Object destination An object of the destination model that specifies information related to account information. The client must deposit money into this account. -

Enums

1. Bank IDs

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

Name Persian Name Code
Melli ملی 2
Saderat صادرات 9
Saman سامان 15

2. Payment Status

Representing the status of Payment object.

Value Code Name Description
2 Deposit Client has been deposit into Toman bank account, And the partner callback API has been called.
4 Callback Retry At least one try for call-back Partner's API failed, needs to retry later.
-4 Reject The payment rejected by administrator because of invalid KYC.
8 Verify Partner verified the payment successfully.
10 Settled The payment is settled with the partner in its wallet.
-8 Expired Partner did not verified the payment in 48 hours and payment expired.
-6 Callback Failed Toman called Partner's callback-url and all attempts failed.
6 Callback Toman called Partner's callback url successfully, And Partner's API responded with 2XX status code.

3. National Type

Representing the type of client.

Value Description
0 حقیقی
1 اتباع
2 حقوقی

Note: (اتباع) is not supported yet.

APIs

1. Base URLs

The base URLs for our staging and production API servers are

Environment URL
Production https://bacs.toman.ir/api/v1/
Staging https://staging-bacs.toman.ir/api/v1/

Note: Please pay attention to trailing slash at the end of the urls for all endpoints.

2. Pagination Schema

All PID service endpoint 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://bacs.toman.ir/api/v1/sspid/?page=3"
previous String (Nullable) The URL of the next page containing items after this page's items "https://bacs.toman.ir/api/v1/sspid/?page=1"
results Array[Object] The array containing the items of this page

3. PID

3.1 Create PID

This endpoint will be used to create a PID for a list of IBANs in one step from API. To use this endpoint, you must send all five of the following keys to our service via API:

Notes:

Sample Code

import requests
import json

url = "https://bacs.toman.ir/api/v1/pids/"

payload = json.dumps({
    "ibans": ["IR5901200000000045951455729", "IR234567890123456789012345"],
    "tracker_id": "trx7238",
    "national_id": "1234567890",
    "phone_number": "+989121234567",
    "birthday": "1980-01-22",
    "national_type": 0,
    "bank_id": 2,
    "ref_1": "this is reference_1 optional field with max 190 length.",
    "ref_2": "this is reference_2 optional field with max 190 length.",
    "ref_3": None
})
headers = {
    'Authorization': 'Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V',
    'Content-Type': 'application/json'
}

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

curl --location 'https://bacs.toman.ir/api/v1/pids/' \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V' \
--header 'Content-Type: application/json' \
--data '{
    "ibans": ["IR5901200000000045951455729","IR234567890123456789012345"],
    "tracker_id": "trx7238",
    "national_id": "1234567890",
    "phone_number": "+989121234567",
    "birthday": "1980-01-22",
    "national_type": 0,
    "bank_id": 2,
    "ref_1": "this is reference_1 optional field with max 190 length.",
    "ref_2": "this is reference_2 optional field with max 190 length.",
    "ref_3": ""
}'

POST /pids/

Scope

pid.payment-id.create

Request Body

Parameter Type Description Example
ibans List[String] Your client's IBANs List. ["IR123456789012345678901234","IR234567890123456789012345"]
tracker_id String (Nullable) The identifier of this pid, assigned by partner upon its creation. max length 40 characters. "trx7238"
national_id String Your client national id (Farsi:کد ملی, شناسه ملی, فراگیر اتباع.) "0039001199"
national_type Enum national_type Your client national type (حقیقی), (اتباع), (حقوقی) 0
phone_number String(exact 11 long) Your client phone number. "+989121234567"
birthday String (exact 10 long) YYYY-MM-DD Your client birthday or registration date (Hijri calendar). "1342-01-22"
bank_id Integer Bank IDs (nullable, optional) The destination's bank ID. 9
ref_1 String (190) (nullable, optional) Reference 1 that prepared for you to add any value. "this is my reference 1 for this PID"
ref_2 String (190) (nullable, optional) Reference 2 that prepared for you to add any value. "123456789"
ref_3 String (190) (nullable, optional) Reference 3 that prepared for you to add any value. null

Response Body

Response body is identifier

Request Data Example

{
  "ibans": [
    "IR5901200000000045951455729",
    "IR234567890123456789012345"
  ],
  "tracker_id": "trx7238",
  "national_id": "0123456789",
  "phone_number": "+989121234567",
  "birthday": "1350-01-22",
  "national_type": 0,
  "bank_id": 2,
  "ref_1": "this is just an example of a reference.",
  "ref_2": "123455555",
  "ref_3": null
}

Response Data Example

{
  "uuid": "eb634c2e-d39b-411d-b5d2-33d83e65ba42",
  "ibans": [
    "IR5901200000000045951455729",
    "IR234567890123456789012345"
  ],
  "tracker_id": "trx7238",
  "payment_identifier": "00000000001000652",
  "phone_number": "+989121234567",
  "national_type": 0,
  "ref_1": "this is just an example of a reference.",
  "ref_2": "123455555",
  "ref_3": null,
  "created_at": "2023-04-19T08:58:26.397925Z",
  "masked_birthday": "1350-**-*2",
  "masked_national_id": "0123****89",
  "client_account_owners": null,
  "destination_detail": {
    "bank_id": 2,
    "iban": "IR460170000000228939030001",
    "account_number": "228939030001",
    "account_owners": "الکام - توسعه آماد"
  }
}

Error Handling

400_BAD_REQUEST

{
  "bank_id": [
    {
      "code": "invalid_bank_id",
      "description": "Bank_id is invalid."
    }
  ]
}

409_CONFLICT

{
  "tracker_id": [
    {
      "code": "duplicated_tracker_id",
      "description": "The tracker_id is duplicated!"
    }
  ]
}

3.2 Get a PID

3.2.1 By UUID

Used to retrieve an existence PID record by uuid.

Sample Code

import requests

url = "https://bacs.toman.ir/api/v1/pids/47e9b192-c57d-49c8-bc45-f4d2aa730093/"

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

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

curl --location 'https://bacs.toman.ir/api/v1/pids/47e9b192-c57d-49c8-bc45-f4d2aa730093/' \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'

GET /pids/<uuid>/

Scope

pid.payment-id.read

Request Body

Without any request body.

Response Body

Response body is an identifier

Response Data Example

{
  "uuid": "eb634c2e-d39b-411d-b5d2-33d83e65ba42",
  "ibans": [
    "IR5901200000000045951455729",
    "IR234567890123456789012345"
  ],
  "tracker_id": "trx7238",
  "payment_identifier": "00000000001000652",
  "phone_number": "+989121234567",
  "national_type": 0,
  "ref_1": "this is just an example of a reference.",
  "ref_2": "123455555",
  "ref_3": null,
  "created_at": "2023-04-19T08:58:26.397925Z",
  "masked_birthday": "1350-**-*2",
  "masked_national_id": "0123****89",
  "client_account_owners": "حمید-بختیاری,سبحان-صفایی",
  "destination_detail": {
    "bank_id": 2,
    "iban": "IR460170000000228939030001",
    "account_number": "228939030001",
    "account_owners": "الکام - توسعه آماد"
  }
}

3.2.2 By tracker_id

Used to retrieve an existence PID record by tracker_id.

Sample Code

import requests

url = "https://bacs.toman.ir/api/v1/pids/tracker-id/trx7238/"

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

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

curl --location 'https://bacs.toman.ir/api/v1/pids/tracker-id/trx7238/' \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'

GET /pids/tracker-id/<tracker_id>/

Scope

pid.payment-id.read

Request Body

Without any request body.

Response Body

Response body is an identifier

Response Data Example

{
  "uuid": "eb634c2e-d39b-411d-b5d2-33d83e65ba42",
  "ibans": [
    "IR5901200000000045951455729",
    "IR234567890123456789012345"
  ],
  "tracker_id": "trx7238",
  "payment_identifier": "00000000001000652",
  "phone_number": "+989121234567",
  "national_type": 0,
  "ref_1": "this is just an example of a reference.",
  "ref_2": "123455555",
  "ref_3": null,
  "created_at": "2023-04-19T08:58:26.397925Z",
  "masked_birthday": "1350-**-*2",
  "masked_national_id": "0123****89",
  "client_account_owners": "حمید-بختیاری,سبحان-صفایی",
  "destination_detail": {
    "bank_id": 2,
    "iban": "IR460170000000228939030001",
    "account_number": "228939030001",
    "account_owners": "الکام - توسعه آماد"
  }
}

3.3 Get List of PIDs

Used to get all PID record with pagination.

Sample Code

import requests

url = "https://bacs.toman.ir/api/v1/pids/"

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

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

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

GET /pids/

Scope

pid.payment-id.read

Request Body

Without any request body.

Query Parameters

Parameter Type Description lookup expression Example
phone_number string Filter by phone number exact,contains, icontains /pids/?phone_number__contains=1234567890
payment_identifier string Filter by payment identifier exact,contains, icontains, in /pids/?payment_identifier=00000000001000652
iban string Filter by ibans that contains iban /pids/?iban=IR5901200000000045951455729
tracker_id string Filter exact by tracker ID /pids/?tracker_id=trx7238
destination_iban string Filter by destination bank IBAN /pids/?destination_iban=IR460170000000228939030001
destination_bank_id int Filter by exact destination bank ID /pids/?destination_back_id=9
created_at (ISO-8601 DateTime) Filter by PID created at lt, gt, lte, gte /pids/?created_at__lt=2023-12-31T23:59:59Z&created_at__gt=2023-01-01T00:00:00Z

Note: You can use any chain of the above parameters together.

Response Data Example

The response of this endpoint is following pagination. The results key will be an Array of identifiers.

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "uuid": "1a993724-e10a-4c87-8a1b-8af84eb28f56",
      "ibans": [
        "IR5901200000000045951455729",
        "IR234567890123456789012345"
      ],
      "tracker_id": "trx7238",
      "payment_identifier": "00000000001000328",
      "phone_number": "+989331234567",
      "national_type": 0,
      "ref_1": "caeec72e-776c-480f-9ab1-69db9ff43178",
      "ref_2": null,
      "ref_3": null,
      "created_at": "2023-04-10T14:46:01.164766Z",
      "masked_birthday": "1376-**-*4",
      "masked_national_id": "5030****61",
      "client_account_owners": "غلامرضا-جعفری",
      "destination_detail": {
        "bank_id": 2,
        "iban": "IR460170000000228939030001",
        "account_number": "228939030001",
        "account_owners": "الکام - توسعه آماد"
      }
    },
    {
      "uuid": "29c3197e-c3d3-46b5-b365-166286c60019",
      "ibans": [
        "IR5901200000000045951455729",
        "IR234567890123456789012345"
      ],
      "tracker_id": "trx7238",
      "payment_identifier": "00000000001000220",
      "phone_number": "+989101234567",
      "national_type": 0,
      "ref_1": "dbcf8292-faf3-46b2-a622-5f9193a9870b",
      "ref_2": null,
      "ref_3": null,
      "created_at": "2023-04-10T09:22:14.696345Z",
      "masked_birthday": "1371-**-*2",
      "masked_national_id": "0015****05",
      "client_account_owners": "سمیه-حسنی",
      "destination_detail": {
        "bank_id": 2,
        "iban": "IR460170000000228939030001",
        "account_number": "228939030001",
        "account_owners": "الکام - توسعه آماد"
      }
    },
    {
      "uuid": "4d7fa22b-6ed4-4939-8fe4-5adbe95225e4",
      "ibans": [
        "IR5901200000000045951455729",
        "IR234567890123456789012345"
      ],
      "tracker_id": "trx7238",
      "payment_identifier": "00000000001000112",
      "phone_number": "+989121234567",
      "national_type": 0,
      "ref_1": "67560400-87e7-4d0e-8d49-9c7292da2993",
      "ref_2": null,
      "ref_3": null,
      "created_at": "2023-04-10T09:12:52.231407Z",
      "masked_birthday": "1371-**-*2",
      "masked_national_id": "0015****05",
      "client_account_owners": "‌علی‌-جوادی",
      "destination_detail": {
        "bank_id": 2,
        "iban": "IR460170000000228939030001",
        "account_number": "228939030001",
        "account_owners": "الکام - توسعه آماد"
      }
    }
  ]
}

3.4 UPDATE a PID IBANs list

3.4.1 By UUID

Used for updating IBANs list of the existence PID record by the uuid.

Sample Code

import requests

url = "https://bacs.toman.ir/api/v1/pids/47e9b192-c57d-49c8-bc45-f4d2aa730093/"

payload = {
    "ibans": ["IR5901200000000045951455729", "IR234567890123456789012345"]
}
headers = {
    'Authorization': 'Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'
}

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

curl --location --request PATCH 'https://bacs.toman.ir/api/v1/pids/47e9b192-c57d-49c8-bc45-f4d2aa730093/' \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'
--data '{
    "ibans": ["IR5901200000000045951455729","IR234567890123456789012345"]
    }'

PATCH /pids/<uuid>/

Scope

pid.payment-id.create

Request Body

Parameter Type Description Example
ibans List[String] Your client's IBANs List. ["IR123456789012345678901234","IR234567890123456789012345"]

Response Body

Response body is

Parameter Type Description Example
ibans List[String] Your client's IBANs List. ["IR123456789012345678901234","IR234567890123456789012345"]

Request Data Example

{
  "ibans": [
    "IR5901200000000045951455729",
    "IR234567890123456789012345"
  ]
}

Response Data Example

{
  "ibans": [
    "IR5901200000000045951455729",
    "IR234567890123456789012345"
  ]
}

3.4.2 By tracker_id

Used for updating Ibans list of the existence PID record by your tracker_id.

Sample Code

import requests

url = "https://bacs.toman.ir/api/v1/pids/tracker-id/trx7238/"

payload = {
    "ibans": ["IR5901200000000045951455729", "IR234567890123456789012345"]
}
headers = {
    'Authorization': 'Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'
}

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

curl --location --request PATCH 'https://bacs.toman.ir/api/v1/pids/tracker-id/trx7238/' \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'
--data '{
    "ibans": ["IR5901200000000045951455729","IR234567890123456789012345"]
    }'

PATCH /pids/tracker-id/<tracker_id>/

Scope

pid.payment-id.create

Request Body

Parameter Type Description Example
ibans List[String] Your client's IBANs List. ["IR123456789012345678901234","IR234567890123456789012345"]

Response Body

Response body is

Parameter Type Description Example
ibans List[String] Your client's IBANs List. ["IR123456789012345678901234","IR234567890123456789012345"]

Request Data Example

{
  "ibans": [
    "IR5901200000000045951455729",
    "IR234567890123456789012345"
  ]
}

Response Data Example

{
  "ibans": [
    "IR5901200000000045951455729",
    "IR234567890123456789012345"
  ]
}

4. Payment

4.1 Get a Payment

To get detail of a payment.

Sample Code

import requests

url = "https://bacs.toman.ir/api/v1/payments/47e9b192-c57d-49c8-bc45-f4d2aa730093/"

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

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

curl --location 'https://bacs.toman.ir/api/v1/payments/47e9b192-c57d-49c8-bc45-f4d2aa730093/' \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'

GET /payments/<uuid>/

Scope

pid.payment.read

Request Body

Without any request body.

Response Body

The response of this endpoint is as following:

Parameter Type Description Example
uuid String Payment UUID. Toman will assign to each payment a unique UUID. "dfgh4898-2d82-4263-b2da-47171304cbdf"
amount Integer Payment amount in IRR. 15000000
paid_at String DateTime ISO 8601 Payment paid at. "2020-05-29T08:02:29.912510Z"
bank_id Integer Payment paid at this bank ID. Is one of values in the Bank IDs section. 9
bank_tracker_id String (190) The tracker id that comes from bank side (کد پیگیری بانک). "5641316546aaa"
status Integer Status of the Payment (for more information check Payment Status enum) 2
identifier Object[identifier] This field will contains all the data related to your client who paid, and your references fields that you send during create PID.

Response Data Example

{
  "uuid": "068b00ec-f2d0-4900-9e0b-eb440b99d564",
  "amount": 1111,
  "paid_at": "2023-02-22T02:41:48.000000Z",
  "bank_id": 2,
  "bank_tracker_id": "1111113",
  "identifier": {
    "uuid": "da920eb2-609d-4fad-99d9-bf8307d9c6e9",
    "ibans": [
      "IR5901200000000045951455729",
      "IR234567890123456789012345"
    ],
    "tracker_id": "trx7238",
    "payment_identifier": "00000000000000648",
    "phone_number": "+989022220297",
    "national_type": 0,
    "ref_1": null,
    "ref_2": null,
    "ref_3": null,
    "created_at": "2023-02-22T00:22:27.295558Z",
    "masked_birthday": "1376-**-*4",
    "masked_national_id": "5030****61",
    "client_account_owners": "غلامرضا-جعفری",
    "destination_detail": {
      "bank_id": 2,
      "iban": "IR260610000000700834059274",
      "account_number": "123456",
      "account_owners": "الکام توسعه آماد"
    }
  },
  "status": 2
}

4.2 Get list Payments

Sample Code

import requests

url = "https://bacs.toman.ir/api/v1/payments/"

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

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

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

GET /payments/

Scope

pid.payment.read

Request Body

Without any request body.

Query Parameters

Parameter Type Description lookup expression Example
phone_number string Filter exact by phone number /payments/?phone_number=1234567890
search string Search by UUID, payment identifier, or bank tracker ID /payments/?search=123e4567-e89b
amount int Filter by amount less than 100 lt, gt, lte, gte /payments/?amount__lt=100
status int Filter by status in /payments/?status__in=1,2,3
bank_id int Filter exact by bank ID /payments/?bank_id=1
paid_at (ISO-8601 DateTime) Filter by Payment paid at lt, gt, lte, gte /payments/?paid_at__lt=2022-12-31T23:59:59Z&paid_at__gt=2022-01-01T00:00:00Z

Note: You can use any chain of the above parameters together.

Response Data Example

The response of this endpoint is following pagination. The results key will be Array of 4.1 Get a Payment response.

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "uuid": "30033122-2f94-4347-886c-96ccacea5e12",
      "amount": 15200000,
      "paid_at": "2023-04-18T16:20:39Z",
      "bank_id": 4,
      "bank_tracker_id": "1234567890",
      "identifier": {
        "uuid": "ff9e626a-a974-4a8e-bdd3-ecd6e809bb47",
        "ibans": [
          "IR5901200000000045951455729",
          "IR234567890123456789012345"
        ],
        "tracker_id": "trx7238",
        "payment_identifier": "00000000010000108",
        "phone_number": "+989121234567",
        "national_type": 0,
        "ref_1": "7669b559-6ad1-4c1b-be98-c5205b47e3e8",
        "ref_2": null,
        "ref_3": null,
        "created_at": "2023-04-16T08:22:41.884231Z",
        "masked_birthday": "1376-**-*4",
        "masked_national_id": "5030****61",
        "client_account_owners": "علی-صفرآبادی",
        "destination_detail": {
          "bank_id": 4,
          "iban": "IR390180000000000046655419",
          "account_number": "46655419",
          "account_owners": "الکام - توسعه آماد"
        }
      },
      "status": 8
    },
    {
      "uuid": "f8f9971b-c339-4a30-b8e7-8bf60a83f17a",
      "amount": 10000000,
      "paid_at": "2023-04-18T14:26:36Z",
      "bank_id": 4,
      "bank_tracker_id": "2546474668",
      "identifier": {
        "uuid": "ff9e626a-a974-4a8e-bdd3-ecd6e809bb47",
        "ibans": [
          "IR5901200000000045951455729",
          "IR234567890123456789012345"
        ],
        "tracker_id": "trx7238",
        "payment_identifier": "00000000010000108",
        "phone_number": "+989121234567",
        "national_type": 0,
        "ref_1": "7669b559-6ad1-4c1b-be98-c5205b47e3e8",
        "ref_2": null,
        "ref_3": null,
        "created_at": "2023-04-16T08:22:41.884231Z",
        "masked_birthday": "1376-**-*4",
        "masked_national_id": "5030****61",
        "client_account_owners": "جواد-غلامی",
        "destination_detail": {
          "bank_id": 4,
          "iban": "IR390180000000000046655419",
          "account_number": "46655419",
          "account_owners": "الکام - توسعه آماد"
        }
      },
      "status": 8
    }
  ]
}

4.3 Verify a Payment

To verify callback Payment.
When a new payment is made by the client, Toman will send a request to the partner callback API to let them know about the new payment, after Partner received this request, he must verify that Payment, Otherwise Toman does not count that payment during the settlement with Partner.

Sample Code

import requests

url = "https://bacs.toman.ir/api/v1/payments/068b00ec-f2d0-4900-9e0b-eb440b99d564/verify/"

payload = {
    "amount": 12345
}
headers = {
    'Authorization': 'Bearer ZA6fq1eV38N8jBRp1DzvJOcvcVKrPl'
}

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

curl --location --request POST 'https://bacs.toman.ir/api/v1/payments/068b00ec-f2d0-4900-9e0b-eb440b99d564/verify/' \
--header 'Authorization: Bearer ZA6fq1eV38N8jBRp1DzvJOcvcVKrPl'
--data '{
    "amount": 12345
    }'

POST /payments/<payment-uuid>/verify/

Scope

pid.payment.verify

Request Body

Parameter Type Description
amount Integer
(Optional)		 Payment amount in IRR

Request Data Example

{
  "amount": 12345
}

Response Data Example

Will return the following status codes:

{
    "non_field_errors": [
        {
            "code": "payment_status_change_not_allowed",
            "description": "Cannot change the status this request from verify to verify"
        }
    ]
}

4.4 New payment Callback

When a client makes a payment into Toman bank account, Toman will let you know about the new payment by calling your given URL using the following schema:

Parameter Type Description Example
uuid String Payment UUID. Toman will assign to each payment a unique UUID. "dfgh4898-2d82-4263-b2da-47171304cbdf"
amount Integer Payment amount in IRR. 15000000
paid_at String DateTime ISO 8601 Payment paid at. "2020-05-29T08:02:29.912510Z"
bank_id Integer Payment paid at this bank ID. Is one of values in the Bank IDs section. 9
bank_tracker_id String (190) The tracker id that comes from bank side (کد پیگیری بانک). "5641316546aaa"
identifier Object This field will contains all the data related to your client who paid, and your references fields that you send during create PID. identifier

Here is an example of the response body that you receive in this URL:

{
  "uuid": "068b00ec-f2d0-4900-9e0b-eb440b99d564",
  "amount": 1111,
  "paid_at": "2023-02-22T02:41:48.000000Z",
  "bank_id": 2,
  "bank_tracker_id": "1111113",
  "identifier": {
    "uuid": "ff9e626a-a974-4a8e-bdd3-ecd6e809bb47",
    "ibans": [
      "IR5901200000000045951455729",
      "IR234567890123456789012345"
    ],
    "tracker_id": "trx7238",
    "payment_identifier": "00000000010000108",
    "phone_number": "+989121111111",
    "national_type": 0,
    "ref_1": "7669b559-6ad1-4c1b-be98-c5205b47e3e8",
    "ref_2": null,
    "ref_3": null,
    "created_at": "2023-04-16T08:22:41.884231Z",
    "masked_birthday": "1376-**-*4",
    "masked_national_id": "5030****61",
    "client_account_owners": "جعفر جلال‌ ز‌اده‌ ‌اسفند‌ابا- ",
    "destination_detail": {
      "bank_id": 2,
      "iban": "IR390180000000000046655419",
      "account_number": "46655419",
      "account_owners": "الکام - توسعه آماد"
    }
  }
}

Notes:

Expected response

Toman expected 2XX series status code from Partner API for callback for new Payment.

4.5 Get CSV export of Payments

Sample Code

import requests

url = "https://bacs.toman.ir/api/v1/payments/export/"

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

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

curl --location 'https://bacs.toman.ir/api/v1/payments/export/' \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'

GET /payments/export/

Scope

pid.payment.read

Request Body

Without any request body.

Query Parameters

Parameters to filter payments, are like Get list Payments

Response Body

The response, contains a csv file that have been exported based on your filter with below headers:

headers
شناسه واریز
UUID
مبلغ
پارتنر آی دی
آی دی بانک
زمان ایجاد تراکنش
آخرین وضعیت تراکنش
نام پارتنر
cURL Python