Introduction

This is Toman's PSP Reporting API Reference.

Authentication

Toman uses OAuth 2.0 to authorize API requests. We will provide you with the required Username, Password, Client ID, and Client Secret required for the process of token acquirement.

Each endpoint in our project has none, one, or more scope requirements, which can be found in the endpoint documentation. Note that you have to had included the required scopes in your authentication process in order to be allowed to use them.

The authentication process URL for our staging and productions servers are:

Environment	Auth URL
Production	`https://accounts.qbitpay.org/oauth2/token/`
Staging	`https://auth.qbitpay.org/oauth2/token/`

The acquired token should be included among request headers with the prefix Bearer:

Authorization: Bearer 5OGgq1FQS7jPITItICRwlDYZv5P91A

Get Access Token

To acquire your access token, you need to send your username, password, client_id, and client_secret to the auth endpoint.

Request Data Example (Without Basic Authentication)

import requests

auth_url = "https://auth.qbitpay.org/oauth2/token/"
username = "MY_USERNAME"
password = "MY_PASSWORD"
client_id = "MY_CLIENT_ID"
client_secret = "MY_CLIENT_SECRET"

response = requests.request(
    "POST",
    auth_url,
    data={
        "client_id": client_id,
        "client_secret": client_secret,
        "username": username,
        "password": password,
        "grant_type": "password",
        "scope": "settlement.wallet.retrieve"
    },
)
token = response.json()["access_token"]
refresh_token = response.json()["refresh_token"]

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

endpoint_response = requests.request(
    "GET",
    "https://settlement-staging.qbitpay.org/wallets/deposits/summary/",
    headers=authorization_header
)

print(endpoint_response.json())

curl -X POST -d "username=$USERNAME" \
             -d "password=$PASSWORD" \
             -d "client_id=$CLIENT_ID" \
             -d "client_secret=$CLIENT_SECRET" \
             -d "grant_type=password" \
             -d "scope=settlement.wallet.retrieve" \
             $AUTH_URL

curl -H "Authorization: Bearer $TOKEN" $API_ENDPOINT

POST /oauth2/token/ HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: auth.qbitpay.org

grant_type=password&
client_id=MY_CLIENT_ID&
client_secret=MY_CLIENT_SECRET&
username=MY_USERNAME&
password=MY_PASSWORD&
scope=settlement.single.submit%20settlement.single.verify

Request Data Example (Using Basic Authentication)

import requests

auth_url = "https://auth.qbitpay.org/oauth2/token/"
username = "MY_USERNAME"
password = "MY_PASSWORD"
client_id = "MY_CLIENT_ID"
client_secret = "MY_CLIENT_SECRET"

response = requests.request(
    "POST",
    auth_url,
    data={
        "username": username,
        "password": password,
        "grant_type": "password",
        "scope": "settlement.wallet.retrieve"
    },
    # this is how requests handles the basic http authentication
    auth=(client_id, client_secret)
)
token = response.json()["access_token"]
refresh_token = response.json()["refresh_token"]

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

endpoint_response = requests.request(
    "GET",
    "https://settlement-staging.qbitpay.org/wallets/deposits/summary/",
    headers=authorization_header
)

print(endpoint_response.json())

curl -u $CLIENT_ID:$CLIENT_SECRET -X POST -d "username=$USERNAME" \
                                          -d "password=$PASSWORD" \
                                          -d "grant_type=password" \
                                          -d "scope=settlement.wallet.retrieve" \
                                          $AUTH_URL

curl -H "Authorization: Bearer $TOKEN" $API_ENDPOINT

POST /oauth2/token/ HTTP/1.1
Authorization: Basic TVlfQ0xJRU5UX0lEOk1ZX0NMSUVOVF9TRUNSRVRF
Content-Type: application/x-www-form-urlencoded
Host: auth.qbitpay.org

grant_type=password&
username=MY_USERNAME&
password=MY_PASSWORD&
scope=settlement.single.submit%20settlement.single.verify

Response Data Example

HTTP/1.1 200 OK
Content-Type: application/json

{
"access_token":"5OGgq1FQS7jPITItICRwlDYZv5P91A",
"expires_in":86400,
"token_type":"Bearer",
"scope":"settlement.single.submit settlement.single.verify",
"refresh_token":"upTFapSZfpJISYeo0YsZVjf8X29SBy"
}

The Content-Type of get token request should be application/x-www-form-urlencoded.
`Content-Type: application/x-www-form-urlencoded`

You can obtain a single token and use it for multiple endpoints by specifying different scopes separated by whitespace. For instance: > scope=settlement.single.submit payment.create.

