Introduction

This is Toman's IPG API Reference.

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.

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

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.

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.

Toman IPG Service

To use Toman IPG, you need to create a Payment entity and obtain a UUID to redirect user to the payment gateway. When the user has finished the payment in the gateway, we will redirect the user to your callback endpoint with the payment details, which you can verify or deny using the information stored on your side.

Models

Payment

The entity representing a payment from the moment it's created is called Payment.

Parameter	Type	Description	Example
uuid	String	A UUID 4 string which uniquely identifies the payment. This field is generated by Toman when the partner wants to create a new payment	"dc5f4898-2d82-4263-b2da-47171304cb96"
amount	Long	The amount to be paid, in Rials	12000
toman_wage	Long	How much of this payment should pay to Toman as the fee for the transaction (Based on the percentage contracted with Toman including VAT.) , in Rials	123
shaparak_wage	Long	How much of this payment should pay to Shaparak as the fee for the transaction(It is 0.0002 of the transaction amount with min of 1200 and max of 40000 rials) , in Rials	120
mobile_number	String (Nullable)	The mobile number to be delivered to the PSP. The saved cards with the given phone number will be shown to the customer. It is also used in the process of National ID check.	"09123456789"
check_national_id	Boolean	Performs a check on the National ID of the owner of the card against the National ID of the owner of the mobile number and aborts the payment if they don't match. The `mobile_number` should not be null if this value is `true`	true
callback_url	String (Nullable)	The absolute url of the callback endpoint. Note that the domain of the `callback_url` must be registered before using.	"https://partner.com/payment/result"
tracker_id	String (Nullable)	This is an ID you can provide for the payment, which will be returned to your `callback_url` for you to verify the payment. Note that due to security reasons, It is highly advised to generate and save a tracker_id for each payment.	"this_is_my_unique_tracker_id"
created_at	String (ISO-8601 Date)	The exact time of the creation of this payment	"2022-01-01T12:12:12.772196Z"
verified_at	String (ISO-8601 Date) (Nullable)	The exact time of the verification of this payment	"2022-01-01T12:17:46.772196Z"
status	Integer	The current status of the payment. Can be an integer between -3 to 5. See Payment Status	4
psp	String	The chosen PSP to handle this payment. At the moment we only support SEP so the only possible value is `SEP`.	"SEP"
terminal_number	String	The terminal number of the partner used in this payment	"term2309"
trace_number	String (Nullable)	This is a field related to successed payments, set by the PSP. (کد رهگیری)	687668
reference_number	String (Nullable)	This is a field related to successed payments, set by the PSP. (شماره مرجع)	21458790785
digital_receipt_number	String (Nullable)	This is a field related to successed payments, set by the PSP. (شماره رسید دیجیتال)	GmshtyjwKSuw15ogyWW+8n66VdBfBVjF6mga37Q7Rb
refund	Refund object (Nullable)	The refund object, if present	{"amount": 1000, "created_at": "2023-08-20T08:44:06.728550Z", "status": 1}

Payment Status

Status Number	Code Name	Description
1	Created	The payment has just been created
2	Token Acquired	Token for this payment has been acquired, you can redirect your user with the token
3	Redirect to PSP	The user has been redirected to a payment gateway
4	Called-back	Toman has redirected the user to your callback endpoint
5	Verified	Payment was verified by you and is considered successful
0	Reverted	You rejected the payment and the money is refunded to the user
-1	Failed	The payment was not successful. E.g. the user cancelled the payment.
-2	Expired	Payment has expired
-3	Unknown	The status of the payment cannot be determined automatically, this status will be tracked by our operators and resolved

Refund

Parameter	Type	Description	Example
amount	Integer	The amount (in IRR) to refund	10000
created_at	String (ISO-8601 Date)	The time when the refund was created	"2022-01-01T12:17:46.772196Z"
status	Integer	Status of the refund. See Refund Status	1

Refund Status

Status Number	Code Name	Description
1	Pending	The refund has just been created
2	Successful	Refund is successful
3	Failed	There is an error in the refund process, the users received no money
-1	Unknown	Status of the refund can not be determined automatically. You can treat this status the same as pending.

Toman Endpoints

Base URLs

The base URLs for our staging and productions API servers are

