NAV Navbar
Logo
PHP cURL Java Python Ruby

Query Operations

A type of query that can be requested through our system, which includes the “Check Status” query.

Check Status

Check Status allows the Merchant to check the status of a specific order and the status of the latest operation performed on that order.

Check Status URLs

Test Environment URL:

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

Production Environment URL:

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

Parameters Submission Type

REST POST request using JSON.

Check Status - Request

(Please take a look at the Check Status Request Example on the right side of the page.)

Check Status Request Example

curl -H "Content-Type: application/json" -d
'{"query_command":"CHECK_STATUS","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":" XYZ9239-yu898 ","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a"}'
https://sbpaymentservices.payfort.com/FortAPI/paymentApi



error_reporting(E_ALL);
ini_set('display_errors', '1');

$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'query_command' => 'CHECK_STATUS',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
);

$ch = curl_init( $url );
# Setup request to send json via POST.
$data = json_encode($arrData);
curl_setopt( $ch, CURLOPT_POSTFIELDS, $data );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
# Return response instead of printing.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
# Send request.
$result = curl_exec($ch);
curl_close($ch);
# Print response.
echo "<pre>$result</pre>";


String jsonRequestString = "{\"query_command\" : \"CHECK_STATUS\" \"access_code\" : \"zx0IPmPy5jp1vAz8Kpg7\", \"merchant_identifier\" : \"CycHZxVj\","
        + "\"merchant_reference\" : \"XYZ9239-yu898\", \"language\" : \"en\", "
        + "\"signature\" : \"7cad05f0212ed933c9a5d5dffa31661acf2c827a\"}";

// Define and Initialize HttpClient
HttpClient httpClient = HttpClientBuilder.create().build();
// Intialize HttpPOST with FORT Payment services URL
HttpPost request = new HttpPost("https://sbpaymentservices.payfort.com/FortAPI/paymentApi");
// Setup Http POST entity with JSON String
StringEntity params = new StringEntity(jsonRequestString);
// Setup request type as JSON
request.addHeader("content-type", "application/json");
request.setEntity(params);
// Post request to FORT
HttpResponse response = httpClient.execute(request);
// Read response using StringBuilder
StringBuilder sb = new StringBuilder();
BufferedReader reader = new BufferedReader(new InputStreamReader(
    response.getEntity().getContent()), 65728);
String line = null;
while ((line = reader.readLine()) != null) {
  sb.append(line);
}
// Print response
System.out.println(sb.toString());

import urllib
import urllib2
import json

url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'query_command' : 'CHECK_STATUS',
'access_code' : 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' : 'CycHZxVj',
'merchant_reference' : 'XYZ9239-yu898',
'language' : 'en',
'signature' : '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
};

values = json.dumps(arrData)
data = urllib.urlencode(values)
req = urllib2.Request(url, data)
response = urllib2.urlopen(req)
page = response.read()
print page + '\n\n'

require 'json'
require 'net/http'
require 'net/https'
require 'uri'
require 'openssl'

arrData = {
'query_command' => 'CHECK_STATUS',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
};

arrData = arrData.to_json
uri = URI.parse("https://sbpaymentservices.payfort.com/FortAPI/paymentApi")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new("/v1.1/auth")
request.add_field('Content-Type', 'application/json')
request.body = arrData
response = http.request(request)

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

ATTRIBUTES Description
query_command
Alpha
Mandatory
max: 50		 The query operations command.
Possible/ expected values: CHECK_STATUS
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 order number.
Example: XYZ9239-yu898
Special characters: - _ .
language
Alpha
Mandatory
Max: 2		 The checkout page and messages language.
Possible/ expected values: en/ ar
signature
Alphanumeric
Mandatory
max: 200		 A string hashed using the Secure Hash Algorithm. Please refer to section Signature
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
fort_id
Numeric
Optional
Max: 20		 The order’s unique reference returned by our system.
Example: 149295435400084008

Check Status - Response

(Please take a look at the Check Status Example Response on the right side of the page.)

Check Status Response Example

{"query_command":"CHECK_STATUS","access_code":"s31bpM1ebfNnwqo","merchant_identifier":"FD1Ptq","merchant_reference":"141127176","language":"en","signature":"90f7092923c9eea8b0df6d509453a1791a36e2cd4a80eaef366e235b169a40e0","fort_id":"21722423333","response_message":"Success","response_code":"12000","status":"12","transaction_status":"12","transaction_code":"12000","transaction_message":"Success"}



