Reporting API

Copy page

Copy page as Markdown for LLMs

Open in ChatGPT

Ask questions about this page

Open in Claude

Ask questions about this page

The Amazon Payment Services Reporting API enables merchants processing large volumes of e-commerce transactions to gain deep insights into transaction performance and behavior through comprehensive data mining capabilities. You can specify custom columns and apply filters to generate detailed reports with a query limit of 200,000 transactions per request.

The reporting process follows a two-step approach: first generate a report with your specified parameters, then download the generated report using the same merchant reference.

Generate Report

Create a custom report with specified columns, filters, and date ranges for your transaction data analysis.

Download Report

Retrieve your previously generated report data using the same merchant reference.

API Endpoints

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

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

Request Format

• Method: POST
• Content-Type: application/json
• Submission: Server-to-server HTTPS POST

1. Generate Report

Request Parameters

Parameter
query_command   String Max: 50 Required Query operations command for report generation. Value: GENERATE_REPORT Example. GENERATE_REPORT
access_code   String Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings. Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   String Max: 20 Required Unique merchant identifier assigned by Amazon Payment Services during account setup. Example. CycHZxVj
merchant_reference   String Max: 40 Required Unique reference for the report request. Must be unique per merchant. Alphanumeric characters, hyphens, underscores, and periods allowed. Example. XYZ9239-yu898
from_date   String Max: 30 Required Start date for report data filtering in ISO 8601 format with timezone. Example. 2024-01-01T00:00:00+03:00
to_date   String Max: 30 Required End date for report data filtering in ISO 8601 format with timezone. Example. 2024-01-31T23:59:59+03:00
columns   Array Max: 110 Required Array of column names to include in the generated report. See Columns Parameter section for available values. Example. ["fort_id", "amount", "currency", "status"]
signature   String Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
language   String Max: 2 Optional Response language for messages and descriptions. Values: en, ar Example. en
response_format   String Max: 4 Optional Response format for the API response. Default is JSON. Values: JSON, XML Example. JSON
filters   Array Optional Array of filter objects to narrow down report results. Each filter contains key-value pairs for specific criteria. Example. [{"key": "payment_option", "value": "VISA"}]

Check signature calculation section to learn how to calculate the signature.

Columns Parameter

The following table contains all the possible values you can include in your report response:

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 Amazon Payment Services 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 3D 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 message the Acquirer returns.
processor_response_code	The code the Processor 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.
reconciliation_reference	The reconciliation reference number (RRN)

Filters Parameter

Include the following parameters into "filters" parameter you will send to Amazon Payment Services:

Parameter	Type	Max Length	Description
key	Alphanumeric	110	The name of the column you want to filter. You can choose more than one. Values: Please refer to Key Parameter section Special chars: # ' \ / . _ - @ : Space
value	Alphanumeric	-	The value of the key you want to return in your response. It depends on the key you have chosen to return.

Key Parameter

The following table contains all the possible values of the "key" parameter:

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 Values: MASTERCARD, VISA, AMEX, SADAD, NAPS, KNET, MADA, MEEZA
channel	The Amazon Payment Services channel used to receive the authorization/purchase request. Possible Values:, Trusted, Merchant Page, Redirection, 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 Values: ECOMMERCE, RECURRING
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 3D Secure check was performed on a specific transaction. Otherwise, it will holds the value "no". Possible 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 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 Values: YES, NO
status	A transaction status 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 message the Acquirer returns.
processor_response_code	The code the Processor 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 Values: MASTERPASS, VISA_CHECKOUT, APPLE_PAY
reconciliation_reference	The reconciliation reference number (RRN)

Generate Report Request

{
  "query_command": "GENERATE_REPORT",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "XYZ9239-yu898",
  "from_date": "2024-01-01T00:00:00+03:00",
  "to_date": "2024-01-31T23:59:59+03:00",
  "columns": [
    "3ds_indicator",
    "acquirer_name",
    "acquirer_response_code",
    "amount",
    "authorization_code",
    "card_bin",
    "currency",
    "customer_ip",
    "customer_name",
    "fort_id",
    "merchant_reference",
    "operation",
    "order_date",
    "order_description",
    "payment_option",
    "response_code",
    "response_message",
    "status",
    "transaction_date"
  ],
  "language": "en",
  "response_format": "JSON",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
  "filters": [
    {
      "key": "payment_option",
      "value": "VISA"
    }
  ]
}