Environment	URL
Production	`https://ipg.toman.ir`
Staging	`https://ipg-staging.toman.ir`

Pagination schema

All IPG 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://ipg-staging.toman.ir/payments?page=2"
previous	String (Nullable)	The URL of the next page containing items after this page's items	"https://ipg-staging.toman.ir/payments?page=4"
results	Array[Object]	The array containing the items of this page

Create Payment

import json

import requests

url = f"{base_url}/payments"

payload = json.dumps(
    {
        "amount": 10000,
        "mobile_number": "09121234567",
        "check_national_id": False,
        "tracker_id": "my_unique_tracker_id",
        "callback_url": "https://my_domain.ir/callback/",
        "card_numbers": ["1234567812345678", "1234567887654321"]
    }
)
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}

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

curl --location -g --request POST "$BASE_URL/payments" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" \
--data-raw '{
        "amount": 10000,
        "mobile_number": "09121234567",
        "check_national_id": false,
        "tracker_id": "my_unique_tracker_id",
        "callback_url": "https://my_domain.ir/callback/",
        "card_numbers": ["1234567812345678", "1234567887654321"]
    }'

`POST /payments`

Scope

payment.create

Creates a new Payment and gets a token for it from the automatically chosen PSP

Request Body

Parameter	Type	Description	Example
amount	Long	The amount to be paid, in Rials. Note that this is the amount that the user will be paying in the payment gateway.	120000
callback_url	String	This is an absolute URL to your callback endpoint which will be called after user has finished the payment process. Note that the domain of your callback_url must be registered and validated in Toman.	"https://my_domain.ir/callback/"
mobile_number	String (Optional)	The mobile number to be delivered to the PSP. When this field is provided, the PSP will suggest the card numbers that the user used before to them. It is also used in the process of National ID check.	"+989123456789"
check_national_id	Boolean (Default: false)	Performs a check on the National ID of the owner of the card against the National ID of the owner of the mobile number and aborts the payment if they don't match. The `mobile_number` should not be null if this value is `true`	true
tracker_id	String (Optional)	This is an ID you can provide for the payment, which will be returned to your `callback_url` for you to verify the payment. Note that due to security reasons, It is highly advised to generate and save a tracker_id for each payment in your database.	"this_is_my_unique_tracker_id"
card_numbers	Array[String] (Optional)	The list of the card numbers to be used in the payment process. If you want to limit the card numbers by which the users pays, you can fill this field.	["1234567812345678", "8765432187654321"]

Response Body

Parameter	Type	Description	Example
uuid	String	A UUID 4 string which uniquely identifies the payment. This field is generated by Toman when the partner wants to create a new payment. You need to use this UUID to perform any actions on your payment. (e.g. redirect to PSP)	"49ca936f-9ca0-4f0b-9a9d-f87b6da65642"
tracker_id	String	This is the `tracker_id` you have sent in your request body. You can use this value when your callback endpoint gets called to be able to track the payment.	"this_is_my_unique_tracker_id"

Request Data Example

{
  "amount": 10000,
  "mobile_number": "09121234567",
  "check_national_id": false,
  "tracker_id": "my_unique_tracker_id",
  "callback_url": "https://my_domain.ir/callback/",
  "card_numbers": [
    "1234567812345678",
    "1234567887654321"
  ]
}

Response Data Example

{
  "uuid": "49ca936f-9ca0-4f0b-9a9d-f87b6da65642",
  "tracker_id": "my_unique_tracker_id"
}

Errors

Code	Description
partner_info_not_fetched	Cannot fetch your identity
no_psp_available	No PSP is currently available

Redirect to PSP

Redirects the customer to the payment gateway. After you created the payment, you should redirect your user to the following url. Toman will notify you with payment result when the customer has finished the payment. Note the redirect is difference with send request.

`GET payments/<uuid>/redirect`

Redirecting to this endpoint is usually implemented via an HTTP redirect response.

Path Parameters

Parameter	Type	Description	Example
UUID	String	The UUID of the payment	49ca936f-9ca0-4f0b-9a9d-f87b6da65642

Errors

Code	Description
http_404_not_found	Not found
status_change_not_allowed	Cannot change the status of payment from <from_status> to `redirected_to_psp`
payment_is_expired	The payment has been expired

Verify Payment

import requests