Refresh Token

Since every access token has an expiration date (see expires_in), you need to acquire a new access token after it expires. The Oauth2 standard, is to use refresh tokens.

To refresh your access token, you need to send your refresh_token, client_id, and client_secret to the auth endpoint with grant_type=refresh_token. The expiration time of the refresh token itself is one week. please notice in the response body of the refresh-token process, a new refresh token will be generated, so we suggest replacing the newly generated refresh token with the old one, for future refresh requests.

response = requests.request(
    "POST",
    auth_url,
    data={
        "grant_type": "refresh_token",
        "refresh_token": refresh_token,
        "client_id": client_id,
        "client_secret": client_secret,
    }
)
access_token = response.json()["access_token"]
new_refresh_token = response.json()["refresh_token"]

curl -X POST -d "refresh_token=$REFRESH_TOKEN"\
             -d "client_id=$CLIENT_ID" \
             -d "client_secret=$CLIENT_SECRET" \
             -d "grant_type=refresh_token" \
             $AUTH_URL

Request Data Example

POST /oauth2/token/ HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: auth.qbitpay.org

grant_type=refresh_token&
refresh_token=upTFapSZfpJISYeo0YsZVjf8X29SBy&
client_id=MY_CLIENT_ID&
client_secret=MY_CLEINT_SECRET

Response Data Example

HTTP/1.1 200 OK
Content-Type: application/json

{
"access_token":"mAGJQqnhLBEZ5UMVAvHVNruOzAyZVs",
"expires_in":86400,
"token_type":"Bearer",
"scope":"settlement.single.submit settlement.single.verify",
"refresh_token":"BLVE2AleqqLHPBmGad4HAQEmqkPr4b"
}

Error Handling

In this section we will list some of the errors that you may encounter while trying to obtian or refresh your tokens.

400_INVALID_SCOPE

{"error": "invalid_scope"}

Reasons

You're acquiring a token with a scope that is not defined. (e.g. wrong scope name)
One or more of the scopes in your request is unavailable for your user.

400_INVALID_GRANT

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

Reasons

You have specified the username or password in your request 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.

Endpoints

Base URLs

The base URLs for our staging and productions API servers are

Environment	URL
Production	`https://repigma.toman.ir`
Staging	`https://repigma-staging.qcluster.org`

Create Terminal

You can use this API to create terminal

import json

import requests

url = f"{base_url}/terminals/"

payload = json.dumps(
    {
        "terminal_type": 1,
        "psp_account_uuid":"a798ad80-b8ff-000-9372-007ed6422163",
        "terminal_number": "4245444",
        "acceptor_code": 213,
        "enabled": true,
        "description": "null",
        "start_fetch_time": "2024-11-24T01:53:22.609789Z"
    }
)
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}

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

curl --location '$BASE_URL/terminals/' \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
--data '{
            "terminal_type": 1,
            "psp_account_uuid":"a798ad80-b8ff-000-9372-007ed6422163",
            "terminal_number": "4245444",
            "acceptor_code": 213,
            "enabled": true,
            "description": "null",
            "start_fetch_time": "2024-11-24T01:53:22.609789Z"
        }'

Request	Scope
`POST /terminals`	`repigma.terminal.create`

Request Body

Parameter	Type	Description	Example
terminal_type	Integer	This parameter specifies the terminal type, which can be either POS (Point of Sale) or IPG (Internet Payment Gateway). Type	1
psp_account_uuid	String	This parameter represents the unique identifier (UUID) for the PSP account	"a798ad80-kkff-0000-9372-007ed6422163"
terminal_number	String	This parameter represents the terminal number, which is a unique identifier assigned to each terminal.	"4221244"
acceptor_code	Integer	This parameter defines the acceptor code, a unique identifier for the merchant or service provider accepting the transaction.	213
enabled	Boolean	This parameter indicates whether the feature or functionality is enabled.	true
description	String	This parameter provides a brief description or additional details about the item or entity.	null
start_fetch_time	String DateTime ISO 8601	This parameter specifies the start time for fetching data.	"2024-11-24T01:53:22.609789Z"

Terminal Type

Type	Code
IPG	0
POS	1

Response Body