import requests

report_data = {
    "query_command": "GENERATE_REPORT",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "XYZ9239-yu898",
    "from_date": "2024-01-01T00:00:00+03:00",
    "to_date": "2024-01-31T23:59:59+03:00",
    "columns": [
        "3ds_indicator",
        "acquirer_name",
        "amount",
        "currency",
        "customer_name",
        "fort_id",
        "merchant_reference",
        "operation",
        "payment_option",
        "response_code",
        "status",
        "transaction_date"
    ],
    "language": "en",
    "response_format": "JSON",
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
    "filters": [
        {
            "key": "payment_option",
            "value": "VISA"
        }
    ]
}

response = requests.post(
    "https://sbpaymentservices.payfort.com/FortAPI/reportingApi",
    json=report_data,
    headers={"Content-Type": "application/json"}
)

result = response.json()
print(result)

<?php
$reportData = [
    "query_command" => "GENERATE_REPORT",
    "access_code" => "zx0IPmPy5jp1vAz8Kpg7",
    "merchant_identifier" => "CycHZxVj",
    "merchant_reference" => "XYZ9239-yu898",
    "from_date" => "2024-01-01T00:00:00+03:00",
    "to_date" => "2024-01-31T23:59:59+03:00",
    "columns" => [
        "3ds_indicator",
        "acquirer_name",
        "amount",
        "currency",
        "customer_name",
        "fort_id",
        "merchant_reference",
        "operation",
        "payment_option",
        "response_code",
        "status",
        "transaction_date"
    ],
    "language" => "en",
    "response_format" => "JSON",
    "signature" => "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
    "filters" => [
        [
            "key" => "payment_option",
            "value" => "VISA"
        ]
    ]
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://sbpaymentservices.payfort.com/FortAPI/reportingApi");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($reportData));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json"
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

curl -H "Content-Type: application/json" \
     -d '{
       "query_command": "GENERATE_REPORT",
       "access_code": "zx0IPmPy5jp1vAz8Kpg7",
       "merchant_identifier": "CycHZxVj",
       "merchant_reference": "XYZ9239-yu898",
       "from_date": "2024-01-01T00:00:00+03:00",
       "to_date": "2024-01-31T23:59:59+03:00",
       "columns": [
         "3ds_indicator",
         "acquirer_name",
         "acquirer_response_code",
         "amount",
         "authorization_code",
         "card_bin",
         "currency",
         "customer_ip",
         "customer_name",
         "fort_id",
         "merchant_reference",
         "operation",
         "order_date",
         "order_description",
         "payment_option",
         "response_code",
         "response_message",
         "status",
         "transaction_date"
       ],
       "language": "en",
       "response_format": "JSON",
       "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
       "filters": [
         {
           "key": "payment_option",
           "value": "VISA"
         }
       ]
     }' \
     https://sbpaymentservices.payfort.com/FortAPI/reportingApi

Generate Report Sample Response

{
  "query_command": "GENERATE_REPORT",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "XYZ9239-yu898",
  "from_date": "2024-01-01T00:00:00+03:00",
  "to_date": "2024-01-31T23:59:59+03:00",
  "response_format": "JSON",
  "signature": "521d32010a9988de86e16b49f6303985508d5f244784474da1184d457b53ded2",
  "language": "en",
  "response_message": "Success",
  "response_code": "56000",
  "status": "56"
}

Response Parameters

Parameter
query_command   String Max: 50 Query operations command for report generation. Value: GENERATE_REPORT Example. GENERATE_REPORT
access_code   String Max: 20 Merchant access code returned from the request. Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   String Max: 20 Merchant identifier returned from the request. Example. CycHZxVj
merchant_reference   String Max: 40 Unique reference for the report request returned from the request. Example. XYZ9239-yu898
from_date   String Max: 30 Start date for report data filtering returned from the request. Example. 2024-01-01T00:00:00+03:00
to_date   String Max: 30 End date for report data filtering returned from the request. Example. 2024-01-31T23:59:59+03:00
signature   String Max: 200 SHA-256 hash signature for response verification and integrity validation. Example. 521d32010a9988de86e16b49f6303985508d5f244784474da1184d457b53ded2
language   String Max: 2 Response language returned from the request. Values: en, ar Example. en
response_format   String Max: 4 Response format returned from the request. Values: JSON, XML Example. JSON
response_message   String Max: 150 Human-readable response description indicating the result of the report generation request. Example. Success
response_code   String Max: 5 Numeric response code indicating the result of the report generation request. Example. 56000
status   String Max: 2 Two-digit status code indicating the transaction state. Example. 56