url = f"{base_url}/payments/{payment_uuid}/verify"

headers = {
    "Authorization": f"Bearer {token}"
}

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

curl --location -g --request POST "$BASE_URL/payments/$PAYMENT_UUID/verify" \
--header "Authorization: Bearer $TOKEN"

`POST /payments/<uuid>/verify`

Scope

payment.create

When the payment is successful Toman will inform you about the status of the payment through your callback endpoint. You must check the validity of the callback data (e.g. Check that the uuid field and the amount match) and then verify the payment. This step is required to prevent refunding the money to the user and shows that your service correctly received the callback. If verification is successful, you will receive a 200 status code, otherwise an HTTP 400 status code with the proper error detail will be provided to you.

Please note that some PSPs do not provide the whole payment data in the callback, and some fields might be returned to you in the verify response.

Path Parameters

Parameter	Type	Description	Example
UUID	String	The uuid field of the payment	49ca936f-9ca0-4f0b-9a9d-f87b6da65642

Request Body

None

Response Body

A Payment Object

Response Data Example

{
  "uuid": "49ca936f-9ca0-4f0b-9a9d-f87b6da65642",
  "amount": 10000,
  "psp": "4180b0d6-8dca-4ea4-9a97-5323eeae59dd",
  "status": 5,
  "toman_wage": 123,
  "shaparak_wage": 1200,
  "verified_at": null,
  "trace_number": "687668",
  "reference_number": "21458790785",
  "digital_receipt_number": "GmshtyjwKSuw15ogyWW+8n66VdBfBVjF6mga37Q7Rb",
  "terminal_number": "12345678",
  "acceptor_code": 1234567,
  "tracker_id": "my_tracker_id"
}

Make sure to check the given Payment Object's amount to match the actual service/product amount, as well as the status field to be called-back before calling this method.

Errors

Code	Description
http_404_not_found	Not found
status_change_not_allowed	Cannot change the status of payment from <from_status> to `verified`
payment_is_expired	The payment has been expired
psp_global_error	PSP <psp_name> has raised an error

Get Payment Details

import requests

url = f"{base_url}/payments/{payment_uuid}"

headers = {
    "Authorization": f"Bearer {token}"
}

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

curl "$BASE_URL/payments/$PAYMENT_UUID" \
--header "Authorization: Bearer $TOKEN"

`GET /payments/<uuid>`

Scope

payment.list

Retrieve details of a payment.

Path Parameters

Parameter	Type	Description	Example
UUID	String	The uuid field of the payment	49ca936f-9ca0-4f0b-9a9d-f87b6da65642

Request Body

None

Response Body

Parameter	Type	Description	Example
uuid	String	A UUID 4 string which uniquely identifies the payment. This field is generated by Toman when the partner wants to create a new payment	"dc5f4898-2d82-4263-b2da-47171304cb96"
amount	Long	The amount to be paid, in Rials	12000
toman_wage	Long	How much of this payment should pay to Toman as the fee for the transaction (Based on the percentage contracted with Toman including VAT.) , in Rials	123
shaparak_wage	Long	How much of this payment should pay to Shaparak as the fee for the transaction(It is 0.0002 of the transaction amount with min of 1200 and max of 40000 rials) , in Rial	1200
tracker_id	String (Nullable)	This is an ID you can provide for the payment, which will be returned to your `callback_url` for you to verify the payment. Note that due to security reasons, It is highly advised to generate and save a tracker_id for each payment.	"this_is_my_unique_tracker_id"
verified_at	String (ISO-8601 Date) (Nullable)	The exact time of the verification of this payment	"2022-01-01T12:17:46.772196Z"
status	Integer	The current status of the payment. Can be an integer between -3 to 5. See Payment Status	4
psp	String	The chosen PSP to handle this payment. At the moment we only support SEP so the only possible value is `SEP`.	"SEP"
terminal_number	String	The terminal number of the partner used in this payment	"term2309"
trace_number	String (Nullable)	Only set for successful payments, returned by the PSP.	687668
reference_number	String (Nullable)	Only set for successful payments, returned by the PSP.	21458790785
digital_receipt_number	String (Nullable)	Only set for successful payments, returned by the PSP.	GmshtyjwKSuw15ogyWW+8n66VdBfBVjF6mga37Q7Rb
terminal_number	Integer	This is your terminal number, you should show this value to the user when payment is finished	14115046
acceptor_code	Integer	This is your acceptor code, you should show this value to the user when payment is finished	14115046

