Introduction
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.
Authentication
Toman uses OAuth 2.0 to authorize API requests. We will provide you with the required Username, Password, Client ID, and Client Secret required for the process of token acquirement.
Each endpoint in our project has none, one, or more scope requirements, which can be found in the endpoint documentation. Note that you have to had included the required scopes in your authentication process in order to be allowed to use them.
The authentication process URL for our staging and productions servers are:
Environment | Auth URL |
---|---|
Production | https://accounts.qbitpay.org/oauth2/token/ |
Staging | https://auth.qbitpay.org/oauth2/token/ |
The acquired token should be included among request headers with the prefix Bearer
:
Authorization: Bearer 5OGgq1FQS7jPITItICRwlDYZv5P91A
Get Access Token
To acquire your access token, you need to send your username
, password
, client_id
, and client_secret
to the auth
endpoint.
Request Data Example (Without Basic Authentication)
Sample Code (Without Basic Authentication)
import requests
auth_url = "https://auth.qbitpay.org/oauth2/token/"
username = "MY_USERNAME"
password = "MY_PASSWORD"
client_id = "MY_CLIENT_ID"
client_secret = "MY_CLIENT_SECRET"
response = requests.request(
"POST",
auth_url,
data={
"client_id": client_id,
"client_secret": client_secret,
"username": username,
"password": password,
"grant_type": "password",
"scope": "settlement.wallet.retrieve"
},
)
token = response.json()["access_token"]
refresh_token = response.json()["refresh_token"]
authorization_header = {
"Authorization": f"Bearer {token}"
}
endpoint_response = requests.request(
"GET",
"https://settlement-staging.qbitpay.org/wallets/deposits/summary/",
headers=authorization_header
)
print(endpoint_response.json())
curl -X POST -d "username=$USERNAME" \
-d "password=$PASSWORD" \
-d "client_id=$CLIENT_ID" \
-d "client_secret=$CLIENT_SECRET" \
-d "grant_type=password" \
-d "scope=settlement.wallet.retrieve" \
$AUTH_URL
curl -H "Authorization: Bearer $TOKEN" $API_ENDPOINT
POST /oauth2/token/ HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: auth.qbitpay.org
grant_type=password&
client_id=MY_CLIENT_ID&
client_secret=MY_CLIENT_SECRET&
username=MY_USERNAME&
password=MY_PASSWORD&
scope=settlement.single.submit%20settlement.single.verify
Request Data Example (Using Basic Authentication)
Sample Code (Using Basic Authentication)
import requests
auth_url = "https://auth.qbitpay.org/oauth2/token/"
username = "MY_USERNAME"
password = "MY_PASSWORD"
client_id = "MY_CLIENT_ID"
client_secret = "MY_CLIENT_SECRET"
response = requests.request(
"POST",
auth_url,
data={
"username": username,
"password": password,
"grant_type": "password",
"scope": "settlement.wallet.retrieve"
},
# this is how requests handles the basic http authentication
auth=(client_id, client_secret)
)
token = response.json()["access_token"]
refresh_token = response.json()["refresh_token"]
authorization_header = {
"Authorization": f"Bearer {token}"
}
endpoint_response = requests.request(
"GET",
"https://settlement-staging.qbitpay.org/wallets/deposits/summary/",
headers=authorization_header
)
print(endpoint_response.json())
curl -u $CLIENT_ID:$CLIENT_SECRET -X POST -d "username=$USERNAME" \
-d "password=$PASSWORD" \
-d "grant_type=password" \
-d "scope=settlement.wallet.retrieve" \
$AUTH_URL
curl -H "Authorization: Bearer $TOKEN" $API_ENDPOINT
POST /oauth2/token/ HTTP/1.1
Authorization: Basic TVlfQ0xJRU5UX0lEOk1ZX0NMSUVOVF9TRUNSRVRF
Content-Type: application/x-www-form-urlencoded
Host: auth.qbitpay.org
grant_type=password&
username=MY_USERNAME&
password=MY_PASSWORD&
scope=settlement.single.submit%20settlement.single.verify
Response Data Example
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token":"5OGgq1FQS7jPITItICRwlDYZv5P91A",
"expires_in":86400,
"token_type":"Bearer",
"scope":"settlement.single.submit settlement.single.verify",
"refresh_token":"upTFapSZfpJISYeo0YsZVjf8X29SBy"
}
Refresh Token
Since every access token has an expiration date (see expires_in
), you need to acquire a new
access token after it expires. The Oauth2 standard, is to
use refresh tokens.
To refresh your access token, you need to send your refresh_token
, client_id
, and client_secret
to the auth
endpoint with grant_type=refresh_token
. The expiration time of the refresh token itself is one week.
please notice in the response body of the refresh-token process, a new refresh token will be generated, so we suggest
replacing the newly generated refresh token with the old one, for future refresh requests.
Sample Code
response = requests.request(
"POST",
auth_url,
data={
"grant_type": "refresh_token",
"refresh_token": refresh_token,
"client_id": client_id,
"client_secret": client_secret,
}
)
access_token = response.json()["access_token"]
new_refresh_token = response.json()["refresh_token"]
curl -X POST -d "refresh_token=$REFRESH_TOKEN"\
-d "client_id=$CLIENT_ID" \
-d "client_secret=$CLIENT_SECRET" \
-d "grant_type=refresh_token" \
$AUTH_URL
Request Data Example
POST /oauth2/token/ HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: auth.qbitpay.org
grant_type=refresh_token&
refresh_token=upTFapSZfpJISYeo0YsZVjf8X29SBy&
client_id=MY_CLIENT_ID&
client_secret=MY_CLEINT_SECRET
Response Data Example
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token":"mAGJQqnhLBEZ5UMVAvHVNruOzAyZVs",
"expires_in":86400,
"token_type":"Bearer",
"scope":"settlement.single.submit settlement.single.verify",
"refresh_token":"BLVE2AleqqLHPBmGad4HAQEmqkPr4b"
}
Error Handling
In this section we will list some of the errors that you may encounter while trying to obtian or refresh your tokens.
400_INVALID_SCOPE
{"error": "invalid_scope"}
Reasons
- 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
orpassword
in your request incorrectly.
401_INVALID_CLIENT
{
"error"
:
"invalid_client"
}
Reasons
- The
client_id
specified in your request is not correct. - The
client_secret
specified in your request is not correct.
Models
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. |
Deposit Request
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" |
status | Integer | Status of the refund. See Deposit Status | 1 |
amount | Integer | The amount (in IRR) to refund | 100000 |
trace_number | String | The trace number of your deposit on bank side | "50002" |
created_at | String DateTime ISO 8601 | The exact time of the creation of this deposit | "2023-12-27T12:00:00Z |
deposit_datetime | String DateTime ISO 8601 | Date and time of bank deposit | "2023-12-27T12:00:00Z |
add_to_wallet_at | String DateTime ISO 8601 | Date and time of your deposit request apply on wallet | "2023-12-27T12:00:00Z |
Deposit Request Status
Status Number | Code Name | Description |
---|---|---|
1 | Created | created deposit request |
2 | SentToProvider | sent deposit request for check at bank |
3 | Accept | Your deposit request accepted |
4 | AddedToWallet | Your deposit request amount added to your wallet |
-1 | Reject | Your deposit request rejected by admin |
Wallet Transaction
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" |
amount | Integer | The amount (in IRR) of transaction | 100000 |
balance | Integer | The remain amount (in IRR) | 100000 |
type | Integer | The type of transaction Wallet Transaction Type | 1 |
Refund Wallet
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" |
balance | Integer | The remain amount (in IRR) | 100000 |
address | String | The unique wallet address in toman | "ipgrwecccedBcFcc8d22AC16E488Cc" |
Wallet Transaction Type
Status Number | Code Name | Description |
---|---|---|
1 | RefundRequest | withdraw transaction for refund |
2 | Deposit | deposit transaction that created by deposit request |
3 | Amendment | Amendment amount for a failed refund |
4 | AdminRequest | Admin request to increase/decrease wallet balance |
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
Sample Code
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 precise 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 (Optional 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"] |
default_card_number | String (Optional) | The default card number which will display in card number filed on payment page (PSP). This card number is also one of the card numbers which the user is limited to use. | "1234123443214321" |
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"
],
"default_card_number": "1234123443214321",
"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. |
psp_not_respond | PSP |
psp_get_token_rejected | Create payment was rejected by PSP. |
error | A server error occurred. |
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 |
Callback
Redirects the customer to the announced callback url on create payment step with a POST request containing the Payment object.
Verify Payment
Sample Code
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": "SEP",
"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
}
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 right status |
psp_verify_rejected | This payment was not success, and PSP rejected verification. |
psp_not_respond_correctly | PSP <psp_name> does not respond correctly. |
tampered_payment_data | Payment data was tampered by end user |
error | A server error occurred. |
Get Payment Details
Retrieve details of a payment.
Sample Code
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.
Sample Code
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 / Verification Date
You can filter payments based on their creation date using the created_at_after
and created_at_before
| verified_at_after
and verified_at_before
parameters.
These parameters accept datetime values in ISO format.
Note: Maximum provided range could be 1 day. Otherwise, you will receive Error.
using created_at_after
or created_at_before
(also verified_at_after
or veridied_at_before
) alone will filter payments until 1 day.
Example:
GET /payments?created_at_after=2023-09-03T21%3A45%3A24.000Z&created_at_before=2023-09-04T21%3A30%3A33.000Z
GET /payments?verified_at_after=2023-09-03T21%3A45%3A24.000Z&verified_at_before=2023-09-04T21%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, creation date and verification 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).
Sample Code
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.
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.
Sample Code
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": "SEP",
"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"
}
Errors
Code | Description |
---|---|
http_404_not_found | Not found |
status_change_not_allowed | Cannot change the status of payment from <from_status> to reverted |
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. |
psp_not_respond_correctly | PSP <psp_name> does not respond correctly. |
error | A server error occurred. |
Terminal list
You can use this API to retrieve terminal list in the format of given sample data and also filter set.
Sample Code
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. | "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 |
recent_payments_count | Integer | Count of payments which verified yesterday. | 20 |
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,
"recent_payments_count": 20
},
{
"uuid": "924ea30d-3a4654650d-a314-949697ce7c07",
"psp": "SADAD",
"terminal_number": "9654654",
"acceptor_code": 13165456,
"iban": "IR546500000000000654012067000",
"enabled": true,
"recent_payments_count": 100
},
{
"uuid": "924ea30d-3aa3-4e0d-a314-7987465416541",
"psp": "SEP",
"terminal_number": "6546546546",
"acceptor_code": 1654646,
"iban": "IR23000000000000000564654100121",
"enabled": true,
"recent_payments_count": 120
},
{
"uuid": "924ea30d-89987-a314-949697ce7c07",
"psp": "SADAD",
"terminal_number": "5646546",
"acceptor_code": 546546465,
"iban": "IR89000000000000000005246546546",
"enabled": false,
"recent_payments_count": 0
}
]
}
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
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.
Sample Code
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 (Optional) | 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 (Optional) | 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. |
not_enough_balance | Not enough balance in your wallet |
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.
Sample Code
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's refunds in a specified format, along with the ability to apply filters.
Sample Code
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.
Sample Code
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" |
withdraw_receipt_link | String (Nullable) | The public URL of the refund which you can give to your customers. | "https://settlement.toman.ir/receipt/settlement/6b15ae8c-ebc1-456d-8889-843654240600:Av34rD87a3dr326123asdfuwersdfvawBGEsJKLGaweLKJG" |
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",
"withdraw_receipt_link": "https://settlement.toman.ir/receipt/settlement/6b15ae8c-ebc1-456d-8889-843654240600:Av34rD87a3dr326123asdfuwersdfvawBGEsJKLGaweLKJG"
"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. |
Retry Refund
To reactivate a refund transactions which are Denied or Failed and is eligible for retry.
- You can retry processing the eligible refund with a Failed status after the agreed-upon reconciliation period.
Sample Code
import requests
url = f"{base_url}/refunds/{refund_uuid}/retry"
headers = {
"Authorization": f"Bearer {token}"
}
response = requests.request("POST", url, headers=headers)
curl --request POST "$BASE_URL/refunds/$REFUND_UUID/retry" \
--header "Authorization: Bearer $TOKEN"
POST /refunds/<uuid>/retry
Scope
ipg.refund.retry
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" |
withdraw_receipt_link | String (Nullable) | The public URL of the refund which you can give to your customers. | "https://settlement.toman.ir/receipt/settlement/6b15ae8c-ebc1-456d-8889-843654240600:Av34rD87a3dr326123asdfuwersdfvawBGEsJKLGaweLKJG" |
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",
"withdraw_receipt_link": "https://settlement.toman.ir/receipt/settlement/6b15ae8c-ebc1-456d-8889-843654240600:Av34rD87a3dr326123asdfuwersdfvawBGEsJKLGaweLKJG"
"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 |
not_enough_balance | Not enough balance in your wallet |
cannot_retry_refund_invalid_status | Status of this refund is invalid for retry. |
cannot_retry_resource_not_found | Cannot get iban or card number for this refund. |
not_time_to_retry_this_refund | Cannot retry failed refund before expected hours |
Deposit Request
This is a request to register an increase amount in the balance of the refund wallet, which will be finalized after the approval of the Toman Admin.
Sample Code
POST /wallet/refund/deposit-requests
Scope
ipg.wallet.deposit.create
import requests
url = f"{base_url}/wallet/refund/deposit-requests"
headers = {
'Authorization': 'Bearer thisistoken}'
}
payload = {
'amount': 12345,
'trace_number': 'str',
'deposit_datetime': '2023-12-27T12:00:00Z'
}
response = requests.request("POST", url, headers=headers)
curl -X 'POST' \
'{base_url}/wallet/refund/deposit-requests' \
-H 'accept: application/json' \
-H 'Authorization: Bearer Hp3FPtstHvoKczqK3Ts4Pp6D2HPBLS' \
-H 'Content-Type: application/json' \
-d '{
"amount": 12345,
"trace_number": "string"
"deposit_datetime": "2023-12-27T12:00:00Z"
}'
Request Body
Parameter | Type | Description | Example |
---|---|---|---|
amount | Integer | The amount (in IRR) you deposit in to bank | 10000 |
trace_number | String | Trace number that bank give it to you | "12ab@#" |
deposit_datetime | String DateTime ISO 8601 | Date and time of bank deposit | "2023-12-27T12:00:00Z" |
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" |
amount | Integer | The amount (in IRR) to refund | 100000 |
trace_number | String | Trace number that bank give it to you | "112233445566" |
deposit_datetime | String DateTime ISO 8601 | Date and time of bank deposit | "2023-12-27T12:00:00Z |
Deposit list
Return your all deposit requests
You can use the GET /wallet/refund/deposit-requests
endpoint to retrieve a list of deposits.
Scope
ipg.wallet.deposit.read
Sample code
import requests
url = f"{base_url}/wallet/refund/deposit-requests"
headers = {
'Authorization': f'Bearer {token}}'
}
response = requests.request("GET", url, headers=headers)
curl --location "$BASE_URL/wallet/refund/deposit-requests" \
--header "Authorization: Bearer $TOKEN"
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[deposit request inside of list] | The array containing the refunds of this page that follows the schema of pagination |
Detail of deposit request 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" |
amount | Integer | The amount (in IRR) tell for deposit | 100000 |
status | Integer | Status of the refund. See Deposit Status | 1 |
trace_number | String | Trace number that bank give it to you | "112233445566" |
deposit_datetime | String DateTime ISO 8601 | Date and time of bank deposit | "2023-12-27T12:00:00Z |
add_to_wallet_at | String DateTime ISO 8601 | Date and time of your deposit request apply on wallet | "2023-12-27T12:00:00Z |
Response Data Example
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"amount": 0,
"trace_number": "string",
"status": -2,
"deposit_datetime": "2023-12-27T12:00:00Z",
"add_to_wallet_at": "2023-12-27T12:00:00Z"
}
]
}
Filtering by Creation Date
You can filter deposit requests 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 /wallet/refund/deposit-requests?created_at_after=2023-09-03T21%3A45%3A24.000Z&created_at_before=2023-09-03T21%3A30%3A33.000Z
Filtering by Status
You can filter deposit requests based on their Deposit Status, using the status
or status__in
parameters.
These parameters accept the DepositRequest statuses.
Example:
GET /wallet/refund/deposit-requests?status=2
GET /wallet/refund/deposit-requests?status__in=2,2
Deposit request detail
Retrieve a single deposit request detail
Sample Code
import requests
url = f"{base_url}/wallet/refund/deposit-requests/{deposit_request_uuid}"
headers = {
"Authorization": f"Bearer {token}"
}
response = requests.request("GET", url, headers=headers)
curl "$BASE_URL/wallet/refund/deposit-requests/$DEPOSIT_request_UUID" \
--header "Authorization: Bearer $TOKEN"
GET /wallet/refund/deposit-requests/<uuid>
Scope
ipg.wallet.deposit.read
Path Parameters
Parameter | Type | Description | Example |
---|---|---|---|
UUID | String | The uuid field of the deposit request | "49ca936f-9ca0-4f0b-9a9d-f87b6da65642" |
Request Body
Without any request body.
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" |
amount | Integer | The amount (in IRR) tell for deposit | 100000 |
status | Integer | Status of the refund. See Deposit Status | 1 |
trace_number | String | Trace number that bank give it to you | "112233445566" |
deposit_datetime | String DateTime ISO 8601 | Date and time of bank deposit | "2023-12-27T12:00:00Z |
add_to_wallet_at | String DateTime ISO 8601 | Date and time of your deposit request apply on wallet | "2023-12-27T12:00:00Z |
Response Data Example
{
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"amount": 0,
"trace_number": "string",
"status": -2,
"deposit_datetime": "2023-12-27T12:00:00Z",
"add_to_wallet_at": "2023-12-27T12:00:00Z"
}
Wallet transaction list
You can use the GET /wallet/refund/transactions
endpoint to retrieve a list of wallet transaction.
Sample code
import requests
url = f"{base_url}/wallet/refund/transactions"
headers = {
'Authorization': 'Bearer thisistoken}'
}
response = requests.request("GET", url, headers=headers)
curl --location "$BASE_URL/wallet/refund/transactions" \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'
GET /wallet/refund/transactions
Scope
ipg.wallet.transaction.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[wallet transaction inside of list] | The array containing the wallet transaction of this page that follows the schema of pagination |
Detail of wallet transaction inside list API
Each item inside of results
key is:
Parameter | Type | 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" |
amount | Integer | The amount (in IRR) deposit or | 100000 |
balance | Integer | The remain amount (in IRR) of your wallet | 100000 |
commission | Integer | The commission (in IRR) of this transaction | 100000 |
type | Integer | See Wallet Transaction Type | 1 |
Response Data Example
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"amount": 9223372036854776000,
"balance": 9223372036854776000,
"commission": 2147483647,
"type": 1
}
]
}
Filtering by Creation Date
You can filter deposit requests 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 /wallet/refund/transaction?created_at_after=2023-09-03T21%3A45%3A24.000Z&created_at_before=2023-09-03T21%3A30%3A33.000Z
Filtering by Status
You can filter wallet transaction based on their Wallet Transaction Type, using the type
or type__in
parameters.
These parameters accept the Transaction type.
Example:
GET /wallet/refund/transaction?type=2
GET /wallet/refund/transaction?type__in=2,3
Get Refund Wallet Data
You can use the GET /wallet/refund
endpoint to retrieve the refund wallet object.
Sample code
import requests
url = f"{base_url}/wallet/refund"
headers = {
'Authorization': 'Bearer thisistoken}'
}
response = requests.request("GET", url, headers=headers)
curl --location "$BASE_URL/wallet/refund" \
--header 'Authorization: Bearer oiHUHxVbyvgJVRtXiXkUnFkmB2i02V'
GET /wallet/refund
Scope
ipg.wallet.read
Request Body
Without any request body.
Response Body
Parameter | Type | Description | Example |
---|---|---|---|
balance | Integer | The remain amount (in IRR) | 100000 |
address | String | The unique wallet address in toman | "ipgrwecccedBcFcc8d22AC16E488Cc" |
Response Data Example
{
"balance": 123,
"address": "ipgrwecccedBcFcc8d22AC16E488Cc"
}
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
This is the typical structure of an error in Toman
{
"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." |