NAV
cURL Python

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

400_INVALID_GRANT

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

Reasons

401_INVALID_CLIENT

{
    "error"
:
    "invalid_client"
}

Reasons

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:

Notes:

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 does not respond currently.
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_beforeparameters. 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:

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:

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:

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.

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