Parameter	Type	Description	Example
uuid	String	The unique identifier for terminal	"3fa85f64-0000-4562-b3fc-2c963f66afa6"
terminal_type	Integer	This parameter specifies the terminal type, which can be either POS (Point of Sale) or IPG (Internet Payment Gateway). Type	1
psp_account_uuid	String	This parameter represents the unique identifier (UUID) for the PSP account.	"a798ad80-kkff-0000-9372-007ed6422163"
psp	String	The name of the `PSP` that terminal connected for process requests.	"SEP"
terminal_number	String	This parameter represents the terminal number, which is a unique identifier assigned to each terminal.	"4221244"
acceptor_code	Integer	This parameter defines the acceptor code, a unique identifier for the merchant or service provider accepting the transaction.	213
enabled	Boolean	This parameter indicates whether the feature or functionality is enabled.	true
description	String	This parameter provides a brief description or additional details about the item or entity.	null
created_at	String DateTime ISO 8601	This parameter indicates the date and time when the entity was created	"2024-11-24T01:53:22.609789Z"
start_fetch_time	String DateTime ISO 8601	This parameter specifies the start time for fetching data.	"2024-11-24T01:53:22.609789Z"

Request Data Example

{
  "terminal_type": 1,
  "psp_account_uuid":"a798ad80-0000-418c-9372-007ed6422163",
  "terminal_number": "4221344",
  "acceptor_code": 213,
  "enabled": true,
  "description": "null",
  "start_fetch_time": "2024-11-24T01:53:22.609789Z"
}

Response Data Example

{
  "uuid": "3fa85f64-5717-0000-b3fc-2c963f66afa6",
  "terminal_type": 1,
  "psp_account_uuid": "3fa85f64-5717-0000-b3fc-2c963f66afa6",
  "psp": "TOP",
  "terminal_number": "4259344",
  "acceptor_code": 131,
  "enabled": true,
  "description": null,
  "created_at": "2024-12-16T10:09:36.110Z",
  "start_fetch_time": "2024-12-16T10:09:36.110Z"
}

Get Terminal's List by UUID

You can use this API to get list of terminals

import requests

url = f"{base_url}/terminals/{terminal_uuid}"

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

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

curl --location -g --request GET "$BASE_URL/terminals/$TERMINAL_UUID" \
--header "Authorization: Bearer $TOKEN"

Request	Scope
`POST /terminals/<uuid>`	`repigma.terminal.read`

Request Body

Without any request body.

Response Body

Parameter	Type	Description	Example
uuid	String	The unique identifier for terminal.	"3fa85f64-0000-4562-b3fc-2c963f66afa6"
terminal_type	Integer	This parameter specifies the terminal type, which can be either POS (Point of Sale) or IPG (Internet Payment Gateway). Type	1
psp_account_uuid	String	This parameter represents the unique identifier (UUID) for the PSP account.	"a798ad80-kkff-0000-9372-007ed6422163"
psp	String	The name of the `PSP` that terminal connected for process requests.	"SEP"
terminal_number	String	This parameter represents the terminal number, which is a unique identifier assigned to each terminal.	"4221244"
acceptor_code	Integer	This parameter defines the acceptor code, a unique identifier for the merchant or service provider accepting the transaction.	213
enabled	Boolean	This parameter indicates whether the feature or functionality is enabled.	true
description	String	This parameter provides a brief description or additional details about the item or entity.	null
created_at	String DateTime ISO 8601	This parameter indicates the date and time when the entity was created	"2024-11-24T01:53:22.609789Z"
start_fetch_time	String DateTime ISO 8601	This parameter specifies the start time for fetching data.	"2024-11-24T01:53:22.609789Z"

Response Data Example

{
  "uuid": "3fa85f64-5717-0000-b3fc-2c963f66afa6",
  "terminal_type": 1,
  "psp_account_uuid": "3fa85f64-5717-0000-b3fc-2c963f66afa6",
  "psp": "TOP",
  "terminal_number": "4259344",
  "acceptor_code": 131,
  "enabled": true,
  "description": null,
  "created_at": "2024-12-16T10:09:36.110Z",
  "start_fetch_time": "2024-12-16T10:09:36.110Z"
}

Pagination schema

All PSP Reporting 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://repigma-staging.qcluster.org/reports/?page=2"
previous	String (Nullable)	The URL of the next page containing items after this page's items	"https://repigma-staging.qcluster.org/reports/?page=4"
results	Array[Object]	The array containing the items of this page

Report

You can use this API to get report of terminals from PSP,exported in an Excel file format.

import requests

url = f"{base_url}/reports/"

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

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

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

Request	Scope
`GET /reports/`	`repigma.report.list`

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 reports across all pages	123
next	String (Nullable)	The URL of the next page containing items after this page's items	"https://repigma-staging.qcluster.org/reports/?page=2"
previous	String (Nullable)	The URL of the next page containing items after this page's items	"https://repigma-staging.qcluster.org/reports/?page=3"
results	Array[list_of_report]	The array containing the report of this page that follows the schema of pagination