{"query_command":"CHECK_STATUS","access_code":"s31bpM1ebfNnwqo","merchant_identifier":"FD1Ptq","merchant_reference":"141127176","language":"en","signature":"90f7092923c9eea8b0df6d509453a1791a36e2cd4a80eaef366e235b169a40e0","fort_id":"21722423333","response_message":"Success","response_code":"12000","status":"12","transaction_status":"12","transaction_code":"12000","transaction_message":"Success"}

{"query_command":"CHECK_STATUS","access_code":"s31bpM1ebfNnwqo","merchant_identifier":"FD1Ptq","merchant_reference":"141127176","language":"en","signature":"90f7092923c9eea8b0df6d509453a1791a36e2cd4a80eaef366e235b169a40e0","fort_id":"21722423333","response_message":"Success","response_code":"12000","status":"12","transaction_status":"12","transaction_code":"12000","transaction_message":"Success"}

{"query_command":"CHECK_STATUS","access_code":"s31bpM1ebfNnwqo","merchant_identifier":"FD1Ptq","merchant_reference":"141127176","language":"en","signature":"90f7092923c9eea8b0df6d509453a1791a36e2cd4a80eaef366e235b169a40e0","fort_id":"21722423333","response_message":"Success","response_code":"12000","status":"12","transaction_status":"12","transaction_code":"12000","transaction_message":"Success"}

{"query_command":"CHECK_STATUS","access_code":"s31bpM1ebfNnwqo","merchant_identifier":"FD1Ptq","merchant_reference":"141127176","language":"en","signature":"90f7092923c9eea8b0df6d509453a1791a36e2cd4a80eaef366e235b169a40e0","fort_id":"21722423333","response_message":"Success","response_code":"12000","status":"12","transaction_status":"12","transaction_code":"12000","transaction_message":"Success"}

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

ATTRIBUTES Description
query_command
Alpha
max: 50		 The query operations command.
Possible/ expected values: CHECK_STATUS
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 order number.
Example: XYZ9239-yu898
language
Alpha
Max: 2		 The checkout page and messages language.
Possible/ expected values: en/ ar
signature
Alphanumeric
Max: 200		 A string hashed using the Secure Hash Algorithm. Please refer to section Signature
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
fort_id
Numeric
Max: 20		 The order’s unique reference returned by our system.
Example: 149295435400084008
response_message
Alphanumeric
Max: 150		 Message description of the response code; it returns according to the request language.
Possible/ expected values: Please refer to section messages
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
transaction_status
Numeric
Max: 2		 The status of the last operation performed on a specific order.
Possible/ expected values: Please refer to section statuses
transaction_code
Numeric
Max: 5		 The message code returned for the last operation performed on a specific order.
Possible/ expected values: Please refer to section messages
transaction_message
Alphanumeric
Max: 150		 The message returned for the last operation performed on a specific order.
Example: Success
refunded_amount
Numeric
Max: 10		 The total refunded amount for the order.
Example: 10000
captured_amount
Numeric
Max: 10		 The total captured amount for the order.
Example: 10000
authorized_amount
Numeric
Max: 10		 The total authorized amount for the order.
Example: 10000

Services Activation

Services are activated for our Merchants by our back-office team. Once you open your Merchant account and click “Payment Stack” under the Services tab. The services provided by PayFort are:

Signature

The Signature is a parameter that holds the digital signature value calculated by the SHA algorithm. The digital signature is used to authenticate the sender and receiver of the message and allows the receiver to verify the integrity of the message.

Message Digest

Name Description
SHA Type The Secure Hash Algorithm is a family of cryptographic hash functions published by the National Institute of Standards as a US Federal information processing standard (FIPS) including: SHA-0, SHA-2, and SHA-3. Values: SHA-256, SHA 512, and SHA-128 (not recommended).
SHA Request Phrase This value is used when the Merchant generates the request signature. Values: Dynamic value defined by the Merchant.
SHA Response Phrase This value is used by our system to generate the response signature for the Merchant’s Request. Values: Dynamic value defined by the Merchant.

Signature Pattern

The below steps describe the signature pattern:

  1. Sort all PayFort requests parameters (both mandatory and optional) in an ascending alphabetical order based on the parameters names.

  2. Concatenate the parameter name with the value separated by ’=’ (param_name=param_value).

  3. Concatenate all the parameters directly without any separator. (param_name1=param_value1param_name2=param_value2).

  4. Add the Merchant’s Passphrase at the beginning and end of the parameters string. (REQUESTPHRASEparam_name1=param_value1param_name2=param_value2RE QUESTPHRASE).

  5. Use the SHA function to generate the SHA value of the resulted string depending on the type of SHA selected by the Merchant.