2. Download Report

Request Parameters

Parameter
query_command   String Max: 50 Required Query operations command for report download. Value: DOWNLOAD_REPORT Example. DOWNLOAD_REPORT
access_code   String Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings. Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   String Max: 20 Required Unique merchant identifier assigned by Amazon Payment Services during account setup. Example. CycHZxVj
merchant_reference   String Max: 40 Required The same unique reference used in the generate report request. This links the download request to the previously generated report. Example. XYZ9239-yu898
signature   String Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a

You must use the exact same merchant_reference that was used in the Generate Report request. Using a different reference will result in a "Report not found" error.

Download Report Request

{
  "query_command": "DOWNLOAD_REPORT",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "XYZ9239-yu898",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
}

import requests

download_data = {
    "query_command": "DOWNLOAD_REPORT",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "XYZ9239-yu898",
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
}

response = requests.post(
    "https://sbpaymentservices.payfort.com/FortAPI/reportingApi",
    json=download_data,
    headers={"Content-Type": "application/json"}
)

result = response.json()
print(result)

<?php
$downloadData = [
    "query_command" => "DOWNLOAD_REPORT",
    "access_code" => "zx0IPmPy5jp1vAz8Kpg7",
    "merchant_identifier" => "CycHZxVj",
    "merchant_reference" => "XYZ9239-yu898",
    "signature" => "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://sbpaymentservices.payfort.com/FortAPI/reportingApi");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($downloadData));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json"
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

curl -X POST https://sbpaymentservices.payfort.com/FortAPI/reportingApi \
  -H "Content-Type: application/json" \
  -d '{
    "query_command": "DOWNLOAD_REPORT",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "XYZ9239-yu898",
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
  }'

Download Report Sample Response

[
  {
    "data_count": 2
  },
  [
    {
      "order_description": "iphone",
      "customer_ip": "2001:0002:6c::430",
      "eci": "ECOMMERCE",
      "merchant_reference": "XYZ9239-yu898",
      "currency": "USD",
      "geolocation_ip": "192.168.33.18",
      "amount": 1000,
      "payment_option": "VISA",
      "fort_id": "150701416400054912",
      "customer_email": "customer@amazon.com",
      "customer_name": "John Smith",
      "operation": "AUTHORIZATION"
    },
    {
      "order_description": "iphone",
      "customer_ip": "2001:0002:6c::430",
      "eci": "ECOMMERCE",
      "merchant_reference": "XYZ9239-yu898",
      "currency": "USD",
      "geolocation_ip": "192.168.33.18",
      "amount": 1000,
      "payment_option": "VISA",
      "fort_id": "150701415400054909",
      "customer_email": "customer@amazon.com",
      "customer_name": "John Smith",
      "operation": "AUTHORIZATION"
    }
  ]
]

Response Parameters

In case the generation of the report is not complete, the merchant will receive a message indicating that the generation of the report is still in progress with the response parameters below. The Merchant can attempt to download report later.

The following parameters will be returned in Amazon Payment Services' response:

Parameter
query_command   String Max: 50 Query operations command for report download. Value: DOWNLOAD_REPORT Example. DOWNLOAD_REPORT
access_code   String Max: 20 Merchant access code returned from the request. Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   String Max: 20 Merchant identifier returned from the request. Example. CycHZxVj
merchant_reference   String Max: 40 The merchant's unique reference for the report request returned from the request. Example. XYZ9239-yu898
signature   String Max: 200 SHA-256 hash signature for response verification and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
response_message   String Max: 150 Human-readable response description indicating the result of the report download request. Example. Success
response_code   String Max: 5 Numeric response code indicating the result of the report download request. Example. 56000
status   String Max: 2 Two-digit status code indicating the transaction state. Example. 56

Response Codes

For a complete list of response codes and their descriptions, please refer to our Error Codes Documentation.

If you prefer using your account dashboard, you can generate and download reports by navigating to the "Reports" section in your merchant portal. For more information, see our reports guide.