NAV Navbar
Logo

Reporting API

This service allows Merchants to generate a customized report via FORT API. Merchants can specify the columns to be included and filters, then download the generated report. The Merchant is allowed to use this service once daily on production environment, the report is limited to 200,000 transactions.

Report Builder URLs

Test Environment URL:

https://sbpaymentservices.payfort.com/FortAPI/reportingApi

Production Environment URL:

https://paymentservices.payfort.com/FortAPI/reportingApi

Parameters Submission Type

REST POST request using JSON.

How it Works

1. The Merchant submits “Generate report” request. This request allows the merchant to generate specify the filters and columns included in the downloaded report.
2. The FORT returns the “Generate Report” response.
3. The Merchant submits the “download report:” request using the same merchant reference used to generate the report.

Generate Report - Request

Include the following parameters in the Request you will send to PayFort:

ATTRIBUTES Description
query_command
Alpha
Mandatory
max: 50
Query operations command.
Possible/ expected values: GENERATE_REPORT
Special characters: _
access_code
Alphanumeric
Mandatory
max: 20
Merchant account Access Code.
Example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier
Alphanumeric
Mandatory
max: 20
FORT Merchant Account identifier.
Example: CycHZxVj
merchant_reference
Alphanumeric
Mandatory
max: 40
The Merchant’s unique reference for a specific request.
Example: XYZ9239-yu898
Special characters: _ - .
from_date
Alphanumeric
Mandatory
max: 30
Query parameter to filter from a specific date.
Example: 2017-01-01T14:36:55+03:00
Special characters: + - :
to_date
Alphanumeric
Mandatory
max: 30
Query parameter to filter the results till a specific date.
Example: 2017-06-28T14:36:55+03:00
Special characters: + - :
columns
List
Mandatory
max: 110
The columns you want to appear in your report.
Possible/ expected values: (Please refer to section column parameters).
Special characters: _
signature
Alphanumeric
Mandatory
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
language
Alpha
Optional
max: 2
The checkout page and messages language.
Possible/ expected values: en / ar
response_format
Alpha
Optional
max: 4
The FORT response format; weather its JSON or XML. *The default response format is “JSON”.
Possible/ expected values:
- JSON
- XML
filters
List
Optional
max: 10
The filters the merchant wants to use to filter the generated report results.
possible/ expected values: (Please refer to section filters parameters).

Columns Parameter

The following table contains all the possible values you want to revert in your response, you can choose any of them:

Value Description
fort_id The order’s unique reference returned by our system.
merchant_reference The Merchant’s unique order number.
authorization_code The authorization code returned from the 3rd party responsible for processing the transaction.
customer_name The Customer’s name.
customer_ip The customer’s IP address; where the Merchant sends as part of the authorization/ purchase request.
geolocation_ip The card for the Customer’s computer.
customer_email The Customer’s email; where the Merchant sends with the authorization/purchase request.
acquirer_name The name of the Acquirer.
payment_option The payment option use to process the authorization/ purchase request.
channel The FORT channel used to receive the authorization/purchase request.
transaction_date The date of the transaction.
card_number The card number used to process the transaction.
expiry_date The card’s expiry date.
card_holder_name The cardholder’s name.
amount The transaction’s amount.
currency The currency of the transaction’s amount in ISO code 3.
card_bin The bank identification number (BIN); which is the initial four to eight numbers that appear on a credit card.
eci The E-commerce indicator associated with the transactions authorization/ purchase request.
operation The operation type (authorization, purchase, void authorization, capture, and refund)
token_name The Token associated with the card used to process the transaction.
3ds_indicator This indicator will hold the value “yes” in case 3-D Secure check was performed on a specific transaction. Otherwise, it will holds the value “no”.
fraud_indicator This indicator will hold the value “yes” in case fraud check was performed on a specific transaction. Otherwise, it will holds the value “no”.
installments_indicator This indicator will hold the value “yes” in case installments service was applied on a specific transaction. Otherwise, it will holds the value “no”.
status A two-digit numeric value that indicates the status of the transaction.
response_code Carries the value of our system’s response.
response_message The Message description of the response code. It returns according to the request language.
third_party_message The message retrieved from the third party.
third_party_code The code retrieved from the third party.
order_date The creation date of the order.
order_description The description of the order provided by the merchant.
acquirer_mid The Acquirer Merchant identifier.
acquirer_response_code The code the Acquirer returns.
acquirer_response_message The code the Acquirer returns.
processor_response_code The code the Acquirer returns.
sadad_olp SADAD Online Payment ID Alias. The value that SADAD’s Customer provides to process SADAD order.
sadad_transaction_id The identifier returned by SADAD for a specific SADAD transaction.
payment_link_id Payment link unique identifier.
Invoice_id The identification for a specific subscription service.
digital_wallet The buyer’s digital wallet.