Detail of report inside list API

Each item inside of results key is:

Parameter	Type	Description	Example
uuid	String	The unique identifier for terminal.	"3fa85f64-0000-4562-b3fc-2c963f66afa6"
status	Integer	This parameter specifies the status of the report, indicating the current state or condition. Status	1
report_type	Integer	This parameter defines the type of report to be generated.	0
storage_filename	String (Nullable)	This parameter specifies the name of the file used for storage, including its format or extension.	"test.xlsx"
start_datetime	String DateTime ISO 8601 (Nullable)	This parameter indicates the start date and time of the report generation process.	"2024-11-24T01:53:22.609789Z"
created_at	String DateTime ISO 8601	This parameter indicates the date and time when the entity was created.	"2024-11-24T01:53:22.609789Z"
end_datetime	String DateTime ISO 8601 (Nullable)	This parameter indicates the end date and time of the report generation process.	"2024-11-24T01:53:22.609789Z"

Report Status

Status	Code
initiate	0
in_progress	1
success	2
failed	3
expired	4

Response Data Example

{
  "count": 123,
  "next": "https://repigma-staging.qcluster.org/reports/?page=3",
  "previous": "https://repigma-staging.qcluster.org/reports/?page=1",
  "results": [
    {
      "uuid": "3fa85f64-0000-4562-b3fc-2c963f66afa6",
      "status": 2,
      "report_type": 0,
      "storage_filename": "Toman_1403-06-23 03:30:00:1403-09-27 03:30:00_rIFosb6o8r.xlsx",
      "start_datetime": "2024-12-17T07:35:07.981Z",
      "end_datetime": "2024-12-17T07:35:07.981Z",
      "created_at": "2024-12-17T07:35:07.981Z"
    }
  ]
}

Download Report

You can use this API to download report of terminals from PSP

import requests

url = f"{base_url}/reports/{report_uuid}/download"

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

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

curl --location -g --request GET "$BASE_URL/reports/$REPORT_UUID/download" \
--header "Authorization: Bearer $TOKEN"

Request	Scope
`POST /reports/<report_uuid>/download`	`repigma.report.download`

Request Body

Without any request body.

Response Body

The response body contains a URL that provides a direct download link for an Excel file. This file includes the requested data in a structured format, making it suitable for further analysis or processing.

The URL returned in the response can be used either programmatically (e.g., in an automated script) or manually by copying the link into a browser.

Response Data Example

{
    "url": "https://s3.qcluster.org/toman-repigma-reports-staging/Toman_1403-06-20%2003%3A30%3A00%3A1403-07-10%2003%3A30%3A00_0sci7cYKUd.xlsx?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=oiYai0le003ieyux00z3%2F20201023%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20241223T154605Z&X-Amz-Expires=172800&X-Amz-SignedHeaders=host&X-Amz-Signature=280b1192627e31d7edeb600005ecc34eced0000068e5e831d831949d8b92c984"
}

PSPs

You can use this API to get details of PSPs

import requests

url = f"{base_url}/psps"

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

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

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

Request	Scope
`GET /psps`	`repigma.psp.read`

Request Body

Without any request body.

Response Body

Parameter	Type	Description	Example
count	Integer	The total number of PSPs across all pages	123
next	String (Nullable)	The URL of the next page containing items after this page's items	"https://repigma-staging.qcluster.org/psps/?page=3"
previous	String (Nullable)	The URL of the next page containing items after this page's items	"https://repigma-staging.qcluster.org/psps/?page=2"
results	Array[detail_of_psps]	The array containing the PSPs detail's of this page that follows the schema of pagination

Detail of PSPs inside list API

Each item inside of results key is:

Parameter	Type	Description	Example
id	Integer	unique identifier (ID) assigned to the record for reference and retrieval purposes.	2
name	String	The name of PSPs.	"TOP"
enabled	Boolean	This parameter indicates whether the feature or functionality is enabled.	true

Response Data Example

{
  "count": 123,
  "next": "https://repigma-staging.qcluster.org/psps/?page=4",
  "previous": "https://repigma-staging.qcluster.org/psps/?page=2",
  "results": [
    {
      "id": 0,
      "name": "SEP",
      "enabled": true
    }
  ]
}

Filter By ID

You can filter by ID using the endpoint GET /psps/{id} to retrieve the specific details associated with that PSP.

Response Data Example For PSPs By ID

{
  "id": 0,
  "name": "SEP",
  "enabled": true
}

PSPs Accounts

