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.

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.

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
uuid	String	A UUID 4 string which uniquely identifies the refund. This field is generated by Toman when the partner wants to create a new refund	"dce5aef0-118c-4c5c-9e0e-7726a1c4d743"
payment	String	The payment uuid that refund created based on that payment and remain amount	"3455234b-b96e-4734-95bb-8936a2f06f4c"
status	Integer	Status of the refund. See Refund Status	1
amount	Integer	The amount (in IRR) to refund	100000
toman_wage	Integer	Toman wage amount that partner should pay for request and processing that refund	120
reference_number	String (Nullable)	The unique reference number generated by refund service provider for tracking the refund in the banking system	"1755156845"
trace_number	String (Nullable)	The unique trace number generated by refund service provider	"50002"
tracker_id	String (Nullable)	The unique tracker id generated by the partner for tracking specific refund in Toman system	"112233445566"
created_at	String (ISO-8601 Date)	The exact time of the creation of this refund	2023-10-01T12:12:12.772196Z

Refund Status

Status Number	Code Name	Description
0	Creating	The refund has just been created in Toman system
1	Pending	The refund is in progress and waiting to be finalized
2	Successful	Refund is successful
3	Failed	There is an error in the refund process, the users received no money
4	Denied	There is an error in the refund transaction; for example, your wallet is empty.
-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"],
        "options": {
            "terminal_number": "13268913"
        }
    }
)
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"],
        "options": {
            "terminal_number": "13268913"
        }
    }'

`POST /payments`

Scope

payment.create

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

Create Options:

When creating a payment, you have the option to customize certain parameters based on your requirements. By default, the payment settings are applied as configured by the system administrator when creating a terminal for your partner. However, you can override these default settings by including specific parameters in your request.

Available Payment Option:

terminal_number(string): You can select a specific terminal for this payment from the list of terminals associated with your account. This allows you to have fine-grained control over the payment process.

Notes:

Please ensure that you provide a valid terminal number to complete the payment process successfully.

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"]
options	Dict{} (Optional)	The dict of the options such as "terminal_number" to be used in the create payment process. If you want creat payment in specific terminal can send them in this field.	{"terminal_number": "13268913" }

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"
  ],
  "options": {
    "terminal_number": "13268913"
  }
}

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
invalid_terminal_configuration	You do not have any active terminals which satisfy these configurations.

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,
  "mobile_number": "09123456789",
  "tracker_id": "my_tracker_id",
  "psp": "4180b0d6-8dca-4ea4-9a97-5323eeae59dd",
  "terminal": "12345678",
  "trace_number": "687668",
  "reference_number": "21458790785",
  "digital_receipt_number": "GmshtyjwKSuw15ogyWW+8n66VdBfBVjF6mga37Q7Rb",
  "status": 5,
  "error_detail": null,
  "masked_paid_card_number": "6219********0852",
  "reverse_trace_number": 78974564,
  "reverse_reference_number": 123456798,
  "created_at": "2022-01-01T12:17:46.772196Z",
  "verified_at": "2022-01-01T12:17:46.772196Z",
  "reversed_at": null
}

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`
psp_not_respond	PSP SEP does not respond currently. It may cause by payment is not at the wright status
payment_is_expired	The payment has been expired
psp_global_error	PSP <psp_name> has raised an error

Get Payment Details

Retrieve details of a payment.

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

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
wage	Long	How much of this payment would be paid to Toman and Shaparak as commission of the transaction ( toman_wage + shaparak_wage )	1323
psp	String	The chosen PSP to handle this payment. At the moment we only support SEP so the only possible value is `SEP`.	"SEP"
status	Integer	The current status of the payment. Can be an integer between -3 to 5. See Payment Status	4
created_at	String (ISO-8601 Date)	The exact time of the creation of this payment	"2022-01-01T12:17:46.772196Z"
verified_at	String (ISO-8601 Date) (Nullable)	The exact time of the verification of this payment	"2022-01-01T12:17:46.772196Z"
reversed_at	String (ISO-8601 Date) (Nullable)	The exact time of the reversal of this payment	"2022-01-01T12:17:46.772196Z"
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
masked_paid_card_number	String (Nullable)	Only set for successful payments, returned by the PSP.	GmshtyjwKSuw15ogyWW+8n66VdBfBVjF6mga37Q7Rb
reverse_trace_number	String (Nullable)	Only set for reversed payments, returned by the PSP.	GmshtyjwKSuw15ogyWW+8n66VdBfBVjF6mga37Q7Rb
reverse_reference_number	String (Nullable)	Only set for reversed 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
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"
is_refunded	Bool	Does this payment have any refund?	false

Request Example

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

Response Data Example

{
    "uuid": "8c91b026-a8a2-4239-855e-46c9a65b05ea",
    "amount": 100000,
    "wage": 2290,
    "toman_wage": 1090,
    "shaparak_wage": 1200,
    "psp": "SADAD",
    "status": -2,
    "created_at": "2023-12-20T11:36:48.564216Z",
    "verified_at": null,
    "reversed_at": null,
    "trace_number": null,
    "reference_number": null,
    "digital_receipt_number": null,
    "masked_paid_card_number": null,
    "reverse_trace_number": null,
    "reverse_reference_number": null,
    "terminal_number": "1111111",
    "acceptor_code": 900036482,
    "tracker_id": null,
    "is_refunded": false
}

Errors

Code	Description
http_404_not_found	Not found

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
psp	String	The chosen PSP to handle this payment. At the moment we only support SEP so the only possible value is `SEP`.	"SEP"
status	Integer	The current status of the payment. Can be an integer between -3 to 5. See Payment Status	4
created_at	String (ISO-8601 Date) (Nullable)	The exact time of the creation of this payment.	"2022-01-01T12:17:46.772196Z"
verified_at	String (ISO-8601 Date) (Nullable)	The exact time of the verification of this payment.	"2022-01-01T12:17:46.772196Z"
reversed_at	String (ISO-8601 Date) (Nullable)	The exact time of the reversal of this payment.	"2022-01-01T12:17:46.772196Z"
terminal_number	Integer	This is your terminal number, you should show this value to the user when payment is finished	14115046
is_refunded	Bool	Is this payment has any refund	false

Response Data Example

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "uuid": "04cb0674-4d55-4bc7-9f9c-4001da357a37",
      "amount": 12345,
      "psp": "SADAD",
      "status": -2,
      "created_at": "2023-12-30T12:28:02.496905Z",
      "verified_at": null,
      "reversed_at": null,
      "is_refunded": false,
      "terminal_number": "111111111"
    },
    {
      "uuid": "b4c88efc-4273-4fcf-ab78-bb02017f0a9e",
      "amount": 12345,
      "psp": "SEP",
      "status": 5,
      "created_at": "2023-12-23T17:27:08.723196Z",
      "verified_at": "2023-12-23T17:30:29.438628Z",
      "reversed_at": null,
      "is_refunded": true,
      "terminal_number": "111111111"
    },
    {
      "uuid": "61fa9bed-2bb6-4743-b00e-f9bd2e9c7d6e",
      "amount": 12345,
      "psp": "SEP",
      "status": 0,
      "created_at": "2023-12-20T12:29:08.051591Z",
      "verified_at": "2023-12-20T12:32:29.765363Z",
      "reversed_at": "2023-12-20T12:32:44.248630Z",
      "is_refunded": false,
      "terminal_number": "111111111"
    }
  ]
}

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
    'search': '6037997100000000'  # Replace with desired search field
}

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&terminal_numbers=123456,654321&search=6037997100000000" \
--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.

Filtering by Terminal Number

You can filter payments based on their terminal number using the terminal_numbers parameter. This parameter accepts a comma-separated list of terminal numbers.

Example: GET /payments?terminal_numbers=30037210,30037211,30037212

Search on Payment

You can search on payments based on the following fields:

uuid
trace_number
digital_receipt_number
tracker_id
reference_number
masked_paid_card_number

For searching on payments, use the search parameter to search among to payment fields. It filters all payments that include given value on above fields

Example: GET /payments?search=6542315

Payment Settle Information

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

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

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

Response Data Example

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

Errors

Code	Description
no_terminal_for_partner	No terminals found for the partner.

Reverse Payment

This endpoint allows partners to initiate the reversal of a payment. Payment reversal is necessary when a transaction needs to be canceled or reverted. It ensures that payments are handled accurately and reverse are processed correctly. The payment's status must verified before.

Notes: Reversing a payment is a critical operation that must be handled with care. It involves contacting the PSP and ensuring that the transaction is successfully canceled or reverted.

import requests

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

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

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

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

`POST /payments/<uuid>/reverse`

Scope

payment.create

Potential Challenges:

Reversal Period: The reversal of a payment must be initiated within a specific reversal period. If this period has expired, your reversal request may not be processed successfully.
PSP-Side Errors: It's possible that the Payment Service Provider (PSP) may encounter errors or issues during the reversal process. In such cases, your reversal request may not be completed as expected. you should try to handle given error code based on the error codes in document.

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,
  "mobile_number": "09123456789",
  "tracker_id": "my_tracker_id",
  "psp": "4180b0d6-8dca-4ea4-9a97-5323eeae59dd",
  "terminal": "12345678",
  "trace_number": "687668",
  "reference_number": "21458790785",
  "digital_receipt_number": "GmshtyjwKSuw15ogyWW+8n66VdBfBVjF6mga37Q7Rb",
  "status": 0,
  "error_detail": null,
  "masked_paid_card_number": "6219********0852",
  "reverse_trace_number": 78974564,
  "reverse_reference_number": 123456798,
  "created_at": "2022-01-01T12:17:46.772196Z",
  "verified_at": "2022-01-01T12:17:46.772196Z",
  "reversed_at": "2022-01-01T12:17:46.772196Z"
}

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 Verified 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 `reverted`
payment_reverse_time_expired	This payment reverse time is expired
can_not_create_reverse_request	Can't build payload for payment reverse request.
psp_not_respond	PSP <psp_name> does not respond currently.
psp_reverse_time_expired	This payment was not reversed, PSP reversal time is expired.
psp_reverse_rejected	This payment was not reversed, and PSP rejected reversal.

Terminal list

You can use this API to retrieve terminal list in the format of given sample data and also filter set.

import requests

url = f"{base_url}/terminals"

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

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

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

`GET /terminals`

Scope

ipg.terminal.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 each terminal detail:

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

Detail of terminals inside list API

Each item inside of results key is:

Parameter	Type	Description	Example
uuid	String	A UUID 4 string which uniquely identifies the terminal. This field is generated by Toman when the create a new terminal	"dc5f4898-2d82-4263-b2da-47171304cb96"
psp	String	The name of the PSP that terminal connected for process requests.	"SEP"
terminal_number	String	The terminal number in SHAPARAK old fashion system.	"879546132"
acceptor_code	Integer	The terminal acceptor coder that used in SHAPARAK old fashion system.	454654654
iban	String	The terminal IBAN number in banking system.	"IR2300000000000023232323232"
enabled	Bool	The terminal activation status can True or False in Toman system.	true

Response Data Example

{
  "count": 4,
  "next": null,
  "previous": null,
  "results": [
    {
      "uuid": "924ea30d-3aa3-4e0d-a314-94545ce7c07",
      "psp": "SEP",
      "terminal_number": "1234567",
      "acceptor_code": 14086523,
      "iban": "IR620180000000002254654000",
      "enabled": true
    },
    {
      "uuid": "924ea30d-3a4654650d-a314-949697ce7c07",
      "psp": "SADAD",
      "terminal_number": "9654654",
      "acceptor_code": 13165456,
      "iban": "IR546500000000000654012067000",
      "enabled": true
    },
    {
      "uuid": "924ea30d-3aa3-4e0d-a314-7987465416541",
      "psp": "SEP",
      "terminal_number": "6546546546",
      "acceptor_code": 1654646,
      "iban": "IR23000000000000000564654100121",
      "enabled": true
    },
    {
      "uuid": "924ea30d-89987-a314-949697ce7c07",
      "psp": "SADAD",
      "terminal_number": "5646546",
      "acceptor_code": 546546465,
      "iban": "IR89000000000000000005246546546",
      "enabled": false
    }
  ]
}

Terminals list with Filters

import requests

url = f"{base_url}/terminals"

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

params = {
    'psp_name': "SEP,SADAD",  # Replace with desired PSP name values
    'acceptor_code': 235664544,  # Replace with desired acceptor code
    'terminal_number': '13658974',  # Replace with desired terminal number
}

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

curl --location "$BASE_URL/terminals?psp_name="SEP,SADAD"&terminal_number="13658974"&acceptor_code=235664544" \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'

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

Filtering by PSP name

You can filter terminals based on their PSP name's using the psp_name parameter. This parameter accepts a comma-separated list of status values.

Example: GET /terminals?psp_name="SEP"

Filtering by Acceptor Code

You can filter terminals based on their acceptor code using the acceptor_code parameter.

Example: GET /terminals?acceptor_code=235664544

Filtering by Terminal Number

You can filter terminals based on their terminal number using the terminal_number parameter.

Example: GET /terminals?terminal_number="13658974"

With these filters, you can customize your terminal list based on psp name, acceptor code, and terminal number.

Payment Refund

The Refund API allows you to initiate a refund for a specific payment using a simple HTTP POST request, this functionality is useful in scenarios where a transaction needs to be refunded, and funds returned to the payer.

import requests

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

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

data = {
    "amount": 10000,
    "tracker_id": "71fe6655-f2bb-4293-a442-de0d80568a48"  # optional
}
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": 10000
    "tracker_id": "71fe6655-f2bb-4293-a442-de0d80568a48"
}'"

`POST /payments/<uuid>/refund`

Scope

ipg.refund.create

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
tracker_id	String (Nullable)	Tracker ID for the refund by the partner. This field must be unique (optional)	"10000a"

Response Body

Parameter	Type	Description	Example
uuid	String	A UUID 4 string which uniquely identifies the refund. This field is generated by Toman when the partner wants to create a new refund	"dce5aef0-118c-4c5c-9e0e-7726a1c4d743"
payment	String	The payment UUID 4 that refund created based on that payment and remain amount	"3455234b-b96e-4734-95bb-8936a2f06f4c"
status	Integer	Status of the refund. See Refund Status	1
amount	Integer	The amount (in IRR) to refund	100000
toman_wage	Integer	Toman wage amount that partner should pay for request and processing that refund	120
tracker_id	String (Nullable)	The uniquely tracker id that given by partner for tracking specific refund in toman system	"112233445566"
payment_reference_number	String	The related reference number on payment	"21458790785"
payment_tracker_id	String (Nullable)	The related tracker id on payment	"21458790785"
payment_terminal_number	String	The related terminal number on payment	"14115046"
payment_masked_paid_card_number	String	The related masked paid card number on payment	"603799******5249"
created_at	String (ISO-8601 Date)	The exact time of the creation of this refund	"2023-10-01T12:12:12.772196Z"

Request Data Example

{
  "amount": 10000,
  "tracker_id": "b4c88efc-4273-4fcf-ab78-bb02017f0a9e"
}

Response Data Example

{
  "uuid": "dce5aef0-118c-4c5c-9e0e-7726a1c4d743",
  "payment": "3455234b-b96e-4734-95bb-8936a2f06f4c",
  "status": 0,
  "amount": 10000,
  "toman_wage": 120,
  "tracker_id": "b4c88efc-4273-4fcf-ab78-bb02017f0a9e",
  "payment_reference_number": "1321321321312",
  "payment_tracker_id": "1321321321312",
  "payment_terminal_number": "1321321321312",
  "payment_masked_paid_card_number": "603799******5249",
  "created_at": "2023-10-01T12:12:12.772196Z"
}

Errors

Code	Description
partner_info_not_fetched	Cannot fetch your identity
payment_not_found	Cannot find the payment for refund
refund_not_allowed	You can not refund this payment at the moment., i.e. it is not verified
invalid_refund_amount	Refund amount can not be greater than the payment amount.

Payment Refunds List

The Payment Refunds List API provides a way to retrieve a list of refunds associated with a specific payment, this information is valuable for tracking and auditing purposes, allowing you to view the history of refunds for a given payment.

import requests

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

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

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

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

`GET /payments/<uuid>/refund`

Scope

ipg.refund.read

Request Body

Without any request body.

Response Body

Parameter	Type	Description	Example
count	Integer	The total number of refunds across all pages	143
next	String (Nullable)	The URL of the next page containing items after this page's items	"https://ipg.toman.ir/payments/dce5aef0-118c-4c5c-9e0e-7726a1c4d743/refund?page=1"
previous	String (Nullable)	The URL of the next page containing items after this page's items	"https://ipg.toman.ir/payments/dce5aef0-118c-4c5c-9e0e-7726a1c4d743/refund?page=3"
results	Array[refund detail inside of list]	The array containing the refunds of this page that follows the schema of pagination

Detail of refunds inside list API

Each item inside of results key is:

Parameter	Type	Description	Example
uuid	String	A UUID 4 string which uniquely identifies the refund. This field is generated by Toman when the partner wants to create a new refund	"dce5aef0-118c-4c5c-9e0e-7726a1c4d743"
payment	String	The payment UUID 4 that refund created based on that payment and remain amount	"3455234b-b96e-4734-95bb-8936a2f06f4c"
status	Integer	Status of the refund. See Refund Status	1
amount	Integer	The amount (in IRR) to refund	100000
toman_wage	Integer	Toman wage amount that partner should pay for request and processing that refund	120
tracker_id	String (Nullable)	The uniquely tracker id that given by partner for tracking specific refund in toman system	"112233445566"
payment_reference_number	String	The related reference number on payment	"21458790785"
payment_tracker_id	String (Nullable)	The related tracker id on payment	"21458790785"
payment_terminal_number	String	The related terminal number on payment	"14115046"
payment_masked_paid_card_number	String	The related masked paid card number on payment	"603799******5249"
created_at	String (ISO-8601 Date)	The exact time of the creation of this refund	"2023-10-01T12:12:12.772196Z"
updated_at	String (ISO-8601 Date)	The exact time of the update of this refund	"2023-10-01T12:12:12.772196Z"
psp	String	The chosen PSP to handle this payment. `SEP`.	"SEP"

Response Data Example

{
  "count": 6,
  "next": null,
  "previous": null,
  "results": [
    {
      "uuid": "c2cc7dd4-73f6-447b-9227-eca533fdb1b1",
      "payment": "6264b779-4795-4de5-b600-b007e4020839",
      "status": -1,
      "amount": 1,
      "toman_wage": 1,
      "tracker_id": null,
      "payment_reference_number": "22823714381",
      "payment_tracker_id": "564646450006456456",
      "payment_terminal_number": "1111111111111",
      "payment_masked_paid_card_number": "603799******5249",
      "created_at": "2024-01-09T10:13:55.481966Z",
      "updated_at": "2024-01-09T10:13:55.481966Z",
      "psp": "SEP"
    },
    {
      "uuid": "6e6a06f6-f93d-4c92-a1b4-d66edc8e168e",
      "payment": "6264b779-4795-4de5-b600-b007e4020839",
      "status": -1,
      "amount": 1,
      "toman_wage": 1,
      "tracker_id": null,
      "payment_reference_number": "22823714381",
      "payment_tracker_id": "564646450006456456",
      "payment_terminal_number": "1111111111111",
      "payment_masked_paid_card_number": "603799******5249",
      "created_at": "2024-01-09T08:46:49.342351Z",
      "updated_at": "2024-01-09T08:46:49.342351Z",
      "psp": "SEP"
    },
    {
      "uuid": "79d9cd3f-10f3-4535-a528-b24e2a9295d1",
      "payment": "6264b779-4795-4de5-b600-b007e4020839",
      "status": 3,
      "amount": 2345,
      "toman_wage": 1,
      "tracker_id": null,
      "payment_reference_number": "22823714381",
      "payment_tracker_id": "564646450006456456",
      "payment_terminal_number": "1111111111111",
      "payment_masked_paid_card_number": "603799******5249",
      "created_at": "2024-01-08T13:52:13.900449Z",
      "updated_at": "2024-01-08T13:52:13.900449Z",
      "psp": "SEP"
    },
    {
      "uuid": "eab02294-ff1b-4078-914a-600be4c51503",
      "payment": "6264b779-4795-4de5-b600-b007e4020839",
      "status": 3,
      "amount": 10000,
      "toman_wage": 1,
      "tracker_id": null,
      "payment_reference_number": "22823714381",
      "payment_tracker_id": "564646450006456456",
      "payment_terminal_number": "1111111111111",
      "payment_masked_paid_card_number": "603799******5249",
      "created_at": "2024-01-08T13:51:51.138635Z",
      "updated_at": "2024-01-08T13:51:51.138635Z",
      "psp": "SEP"
    },
    {
      "uuid": "1286ba6a-c751-4d20-ab3d-cacdf7dd01d5",
      "payment": "6264b779-4795-4de5-b600-b007e4020839",
      "status": 3,
      "amount": 10000,
      "toman_wage": 1,
      "tracker_id": null,
      "payment_reference_number": "22823714381",
      "payment_tracker_id": "564646450006456456",
      "payment_terminal_number": "1111111111111",
      "payment_masked_paid_card_number": "603799******5249",
      "created_at": "2024-01-08T13:43:18.639646Z",
      "updated_at": "2024-01-08T13:43:18.639646Z",
      "psp": "SEP"
    },
    {
      "uuid": "0febef1f-59ca-4b80-8d8a-694183be67e4",
      "payment": "6264b779-4795-4de5-b600-b007e4020839",
      "status": 3,
      "amount": 10000,
      "toman_wage": 1,
      "tracker_id": null,
      "payment_reference_number": "22823714381",
      "payment_tracker_id": "564646450006456456",
      "payment_terminal_number": "1111111111111",
      "payment_masked_paid_card_number": "603799******5249",
      "created_at": "2024-01-08T13:04:10.509003Z",
      "updated_at": "2024-01-08T13:04:10.509003Z",
      "psp": "SEP"
    }
  ]
}

Refunds list

The Refund List API provides functionality to retrieve a list of partner refunds in a specified format, along with the ability to apply filters.

import requests

url = f"{base_url}/refunds"

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

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

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

`GET /refunds`

Scope

ipg.refund.read

Request Body

Without any request body.

Response Body

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

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

Detail of refunds inside list API

Each item inside of results key is:

Parameter	Type	Description	Example
uuid	String	A UUID 4 string which uniquely identifies the refund. This field is generated by Toman when the partner wants to create a new refund	"dce5aef0-118c-4c5c-9e0e-7726a1c4d743"
payment	String	The payment uuid that refund created based on that payment and remain amount	"3455234b-b96e-4734-95bb-8936a2f06f4c"
status	Integer	Status of the refund. See Refund Status	1
amount	Integer	The amount (in IRR) to refund	100000
toman_wage	Integer	Toman wage amount that partner should pay for request and processing that refund	120
tracker_id	String (Nullable)	The unique tracker id generated by the partner for tracking specific refund in Toman system	"112233445566"
payment_reference_number	String	The related reference number on payment	"21458790785"
payment_tracker_id	String (Nnullable)	The related tracker id on payment	"21458790785"
payment_terminal_number	String	The related terminal number on payment	"14115046"
payment_masked_paid_card_number	String	The related masked paid card number on payment	"603799******5249"
psp	String	The chosen PSP to handle this payment. `SEP`.	"SEP"
created_at	String (ISO-8601 Date)	The exact time of the creation of this refund	"2023-10-01T12:12:12.772196Z"
updated_at	String (ISO-8601 Date)	The exact time of the update of this refund	"2023-10-01T12:12:12.772196Z"

Response Data Example

{
  "count": 5,
  "next": null,
  "previous": null,
  "results": [
    {
      "uuid": "dce5aef0-118c-4c5c-9e0e-7726a1c4d743",
      "payment": "3455234b-b96e-4734-95bb-8936a2f06f4c",
      "status": 0,
      "amount": 10000,
      "toman_wage": 120,
      "tracker_id": "112233445566",
      "payment_reference_number": "1321321321312",
      "payment_tracker_id": "1321321321312",
      "payment_terminal_number": "1321321321312",
      "payment_masked_paid_card_number": "603799******5249",
      "psp": "SEP",
      "created_at": "2023-10-01T12:12:12.772196Z",
      "updated_at": "2023-10-01T12:12:12.772196Z"
    },
    {
      "uuid": "81694dcf-69dd-40d6-9389-ab4907946eeb",
      "payment": "3455234b-b96e-4734-95bb-8936a2f06f4c",
      "status": 1,
      "amount": 8000,
      "toman_wage": 120,
      "tracker_id": "112233445565",
      "payment_reference_number": "1321321321312",
      "payment_tracker_id": "1321321321312",
      "payment_terminal_number": "1321321321312",
      "payment_masked_paid_card_number": "603799******5249",
      "psp": "SEP",
      "created_at": "2023-10-01T12:12:12.772196Z",
      "updated_at": "2023-10-01T12:12:12.772196Z"
    },
    {
      "uuid": "0fc51c4e-9dc9-4f6e-b681-159de8471a98",
      "payment": "3455234b-b96e-4734-95bb-8936a2f06f4c",
      "status": 2,
      "amount": 7000,
      "toman_wage": 120,
      "tracker_id": "112233445564",
      "payment_reference_number": "1321321321312",
      "payment_tracker_id": "1321321321312",
      "payment_terminal_number": "1321321321312",
      "payment_masked_paid_card_number": "603799******5249",
      "psp": "SEP",
      "created_at": "2023-10-01T12:12:12.772196Z",
      "updated_at": "2023-10-01T12:12:12.772196Z"
    },
    {
      "uuid": "1dbaf80f-0770-4328-a23b-d984093a1515",
      "payment": "3455234b-b96e-4734-95bb-8936a2f06f4c",
      "status": 3,
      "amount": 6000,
      "toman_wage": 120,
      "tracker_id": "112233445563",
      "payment_reference_number": "1321321321312",
      "payment_tracker_id": "1321321321312",
      "payment_terminal_number": "1321321321312",
      "payment_masked_paid_card_number": "603799******5249",
      "psp": "SEP",
      "created_at": "2023-10-01T12:12:12.772196Z",
      "updated_at": "2023-10-01T12:12:12.772196Z"
    },
    {
      "uuid": "770bee8f-23d5-4e0f-baee-590c5cbf96da",
      "payment": "3455234b-b96e-4734-95bb-8936a2f06f4c",
      "status": -1,
      "amount": 5000,
      "toman_wage": 120,
      "tracker_id": "112233445562",
      "payment_reference_number": "1321321321312",
      "payment_tracker_id": "1321321321312",
      "payment_terminal_number": "1321321321312",
      "payment_masked_paid_card_number": "603799******5249",
      "psp": "SEP",
      "created_at": "2023-10-01T12:12:12.772196Z",
      "updated_at": "2023-10-01T12:12:12.772196Z"
    }
  ]
}

Refund list with Filters

import requests

url = f"{base_url}/refunds"

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

params = {
    "status__in": "1,2,3",  # Replace with desired status values
    "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
    "terminal_numbers": "123456,654321"  # Replace with desired terminal numbers
}

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

curl --location "$BASE_URL/refunds?status__in=1&created_at_after=2023-09-03T21%3A45%3A24.000Z&terminal_numbers=123456,654321" \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'

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

Filtering by Status

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

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

Filtering by Creation Date

You can filter refunds 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 /refunds?created_at_after=2023-09-03T21%3A45%3A24.000Z&created_at_before=2023-09-03T21%3A30%3A33.000Z

Filtering by Terminal Number

You can filter refunds based on their terminal number using the terminal_numbers parameter. This parameter accepts a comma-separated list of terminal numbers.

Example: GET /refunds?terminal_numbers=30037210,30037211,30037212

Search on Refunds

You can search on refunds based on the following fields:

uuid
payment_reference_number
payment_tracker_id
payment_terminal

For searching on refunds, use the search parameter to search among to refunds fields. It filters all refunds that include given value on above fields

Example: GET /refunds?search=6542315

Refund detail

Retrieve details of a refund.

import requests

url = f"{base_url}/refunds/{refund_uuid}"

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

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

curl "$BASE_URL/refunds/$REFUND_UUID" \
--header "Authorization: Bearer $TOKEN"

`GET /refunds/<uuid>`

Scope

ipg.refund.read

Path Parameters

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

Request Body

Without any request body.

Response Body

Parameter	Type	Description	Example of Data
psp	String	Name of the PSP	"SEP"
uuid	String	UUID 4 Unique identifier for the refund	"123e4567-e89b-12d3-a456-426614174001"
payment	String	UUID 4 of associated payment	"123e4567-e89b-12d3-a456-426614174002"
status	Integer	Status of the refund	1
amount	Integer	Amount of the refund	100.00
toman_wage	Integer (Nullable)	Toman wage associated with the refund	50.00
payment_amount	Integer	Amount of the payment	75.00
tracker_id	String (Nullable)	Tracker ID for the refund	"987654321"
payment_reference_number	String	Reference number for the associated payment	"PAY-1234567890"
payment_tracker_id	String (Nullable)	Tracker ID for the associated payment	"9876543210"
payment_terminal_number	String	Terminal number for the associated payment	"TERM-001"
payment_terminal_acceptor_code	String	Acceptor code for the associated payment terminal	"ACCEPTOR-12345"
payment_masked_paid_card_number	String	Masked paid card number for the associated payment	"603799******1234"
withdraw_bank_id	String	Bank ID for the withdrawal	"BANK-7890"
withdraw_uuid	String	UUID of the associated withdrawal	"123e4567-e89b-12d3-a456-426614174003"
created_at	String DateTime ISO 8601	Date and time of creation refund	"2023-12-27T12:00:00Z"
updated_at	String DateTime ISO 8601	Date and time of update refund	"2023-12-27T12:00:00Z"
success_at	String DateTime ISO 8601	Date and time of successful refund completion	"2023-12-28T10:30:00Z"
related_payment	Array [payments]	Method to retrieve related payments	[{"uuid": "123e4567-e89b-12d3-a456-426614174004", ...}, {"uuid": "123e4567-e89b-12x3-a456-426614174004", ...}]
error_detail	String (Nullable) errors	Details of any error associated with refund	"Invalid request"

Response Data Example

{
  "psp": "SEP",
  "uuid": "51437acb-353a-4c6d-b432-6b264510d274",
  "payment": "e2870f8c-3f5b-41f2-b12c-51c1984f110f",
  "status": 2,
  "amount": 10000,
  "toman_wage": 0,
  "payment_amount": 12345,
  "tracker_id": null,
  "payment_reference_number": "22777111668",
  "payment_tracker_id": "c3239d89-798d-4cbc-b59d-1b4eaf83f074",
  "payment_terminal_number": "13739092",
  "payment_terminal_acceptor_code": "14874005",
  "payment_masked_paid_card_number": "603799******1111",
  "withdraw_bank_id": null,
  "withdraw_uuid": "0992d0cb-d264-4fcb-803f-898f8ea7941b",
  "created_at": "2023-11-28T14:51:45.579992Z",
  "updated_at": "2023-11-28T14:51:45.579992Z",
  "success_at": null,
  "related_payment": {
    "amount": 12345,
    "psp": "SEP",
    "status": 5,
    "is_refunded": false,
    "uuid": "e2870f8a-3f5b-41f2-b12c-51c1984f110f",
    "terminal_number": "13739092",
    "created_at": "2023-11-28T14:50:52.259751Z"
  },
  "error_detail": null
}

Errors

Code	Description
refund_not_found	Cannot find the refund

Error Details Table

Message	Explain
Card number not found	Couldn't found payment's card number.
Multiple iban found	Found multiple Ibans for the card number.
An Unknown error occurred	An unexpected error occurred.
Bank not response	Provider's not response.
Card number is not support	Card number not supported.
Card is not active	Card is not active.
Account is not supported	Couldn't found related Iban's of the card, It may be a gift card.
Out of Credit	Not enough credit in your wallet.
Bank Operation Error	Due to a problem in the bank, the operation was not completed.
Shahab Not Exist	Customer Shahab code not exists
PAYA does not support	Paya system does not support the desired bank.

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.

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 structure

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