Request Example

    GET /payments/49ca936f-9ca0-4f0b-9a9d-f87b6da65642

Response Data Example

{
  "uuid": "49ca936f-9ca0-4f0b-9a9d-f87b6da65642",
  "amount": 10000,
  "psp": "4180b0d6-8dca-4ea4-9a97-5323eeae59dd",
  "status": 4,
  "toman_wage": 123,
  "shaparak_wage": 1200,
  "verified_at": null,
  "trace_number": "687668",
  "reference_number": "21458790785",
  "digital_receipt_number": "GmshtyjwKSuw15ogyWW+8n66VdBfBVjF6mga37Q7Rb",
  "terminal_number": "12345678",
  "acceptor_code": 1234567,
  "tracker_id": "my_tracker_id"
}

Errors

Code	Description
http_404_not_found	Not found

Refund

import requests

url = f"{base_url}/payments/{payment_uuid}/refund"

headers = {
    "Authorization": f"Bearer {token}"
}

data = {
    "amount": 10000
}
response = requests.request("POST", url, json=data, headers=headers)

curl --location -g --request POST "$BASE_URL/payments/$PAYMENT_UUID/refund" \
--header "Authorization: Bearer $TOKEN --data '{
    "amount": 1000
}'"

`POST /payments/<uuid>/refund`

Scope

payment.create

You can ues this endpoint to refund a portion or the whole amount of a payment to your user/customer. This endpoint can only be called for successful (verified) payments.

Path Parameters

Parameter	Type	Description	Example
UUID	String	The uuid field of the payment	49ca936f-9ca0-4f0b-9a9d-f87b6da65642

Request Body

Parameter	Type	Description	Example
amount	Integer	The amount (in IRR) you want to return to your customer	10000

Response Body

A Refund Object

Request Data Example

{
  "amount": 10000
}

Response Data Example

{
  "amount": 10000,
  "created_at": "2022-01-01T12:12:12.772196Z",
  "status": 1
}

Errors

Code	Description
partner_info_not_fetched	Cannot fetch your identity
refund_not_allowed	The payment is in an invalid state for refund, i.e. it is not verified
invalid_refund_amount	Refund amount is greater than the payment amount
refund_not_available	The psp does not support refunding

Payments list

Used for get all Payments record with pagination.

import requests

url = f"{base_url}/payments"

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

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

curl --location "$BASE_URL/payments" \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'

`GET /payments`

Scope

payment.list

Request Body

Without any request body.

Response Data Example

The response of this endpoint is following pagination. The results key will be Array of each payment detail:

Parameter	Type	Description	Example
count	Integer	The total number of Payments across all pages	24578
next	String (Nullable)	The URL of the next page containing items after this page's items	"https://ipg.toman.ir/payments?page=20"
previous	String (Nullable)	The URL of the next page containing items after this page's items	"https://ipg.toman.ir/payments?page=22"
results	Array[payment detail inside of list]	The array containing the payments of this page that follows the schema of pagination

Detail of payments inside list API

Each item inside of results key is:

Parameter	Type	Description	Example
uuid	String	A UUID 4 string which uniquely identifies the payment. This field is generated by Toman when the partner wants to create a new payment	"dc5f4898-2d82-4263-b2da-47171304cb96"
amount	Long	The amount to be paid, in Rials	12000
verified_at	String (ISO-8601 Date) (Nullable)	The exact time of the verification of this payment.	"2022-01-01T12:17:46.772196Z"
status	Integer	The current status of the payment. Can be an integer between -3 to 5. See Payment Status	4
psp	String	The chosen PSP to handle this payment. At the moment we only support SEP so the only possible value is `SEP`.	"SEP"

Response Data Example