Create Signature Value

In this section, you can find examples on how to create the signature value for request and response messages. Please note that all values mentioned in the examples are fictitious.

The following is an example of the Request Parameters:

Below are the Merchant signature settings from the back-office:

After sorting the parameters and completing step 4 of the Signature Pattern, the result will be the following concatenated string:

After applying step 5 of the Signature Pattern, the result will be as follows:

The following is an example for the Merchant Page 2.0 request signature calculations:

Assume you have the below parameters included in the request of Merchant Page 2.0:

Below are the Merchant signature settings from the back-office:

The string to hash should be prepared for the above request is the following step 4 of the Signature Pattern:

After applying step 5 of the Signature Pattern, the result will be as follows:

PayFort Gateway includes the signature in the Response so you can check the integrity of the received data. You do this by calculating the secure hash using the above method, then comparing your calculation with the value you received from PayFort Gateway. If the values match, then you can be assured that we received the data you sent, and you received the data we sent.

FORT XML Response Builder

Through this section you can discover one of the FORT services that enables you to receive the FORT response in XML format.

Structure

The XML response builder results specifications are:
1. The root node name is ‘response’.
2. The FORT_PARAMETER of type “List” has a special tag name format; where the parent node tag name format is:
<FORT_PARAMETER + “_list”>
3. The list child nodes tag name’s is the name of the parameter name itself.

Sample Code

Transactions Response Codes

The Response code is made up of 5 digits; a combination of a 2-digit Status (Please see section statuses) and a 3-digit Message (Please see section messages).

Statuses

Status Code Description
00 Invalid Request.
01 Order Stored.
02 Authorization Success.
03 Authorization Failed.
04 Capture Success.
05 Capture failed.
06 Refund Success.
07 Refund Failed.
08 Authorization Voided Successfully.
09 Authorization Void Failed.
10 Incomplete.
11 Check status Failed.
12 Check status success.
13 Purchase Failure.
14 Purchase Success.
15 Uncertain Transaction.
17 Tokenization failed.
18 Tokenization success.
19 Transaction pending.
20 On hold.
21 SDK Token creation failure.
22 SDK Token creation success.
23 Failed to process Digital Wallet service.
24 Digital wallet order processed successfully.
27 Check card balance failed.
28 Check card balance success.
29 Redemption failed.
30 Redemption success.
31 Reverse Redemption transaction failed.
32 Reverse Redemption transaction success.
40 Transaction In review.
42 Currency conversion success.
43 Currency conversion failed.
46 Bill creation success.
47 Bill creation failed.
48 Generating invoice payment link success.
49 Generating invoice payment link failed.
50 Batch file upload successfully.
51 Upload batch file failed.
52 Token created successfully.
53 Token creation failed.
54 Get Tokens Success.
55 Get Tokens Failed.
56 Reporting Request Success.
57 Reporting Request Failed.
58 Token updated successfully.
59 Token updated failed.
62 Get Installment Plans Successfully.
63 Get Installment plans Failed.
66 Delete Token Success.
70 Get batch results successfully.
71 Get batch results failed.
72 Batch processing success.
73 Batch processing failed.
74 Bank transfer successfully.
75 Bank transfer failed.
76 Batch validation successfully.
77 Batch validation failed.

Messages

