1. Overview
PPG is the Proxy Payment Gateway of JIBit Corporation.
It lets the users of 3rd-party clients (merchants, banks, organizations, etc.) purchase goodies from them
using PPG as a transparent payment gateway.
In the back end, we will redirect the user to a PSP payment gateway (for example, Saman IPG) to pay the
purchase price.
Using the APIs of this application, a client can create and initiate purchase orders and track the state of these purchases.
You can always download the latest REST API documentation of PPG (version 3) in HTML and Swagger (Open API) format.
Using Swagger Online Editor, you can directly call the PPG APIs and auto-generate an HTTP client for PPG APIs in your preferred programming language.
The base URL of PPG is:
1.1. Purchase Flow
The sequence diagram of the purchase flow is as follows:

It boils down to the following steps:
-
An authorized client creates a purchase.
If the purchase remains CREATED for a long time (15 minutes), we will expire and close the purchase (EXPIRED
state).
Note: To obtain an access token, use the Generate Token API.
To create a purchase, use the Create Purchase API. -
We create the requested purchase and return a few details, including the Payment URL (
pspSwitchingUrl
). -
The client’s user calls that Payment URL.
-
We select a PSP terminal for the user and initiate a payment process in the selected PSP.
-
If the initiation process succeeds, we will redirect the user to the PSP page.
If the initiation process has failed for any reason, we may fail and close the purchase after retrying with other possible PSP terminals (FAILED
state). -
In case of a successful initiation process in PSP, we expect the PSP to call our Callback to inform us of the payment process.
If the user does not complete the payment in less than 15 minutes, we may close the purchase and change its state toEXPIRED
. -
If the PSP redirects the user to our callback, we would redirect the user to the client callback with the same status as the PSP’s status.
Possible statuses areSUCCESSFUL
andFAILED
(andUNKNOWN
for auto-verify enabled terminals).
See Redirecting The User to The Client Callback. -
If the payment was successful, the client should verify the purchase completion using the Verify Purchase API (
READY_TO_VERIFY
state).
If the client does not verify the purchase, we will expire the purchase after 15 minutes(EXPIRED
state). -
If the client verifies us, we will verify the PSP payment and return the verification result to the client.
If, for whatever reason, the PSP verification result is unknown (UNKNOWN
state), the client should use the corresponding inquiry endpoint to identify the actual payment verification state.
Note: Use the Filter Purchases API to inquiry the purchases. -
In case of user payment fraud, we would fail the payment.
Possible frauds are changing the purchase amount or paying with a different card than the forced one.
After reversing the purchase, its amount will return to the user’s bank account in minutes or
hours.
11. Finally, we would insert the purchase in our ledger, and the purchase state will be SUCCESS
.
Purchase possible states are: IN_PROGRESS
, READY_TO_VERIFY
,EXPIRED
,
FAILED
, REVERSED
, SUCCESS
, and UNKNOWN
.
Note: After creating the purchase, if it is not verified (completed) within 15 minutes, it will be expired.
1.2. Redirecting The User to The Client Callback
After that, PSP redirects the user to our callback (Step 7); we would redirect the user to the client
callback with the POST
method and Content-Type: application/x-www-form-urlencoded
in the header.
The passed parameters are:
-
amount
: The amount of payment -
wage
: Represents the wage of purchase. -
currency
: The currency of payment.
Currently, its only value isIRR
. -
purchaseId
: The purchase Id generated on our side that uniquely identifies the purchase. -
clientReferenceNumber
: The reference number provided by the client for the purchase.
It may have special characters and therefore is URL-encoded. -
status
: Indicates the PSP payment status.
Possible values:SUCCESSFUL
,FAILED
, andUNKNOWN
.
UNKNOWN
status occurs only on terminals with auto-verify enabled.
ForSUCCESSFUL
andUNKNOWN
statuses, the client must call the Verify API to verify the purchase.
IfUNKNOWN
status persists after verification,
periodically inquiry purchase until it changes to a final state (FAILED
,SUCCESS
,REVERSED
, orEXPIRED
) -
payerIp
: The payer IP. -
pspReferenceNumber
: The PSP reference number.
It may have special characters and therefore is URL-encoded.
If the payment fails, we will not send this. -
pspRRN
: The PSP RRN.
If the payment fails, we will not send this. -
payerMaskedCardNumber
: The payer’s masked card number.
If the payment fails, we will not send this. -
pspName
: The PSP Name like 'saman-ipg', 'sepehr-ipg' or 'ap-ipg'. -
pspTerminalId
: The terminal ID of the PSP that handled the transaction. Example:22356849853
-
pspHashedCardNumber
: The hashed bank card number used for the transaction.
PSP provides it, and all its characters are upper case.
Example:F62A0955E51BC46D71B3647594913594
If the payment fails, we will not send this. -
failReason
: The purchase failure reason in case of any failure.
Possible values are: CANCELLED_BY_USER, TRANSACTION_TIMED_OUT, PSP_PAYER_CARD_NOT_MATCHED, UNKNOWN.
If the fail-reason is UNKNOWN, you can inquire the purchase later to find the exact fail reason.
If the payment succeeds, we will not send this.
POST {clientCallbackPath} HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: {clientCallbackHost}
amount=500000&wage=4000&currency=IRR&purchaseId=3476532108364833&clientReferenceNumber=client-ref-num&status=SUCCESSFUL&payerIp=23.155.43.100&pspReferenceNumber=GmshtyjwKSsd%2Fd54Idy8COJK78gDjse2BjPw%2B3dlFj&payerMaskedCardNumber=504172******7412&pspRRN=17356154785&pspName=saman-ipg&pspHashedCardNumber=F62A0955E51BC46D71B3647594913594
The client gives us the client callback URL at the purchase creation.
callbackUrl
== {clientCallbackHost}
+ {clientCallbackPath}
For example, if the client’s callbackUrl
is https://api.client.ir/transaction/1234567/callback
,
then:
-
{clientCallbackHost}
==https://api.client.ir
-
{clientCallbackPath}
==/transaction/1234567/callback
1.3. JWT Access Tokens
The client must have a token to access the authorized APIs on PPG.
The access token expiration duration is 24 hours.
The refresh token has a 2x expiration duration, which means it will expire in 48 hours.
The client is responsible for generating a new pair of access/refresh tokens using the refresh token every day.
For generating the pair of access/refresh tokens on the first day, the client must use the API/secret keys.
The API/secret keys are accessible on Dashboard Panel.
Note: Please don’t use the API/secret keys to generate a new pair of access/refresh tokens
in subsequent days.
Please consider this for the sake of your security.
The client should set the JWT token on the header of the requests that want to access the secured APIs in this format:
Authorization: Bearer {client.jwt.accessToken}
To get a new pair of access/refresh tokens using API/secret keys, use the Generate Token API.
To get a new pair of access/refresh tokens using the current refresh token, use the Refresh Token API.
1.4. Client-Trusted IPs
The client could introduce a set of trusted IPs to access the APIs on PPG.
After that, the client must call the APIs from one of those trusted IPs.
This feature is optional, and if the client doesn’t set any trusted IP, API calls from all IPs are
allowed.
The client owner should add the IPs on the Dashboard Panel to register the trusted IPs
for calling APIs of PPG.
If the client calls the APIs from an untrusted IP, it will get the ip.not_trusted
error.
Note: Only IPv4 addresses are supported. example: 5.117.199.255
1.5. Error Handling Mechanism
In any unsuccessful endpoint call (4xx and 5xx HTTP status codes), the response is JSON content in the form of:
{
"fingerprint": "79d4215f-deba-4f3c-8024-839448bcfaa0",
"errors": [
{
"code": "token.generation.failed",
"message": "Token generation failed."
}
]
}
The fingerprint helps us to track the exact problem internally.
The error array contains a list of possible errors.
Each error has a code as a field, and you can use this code to understand the meaning of the error.
Sometimes you will see a message alongside the code.
This message is a human-readable reason for the error that occurred.
If you encountered server.error
as code, tell us the fingerprint value to track the exact
problem internally.
We listed the possible error codes and messages for every endpoint.
1.5.1. Error Explained: Invalid Or Missing Body
When the request body is not a valid JSON object, the web.invalid_or_missing_body
as the
error code will return.
Possible reasons are:
-
When a field value does not have the correct type.
For example:-
Assigning a primitive value to an object field.
Example:{ "additionalData": 1234, … }
=> Correction:{ "additionalData": { "count": 1234 }, … }
-
Assigning an incorrect value for an enum field.
Example:{ "currency": "RIALS", … }
=> Correction:{ "currency": "IRR", … }
-
Assigning a float number to an integer field.
Example:{ "amount": 1840000.6, … }
=> Correction:{ "amount": 1840000, … }
-
-
When not opening or closing the brackets correctly.
Example:{ "amount": 120000, …
with missing closing bracket => Correction:{ "amount": 120000, … }
-
When using field names without
"
around them.
Example:{ amount: 120000, … }
=> Correction:{ "amount": 120000, … }
-
When using string values without
"
around them.
Example:{ "payerMobileNumber": 09334280857, … }
=> Correction:{ "payerMobileNumber": "09334280857", … }
1.6. Version information
Version : 3.1.231
1.7. URI scheme
Host : napi.jibit.ir
BasePath : /ppg
Schemes : HTTPS
1.8. Tags
-
App API : Provides APIs to check the health status of the service.
-
Client API : Provides the Client-related APIs.
-
Purchase API : Provides APIs to manage purchase-related APIs.
-
Refund API : Provides APIs to manage refund-related APIs.
-
Settlement API : Provides APIs to manage settlement-related APIs.
-
Terminal API : Provides APIs to manage terminal-related APIs.
-
Token API : Provides APIs to manage tokens of the client. These APIs are permitted to be called without the authorization token.
1.9. Consumes
-
application/json
1.10. Produces
-
application/json
2. Resources
2.1. App API
Provides APIs to check the health status of the service.
2.1.1. Check Health Status
GET /v3/app/health
Description
Checks the health status of the service.
Possible Error Codes:
-
ip.not_trusted
: When the client IP is not trusted. Read More. -
client.not_active
: When the client is inactive. -
security.auth_required
: The bearer JWT token is not in the request header as theAuthorization
parameter.
Read More. -
token.verification_failed
: When the access token is invalid or expired. Read More. -
server.error
: Internal server error. Please provide the value of the fingerprint to help us track the exact problem internally.
Authorization: Bearer JWT token in the header. Read More.
Example HTTP request
GET /ppg/v3/app/health HTTP/1.1
Host: napi.jibit.ir
Authorization: Bearer {client.jwt.accessToken}
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 48
{
"status" : "UP",
"pspStatusMap" : { }
}
Example Curl request
$ curl 'https://napi.jibit.ir/ppg/v3/app/health' -i -X GET \
-H 'Authorization: Bearer {client.jwt.accessToken}'
2.2. Client API
Provides the Client-related APIs.
2.2.1. Get Client Balances
GET /v3/balances
Description
Retrieves the balances of the client for all its balance types.
Possible Error Codes:
-
client.not_active
: When the current client is not active. -
ip.not_trusted
: When the client IP is not trusted. Read More. -
security.auth_required
: The bearer JWT token is not present in request header as theAuthorization
parameter.
Read More. -
token.verification_failed
: The access token is invalid or expired. Read More. -
server.error
: Internal server error. Please tell us the value of the fingerprint to track the exact problem internally.
Authorization: Bearer JWT token in header. Read More.
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The balances of the client. |
Example HTTP request
GET /ppg/v3/balances HTTP/1.1
Host: napi.jibit.ir
Authorization: Bearer {client.jwt.accessToken}
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 438
{
"balances" : [ {
"balanceType" : "WLT",
"amount" : 10000,
"currency" : "IRR"
}, {
"balanceType" : "STL",
"amount" : 10000,
"currency" : "IRR"
}, {
"balanceType" : "FEE",
"amount" : 10000,
"currency" : "IRR"
}, {
"balanceType" : "SHW",
"amount" : 10000,
"currency" : "IRR"
}, {
"balanceType" : "BLK",
"amount" : 10000,
"currency" : "IRR"
} ]
}
Example Curl request
$ curl 'https://napi.jibit.ir/ppg/v3/balances' -i -X GET \
-H 'Authorization: Bearer {client.jwt.accessToken}'
2.3. Purchase API
Provides APIs to manage purchase-related APIs.
2.3.1. Create Purchase
POST /v3/purchases
Description
Creates a purchase request.
After creating the purchase, the client must redirect its user to the provided URL (pspSwitchingUrl
).
Once the purchase is initialized, the user will be redirected to a PSP payment gateway. See also Redirecting The User to The Client Callback
Note 1: After the user completes the payment on the PSP page, the client should verify the purchase.
Note 2: If the purchase is not verified (completed) within 15 minutes of creation, it will expire.
Possible Error Codes:
-
client.not_active
: When the client is inactive. -
amount.is_required
: When the amount is empty. -
amount.not_enough
: When the amount is invalid. The minimum amount is 5000 Rials. -
wage.is_invalid
: When the wage is invalid. Its minimum value is 0. -
fee_as_wage.wage_must_be_zero
: When the Setting the Fee as Wage feature is enabled for the client, and thewage
parameter has non-zero value. -
amount_plus_wage.permitted_value_exceeded
: When amount plus wage exceeds the maximum permitted value for your client. The default max amount is 2_000_000_000 IRR. -
wage.must_be_less_than_fifteen_percent_of_purchase_amount
: when wage exceeds 15% of the purchase amount. -
currency.is_required
: When the currency is empty. -
callbackUrl.is_required
: When callbackUrl is empty. -
callbackUrl.is_invalid
: When callbackUrl is invalid. -
callbackUrl.max_length
: When callbackUrl exceeds its allowed length. Its maximum length is 1024 characters. -
callbackUrl.domain_not_in_whitelist
: Domain of callback URL is not in whitelist. -
clientReferenceNumber.is_required
: When clientReferenceNumber is empty. -
clientReferenceNumber.duplicated
: When clientReferenceNumber for the client is not unique. -
payerCardNumber.is_invalid
: When payerCardNumber is invalid. -
payerNationalCode.is_invalid
: When payerNationalCode is invalid. -
userIdentifier.max_length
: When userIdentifier exceeds its allowed length. Its maximum length is 50 characters. -
payerMobileNumber.is_invalid
: When payerMobileNumber is invalid. -
payerMobileNumber.in_blacklist
: When the payer mobile number is in the blacklist. -
payerMobileNumber.must_be_provided_to_check_with_card_number
: When the client has setcheckPayerMobileNumber
to true, but the payerMobileNumber is not provided. -
payerCardNumber_and_payerCardNumbers.just_one_of_them_is_permitted
: Just one of these parameters is permitted:payerCardNumber
,payerCardNumbers
-
description.max_length
: When the description exceeds its allowed length. Its maximum length is 256 characters. -
switching.terminalIds.is_required
: When no terminal IDs are provided for terminal switching. -
ip.not_trusted
: When the client IP is not trusted. Read More. -
security.auth_required
: The bearer JWT token is not in the request header as theAuthorization
parameter. Read More. -
token.verification_failed
: The access token is invalid or expired. Read More. -
web.invalid_or_missing_body
: When the request body is not a valid JSON. Read More. -
server.error
: Internal server error. Please provide the value of the fingerprint to help us track the exact problem internally.
Authorization: Bearer JWT token in the header. Read More.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Body |
dto |
Encapsulates the information required to create a purchase. |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Encapsulates the details of the created purchase including the PSP switching URL. |
Example HTTP request
POST /ppg/v3/purchases HTTP/1.1
Content-Type: application/json
Content-Length: 627
Host: napi.jibit.ir
Authorization: Bearer {client.jwt.accessToken}
{
"amount" : 499990000,
"wage" : 10000,
"currency" : "IRR",
"callbackUrl" : "https://www.client.ir/purchases/123456789/callback",
"clientReferenceNumber" : "required-client-ref-num",
"userIdentifier" : "a.pourtaghi",
"payerNationalCode" : "2234567890",
"payerCardNumber" : "6037997122223333",
"payerCardNumbers" : [ "6037997122223333" ],
"payerMobileNumber" : "09123454321",
"additionalData" : {
"someTag" : "some-value"
},
"description" : "optional client description",
"switching" : {
"terminalIds" : [ "saman_11223344", "sepehr_1234" ],
"autoSwitching" : true
}
}
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 231
{
"purchaseId" : 1345628234,
"purchaseIdStr" : "1345628234",
"clientReferenceNumber" : "required-client-ref-num",
"pspSwitchingUrl" : "https://napi.jibit.ir/ppg/v3/purchases/1345628234/payments",
"currency" : null
}
Example Curl request
$ curl 'https://napi.jibit.ir/ppg/v3/purchases' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {client.jwt.accessToken}' \
-d '{
"amount" : 499990000,
"wage" : 10000,
"currency" : "IRR",
"callbackUrl" : "https://www.client.ir/purchases/123456789/callback",
"clientReferenceNumber" : "required-client-ref-num",
"userIdentifier" : "a.pourtaghi",
"payerNationalCode" : "2234567890",
"payerCardNumber" : "6037997122223333",
"payerCardNumbers" : [ "6037997122223333" ],
"payerMobileNumber" : "09123454321",
"additionalData" : {
"someTag" : "some-value"
},
"description" : "optional client description",
"switching" : {
"terminalIds" : [ "saman_11223344", "sepehr_1234" ],
"autoSwitching" : true
}
}'
2.3.2. Filter Purchases
GET /v3/purchases
Description
Filters the purchases with provided criteria and page request.
All criteria parameter values should be URL-Encoded.
Possible Error Codes:
-
too_many_requests
: Only one request is allowed at a time to filter purchases. -
page_number.max_exceeded
: The page number is exceeded its allowed value. -
page_size.max_exceeded
: The page size is exceeded its allowed size. -
client.not_active
: When the client is not active. -
ip.not_trusted
: When the client IP is not trusted. Read More. -
security.auth_required
: The bearer JWT token is not present in request header as theAuthorization
parameter.
Read More. -
token.verification_failed
: The access token is invalid or expired. Read More. -
server.error
: Internal server error. Please tell us the value of fingerprint to be able to track the exact problem internally.
Authorization: Bearer JWT token in header. Read More.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Query |
clientReferenceNumber |
Finds a purchase by its client
reference number. The |
string |
Query |
from |
Filters purchases from their
creation date inclusively. The |
string (date-time) |
Query |
page |
Represents the page number; One
indexed. The |
integer (int32) |
Query |
pspReferenceNumber |
Filters purchases by their PSP
reference number. The |
string |
Query |
pspRrn |
Filters purchases by their PSP
RRN. The |
string |
Query |
pspTraceNumber |
Filters purchases by their PSP
trace number. The |
string |
Query |
purchaseId |
Finds a purchase by its
identifier. Can be used to find an exact purchase. The |
integer (int64) |
Query |
size |
Represents the page size. The
|
integer (int32) |
Query |
status |
Filters purchases based on their
state. The |
enum (EXPIRED, FAILED, IN_PROGRESS, MANUALLY_SUCCESS, READY_TO_VERIFY, REVERSED, SUCCESS, UNKNOWN) |
Query |
to |
Filters purchases to their
creation date exclusively. The |
string (date-time) |
Query |
userIdentifier |
Filters purchases based on their
user identifier. The |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The list of paginated purchases. |
Example HTTP request
GET /ppg/v3/purchases?status=FAILED&userIdentifier=09334565674&page=1&size=20 HTTP/1.1
Host: napi.jibit.ir
Authorization: Bearer {client.jwt.accessToken}
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 1968
{
"pageNumber" : 1,
"size" : 20,
"numberOfElements" : 1,
"hasNext" : false,
"hasPrevious" : false,
"elements" : [ {
"purchaseId" : 1200,
"purchaseIdStr" : "1200",
"amount" : 100000,
"wage" : 5000,
"fee" : 4555,
"feePaymentType" : "POST_PAID",
"shaparakFee" : 1200,
"resellerCode" : "test-reseller",
"affiliateFee" : 50000,
"netAmount" : 103800,
"currency" : "IRR",
"callbackUrl" : "https://www.client.ir/purchases/123456789/callback",
"state" : "READY_TO_VERIFY",
"clientReferenceNumber" : "client-ref-num",
"pspName" : "saman-ipg",
"pspRrn" : "84a29cbb205c4aa18dc71b8e3cb99639",
"pspReferenceNumber" : "GmshtyjwKSsoD4uz5cpmzY5aBaWxx21mxAYRo92Gx0",
"pspTraceNumber" : "psp-trace-num",
"expirationDate" : "2025-06-11T02:21:21.128222700Z",
"userIdentifier" : "a.pourtaghi",
"payerMobileNumber" : "09132517905",
"payerCardNumber" : "434567-3452",
"payerNationalCode" : "4060145796",
"description" : "client custom description",
"additionalData" : {
"someTag" : "some-value"
},
"pspMaskedCardNumber" : "434567****3452",
"pspHashedCardNumber" : "538B3C64A94DEE355DA7DB7BF8A7D50F",
"pspCardOwner" : "Ali Khaksari",
"pspFailReason" : "CARD_IS_LIMITED",
"pspFailReasons" : [ {
"code" : 62,
"description" : "کارت بانکی محدود شده است",
"pspError" : "CARD_IS_LIMITED"
} ],
"initPayerIp" : "43.23.6.28",
"redirectPayerIp" : "45.73.6.28",
"pspSettled" : false,
"refunded" : null,
"refundInquiryResult" : null,
"refundableAmount" : 105000,
"createdAt" : "2025-06-11T02:13:01.127260900Z",
"billingDate" : "2025-06-11T02:16:21.128222700Z",
"verifiedAt" : "2025-06-11T02:15:51.128222700Z",
"pspSettledAt" : "2025-06-11T02:23:01.128222700Z",
"settlementId" : null,
"hasContradiction" : true
} ]
}
Example Curl request
$ curl 'https://napi.jibit.ir/ppg/v3/purchases?status=FAILED&userIdentifier=09334565674&page=1&size=20' -i -X GET \
-H 'Authorization: Bearer {client.jwt.accessToken}'
2.3.3. Filter Purchase Histories
GET /v3/purchases/histories
Description
Filters purchase log history based on the given criteria and page request.
For quicker responses, choose smaller date ranges, such as one hour,
and use nextPageId
instead of page
in your request.
Ensure all criteria parameter values are URL-Encoded.
Note: Except for filtering by purchase identifier (purchaseId
), other
filtering options need to be manually enabled by an admin.
Possible Error Codes:
-
from_and_to.difference_must_be_less_than_3_hours
: The difference betweenfrom
andto
should be less than 3 hours. -
criteria.is_empty
: No filtering criteria specified. Please include at least one. -
states.can_not_have_null_value
: Thestates
parameter cannot have a null value. -
too_many_requests
: Only one request at a time is allowed for filtering purchase histories. -
page_number.max_exceeded
: The page number exceeds its allowed value. -
page_size.max_exceeded
: The page size exceeds its allowed value. -
client.not_active
: The client is not active. -
ip.not_trusted
: The client’s IP is not trusted. Xref:client_trusted_ips[Read More.] -
security.auth_required
: A Bearer JWT token as theAuthorization
parameter is missing in the request header. Xref:jwt_access_tokens[Read More.] -
token.verification_failed
: The access token is invalid or expired. Xref:jwt_access_tokens[Read More.] -
server.error
: Internal server error. Provide the fingerprint value to help trace the issue internally.
Authorization: Bearer JWT token in header. Xref:jwt_access_tokens[Read More.]
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Query |
from |
The start of the date range
(inclusive) for querying purchase history. |
string (date-time) |
Query |
nextPageId |
The identifier for fetching the
next page of results. |
integer (int64) |
Query |
page |
The page number to fetch
(1-indexed). If null, it means the first page. |
integer (int32) |
Query |
purchaseId |
Represents the unique identifier
for a purchase. |
integer (int64) |
Query |
size |
The number of results per page.
If null, the default size will be used. |
integer (int32) |
Query |
statuses |
A list representing the statuses
of a purchase history. |
< enum (MANUALLY_SUCCESS, REVERSED, UNKNOWN) > array(multi) |
Query |
to |
The end of the date range
(exclusive) for querying purchase history. |
string (date-time) |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
A paginated list of purchase
histories. |
Example HTTP request
GET /ppg/v3/purchases/histories?nextPageId=123456789012345&size=3&purchaseId=1234567890123456&statuses=REVERSED%252CMANUALLY_SUCCESS%252CUNKNOWN&statuses=REVERSED%2CMANUALLY_SUCCESS%2CUNKNOWN HTTP/1.1
Host: napi.jibit.ir
Authorization: Bearer {client.jwt.accessToken}
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 635
{
"size" : 3,
"totalCount" : 8,
"hasNext" : true,
"nextPageId" : "9876543210987653",
"elements" : [ {
"purchaseId" : 1234567890123456,
"clientRefNum" : "client-ref-num-3",
"newState" : "MANUALLY_SUCCESS",
"createdAt" : "2025-06-11T02:12:59.542471900Z"
}, {
"purchaseId" : 1234567890123456,
"clientRefNum" : "client-ref-num-2",
"newState" : "REVERSED",
"createdAt" : "2025-06-11T02:12:59.542471900Z"
}, {
"purchaseId" : 1234567890123456,
"clientRefNum" : "client-ref-num-1",
"newState" : "UNKNOWN",
"createdAt" : "2025-06-11T02:12:59.541474100Z"
} ]
}
Example Curl request
$ curl 'https://napi.jibit.ir/ppg/v3/purchases/histories?nextPageId=123456789012345&size=3&purchaseId=1234567890123456&statuses=REVERSED%252CMANUALLY_SUCCESS%252CUNKNOWN&statuses=REVERSED%2CMANUALLY_SUCCESS%2CUNKNOWN' -i -X GET \
-H 'Authorization: Bearer {client.jwt.accessToken}'
2.3.4. Reverse Purchase
POST /v3/purchases/reverse
Description
Reverse a purchase.
This feature is not enabled by default and should be enabled by admin manually.
Possible Error Codes:
-
reverse.is_not_enabled
: When this feature is not enabled for the client. -
purchase.not_found
: When the purchase is not found. -
reverse.not_supported
: When the refund is not supported for this type of purchase. -
purchase.invalid_state
: When the purchase is not in valid (FINISHED) state. -
clientReferenceNumber_or_purchaseId.are_required
: When clientReferenceNumber and purchaseId are not provided. -
purchase.not_reversible
: When the purchase is not reversible because of internal verification procedures. -
purchase.refunded
: When the refund API has called for this purchase; so you can’t reverse it. -
purchase.already_reversed
: When the purchase is already reversed. -
ip.not_trusted
: When the client IP is not trusted. Read More. -
security.auth_required
: The bearer JWT token is not present in request header as theAuthorization
parameter.
Read More. -
token.verification_failed
: The access token is invalid or expired. Read More. -
web.invalid_or_missing_body
: When the request body is not a valid JSON. Read More. -
server.error
: Internal server error. Please tell us the value of fingerprint to be able to track the exact problem internally.
Authorization: Bearer JWT token in header. Read More.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Body |
dto |
Encapsulated the information required to reverse a purchase. |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Encapsulates the purchase reverse
result. |
2.3.5. Verify Purchase
POST /v3/purchases/{purchaseId}/verify
Description
Verifies a purchase by the client.
The client should call this API after we redirect the user to the client’s callback URL.
Only purchases with the state READY_TO_VERIFY
can be verified.
If the client does not call this API, the PSP will automatically reverse the payment after a certain
period of time, and the purchase state will be set to EXPIRED
.
Note 1: This API does not have a request body and can be called using both GET
and POST
methods.
Note 2: For using Auto-verify feature consult our admins. Note that using this feature does not
guaranty that purchase will be verified 100%,
but it can decrease the number of EXPIRED
purchases due to not verified by client
significantly.
So a client still must call the verification API with this feature enabled, but in most cases the API
will return payment.already_verified
error.
Possible Error Codes:
-
ip.not_trusted
: When the client IP is not trusted. Read More. -
client.not_active
: When the client is inactive. -
purchase.not_found
: When the purchase does not found. -
payment.already_verified
: When the purchase is already verified. -
purchase.invalid_state
: When the purchase’s state is invalid. -
purchase.already_reversed
: When the purchase is already reversed. -
security.auth_required
: The bearer JWT token is not in the request header as theAuthorization
parameter.
Read More. -
token.verification_failed
: When the access token is invalid or expired. Read More. -
server.error
: Internal server error. Please provide the value of the fingerprint to help us track the exact problem internally.
Authorization: Bearer JWT token in the header. Read More.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
purchaseId |
Represents the purchase Identifier. |
integer (int64) |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Encapsulates the purchase
verification result. |
2.4. Refund API
Provides APIs to manage refund-related APIs.
2.4.1. Refund Purchase
POST /v3/purchases/refund
Description
Refunds a purchase.
Possible Error Codes:
-
clientReferenceNumber_or_purchaseId.are_required
: When clientReferenceNumber and purchaseId are not provided. -
purchase.not_found
: When the purchase is not found. -
purchase.invalid_state
: When the purchase is not in valid (SUCCESS) state. -
refund.not_supported
: When the refund is not supported for this type of purchase. -
batchID.invalid_length
-
submissionMode.not_valid
-
transfers.invalid_length
-
transfers.0.transferID.invalid_length
-
transfers.0.destination.not_valid
-
transfers.0.source_bank.not_supported
-
transfers.0.destinationFirstName.invalid_length
-
transfers.0.destinationLastName.invalid_length
-
transfers.0.amount.not_enough_for_ach
-
transfers.0.amount.exceeded_maximum_for_ach
-
transfers.0.amount.not_enough_for_normal
-
transfers.0.amount.exceeded_maximum_for_normal
-
transfers.0.currency.not_valid
-
transfers.0.description.invalid_length
-
transfers.0.metadata.invalid_length
-
transfers.0.notifyURL.invalid_length
-
transfers.0.notifyURL.not_valid
-
transfers.0.paymentID.invalid_length
-
transfers.0.paymentID.not_valid
-
payment_id.not_enabled
-
balances.not_enough
-
daily_limitation.reached
-
transfer.already_exists
-
ip.not_trusted
: When the client IP is not trusted. Read More. -
security.auth_required
: The bearer JWT token is not present in request header as theAuthorization
parameter.
Read More. -
token.verification_failed
: The access token is invalid or expired. Read More. -
web.invalid_or_missing_body
: When the request body is not a valid JSON. Read More. -
server.error
: Internal server error. Please tell us the value of fingerprint to be able to track the exact problem internally.
Authorization: Bearer JWT token in header. Read More.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Body |
dto |
Encapsulated the information required to refund a purchase. |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Encapsulates the response information of purchase refund from transferor. |
Example HTTP request
POST /ppg/v3/purchases/refund HTTP/1.1
Content-Type: application/json
Content-Length: 125
Host: napi.jibit.ir
Authorization: Bearer {client.jwt.accessToken}
{
"clientReferenceNumber" : "client-ref-num-222",
"purchaseId" : 1234,
"amount" : 490000,
"cancellable" : true
}
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 125
{
"refundId" : 1234,
"partialRefundIndex" : 1,
"batchId" : "REFUND-BATCH-1234",
"transferId" : "REFUND-1234-1"
}
Example Curl request
$ curl 'https://napi.jibit.ir/ppg/v3/purchases/refund' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {client.jwt.accessToken}' \
-d '{
"clientReferenceNumber" : "client-ref-num-222",
"purchaseId" : 1234,
"amount" : 490000,
"cancellable" : true
}'
2.4.2. Inquiry Refund
GET /v3/purchases/refunds/{refundId}
Description
Inquiries a Refund.
refundId is purchaseId.
Possible Error Codes:
-
transfer.not_found
: When the refundId is not found. -
ip.not_trusted
: When the client IP is not trusted. Read More. -
security.auth_required
: The bearer JWT token is not present in request header as theAuthorization
parameter.
Read More. -
token.verification_failed
: The access token is invalid or expired. Read More. -
web.invalid_or_missing_body
: When the request body is not a valid JSON. Read More. -
server.error
: Internal server error. Please tell us the value of fingerprint to be able to track the exact problem internally.
Authorization: Bearer JWT token in header. Read More.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
refundId |
refundId |
integer (int64) |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
Encapsulates the details of transferor refund inquiry. |
2.4.3. Cancel Refund
POST /v3/purchases/refunds/{refundId}/cancel
Description
Cancels a cancelling refund.
Possible Error Codes:
-
transfer.not_found
: When the refundId is not found. -
cancellation.failed
: When the cancellation process failed. -
cancellation.not_applicable
: When cancel request could not be applied. -
ip.not_trusted
: When the client IP is not trusted. Read More. -
security.auth_required
: The bearer JWT token is not present in request header as theAuthorization
parameter.
Read More. -
token.verification_failed
: The access token is invalid or expired. Read More. -
web.invalid_or_missing_body
: When the request body is not a valid JSON. Read More. -
server.error
: Internal server error. Please tell us the value of fingerprint to be able to track the exact problem internally.
Authorization: Bearer JWT token in header. Read More.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
refundId |
is equal to
|
integer (int64) |
Body |
dto |
Encapsulated the information required to do an action on a (partial) refund. |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
OK |
No Content |
Example HTTP request
POST /ppg/v3/purchases/refunds/1234/cancel HTTP/1.1
Content-Type: application/json
Content-Length: 62
Host: napi.jibit.ir
Authorization: Bearer {client.jwt.accessToken}
{
"transferId" : "trf-id-1",
"partialRefundIndex" : 1
}
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Example Curl request
$ curl 'https://napi.jibit.ir/ppg/v3/purchases/refunds/1234/cancel' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {client.jwt.accessToken}' \
-d '{
"transferId" : "trf-id-1",
"partialRefundIndex" : 1
}'
2.4.4. Ignore Cancelling Refund
POST /v3/purchases/refunds/{refundId}/ignore-cancellable
Description
Ignores a cancelling refund.
Possible Error Codes:
-
transfer.not_found
: When the refundId is not found. -
ip.not_trusted
: When the client IP is not trusted. Read More. -
security.auth_required
: The bearer JWT token is not present in request header as theAuthorization
parameter.
Read More. -
token.verification_failed
: The access token is invalid or expired. Read More. -
web.invalid_or_missing_body
: When the request body is not a valid JSON. Read More. -
server.error
: Internal server error. Please tell us the value of fingerprint to be able to track the exact problem internally.
Authorization: Bearer JWT token in header. Read More.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
refundId |
is equal to
|
integer (int64) |
Body |
dto |
Encapsulated the information required to do an action on a (partial) refund. |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
OK |
No Content |
Example HTTP request
POST /ppg/v3/purchases/refunds/1234/ignore-cancellable HTTP/1.1
Content-Type: application/json
Content-Length: 58
Host: napi.jibit.ir
Authorization: Bearer {client.jwt.accessToken}
{
"transferId" : "tf-2",
"partialRefundIndex" : 1
}
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Example Curl request
$ curl 'https://napi.jibit.ir/ppg/v3/purchases/refunds/1234/ignore-cancellable' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {client.jwt.accessToken}' \
-d '{
"transferId" : "tf-2",
"partialRefundIndex" : 1
}'
2.4.5. Retry Refund
POST /v3/purchases/refunds/{refundId}/retry
Description
Retries a failed refund.
Possible Error Codes:
-
transfer.not_found
: When the refundId is not found. -
retry.failed
: When the retry process failed. -
retry.not_applicable
: When retry request could not be applied. -
ip.not_trusted
: When the client IP is not trusted. Read More. -
security.auth_required
: The bearer JWT token is not present in request header as theAuthorization
parameter.
Read More. -
token.verification_failed
: The access token is invalid or expired. Read More. -
web.invalid_or_missing_body
: When the request body is not a valid JSON. Read More. -
server.error
: Internal server error. Please tell us the value of fingerprint to be able to track the exact problem internally.
Authorization: Bearer JWT token in header. Read More.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
refundId |
is equal to
|
integer (int64) |
Body |
dto |
Encapsulated the information required to do an action on a (partial) refund. |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
OK |
No Content |
Example HTTP request
POST /ppg/v3/purchases/refunds/1234/retry HTTP/1.1
Content-Type: application/json
Content-Length: 58
Host: napi.jibit.ir
Authorization: Bearer {client.jwt.accessToken}
{
"transferId" : "tf-3",
"partialRefundIndex" : 1
}
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Example Curl request
$ curl 'https://napi.jibit.ir/ppg/v3/purchases/refunds/1234/retry' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {client.jwt.accessToken}' \
-d '{
"transferId" : "tf-3",
"partialRefundIndex" : 1
}'
2.4.6. Verify Refund
POST /v3/purchases/refunds/{refundId}/verify
Description
Verifies a refund. If the verifying refund option is enabled, the client should verify its refund to start actual refunding.
Possible Error Codes:
-
transfer.not_found
: When the refundId is not found. -
purchase.not_found
: When the purchase is not found. -
verify.failed
: There is an internal issue while verifying. Please try again. -
verify.not_applicable
: The refund is already verified, and it can’t be verified again. -
ip.not_trusted
: When the client IP is not trusted. Read More. -
security.auth_required
: The bearer JWT token is not present in request header as theAuthorization
parameter.
Read More. -
token.verification_failed
: The access token is invalid or expired. Read More. -
server.error
: Internal server error. Please tell us the value of fingerprint to be able to track the exact problem internally.
Authorization: Bearer JWT token in header. Read More.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
refundId |
is equal to
|
integer (int64) |
Body |
dto |
Encapsulated the information required to do an action on a (partial) refund. |
Responses
HTTP Code | Description | Schema |
---|---|---|
204 |
No Content |
No Content |
Example HTTP request
POST /ppg/v3/purchases/refunds/1234/verify HTTP/1.1
Content-Type: application/json
Content-Length: 60
Host: napi.jibit.ir
Authorization: Bearer {client.jwt.accessToken}
{
"transferId" : "trf-id",
"partialRefundIndex" : 1
}
Example HTTP response
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Example Curl request
$ curl 'https://napi.jibit.ir/ppg/v3/purchases/refunds/1234/verify' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {client.jwt.accessToken}' \
-d '{
"transferId" : "trf-id",
"partialRefundIndex" : 1
}'
2.5. Settlement API
Provides APIs to manage settlement-related APIs.
2.5.1. Filter Settlements
GET /v3/settlements
Description
Filters the settlements with provided criteria and page request.
All criteria parameter values should be URL-Encoded.
Possible Error Codes:
-
page_number.max_exceeded
: The page number is exceeded its allowed value. -
page_size.max_exceeded
: The page size is exceeded its allowed size. -
client.not_active
: When the client is not active. -
ip.not_trusted
: When the client IP is not trusted. Read More. -
security.auth_required
: The bearer JWT token is not present in request header as theAuthorization
parameter.
Read More. -
token.verification_failed
: The access token is invalid or expired. Read More. -
server.error
: Internal server error. Please tell us the value of fingerprint to be able to track the exact problem internally.
Authorization: Bearer JWT token in header. Read More.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Query |
page |
Represents the page number; One
indexed. The |
integer (int32) |
Query |
settlementId |
Finds a settlement by its
identifier. The |
integer (int64) |
Query |
size |
Represents the page size. The
|
integer (int32) |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The list of paginated settlements. |
Example HTTP request
GET /ppg/v3/settlements?settlementId=12345&page=1&size=20 HTTP/1.1
Host: napi.jibit.ir
Authorization: Bearer {client.jwt.accessToken}
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 716
{
"pageNumber" : 1,
"size" : 20,
"numberOfElements" : 1,
"hasNext" : false,
"hasPrevious" : false,
"elements" : [ {
"settlementId" : 12345,
"terminalId" : "591914e6-63ec-4ce7-993d-42400b26a8c0",
"fileName" : "file-name",
"state" : "IN_PROGRESS",
"amount" : 100000,
"wage" : 555555,
"directSettlement" : true,
"currency" : "IRR",
"cutoff" : "05:43:06.6704446",
"acceptorCode" : "acceptor-code",
"ledgerAccount" : "ledger-account",
"iin" : 4433333,
"paymentFacilitatorIban" : "IR9999",
"settlementIban" : "IR3333",
"createdAt" : "2025-06-11T02:13:06.670444600Z",
"modifiedAt" : "2025-06-11T02:13:06.670444600Z"
} ]
}
Example Curl request
$ curl 'https://napi.jibit.ir/ppg/v3/settlements?settlementId=12345&page=1&size=20' -i -X GET \
-H 'Authorization: Bearer {client.jwt.accessToken}'
2.6. Terminal API
Provides APIs to manage terminal-related APIs.
2.6.1. List Active Terminals
GET /v3/terminals/list
Description
Lists all active terminals of the client and it’s subordinates.
Possible Error Codes:
-
client.not_active
: When the client is inactive. -
ip.not_trusted
: When the client IP is not trusted. Read More. -
security.auth_required
: The bearer JWT token is not in the request header as theAuthorization
parameter. Read More. -
token.verification_failed
: The access token is invalid or expired. Read More. -
web.invalid_or_missing_body
: When the request body is not a valid JSON. Read More. -
server.error
: Internal server error. Please provide the value of the fingerprint to help us track the exact problem internally.
Authorization: Bearer JWT token in the header. Read More.
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
A wrapper for the collection responses. |
Example HTTP request
GET /ppg/v3/terminals/list HTTP/1.1
Host: napi.jibit.ir
Authorization: Bearer {client.jwt.accessToken}
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 497
{
"elements" : [ {
"naturalId" : "sepehr_223456789",
"clientCode" : "rayan",
"clientName" : "rayan-name",
"pspName" : "sepehr-ipg",
"pspTerminalId" : "223456789",
"pspMerchantNumber" : "1102395",
"type" : "NORMAL",
"directSettlement" : false,
"priority" : 10,
"isAutoVerifyEnabled" : false,
"isCheckPayerMobileNumberActive" : true,
"isCheckPayerNationalCodeActive" : true,
"createdAt" : "2025-06-11T02:13:08.902217900Z"
} ]
}
Example Curl request
$ curl 'https://napi.jibit.ir/ppg/v3/terminals/list' -i -X GET \
-H 'Authorization: Bearer {client.jwt.accessToken}'
2.7. Token API
Provides APIs to manage tokens of the client. These APIs are permitted to be called without the authorization token.
2.7.1. Generate Token
POST /v3/tokens
Description
Generates a pair of access/refresh tokens by using API/secret keys.
Possible Error Codes:
-
security.bad_credentials
: When provided api/secret keys are not valid. -
client.not_active
: When the client is not active. -
apiKey.is_required
: When api key is not provided. -
secretKey.is_required
: When secret Key is not provided. -
web.invalid_or_missing_body
: When the request body is not a valid JSON. Read More. -
server.error
: Internal server error. Please tell us the value of fingerprint to be able to track the exact problem internally.
Authorization
header parameter is NOT required.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Body |
dto |
The dto encapsulating the information to generate a pair of access/refresh tokens. |
Example HTTP request
POST /ppg/v3/tokens HTTP/1.1
Content-Type: application/json
Content-Length: 59
Host: napi.jibit.ir
{
"apiKey" : "api-key",
"secretKey" : "secret-key"
}
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 75
{
"accessToken" : "access-token",
"refreshToken" : "refresh-token"
}
Example Curl request
$ curl 'https://napi.jibit.ir/ppg/v3/tokens' -i -X POST \
-H 'Content-Type: application/json' \
-d '{
"apiKey" : "api-key",
"secretKey" : "secret-key"
}'
2.7.2. Refresh Token
POST /v3/tokens/refresh
Description
Refreshes the access/refresh tokens by using previously generated refresh token.
Possible Error Codes:
-
security.bad_credentials
: When provided refresh token is not valid. -
client.not_active
: When the client is not active. -
refreshToken.is_required
: When refresh token is not provided. -
web.invalid_or_missing_body
: When the request body is not a valid JSON. Read More. -
server.error
: Internal server error. Please tell us the value of fingerprint to be able to track the exact problem internally.
Authorization
header parameter is NOT required.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Body |
dto |
The dto encapsulating the information to refresh the access/refresh tokens for the client. |
Example HTTP request
POST /ppg/v3/tokens/refresh HTTP/1.1
Content-Type: application/json
Content-Length: 40
Host: napi.jibit.ir
{
"refreshToken" : "refresh-token"
}
Example HTTP response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 75
{
"accessToken" : "access-token",
"refreshToken" : "refresh-token"
}
Example Curl request
$ curl 'https://napi.jibit.ir/ppg/v3/tokens/refresh' -i -X POST \
-H 'Content-Type: application/json' \
-d '{
"refreshToken" : "refresh-token"
}'
3. Definitions
3.1. Balance
Name | Description | Schema |
---|---|---|
amount |
Represents the amount of current balance type. |
integer (int64) |
balanceType |
Represents the balance type. Its
possible values are: |
string |
currency |
Represents the currency of current balance type. |
enum (IRR) |
3.2. ClientBalances
Name | Description | Schema |
---|---|---|
balances |
Represents the list of ledger account balances which may contain the default wallet and pre-paid/post-paid fees and settleable wallet. |
< Balance > array |
3.3. CollectionResponse«TerminalDto»
Name | Description | Schema |
---|---|---|
elements |
Represents the actual data. |
< TerminalDto > array |
3.4. CreatePurchaseDto
Name | Description | Schema |
---|---|---|
additionalData |
Represents the additional data
provided by client in JSON format. Optional. |
object |
amount |
Represents the amount of
purchase. |
integer (int64) |
callbackUrl |
Represents a callback which we should
call in order to notify the client about a particular purchase state. |
string |
checkPayerMobileNumber |
If this flag is set to true, the
payment must be paid only by a card which belongs to the owner of the phone number; |
boolean |
clientReferenceNumber |
Represents a reference number
provided by client to trace purchase in our system. |
string |
currency |
Represents the currency of |
enum (IRR) |
description |
Represents the client-provided
description. Optional. |
string |
payerCardNumber |
Bank card number which is required to
do the transaction. |
string |
payerCardNumbers |
Bank card numbers which are required
to do the transaction. |
< string > array |
payerMobileNumber |
Represents the mobile number of the
payer. It will be sent to Psp to autocomplete the payment fields. |
string |
payerNationalCode |
Represents the national code of card
owner. |
string |
switching |
Represents the terminal switching
information in the purchase process. |
|
userIdentifier |
Represents the user identifier in the
client system. |
string |
wage |
Represents the wage of purchase. |
integer (int64) |
3.5. DetailedPurchaseDto
Name | Description | Schema |
---|---|---|
additionalData |
An optional additional data provided
by the client in JSON format. |
object |
affiliateFee |
Represents the reseller affiliate fee for this purchase. |
integer (int64) |
amount |
Represents the amount of purchase. |
integer (int64) |
billingDate |
When was the billing date? Used to
generate the billing receipt. |
string (date-time) |
callbackUrl |
Represents a callback which we should
call in order to notify the client about a particular purchase state. |
string |
clientReferenceNumber |
A string value from client side to trace purchase in our system. This value is unique between client purchases. |
string |
createdAt |
When the purchase created? |
string (date-time) |
currency |
Represents the currency type. |
enum (IRR) |
description |
An optional client provided description for the purchase. |
string |
expirationDate |
When has the purchase been expired? |
string (date-time) |
fee |
Represents the Jibit fee for this purchase. |
integer (int64) |
feePaymentType |
Represents the payment type of purchase fee. |
enum (POST_PAID, PRE_PAID) |
hasContradiction |
Indicates whether the purchase had a contradiction or not. |
boolean |
initPayerIp |
The IP address of the user calling the payment URL generated by us. |
string |
netAmount |
Represents the net amount of purchase
that will be settled with the client. |
integer (int64) |
payerCardNumber |
Represents the user card number that the purchase is forced to do the transaction. |
string |
payerMobileNumber |
Represents the user mobile number. |
string |
payerNationalCode |
Represents the user national code that is used to check the owner of the PSP payer card. |
string |
pspCardOwner |
Represents the card owner name. |
string |
pspFailReason |
Represents the PSP fail reason. |
string |
pspFailReasons |
Represents the list of PSP fail reasons. |
< PspFailReason > array |
pspHashedCardNumber |
Hashed bank card number used to do the transaction. Provided by PSP. |
string |
pspMaskedCardNumber |
Masked bank card number used to do the transaction. |
string |
pspName |
Represents the PSP name which the purchase belongs to. |
string |
pspReferenceNumber |
Represents the PSP reference number. |
string |
pspRrn |
Represents the PSP Retrieval Reference Number, a key to uniquely identify a card transaction based on the ISO 8583 standard. |
string |
pspSettled |
Whether the PSP settled the payment. |
boolean |
pspSettledAt |
When the PSP settled the payment? |
string (date-time) |
pspTraceNumber |
Represents the PSP trace number. |
string |
purchaseId |
Represents the purchase identifier. |
integer (int64) |
purchaseIdStr |
Represents the purchase identifier as String to bypass deserialization issues in some programming languages e.x. Javascript and Typescript. |
string |
redirectPayerIp |
The IP address of the user reported by the PSP. |
string |
refundInquiryResult |
Refund Inquiry result from transferor. |
|
refundableAmount |
Represents the refundable amount. It
is equal to or less than |
integer (int64) |
refunded |
Whether the purchase is refunded. |
boolean |
resellerCode |
Represents the reseller code for this purchase. |
string |
settlementId |
Indicates the identifier of the
settlement which the purchase is settled by. |
integer (int64) |
shaparakFee |
Represents the Shaparak fee for this purchase. |
integer (int64) |
state |
Represents the simple purchase state. |
enum (EXPIRED, FAILED, IN_PROGRESS, MANUALLY_SUCCESS, READY_TO_VERIFY, REVERSED, SUCCESS, UNKNOWN) |
userIdentifier |
Identifies the user in the client system. |
string |
verifiedAt |
When was the payment verification
date? |
string (date-time) |
wage |
Represents the wage of purchase given by client. |
integer (int64) |
3.6. DetailedPurchaseHistoryDto
Name | Description | Schema |
---|---|---|
clientRefNum |
Represents the client reference
number. |
string |
createdAt |
Represents the creation time of this
purchase history, which indicates when purchase status got changed. |
string (date-time) |
newState |
Represents the simplified version of
purchase new state. |
enum (EXPIRED, FAILED, IN_PROGRESS, MANUALLY_SUCCESS, READY_TO_VERIFY, REVERSED, SUCCESS, UNKNOWN) |
purchaseId |
Represents the purchase identifier. |
integer (int64) |
3.7. DetailedSettlementDto
Name | Description | Schema |
---|---|---|
acceptorCode |
Represents the acceptor code. |
string |
affiliateFee |
Represents the reseller’s affiliate fee. |
integer (int64) |
amount |
Represents the settlement amount. |
integer (int64) |
createdAt |
When was the settlement created. |
string (date-time) |
currency |
Represents the currency type. |
enum (IRR) |
cutoff |
Cutoff time. |
|
directSettlement |
Represents whether settlement is direct settled. |
boolean |
fileName |
Represents the file name which was sent to shaparak. |
string |
iin |
Represents the iin. |
integer (int64) |
ledgerAccount |
Represents ledger account of client. |
string |
modifiedAt |
When was the settlement modified. |
string (date-time) |
paymentFacilitatorIban |
Represents the pf Iban. |
string |
resellerCode |
Represents the reseller code |
string |
settledAt |
When was the settlement settled. |
string (date-time) |
settlementIban |
Represents the settlement Iban. |
string |
settlementId |
Represents the settlement identifier. |
integer (int64) |
shaparakFailReason |
Represents the shaparak fail reason. |
enum (DATA_FORMAT_MISMATCH, DATA_LENGTH_MISMATCH, DUPLICATE_DATA, ERROR_ACCESSING_DATA, EXPIRED_REFERENCE, EXTERNAL_SERVICE_UNREACHABLE, GENERAL_EXTERNAL_SERVICE_ERROR, INCONSISTENT_DATA, INTERNAL_ERROR, INVALID_EXTERNAL_SERVICE_RESPONSE, MISSING_VALUE, NOT_ENOUGH_RESOURCES, NO_ACH_REF_NUM, OUT_OF_BOUNDS_DATA, REFERENCED_DATA_NOT_FOUND, UNKNOWN, UNKNOWN_DATA_PROVIDED) |
shaparakReferenceNumber |
Represents the shaparak reference number. |
string |
shaparakTrackingNumber |
Represents the shaparak tracking number. |
string |
shaparakTransactionId |
Represents the shaparak tracking id. |
string |
state |
Represents the settlement state. |
enum (EARLY_SETTLED, FAILED, IN_PROGRESS, OBSOLETE, SETTLED) |
terminalId |
Represents the terminal Id. |
string (uuid) |
wage |
Represents the settlement wage. |
integer (int64) |
3.8. GenerateTokenDto
Name | Description | Schema |
---|---|---|
apiKey |
Represents the api key of client. |
string |
secretKey |
Represents the secret key of
client. |
string |
3.9. HealthDto
Name | Description | Schema |
---|---|---|
pspStatusMap |
A map containing the health status of various PSP vendors. |
< string, enum (DOWN, NOT_IMPLEMENTED, UP) > map |
status |
The current health status of the
service. |
enum (DOWN, NOT_IMPLEMENTED, UP) |
3.10. IdPaginated«DetailedPurchaseHistoryDto»
Name | Description | Schema |
---|---|---|
elements |
The list of elements in the current page. |
< DetailedPurchaseHistoryDto > array |
hasNext |
Indicates if there is another page following the current one. |
boolean |
nextPageId |
The identifier for fetching the next
page of results. |
string |
size |
The number of elements in the current page. |
integer (int32) |
totalCount |
The total number of elements. If null, the total count was not calculated for faster response times. |
integer (int64) |
3.11. LocalTime
Type : object
3.12. Paginated«DetailedPurchaseDto»
Name | Description | Schema |
---|---|---|
elements |
The actual paginated elements. |
< DetailedPurchaseDto > array |
hasNext |
Can this page be followed by another page after it? |
boolean |
hasPrevious |
Is there a previous page for this page? |
boolean |
numberOfElements |
Total number of elements. |
integer (int64) |
pageNumber |
The current 1-index page number. |
integer (int32) |
size |
The size of current page. |
integer (int32) |
3.13. Paginated«DetailedSettlementDto»
Name | Description | Schema |
---|---|---|
elements |
The actual paginated elements. |
< DetailedSettlementDto > array |
hasNext |
Can this page be followed by another page after it? |
boolean |
hasPrevious |
Is there a previous page for this page? |
boolean |
numberOfElements |
Total number of elements. |
integer (int64) |
pageNumber |
The current 1-index page number. |
integer (int32) |
size |
The size of current page. |
integer (int32) |
3.14. PspFailReason
Name | Description | Schema |
---|---|---|
code |
Represents the Shaparak error code. Example: 54 |
integer (int32) |
description |
Represents a human-readable description of the error |
string |
pspError |
DEPRECATED. Use
|
string |
3.15. PurchaseCreationResult
Name | Description | Schema |
---|---|---|
affiliateFee |
Represents the affiliate fee of
client’s reseller. |
integer (int64) |
clientReferenceNumber |
Represents the reference number provided by client to trace the purchase in our system. The reference number between client purchases must be unique. |
string |
currency |
Represents the currency type. |
enum (IRR) |
fee |
Represents the Jibit fee of the
purchase. |
integer (int64) |
netAmount |
Represents the net amount of purchase
that will be settled with the client. |
integer (int64) |
pspSwitchingUrl |
The URL pointing to our PSP switching
web service. |
string |
purchaseId |
The identifier for the just created purchase. It is generated by our service. |
integer (int64) |
purchaseIdStr |
The identifier for the just created
purchase as String to bypass deserialization issues in some programming languages e.x. Javascript and
Typescript. |
string |
shaparakFee |
Represents the Shaparak fee of the purchase. |
integer (int64) |
3.16. RefreshTokenDto
Name | Description | Schema |
---|---|---|
refreshToken |
Represents the refresh token. Used to generate a new pair of access/refresh tokens for the client. |
string |
3.17. RefundActionDto
Name | Description | Schema |
---|---|---|
transferId |
This is the unique identifier of a
partial refund. |
string |
3.18. RefundPurchaseDto
Name | Description | Schema |
---|---|---|
amount |
The amount which the client want to refund (for partial refund). |
integer (int64) |
cancellable |
Whether to pend the refund request and perform it after one hour. |
boolean |
clientReferenceNumber |
Represents the reference number provided by client to trace the purchase in our system. |
string |
purchaseId |
Represents the purchase id. |
integer (int64) |
3.19. ReversePurchaseDto
Name | Description | Schema |
---|---|---|
clientReferenceNumber |
Represents the reference number provided by client to trace the purchase in our system. |
string |
purchaseId |
Represents the purchase id. |
integer (int64) |
3.20. ReverseResultDto
Name | Description | Schema |
---|---|---|
status |
It is the status of reverse. Possible
states are: |
enum (ALREADY_REVERSED, FAILED, NOT_REVERSIBLE, SUCCESSFUL, UNKNOWN) |
3.21. TerminalDto
Name | Description | Schema |
---|---|---|
clientCode |
Represents the unique code associated
with a client. Example: |
string |
clientName |
Represents the name of the client
associated with the terminal. |
string |
createdAt |
Represents the timestamp indicating
when the |
string (date-time) |
directSettlement |
Represents whether the terminal
supports direct settlement. |
boolean |
isAutoVerifyEnabled |
Indicates whether auto-verification is enabled for the terminal. |
boolean |
isCheckPayerMobileNumberActive |
Indicates whether the functionality
to check if the payer’s mobile number is active |
boolean |
isCheckPayerNationalCodeActive |
Indicates whether the functionality
to check if the payer’s national code is |
boolean |
isSingleCardFreezeActive |
Indicates whether the functionality
to freeze a single card number in IPG page |
boolean |
naturalId |
Represents the unique natural
identifier of a terminal. Example: |
string |
priority |
Represents the priority of the
terminal. |
integer (int32) |
pspMerchantNumber |
Represents the merchant number
associated with a specific PSP. |
string |
pspName |
Represents the name of payment
service provider (PSP) associated with the terminal. |
string |
pspTerminalId |
The unique identifier of the PSP
terminal. |
string |
type |
Represents the type of the terminal
in the system. |
enum (AUTO_SETTLING_PF, NORMAL, PAYMENT_FACILITATION) |
3.22. TerminalSwitchingDto
Name | Description | Schema |
---|---|---|
autoSwitching |
Determines whether terminal switching
is automatic or manual. |
boolean |
terminalIds |
A list of terminal natural IDs
required for terminal switching. |
< string > array |
3.23. TokenDto
Name | Description | Schema |
---|---|---|
accessToken |
Represents the new access token. |
string |
refreshToken |
Represents the new refresh token. |
string |
3.24. Transfer
Name | Description | Schema |
---|---|---|
amount |
integer (int64) |
|
bankTransferID |
string |
|
cancellable |
boolean |
|
createdAt |
string (date-time) |
|
currency |
string |
|
description |
string |
|
destination |
string |
|
destinationFirstName |
string |
|
destinationLastName |
string |
|
failReason |
string |
|
feeAmount |
integer (int64) |
|
feeCurrency |
string |
|
metadata |
string |
|
modifiedAt |
string (date-time) |
|
notifyURL |
string |
|
partialRefundIndex |
Represents the position of a partial
refund within a batch of refunds for a purchase. It is one-based, meaning it starts at 1. |
integer (int32) |
paymentID |
string |
|
refundId |
represents the purchase identifier of the refund. |
integer (int64) |
state |
State can have these following
values: |
enum (CANCELLED, CANCELLING, CORE_SUBMITTED, DESTINATION_IDENTIFIED, FAILED, FEE_COMPUTED, INITIALIZED, IN_PROGRESS, MANUALLY_FAILED, ON_HOLD, ON_HOLD_BALANCES_NOT_ENOUGH, ON_HOLD_WAIT_FOR_MANUAL_SUBMISSION, ON_HOLD_WAIT_FOR_VERIFY, RETRYING, TRANSFERRED) |
transferID |
string |
|
transferMode |
enum (ACH, NORMAL, RTGS) |
3.25. TransferorInquiryResult
Name | Description | Schema |
---|---|---|
batchID |
Represents the batch id. |
string |
refundedAmount |
integer (int64) |
|
transfers |
Represents the list of Transfers. |
< Transfer > array |
3.26. TransferorResult
Name | Description | Schema |
---|---|---|
batchId |
The batch id returned from transferor. |
string |
partialRefundIndex |
Represents the position of a partial
refund within a batch of refunds for a purchase. It is one-based, meaning it starts at 1. |
integer (int32) |
refundId |
represents the purchase identifier of the refund. |
integer (int64) |
transferId |
The transfer id returned from transferor. |
string |
3.27. VerificationResultDto
Name | Description | Schema |
---|---|---|
status |
It is the status of verification. |
enum (ALREADY_VERIFIED, FAILED, NOT_VERIFIABLE, SUCCESSFUL, UNKNOWN) |