{
  "count": 124,
  "next": "https://ipg.toman.ir/payments?page=3",
  "previous": "https://ipg.toman.ir/payments?page=1",
  "results": [
    {
      "uuid": "2e9e406a-49db-480d-9433-f7a566649c6e",
      "amount": 10000,
      "psp": "SEP",
      "status": -1,
      "verified_at": null
    },
    {
      "uuid": "7f444076-c78d-43f6-878f-c0a6c1631fca",
      "amount": 10000,
      "psp": "SEP",
      "status": 3,
      "verified_at": "2023-03-26T08:42:53.330604Z"
    },
    {
      "uuid": "92c58233-dc28-4ffe-9a7a-b9700271838c",
      "amount": 12345,
      "psp": "SEP",
      "status": 3,
      "verified_at": null
    },
    {
      "uuid": "f34f4717-9669-4a50-acf3-9ddb4eb40278",
      "amount": 20000,
      "psp": "SEP",
      "status": 3,
      "verified_at": "2023-03-26T08:42:53.330604Z"
    },
    {
      "uuid": "a7726c34-bc00-4a67-a05d-ac1283635949",
      "amount": 20000,
      "psp": "SEP",
      "status": 5,
      "verified_at": "2023-04-19T14:38:21.261807Z"
    },
    {
      "uuid": "6d90fd1c-7ef9-424d-9deb-47a3630cce70",
      "amount": 20000,
      "psp": "SEP",
      "status": 4,
      "verified_at": null
    },
    {
      "uuid": "5a80e48e-845b-4b96-9b17-babbc1f2ab24",
      "amount": 100000,
      "psp": "SEP",
      "status": 3,
      "verified_at": "2023-03-26T08:42:53.330604Z"
    },
    {
      "uuid": "dead82b9-920e-42bc-8888-ad18de2dd5b7",
      "amount": 10000,
      "psp": "SEP",
      "status": 3,
      "verified_at": null
    },
    {
      "uuid": "099da60d-b7cb-447a-a3fc-d6d72ef95ed7",
      "amount": 100000,
      "psp": "SEP",
      "status": 3,
      "verified_at": null
    },
    {
      "uuid": "ce478e81-c528-41e2-a450-d946847e6b1e",
      "amount": 20000,
      "psp": "SEP",
      "status": 3,
      "verified_at": "2023-03-26T08:42:53.330604Z"
    },
    {
      "uuid": "76b41e6e-a612-4f92-9911-a4059fd3a7ee",
      "amount": 100000,
      "psp": "SEP",
      "status": 4,
      "verified_at": "2023-03-28T08:45:53.330604Z"
    },
    {
      "uuid": "2009299f-459c-4ce9-8ad3-aaab1a6068e9",
      "amount": 10000,
      "psp": "SEP",
      "status": -1,
      "verified_at": "2023-03-26T08:42:53.330604Z"
    },
    {
      "uuid": "4da99a07-c3a8-4389-815d-9d645405d652",
      "amount": 10000,
      "psp": "SEP",
      "status": 3,
      "verified_at": "2023-03-26T19:42:53.330604Z"
    },
    {
      "uuid": "33009d6f-6b9e-4bdd-b506-000cb99c92ae",
      "amount": 10000,
      "psp": "SEP",
      "status": 3,
      "verified_at": "2023-03-26T18:42:53.330604Z"
    },
    {
      "uuid": "242b97e8-f4f2-4eb7-a4cf-1504c9762adc",
      "amount": 10000,
      "psp": "SEP",
      "status": 5,
      "verified_at": "2023-03-26T10:36:01.173222Z"
    },
    {
      "uuid": "c4d45516-08d0-4110-9d6a-d8f6d288c729",
      "amount": 10000,
      "psp": "SEP",
      "status": 5,
      "verified_at": "2023-03-26T08:42:53.330604Z"
    }
  ]
}

Payments list with Filters

import requests

url = f"{base_url}/payments"

headers = {
    'Authorization': 'Bearer thisistoken}'
}

params = {
    'status__in': '1,2,3',  # Replace with desired status values
    'amount__gte': '10000',    # Replace with desired minimum amount
    'amount__lte': '100000',   # Replace with desired maximum amount
    'created_at_after': '2023-09-03T21%3A45%3A24.000Z',  # Replace with desired start date
    'created_at_before': '2023-09-03T21%3A30%3A33.000Z'  # Replace with desired end date
}

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

curl --location "$BASE_URL/payments?status__in=5&amount__gte=10000&amount__lte=5000000&created_at_after=2023-09-03T21%3A45%3A24.000Z" \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'