You can use this API to get psp's accounts

import requests

url = f"{base_url}/psp-accounts"

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

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

curl --location -g --request GET "$BASE_URL/psp-accounts" \
--header "Authorization: Bearer $TOKEN"

Request	Scope
`GET /psp-accounts`	`repigma.psp_account.read`

Request Body

Without any request body.

Response Body

Parameter	Type	Description	Example
count	Integer	The total number of PSPs accounts across all pages	123
next	String (Nullable)	The URL of the next page containing items after this page's items	"https://repigma-staging.qcluster.org/psp-accounts/?page=3"
previous	String (Nullable)	The URL of the next page containing items after this page's items	"https://repigma-staging.qcluster.org/psp-accounts/?page=1"
results	Array[details_of_psps_accounts]	The array containing the PSPs accounts details of this page that follows the schema of pagination

Detail of report inside list API

Each item inside of results key is:

Parameter	Type	Description	Example
uuid	String	The unique identifier for terminal	"3fa85f64-0000-4562-b3fc-2c963f66afa6"
name	String	The name of account	"test"
psp	String	The name of the `PSP` that terminal connected for process requests.	"SEP"
enabled	Boolean	This parameter indicates whether the feature or functionality is enabled.	true
created_at	String DateTime ISO 8601	This parameter indicates the date and time when the entity was created.	"2024-11-24T01:53:22.609789Z"

Response Data Example

{
  "count": 123,
  "next": "https://repigma-staging.qcluster.org/psp-accounts/?page=3",
  "previous": "https://repigma-staging.qcluster.org/psp-accounts/?page=1",
  "results": [
    {
      "uuid": "3fa85f64-5717-0000-b3fc-2c963f66afa6",
      "name": "test",
      "psp": "SEP",
      "enabled": true,
      "created_at": "2024-12-17T19:57:40.629Z"
    }
  ]
}

Filter By UUID

You can filter by ID using the endpoint GET /psp-accounts/{uuid} to retrieve the specific details associated with that PSP account.

Response Data Example For PSP account By UUID

{
  "uuid": "3fa85f64-0000-4562-b3fc-2c963f66afa6",
  "name": "test",
  "psp": "SEP",
  "enabled": true,
  "created_at": "2024-12-17T20:13:09.809Z"
}

Terminal Payment list

You can use this API to get list of payments filtered by terminal type.

import requests

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

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

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

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

Request	Scope
`GET /payments/<terminal_type>`	`repigma.payment.list`

you can view the types of terminals here. Type

Request Body

Without any request body.

Response Body

Parameter	Type	Description	Example
count	Integer	The total number of payments across all pages	123
next	String (Nullable)	The URL of the next page containing items after this page's items	"http://repigma-staging.qcluster.org/payments/ipg?cursor=bz0xJnA9MjAyNC0xMi0xNy"
previous	String (Nullable)	The URL of the next page containing items after this page's items	"http://repigma-staging.qcluster.org/payments/ipg?cursor=bz0xJnA9MjAyNC0xMi0xNy"
results	Array[list_of_payment]	The array containing the payments of this page that follows the schema of pagination

Detail of report inside list API

Each item inside of results key is:

Parameter	Type	Description	Example
id	String	This parameter specifies the unique identifier (ID) assigned to the terminal.	"01JFA14K25Z6JM7800T89W0ZFD"
amount	Integer	This parameter represents the transaction amount. (IRR)	6820500
psp	String	The name of the `PSP` that terminal connected for process requests.	"SEP"
masked_paid_card_number	String	This parameter provides the masked version of the card number used in the transaction recorded on the terminal	"603799******9999"
terminal_number	String	This parameter represents the unique terminal number, identifying the specific terminal where the transaction was processed.	"14141414"
transaction_datetime	String DateTime ISO 8601	This parameter specifies the date and time when the transaction occurred.	"2024-11-24T01:53:22.609789Z"
status	Integer	This parameter indicates the transaction status, where `0` represents a failed transaction and `1` indicates a successful transaction.	1

Response Data Example

{
  "count": 123,
  "next": "http://repigma-staging.qcluster.org/payments/ipg?cursor=bz0xJnA9MjAyNC0xMi0xNyswOSkIwMCUzQTAw",
  "previous": null,
  "results": [
    {
      "id": "01JFA14K25Z6JM78KNT0000ZFD",
      "amount": 682500,
      "masked_paid_card_number": "603799******9999",
      "terminal_number": "14141414",
      "transaction_datetime": "2024-12-17T10:02:55Z",
      "status": 1,
      "psp": "SEP"
    }
  ]
}