Filters Parameter

Include the following parameters into “filters” parameter you will send to PayFort:

ATTRIBUTES Description
key
Alphanumeric
max: 110
The name of the column you want to filter. You can choose more than one.
Possible/ expected values: (Please refer to section Key parameter).
Special characters: # ' \ / . _ - @ : Space
value
Alphanumeric
max: -
The value of the key you want to revert in your response. It depends on the key you have chosen to revert.

Key Parameter

The following table contains all the possible values of the “key” parameter, you can choose any of them:

Key Description & Possible Values
fort_id The order’s unique reference returned by our system.
merchant_reference The Merchant’s unique order number.
authorization_code The authorization code returned from the 3rd party responsible for processing the transaction.
customer_name The Customer’s name.
customer_ip The customer’s IP address; where the Merchant sends as part of the authorization/ purchase request.
geolocation_ip The card for the Customer’s computer.
customer_email The Customer’s email; where the Merchant sends with the authorization/purchase request.
acquirer_name The name of the Acquirer.
payment_option The payment option use to process the authorization/ purchase request.
Possible/ Expected Values:
- MASTERCARD
- VISA
- AMEX
- SADAD
- NAPS
- KNET
- MADA
- MEEZA
channel The FORT channel used to receive the authorization/purchase request.
Possible/ Expected Values:
- MOTO
- Trusted
- Merchant Page
- Redirection
- eTerminal
- Recurring
transaction_date The date of the transaction.
card_number The card number used to process the transaction.
expiry_date The card’s expiry date.
card_holder_name The cardholder’s name.
amount The transaction’s amount.
currency The currency of the transaction’s amount in ISO code 3.
card_bin The bank identification number (BIN); which is the initial four to eight numbers that appear on a credit card.
eci The E-commerce indicator associated with the transactions authorization/ purchase request.
Possible/ Expected Values:
- ECOMMERCE
- RECURRING
- MOTO
operation The operation type (authorization, purchase, void authorization, capture, and refund).
token_name The Token associated with the card used to process the transaction.
3ds_indicator This indicator will hold the value “yes” in case 3-D Secure check was performed on a specific transaction. Otherwise, it will holds the value “no”.
Possible/ Expected Values:
- YES
- NO
fraud_indicator This indicator will hold the value “yes” in case fraud check was performed on a specific transaction. Otherwise, it will holds the value “no”.
Possible/ Expected Values:
- YES
- NO
installments_indicator This indicator will hold the value “yes” in case installments service was applied on a specific transaction. Otherwise, it will holds the value “no”.
Possible/ Expected Values:
- YES
- NO
status A two-digit numeric value that indicates the status of the transaction.
response_code Carries the value of our system’s response.
response_message The Message description of the response code. It returns according to the request language.
third_party_message The message retrieved from the third party.
third_party_code The code retrieved from the third party.
order_date The creation date of the order.
order_description The description of the order provided by the merchant.
acquirer_mid The Acquirer Merchant identifier.
acquirer_response_code The code the Acquirer returns.
acquirer_response_message The code the Acquirer returns.
processor_response_code The code the Acquirer returns.
sadad_olp SADAD Online Payment ID Alias. The value that SADAD’s Customer provides to process SADAD order.
sadad_transaction_id The identifier returned by SADAD for a specific SADAD transaction.
payment_link_id Payment link unique identifier.
Invoice_id The identification for a specific subscription service.
digital_wallet The buyer’s digital wallet.
Possible/ Expected Values:
- MASTERPASS
- VISA_CHECKOUT
- APPLE_PAY

Generate Report Request Example

Generate Report - Response

The following parameters will be returned in PayFort’s Response:

ATTRIBUTES Description
query_command
Alpha
max: 50
Query operations command.
Possible/ expected values: GENERATE_REPORT
access_code
Alphanumeric
max: 20
Merchant account Access Code.
Example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier
Alphanumeric
max: 20
FORT Merchant Account identifier.
Example: CycHZxVj
merchant_reference
Alphanumeric
max: 40
The Merchant’s unique reference for a specific request.
Example: XYZ9239-yu898
from_date
Alphanumeric
Mandatory
max: 30
Query parameter to filter from a specific date.
Example: 2017-01-01T14:36:55+03:00
to_date
Alphanumeric
Mandatory
max: 30
Query parameter to filter the results till a specific date.
Example: 2017-06-28T14:36:55+03:00
signature
Alphanumeric
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
language
Alpha
max: 2
The checkout page and messages language.
Possible/ expected values: en / ar
response_format
Alpha
Max: 4
The FORT response format; weather its JSON or XML. *The default response format is “JSON”.
Possible/ expected values:
- JSON
- XML
response_message
Alphanumeric
max: 150
Message description of the response code. It returns according to the request language.
Example: Insufficient Funds
response_code
Numeric
Max: 5
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages.
Example: 56000
status
Numeric
max: 2
A two-digit numeric value that indicates the status of the transaction
Possible/ expected values: (Please refer to section statuses).

Generate Report “JSON” Response Example

Generate Report “XML” Response Example

Download Report - Request

Include the following parameters in the Request you will send to PayFort:

ATTRIBUTES Description
query_command
Alpha
Mandatory
max: 50
Query operations command.
Possible/ expected values: DOWNLOAD_REPORT
Special characters: _
access_code
Alphanumeric
Mandatory
max: 20
Access Code.
Example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier
Alphanumeric
Mandatory
max: 20
The ID of the Merchant.
Example: CycHZxVj
merchant_reference
Alphanumeric
Mandatory
max: 40
The Merchant’s unique number. *Please, use the same merchant reference you used in the “generate report” request.
Example: XYZ9239-yu898
signature
Alphanumeric
Mandatory
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a

Download Report Request Example

Download Report - Response

The following parameters will be returned in PayFort’s Response:

ATTRIBUTES Description
query_command
Alpha
max: 50
Query operations command.
Possible/ expected values: DOWNLOAD_REPORT
access_code
Alphanumeric
max: 20
Access Code.
Example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier
Alphanumeric
max: 20
The ID of the Merchant.
Example: CycHZxVj
merchant_reference
Alphanumeric
max: 40
The Merchant’s unique reference for a specific request.
Example: XYZ9239-yu898
signature
Alphanumeric
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
response_message
Alphanumeric
max: 150
Message description of the response code. It returns according to the request language.
Example: Insufficient Funds
response_code
Numeric
Max: 5
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages.
Example: 56000
status
Numeric
max: 2
A two-digit numeric value that indicates the status of the transaction
Possible/ expected values: (Please refer to section statuses).

Download Report “JSON” Response Example

Download Report “XML” Response Example

Reporting Pagination API

This service allows Merchants to specify the number of pages via FORT API. The Merchant will receive back specified pages based on the search criteria. The Merchant is allowed to search for 20,000 transactions per each request.

Reporting Pagination API URLs

Test Environment URL:

https://sbpaymentservices.payfort.com/FortAPI/reportingApi

Production Environment URL:

https://paymentservices.payfort.com/FortAPI/reportingApi

Parameters Submission Type

REST POST request using JSON.

How it Works

  1. The Merchant submits “Get Report” request. This request allows the Merchant to specify the number of pages via FORT API; where he sends the page size (the number of records he wants to retrieve in each request) and the start index (the record to start retrieve records from).

  2. The FORT returns the “Get Report” response including the records the Merchant requested for.

Reporting Pagination API - Request

Include the following parameters in the Request you will send to PayFort:

ATTRIBUTES Description
query_command
Alpha
Mandatory
max: 50
Query operations command.
Possible/ expected values: GET_REPORT
Special characters: _
access_code
Alphanumeric
Mandatory
max: 20
Access code.
Example: zx0IPmPy5jp1vAz
merchant_identifier
Alphanumeric
Mandatory
max: 20
The ID of the Merchant.
Example: CycHZxVj
from_date
Alphanumeric
Mandatory
max: 30
Query parameter to filter from a specific date.
Example: 2017-01-01T14:36:55+03:00
Special characters: + - :
to_date
Alphanumeric
Mandatory
max: 30
Query parameter to filter the results till a specific date.
Example: 2017-06-28T14:36:55+03:00
Special characters: + - :
columns
List
Mandatory
max: 110
The columns the merchant wants to include in the generated report.
Possible/ expected values: (Please refer to section columns parameters).
Special characters: _
page_size
Numeric
Mandatory
max: 2
The number of records each request. *The maximum page size is 50 records per page.
Example: 10
start_index
Numeric
Mandatory
max: 5
From where you want to start getting the records.
Example: 19000
signature
Alphanumeric
Mandatory
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
language
Alpha
Optional
max: 2
The checkout page and messages language.
Possible/ expected values: en / ar
response_format
Alpha
Optional
max: 4
The FORT response format; weather its JSON or XML. *The default response format is “JSON”.
Possible/ expected values:
- JSON
- XML
filters
List
Optional
max: 10
The filters the merchant wants to use to filter the generated report results.
Possible/ expected values: (Please refer to section filters parameters).

Columns Parameters

The following table contains all the possible values you want to revert in your response, you can choose any of them:

Value Description
fort_id The order’s unique reference returned by our system.
merchant_reference The Merchant’s unique order number.
authorization_code The authorization code returned from the 3rd party responsible for processing the transaction.
customer_name The Customer’s name.
customer_ip The customer’s IP address; where the Merchant sends as part of the authorization/ purchase request.
geolocation_ip The card for the Customer’s computer.
customer_email The Customer’s email; where the Merchant sends with the authorization/purchase request.
acquirer_name The name of the Acquirer.
payment_option The payment option use to process the authorization/ purchase request.
channel The FORT channel used to receive the authorization/purchase request.
transaction_date The date of the transaction.
card_number The card number used to process the transaction.
expiry_date The card’s expiry date.
card_holder_name The cardholder’s name.
amount The transaction’s amount.
currency The currency of the transaction’s amount in ISO code 3.
card_bin The bank identification number (BIN); which is the initial four to eight numbers that appear on a credit card.
eci The E-commerce indicator associated with the transactions authorization/ purchase request.
operation The operation type (authorization, purchase, void authorization, capture, and refund)
token_name The Token associated with the card used to process the transaction.
3ds_indicator This indicator will hold the value “yes” in case 3-D Secure check was performed on a specific transaction. Otherwise, it will holds the value “no”.
fraud_indicator This indicator will hold the value “yes” in case fraud check was performed on a specific transaction. Otherwise, it will holds the value “no”.
installments_indicator This indicator will hold the value “yes” in case installments service was applied on a specific transaction. Otherwise, it will holds the value “no”.
status A two-digit numeric value that indicates the status of the transaction.
response_code Carries the value of our system’s response.
response_message The Message description of the response code. It returns according to the request language.
third_party_message The message retrieved from the third party.
third_party_code The code retrieved from the third party.
order_date The creation date of the order.
order_description The description of the order provided by the merchant.
acquirer_mid The Acquirer Merchant identifier.
acquirer_response_code The code the Acquirer returns.
sadad_olp SADAD Online Payment ID Alias. The value that SADAD’s Customer provides to process SADAD order.
sadad_transaction_id The identifier returned by SADAD for a specific SADAD transaction.
payment_link_id Payment link unique identifier.
Invoice_id The identification for a specific subscription service.
digital_wallet The buyer’s digital wallet.

Filters Parameter

Include the following parameters into “filters” parameter you will send to PayFort:

ATTRIBUTES Description
key
Alphanumeric
max: 110
The name of the column you want to filter. You can choose more than one.
Possible/ expected values: (Please refer to section Key parameter).
Special characters: # ' \ / . _ - @ : Space
value
Alphanumeric
max: -
The value of the key you want to revert in your response. It depends on the key you have chosen to revert.

Key Parameters

The following table contains all the possible values of the “key” parameter, you can choose any of them:

Key Description & Possible Values
fort_id The order’s unique reference returned by our system.
merchant_reference The Merchant’s unique order number.
authorization_code The authorization code returned from the 3rd party responsible for processing the transaction.
customer_name The Customer’s name.
customer_ip The customer’s IP address; where the Merchant sends as part of the authorization/ purchase request.
geolocation_ip The card for the Customer’s computer.
customer_email The Customer’s email; where the Merchant sends with the authorization/purchase request.
acquirer_name The name of the Acquirer.
payment_option The payment option use to process the authorization/ purchase request.
Possible/ Expected Values:
- MASTERCARD
- VISA
- AMEX
- SADAD
- NAPS
- KNET
- MADA
- MEEZA
channel The FORT channel used to receive the authorization/purchase request.
Possible/ Expected Values:
- MOTO
- Trusted
- Merchant Page
- Redirection
- eTerminal
- Recurring
transaction_date The date of the transaction.
card_number The card number used to process the transaction.
expiry_date The card’s expiry date.
card_holder_name The cardholder’s name.
amount The transaction’s amount.
currency The currency of the transaction’s amount in ISO code 3.
card_bin The bank identification number (BIN); which is the initial four to eight numbers that appear on a credit card.
eci The E-commerce indicator associated with the transactions authorization/ purchase request.
Possible/ Expected Values:
- ECOMMERCE
- RECURRING
- MOTO
operation The operation type (authorization, purchase, void authorization, capture, and refund).
token_name The Token associated with the card used to process the transaction.
3ds_indicator This indicator will hold the value “yes” in case 3-D Secure check was performed on a specific transaction. Otherwise, it will holds the value “no”.
Possible/ Expected Values:
- YES
- NO
fraud_indicator This indicator will hold the value “yes” in case fraud check was performed on a specific transaction. Otherwise, it will holds the value “no”.
Possible/ Expected Values:
- YES
- NO
installments_indicator This indicator will hold the value “yes” in case installments service was applied on a specific transaction. Otherwise, it will holds the value “no”.
Possible/ Expected Values:
- YES
- NO
status A two-digit numeric value that indicates the status of the transaction.
response_code Carries the value of our system’s response.
response_message The Message description of the response code. It returns according to the request language.
third_party_message The message retrieved from the third party.
third_party_code The code retrieved from the third party.
order_date The creation date of the order.
order_description The description of the order provided by the merchant.
acquirer_mid The Acquirer Merchant identifier.
acquirer_response_code The code the Acquirer returns.
sadad_olp SADAD Online Payment ID Alias. The value that SADAD’s Customer provides to process SADAD order.
sadad_transaction_id The identifier returned by SADAD for a specific SADAD transaction.
payment_link_id Payment link unique identifier.
Invoice_id The identification for a specific subscription service.
digital_wallet The buyer’s digital wallet.
Possible/ Expected Values:
- MASTERPASS
- VISA_CHECKOUT
- APPLE_PAY

Get Report Request Example

Reporting Pagination API - Response

The following parameters will be returned in PayFort’s Response:

ATTRIBUTES Description
query_command
Alpha
max: 50
Query operations command.
Possible/ expected values: GET_REPORT
access_code
Alphanumeric
max: 20
Access code.
Example: zx0IPmPy5jp1vAz
merchant_identifier
Alphanumeric
max: 20
The ID of the Merchant.
Example: CycHZxVj
from_date
Alphanumeric
max: 30
Query parameter to filter from a specific date.
Example: 2017-01-01T14:36:55+03:00
Special characters: + - :
to_date
Alphanumeric
max: 30
Query parameter to filter the results till a specific date.
Example: 2017-06-28T14:36:55+03:00
Special characters: + - :
page_size
Numeric
max: 2
The number of records each request. *The maximum page size is 50 records per page.
Example: 10
start_index
Numeric
max: 5
From where you want to start getting the records.
Example: 19000
signature
Alphanumeric
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
transactions
List
max: -
Records you have in your account. They are retrieved according to your request.
transactions_count
Numeric
max: 5
The total number of records you have in your account.
Example: 1913
language
Alpha
max: 2
The checkout page and messages language.
Possible/ expected values: en / ar
response_format
Alpha
max: 4
The FORT response format; weather its JSON or XML. *The default response format is “JSON”.
Possible/ expected values:
- JSON
- XML
response_message
Alphanumeric
max: 150
Message description of the response code. It returns according to the request language.
Example: Insufficient Funds
response_code
Numeric
Max: 5
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages.
Example: 20064
status
Numeric
max: 2
A two-digit numeric value that indicates the status of the transaction
Possible/ expected values: (Please refer to section statuses).

Get Report “JSON” Response Example

Get Report “XML” Response Example