You can use the GET /payments endpoint to retrieve a list of payments with specific filters. This endpoint supports several query parameters that allow you to customize your payment list.

Filtering by Status

You can filter payments based on their status using the status__in parameter. This parameter accepts a comma-separated list of status values. You can refer to the Payment Status documentation for a list of available status values.

Example: GET /payments?status__in=1,2,3

Filtering by Amount

You can filter payments based on their amount using the amount__gte and amount__lte parameters. amount__gte specifies the minimum amount, while amount__lte specifies the maximum amount.

Example: GET /payments?amount__gte=10000&amount__lte=100000

Filtering by Creation Date

You can filter payments based on their creation date using the created_at_after and created_at_before parameters. These parameters accept datetime values in ISO format.

Example: GET /payments?created_at_after=2023-09-03T21%3A45%3A24.000Z&created_at_before=2023-09-03T21%3A30%3A33.000Z

With these filters, you can customize your payment list to include only the payments that match your criteria based on status, amount, and creation date.

Payment Settle Information

import json

import requests

url = f"{base_url}/payments/settle-info"

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

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

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

`GET /payments/settle-info`

Scope

payment.list

This API endpoint allows users with appropriate permissions to retrieve payment settlement information for a partner.\ Also, it calculates the sum of payments created after the last settlement date for each terminal (unsettled amount + settling amount).\ Additionally, it retrieves the total amount in progress for settlement across all terminals (settling amount).

Request Body

Without any request body.

Response Body

Parameter	Type	Description	Example
unsettle_payments	Integer	The sum of payments that are created after the last settlement date for your each terminal (unsettled amount + settling amount).	10000000
shaparak_amount_in_progress	Integer	The total amount in progress for settlement in shaparak old fashion system (settling amount).	3800000

Request Data Example

Without any request body.

Response Data Example

{
  "unsettle_payments": 10000000,
  "shaparak_amount_in_progress": 3800000
}

Errors

Code	Description
no_terminal_for_partner	No terminals found for the partner.

Partner Endpoints

Other than calling our endpoints, you should provide us with a callback endpoint, so we can inform you about the result of the payment process and redirect the customer to it.

Partner callback

`POST callback_url` (called by Toman)

This is an endpoint provided by you and is called by Toman in order to inform the result of the payment.

Toman will redirect the customer to endpoint via POST method and will send the payment details with Content-Type: application/x-www-form-urlencoded header.

Some PSPs do not return all the fields in the callback data. As an example, the reference_number field in Sadad PSP will always be empty in callback data and you can only receive it during verify request.

Path Parameters

None

Request Body

A Payment Object

Request Example

POST /your/callback/url HTTP/2
Host: partner.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 272
Connection: keep-alive

uuid=49ca936f-9ca0-4f0b-9a9d-f87b6da65642&
amount=10000&
mobile_number=09121234567&
tracker_id=my_tracker_id
psp=SEP&
terminal=13222960&
trace_number=697769&
reference_number=21357791984&
digital_receipt_number=GeshtyjwnSfw15oguWW%2B8n66VrBfBVjF6mga37v7Rb&
status=4&
error_detail=

Errors

{
  "non_field_errors": [
    {
      "code": "partner_info_not_fetched",
      "detail": "Cannot fetch your identity."
    }
  ],
  "username": [
    {
      "code": "required",
      "detail": "This field is required."
    }
  ]
}

All errors coming back from Toman API follow a specific format. If an error is related to a specific field, you can find it inside a list with the mentioned field's name. If the error is about the request in general and not a specific field it can be found inside the non_field_errors list. You can see an example of an error response in the code section.

Parameter	Type	Description	Example
non_field_errors	Array	List of error(s) that are not bound to any specific field
non_field_errors.code	String	The identifier of the error. You can use this code to programmatically determine what went wrong	"partner_info_not_fetched"
non_field_errors.detail	String	The programmer readable error detail. This field is subject to change and should not be used to identify the error	"Cannot fetch your identity."
<field_name>	Array	List of error that are bound to a specific field. This parameter's name is the name of the field
<field_name>.code	String	The identifier of the error. You can use this code to programmatically determine what went wrong	"required"
<field_name>.detail	String	The programmer readable error detail. This field is subject to change and should not be used to identify the error	"This field is required."