Message Code Message Value
000 Success.
001 Missing parameter.
002 Invalid parameter format.
003 Payment option is not available for this merchant’s account.
004 Invalid command.
005 Invalid amount.
006 Technical problem.
007 Duplicate order number.
008 Signature mismatch.
009 Invalid merchant identifier.
010 Invalid access code.
011 Order not saved.
012 Card expired.
013 Invalid currency.
014 Inactive payment option.
015 Inactive merchant account.
016 Invalid card number.
017 Operation not allowed by the acquirer.
018 Operation not allowed by processor.
019 Inactive acquirer.
020 Processor is inactive.
021 Payment option deactivated by acquirer.
023 Currency not accepted by acquirer.
024 Currency not accepted by processor.
025 Processor integration settings are missing.
026 Acquirer integration settings are missing.
027 Invalid extra parameters.
029 Insufficient funds.
030 Authentication failed.
031 Invalid issuer.
032 Invalid parameter length.
033 Parameter value not allowed.
034 Operation not allowed.
035 Order created successfully.
036 Order not found.
037 Missing return URL.
038 Token service inactive.
039 No active payment option found.
040 Invalid transaction source.
042 Operation amount exceeds the authorized amount.
043 Inactive Operation.
044 Token name does not exist.
046 Channel is not configured for the selected payment option.
047 Order already processed.
048 Operation amount exceeds captured amount.
049 Operation not valid for this payment option.
050 Merchant per transaction limit exceeded.
051 Technical error.
052 Consumer is not in OLP database.
053 Merchant is not found in OLP Engine DB.
054 Transaction cannot be processed at this moment.
055 OLP ID Alias is not valid. Please contact your bank.
056 OLP ID Alias does not exist. Please enter a valid OLP ID Alias.
057 Transaction amount exceeds the daily transaction limit.
058 Transaction amount exceeds the per transaction limit.
059 Merchant Name and SADAD Merchant ID do not match.
060 The entered OLP password is incorrect. Please provide a valid password.
062 Token has been created.
063 Token has been updated.
064 3-D Secure check requested.
065 Transaction waiting for customer’s action.
066 Merchant reference already exists.
067 Dynamic Descriptor not configured for selected payment option.
068 SDK service is inactive.
069 Mapping not found for the given error code.
070 device_id mismatch.
071 Failed to initiate connection.
072 Transaction has been cancelled by the consumer.
073 Invalid request format.
074 Transaction failed.
075 Transaction failed.
076 Transaction not found in OLP.
077 Error transaction code not found.
078 Failed to check fraud screen.
079 Transaction challenged by fraud rules.
080 Invalid payment option.
082 Inactive fraud service.
083 Unexpected user behavior.
084 Transaction amount is either bigger than maximum or less than minimum amount accepted for the selected plan.
086 Installment plan is not configured for Merchant account.
087 Card BIN does not match accepted issuer bank.
088 Token name was not created for this transaction.
089 Failed to retrieve digital wallet details.
090 Transaction in review.
092 Invalid issuer code.
093 service inactive.
094 Invalid Plan Code.
095 Inactive Issuer.
096 Inactive Plan.
097 Operation not allowed for service.
098 Invalid or expired call_id.
099 Failed to execute service.
100 Invalid expiry date.
101 Bill number not found.
102 Apple Pay order has been expired.
103 Duplicate subscription ID.
104 No plans valid for request.
105 Invalid bank code.
106 Inactive bank.
107 Invalid transfer_date.
110 Contradicting parameters, please refer to the integration guide.
111 Service not applicable for payment option.
112 Service not applicable for payment operation.
113 Service not applicable for e-commerce indicator.
114 Token already exist.
115 Expired invoice payment link.
116 Inactive notification type.
117 Invoice payment link already processed.
118 Order bounced.
119 Request dropped.
120 Payment link terms and conditions not found.
121 Card number is not verified.
122 Invalid date interval.
123 You have exceeded the maximum number of attempts.
124 Account successfully created.
125 Invoice already paid.
126 Duplicate invoice ID.
127 Merchant reference is not generated yet.
128 The generated report is still pending, you can’t download it now.
129 “Downloaded report” queue is full. Wait till its empty again.
134 Your search results have exceeded the maximum number of records.
136 The Batch file validation is failed.
137 Invalid Batch file execution date.
138 The Batch file still under validation.
140 The Batch file still under processing.
141 The Batch reference does not exist.
142 The Batch file header is invalid.
144 Invalid Batch file.
146 The Batch reference is already exist.
147 The Batch process request has been received.
148 Batch file will be processed.
149 Payment link request id not found.
150 Payment link is already open.
151 3ds_id does not exist.
152 3Ds verification doesn’t match the request details.
154 You have reached the maximum number of upload retries.
155 The upload retries is not configured.
662 Operation not allowed. The specified order is not confirmed yet.
666 Transaction declined.
773 Transaction closed.
777 The transaction has been processed, but failed to receive confirmation.
778 Session timed-out.
779 Transformation error.
780 Transaction number transformation error.
781 Message or response code transformation error.
783 Installments service inactive.
784 Transaction still processing you can’t make another transaction.
785 Transaction blocked by fraud check.
787 Failed to authenticate the user.
788 Invalid bill number.
789 Expired bill number.
790 Invalid bill type code.

Security Settings

Security Settings are configurations to the Merchant account. The Security Settings differ based on the Merchant Account. The validation takes place based on the settings pertaining to each Merchant Account.

Security Settings Configuration

To configure your security settings, do the following:

  1. Select “Security Settings” under the Integration Settings tab.
  2. Click “Generate” to generate your Access Code.
  3. Select the SHA Type from the available drop-down list.
  4. Enter the SHA Request Phrase and the SHA Response Phrase.
  5. Enter the Origin IP or the Origin URL.
  6. Click “Save Changes”.
PHP cURL Java Python Ruby