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:

Toman: Is responsible to serve payment identifier (شناسه واریز) for its partners.
Partner: You. A business that wants to give PID service to its clients.
Client: Your clients (Partner's clients). Anyone who wants to make a deposit using Toman's PID service through a partner.
Bank: The destination bank that the client will make a deposit into.

Activate service

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

Logo: You business logo (max 50kb and 400*400).
Callback new payment URL: Toman will call this endpoint when client made a new payment, to inform you about it.
Callback two-step PID URL: Toman will call this endpoint to let you know about client's PID and additional detail ( destination account, bank and etc).
Redirect URL: When client finished its two-step PID, Toman will redirect client to this endpoint.
Landing page URL: Toman will show your landing page by a QRCode to client when he/she visit Toman two-step PID page.
White List IP: Prepare a list of your server's IP. Toman will block any request from other IPs.

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)

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)

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

The Content-Type of get token request should be application/x-www-form-urlencoded.
`Content-Type: application/x-www-form-urlencoded`

You can obtain a single token and use it for multiple endpoints by specifying different scopes separated by whitespace. For instance: > scope=settlement.single.submit payment.create.

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.

response = requests.request(
    "POST",
    auth_url,
    data={
        "grant_type": "refresh_token",
        "refresh_token": refresh_token,
        "client_id": client_id,
        "client_secret": client_secret,
    }
)
access_token = response.json()["access_token"]
new_refresh_token = response.json()["refresh_token"]

curl -X POST -d "refresh_token=$REFRESH_TOKEN"\
             -d "client_id=$CLIENT_ID" \
             -d "client_secret=$CLIENT_SECRET" \
             -d "grant_type=refresh_token" \
             $AUTH_URL

Request Data Example

POST /oauth2/token/ HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: auth.qbitpay.org

grant_type=refresh_token&
refresh_token=upTFapSZfpJISYeo0YsZVjf8X29SBy&
client_id=MY_CLIENT_ID&
client_secret=MY_CLEINT_SECRET

Response Data Example

HTTP/1.1 200 OK
Content-Type: application/json

{
"access_token":"mAGJQqnhLBEZ5UMVAvHVNruOzAyZVs",
"expires_in":86400,
"token_type":"Bearer",
"scope":"settlement.single.submit settlement.single.verify",
"refresh_token":"BLVE2AleqqLHPBmGad4HAQEmqkPr4b"
}

Error Handling

In this section we will list some of the errors that you may encounter while trying to obtian or refresh your tokens.

400_INVALID_SCOPE

{"error": "invalid_scope"}

Reasons

You're acquiring a token with a scope that is not defined. (e.g. wrong scope name)
One or more of the scopes in your request is unavailable for your user.

400_INVALID_GRANT

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

Reasons

You have specified the username or password in your request wrong.

401_INVALID_CLIENT

{
    "error"
:
    "invalid_client"
}

Reasons

The client_id specified in your request is not correct.
The client_secret specified in your request is not correct.

Models

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. Is one of 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
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

2. Payment Status

Representing the status of Payment object.

Value	Code Name	Description
2	Deposit	Client has been deposit into Toman bank account, And need Partner 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:

Your client's IBANs List
Your client's phone number
Your client's birthday (هجری شمسی),(حقوقی: تاریخ ثبت شرکت)
Your client's National ID (کد ملی), (شناسه ملی), (فراگیر اتباع)
Your client's National type (حقیقی), (اتباع), (حقوقی)

Notes:

We have placed three optional and nullable fields for you that are not used in our services and have been added to make your work easier, by key ref_1, ref_2, and ref_3. You can set any value you want (up to 190 characters long). For example, you can add additional information or your client ID, etc. In the future, you will receive these references alongside Payment details if any payment is created by your client (This fields cannot be updated.).
The tracker_id optional field (nullable), Which can use for retrieve and update IBANs list of the PID.
Each client able to have multiple PIDs with the different IBANs lists.

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

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.

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.

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.

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.

Response Data Example

The response of this endpoint is following pagination. The results key will be 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 the update IBANs list of the existence PID record by the uuid.

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 the update Ibans list of the existence PID record by your tracker_id.

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.

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

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 request to callback Partner 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.

import requests

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

payload = {}
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'

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

Scope

pid.payment.verify

Request Body

Without any request body.

Response Data Example

Will return the following status codes:

200: It means that you have verified an existing payment for the first time. In this situation, the response has not any content.
404: The payment does not exist. In this situation, the response has not any content.
409: The payment has been verified in the past, and you are verifying it again. This means that this payment is not new, and you should not count this payment several times. In this situation, the response body will be the same as follows:

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

Method: POST
Content-type: application/json
URL: This endpoint will be given to us by the Partner (You), when activating this service, that describe at Callback new payment-url.
Body:

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": 4,
      "iban": "IR390180000000000046655419",
      "account_number": "46655419",
      "account_owners": "الکام - توسعه آماد"
    }
  }
}

Notes:

After you receive this callback, you MUST verify it. Every time you verify a payment, it will be settled in your account during the next settlement cycle.
Since this endpoint (New payment Callback URL) is not protected with any security protocol, you must prevent increasing your client balance till you get OK from verified payment URL.
Each payment has unique UUID, so you need to prevent duplicated callback cause any side effect like multiple-increase client wallet balance or etc.
Since only Toman and the partner know about the ref_1, ref_2 and ref_3 keys, it is better not to leave these values empty and fill value in these fields. This is to ensure that the ref values are the same when receiving the information of a payment for more security.

Expected response

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