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.

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

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

Request Data Example (Without Basic Authentication)

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)

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.

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

Reasonse

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 available for your user.

400_INVALID_GRANT

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

Reasonse

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

401_INVALID_CLIENT

{
    "error"
:
    "invalid_client"
}

Reasonse

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"
iban	String	Your client's IBAN.	"IR123456789012345678901234"
phone_number	String	Your client's phone number. Valid formats are `+989..` or `091...` or `989....`	"+989121234567"
national_id	String (exact 10 long)	Your client's national id (`کد ملی`).	"0039001199"
birthday	String (exact 10 long) YYYY-MM-DD	Your client's birth 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 account 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 know 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"
iban	String(190)	Partner's client IBAN (Farsi: `Shomar-e-Sheba`).	"IR590120000000004595173711"
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	"1376-*-4"
masked_national_id	String(10)	The masked client's National ID	"5030****61"
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	Description
2	Client has been deposit into Toman bank account, And need Partner API has been called.
4	At least one try for call-back Partner's API failed, needs to retry later.
6	Toman called Partner's callback url successfully, And Partner's API responded with 2XX status code.
8	Partner verified the payment successfully.
-6	Toman called Partner's callback-url and all attempts failed.

APIs

1. Base URLs

The base URLs for our staging and productions 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 specific IBAN in one step from API. To use this endpoint, you must send all four of the following keys to our service via API:

Your client's IBAN
Your client's phone number
Your client's birthday (هجری شمسی)
Your client's National ID (کد ملی)

Notes:

Considering that one IBAN (Shomar-e-Sheba) can't have two different PIDs, if a PID has already been created for the IBAN, this endpoint will return the same one.So if you call this endpoint more than once, always you will receive the same PID.
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.
All four items iban, phone_number, national_id and birthday must be match together and must belong to same person, Otherwise will prevent to create PID and error will be returned.

Sample Code

import requests
import json

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

payload = json.dumps({
    "iban": "IR590120000000004595173456",
    "national_id": "1234567890",
    "phone_number": "+989121234567",
    "birthday": "1980-01-22",
    "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 '{
    "iban": "IR590120000000004595173456",
    "national_id": "1234567890",
    "phone_number": "+989121234567",
    "birthday": "1980-01-22",
  "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 /api/v1/pids/`

Scope

pid.payment-id.create

Request Body

Parameter	Type	Description	Example
iban	String(exact 26 long)	Your client IBAN (Farsi: `Shomar-e-Sheba`). Should start with uppercase "IR"	"IR590120000000004595173711"
national_id	String (exact 10 long)	Your client national id (Farsi:`Code Melli`).	"0039001199"
phone_number	String(exact 11 long)	Your client phone number.	"+989121234567"
birthday	String (exact 10 long) YYYY-MM-DD	Your client birthday (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

{
  "iban": "IR5901200000000045951455729",
  "national_id": "0123456789",
  "phone_number": "+989121234567",
  "birthday": "1350-01-22",
  "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",
  "iban": "IR5901200000000045951455729",
  "payment_identifier": "00000000001000652",
  "phone_number": "+989121234567",
  "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": "الکام - توسعه آماد"
  }
}

3.2 Get a PID

Used for retrieve an existence PID record.

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",
  "iban": "IR5901200000000045951455729",
  "payment_identifier": "00000000001000652",
  "phone_number": "+989121234567",
  "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 for 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.

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",
      "iban": "IR940190000000105844477003",
      "payment_identifier": "00000000001000328",
      "phone_number": "+989331234567",
      "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",
      "iban": "IR100560080588802456034001",
      "payment_identifier": "00000000001000220",
      "phone_number": "+989101234567",
      "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",
      "iban": "IR230700001000115499597001",
      "payment_identifier": "00000000001000112",
      "phone_number": "+989121234567",
      "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": "الکام - توسعه آماد"
      }
    }
  ]
}

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 same as response of sections 4.1 section.

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",
    "iban": "IR150620000000100853087005",
    "payment_identifier": "00000000000000648",
    "phone_number": "+989022220297",
    "ref_1": null,
    "ref_2": null,
    "ref_3": null,
    "created_at": "2023-02-22T00:22:27.295558Z",
    "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.

Response Data Example

The response of this endpoint is following pagination. The results key will be Array of 5.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",
        "iban": "IR610180000000003554001008",
        "payment_identifier": "00000000010000108",
        "phone_number": "+989121234567",
        "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",
        "iban": "IR610180000000004544001008",
        "payment_identifier": "00000000010000108",
        "phone_number": "+989121234567",
        "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 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.

Sample Code

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

Scope

pid.payment.verify

Request Body

Without any request body.

Response Data Example

Will return 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 not exists. 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 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 client made a payment into Toman bank account, Toman will let you know about the new payment by calling your given URL using 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 request 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",
    "iban": "IR610180000000003694001055",
    "payment_identifier": "00000000010000108",
    "phone_number": "+989332645811",
    "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. Otherwise, the Payment will not settle in your account for that day.
Since this endpoint (New payment Callback URL) is not protect with any security protocol, you must prevent increasing your client balance till you get OK from verify payment URL.
Each payment has unique UUID, so you need prevent to 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 on these fields,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.