NAV Navbar
Logo
PHP Python Ruby Java cURL

Before Starting the Integration section in the API:

Step 1: Access your test account
You have to make sure that you get access to a test account, it’s a full test environment allow you to simulate and process simulation transactions. You can contact support@payfort.com to get your test account.

Step 2: make sure that you are using the correct integration type
Before building the integration, you need to make sure that you are selecting and using the proper parameters in the API calls as per the required integration type.

All the mandatory parameters mentioned in every section in the API documentation.

Step 3: Create the transaction request
Process a valid API request depends on transaction parameters included, you need to check the documentation and read every parameter possible values in order to reduce the errors in processing the transaction.

Step 4: Process the transaction response
After each payment processed, PayFort returns the transaction’s response on the URL configured in your account under Technical Settings channel configuration.

You can find more details in the API documentation section Transaction Feedback Implementation.

You need to validate the response parameters returned on this URL by calculating the signature for the response parameters using the SHA Response Phrase configured in your account under Security Settings.

Step 5: Test and Go Live
You can use our testing cards to test your integration and simulate your test cases.

PayFort requires to test your integration before going live to verify the integration and make sure it’s implemented properly.

Redirection

Authorization and Purchase

Operations that help the Merchant to complete the payment process. The Authorization operation hold an amount from the Customer’s credit card account for a period of time until the Merchant capture or void the transaction. If no capture or void was processed during this period, the transaction will be voided automatically. In Purchase you will send one single request in order to authorize and capture the transaction amount.
We offer the Merchant to Redirect the Customer from his website to PayFort’s gateway page to fill out his credit card details during these operations.

Authorization/ Purchase URLs

Test Environment URL:

https://sbcheckout.payfort.com/FortAPI/paymentPage

Production Environment URL:

https://checkout.payfort.com/FortAPI/paymentPage

Parameters Submission Type

HTTPs Form Post Request.

Authorization/ Purchase - Request

Please take a look at the Authorization/ Purchase Request Example on the right side of the page.

Authorization/ Purchase Request Example

$requestParams = array(
'command' => 'AUTHORIZATION',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'amount' => '10000',
'currency' => 'AED',
'language' => 'en',
'customer_email' => 'test@payfort.com',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
);


$redirectUrl = 'https://sbcheckout.payfort.com/FortAPI/paymentPage';
echo "<html xmlns='http://www.w3.org/1999/xhtml'>\n<head></head>\n<body>\n";
echo "<form action='$redirectUrl' method='post' name='frm'>\n";
foreach ($requestParams as $a => $b) {
    echo "\t<input type='hidden' name='".htmlentities($a)."' value='".htmlentities($b)."'>\n";
}
echo "\t<script type='text/javascript'>\n";
echo "\t\tdocument.frm.submit();\n";
echo "\t</script>\n";
echo "</form>\n</body>\n</html>";
import cgi

requestParams = {
'command' => 'AUTHORIZATION',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'amount' => '10000',
'currency' => 'AED',
'language' => 'en',
'customer_email' => 'test@payfort.com',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
};


redirectUrl = 'https://sbcheckout.payfort.com/FortAPI/paymentPage';
print "<html xmlns='http://www.w3.org/1999/xhtml'>\n<head></head>\n<body>\n";
print "<form action='redirectUrl' method='post' name='frm'>\n";
for (slug, title) in requestParams.items():
    print "\t<input type='hidden' name='"+ cgi.escape(slug)+"' value='"+ cgi.escape(title)+"'>\n";

print "</form>";
print "\t<script type='text/javascript'>\n";
print "\t\tdocument.frm.submit();\n";
print "\t</script>\n";
print "\n</body>\n</html>";
require 'cgi'
requestParams = {
'command' => 'AUTHORIZATION',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'amount' => '10000',
'currency' => 'AED',
'language' => 'en',
'customer_email' => 'test@payfort.com',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
};
requestParams.each {|key, value|
  puts key +value ;
}

redirectUrl = 'https://sbcheckout.payfort.com/FortAPI/paymentPage';
puts "<html xmlns='http://www.w3.org/1999/xhtml'>\n<head></head>\n<body>\n";
puts "<form action='redirectUrl' method='post' name='frm'>\n";
requestParams.each {|key, value|
    puts "\t<input type='hidden' name='"+ CGI.escapeHTML(key)+"' value='"+ CGI.escapeHTML(value)+"'>\n";
}
puts "</form>\n";
puts "\t<script type='text/javascript'>\n";
puts "\t\tdocument.frm.submit();\n";
puts "\t</script>\n";
puts "</body>\n</html>";

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

ATTRIBUTES Description
command
Alpha
Mandatory
Max: 20
A command.
Possible/ expected values: AUTHORIZATION, PURCHASE
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: - _ .
amount
Numeric
Mandatory
Max: 10
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount check the note after this table.
Example: 10000
currency
Alpha
Mandatory
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Mandatory
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
customer_email
Alphanumeric
Mandatory
Max: 254
The customer’s email.
Example: customer1@domain.com
Special characters: _ - . @ +
signature
Alphanumeric
Mandatory
Max: 200
A string hashed using the Secure Hash Algorithm. Please refer to section Signature
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
token_name
Alphanumeric
Optional
Max: 100
The Token received from the Tokenization process.
Example: Op9Vmp
Special characters: . @ - _
payment_option
Alpha
Optional
Max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
- SADAD (for Purchase operations only)
- NAPS (for Purchase operations only)
- KNET(for Purchase operations only)
- MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document
- MEEZA (for Purchase operations and ECOMMERCE eci only)
sadad_olp
Alphanumeric
Optional
Max: 12
SADAD Online Payment ID Alias. The merchant sends this value if the OLP ID is collected on the merchant checkout.
Example: SABBP2P_UAT2
Special characters: @ . _
eci
Alpha
Optional
Max: 16
E-commerce indicator. *MOTO and E-commerce indicator clickable in VISA, MASTERCARD and AMEX.
Possible/ expected values:
- ECOMMERCE
- MOTO
order_description
Alphanumeric
Optional
Max: 150
It holds the description of the order.
Example: iPhone 6-S
Special characters: ' / . _ - # : $ Space
customer_ip
Alphanumeric
Optional
max: 45
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
Special characters: . :
customer_name
Alpha
Optional
Max: 40
The customer’s name.
Example: John Smith
Special characters: _ \ / - . ' Space
merchant_extra
Alphanumeric
Optional
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra1
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra2
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra3
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra4
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra5
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
remember_me
Alpha
Optional
Max: 2
This parameter provides you with an indication to whether to save this token for the user based on the user selection.
Possible/ expected values: NO
phone_number
Alphanumeric
Optional
max: 19
The customer’s phone number.
Example: 00962797219966
Special characters: + - ( ) Space
settlement_reference
Alphanumeric
Optional
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898
Special characters: - _ .
return_url
Alphanumeric
Optional
Max: 400
The URL of the Merchant’s page that will be displayed to the customer when the order is processed.
Example: http://www.merchant.com
Special characters: $ ! = ? # & - _ / : .

Authorization/ Purchase - Response

(Please take a look at the Authorization/ Purchase Response Example on the right side of the page.)

Authorization/ Purchase Response Example

{"command":"AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","customer_email":"test@payfort.com","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","payment_option":"VISA","eci":"ECOMMERCE","order_description":"iPhone6-S","customer_ip":"192.178.1.10","customer_name":"John","response_message":"Success","response_code":"20064","status":"04","card_holder_name":"John Smith","expiry_date":"2105","card_number":"400555******0001"}
{"command":"AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","customer_email":"test@payfort.com","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","payment_option":"VISA","eci":"ECOMMERCE","order_description":"iPhone6-S","customer_ip":"192.178.1.10","customer_name":"John","response_message":"Success","response_code":"20064","status":"04","card_holder_name":"John Smith","expiry_date":"2105","card_number":"400555******0001"}
{"command":"AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","customer_email":"test@payfort.com","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","payment_option":"VISA","eci":"ECOMMERCE","order_description":"iPhone6-S","customer_ip":"192.178.1.10","customer_name":"John","response_message":"Success","response_code":"20064","status":"04","card_holder_name":"John Smith","expiry_date":"2105","card_number":"400555******0001"}

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

ATTRIBUTES Description
command
Alpha
Max: 20
A command.
Possible/ expected values: AUTHORIZATION, PURCHASE
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
amount
Numeric
Max: 10
The transaction’s amount.
Example: 10000
currency
Alpha
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
customer_email
Alphanumeric
Max: 254
The customer’s email.
Example: customer1@domain.com
signature
Alphanumeric
Max: 200
A string hashed using the Secure Hash Algorithm. Please refer to section Signature
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
token_name
Alphanumeric
max: 100
The Token received from the Tokenization process.
Example: Op9Vmp
fort_id
Numeric
Max: 20
The order’s unique reference returned by our system.
Example: 149295435400084008
payment_option
Alpha
Max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
- SADAD (for Purchase operations only)
- NAPS (for Purchase operations only)
- KNET(for Purchase operations only)
- MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document
- MEEZA (for Purchase operations and ECOMMERCE eci only)
sadad_olp
Alphanumeric
Max: 12
SADAD Online Payment ID Alias. The merchant sends this value if the OLP ID is collected on the merchant checkout.
Example: SABBP2P_UAT2
knet_ref_number
Alphanmeric
Max: 100
The reference number of KNET. *In case of sending KNET payment option.
Example: 832911577112
third_party_transaction_number
Alphanmeric
Max: 50
The third party transaction number. *In case of sending KNET payment option.
Example: 9547069411183290
eci
Alpha
Max: 16
The E-commerce indicator.
Possible/ expected values:
- ECOMMERCE
- MOTO
order_description
Alphanumeric
Max: 150
It holds the description of the order.
Example: iPhone 6-S
customer_ip
Alphanumeric
max: 45
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
customer_name
Alpha
Max: 40
The customer’s name.
Example: John Smith
merchant_extra
Alphanumeric
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra1
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra2
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra3
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra4
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra5
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
authorization_code
Alphanumeric
Max: 100
The authorization code returned from the 3rd party.
Example: P1000000000000372136
response_message
Alphanumeric
Max: 150
The 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
card_holder_name
Alpha
Max: 50
The card holder name.
Example: John Smith
expiry_date
Numeric
Max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
Max: 19
The masked credit card’s number.
Only the MEEZA payment option takes 19 digits card number.
*AMEX payment option takes 15 digits card number.
*Otherwise, they take 16 digits card number.
Example: 400555
*****0001
remember_me
Alpha
Max: 2
This parameter provides you with an indication to whether to save this token for the user based on the user selection.
Possible/ expected values: NO
phone_number
Alphanumeric
max: 19
The customer’s phone number.
Example: 00962797219966
settlement_reference
Alphanumeric
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898

How to add the Tokenization service on the Redirection channel?

The Tokenization service is applicable to be integrated through the Redirection Channel through the below steps:
1. The Customer enables the remember_me option displayed in the payment page.
2. Processes the first PURCHASE/ AUTHORIZATION payment successfully.
3. The Merchant will receive a token_name in the response. This token_name should be considered as a permanent token name, and it can be used in the future customer’s payments by submitting the token_name in the next PURCHASE/ AUTHORIZATION payment.

If the Customer wants to update/ delete his card, you should check Update Token section.

Maintenance Operations

Maintenance Operations are operations exist on the authorized amount ONLY. The following sections illustrate the maintenance operations:

Capture Operation

An operation that allows the Merchant to capture the authorized amount to his account. The capture could be partial or full depends on the Merchant requirements and request.

Capture Operation 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.

Capture Operation - Request

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

Capture Request Example


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

$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';

$arrData = array(
'command' => 'CAPTURE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'amount' => '10000',
'currency' => 'AED',
'language' => 'en',
'fort_id' => '149295435400084008',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
);


$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>";

curl -H "Content-Type: application/json" -d '{"command":"CAPTURE","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","fort_id":"149295435400084008","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone6-S"}'
https://sbpaymentservices.payfort.com/FortAPI/paymentApi

import urllib
import urllib2
import json

url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command':'CAPTURE',
'access_code':'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier':'CycHZxVj',
'merchant_reference':'XYZ9239-yu898',
'amount':'10000',
'currency':'AED',
'language':'en',
'fort_id':'149295435400084008',
'signature':'7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description':'iPhone 6-S',
};

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

String jsonRequestString = "{\"command\" : \"CAPTURE\" , \"access_code\" : \"zx0IPmPy5jp1vAz8Kpg7\", \"merchant_identifier\" : \"CycHZxVj\", " + "\"merchant_reference\" : \"XYZ9239-yu898\", \"amount\" : \"10000\", \"currency\" : \"AED\"," + "\"language\" : \"en\", \"fort_id\" : \"149295435400084008\", " + "\"signature\" : \"7cad05f0212ed933c9a5d5dffa31661acf2c827a\", \"order_description\" : \"iPhone 6-S\"}";

// 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());

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

arrData = {
'command' => 'CAPTURE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'amount' => '10000',
'currency' => 'AED',
'language' => 'en',
'fort_id' => '149295435400084008',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
};

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
command
Alpha
Mandatory
Max: 20
A command.
Possible/ expected values: CAPTURE
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. * You have the option to send “fort_id” instead of “merchant_reference”, or you can send them BOTH.
Example: XYZ9239-yu898
Special characters: - _ .
amount
Numeric
Mandatory
Max: 10
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 10000
currency
Alpha
Mandatory
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
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
order_description
Alphanumeric
Optional
Max: 150
It holds the description of the order.
Example: iPhone 6-S
Special characters: ' / . _ - # : $ Space

Capture Operation - Response

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

Capture Response Example

{"command":"CAPTURE","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","fort_id":"149295435400084008","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}
{"command":"CAPTURE","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","fort_id":"149295435400084008","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}
{"command":"CAPTURE","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","fort_id":"149295435400084008","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}
{"command":"CAPTURE","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","fort_id":"149295435400084008","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}
{"command":"CAPTURE","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","fort_id":"149295435400084008","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}

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

ATTRIBUTES Description
command
Alpha
Max: 20
A command.
Possible/ expected values: CAPTURE
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
amount
Numeric
Max: 10
The transaction’s amount.
Example: 10000
currency
Alpha
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
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
order_description
Alphanumeric
Max: 150
It holds the description of the order.
Example: iPhone 6-S
response_message
Alphanumeric
Max: 150
The 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

Void-Authorization Operation

An operation that allows the Merchant to cancel the payment request AFTER being authorized.

Void-Authorization Operation 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.

Void-Authorization Operation - Request

(Please take a look at the Void-Authorization Request Example on the right side of the page.)

Void-Authorization Request Example


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

$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';

$arrData = array(
'command' => 'VOID_AUTHORIZATION',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
);


$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>";


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

String jsonRequestString = "{\"command\" : \"VOID_AUTHORIZATION\" , "
      + "\"access_code\" : \"zx0IPmPy5jp1vAz8Kpg7\", \"merchant_identifier\" : \"CycHZxVj\", \"merchant_reference\" : \"XYZ9239-yu898\","
      + "\"language\" : \"en\", \"signature\" : \"7cad05f0212ed933c9a5d5dffa31661acf2c827a\", "
      + "\"order_description\" : \"iPhone 6-S\"}";

// 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 = {
'command':'VOID_AUTHORIZATION',
'access_code':'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier':'CycHZxVj',
'merchant_reference':'XYZ9239-yu898',
'language':'en',
'signature':'7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description':'iPhone 6-S',
};

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 = {
'command' => 'VOID_AUTHORIZATION',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
};

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
command
Alpha
Mandatory
Max: 20
Command.
Possible/ expected values: VOID_AUTHORIZATION.
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. *You have the option to send “fort_id” instead of “merchant_reference”, or you can send them BOTH.
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
order_description
Alphanumeric
Optional
Max: 150
It holds the description of the order.
Example: iPhone 6-S
Special characters: ' / . _ - # : $ Space

Void-Authorization Operation - Response

(Please take a look at the Void-Authorization Response Example on the right side of the page.)

Void-Authorization Response Example


{"command":"VOID_AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone6-S","fort_id":"149295435400084008","response_message":"Success","response_code":"20064","status":"04"}


{"command":"VOID_AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone6-S","fort_id":"149295435400084008","response_message":"Success","response_code":"20064","status":"04"}


{"command":"VOID_AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone6-S","fort_id":"149295435400084008","response_message":"Success","response_code":"20064","status":"04"}


{"command":"VOID_AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone6-S","fort_id":"149295435400084008","response_message":"Success","response_code":"20064","status":"04"}


{"command":"VOID_AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone6-S","fort_id":"149295435400084008","response_message":"Success","response_code":"20064","status":"04"}

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

ATTRIBUTES Description
command
Alpha
Max: 20
Command.
Possible/ expected values: VOID_AUTHORIZATION
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
order_description
Alphanumeric
Max: 150
It holds the description of the order.
Example: iPhone 6-S
response_message
Alphanumeric
Max: 150
The 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

Refund Operation

An operation that returns the entire amount of a transaction or part of it AFTER being captured.

Refund Operation 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.

Refund Operation - Request

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

Refund Request Example


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

$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';

$arrData = array(
'command' => 'REFUND',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => ' XYZ9239-yu898',
'amount' => '10000',
'currency' => 'AED',  
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'fort_id' => '149295435400084008',
'order_description' => 'iPhone 6-S',
);


$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>";

curl -H "Content-Type: application/json" -d
'{"command":"REFUND","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","order_description":"iPhone6-S"}'
https://sbpaymentservices.payfort.com/FortAPI/paymentApi

import urllib
import urllib2
import json

url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command':'REFUND',
'access_code':'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier':'CycHZxVj',
'merchant_reference':' XYZ9239-yu898',
'amount':'10000',
'currency':'AED',  
'language':'en',
'signature':'7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'fort_id':'149295435400084008',
'order_description':'iPhone 6-S',
};

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

String jsonRequestString = "{\"command\" : \"REFUND\" , \"access_code\" : \"zx0IPmPy5jp1vAz8Kpg7\", \"merchant_identifier\" : \"CycHZxVj\", "
       + "\"merchant_reference\" : \"XYZ9239-yu898\", \"amount\" : \"10000\", \"currency\" : \"AED\","
       + "\"language\" : \"en\", \"signature\" : \"7cad05f0212ed933c9a5d5dffa31661acf2c827a\", "
       + "\"fort_id\" : \"149295435400084008\", \"order_description\" : \"iPhone 6-S\"}";

// 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());

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

arrData = {
'command' => 'REFUND',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => ' XYZ9239-yu898',
'amount' => '10000',
'currency' => 'AED',  
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'fort_id' => '149295435400084008',
'order_description' => 'iPhone 6-S',
};

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
command
Alpha
Mandatory
Max: 20
A command.
Possible/ expected values: REFUND
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. *You have the option to send “fort_id” instead of “merchant_reference”, or you can send them BOTH.
Example: XYZ9239-yu898
Special characters: - _ .
amount
Numeric
Mandatory
Max: 10
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 10000
currency
Alpha
Mandatory
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
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
maintenance_reference
Alphanumeric
Optional
Max: 200
The Refund’s unique order number. * You will be able to retry on the refund request using the same maintenance reference if the refund transaction was declined.
Example: customer123
fort_id
Numeric
Optional
Max: 20
The order’s unique reference returned by our system.
Example: 149295435400084008
order_description
Alphanumeric
Optional
Max: 150
It holds the description of the order.
Example: iPhone 6-S
Special characters: ' / . _ - # : $ Space

Refund Operation - Response

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

Refund Response Example

{"command":"REFUND","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}
{"command":"REFUND","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}
{"command":"REFUND","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}
{"command":"REFUND","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}
{"command":"REFUND","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}

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

ATTRIBUTES Description
command
Alpha
Max: 20
Command.
Possible/ expected values: REFUND
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
amount
Numeric
Max: 10
The transaction’s amount.
Example: 10000
currency
Alpha
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
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
maintenance_reference
Alphanumeric
Max: 200
The Refund’s unique order number. * You will be able to retry on the refund request using the same maintenance reference if the refund transaction was declined.
Example: customer123
fort_id
Numeric
Max: 20
The order’s unique reference returned by our system.
Example: 149295435400084008
order_description
Alphanumeric
Max: 150
It holds the description of the order.
Example: iPhone 6-S
response_message
Alphanumeric
Max: 150
The 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

Merchant Page

This integration type allows Merchants to accept the Customer’s payments in their websites by collecting their credit card information using a PayFort inline frame (iframe). PayFort processes the transaction and returns the results back to the Merchants through invisible redirection.

Features

How It Works - Overview

1. The Merchant page (payment details form) will appear to your Customer encapsulated inside an iframe that has the same look and feel of your website.

2. We then receive the payment details and send you confirmation to complete the transaction.

Integration Flow

1. The Customer begins the checkout process on the Merchant’s website.

2. The Merchant requests to display the Merchant Page (payment details form) encapsulated inside an iframe which has been themed as the Merchant website. Then the Customer enters the card’s details on the Merchant page.

3. PayFort checks the card details.

4. PayFort creates a token for the Customer transaction and sends it to the Merchant.

5. The Merchant then sends a JSON request along with the token to PayFort.

6. In case the Merchant receives from PayFort a 3-D Secure URL “3ds_url”, and response indicating that a 3Ds check is required:

    a. The Merchant redirects the Customer to the ACS to check his card enrollment.

    b. The Customer enters authentication data on the ACS platform.

    c. The ACS performs authentication of the Customer’s data and sends the authentication results to PayFort.

7. PayFort completes the operation based on the 3-D Secure response and returns the response to the Merchant.

8. PayFort sends the payment results to the Merchant.

Merchant Page URLs

Test Environment URL:

https://sbcheckout.payfort.com/FortAPI/paymentPage

Production Environment URL:

https://checkout.payfort.com/FortAPI/paymentPage

Parameters Submission Type

HTTPs Form Post Request

Merchant Page - Request

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

ATTRIBUTES Description
service_command
Alpha
Mandatory
max: 20
Command.
Possible/ expected values: TOKENIZATION
access_code
Alphanumeric
Mandatory
Max: 20
Access code.
Example: zx0IPmPy5jp1vAz
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
token_name
Alphanumeric
Optional
Max: 100
The token received from the Tokenization process.
Example: Op9Vmp
Special characters: . @ - _
return_url
Alphanumeric
Optional
Max: 400
The URL of the Merchant’s page to be displayed to the customer when the order is processed.
Example: http://www.merchant.com
Special characters: $ ! = ? # & - _ / : .

Merchant Page - Response

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

ATTRIBUTES Description
service_command
Alpha
Max: 20
Command.
Possible/ expected values: TOKENIZATION
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: 20
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
token_name
Alphanumeric
max: 100
The token received from the Tokenization process.
Example: Op9Vmp
expiry_date
Numeric
Max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
Max: 19
The masked credit card’s number.
Only the MEEZA payment option takes 19 digits card number.
*AMEX payment option takes 15 digits card number.
*Otherwise, they take 16 digits card number.
Example: 400555
*****0001
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).
card_bin
Numeric
Max: 8
The first 6 digits of the card number.*If the card number for MEEZA was of length 19 then the card bin will be the first 8 digits.
Example: 478773
return_url
Alphanumeric
Max: 400
The URL of the Merchant’s page to be displayed to the customer when the order is processed.
Example: http://www.merchant.com

Merchant Page Operations

Merchant Page Operations 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.

Operations - Request

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

ATTRIBUTES Description
command
Alpha
Mandatory
max: 20
Command.
Possible/ expected values: AUTHORIZATION, PURCHASE
access_code
Alphanumeric
Mandatory
Max: 20
The ID of the Merchant.
Example: zx0IPmPy5jp1vAz
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: - _ .
amount
Numeric
Mandatory
Max: 10
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 10000
currency
Alpha
Mandatory
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Mandatory
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
customer_email
Alphanumeric
Mandatory
Max: 254
The customer’s email.
Example: customer@domain.com
Special characters: _ - . @ +
customer_ip
Alphanumeric
Mandatory
max: 45
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
Special characters: . :
token_name
Alphanumeric
Mandatory
Max: 100
The Token received from the Tokenization process.
Example: Op9Vmp
Special characters: _ - . @
signature
Alphanumeric
Mandatory
Max: 200
A string hashed using the Secure Hash Algorithm. Please refer to section Signature
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
payment_option
Alpha
Optional
Max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
- MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document
- MEEZA (for Purchase operations and ECOMMERCE eci only)
eci
Alpha
Optional
Max: 16
Ecommerce indicator.
Possible/ expected values:
- ECOMMERCE
- MOTO
- RECCURING
order_description
Alphanumeric
Optional
Max: 150
It holds the description of the order.
Example: iPhone 6-S
Special characters: ' / . _ - # : $ Space
card_security_code
Numeric
Optional
Max: 4
A security code for the card. * Only AMEX accepts card security code of 4 digits.
Example: 123
customer_name
Alpha
Optional
Max: 40
The customer’s name.
Example: John Smith
Special characters: _ \ / - . ' Space
merchant_extra
Alphanumeric
Optional
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra1
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra2
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra3
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra4
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra5
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
remember_me
Alpha
Optional
Max: 3
This parameter provides you with an indication to whether to save this token for the user based on the user selection. *The Tokenization service MUST be activated in order to be able to send “remember_me” parameter.
Possible/ expected values: -YES -NO
phone_number
Alphanumeric
Optional
max: 19
The customer’s phone number.
Example: 00962797219966
Special characters: + - ( ) Space
settlement_reference
Alphanumeric
Optional
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898
Special characters: - _ .
return_url
Alphanumeric
Optional
Max: 400
The URL of the Merchant’s page to be displayed to the customer when the order is processed.
Example: http://www.merchant.com
Special characters: $ ! = ? # & - _ / : .

Operations - Response

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

ATTRIBUTES Description
command
Alpha
max: 20
Command.
Possible/ expected values: AUTHORIZATION, PURCHASE
access_code
Alphanumeric
Max: 20
The ID of the Merchant.
Example: zx0IPmPy5jp1vAz
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
amount
Numeric
Max: 10
The transaction’s amount.
Example: 10000
currency
Alpha
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
customer_email
Alphanumeric
Max: 254
The customer’s email.
Example: customer1@domain.com
customer_ip
Alphanumeric
max: 45
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
token_name
Alphanumeric
max: 100
The Token received from the Tokenization process.
Example: COp9Vmp
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
payment_option
Alpha
Max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
- MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document
- MEEZA (for Purchase operations and ECOMMERCE eci only)
eci
Alpha
Max: 16
Ecommerce indicator.
Possible/ expected values:
- ECOMMERCE
- MOTO
- RECCURING
order_description
Alphanumeric
Max: 150
A description of the order.
Example: iPhone 6-S
authorization_code
Alphanumeric
Max: 100
The authorization code returned from the 3rd party.
Example: P1000000000000372136
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
customer_name
Alpha
Max: 40
The customer’s name.
Example: John Smith
merchant_extra
Alphanumeric
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra1
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra2
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra3
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra4
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra5
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
expiry_date
Numeric
Max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
Max: 19
The masked credit card’s number.
Only the MEEZA payment option takes 19 digits card number.
*AMEX payment option takes 15 digits card number.
*Otherwise, they take 16 digits card number.
Example: 400555
*****0001
status
Numeric
Max: 2
A two-digit numeric value that indicates the status of the transaction.
Possible/ expected values: Please refer to section statuses
card_holder_name
Alpha
Max: 50
The card holder name.
Example: John Smith
3ds_url
Alphanumeric
Max: 300
The URL where the Merchant redirects a customer whose card is 3-D Secure for authentication.
Example: http://www.3dsecure.com
remember_me
Alpha
Max: 3
This parameter provides you with an indication to whether to save this token for the user based on the user selection.
Possible/ expected values: -YES -NO
phone_number
Alphanumeric
max: 19
The customer’s phone number.
Example: 00962797219966
settlement_reference
Alphanumeric
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898

How to add the Tokenization service on the Merchant Page channel?

The Tokenization service is applicable to be integrated through the Merchant Page Channel through the below steps:
1. The Customer processes the first PURCHASE/ AUTHORIZATION payment successfully.
2. The Merchant will receive a token_name in the response. This token_name should be considered as a permanent token name, and it can be used in the future customer’s payments by submitting the token_name in the next PURCHASE/ AUTHORIZATION payment with card_security_code parameter.
3. No need to open the Merchant Page to fill all the card details again in the next checkouts.

If the Customer wants to update/ delete his card, you should check Update Token section.

Merchant Page Customization

This is a list with all customizable CSS classes on the basic merchant page:

Merchant Page 2.0

This type of integration allows the Merchant to develop his own payment form that collects the card details. The card details are sent directly to PayFort and substituted with Token. The Merchant uses the Token created to complete the transaction.

Features

How It Works - Overview

1. The Merchant develops the form that collects the card details (credit card number, expiry date, CVV), and sends the request to PayFort.
2. PayFort receives the payment details and returns the response which includes the Token to the Merchant.
3. The Merchant use it to complete the Authorization or Purchase operation.

Integration Flow

1. The Customer begins the checkout process on the Merchant’s website.

2. The Merchant displays the form he developed to collect the card’s details. Then the Customer enters the card’s details on the Merchant page.

3. PayFort validates the card format.

4. PayFort creates a token for the card details and sends it back to the Merchant.

5. The Merchant stores the Token and proceeds with the transaction.

6. The Merchant sends a payment request along with the Token to PayFort.

7. PayFort sends the Merchant the 3-D Secure URL, and response indicating that a check is required:

    a. The Merchant redirects the Customer to check his card enrollment.
    b. The Customer enters authentication data.
    c. 3-D Secure authentication is completed and PayFort receives the authentication results.

8. PayFort completes the operation based on the 3-D Secure response and returns the response to the Merchant.

9. The payment results are displayed to the Customer.

Merchant Page 2.0 URLs

Test Environment URL:

https://sbcheckout.PayFort.com/FortAPI/paymentPage

Production Environment URL:

https://checkout.PayFort.com/FortAPI/paymentPage

Parameters Submission Type

HTTPs Form Post Request.

Merchant Page 2.0 - Request

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

ATTRIBUTES Description
service_command
Alpha
Mandatory
max: 20
Command.
Possible/ expected values: TOKENIZATION
access_code
Alphanumeric
Mandatory
Max: 20
Access code.
Example: zx0IPmPy5jp1vAz
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
expiry_date
Numeric
Mandatory
Max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
Mandatory
Max: 19
The clear credit card’s number.
*Only the MEEZA payment option takes 19 digits card number.
*AMEX payment option takes 15 digits card number.
*Otherwise, they take 16 digits card number.
Example: 4005550000000001
card_security_code
Numeric
Mandatory
Max: 4
A security code for the card. * Only AMEX accepts card security code of 4 digits.
Example: 123
signature
Alphanumeric
Mandatory
Max: 200
A string hashed using the Secure Hash Algorithm. Please refer to section Signature
*Please don’t include the following parameters in calculating the signature if you are using Merchant Page 2.0 tokenization request: card_security_code, card number, expiry_date, card_holder_name, remember_me
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
token_name
Alphanumeric
Optional
Max: 100
The Token received from the Tokenization process.
Example: Op9Vmp
Special characters: . @ - _
card_holder_name
Alpha
Optional
max: 50
The card holder name.
Example: John Smith
Special characters: ' - .
remember_me
Alpha
Optional
Max: 3
This parameter provides you with an indication to whether to save this token for the user based on the user selection.
Possible/ expected values: -YES -NO
return_url
Alphanumeric
Optional
Max: 400
The URL of the Merchant’s page to be displayed to the customer when the order is processed.
Example: http://www.merchant.com
Special characters: $ ! = ? # & - _ / : .

Merchant Page 2.0 - Response

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

ATTRIBUTES Description
service_command
Alpha
Max: 20
Command.
Possible/ expected values: TOKENIZATION
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
expiry_date
Numeric
Max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
Max: 19
The masked credit card’s number.
Only the MEEZA payment option takes 19 digits card number.
*AMEX payment option takes 15 digits card number.
*Otherwise, they take 16 digits card number.
Example: 400555
*****0001
signature
Alphanumeric
Max: 200
A string hashed using the Secure Hash Algorithm. Please refer to section Signature
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
token_name
Alphanumeric
max: 100
The Token received from the Tokenization process.
Example: COp9Vmp
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).
card_bin
Numeric
Max: 8
The first 6 digits of the card number.*If the card number for MEEZA was of length 19 then the card bin will be the first 8 digits.
Example: 478773
card_holder_name
Alpha
Max: 50
The card holder name.
Example: John Smith
remember_me
Alpha
Max: 3
This parameter provides you with an indication to whether to save this token for the user based on the user selection.
Possible/ expected values: - YES, - NO
return_url
Alphanumeric
Max: 400
The URL of the Merchant’s page to be displayed to the customer when the order is processed.
Example: http://www.merchant.com

Merchant Page 2.0 Operations

Merchant Page 2.0 Operations 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.

Operations - Request

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

ATTRIBUTES Description
command
Alpha
Mandatory
max: 20
Command.
Possible/ expected values: AUTHORIZATION, PURCHASE
access_code
Alphanumeric
Mandatory
Max: 20
Access code.
Example: zx0IPmPy5jp1vAz
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: - _ .
amount
Numeric
Mandatory
Max: 10
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 10000
currency
Alpha
Mandatory
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Mandatory
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
customer_email
Alphanumeric
Mandatory
Max: 254
The customer’s email.
Example: customer@domain.com
Special characters: _ - . @ +
customer_ip
Alphanumeric
Mandatory
max: 45
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
Special characters: . :
token_name
Alphanumeric
Mandatory
Max: 100
The Token received from the Tokenization process.
Example: Op9Vmp
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
payment_option
Alpha
Optional
Max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
- MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document
- MEEZA (for Purchase operations and ECOMMERCE eci only)
eci
Alpha
Optional
Max: 16
Ecommerce indicator.
Possible/ expected values:
- ECOMMERCE
- MOTO
- RECCURING
order_description
Alphanumeric
Optional
Max: 150
It holds the description of the order.
Example: iPhone 6-S
Special characters: ' / . _ - # : $ Space
card_security_code
Numeric
Optional
Max: 4
A security code for the card. * Only AMEX accepts card security code of 4 digits.
Example: 123
customer_name
Alpha
Optional
Max: 40
The customer’s name.
Example: John Smith
Special characters: _ \ / - . ' Space
merchant_extra
Alphanumeric
Optional
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra1
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra2
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra3
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra4
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra5
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
remember_me
Alpha
Optional
Max: 3
This parameter provides you with an indication to whether to save this token for the user based on the user selection. *The Tokenization service MUST be activated in order to be able to send “remember_me” parameter.
Possible/ expected values: -YES -NO
phone_number
Alphanumeric
Optional
max: 19
The customer’s phone number.
Example: 00962797219966
Special characters: + - ( ) Space
settlement_reference
Alphanumeric
Optional
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898
Special characters: - _ .
return_url
Alphanumeric
Optional
Max: 400
The URL of the Merchant’s page to be displayed to the customer when the order is processed.
Example: http://www.merchant.com
Special characters: $ ! = ? # & - _ / : .

Operations - Response

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

ATTRIBUTES Description
command
Alpha
max: 20
Command.
Possible/ expected values: AUTHORIZATION, PURCHASE
access_code
Alphanumeric
Max: 20
The ID of the Merchant.
Example: zx0IPmPy5jp1vAz
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
amount
Numeric
Max: 10
The transaction’s amount.
Example: 10000
currency
Alpha
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
customer_email
Alphanumeric
Max: 254
The customer’s email.
Example: customer1@domain.com
customer_ip
Alphanumeric
max: 45
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
token_name
Alphanumeric
max: 100
The Token received from the Tokenization process.
Example: COp9Vmp
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
payment_option
Alpha
Max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
- MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document
- MEEZA (for Purchase operations and ECOMMERCE eci only)
eci
Alpha
Max: 16
Ecommerce indicator.
Possible/ expected values:
- ECOMMERCE
- MOTO
- RECCURING
order_description
Alphanumeric
Max: 150
It holds the description of the order.
Example: iPhone 6-S
authorization_code
Alphanumeric
Max: 100
The authorization code returned from the 3rd party.
Example: P1000000000000372136
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
customer_name
Alpha
Max: 40
The customer’s name.
Example: John Smith
merchant_extra
Alphanumeric
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra1
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra2
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra3
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra4
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra5
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
expiry_date
Numeric
Max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
Max: 19
The masked credit card’s number.
Only the MEEZA payment option takes 19 digits card number.
*AMEX payment option takes 15 digits card number.
*Otherwise, they take 16 digits card number.
Example: 400555
*****0001
status
Numeric
Max: 2
A two-digit numeric value that indicates the status of the transaction.
Possible/ expected values: Please refer to section statuses
card_holder_name
Alpha
Max: 50
The card holder name.
Example: John Smith
3ds_url
Alphanumeric
Max: 300
The URL where the Merchant redirects a customer whose card is 3-D Secure for authentication.
Example: http://www.3dsecure.com
remember_me
Alpha
Max: 3
This parameter provides you with an indication to whether to save this token for the user based on the user selection.
Possible/ expected values: - YES, - NO
phone_number
Alphanumeric
max: 19
The customer’s phone number.
Example: 00962797219966
settlement_reference
Alphanumeric
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898

How to add the Tokenization service on the Merchant Page 2.0 channel?

The Tokenization service is applicable to be integrated through the Merchant Page 2.0 Channel through the below steps:
1. The Customer processes the first PURCHASE/ AUTHORIZATION payment successfully.
2. The Merchant will receive a token_name in the response. This token_name should be considered as a permanent token name, and it can be used in the future customer’s payments by submitting the token_name in the next PURCHASE/ AUTHORIZATION payment with card_security_code parameter.
3. No need to open the Merchant Page to fill all the card details again in the next checkouts.

If the Customer wants to update/ delete his card, you should check Update Token section.

FORT Mobile SDK

The FORT Mobile SDK allows Merchants to securely integrate the payment functions. It also allows Merchants to easily accept In-App payments. Instead of the traditional, time-consuming, and complex way of being redirected to the mobile browser to complete the payment, In-App payments can be completed through our FORT Mobile SDK. In turn, this gives the Merchant’s consumers a smooth, pleasing user-experience by using In-App payment functions through the native applications.

Features

Download

Download SDK 1.8 for iOS iOS SDK Integration Guide

Create FORT Mobile SDK Token

A Mobile SDK Token is required to authenticate every request sent to the SDK. The Token is also significant to process payment operations in the FORT through our FORT Mobile SDK.

SDK Token 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.

SDK Token - Request

Include the following parameters in the Request you will send to the FORT SDK:

ATTRIBUTES Description
service_command
Alpha
Mandatory
max: 20
Command.
Possible/ expected values: SDK_TOKEN
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
language
Alpha
Mandatory
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
device_id
Alphanumeric
Mandatory
Max: 100
A unique device identifier.
Example: ffffffff-a9fa-0b44-7b27-29e70033c587
Special characters: -
signature
Alphanumeric
Mandatory
Max: 200
A string hashed using the Secure Hash Algorithm. Please refer to section Signature
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a

SDK Token - Response

The following parameters will be returned in the FORT SDK Response:

ATTRIBUTES Description
service_command
Alpha
Max: 20
Command.
Possible/ expected values: SDK_TOKEN
access_code
Alphanumeric
Max: 20
Access code.
Example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier
Alphanumeric
Max: 20
The ID of the Merchant.
Example: CycHZxVj
language
Alpha
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
device_id
Alphanumeric
Max: 100
A unique device identifier.
Example: ffffffff-a9fa-0b44-7b27-29e70033c587
signature
Alphanumeric
Max: 200
A string hashed using the Secure Hash Algorithm. Please refer to section Signature
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
sdk_token
Alphanumeric
Max: 100
An SDK Token to enable using the FORT Mobile SDK.
Example: dwp78q3
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

Integrate Android SDK

To process a transaction using the FORT Mobile SDK, create a Mobile SDK Token (Please refer to section Create FORT Mobile SDK Token) and proceed through the following sections.

About the Software

The first version of the solution is available only for the Android OS.
Supported Android Platforms: The FORT Mobile SDK supports all devices running Android 4.1.x (API level 16).
#ICE_CREAM_SANDWICH or higher are supported.
This release supports Android Pie API 28. The FORT Mobile SDK supports both English and Arabic languages. Portrait is the only orientation supported within the FORT Mobile SDK. Through the first version of the FORT Mobile SDK, the Merchant has the ability to process a CREDIT CARD transactions only. The supported credit card payment options are VISA, MASTERCARD, American Express (AMEX), MADA and MEEZA.

IDE Configurations

To start using the FORT Mobile SDK, do the following:

1. Extract this folder.
2. Download SDK for Android.
3. Unzip the downloaded Android SDK.
4. The folder content is as follows:

   * Dependencies folder which includes:
     - Eclipse folder:
       a. .jar files for the SDK dependencies.
       b. LINKS_README text file that contains a list for sources of the above jars and a
      list of required libraries to be added as dependencies
      as well (Manual configuration).
     - AndroidStudio_gradle text file; add the compile command for what your project
      does not include.

   * Res folder which includes:
     - Layout
     - Layout-ar
   * FORTSDKv1.5.aar-release.

To continue the integration, please proceed with the following steps:
1. Go to File → New → New Module.
2. Select “Import .JAR/.AAR Package” and click next.
3. Enter the path to .aar file and click finish.
4. Browse to the dependencies folder and open the “AndroidStudio_gradle” text file.
5. Copy and paste the implementation/ api lines that are NOT already supported in your dependency block. (All listed dependencies are   required).
6. Click the “Sync the project with gradle files” button.
7. Clean the project.
8. The SDK is now ready for your use.

The integration will include two main steps. For the first step, you need to create a library project by following the below steps:
1. Create a new project (from this time it’s called “library project”) in your workspace.
2. Do not forget to mark it as library.
3. Clear the src folder of the library project.
4. Unzip the .aar file. You can rename it to zip and then unzip it or use any tool.
5. Copy the classes.jar file to libs folder on the library project.
6. Replace the res folder on library project with the res folder of the .aar file.


The project you have created contains almost everything you need. Now let’s start configuring your project to reference this library project by following the below points:
1. In the target project, use the library created in step one (mentioned above) as a dependency.
2. Open the AndroidManifest.xml file inside .aar file and make sure to copy everything it takes (permissions, activities, services, receivers …) in the AndroidManifest.xml file of the target project.
3. Copy the entire contents (if any) inside the assets folder of the .aar file to the assets folder of the target project.
4. Copy the entire contents (if any) inside the libs folder of the .aar file to the libs folder of the target project.
5. Open the dependencies file → Eclipse, then copy all .jar files and add them to the libs folder of the target project.
6. Check if your target project has the project dependencies included in the LINKS_README text file under the LINKS_README text file under the libraries (Projects/aar). Otherwise use the links included in the previously mentioned file and add them as a dependency project on your target project.
7. Clean and rebuild your target project.

OS Permissions

The FORT Mobile SDK requires the following permissions to work properly:

Using the FORT Mobile SDK

Please take a look at the Java model/ bean of the FORT Mobile SDK request on the right side of the page.

The following are the Mobile SDK Call Parameters:

// FORT Mobile SDK request

public class FortRequest implements Serializable{
private Map<String, Object> requestMap;
private boolean showResponsePage;
public Map<String, Object> getRequestMap() {
   return requestMap;
}
public void setRequestMap(Map<String, Object> requestMap) {
  this.requestMap = requestMap;
}
public boolean isShowResponsePage() {
  return showResponsePage;
}
public void setShowResponsePage(boolean showResponsePage) {
  this.showResponsePage = showResponsePage;
}
}

Define and initialize an instance of the FortCallBackManager in your activity as appears on the right side of the page (Java section):

// FORT Callback Manager Instance

private FortCallBackManager fortCallback = null;
fortCallback = FortCallback.Factory.create();

You need to add the statement that appears on the right side of the page (Java section) to the onActivityResult function.

//Callback Statement
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
super.onActivityResult(requestCode, resultCode, data);
fortCallback.onActivityResult(requestCode,resultCode,data);
}

For every transaction that needs to be processed, do the call that appears on the right side of the page and handle the callback methods upon your business flow.

//FORT Mobile SDK Call
FortSdk.getInstance().registerCallback(this,fortRequest,5, fortCallback, showLoading, new FortInterfaces.OnTnxProcessed() {
@Override
public void onCancel(Map<String, Object> requestParamsMap,Map<String, Object> responseMap) {
        //TODO: handle me
    }
@Override
public void onSuccess(Map<String, Object> requestParamsMap, Map<String, Object> fortResponseMap) {
        //TODO: handle me
    }
@Override
public void onFailure(Map<String, Object> requestParamsMap, Map<String, Object> fortResponseMap) {
        //TODO: handle me
    }
@Override
public void onSuccess(Map<String, Object> requestParamsMap, Map<String, Object> fortResponseMap) {
       //TODO: handle me
}
});

The FORT Mobile SDK Call registers a new callback for a new request. The registerCallBack requires the inputs found on the right side of the page (Java section).

//The registerCallBack Request
  public void registerCallback(
  Activity context,
  final FortRequest fortRequest,
  String environment,
  final int requestCode,
  final FortCallBackManager callbackManager,
  boolean showLoading,
  final FortInterfaces.OnTnxProcessed callback)

Parameter Description
context Passes the currency activity context.
fortRequest An instance of the model mentioned in Collect the FORT Mobile SDK Request section.
environment This parameter used to determine whether the request is going to be submitted to the test or production environment.
It has two possible values:
- ENVIRONMENT.TEST
- ENVIRONMENT.PRODUCTION
requestCode A unique ID for this request.
callBackManager The instance defined in section Define a Callback Manager.
showLoading A Boolean flag to show or hide the loading dialog.
callback A transaction callback listener that overrides the following three callback options:
- onCancel(): called when the user cancels the payment by clicking the back button.
- onSuccess(): called when the transaction is processed successfully.
- onFailure(): called when the transaction is failed.

Please Make sure to use the FortSDK function found on the right side of the page (Java section) to generate the device_id parameter value that must be used for creating the sdk_token from your business security server.

//FortSDK function
String device_id = FortSdk.getDeviceId(this);

We provide you with the res folder that includes the source code of the pages in order to customize the design, themes, etc. You can customize both English and Arabic layouts as needed. However, please take the following tips into consideration:

 1. Don’t change the layout name because it’s considered an override process.
 2. Make sure to use all the views that has the ID property in order to avoid the NullPointerException.
 3. Redesign the view for portrait orientation. Note that Landscape orientation isn’t supported.
 4. You can support as much layout densities as you want.
 5. Don’t forget to redesign the layout-ar file too (right-to-left).
 6. Don’t change, rename, or remove onClick functions.

Our Mobile SDK v 1.5 consists one of the following three main activities design:
   * activity_cc_payment.xml
   * activity_cc_response.xml
   * activity_init_secure_conn

Every file is available for both English and Arabic alignments; layout and layout-ar.

The following code was used to customize the way the “Amount” is displayed in the Customized Mobile SDK Payment Page:

SDK Operations

The FORT Mobile SDK allows the Merchant’s application to process Authorization and Purchase operations.

Include the following parameters in the Request you will send to the FORT SDK:

ATTRIBUTES Description
command
Alpha
Mandatory
max: 20
Command.
Possible/ expected values: AUTHORIZATION, PURCHASE
merchant_reference
Alphanumeric
Mandatory
Max: 40
The Merchant’s unique order number.
Example: XYZ9239-yu898
Special characters: - _ .
amount
Numeric
Mandatory
Max: 10
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 10000
currency
Alpha
Mandatory
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Mandatory
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
customer_email
Alphanumeric
Mandatory
Max: 254
The customer’s email.
Example: customer@domain.com
Special characters: _ - . @ +
sdk_token
Alphanumeric
Mandatory
Max: 100
An SDK Token to enable using the FORT Mobile SDK.
Example: Dwp78q3
token_name
Alphanumeric
Optional
Max: 100
The Token received from the Tokenization process.
Example: Op9Vmp
Special characters: . @ - _
payment_option
Alpha
Optional
Max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
- MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document
- MEEZA (for Purchase operations and ECOMMERCE eci only)
eci
Alpha
Optional
Max: 16
Ecommerce indicator.
Possible/ expected values: ECOMMERCE
order_description
Alphanumeric
Optional
Max: 150
A description of the order.
Example: iPhone 6-S
Special characters: ' / . _ - # : $ Space
customer_ip
Alphanumeric
Optional
max: 45
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
Special characters: . :
customer_name
Alpha
Optional
Max: 40
The customer’s name.
Example: John Smith
Special characters: _ \ / - . '
phone_number
Alphanumeric
Optional
max: 19
The customer’s phone number.
Example: 00962797219966
Special characters: + - ( ) Space
settlement_reference
Alphanumeric
Optional
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898
Special characters: - _ .
merchant_extra
Alphanumeric
Optional
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra1
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra2
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra3
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra4
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra5
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @

The following parameters will be returned in the FORT SDK Response:

ATTRIBUTES Description
command
Alpha
Max: 20
Command.
Possible/ expected values: AUTHORIZATION, PURCHASE
merchant_reference
Alphanumeric
Max: 40
The Merchant’s unique order number.
Example: XYZ9239-yu898
amount
Numeric
Max: 10
The transaction’s amount.*Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 10000
currency
Alpha
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
customer_email
Alphanumeric
Max: 254
The customer’s email.
Example: customer1@domain.com
fort_id
Numeric
Max: 20
The order’s unique reference returned by our system.
Example: 149295435400084008
sdk_token
Alphanumeric
Max: 100
An SDK Token to enable using the FORT Mobile SDK.
Example: Dwp78q3
token_name
Alphanumeric
max: 100
The Token received from the Tokenization process.
Example: Op9Vmp
payment_option
Alpha
Max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
- MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document
- MEEZA (for Purchase operations and ECOMMERCE eci only)
eci
Alpha
Max: 16
The E-commerce indicator.
Possible/ expected values: ECOMMERCE
authorization_code
Alphanumeric
Max: 100
The authorization code returned from the 3rd party.
Example: P1000000000000372136
order_description
Alphanumeric
Max: 150
It holds the description of the order.
Example: iPhone 6-S
response_message
Alphanumeric
Max: 150
The 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
customer_ip
Alphanumeric
max: 45
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
customer_name
Alpha
Max: 40
The customer’s name.
Example: John Smith
expiry_date
Numeric
Max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
Max: 16
The masked credit card’s number. Only the MEEZA payment option takes 19 digits card number.
*AMEX payment option takes 15 digits card number.
*Otherwise, they take 16 digits card number.
Example: 400555
*****0001
status
Numeric
Max: 2
A two-digit numeric value that indicates the status of the transaction.
Possible/ expected values: Please refer to section statuses
phone_number
Alphanumeric
max: 19
The customer’s phone number.
Example: 00962797219966
settlement_reference
Alphanumeric
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898
merchant_extra
Alphanumeric
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra1
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra2
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra3
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra4
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra5
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith

FORT Android SDK – Device ID permission

This section helps the developers to understand the need and usage of the permission requested by the FORT Payment SDK to generate a unique device ID.

A part of the FORT mobile SDK flow is to get a unique ID for the device. Generating the ID based on more than one input (collecting as much as possible will lead to a real unique ID).

The Telephone manager is one of these sources. Accessing the Telephone manager need the use of ‘android.permission.READ_PHONE_STATE’ permission. According to Android that’s a dangerous permission to be used. Getting the needed permission through the flow on the case of getting the client granted that will produce a miss match device ID on the 1st SDK call.

To avoid the mismatch flow we are suggesting you the following solutions:
* Handle the 1st SDK call in the onActivityResults().
Since The FORT SDK is a module running within the main application context the requested permission response will be returned to the merchant context. Once the activity that called geDeviceId for the 1st received a call-back in the onActivityResult() with request code = 222 you can for sure starts the payment flow of creating an SDK token and calling the SDK afterwards.

Sample code

Integrate iOS SDK

To process a transaction using the FORT Mobile SDK, create a Mobile SDK Token (Please refer to section Create FORT Mobile SDK Token) and proceed through the following sections.

About the Software

IOS 8+ The FORT Mobile SDK supports both English and Arabic languages. Portrait is the only orientation supported within the FORT Mobile SDK. Through the first version of the FORT Mobile SDK, the Merchant has the ability to process a CREDIT CARD transactions only. The supported credit card payment options are VISA, MASTERCARD, American Express (AMEX), MADA and MEEZA.

Include the SDK to your Xcode Project

1. Extract this folder.
2. Drag the PayFortSDK.framework & PayFortSDK.bundle to Frameworks in Project Navigator.
3. Create a new group Frameworks if it does not exist:
      * Choose Create groups for any added folders.
      * Make Sure to select Copy files if needed.
4. Set -ObjC in the Other Linker Flags in the Target → Build Settings Tab.
5. For Swift Projects Don’t forget to add the #import to the Bridging-Header.h

Objective C

Swift

Installation

1. Import the PayFort Library.

2. Initialize PayFortConrtoller with targeted environment, You set the target environment by setting one the two ENUM KPayFortEnviromentSandBox or KPayFortEnviromentProduction.

Objective C

Swift

3. Set Dictionary contain all keys and values for SDK.

Objective C

Swift

4. Call PayFort and Response callback

Objective C

Swift

SDK - Response

By default the response will be dictionary to show the sent data in addition to the status, response message and response code.
The response will be ready in the registered call back handler with success, failed and cancelled. You can view the response by log the result as the followings:

Objective C

Swift

Also there is an option to show response view directly in elegant view that show response results either its success or failed. By activating the following option:

Objective C

Swift

Hidden PayFort loading

There is an option to hide loading view when SDK initialize the connection request. By disable the following option:

Objective C

Swift

Custom Payment Designing

You have the option to provide your custom UI theme for the payment view by the followings:

FORT Mobile SDK Operations

The FORT Mobile SDK allows the Merchant’s application to process Authorization and Purchase operations.

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

ATTRIBUTES Description
command
Alpha
Mandatory
max: 20
Command.
Possible/ expected values: AUTHORIZATION, PURCHASE
merchant_reference
Alphanumeric
Mandatory
Max: 40
The Merchant’s unique order number.
Example: XYZ9239-yu898
Special characters: - _ .
amount
Numeric
Mandatory
Max: 10
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 10000
currency
Alpha
Mandatory
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Mandatory
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
customer_email
Alphanumeric
Mandatory
Max: 254
The customer’s email.
Example: customer@domain.com
Special characters: _ - . @ +
sdk_token
Alphanumeric
Mandatory
Max: 100
An SDK Token to enable using the FORT Mobile SDK.
Example: Dwp78q3
token_name
Alphanumeric
Optional
Max: 100
The Token received from the Tokenization process.
Example: Op9Vmp
Special characters: . @ - _
payment_option
Alpha
Optional
Max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
- MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document
- MEEZA (for Purchase operations and ECOMMERCE eci only)
eci
Alpha
Optional
Max: 16
Ecommerce indicator.
Possible/ expected values: ECOMMERCE
order_description
Alphanumeric
Optional
Max: 150
It holds the description of the order.
Example: iPhone 6-S
Special characters: ' / . _ - # : $ Space
customer_ip
Alphanumeric
Optional
max: 45
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
Special characters: . :
customer_name
Alpha
Optional
Max: 40
The customer’s name.
Example: John Smith
Special characters: _ \ / - . '
phone_number
Alphanumeric
Optional
max: 19
The customer’s phone number.
Example: 00962797219966
Special characters: + - ( ) Space
settlement_reference
Alphanumeric
Optional
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898
Special characters: - _ .
merchant_extra
Alphanumeric
Optional
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra1
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra2
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra3
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra4
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra5
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @

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

ATTRIBUTES Description
command
Alpha
Max: 20
Command.
Possible/ expected values: AUTHORIZATION, PURCHASE
merchant_reference
Alphanumeric
Max: 40
The Merchant’s unique order number. *The amount parameter is returned by our system according to the predefined allowed decimal points per currency.
Example: XYZ9239-yu898
amount
Numeric
Max: 10
The transaction’s amount.
Example: 10000
currency
Alpha
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
customer_email
Alphanumeric
Max: 254
The customer’s email.
Example: customer1@domain.com
fort_id
Numeric
Max: 20
The order’s unique reference returned by our system.
Example: 149295435400084008
sdk_token
Alphanumeric
Max: 100
An SDK Token to enable using the FORT Mobile SDK.
Example: Dwp78q3
token_name
Alphanumeric
max: 100
The Token received from the Tokenization process.
Example: Op9Vmp
payment_option
Alpha
Max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
- MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document
- MEEZA (for Purchase operations and ECOMMERCE eci only)
eci
Alpha
Max: 16
The E-commerce indicator.
Possible/ expected values: ECOMMERCE
authorization_code
Alphanumeric
Max: 100
The authorization code returned from the 3rd party.
Example: P1000000000000372136
order_description
Alphanumeric
Max: 150
It holds the description of the order.
Example: iPhone 6-S
response_message
Alphanumeric
Max: 150
The 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
customer_ip
Alphanumeric
max: 45
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
expiry_date
Numeric
Max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
Max: 16
The masked credit card’s number.Only the MEEZA payment option takes 19 digits card number.
*AMEX payment option takes 15 digits card number.
*Otherwise, they take 16 digits card number.
Example: 400555
*****0001
customer_name
Alpha
Max: 40
The customer’s name.
Example: John Smith
phone_number
Alphanumeric
max: 19
The customer’s phone number.
Example: 00962797219966
settlement_reference
Alphanumeric
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898
merchant_extra
Alphanumeric
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra1
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra2
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra3
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra5
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith

How to add the Tokenization service on the Mobile SDK channel?

The Tokenization service is applicable to be integrated through the Mobile SDK Channel through the below steps:
1. The Customer enables the remember_me option displayed in the SDK payment page.
2. Processes the first PURCHASE/ AUTHORIZATION payment successfully.
3. The Merchant will receive a token_name in the response. This token_name should be considered as a permanent token name, and it can be used in the future customer’s payments by submitting the token_name in the next PURCHASE/ AUTHORIZATION payment.

If the Customer wants to update/ delete his card, you should check Update Token section.

Tokenization Sample Code

Objective-C

Swift

Apple Pay Service

Apple Pay is a digital wallet that allows Merchant’s customers to make payments using different Apple devices. The customer can complete the payment using his fingerprint.

Apple Pay Service URLs

Test Environment URL:

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

Production Environment URL:

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

Get Started With Apple Pay

Before you start Apple Pay integration please refer to the following URL https://developer.apple.com/apple-pay/get-started/ to complete the following steps:
    1. Setup you Apple Pay account.
    2. Complete the integration with Apple Pay; Apple Pay JS, and/or Apple Pay SDK.
    3. After completing the integration with Apple you should upload the Payment    Processing certificate that received from Apple in your PayFort account under    “Apple Pay Settings” tab.
After completing the integration with Apple Pay proceed with PayFort integration to process Authorization/ Purchase request.

Parameters Submission Type

REST POST request using JSON.

Apple Pay Authorization/ Purchase - Request

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

ATTRIBUTES Description
digital_wallet
Alpha
Mandatory
Max: 100
The buyer’s digital wallet.
Possible/ expected values: APPLE_PAY
Special characters: _
command
Alpha
Mandatory
Max: 20
A command.
Possible/ expected values: AUTHORIZATION, PURCHASE
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: - _ .
amount
Numeric
Mandatory
Max: 10
The transaction’s amount. *Each currency has predefined allowed
decimal points that should be taken into consideration when
sending the amount.
Example: 10000
currency
Alpha
Mandatory
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Mandatory
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
customer_email
Alphanumeric
Mandatory
Max: 254
The customer’s email.
Example: customer1@domain.com
Special characters: _ - . @ +
apple_data
Alphanumeric
Mandatory
Max: 500
This string represent the encrypted payment data.
Example: Check Example 1 below the table.
Special characters: / + =
apple_signature
Alphanumeric
Mandatory
Max: 3000
Signature of the payment and header data. The signature includes
the signing certificate, its intermediate CA certificate, and information about the signing algorithm.
Example: MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID5jCC…
Special characters: / + =
apple_header
List
Mandatory
Max: -
Additional version-dependent information used to decrypt and verify the payment.
Example: Check Example 2 below the table.
apple_transactionId
Alphanumeric
Mandatory
Max: 100
Transaction identifier, generated on the device.
Example: 93eec76cbedaedca44648e3d5c314766906e4e78ce33cd3b8
396f105a1c0daed
apple_ephemeralPublicKey
Alphanumeric
Mandatory
max: 200
Ephemeral public key bytes.
Example: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEM9JqF04vD
lGI…
apple_publicKeyHash
Alphanumeric
Mandatory
Max: 100
Hash of the X.509 encoded public key bytes of the merchant’s certificate.
Example: bVTUiyTv0uCJgQz8SNYHBHOlHMD6sR1qDuCqTaETzkw=
Special characters: / + =
apple_paymentMethod
List
Mandatory
Max: -
The details of the credit card.
Example: Check Example 3 below the table.
Special characters: -
apple_displayName
Alphanumeric
Mandatory
Max: 50
The credit card name.
Example: Visa 0492
Special characters: Space
apple_network
Alpha
Mandatory
Max: 20
The credit card name.
Example: Visa 0492
Possible/ expected values:
- Visa
- MasterCard
- AmEx
apple_type
Alpha
Mandatory
Max: 20
The credit card type.
Example: Visa 0492
Example: credit
signature
Alphanumeric
Mandatory
Max: 200
A string hashed using the Secure Hash Algorithm. Please refer to
section Signature
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
apple_applicationData
Alphanumeric
Optional
Max: 200
Hash of the applicationData property of the original
PKPaymentRequest object.
Example: 5173d4e05f2e07dc4e7ea9669bda185712ffffe1d6
cfce2d4e854d7661e70d67…
eci
Alpha
Optional
Max: 16
E-commerce indicator. *MOTO and E-commerce indicator clickable
in VISA, MASTERCARD and AMEX.
Possible/ expected values:
- ECOMMERCE
- MOTO
order_description
Alphanumeric
Optional
Max: 150
It holds the description of the order.
Example: iPhone 6-S
Special characters: ' / . _ - # : $ Space
customer_ip
Alphanumeric
Optional
max: 45
It holds the customer’s IP address. *We support IPv4 and IPv6 as
shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
Special characters: . :
customer_name
Alpha
Optional
Max: 40
The customer’s name.
Example: John Smith
Special characters: _ \ / - . ' Space
merchant_extra
Alphanumeric
Optional
Max: 999
Extra data sent by merchant. Will be received and sent back as
received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra1
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as
received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra2
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as
received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra3
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as
received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra4
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as
received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra5
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as
received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
phone_number
Alphanumeric
Optional
max: 19
The customer’s phone number.
Example: 00962797219966
Special characters: + - ( ) Space

Example 1

Example 2

Example 3

Apple Pay Authorization/ Purchase - Response

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

ATTRIBUTES Description
digital_wallet
Alpha
Max: 100
The buyer’s digital wallet.
Possible/ expected values: APPLE_PAY
command
Alpha
Max: 20
Command.
Possible/ expected values: AUTHORIZATION, PURCHASE
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
amount
Numeric
Max: 10
The transaction’s amount.
Example: 10000
currency
Alpha
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
customer_email
Alphanumeric
Max: 254
The customer’s email.
Example: customer1@domain.com
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
payment_option
Alpha
Max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- MADA (for Purchase operations and eci Ecommerce only)
eci
Alpha
Max: 16
The E-commerce indicator.
Possible/ expected values:
- ECOMMERCE
- MOTO
order_description
Alphanumeric
Max: 150
It holds the description of the order.
Example: iPhone 6-S
customer_ip
Alphanumeric
max: 45
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
customer_name
Alpha
Max: 40
The customer’s name.
Example: John Smith
merchant_extra
Alphanumeric
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra1
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra2
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra3
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra4
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra5
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
authorization_code
Alphanumeric
Max: 100
The authorization code returned from the 3rd party.
Example: P1000000000000372136
response_message
Alphanumeric
Max: 150
The 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
card_holder_name
Alpha
Max: 50
The card holder name.
Example: John Smith
expiry_date
Numeric
Max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
Max: 19
The masked credit card’s number.
AMEX payment option takes 15 digits card number.
*Otherwise, they take 16 digits card number.
Example: 400555
*****0001
phone_number
Alphanumeric
max: 19
The customer’s phone number.
Example: 00962797219966

Apple Pay SDK Service

Apple Pay is a digital wallet that allows Merchant’s customers to make payments using different Apple devices through FORT iOS SDK. The Customer authenticate his identity with Touch ID fingerprint verification to complete the payment.

Requirements

Before you start Apple Pay SDK integration; you need to check the following points:
• You will need to have one of these iOS devices (iPhone 6, iPhone 6s, iPhone 6 Plus, iPhone 6s Plus, iPhone 7, iPhone 7 Plus, iPhone SE, iPad Air 2, iPad mini 3, iPad mini 4, and iPad Pro models) running iOS 8.1 or later.

• You will need a Mac with Xcode 6.1 or newer installed. You can install or upgrade Xcode in the Mac App Store.

• You will also need an apple developer account and a membership in the iOS Developer Program. You can create a one from here.

• You will need to download the FORT iOS Mobile SDK, click here.

Get Started

Before you start Apple Pay integration with PayFort please refer to the following URL here to complete the following steps:
    1. Setup your Apple Pay account.
    2. Complete the integration with Apple Pay SDK.
After completing the integration with Apple Pay, check that you have got the following:
    • Apple merchantID.
    • Merchant certificate.
    • Payment processing certificate.
Then copy the following sample code to complete integration with FORT Mobile SDK:

Apple Pay SDK Authorization/ Purchase - Request

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

ATTRIBUTES Description
digital_wallet
Alpha
Mandatory
Max: 100
The buyer’s digital wallet.
Possible/ expected values: APPLE_PAY
Special characters: _
command
Alpha
Mandatory
Max: 20
A command.
Possible/ expected values: AUTHORIZATION, PURCHASE
merchant_reference
Alphanumeric
Mandatory
Max: 40
The Merchant’s unique order number.
Example: XYZ9239-yu898
Special characters: - _ .
amount
Numeric
Mandatory
Max: 10
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 10000
currency
Alpha
Mandatory
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Mandatory
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
customer_email
Alphanumeric
Mandatory
Max: 254
The customer’s email.
Example: customer1@domain.com
Special characters: _ - . @ +
sdk_token
Alphanumeric
Mandatory
Max: 100
An SDK token to enable using the FORT Mobile SDK.
Example: Dwp78q3
payment_option
Alpha
Optional
Max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- MADA (for Purchase operations and eci Ecommerce only)
eci
Alpha
Optional
Max: 16
E-commerce indicator.
Possible/ expected values: ECOMMERCE
order_description
Alphanumeric
Optional
Max: 150
It holds the description of the order.
Example: iPhone 6-S
Special characters: ' / . _ - # : $ Space
customer_ip
Alphanumeric
Optional
max: 45
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
Special characters: . :
customer_name
Alpha
Optional
Max: 40
The customer’s name.
Example: John Smith
Special characters: _ \ / - . ' Space
phone_number
Alphanumeric
Optional
max: 19
The customer’s phone number.
Example: 00962797219966
Special characters: + - ( ) Space
token_name
Alphanumeric
Optional
max: 100
The Token name.
Example: Op9Vmp
Special characters: - _ . @
settlement_reference
Alphanumeric
Optional
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898
Special characters: - _ .
merchant_extra
Alphanumeric
Optional
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra1
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra2
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra3
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra4
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra5
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @

Apple Pay SDK Authorization/ Purchase - Response

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

ATTRIBUTES Description
digital_wallet
Alpha
Max: 100
The buyer’s digital wallet.
Possible/ expected values: APPLE_PAY
command
Alpha
Max: 20
Command.
Possible/ expected values: AUTHORIZATION, PURCHASE
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
amount
Numeric
Max: 10
The transaction’s amount.
Example: 10000
currency
Alpha
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
customer_email
Alphanumeric
Max: 254
The customer’s email.
Example: customer1@domain.com
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
sdk_token
Alphanumeric
Max: 100
An SDK token to enable using the FORT Mobile SDK.
Example: Dwp78q3
payment_option
Alpha
Max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- MADA (for Purchase operations and eci Ecommerce only)
eci
Alpha
Max: 16
The E-commerce indicator.
Possible/ expected values: ECOMMERCE
order_description
Alphanumeric
Max: 150
It holds the description of the order.
Example: iPhone 6-S
customer_ip
Alphanumeric
max: 45
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
customer_name
Alpha
Max: 40
The customer’s name.
Example: John Smith
merchant_extra
Alphanumeric
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra1
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra2
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra3
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra4
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra5
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
authorization_code
Alphanumeric
Max: 100
The authorization code returned from the 3rd party.
Example: P1000000000000372136
response_message
Alphanumeric
Max: 150
The 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
card_holder_name
Alpha
Max: 50
The card holder name.
Example: John Smith
expiry_date
Numeric
Max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
Max: 19
The masked credit card’s number.
AMEX payment option takes 15 digits card number.
*Otherwise, they take 16 digits card number.
Example: 400555
*****0001
phone_number
Alphanumeric
max: 19
The customer’s phone number.
Example: 00962797219966
token_name
Alphanumeric
max: 100
The Token received from the Tokenization process.
Example: Op9Vmp
settlement_reference
Alphanumeric
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898

Recurring Transactions

Recurring transactions allows the Merchant to charge Customer’s card a specific amount on regular basis using the Purchase operation configured in single message mode. For example, the Merchant will be charging his Customer’s card the subscription fee on monthly basis.

How It Works - Overview

1. The Merchant has to have a Token created assigned to a specific Customer account. For more details on “Token” please refer to the FORT Tokenization Service.
2. The Merchant’s server sends the recurring transaction details along with the Customer’s Token to PayFort.
3. The transaction is processed and a valid response is returned to the Merchant servers indicating the status of the transaction.

Recurring 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.

Recurring - Request

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

ATTRIBUTES Description
command
Alpha
Mandatory
max: 20
command.
Possible/ expected values: PURCHASE
access_code
Alphanumeric
Mandatory
max: 20
Access code.
Example: zx0IPmPy5jp1vAz
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: - _ .
amount
Numeric
Mandatory
max: 10
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 10000
currency
Alpha
Mandatory
max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Mandatory
max: 2
The checkout page and messages language.
Possible/ expected values: en / ar
customer_email
Alphanumeric
Mandatory
max: 254
The customer’s email.
Example: customer@domain.com
Special characters: _ - . @ +
eci
Alpha
Mandatory
max: 16
Ecommerce indicator.
Possible/ expected values: RECURRING
token_name
Alphanumeric
Mandatory
max: 100
The Token received from the Tokenization process.
Example: Op9Vmp
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
payment_option
Alpha
Optional
Max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
order_description
Alphanumeric
Optional
max: 150
It holds the description of the order.
Example: iPhone 6-S
Special characters: ' / . _ - # : $ Space
customer_name
Alpha
Optional
max: 40
The customer’s name.
Example: John Smith
Special characters: _ \ / - . ' Space
merchant_extra
Alphanumeric
Optional
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra1
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra2
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra3
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra4
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra5
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
phone_number
Alphanumeric
Optional
max: 19
The customer’s phone number.
Example: 00962797219966
Special characters: + - ( ) Space
settlement_reference
Alphanumeric
Optional
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898
Special characters: - _ .

Recurring - Response

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

ATTRIBUTES Description
command
Alpha
max: 20
command.
Possible/ expected values: PURCHASE
access_code
Alphanumeric
max: 20
Access code.
Example: zx0IPmPy5jp1vAz
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
amount
Numeric
max: 10
The transaction’s amount.
Example: 10000
currency
Alpha
max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
max: 2
The checkout page and messages language.
Possible/ expected values: en / ar
customer_email
Alphanumeric
max: 254
The customer’s email.
Example: customer@domain.com
eci
Alpha
max: 16
Ecommerce indicator.
Possible/ expected values: RECURRING
token_name
Alphanumeric
max: 100
The Token received from the Tokenization process.
Example: Op9Vmp
signature
Alphanumeric
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
fort_id
Numeric
max: 20
The order’s unique reference returned by our system.
Example: 149295435400084008
payment_option
Alpha
Max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
order_description
Alphanumeric
max: 150
It holds the description of the order.
Example: iPhone 6-S
customer_name
Alpha
max: 40
The customer’s name.
Example: John Smith
merchant_extra
Alphanumeric
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra1
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra2
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra3
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra4
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra5
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
expiry_date
Numeric
Max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
Max: 16
The clear credit card’s number.
Example: 400555******0001
authorization_code
Alphanumeric
max: 100
The authorization code returned from the 3rd party.
Example: P1000000000000372136
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).
phone_number
Alphanumeric
max: 19
The customer’s phone number.
Example: 00962797219966
settlement_reference
Alphanumeric
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898

Installments

Installments Redirection

Installments Redirection Service - Request

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

ATTRIBUTES Description
installments
Alpha
Optional
max: 10
Used to specify the type of the Installments service.
Possible/ expected values: STANDALONE

Installments Redirection Service - Response

The following parameters will be returned in PayFort’s Response in addition to the Purchase - Response Parameters:

ATTRIBUTES Description
installments
Alpha
max: 10
Used to specify the type of the Installments service.
Possible/ expected values: STANDALONE
number_of_installments
Numeric
max: 2
The number of installments the customer has selected in the payment page.
Example: 3

Installments Merchant Page (Iframe)

Installments Merchant page Service - Request

Include the following parameters in the Merchant page - Request Parameters you will send to PayFort:

ATTRIBUTES Description
installments
Alpha
Mandatory
max: 10
Used to specify the type of the Installments service.
Possible/ expected values: STANDALONE
amount
Numeric
Mandatory
Max: 10
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 10000
currency
Alpha
Mandatory
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: USD
customer_country_code
Alpha
Optional
Max: 3
The Customer’s country code. ISO 3 digit country code.
Example: JOR

Installments Merchant page Service - Response

The following parameters will be returned in PayFort’s Response in addition to the Merchant Page - Response Parameters:

ATTRIBUTES Description
installments
Alpha
max: 10
Used to specify the type of the Installments service.
Possible/ expected values: STANDALONE
amount
Numeric
Max: 10
The transaction’s amount.
Example: 10000
currency
Alpha
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: USD
customer_country_code
Alpha
Max: 3
The Customer’s country code. ISO 3-digit country code.
Example: JOR
number_of_installments
Numeric
Max: 2
The number of installments the customer has selected in payment page.
Example: 3
plan_code
Alphanumeric
Max: 8
A code that refers to the “installments plan” the customer selected from the merchant page.
Example: NNNN89JJ
issuer_code
Alphanumeric
Max: 8
A code that refers to the “card issuer” the customer selected from the merchant page.
Example: 12HP34SE

Installments Purchase Service - Request

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

ATTRIBUTES Description
installments
Alpha
Mandatory
max: 10
Used to specify the type of the Installments service.
Possible/ expected values: YES
plan_code
Alphanumeric
Mandatory
Max: 8
A code that refers to the “installments plan” the customer selected from the merchant page.
Example: NNNN89JJ
issuer_code
Alphanumeric
Mandatory
Max: 8
A code that refers to the “card issuer” the customer selected from the merchant page.
Example: 12HP34SE

Installments Purchase Service - Response

The following parameters will be returned in PayFort’s Response in addition to the Operation - Response Parameters:

ATTRIBUTES Description
installments
Alpha
max: 10
Used to specify the type of the Installments service.
Possible/ expected values: YES
plan_code
Alphanumeric
Max: 8
A code that refers to the “installments plan” the customer selected from the merchant page.
Example: NNNN89JJ
issuer_code
Alphanumeric
Max: 8
A code that refers to the “card issuer” the customer selected from the merchant page.
Example: 12HP34SE
number_of_installments
Numeric
Max: 2
The number of installments the customer has selected in payment page.
Example: 3

Installments Hosted Checkout

Get Installments Plans API

This service allows you to know the installment plan details and issuers configured in your account for the installment service.

Test Environment URL:

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

Production Environment URL:

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

REST POST request using JSON.

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_INSTALLMENTS_PLANS
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
signature
Alphanumeric
Mandatory
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
amount
Numeric
Optional
max: 10
The transaction’s amount.*Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 10000
currency
Alpha
Optional
max: 3
The currency of the transaction’s amount in ISO code 3.
Example: USD
language
Alpha
Optional
max: 2
The checkout page and messages language.
Possible/ expected values: en / ar
issuer_code
Alphanumeric
Optional
max: 8
A code that refers to the “card issuer” the customer selected from the merchant page.
Example: 12HP34SE

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

ATTRIBUTES Description
query_command
Alpha
max: 50
Query operations command.
Possible/ expected values: GET_INSTALLMENTS_PLANS
access_code
Alphanumeric
max: 20
Access code.
Example: zx0IPmPy5jp1vAz
merchant_identifier
Alphanumeric
max: 20
The ID of the Merchant.
Example: CycHZxVj
signature
Alphanumeric
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
amount
Numeric
max: 10
The transaction’s amount.
Example: 10000
currency
Alpha
max: 3
The currency of the transaction’s amount in ISO code 3.
Example: USD
language
Alpha
max: 2
The checkout page and messages language.
Possible/ expected values: en / ar
issuer_code
Alphanumeric
max: 8
A code that refers to the “card issuer” the customer selected from the merchant page.
Example: 12HP34SE
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).
installment_detail
List
max: -
This parameter is a parent parameter for other parameters that contain the details of installment.
Possible/ expected values: (Please refer to the below section issuer_detal).

This parameter is a sub parameter of the “installment_detail” parameter, the table below shows the children parameters of the “issuer_detail”:

ATTRIBUTES Description
issuer_code
Alphanumeric
max: 8
A code that refers to the “card issuer” the customer selected from the merchant page.
Example: 12HP34SE
issuer_name_ar
Alphanumeric
max: 50
The issuer name in Arabic.
Example: Issuer2عربي
issuer_name_en
Alphanumeric
max: 50
The issuer name in English.
Example: Issuer2
terms_and_condition_ar
Alphanumeric
max: 200
The Arabic terms and condition URL.
Example: http://www.gmail.com
terms_and_condition_en
Alphanumeric
max: 200
The English terms and condition URL.
Example: http://www.yahoo.com
country_code
Alpha
max: 3
The country’s code in ISO 3-digits.
Example: JOR
issuer_logo_ar
Alphanumeric
max: 350
The issuer logo for the Arabic version.
Example: https://payfort-fort-images-lt.s3.amazonaws.com/frontend/files/logos/issuer/logo_en_164.jpg
issuer_logo_en
Alphanumeric
max: 350
The issuer logo for the English version.
Example: https://payfort-fort-images-lt.s3.amazonaws.com/frontend/files/logos/issuer/logo_en_164.jpg
banking_system
Alpha
max: 11
The type of institutions that provide financial services.
Possible/ expected values:
-Non Islamic
-Islamic
formula
Alphanumeric
max: 100
The equation of calculating the installment value.
Example: (amount +(amount *effective rate/100))/period
Please check the note below the table for more details.
plan_details
List
max: -
This parameter contain all the plans for this issuer.
Possible/ expected values: (Please refer to next plan_detail section).
bins
List
max: -
List of 6 digits of the card number related to this issuer.
Possible/ expected values: (Please refer to next bins section).
confirmation_message_ar
Alphanumeric
max: 500
This parameter shows to the customer the confirmation message that the merchant configure on his back-office in Arabic.
disclaimer_message_ar
Alphanumeric
max: 500
This parameter shows to the customer the disclaimer message that the merchant configure on his back-office in Arabic.
processing_fees_message_ar
Alphanumeric
max: 500
This parameter shows to the customer the processing fee message that the merchant configure on his back-office in Arabic.
confirmation_message_en
Alphanumeric
max: 500
This parameter shows the customer to the confirmation message that the merchant configure on his back-office in English.
disclaimer_message_en
Alphanumeric
max: 500
This parameter shows to the customer the disclaimer message that the merchant configure on his back-office in English.
processing_fees_message_en
Alphanumeric
max: 500
This parameter shows to the customer the processing fee message that the merchant configure on his back-office in English.

This parameter is a sub parameter of the “issuer_detail” parameter, the table below shows the children parameters of the “plan_detail”:

ATTRIBUTES Description
plan_code
Alphanumeric
max: 8
A code that refers to the “installments plan”.
Example: NNNN89JJ
currency_code
Alpha
max: 3
The currency of the transaction’s amount in ISO code 3.
Example: USD
number_of_installment
Numeric
max: 2
The number of installments.
Example: 3
fees_type
Alpha
max: 10
The type of the fee.
Possible/ expected values:
-Fixed
-Percentage
*Please refer to the below formulas section to know the difference.
fees_amount
Numeric
max: 10
The amount of the fee.
Example: 11
processing_fees_type
Alpha
max: 10
The type of the processing fee.
Possible/ expected values:
-Fixed
-Percentage
*Please refer to the below formulas section to know the difference.
processing_fees_amount
Numeric
max: 10
The amount of the processing fee.
Example: 11
rate_type
Alpha
max: 15
The type of the rate.
Possible/ expected values:
-Reducing Balance
-Flat
plan_merchant_type
Alpha
max: 11
The type of agreement between the plan and Merchant.
Possible/ expected values:
-Partner
-Non Partner
plan_type
Alpha
max: 12
The type of the installments plan.
Possible/ expected values:
-Local
-Cross-Border
fee_display_value
Numeric
max:
The display value that represent the fees amount.
Example: 11.0
minimum_amount
Numeric
max: 10
The minimum range of the accepted amount for this plan.
Example: 11
maximum_amount
Numeric
max: 10
The maximum range of the accepted amount for this plan.
Example: 110000000
amountPerMonth
Numeric
max: 10
The payable amount per month.
Example: 3.00

This parameter is a sub parameter of the “issuer_detail” parameter, the table below shows the children parameters of the “bins”:

ATTRIBUTES Description
bin
Numeric
max: 6
The first 6 digits of the card number.
Example: 478773
currency_code
Alpha
max: 3
The currency of the transaction’s amount in ISO code 3.
Example: JOR
card_brand_code
Alpha
max: 16
The type of the credit card.
Possible/ expected values:
-VISA
-Master Card
-American Express

The monthly installments amount that are displayed on PayFort payment pages are calculated based on the below formulas:

Percentage Fees: Installments interest rate in percent (%) charged to the customer by the bank.

Fixed Fees: Installments fees in fixed amount charged to the customer by the bank.

The following is sample of a response of an Get Installments Plans API request:

Merchant Page 2.0 Tokenization

Test Environment URL:

https://sbcheckout.payfort.com/FortAPI/paymentPage

Production Environment URL:

https://checkout.payfort.com/FortAPI/paymentPage

HTTPs Form Post Request

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

ATTRIBUTES Description
service_command
Alpha
Mandatory
max: 20
Command.
Possible/ expected values: TOKENIZATION
access_code
Alphanumeric
Mandatory
Max: 20
Access code.
Example: zx0IPmPy5jp1vAz
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
expiry_date
Numeric
Mandatory
Max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
Mandatory
Max: 16
The clear credit card’s number.
Example: 4005550000000001
card_security_code
Numeric
Mandatory
Max: 4
A security code for the card. * Only AMEX accepts card security code of 4 digits.
Example: 123
signature
Alphanumeric
Mandatory
Max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details).
*Please don’t include the following parameters in calculating the signature of Merchant Page 2.0 tokenization request: card_security_code, card number, expiry_date, card_holder_name, remember_me.
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
token_name
Alphanumeric
Optional
Max: 100
The token received from the Tokenization process.
Example: Op9Vmp
Special characters: . @ - _
card_holder_name
Alpha
Optional
Max: 50
The card holder name.
Example: John Smith
Special characters: . - ’
remember_me
Alpha
Optional
Max: 3
This parameter provides you with an indication to whether to save this token for the user based on the user selection.
Possible/ expected values: - YES - NO
return_url
Alphanumeric
Optional
Max: 400
The URL of the Merchant’s page to be displayed to the customer when the order is processed.
Example: http://www.merchant.com
Special characters: $ ! = ? # & - _ / : .

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

ATTRIBUTES Description
service_command
Alpha
Max: 20
Command.
Possible/ expected values: TOKENIZATION
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
expiry_date
Numeric
Max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
Max: 19
The masked credit card’s number.
AMEX payment option takes 15 digits card number.
*Otherwise, they take 16 digits card number.
Example: 400555
*****0001
signature
Alphanumeric
Max: 200
A string hashed using the Secure Hash Algorithm. Please refer to section Signature
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
token_name
Alphanumeric
max: 100
The Token received from the Tokenization process.
Example: COp9Vmp
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).
card_bin
Numeric
Max: 8
The first 6 digits of the card number.*If the card number for MEEZA was of length 19 then the card bin will be the first 8 digits.
Example: 478773
card_holder_name
Alpha
Max: 50
The card holder name.
Example: John Smith
remember_me
Alpha
Max: 3
This parameter provides you with an indication to whether to save this token for the user based on the user selection.
Possible/ expected values: - YES - NO
return_url
Alphanumeric
Max: 400
The URL of the Merchant’s page to be displayed to the customer when the order is processed.
Example: http://www.merchant.com

Merchant Page 2.0 Operations

Test Environment URL:

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

Production Environment URL:

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

REST POST request using JSON.

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

ATTRIBUTES Description
command
Alpha
Mandatory
max: 20
Command.
Possible/ expected values: PURCHASE
access_code
Alphanumeric
Mandatory
Max: 20
Access code.
Example: zx0IPmPy5jp1vAz
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: - _ .
amount
Numeric
Mandatory
Max: 10
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 10000
currency
Alpha
Mandatory
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Mandatory
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
customer_email
Alphanumeric
Mandatory
Max: 254
The customer’s email.
Example: customer@domain.com
Special characters: _ - . @ +
token_name
Alphanumeric
Mandatory
Max: 100
The Token received from the Tokenization process.
Example: Op9Vmp
Special characters: _ - . @
installments
Alpha
Mandatory
Max: 10
Used to specify the type of the Installments service.
Possible/ expected values: HOSTED
issuer_code
Alphanumeric
Mandatory
Max: 8
A code that refers to the “card issuer” the customer selected from the merchant page.
Example: 12HP34SE
plan_code
Alphanumeric
Mandatory
Max: 8
A code that refers to the “installments plan” the customer selected from the merchant page.
Example: NNNN89JJ
customer_ip
Alphanumeric
Mandatory
max: 45
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
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
payment_option
Alpha
Optional
Max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
eci
Alpha
Optional
Max: 16
Ecommerce indicator.
Possible/ expected values:
ECOMMERCE
order_description
Alphanumeric
Optional
Max: 150
It holds the description of the order.
Example: iPhone 6-S
Special characters: ' / . _ - # : $ Space
card_security_code
Numeric
Optional
Max: 4
A security code for the card. * Only AMEX accepts card security code of 4 digits.
Example: 123
customer_name
Alpha
Optional
Max: 40
The customer’s name.
Example: John Smith
Special characters: _ \ / - . ' Space
merchant_extra
Alphanumeric
Optional
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra1
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra2
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra3
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra4
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra5
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
remember_me
Alpha
Optional
Max: 3
This parameter provides you with an indication to whether to save this token for the user based on the user selection. *The Tokenization service MUST be activated in order to be able to send “remember_me” parameter.
Possible/ expected values: -YES -NO
phone_number
Alphanumeric
Optional
max: 19
The customer’s phone number.
Example: 00962797219966
Special characters: + - ( ) Space
settlement_reference
Alphanumeric
Optional
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898
Special characters: - _ .
return_url
Alphanumeric
Optional
Max: 400
The URL of the Merchant’s page to be displayed to the customer when the order is processed.
Example: http://www.merchant.com
Special characters: $ ! = ? # & - _ / : .

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

ATTRIBUTES Description
command
Alpha
max: 20
Command.
Possible/ expected values: PURCHASE
access_code
Alphanumeric
Max: 20
The ID of the Merchant.
Example: zx0IPmPy5jp1vAz
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
amount
Numeric
Max: 10
The transaction’s amount.
Example: 10000
currency
Alpha
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
customer_email
Alphanumeric
Max: 254
The customer’s email.
Example: customer1@domain.com
token_name
Alphanumeric
max: 100
The Token received from the Tokenization process.
Example: COp9Vmp
installments
Alpha
Max: 10
Used to specify the type of the Installments service.
Possible/ expected values: HOSTED
issuer_code
Alphanumeric
Max: 8
A code that refers to the “card issuer” the customer selected from the merchant page.
Example: 12HP34SE
plan_code
Alphanumeric
Max: 8
A code that refers to the “installments plan” the customer selected from the merchant page.
Example: NNNN89JJ
customer_ip
Alphanumeric
max: 45
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
signature
Alphanumeric
Max: 200
A string hashed using the Secure Hash Algorithm. Please refer to section Signature
Example: d7c185c475ac0e3
fort_id
Numeric
Max: 20
The order’s unique reference returned by our system.
Example: 149295435400084008
payment_option
Alpha
Max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
eci
Alpha
Max: 16
Ecommerce indicator.
Possible/ expected values:
ECOMMERCE
order_description
Alphanumeric
Max: 150
It holds the description of the order.
Example: iPhone 6-S
authorization_code
Alphanumeric
Max: 100
The authorization code returned from the 3rd party.
Example: P1000000000000372136
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
customer_name
Alpha
Max: 40
The customer’s name.
Example: John Smith
merchant_extra
Alphanumeric
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra1
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra2
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra3
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra4
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra5
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
expiry_date
Numeric
Max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
Max: 19
The masked credit card’s number.
AMEX payment option takes 15 digits card number.
*Otherwise, they take 16 digits card number.
Example: 400555
*****0001
status
Numeric
Max: 2
A two-digit numeric value that indicates the status of the transaction.
Possible/ expected values: Please refer to section statuses
card_holder_name
Alpha
Max: 50
The card holder name.
Example: John Smith
3ds_url
Alphanumeric
Max: 300
The URL where the Merchant redirects a customer whose card is 3-D Secure for authentication.
Example: http://www.3dsecure.com
remember_me
Alpha
Max: 3
This parameter provides you with an indication to whether to save this token for the user based on the user selection.
Possible/ expected values: - YES - NO
phone_number
Alphanumeric
max: 19
The customer’s phone number.
Example: 00962797219966
settlement_reference
Alphanumeric
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898

Installments Hosted for Trusted Channel

Installments Hosted for Trusted – Request

Include the following parameters in the Trusted Channel – Request Parameters you will send to PayFort:

ATTRIBUTES Description
installments
Alpha
Mandatory
Max: 10
Used to specify the type of the Installments service.
Possible/ expected values: HOSTED
issuer_code
Alphanumeric
Mandatory
Max: 8
A code that refers to the “card issuer” the customer selected from the merchant page.
Example: 12HP34SE
plan_code
Alphanumeric
Mandatory
Max: 8
A code that refers to the “installments plan” the customer selected from the merchant page.
Example: NNNN89JJ

Installments Hosted for Trusted – Response

The following parameters will be returned in PayFort’s Response in addition to Trusted Channel – Response parameters:

ATTRIBUTES Description
installments
Alpha
Max: 10
Used to specify the type of the Installments service.
Possible/ expected values: HOSTED
issuer_code
Alphanumeric
Max: 8
A code that refers to the “card issuer” the customer selected from the merchant page.
Example: 12HP34SE
plan_code
Alphanumeric
Max: 8
A code that refers to the “installments plan” the customer selected from the merchant page.
Example: NNNN89JJ

Installments Merchant Page - Style Sheet

This is a list with all customizable CSS classes Installments Merchant Page:

MOTO Channel

MOTO (Mobile Order/ Telephone Order) channel allows the Merchant to process MOTO transactions through the FORT API using credit card Tokens ONLY.

MOTO Channel 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.

MOTO Channel - Moto Request

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

ATTRIBUTES Description
command
Alpha
Mandatory
max: 20
Command.
Possible/ expected values: AUTHORIZATION, PURCHASE
access_code
Alphanumeric
Mandatory
max: 20
Access code.
Example: zx0IPmPy5jp1vAz
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: - _ .
amount
Numeric
Mandatory
max: 10
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 10000
currency
Alpha
Mandatory
max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Mandatory
max: 2
The checkout page and messages language.
Possible/ expected values: en / ar
customer_email
Alphanumeric
Mandatory
max: 254
The customer’s email.
Example: customer@domain.com
Special characters: _ - . @ +
eci
Alpha
Mandatory
max: 16
Ecommerce indicator.
Possible/ expected values: MOTO
token_name
Alphanumeric
Mandatory
max: 100
The token received from the Tokenization process.
Example: Op9Vmp
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
payment_option
Alpha
Optional
max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
order_description
Alphanumeric
Optional
max: 150
It holds the description of the order.
Example: iPhone 6-S
Special characters: ' / . _ - # : $ Space
customer_ip
Alphanumeric
Optional
max: 45
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
Special characters: . :
customer_name
Alpha
Optional
max: 40
The customer’s name.
Example: John Smith
Special characters: _ \ / - . ' Space
phone_number
Alphanumeric
Optional
max: 19
The customer’s phone number.
Example: 00962797219966
Special characters: + - ( ) Space
settlement_reference
Alphanumeric
Optional
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898
Special characters: - _ .
merchant_extra
Alphanumeric
Optional
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra1
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra2
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra3
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra4
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra5
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
return_url
Alphanumeric
Optional
max: 400
The URL of the Merchant’s page to be redirected to when the order is processed.
Example: http://www.merchant.com
Special characters: $ ! = ? # & - _ / : .

MOTO Channel - Moto Response

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

ATTRIBUTES Description
command
Alpha
max: 20
Command.
Possible/ expected values: AUTHORIZATION, PURCHASE
access_code
Alphanumeric
max: 20
Access code.
Example: zx0IPmPy5jp1vAz
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
amount
Numeric
max: 10
The transaction’s amount.
Example: 10000
currency
Alpha
max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
max: 2
The checkout page and messages language.
Possible/ expected values: en / ar
customer_email
Alphanumeric
max: 254
The customer’s email.
Example: customer@domain.com
eci
Alpha
max: 16
Ecommerce indicator.
Possible/ expected values: MOTO
token_name
Alphanumeric
max: 100
The token received from the Tokenization process.
Example: Op9Vmp
signature
Alphanumeric
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
fort_id
Numeric
max: 20
The order’s unique reference returned by our system.
Example: 149295435400084008
payment_option
Alpha
max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
order_description
Alphanumeric
max: 150
It holds the description of the order.
Example: iPhone 6-S
customer_ip
Alphanumeric
max: 45
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
customer_name
Alpha
max: 40
The customer’s name.
Example: John Smith
authorization_code
Alphanumeric
max: 100
The authorization code returned from the 3rd party.
Example: P1000000000000372136
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).
expiry_date
Numeric
max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
max: 16
The card’s number masked based on a certain standard that is selected in the technical settings.
Example: 400555******0001
phone_number
Alphanumeric
max: 19
The customer’s phone number.
Example: 00962797219966
settlement_reference
Alphanumeric
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898
merchant_extra
Alphanumeric
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra1
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra2
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra3
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra4
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra5
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
return_url
Alphanumeric
max: 400
The URL of the Merchant’s page to be redirected to when the order is processed.
Example: http://www.merchant.com

Trusted Channel

Trusted channel allows PCI certified Merchants to collect the user’s credit card details on the Merchant’s checkout page. The Merchants are able to process (Ecommerce, Recurring and MOTO) transactions through the FORT using clear card data and credit card tokens.

Trusted Channel 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.

Trusted Channel - Request

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

ATTRIBUTES Description
command
Alpha
Mandatory
max: 20
Command.
Possible/ expected values: AUTHORIZATION, PURCHASE
access_code
Alphanumeric
Mandatory
max: 20
Access code.
Example: zx0IPmPy5jp1vAz
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: - _ .
amount
Numeric
Mandatory
max: 10
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 10000
currency
Alpha
Mandatory
max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Mandatory
max: 2
The checkout page and messages language.
Possible/ expected values: en / ar
customer_email
Alphanumeric
Mandatory
max: 254
The customer’s email.
Example: customer@domain.com
Special characters: _ - . @ +
eci
Alpha
Mandatory
max: 16
Ecommerce indicator.
Possible/ expected values:
- MOTO
- RECURRING
- ECOMMERCE
expiry_date
Numeric
Mandatory
max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
Mandatory
max: 19
The clear credit card’s number.
*Only the MEEZA payment option takes 19 digits card number.
*AMEX payment option takes 15 digits card number.
*Otherwise, they take 16 digits card number.
Example: 4005550000000001
card_security_code
Numeric
max: 4
The clear card security code collect on the merchant’s checkout page. *It’s ONLY mandatory in the ecommerce requests. * Only AMEX accepts card security code of 4 digits.
Example: 123
customer_ip
Alphanumeric
Mandatory
max: 45
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
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
card_holder_name
Alpha
Optional
max: 50
The card holder name.
Example: John Smith
Special characters: ' - .
token_name
Alphanumeric
Optional
Max: 100
The Token received from the Tokenization process.
Example: Op9Vmp
Special characters: . @ - _
payment_option
Alpha
Optional
max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
- MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document
- MEEZA (for Purchase operations and ECOMMERCE eci only)
order_description
Alphanumeric
Optional
max: 150
It holds the description of the order.
Example: iPhone 6-S
Special characters: ' / . _ - # : $ Space
customer_name
Alpha
Optional
max: 40
The customer’s name.
Example: John Smith
Special characters: _ \ / - . ' Space
phone_number
Alphanumeric
Optional
max: 19
The customer’s phone number.
Example: 00962797219966
Special characters: + - ( ) Space
settlement_reference
Alphanumeric
Optional
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898
Special characters: - _ .
merchant_extra
Alphanumeric
Optional
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra1
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra2
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra3
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra4
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra5
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
return_url
Alphanumeric
Optional
max: 400
The URL of the Merchant’s page to be redirected to when the order is processed.
Example: http://www.merchant.com
Special characters: $ ! = ? # & - _ / : .

Trusted Channel - Response

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

ATTRIBUTES Description
command
Alpha
max: 20
Command.
Possible/ expected values: AUTHORIZATION, PURCHASE
access_code
Alphanumeric
max: 20
Access code.
Example: zx0IPmPy5jp1vAz
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
amount
Numeric
max: 10
The transaction’s amount.
Example: 10000
currency
Alpha
max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
max: 2
The checkout page and messages language.
Possible/ expected values: en / ar
customer_email
Alphanumeric
max: 254
The customer’s email.
Example: customer@domain.com
eci
Alpha
max: 16
Ecommerce indicator.
Possible/ expected values:
- MOTO
- RECURRING
- ECOMMERCE
expiry_date
Numeric
max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
max: 16
The masked credit card’s number.
Only the MEEZA payment option takes 19 digits card number.
*AMEX payment option takes 15 digits card number.
*Otherwise, they take 16 digits card number.
Example: 400555
*****0001
customer_ip
Alphanumeric
max: 45
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
signature
Alphanumeric
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
card_holder_name
Alpha
Max: 50
The card holder name.
Example: John Smith
token_name
Alphanumeric
max: 100
The Token received from the Tokenization process.
Example: Op9Vmp
fort_id
Numeric
max: 20
The order’s unique reference returned by our system.
Example: 149295435400084008
payment_option
Alpha
max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
- MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document
- MEEZA (for Purchase operations and ECOMMERCE eci only)
order_description
Alphanumeric
max: 150
It holds the description of the order.
Example: iPhone 6-S
customer_name
Alpha
max: 40
The customer’s name.
Example: John Smith
merchant_extra
Alphanumeric
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra1
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra2
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra3
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra4
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra5
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
authorization_code
Alphanumeric
max: 100
The authorization code returned from the 3rd party.
Example: P1000000000000372136
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).
3ds_url
Alphanumeric
Max: 300
The URL where the Merchant redirects a customer whose card is 3-D Secure for authentication.
Example: http://www.3dsecure.com
phone_number
Alphanumeric
max: 19
The customer’s phone number.
Example: 00962797219966
settlement_reference
Alphanumeric
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898

How to add the Tokenization service on the Trusted channel?

The Tokenization service is applicable to be integrated through the Trusted Channel through the below steps:
1. The Customer processes the first PURCHASE/ AUTHORIZATION payment successfully.
2. The Merchant will receive a token_name in the response. This token_name should be considered as a permanent token name, and it can be used in the future customer’s payments by submitting the token_name in the next PURCHASE/ AUTHORIZATION payment with card_security_code parameter.
3. No need to open the Merchant Page to fill all the card details again in the next checkouts.

If the Customer wants to update/ delete his card, you should check Update Token section.

3-D Secure services

3-D Secure services is an extra authentication service to authenticate the transaction by sending an OTP to the card holder from the issuer bank then the card holder have to authenticate the transaction by entering this OTP on the 3DS page. There are two types of 3-D Secure Services:

  1. Check 3-D Secure & Flex 3-D Secure Services:

        Check 3-D Secure Service: This service provides cardholders a decreased risk of other people being able to use their payment cards fraudulently on the Merchant’s site.
        Flex 3-D Secure Service: This service gives you the flexibility to downgrade the 3-D Secure authentication in the transaction processing, based on a set of rules of your choice.

  2. External MPI & Expose 3-D Secure services:

        External MPI Service: This service allows the Fort to accept Purchase/ Authorization transactions in which the 3ds check was done externally using an external MPI.
        Expose 3-D Secure Service: This service allows the Merchant to use the 3-D Secure service in standalone request without the transactionpurchase/Authorization flow; the user 3-D Secure Authentication can be done separately to get the user Authentication data and then the merchant can perform the charge request “Authorization/Purchase” in another request.

Check 3-D Secure & Flex 3-D Secure Services

Check 3-D Secure Service

This service provides cardholders a decreased risk of other people being able to use their payment cards fraudulently on the Merchant’s site.

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

ATTRIBUTES Description
check_3ds
Alpha
Optional
max: 2
This parameter allows the Merchant to deactivate the 3-D Secure service per transaction. This parameter can be used with both Authorization and Purchase transactions.
Possible/ expected values: NO

Flex 3-D Secure Service

This service gives you the flexibility to downgrade the 3-D Secure authentication in the transaction processing, based on a set of rules of your choice. You can active/ deactivate this service under the “Flex Management” tab on your FORT Back-office.

Click on the “Flex Management” tab on the main menu of your FORT Back-office. The following tabs should be displayed:
Service configuration: to allow the merchant to activate/ deactivate the flex service after accept the terms and conditions.
List management: allow the merchant to add multiple lists with different list types (email, IP, BIN, custom field and country) through “Add New List”.
Rules Management: to set the required rules for flex Management by merchant choice.
Audit log: triggered all the actions done by the merchant in configurations the Flex service.

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

ATTRIBUTES Description
flex_value
Alphanumeric
Optional
max: 255
This parameter reflects the custom field value you had configure in the Back-office. *Only English values are applicable.
Example: Sale50
Special characters: _ / \ - . # $ % & @ *

External MPI & Expose 3-D Secure services

External MPI 3-D Secure Service

This service allows the Fort to accept Purchase/ Authorization transactions in which the 3ds check was done externally using an external MPI.

Test Environment URL:

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

Production Environment URL:

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

REST POST request using JSON.

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

ATTRIBUTES Description
command
Alpha
Mandatory
max: 20
Command.
Possible/ expected values: AUTHORIZATION, PURCHASE
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: _ - .
amount
Numeric
Mandatory
Max: 10
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 10000
currency
Alpha
Mandatory
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Mandatory
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
customer_email
Alphanumeric
Mandatory
Max: 254
The customer’s email.
Example: customer@domain.com
Special characters: _ - . @ +
eci
Alpha
Optional
Max: 16
Ecommerce indicator.
Possible/ expected values:
- ECOMMERCE
- MOTO
expiry_date
Numeric
Mandatory
Max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
Mandatory
Max: 19
The clear credit card’s number. *Only the MEEZA payment option takes 19 digits card number. *AMEX payment option takes 15 digits card number. *Otherwise, they take 16 digits card number.
Example: 4005550000000001
card_security_code
Numeric
Max: 4
A security code for the card. * Only AMEX accepts card security code of 4 digits.
Example: 123
signature
Alphanumeric
Mandatory
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
3ds_xid
Alphanumeric
Optional
Max: 28
Unique transaction Identification number to identify the 3DS transaction.
Example: 6kQGHEiZDU0H4+mUWF7zELHAcqM=
3ds_enrolled
Alpha
Optional
Max: 1
Parameter that hold if the card is enrolled or not.
Possible/ expected values:
- Y (Yes)
- N (No)
3ds_status
Alpha
Optional
Max: 1
The status of the 3ds check just like 3-DSEnrolled but this parameter is available after a check is completed.
Possible/ expected values:
- Y
- N
- U
- A
3ds_eci
Numeric
Optional
Max: 2
The eCommerce indicator returned from the MPI.
Possible/ expected values:
- 05
- 06
ver_token
Alphanumeric
Optional
Max: 28
Verification token generated by the issuer to prove that the cardholders has been authenticated.
Example: gIGCg4SFhoeIiYqLjI2Oj5CRkpM=
card_holder_name
Alpha
Optional
max: 50
The card holder name.
Example: John Smith
Special characters: ' - .
token_name
Alphanumeric
Optional
Max: 100
The Token received from the Tokenization process.
Example: Op9Vmp
Special characters: . @ - _
payment_option
Alpha
Optional
Max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
- MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document
- MEEZA (for Purchase operations and ECOMMERCE eci only)
order_description
Alphanumeric
Optional
Max: 150
It holds the description of the order.
Example: iPhone 6-S
Special characters: ' / . _ - # : $ Space
customer_ip
Alphanumeric
Optional
max: 45
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
Special characters: . :
customer_name
Alpha
Optional
Max: 40
The customer’s name.
Example: John Smith
Special characters: _ \ / - . ' Space
phone_number
Numeric
Optional
Max: 19
The customer’s phone number.
Example: 00962797219966
Special characters: + - ( ) Space
settlement_reference
Alphanumeric
Optional
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898
Special characters: - _ .
merchant_extra
Alphanumeric
Optional
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra1
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra2
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra3
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra4
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra5
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
return_url
Alphanumeric
Optional
Max: 400
The URL of the Merchant’s page to be displayed to the customer when the order is processed.
Example: http://www.merchant.com
Special characters: $ ! = ? # & - _ / : .

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

ATTRIBUTES Description
command
Alpha
Mandatory
max: 20
Command.
Possible/ expected values: AUTHORIZATION, PURCHASE
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: _ - .
amount
Numeric
Mandatory
Max: 10
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 10000
currency
Alpha
Mandatory
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Mandatory
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
customer_email
Alphanumeric
Mandatory
Max: 254
The customer’s email.
Example: customer@domain.com
Special characters: _ - . @ +
eci
Alpha
Optional
Max: 16
Ecommerce indicator.
Possible/ expected values:
- ECOMMERCE
- MOTO
expiry_date
Numeric
Mandatory
Max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
Mandatory
Max: 19
The clear credit card’s number. *Only the MEEZA payment option takes 19 digits card number. *AMEX payment option takes 15 digits card number. *Otherwise, they take 16 digits card number.
Example: 4005550000000001
signature
Alphanumeric
Mandatory
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
card_holder_name
Alpha
Optional
max: 50
The card holder name.
Example: John Smith
Special characters: ' - .
token_name
Alphanumeric
Optional
Max: 100
The Token received from the Tokenization process.
Example: Op9Vmp
Special characters: . @ - _
fort_id
Numeric
Max: 20
The order’s unique reference returned by our system.
Example: 149295435400084008
payment_option
Alpha
Optional
Max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
- MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document
- MEEZA (for Purchase operations and ECOMMERCE eci only)
order_description
Alphanumeric
Optional
Max: 150
It holds the description of the order.
Example: iPhone 6-S
Special characters: ' / . _ - # : $ Space
customer_ip
Alphanumeric
Optional
max: 45
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
Special characters: . :
customer_name
Alpha
Optional
Max: 40
The customer’s name.
Example: John Smith
Special characters: _ \ / - . ' Space
phone_number
Numeric
Optional
Max: 19
The customer’s phone number.
Example: 00962797219966
Special characters: + - ( ) Space
settlement_reference
Alphanumeric
Optional
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898
Special characters: - _ .
merchant_extra
Alphanumeric
Optional
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra1
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra2
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra3
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra4
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
merchant_extra5
Alphanumeric
Optional
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
Special characters: . ; / _ - , ' @
return_url
Alphanumeric
Optional
Max: 400
The URL of the Merchant’s page to be displayed to the customer when the order is processed.
Example: http://www.merchant.com
Special characters: $ ! = ? # & - _ / : .
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
3ds_url
Alphanumeric
Max: 300
The URL where the Merchant redirects a customer whose card is 3-D Secure for authentication.
Example: http://www.3dsecure.com

Expose 3-D Secure Service

This service allows the Merchant to use the 3-D Secure service in standalone request without the transaction purchase/Authorization flow; the user 3-D Secure Authentication can be done separately to get the user Authentication data and then the merchant can perform the charge request “Authorization/Purchase” in another request.

Test Environment URL:

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

Production Environment URL:

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

REST POST request using JSON.

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

ATTRIBUTES Description
service_command
Alpha
Mandatory
max: 20
Command.
Possible/ expected values: 3DS_ENROLLMENT
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: _ - .
amount
Numeric
Mandatory
Max: 10
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 10000
currency
Alpha
Mandatory
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Mandatory
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
expiry_date
Numeric
Mandatory
Max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
Mandatory
Max: 19
The clear credit card’s number.
Example: 4005550000000001
merchant_3ds_url
Alphanumeric
Mandatory
max: 300
The URL where the Merchant will be redirected to see the returned 3ds parameters.
Example: https://www.merchant.com
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

3-D Secure Enrollment Request Example!

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

ATTRIBUTES Description
query_command
Alpha
max: 50
Query operations command.
Possible/ expected values: 3DS_ENROLLMENT
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
amount
Numeric
Max: 10
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 10000
currency
Alpha
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
expiry_date
Numeric
Max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
> Max: 19
The masked credit card’s number.
Example: 400555******0001
merchant_3ds_url
Alphanumeric
max: 300
The URL where the Merchant will be redirected to see the returned 3ds parameters.
Example: https://www.merchant.com
Special characters: - & ? = _ . : / #
3ds_enrolled
Alpha
Max: 1
Parameter that hold if the card is enrolled or not.
Possible/ expected values:
- Y (Yes)
- N (No)
- U (Unspecified failure)
threeds_id
Alphanumeric
Max: 100
The 3ds operations unique reference.
Example: 153606397100001061
signature
Alphanumeric
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
3ds_xid
Alphanumeric
max: 28
Unique transaction Identification number to identify the 3DS transaction.
Example: 6kQGHEiZDU0H4+mUWF7zELHAcqM=
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: 44000
status
Numeric
max: 2
A two-digit numeric value that indicates the status of the transaction
Possible/ expected values: (Please refer to section statuses).

3-D Secure Enrollment Response Example!

• After you get back a 3Ds Enrollment response that includes the parameter “3ds_enrolled” of value “Y”; follow the below steps for the 3Ds Authentication request:

  1. In case you are on “MIGS” processor; Copy the returned 3ds_url in a new browser. Then, select all the returned parameters to be send in the next request “3Ds Authentication”.
  2. In case you are on “Cybersource”/ “MPGS” processor; two parameters will returns in the “3Ds Enrollment”; as below:
        • MD
        • PaRes
    And you have to copy them in the “3Ds Authentication” request; as you will see in the 3Ds Authentication request example.

Test Environment URL:

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

Production Environment URL:

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

REST POST request using JSON.

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

ATTRIBUTES Description
service_command
Alpha
Mandatory
max: 20
Command.
Possible/ expected values: 3DS_AUTHENTICATION
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
language
Alpha
Mandatory
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
third_party_body
Alphanumeric
Mandatory
Max: 6000
Combinations of 3ds parameters from the 3ds_enrollment.
Example: Check the examples below
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

3-D Secure Authentication Request on MIGS processor Example!

3-D Secure Authentication Request on Cybersource/ MPGS Processors Example!

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

ATTRIBUTES Description
service_command
Alpha
max: 20
Command.
Possible/ expected values: 3DS_AUTHENTICATION
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
language
Alpha
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
threeds_id
Alphanumeric
Max: 100
The 3ds operations unique reference.
Example: 153606397100001061
3ds_xid
Alphanumeric
Max: 28
Unique transaction Identification number to identify the 3DS transaction.
Example: 6kQGHEiZDU0H4+mUWF7zELHAcqM=
3ds_enrolled
Alpha
Max: 1
Parameter that hold if the card is enrolled or not.
Possible/ expected values:
- Y (Yes)
- N (No)
3ds_status
Alpha
Max: 1
The status of the 3ds check just like 3-DSEnrolled but this parameter is available after a check is completed.
Possible/ expected values:
- Y
- N
- U
- A
3ds_eci
Numeric
Max: 2
The eCommerce indicator returned from the MPI.
Possible/ expected values:
- 05
- 06
ver_type
Alphanumeric
Max: 3
The type of verification used for 3DS.
Possible/ expected values:
- 3DS
- SPA
ver_token
Alphanumeric
Max: 28
Verification token generated by the issuer to prove that the cardholders has been authenticated.
Example: gIGCg4SFhoeIiYqLjI2Oj5CRkpM=
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: 44000
status
Numeric
max: 2
A two-digit numeric value that indicates the status of the transaction
Possible/ expected values: (Please refer to section statuses).

3Ds Authentication Response on MIGS Processor Example!

3-D Secure Authentication Response on Cybersource/ MPGS Processors Example!

PayFort Fraud Service

This service protects the Merchant form being lured into a scam over the Internet, and as a result minimizes chargebacks.

PayFort Fraud Service - Request/ Response

Include the following parameter in the Request you will send to PayFort, and the same parameter will be returned in PayFort’s Response:

ATTRIBUTES Description
customer_ip
Alphanumeric
Mandatory
max: 45
Refers to the customer’s IP Geolocation. *We support IPv4 and IPv6 as shown in the example below.
Example: 192.178.1.10
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
Special characters: . :

ACI ReD Fraud Service

ACI ReD is a reliable Fraud Screening and Prevention service that will further help safeguard your online payments and minimize chargebacks. It is designed to meet the needs of e-commerce Merchants as well as PSPs. ReD focuses on protecting the Merchant’s revenues and support the growth of their business, not to mention enhancing their Customer experience and boosting Customer satisfaction.

ACI ReD Fraud - Request

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

ATTRIBUTES Description
customer_type
Alpha
Optional
max: 1
This parameter is required if any customer detail is present.
Example: B
customer_id
Alphanumeric
Optional
max: 16
The Customer’s ID/ account number.
Example: Au8vJ9HxLo
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
customer_first_name
Alpha
Optional
max: 30
The Customer’s first name.
Example: Osama
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
customer_middle_initial
Alpha
Optional
max: 1
The Customer’s middle name’s initial.
Example: M
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
customer_last_name
Alpha
Optional
max: 30
The Customer’s last name.
Example: Kamal
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
customer_address1
Alphanumeric
Optional
max: 30
The Customer/ Billing address line 1.
Example: Amman - Khalda
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
customer_address2
Alphanumeric
Optional
max: 30
The Customer/ Billing address line 2 (for extra details).
Example: Al Sati St.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
customer_apartment_no
Alphanumeric
Optional
max: 30
The Customer/ Billing apartment number.
Example: 12
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
customer_city
Alphanumeric
Optional
max: 20
The Customer/ Billing city.
Example: Amman
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
customer_state
Alpha
Optional
max: 10
The Customer/ Billing state code.
Example: Jordan
customer_zip_code
Alphanumeric
Optional
max: 9
The Customer/ Billing post/ zip code.
Example: 11183
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
customer_country_code
Alpha
Optional
max: 3
The Customer’s country code; ISO 3-digit country code.
Example: JOR
customer_phone
Numeric
Optional
max: 19
The Customer’s home phone number.
Example: 00962797219966
customer_alt_phone
Numeric
Optional
max: 19
The Customer’s alternative phone.
* For the Telecommunications sector, send: MSISDN.
Example: 00962797256645
customer_date_birth
Alphanumeric
Optional
max: 10
The Customer’s date of birth.
Format: YYYY-MM- DD.
Example: 1977-10-03
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
ship_type
Alpha
Optional
max: 1
Shipping details present flag.
* This parameter is not applicable for the Gaming sector.
Example: S
ship_first_name
Alpha
Optional
max: 30
Ship to first name.
* This parameter is not applicable for the Gaming sector.
Example: Rana
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
ship_middle_name
Alpha
Optional
max: 1
Ship to middle initial.
* This parameter is not applicable for the Gaming sector.
Example: A
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
ship_last_name
Alpha
Optional
max: 30
Ship to last name.
* This parameter is not applicable for the Gaming sector.
Example: Rashdan
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
ship_address1
Alphanumeric
Optional
max: 30
Ship to address line 1.
* This parameter is not applicable for the Gaming sector.
Example: Cairo - Egypt
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ , Space
ship_address2
Alphanumeric
Optional
max: 30
Ship to address line 2.
* This parameter is not applicable for the Gaming sector.
Example: Garden City
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ , Space
ship_apartment_no
Alphanumeric
Optional
max: 30
Ship to appartment number.
* This parameter is not applicable for the Gaming sector.
Example: 22
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
ship_address_city
Alphanumeric
Optional
max: 20
Ship to address city.
* This parameter is not applicable for the Gaming sector.
Example: Dubai
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
ship_address_state
Alpha
Optional
max: 3
Ship to address state.
* This parameter is not applicable for the Gaming sector.
Example: UAE
ship_zip_code
Alphanumeric
Optional
max: 9
Ship to post/ zip code.
* This parameter is not applicable for the Gaming sector.
Example: 11183
ship_country_code
Alpha
Optional
max: 3
Ship to country code; ISO 3-Digit country code.
* This parameter is not applicable for the Gaming sector.
Example: JOR
ship_phone
Numeric
Optional
max: 19
Ship to home phone number.
* This parameter is not applicable for the Gaming sector.
Example: 0096265534256
ship_alt_phone
Numeric
Optional
max: 12
Ship To alternative phone.
* This parameter is not applicable for the Gaming sector.
Example: 0797334465
ship_email
Alphanumeric
Optional
max: 254
Ship to email address.
* For the Gaming sector, send: Player Email Address.
Example: ship@gmail.com
Special characters: @ - . _ Space
ship_comments
Alphanumeric
Optional
max: 160
Any shipping comments.
* For the Gaming sector, send: Player Email Address.
Example: (Any shipping comments can be entered)
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
ship_method
Alpha
Optional
max: 1
The shipping method.
* This parameter is not applicable for the Gaming sector.
Possible/ expected values:
- N (Next Day Service)
- T (Two-Day Service)
- W (Three- Day Service)
- C (Low-Cost Carrier)
- D (Customer Choice)
- I (International)
- M (Military)
- P (Collect at Store)
- O (Other)
fraud_extra1
Alphanumeric
Optional
max: 256
If the sector is Retail, Gaming, Travel, or Telecommunications, then the field value must contain the “Concatenated Billing Address”.
* For the Gaming sector, send: Player Email Address.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra2
Alphanumeric
Optional
max: 256
If the sector is Retail, Travel, or Telecommunications, the value of the field must be the “Concatenated Shipping Address” as follows:
street + + shipzip if the address is particularly long and space is lim ited then truncate the first portion of the address and send the postcode/Zip code in full.
* This parameter is not applicable for the Gaming sector.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra3
Alphanumeric
Optional
max: 256
If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the “Address Verification (PayPal)”.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra4
Alphanumeric
Optional
max: 256
If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the “Account Status (PayPal)”.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra5
Alphanumeric
Optional
max: 256
If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the “Eligibility Status (PayPal)”.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra6
Alphanumeric
Optional
max: 256
If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the “Outstanding Balance on the Account (PayPal)”.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra7
Alphanumeric
Optional
max: 256
If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the “Credit Score (PayPal)”.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra8
Alphanumeric
Optional
max: 256
If the sector is Telecommunications, the value must be the “Account Number” (if multiple MSISDN per account).
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra9
Alphanumeric
Optional
max: 265
If the sector is Telecommunications, the value must be the “MSISDN Age in days”.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra10
Alphanumeric
Optional
max: 256
- If the sector is Travel, the value must be the “Full Travel Itinerary”.
- If the sector is Telecommunications, the value must be the “Earliest Account Activity/ First Call Date”.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra11
Alphanumeric
Optional
max: 30
If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the “Account Age”.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra12
Alphanumeric
Optional
max: 30
If the sector is Retail, Travel, or Telecommunications, the value must be the “Number of Previous Orders Sent to the Shipping Address”.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra13
Alphanumeric
Optional
max: 30
If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the “Number of Days Since the Email Attached to the Account has Changed”.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra14
Alphanumeric
Optional
max: 30
If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the “Number of Days Since the Password was Changed”.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra16
Alphanumeric
Optional
max: 30
If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the “Number of Previous Orders Associated with the Card and Email”.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra17
Alphanumeric
Optional
max: 30
If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the “Event/ Promotion Flag”.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra18
Alphanumeric
Optional
max: 30
- If the sector is Retail, Gaming, or Telecommunications, the value must be the “Sales Channel”.
- If the sector is Travel, the value must be the “Third Party Booking Flag, Yes or No”.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra19
Alphanumeric
Optional
max: 30
- If the sector is Retail, Travel, or Telecommunications, the value must be the “Private/ Business/ Trade” (customerType).
- If the sector is Gaming, the value must be the “Customer Gaming ID”.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra20
Alphanumeric
Optional
max: 30
- If the sector is Retail, Gaming, or Telecommunications, the value must be the “Number of Previous Successful Transactions”.
- If the sector is Travel, the value must be the “Number of Previous Successful Bookings”.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra21
Alphanumeric
Optional
max: 30
- If the sector is Gaming, the values must be the “Gift for Other Player Flag”.
- If the sector is Travel, the value must be the “Booking Type”.
- If the sector is Telecommunications, the value must be the “Payment Type”.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra22
Alphanumeric
Optional
max: 30
- If the sector is Gaming, the values must be the “Playing Time”.
- If the sector is Travel, the value must be the “Time to First Departure in Hours”.
- If the sector is Telecommunications, the value must be the “Number of Previous Successful Top-ups”.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra23
Alphanumeric
Optional
max: 30
If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the “Channel (IVR vs. Web vs. Mobile Application, etc.).
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra24
Alphanumeric
Optional
max: 30
- If the sector is Gaming, the values must be the "Premium Account Balance”.
- If the sector is Travel, the value must be the “Loyalty Scheme”.
- If the sector is Telecommunications, the value must be the “Sim IMSI (International Mobile Subscriber Identity)”.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra25
Alphanumeric
Optional
max: 30
- If the sector is Gaming, the values must be the “Game Account Balance”.
- If the sector is Travel, the value must be the “Loyalty Scheme Member Number”.
- If the sector is Telecommunications, the value must be the “IMEI (International Mobile Equipment Identity)”.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
cart_details
Alphanumeric
Optional
max: 999
This parameter is a parent parameter for other parameters that contain the details of the shopping cart created by the Merchant.
Example: (Please refer to section Cart Details Example Value
Special characters: $
device_fingerprint
Alphanumeric
max: 4000
Unique device ID generated by Script. please refer to Fraud Native Mobile SDK Guide to generate device fingerprint.
Example: 04003hQUMXGB0po…
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ % + ! Space

ACI ReD Cart Fraud - Request

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

ATTRIBUTES Description
item_quantity
Alphanumeric
Optional
max: 10
The item’s quantity.
* For the Gaming sector, send: Clan.
Example: 4
item_sku
Alphanumeric
Optional
max: 12
The item’s commodity or “Stock Keeping Unit” code.
* For the Gaming sector, send: Gold balance.
Example: 1ShirtBlueM
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
item_prod_code
Alphanumeric
Optional
max: 12
The item’s product code.
* For the Gaming sector, send: Silver balance.
Example: MOB111
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
item_part_no
Alphanumeric
Optional
max: 30
The item’s Manufacturers Part or EAN number.
* For the Gaming sector, send: Exp balance.
* For the Travel sector, send: Flight/ Train/ Bus Number.
Example: TSR-1002
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
item_description
Alphanumeric
Optional
max: 256
The item’s description.
* For the Gaming sector, send: Date of first credit.
* For the Travel sector, send: Ticket Delivery Method.
Example: iPhone 6-S
Special characters: - _ ' , . Space
item_price
Numeric
Optional
max: 10
The item’s unit price (lowest denomination).
* For the Travel sector, send: Ticket Price.
Example: 700
item_shipping_no
Alphanumeric
Optional
max: 19
The item’s shipping/ tracking number.
* For the Travel sector, send: Ticket Departure Date And Time.
Example: AB586985609GB
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
item_shipping_method
Alpha
Optional
max: 1
The item’s shipping method.
* For the Retail, Travel, Telecommunications sectors, send: New Shipping Address Flag.
* This parameter is not applicable for the Gaming sector.
Possible/ expected values:
- N (Next Day Service)
- T (Two-Day Service)
- W (Three- Day Service)
- C (Low-Cost Carrier)
- D (Customer Choice)
- I (International)
- M (Military)
- P (Collect at Store)
- O (Other)
item_shipping_comments
Alphanumeric
Optional
max: 160
The item’s shipping comments.
* For the Travel sector, send: Ticket Itinerary.
Example: (Any shipping comments can be entered).
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
item_gift_msg
Alphanumeric
Optional
max: 160
The item’s gift message.
* For the Retail and Telecommunications sectors, send: High Risk Product Flag.
Example: Congrats!
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
rcpt_title
Alphanumeric
Optional
max: 5
The Recipient’s title.
* For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available.
* For the Travel sector, send: Adult/Child/Infant flag.
Example: Mr.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
rcpt_first_name
Alphanumeric
Optional
max: 30
The Recipient’s first name.
* For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available.
* For the Travel sector, send: Passenger First Name.
Example: Mohammad
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
rcpt_middle_initial
Alphanumeric
Optional
max: 1
The Recipient’s middle initial.
* For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available.
* For the Travel sector, send: Passenger Middle Initial.
Example: R
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
rcpt_last_name
Alphanumeric
Optional
max: 30
The Recipient’s last name.
* For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available.
* For the Travel sector, send: Passenger Last Name.
Example: Tawfeeq
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
rcpt_apartment_no
Alphanumeric
Optional
max: 30
The Recipient’s apartment number.
* For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available.
* For the Travel sector, send: Travel Class; i.e.: Standard/ Economy etc.
Example: 12
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
rcpt_address1
Alphanumeric
Optional
max: 30
The Recipient’s address line 1.
* For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available.
* For the Travel sector, send: Departure Airport/ Station Code/ City.
Example: Amman - Khalda
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
rcpt_address2
Alphanumeric
Optional
max: 30
The Recipient’s address line 2 (for extra details).
* For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available.
* For the Travel sector, send: Arrival Airport/ Station Code/ City.
Example: Al Sati St.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
rcpt_city
Alphanumeric
Optional
max: 30
The Recipient’s city.
* For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available.
* For the Travel sector, send: Booking Type.
Example: Sharjah
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
rcpt_state
Alphanumeric
Optional
max: 10
The Recipient’s state.
* For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available.
* For the Travel sector, send: Departure Country 3 Digit ISO Code.
Example: Qatar
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
rcpt_zip_code
Alphanumeric
Optional
max: 10
The Recipient’s post/ zip code.
* For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available.
* For the Travel sector, send: Ticket Type; i.e.: One Way/ Return etc.
Example: 11183
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
rcpt_country_code
Alpha
Optional
max: 3
The Recipient’s country code; ISO 3-Digit country code.
* For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available.
* For the Travel sector, send: Arrival Country.
Example: JOR
rcpt_phone
Numeric
Optional
max: 19
The Recipient’s phone number.
* For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available.
Example: 00962797675543
rcpt_email
Alphanumeric
Optional
max: 45
The Recipient’s email address.
* For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available.
* For the Travel sector, send: Passenger Name Record.
Example: recipient@hotmail.com
Special characters: @ - . _ Space

ACI ReD Fraud - Response

The following parameter will be returned in the Response:

ATTRIBUTES Description
fraud_comment
Alphanumeric
max: 1000
“fraud_comment” this value represents the feedback of the agent reviewing “in review” transaction. This parameter is part of the Authorization/ Purchase response parameters returned on the notification URL after the In review transaction is updated.
Example: Close

Cart Details Example Value

The following is an example value of the “cart_details”:

Device fingerprint script

The following is the script you should use to generate the device fingerprint:

Digital wallet

MasterPass Service

As another move towards a cashless environment, PayFort provides MasterPass; a digital wallet that securely stores the buyer’s credit card details and shipping addresses and information, making shopping through thousands of online Merchants simple and convenient. This is fulfilled by enhancing and simplifying the buyer’s digital shopping experience.

MasterPass Redirection

    1. The Merchant submits a form that includes all the parameters.
    The Merchant calls the following URL to be redirected to the FORT:         

https://checkout.payfort.com/FortAPI/paymentPage

    2. The FORT returns a response to the Merchant.
    3. The FORT inserts the response parameters into a JavaScript.
    4. A lightbox appears to the buyer where he enters his credentials, selects the card type and the shipping address, and clicks “Finish Shopping”.
    5. The FORT either proceeds to Authorize or Purchase the payment based on the value of the command parameter sent in the Merchant’s form.

6. The FORT returns a response to the Merchant.(Please refer to section MasterPass Service - Response for the Response Parameters).


Test Environment URL:

 https://sbcheckout.payfort.com/FortAPI/paymentPage

Production Environment URL:

 https://checkout.payfort.com/FortAPI/paymentPage


HTTPs Form Post Request.


(Please take a look at the Request Example on the right side of the page.)
Include the following parameters in the Request you will send to PayFort:

MasterPass Request Example

<form action="https://sbcheckout.payfort.com/FortAPI/paymentPage"method="post"id="simulatorForm">
<input type="hidden" name="digital_wallet" id="digital_wallet" value="MASTERPASS"/>
<input type="hidden" name="command"id="command" value="AUTHORIZATION"/>
<input type="hidden" name="access_code" id="access_code" value="zx0IPmPy5jp1vAz"/>
<input type="hidden" name="merchant_identifier" id="merchant_identifier" value="CycHZxVj"/>
<input type="hidden" name="merchant_reference" id="merchant_reference" value="XYZ9239-yu898"/>
<input type="hidden" name="amount" id="amount" value="10000"/>
<input type="hidden" name="currency" id="currency" value="AED"/>
<input type="hidden" name="language" id="language" value="en"/>
<input type="hidden" name="customer_email" id="customer_email" value="someone@email.com"/>
<input type="hidden" name="signature" id="signature" value="7cad05f0212ed933c9a5d5dffa31661acf2c827a"/>
<input type="hidden" name="payment_option"id="payment_option" value="VISA"/>
<input type="hidden" name="order_description" id="order_description" value="iPhone 6-S"/>
<input type="hidden" name="customer_ip" id="customer_ip" value="192.178.1.10"/>
<input type="hidden" name="customer_name" id="customer_name" value="John Smith"/>
<input type="hidden" name="cart_details" id="cart_details" value='{"sub_total":"900","cart_items":[{"item_description":"Xbox","item_image":"http://image.com","item_name":"Xbo x 360","item_price":"300","item_quantity":"2"},{"item_description":"Playstation 3","item_image":"http://image.com","item_name":"Playstation 3","item_price":"150","item_quantity":"2"}]}'/>
<input type="hidden" name="return_url" id="return_url" value="http://backtothemerchanturl.com"/>
<input value="Send" type="submit"> </form>
ATTRIBUTES Description
digital_wallet
Alpha
Mandatory
max: 100
The buyer’s digital wallet.
Possible/ expected values: MASTERPASS
command
Alpha
Mandatory
max: 20
Command.
Possible/ expected values: AUTHORIZATION, PURCHASE
access_code
Alphanumeric
Mandatory
max: 20
Access code.
Example: zx0IPmPy5jp1vAz
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: - _ .
amount
Numeric
Mandatory
max: 10
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 10000
currency
Alpha
Mandatory
max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Mandatory
max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
customer_email
Alphanumeric
Mandatory
max: 254
The customer’s email.
Example: customer@domain.com
Special characters: _ - . @ +
cart_details
Alphanumeric
Mandatory
max: 999
This parameter is a parent parameter for other parameters that contain the details of the shopping cart created by the Merchant.
Example: please check the note below the table.
Special characters: $
cart_items
Alphanumeric
Mandatory
max: 999
The items of the shopping cart.
Example: Tshirt
Special characters: $
item_price
Numeric
Mandatory
max: 10
The price of a cart item.
Example: 700
sub_total
Numeric
Mandatory
max: 10
The total price of the cart items.
Example: 550
item_description
Alphanumeric
Mandatory
max: 256
A description of a cart’s item.
Example: iPhone 6-S
Special characters: - _ ' , . Space
item_image
Alphanumeric
Mandatory
max: 500
A URL to the item’s image.
Example: https://www.image.com
Special characters: # / : . = ? & - _
item_name
Alphanumeric
Mandatory
max: 100
The name of an item in the shopping cart.
Example: Item1
Special characters: Space
item_quantity
Alphanumeric
Mandatory
max: 10
The quantity of a cart item.
Example: 4
signature
Alphanumeric
Mandatory
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
order_description
Alphanumeric
Optional
Max: 150
It holds the description of the order.
Example: iPhone 6-S
Special characters: ' / . _ - # : $ Space
payment_option
Alpha
Optional
max: 10
Payment Option.
Possible/ expected values: MASTERCARD, VISA
customer_ip
Alphanumeric
Optional
max: 45
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
Special characters: . :
customer_name
Alpha
Optional
max: 40
The customer’s name.
Example: John Smith
Special characters: _ \ / - . ' Space
phone_number
Alphanumeric
Optional
max: 19
The customer’s phone number.
Example: 00962797219966
Special characters: + - ( ) Space
settlement_reference
Alphanumeric
Optional
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898
Special characters: - _ .
return_url
Alphanumeric
Optional
max: 400
The URL of the Merchant’s page to be displayed to the customer when the order is processed.
Example: http://www.merchant.com
Special characters: $ ! = ? # & - _ / : .


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

ATTRIBUTES Description
digital_wallet
Alpha
max: 100
The buyer’s digital wallet.
Possible/ expected values: MASTERPASS
command
Alpha
max: 20
Command.
Possible/ expected values: AUTHORIZATION, PURCHASE
access_code
Alphanumeric
max: 20
Access code.
Example: zx0IPmPy5jp1vAz
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
amount
Numeric
max: 10
The transaction’s amount.
Example: 10000
currency
Alpha
max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
customer_email
Alphanumeric
max: 254
The customer’s email.
Example: customer@domain.com
cart_details
Alphanumeric
max: 999
This parameter is a parent parameter for other parameters that contain the details of the shopping cart created by the Merchant.
cart_items
Alphanumeric
max: 999
The items of the shopping cart.
Example: Tshirt
item_price
Numeric
max: 10
The price of a cart item.
Example: 700
sub_total
Numeric
max: 10
The total price of the cart items.
Example: 550
item_description
Alphanumeric
max: 256
A description of a cart’s item.
Example: iPhone 6-S
item_image
Alphanumeric
max: 500
A URL to the item’s image.
Example: https://www.image.com
item_name
Alphanumeric
max: 100
The name of an item in the shopping cart.
Example: Item1
item_quantity
Alphanumeric
max: 10
The quantity of a cart item.
Example: 4
signature
Alphanumeric
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
order_description
Alphanumeric
Max: 150
It holds the description of the order.
Example: iPhone 6-S
payment_option
Alpha
max: 10
Payment Option.
Possible/ expected values: MASTERCARD, VISA
customer_ip
Alphanumeric
max: 45
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
customer_name
Alpha
max: 40
The customer’s name.
Example: John Smith
response_message
Alphanumeric
Max: 150
The 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
authorization_code
Alphanumeric
Max: 100
The authorization code returned from the 3rd party.
Example: P1000000000000372136
status
Numeric
Max: 2
A two-digit numeric value that indicates the status of the transaction.
Possible/ expected values: Please refer to section statuses.
phone_number
Alphanumeric
max: 19
The customer’s phone number.
Example: 00962797219966
settlement_reference
Alphanumeric
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898
lightbox_callback_url
Alphanumeric
max: 400
The URL where MasterPass is redirected to the FORT.
lightbox_merchant_checkout_id
Alphanumeric
max: 100
When a Merchant is added to MasterPass, MasterPass generates this ID.
Example: a4a6w4cmliej1igb8j5ha1igi4spzo4xxx
lightbox_version
Alphanumeric
max: 5
The lightbox version to determine which version to be used.
Example: V2
lightbox_allowed_card_types
Alpha
max: 150
The card types supported by the Merchant. (A MasterPass parameter).
Example: MasterCard
lightbox_request_token
Alphanumeric
max: 100
A Token sent by MasterPass to identify the lightbox transaction. (A MasterPass parameter).
Example: 61c593e2b3524bc7694f893098cbb6dc8611b63a
return_url
Alphanumeric
max: 400
The URL of the Merchant’s page to be displayed to the customer when the order is processed.
Example: http://www.merchant.com

MasterPass Hosted

Masterpass Hosted accepts digital wallet transactions without redirection to Masterpass pages and instead; it will be hosted on the Merchant website.


Test Environment URL:

 https://sbcheckout.payfort.com/FortAPI/paymentPage

Production Environment URL:

 https://checkout.payfort.com/FortAPI/paymentPage


REST POST request using JSON.


(Please take a look at the Request Example on the right side of the page.)
Include the following parameters in the Request you will send to PayFort:

MasterPass Request Example

<form action="https://sbcheckout.payfort.com/FortAPI/paymentPage"method="post"id="simulatorForm">
<input type="hidden" name="digital_wallet" id="digital_wallet" value="MASTERPASS"/>
<input type="hidden" name="command"id="command" value="AUTHORIZATION"/>
<input type="hidden" name="access_code" id="access_code" value="zx0IPmPy5jp1vAz"/>
<input type="hidden" name="merchant_identifier" id="merchant_identifier" value="CycHZxVj"/>
<input type="hidden" name="merchant_reference" id="merchant_reference" value="XYZ9239-yu898"/>
<input type="hidden" name="amount" id="amount" value="10000"/>
<input type="hidden" name="currency" id="currency" value="AED"/>
<input type="hidden" name="language" id="language" value="en"/>
<input type="hidden" name="customer_email" id="customer_email" value="someone@email.com"/>
<input type="hidden" name="signature" id="signature" value="7cad05f0212ed933c9a5d5dffa31661acf2c827a"/>
<input type="hidden" name="payment_option"id="payment_option" value="VISA"/>
<input type="hidden" name="order_description" id="order_description" value="iPhone 6-S"/>
<input type="hidden" name="customer_ip" id="customer_ip" value="192.178.1.10"/>
<input type="hidden" name="oauth_verifier" id="oauth_verifier" value="ed91ead4afaa0c00673fe771c1027f247f7ddf04"/>
<input type="hidden" name="customer_name" id="customer_name" value="John Smith"/>
<input type="hidden" name="cart_details" id="cart_details" value='{"sub_total":"900","cart_items":[{"item_description":"Xbox","item_image":"http://image.com","item_name":"Xbo x 360","item_price":"300","item_quantity":"2"},{"item_description":"Playstation 3","item_image":"http://image.com","item_name":"Playstation 3","item_price":"150","item_quantity":"2"}]}'/>
<input type="hidden" name="return_url" id="return_url" value="http://backtothemerchanturl.com"/>
<input value="Send" type="submit"> </form>
ATTRIBUTES Description
digital_wallet
Alpha
Mandatory
max: 100
The buyer’s digital wallet.
Possible/ expected values: MASTERPASS
command
Alpha
Mandatory
max: 20
Command.
Possible/ expected values: AUTHORIZATION, PURCHASE
access_code
Alphanumeric
Mandatory
max: 20
Access code.
Example: zx0IPmPy5jp1vAz
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: - _ .
amount
Numeric
Mandatory
max: 10
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 10000
currency
Alpha
Mandatory
max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Mandatory
max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
customer_email
Alphanumeric
Mandatory
max: 254
The customer’s email.
Example: customer@domain.com
Special characters: _ - . @ +
oauth_verifier
Alphanumeric
Mandatory
max: 100
MasterPass transaction ID, returned by MasterPass light box response.
Example: ed91ead4afaa0c00673fe771c1027f247f7ddf04
cart_details
Alphanumeric
Mandatory
max: 999
This parameter is a parent parameter for other parameters that contain the details of the shopping cart created by the Merchant.
Example: please check the note below the table.
Special characters: $
cart_items
Alphanumeric
Mandatory
max: 999
The items of the shopping cart.
Example: Tshirt
Special characters: $
item_price
Numeric
Mandatory
max: 10
The price of a cart item.
Example: 700
sub_total
Numeric
Mandatory
max: 10
The total price of the cart items.
Example: 550
item_description
Alphanumeric
Mandatory
max: 256
A description of a cart’s item.
Example: iPhone 6-S
Special characters: - _ ' , . Space
item_image
Alphanumeric
Mandatory
max: 500
A URL to the item’s image.
Example: https://www.image.com
Special characters: # / : . = ? & - _
item_name
Alphanumeric
Mandatory
max: 100
The name of an item in the shopping cart.
Example: Item1
Special characters: Space
item_quantity
Alphanumeric
Mandatory
max: 10
The quantity of a cart item.
Example: 4
signature
Alphanumeric
Mandatory
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
order_description
Alphanumeric
Optional
Max: 150
It holds the description of the order.
Example: iPhone 6-S
Special characters: ' / . _ - # : $ Space
payment_option
Alpha
Optional
max: 10
Payment Option.
Possible/ expected values: MASTERCARD, VISA
customer_ip
Alphanumeric
Optional
max: 45
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
Special characters: . :
customer_name
Alpha
Optional
max: 40
The customer’s name.
Example: John Smith
Special characters: _ \ / - . ' Space
phone_number
Alphanumeric
Optional
max: 19
The customer’s phone number.
Example: 00962797219966
Special characters: + - ( ) Space
settlement_reference
Alphanumeric
Optional
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898
Special characters: - _ .
return_url
Alphanumeric
Optional
max: 400
The URL of the Merchant’s page to be displayed to the customer when the order is processed.
Example: http://www.merchant.com
Special characters: $ ! = ? # & - _ / : .


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

ATTRIBUTES Description
digital_wallet
Alpha
max: 100
The buyer’s digital wallet.
Possible/ expected values: MASTERPASS
command
Alpha
max: 20
Command.
Possible/ expected values: AUTHORIZATION, PURCHASE
access_code
Alphanumeric
max: 20
Access code.
Example: zx0IPmPy5jp1vAz
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
amount
Numeric
max: 10
The transaction’s amount.
Example: 10000
currency
Alpha
max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
customer_email
Alphanumeric
max: 254
The customer’s email.
Example: customer@domain.com
oauth_verifier
Alphanumeric
max: 100
MasterPass transaction ID, returned by MasterPass light box response.
Example: ed91ead4afaa0c00673fe771c1027f247f7ddf04
cart_details
Alphanumeric
max: 999
This parameter is a parent parameter for other parameters that contain the details of the shopping cart created by the Merchant.
cart_items
Alphanumeric
max: 999
The items of the shopping cart.
Example: Tshirt
item_price
Numeric
max: 10
The price of a cart item.
Example: 700
sub_total
Numeric
max: 10
The total price of the cart items.
Example: 550
item_description
Alphanumeric
max: 256
A description of a cart’s item.
Example: iPhone 6-S
item_image
Alphanumeric
max: 500
A URL to the item’s image.
Example: https://www.image.com
item_name
Alphanumeric
max: 100
The name of an item in the shopping cart.
Example: Item1
item_quantity
Alphanumeric
max: 10
The quantity of a cart item.
Example: 4
signature
Alphanumeric
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
order_description
Alphanumeric
Max: 150
It holds the description of the order.
Example: iPhone 6-S
payment_option
Alpha
max: 10
Payment Option.
Possible/ expected values: MASTERCARD, VISA
customer_ip
Alphanumeric
max: 45
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
customer_name
Alpha
max: 40
The customer’s name.
Example: John Smith
response_message
Alphanumeric
Max: 150
The 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
authorization_code
Alphanumeric
Max: 100
The authorization code returned from the 3rd party.
Example: P1000000000000372136
status
Numeric
Max: 2
A two-digit numeric value that indicates the status of the transaction.
Possible/ expected values: Please refer to section statuses.
phone_number
Alphanumeric
max: 19
The customer’s phone number.
Example: 00962797219966
settlement_reference
Alphanumeric
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898
lightbox_callback_url
Alphanumeric
max: 400
The URL where MasterPass is redirected to the FORT.
lightbox_merchant_checkout_id
Alphanumeric
max: 100
When a Merchant is added to MasterPass, MasterPass generates this ID.
Example: a4a6w4cmliej1igb8j5ha1igi4spzo4xxx
lightbox_version
Alphanumeric
max: 5
The lightbox version to determine which version to be used.
Example: V2
lightbox_allowed_card_types
Alpha
max: 150
The card types supported by the Merchant. (A MasterPass parameter).
Example: MasterCard
lightbox_request_token
Alphanumeric
max: 100
A Token sent by MasterPass to identify the lightbox transaction. (A MasterPass parameter).
Example: 61c593e2b3524bc7694f893098cbb6dc8611b63a
return_url
Alphanumeric
max: 400
The URL of the Merchant’s page to be displayed to the customer when the order is processed.
Example: http://www.merchant.com

Visa Checkout Service

Visa Checkout is a digital wallet that securely stores the buyer’s credit card details and shipping addresses and information, making shopping through thousands of online Merchants simple and convenient. This service enhances and simplifies the buyer’s online shopping experience. Visa Checkout can be offered through two different integrations:

Merchant Hosted Checkout Button

This integration allows the Merchant to host Visa Checkout button on his website giving him maximum control over the look and feel and user experience. The following steps describe how this integration works:

1. The Merchant should include the following JavaScript in the HTML header of its checkout page. This JavaScript loads the Visa Checkout library and defines handlers to initialization and payment events.

2. The Merchant should use the following class to render Visa Checkout button that a consumer clicks to initiate a payment.

Use the following URLs for test and production environments:

Test Environment URL:

https://sandbox.secure.checkout.visa.com/wallet-services-web/xo/button.png

Production Environment URL:

https://secure.checkout.visa.com/wallet-services-web/xo/button.png

3. The Merchant should use the following JavaScript to control the operation on Visa Checkout on the website.

Use the following URLs for test and production environments:

Test Environment URL:

https://sandbox-assets.secure.checkout.visa.com/checkout-widget/resources/js/integration/v1/sdk.js

Production Environment URL:

https://assets.secure.checkout.visa.com/checkout-widget/resources/js/integration/v1/sdk.js

4. After completing the previous steps, the consumer clicks on Visa Checkout button, Visa Checkout light box appears and the user complete the checkout process.

5. The Merchant receives a successful response. The response associated with the payment success event returns list of parameters. The Merchant has to collect the value of “call_id” parameter to be used in the following step.

6. The Merchant submits Purchase request to the FORT adding 2 extra parameters: digital-wallet, call_id. Please refer to Merchant Hosted Visa Checkout - Request for more details.

7. The Merchant system receives the FORT’s purchase request and then uses Visa Checkout update image pixel. Below you can find an example of how to use Visa Checkout update image pixel. Please refer to “Visa checkout PayFort documentation” for more details.

The following example shows an HTML web page that loads the Visa Checkout library, defines handlers for initialization and payment events, and creates a Visa Checkout button:

Include the following the parameters to the Merchant page operation - Request parameters.

ATTRIBUTES Description
digital_wallet
Alpha
Mandatory
max: 100
The buyer’s digital wallet.
Possible/ expected values: VISA_CHECKOUT
Special characters: _
call_id
Alphanumeric
Mandatory
max: 100
Visa Chekout transaction ID, returned by visa checkout light box response as “callId” parameter.
Example: 3000545511479392001

The following parameters will be returned in PayFort’s Response in additional to the Merchant page operation - Response parameters:

ATTRIBUTES Description
digital_wallet
Alpha
max: 100
The buyer’s digital wallet.
Possible/ expected values: VISA_CHECKOUT
call_id
Alphanumeric
max: 100
Visa Chekout transaction ID, returned by visa checkout light box response as “callId” parameter.
Example: 3000545511479392001

PayFort Hosted Checkout Button

This integration allows the Merchant to integrate Visa Checkout using PayFort hosted checkout button. The following steps describe how this integration works:
1. The user clicks on the pay button on the Merchant checkout page.
2. The Merchant submits an Authorization or Purchase request in addition to one extra parameter: digital_wallet. (Please refer to PayFort Hosted Visa Checkout - Request for more details).
3. The user is redirected to a page hosted on PayFort where Visa Checkout light-box page is displayed.

4. The user enters his credential and complete Visa Checkout process.
5. PayFort processes the transaction and return a valid response back to the Merchant.

Include the following parameter to the redirection request parameters (Please refer to Authorization/ Purchase – Request section)

ATTRIBUTES Description
digital_wallet
Alpha
Mandatory
max: 100
The buyer’s digital wallet.
Possible/ expected values: VISA_CHECKOUT
Special characters: _

The following parameters will be returned in PayFort’s Response in additional to the Authorization/ Purchase – Response parameters:

ATTRIBUTES Description
digital_wallet
Alpha
Mandatory
max: 100
The buyer’s digital wallet.
Possible/ expected values: VISA_CHECKOUT

Bill Presentment

This service allows the Merchant to generate a unique bill numbers for Customer’s orders using the FORT API. The Merchant displays or sends the unique bill number to the Customer. The Customer presents the unique bill number to PayFort’s payment partners to pay for his order.

Bill Presentment 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.

Bill Presentment - Request

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

ATTRIBUTES Description
service_command
Alpha
Mandatory
max: 20
Command.
Possible/ expected values: BILL_PRESENTMENT
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
merchant_reference
Alphanumeric
Mandatory
max: 40
The Merchant’s unique order number.
Example: XYZ2939-yu898
Special characters: - _ .
amount
Numeric
Mandatory
max: 10
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 10000
currency
Alpha
Mandatory
max: 3
The currency of the transaction’s amount in ISO code 3.
Possible/ expected values: EGP
language
Alpha
Mandatory
max: 2
The checkout page and messages language.
Possible/ expected values: en / ar
request_expiry_date
Alphanumeric
Mandatory
max: 25
The date when the bill expires.*The merchant will hold the item till the expiry date. If the customer didn’t pay, the holding will be canceled.
Example: 2017-12-20T15:36:55+03:00
Special characters: - + :
payment_partner
Alpha
Mandatory
max: 5
A financial corporation that generate bills to the customer.
Possible/ expected values: FAWRY
signature
Alphanumeric
Mandatory
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
customer_name
Alpha
Optional
Max: 40
The customer’s name.
Example: John Smith
Special characters: _ \ / - . ' Space
customer_email
Alphanumeric
Optional
Max: 254
The customer’s email.
Example: customer@domain.com
Special characters: _ - . @ +

Bill Presentment - Response

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

ATTRIBUTES Description
service_command
Alpha
max: 20
Command.
Possible/ expected values: BILL_PRESENTMENT
access_code
Alphanumeric
max: 20
Access code.
Possible/ expected Example: zx0IPmPy5jp1vAz
merchant_identifier
Alphanumeric
max: 20
The ID of the Merchant.
Example: CycHZxVj
merchant_reference
Alphanumeric
max: 40
The Merchant’s unique order number.
Example: XYZ2939-yu898
amount
Numeric
max: 10
The transaction’s amount.
Example: 10000
currency
Alpha
max: 3
The currency of the transaction’s amount in ISO code 3.
Possible/ expected values: EGP
language
Alpha
max: 2
The checkout page and messages language.
Possible/ expected values: en / ar
bill_number
Numeric
max: 14
A unique number generated by PayFort to pay bills.
Example: 14823285500005
request_expiry_date
Alphanumeric
max: 25
The date when the bill expires.*The merchant will hold the item till the expiry date. If the customer didn’t pay, the holding will be canceled.
Example: 2017-12-20T15:36:55+03:00
payment_partner
Alpha
max: 5
A financial corporation that generate bills to the customer.
Possible/ expected values: FAWRY
signature
Alphanumeric
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
customer_name
Alpha
Max: 40
The customer’s name.
Example: John Smith
customer_email
Alphanumeric
Max: 254
The customer’s email.
Example: customer1@domain.com
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: 46000
status
Numeric
Max: 2
A two-digit numeric value that indicates the status of the transaction.
Possible/ expected values: (Please refer to section statuses).

Invoicing Service

This service enables the Merchant to generate an invoice payment link. The Customer will be able to use this link to pay his invoices using any of the payment options that are configured for the Merchant.

Invoicing Service 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.

Invoicing Service - Request

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

ATTRIBUTES Description
service_command
Alpha
Mandatory
max: 20
Command.
Possible/ expected values: PAYMENT_LINK
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
merchant_reference
Alphanumeric
Mandatory
max: 40
The Merchant’s unique order number.
Example: XYZ9239-yu898
Special characters: - _ .
amount
Numeric
Mandatory
max: 10
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 100 USD=1.00 USD
currency
Alpha
Mandatory
max: 3
The currency of the transaction’s amount in ISO code 3.
Example: USD
language
Alpha
Mandatory
max: 2
The invoice and the received messages language.
Possible/ expected values: en / ar
customer_email
Alphanumeric
Mandatory
max: 254
The customer’s email.
Example: customer@domain.com
Special characters: _ - . @ +
request_expiry_date
Alphanumeric
Mandatory
max: 25
The invoice link expiry date.
Example: 2017-12-20T15:36:55+03:00
Special characters: + : -
notification_type
Alpha
Mandatory
max: 20
The way the Customer wants to use to get his notification. The Merchant can choose more than one way. * If the Customer chooses NONE with “EMAIL” or “SMS”, then the NONE will be taken as notification type.
Possible/ expected values:
- SMS
- EMAIL
- NONE
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
link_command
Alphanumeric
Optional
max: 15
Link operation to be executed.
Possible/ expected values: AUTHORIZATION/ PURCHASE
payment_link_id
Alphanumeric
Optional
max: 20
The ID of the generated Invoice payment link.
Example: 148708392700020346
Special characters: - _ .
payment_option
Alpha
Optional
max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
- SADAD (for Purchase operations only)
- NAPS (for Purchase operations only)
- KNET(for Purchase operations only)
- MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document
- MEEZA (for Purchase operations and ECOMMERCE eci only)
order_description
Alphanumeric
Optional
max: 150
It holds the description of the order.
Example: iPhone 6-S
Special characters: ' / . _ - # : $ Space
customer_name
Alpha
Optional
max: 40
The customer’s name.
Example: John Smith
Special characters: _ \ / - . ' Space
customer_phone
Numeric
Optional
max: 19
The Customer mobile number. It’s mandatory when selecting SMS as notification type.
Example: 00962797219966
return_url
Alphanumeric
Optional
max: 400
The URL of the Merchant’s page to be redirected to when the order is processed.
Example: http://www.merchant.com
Special characters:$ ! = ? # & _ - / : .

Invoicing Service - Response

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

ATTRIBUTES Description
service_command
Alpha
max: 20
Command.
Possible/ expected values: PAYMENT_LINK
access_code
Alphanumeric
max: 20
Access code.
Possible/ expected Example: zx0IPmPy5jp1vAz
merchant_identifier
Alphanumeric
max: 20
The ID of the Merchant.
Example: CycHZxVj
merchant_reference
Alphanumeric
max: 40
The Merchant’s unique order number.
Example: XYZ2939-yu898
amount
Numeric
max: 10
The transaction’s amount.
Example: 100 USD=1.00 USD
currency
Alpha
max: 3
The currency of the transaction’s amount in ISO code 3.
Example: USD
language
Alpha
max: 2
The invoice and received messages language.
Possible/ expected values: en / ar
customer_email
Alphanumeric
max: 254
The customer’s email.
Example: customer@domain.com
request_expiry_date
Alphanumeric
max: 25
The invoice link expiry date.
Example: 2017-12-20T15:36:55+03:00
notification_type
Alpha
max: 20
The way the Customer wants to use to get his notification. The Merchant can choose more than one way. *If the Customer chooses NONE with “EMAIL” or “SMS”, then the NONE will be taken as notification type.
Possible/ expected values:
- SMS
- EMAIL
- NONE
signature
Alphanumeric
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
link_command
Alphanumeric
max: 15
Link operation to be executed.
Possible/ expected values: AUTHORIZATION/ PURCHASE
payment_link_id
Alphanumeric
max: 20
The ID of the generated Invoice payment link.
Example: 148708392700020346
payment_link
Alphanumeric
max: 150
The generated invoice link notified to the Customer by one of the notification types, used to complete the payment process.
Example: https://checkout.payfort.com/dfc3d762
payment_option
Alpha
max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
- SADAD (for Purchase operations only)
- NAPS (for Purchase operations only)
- KNET(for Purchase operations only)
- MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document
- MEEZA (for Purchase operations and ECOMMERCE eci only)
order_description
Alphanumeric
max: 150
It holds the description of the order.
Example: iPhone 6-S
customer_name
Alpha
max: 40
The customer’s name.
Example: John Smith
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 is made up of five digits, the first 2 digits refer to the request status, and the last 3 digits refer to the request messages.
Example: 20064
status
Numeric
max: 2
A two-digit numeric value that indicates the status of the transaction.
Possible/ expected values: statuses
customer_phone
Numeric
max: 19
The Customer mobile number.
Example: 00962797219966
return_url
Alphanumeric
max: 400
The URL of the Merchant’s page to be redirected to when the order is processed.
Example: http://www.merchant.com
ATTRIBUTES Description
command
Alpha
Max: 20
A command.
Possible/ expected values: AUTHORIZATION, PURCHASE
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
amount
Numeric
Max: 10
The transaction’s amount.
Example: 10000
currency
Alpha
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
customer_email
Alphanumeric
Max: 254
The customer’s email.
Example: customer1@domain.com
signature
Alphanumeric
Max: 200
A string hashed using the Secure Hash Algorithm. Please refer to section Signature
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
payment_link_id
Alphanumeric
max: 20
The ID of the generated Invoice payment link.
Example: 148708392700020346
token_name
Alphanumeric
max: 100
The Token received from the Tokenization process.
Example: Op9Vmp
fort_id
Numeric
Max: 20
The order’s unique reference returned by our system.
Example: 149295435400084008
payment_option
Alpha
Max: 10
Payment option.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
- SADAD (for Purchase operations only)
- NAPS (for Purchase operations only)
- KNET(for Purchase operations only)
- MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document
- MEEZA (for Purchase operations and ECOMMERCE eci only)
sadad_olp
Alphanumeric
Max: 12
SADAD Online Payment ID Alias. The merchant sends this value if the OLP ID is collected on the merchant checkout.
Example: SABBP2P_UAT2
eci
Alpha
Max: 16
The E-commerce indicator.
Possible/ expected values:
- ECOMMERCE
- MOTO
order_description
Alphanumeric
Max: 150
It holds the description of the order.
Example: iPhone 6-S
customer_ip
Alphanumeric
max: 45
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below.
Example:
IPv4 → 192.178.1.10
IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf
customer_name
Alpha
Max: 40
The customer’s name.
Example: John Smith
merchant_extra
Alphanumeric
Max: 999
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra1
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra2
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra3
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra4
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
merchant_extra5
Alphanumeric
Max: 250
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report.
Example: JohnSmith
authorization_code
Alphanumeric
Max: 100
The authorization code returned from the 3rd party.
Example: P1000000000000372136
response_message
Alphanumeric
Max: 150
The 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
card_holder_name
Alpha
Max: 50
The card holder name.
Example: John Smith
expiry_date
Numeric
Max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
Max: 19
The masked credit card’s number.
Only the MEEZA payment option takes 19 digits card number.
*AMEX payment option takes 15 digits card number.
*Otherwise, they take 16 digits card number.

Example: 400555
*****0001
remember_me
Alpha
Max: 2
This parameter provides you with an indication to whether to save this token for the user based on the user selection.
Possible/ expected values: NO
phone_number
Alphanumeric
max: 19
The customer’s phone number.
Example: 00962797219966
settlement_reference
Alphanumeric
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898

Batch Service

This service allows the Merchant to process requests to FORT in bulk as a batch.

Before Starting

Before starting you have to know the following:
1. You’re only allowed to send one of the following transactions in your batch file or a mixture of them:
    * Recurring: PURCHASE command.
    * Maintenance operations (capture, refund, and void authorization): after completing a successful Authorization or Purchase transactions through one of PayFort’s channels.
2. You should active the Batch processing service.

How it works - Steps

1. Upload Batch File:
This request allows the Merchant to upload the batch file to FORT system.

2. Get Batch Results:
This request allows the Merchants to validate the format of the file and to check that the merchant reference for each and every transaction is unique.

3. Process Batch File:
This request allows the Merchant to initiate the processing of transactions. In order to start the processing; the file should have been validated and passed the validation process.

Upload Batch file

This request allows the Merchant to upload the Batch file to the FORT system. The Merchant will specify the order of the fields in the batch file.

Upload Batch File URLs

Test Environment URL:

https://sbbatch.payfort.com/integration-batch/upload/

Production Environment URL:

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

Parameters Submission Type

Form Post Request.

Upload Batch File - Request

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

ATTRIBUTES Description
service_command
Alpha
Mandatory
Max: 20
Command.
Possible/ expected values: UPLOAD_BATCH_FILE
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
batch_reference
Alphanumeric
Mandatory
Max: 20
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
file
Alphanumeric
Mandatory
Max: 50
The file that contain a batch of transactions. The file should be of type CSV.
Example: test.csv
Special characters: . - ! @ # $ % ^ & ( ) _ + , Space
signature
Alphanumeric
Mandatory
Max: 200
A string hashed using the Secure Hash Algorithm. Please refer to section Signature
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a

Upload Batch File - Response

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

ATTRIBUTES Description
service_command
Alpha
Max: 20
Command.
Possible/ expected values: UPLOAD_BATCH_FILE
access_code
Alphanumeric
Max: 20
Access code.
Example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier
Alphanumeric
Max: 20
The ID of the Merchant.
Example: CycHZxVj
batch_reference
Alphanumeric
Max: 20
The Merchant’s unique order number.
Example: XYZ9239-yu898
language
Alpha
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
batch_id
Numeric
Max: 20
The Merchant’s unique batch ID.
Example: 150754364000030895
signature
Alphanumeric
Mandatory
Max: 200
A string hashed using the Secure Hash Algorithm. Please refer to section Signature
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
response_message
Alphanumeric
Max: 150
The 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: 50000
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 Batch Results

This request allows the Merchants to validate the format of the file and to check that the merchant reference for each and every transaction is unique.

Get Batch Results URLs

Test Environment URL:

https://sbbatch.payfort.com/integration-batch/batchApi/

Production Environment URL:

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

Parameters Submission Type

REST POST request using JSON.

Get Batch Results - Request

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

ATTRIBUTES Description
service_command
Alpha
Mandatory
Max: 20
Command.
Possible/ expected values: GET_BATCH_RESULTS
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
batch_reference
Alphanumeric
Mandatory
Max: 20
The Merchant’s unique order number. *You have to use the same batch reference you used in the upload_batch_file.
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
batch_id
Numeric
Optional
Max: 20
The Merchant’s unique batch ID returned when uploading a file successfully.
Example: 150754364000030895

Get Batch Results - Response

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

ATTRIBUTES Description
service_command
Alpha
Max: 20
Command.
Possible/ expected values: GET_BATCH_RESULTS
access_code
Alphanumeric
Max: 20
Access code.
Example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier
Alphanumeric
Max: 20
The ID of the Merchant.
Example: CycHZxVj
batch_reference
Alphanumeric
Max: 20
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
Mandatory
Max: 200
A string hashed using the Secure Hash Algorithm. Please refer to section Signature
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
batch_id
Numeric
Max: 20
The Merchant’s unique batch ID.
Example: 150754364000030895
transactions_count
Numeric
Max: 10
A parameter that counts the total number of transactions inside the file.
Example: 9
response_message
Alphanumeric
Max: 150
The 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: 70000
status
Numeric
Max: 2
A two-digit numeric value that indicates the status of the transaction.
Possible/ expected values: Please refer to section statuses

Process Batch file

This request allows the merchant to initiate the processing of transactions. In order to start processing; the file should have been validated and passed the validation successfully.

Process Batch File URLs

Test Environment URL:

https://sbbatch.payfort.com/integration-batch/batchApi/

Production Environment URL:

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

Parameters Submission Type

REST POST request using JSON.

Process Batch File - Request

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

ATTRIBUTES Description
service_command
Alpha
Mandatory
Max: 20
Command.
Possible/ expected values: PROCESS_BATCH
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
batch_reference
Alphanumeric
Mandatory
Max: 20
The Merchant’s unique order number. *You have to use the same batch reference you used in the upload_batch_file.
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
batch_id
Numeric
Optional
Max: 20
The Merchant’s unique batch ID returned when uploading a file successfully.
Example: 150754364000030895

Process Batch File - Response

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

ATTRIBUTES Description
service_command
Alpha
Max: 20
Command.
Possible/ expected values: PROCESS_BATCH
access_code
Alphanumeric
Max: 20
Access code.
Example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier
Alphanumeric
Max: 20
The ID of the Merchant.
Example: CycHZxVj
batch_reference
Alphanumeric
Max: 20
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
Mandatory
Max: 200
A string hashed using the Secure Hash Algorithm. Please refer to section Signature
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
batch_id
Numeric
Max: 20
The Merchant’s unique batch ID.
Example: 150754364000030895
response_message
Alphanumeric
Max: 150
The 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: 72147
status
Numeric
Max: 2
A two-digit numeric value that indicates the status of the transaction.
Possible/ expected values: Please refer to section statuses

After processing the batch file successfully; you can send “Get Batch Results – Request” again to see the final status for each transaction inside the file.

Batch Invoicing

This service allows the Merchant to upload a bulk of invoices to FORT as a batch.

Before Starting

Before starting you have to know the following:
1. You’re only allowed to send PAYMENT_LINK service command in the invoice batch file.
2. You should active the Batch processing and invoicing services.
3. You can download the invoice batch file template from the Back office by clicking on the “Batch invoicing” tab that will appears only if you were active the batch and invoicing services.

How it Works

1. Upload Invoicing Batch File:
This request allows the Merchant to upload the invoice batch file to FORT system. You can download the invoice batch file template from your back office.

2. Get Invoicing Batch Results:
This request allows the Merchants to validate the format of the file and to check that the merchant reference for each and every transaction is unique. After validation the “Account Administrator” will receive an email notification with success invoices count.

3. Process Invoicing Batch File:
This request allows the Merchant to initiate the processing of transactions. In order to start the processing; the file should have been validated and passed the validation process. After processing the “Account Administrator” will receive an email notification with success invoices count.

Reporting API

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

Verify Service Command

Verify Service Command

Verify API provides several methods that you can use to determine if a particular card account is valid and in good standing. The ability to pre-validate a credit card (Visa, MasterCard and Amex) increases the probability of a successful, seamless transaction flow and more valid card registration.

Before Starting

Before start integrating this service you need to know the below:
• This service command is applicable on two channels only; where you have to configure the channel you want to add this service to it from the FORT back-office:
    1. Merchant page.
    2. Trusted.
• This service command is only applicable on “MOTO” E-commerce indicator.
• You need to add the amount to be Authorized/ Captured from the customer for the verification.
• This Authorized/ Captured amount will be Voided/ Refunded after checking the card validity.
• The verification transactions will be recorded under one report “Card Verification Report” in the back-office.

Verify Service Command on Trusted 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.

Verify Service Command on Trusted - Request

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

ATTRIBUTES Description
service_command
Alpha
Mandatory
max: 20
Command.
Possible/ expected values: VERIFY_CARD
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: _ - .
currency
Alpha
Mandatory
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Mandatory
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
expiry_date
Numeric
Mandatory
max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
Mandatory
max: 16
The clear credit card’s number.
Example: 4005550000000001
signature
Alphanumeric
Mandatory
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
settlement_reference
Alphanumeric
Optional
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: example
Special characters: _ - .

Verify Service Command on Trusted Request Example

Verify Service Command on Trusted - Response

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

ATTRIBUTES Description
service_command
Alpha
max: 20
Command.
Possible/ expected values: VERIFY_CARD
Special characters: _
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
Special characters: _ - .
currency
Alpha
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: AED
language
Alpha
Max: 2
The checkout page and messages language.
Possible/ expected values: en/ ar
expiry_date
Numeric
max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
max: 16
The masked credit card’s number.
Example: 400555******0001
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_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: 80000
status
Numeric
max: 2
A two-digit numeric value that indicates the status of the transaction
Possible/ expected values: (Please refer to section statuses).
settlement_reference
Alphanumeric
max: 34
The Merchant submits this value to the FORT. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: example

Verify Service Command on Trusted Response Example

Check Status for Verify Service Command

This feature allows the Merchants to easily check the actual status of the “Verify card command” results through this API.

Check Status for Verify Service Command 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 for Verify Service - 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: CHECK_VERIFY_CARD_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 number. *Please, use the same merchant reference you used in the “generate report” request.
Example: XYZ9239-yu898
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 for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a

Check Status on Verify Service Command Request Example

Check Status for Verify Service Command - Response

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

ATTRIBUTES Description
query_command
Alpha
max: 50
Query operations command.
Possible/ expected values: CHECK_VERIFY_CARD_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 reference for a specific request.
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 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).
transaction_status
Numeric
max: 2
The status of the last verify operation performed on a specific card.
Possible/ expected values: (Please refer to section statuses).
transaction_message
Alphanumeric
Max: 150
The message returned for the last verify operation performed on a specific card.
Example: success

Check Status on Verify Service Command Response Example

Other Payfort Services

FORT Tokenization Service

The Tokenization service allows the Merchant to store the Customer’s credit card details in a safe and secure environment substituting the Customer’s sensitive card details with a non-sensitive equivalent referred to as a Token. The Token can be used to process transactions without the use of the card details.

Create Token in Transaction Flow

To create a new Token, include the following parameter in the Authorization/ Purchase Request parameters you will send to PayFort; the same parameter will hold the Token name in PayFort’s Response:

ATTRIBUTES Description
token_name
Alphanumeric
Optional
max: 100
Holds the name of the Token to update the Token or rename it.
Example: OpVmp
Special characters: . @ - _

Create New Token Service

This service allows Merchants to verify and tokenize their Customer’s credit cards without charging their Customers.

Test Environment URL:

https://sbcheckout.PayFort.com/FortAPI/paymentPage

Production Environment URL:

https://checkout.PayFort.com/FortAPI/paymentPage

HTTPs Form Post Request.

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

ATTRIBUTES Description
service_command
Alpha
Mandatory
Max: 20
Command.
Possible/ expected values: CREATE_TOKEN
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
card_number
Numeric
Mandatory
Max: 19
The clear card data collect on the Merchant page form, developed by the Merchant.
*Only the MEEZA payment option takes 19 digits card number.
*AMEX payment option takes 15 digits card number.
*Otherwise, they take 16 digits card number
Example: 4005550000000001
expiry_date
Numeric
Mandatory
Max: 4
The card’s expiry date.
Example: 2105
return_url
Alphanumeric
Mandatory
Max: 400
The URL of the Merchant’s page that will be displayed to the customer when the order is processed.
Example: http://www.merchant.com
Special characters: $ ! = ? # & - _ / : .
signature
Alphanumeric
Mandatory
Max: 200
A string hashed using the Secure Hash Algorithm. Please refer to section Signature
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
currency
Alpha
Optional
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: USD
token_name
Alphanumeric
Optional
Max: 100
The Token received from the Tokenization process.
Example: Op9Vmp
Special characters: . @ - _
card_holder_name
Alpha
Optional
Max: 50
The card holder name.
Example: John Smith
Special characters: ' - .

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

ATTRIBUTES Description
service_command
Alpha
Max: 20
Command.
Possible/ expected values: CREATE_TOKEN
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
card_number
Numeric
Max: 19
The masked credit card’s number.
Only the MEEZA payment option takes 19 digits card number.
*AMEX payment option takes 15 digits card number.
*Otherwise, they take 16 digits card number
Example: 400555
*****0001
expiry_date
Numeric
Max: 4
The card’s expiry date.
Example: 2105
return_url
Alphanumeric
Max: 400
The URL of the Merchant’s page that will be displayed to the customer when the order is processed.
Example: http://www.merchant.com
signature
Alphanumeric
Max: 200
A string hashed using the Secure Hash Algorithm. Please refer to section Signature
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
currency
Alpha
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: USD
token_name
Alphanumeric
Max: 100
The Token received from the Tokenization process.
Example: Op9Vmp
card_holder_name
Alpha
Max: 50
The card holder name.
Example: John Smith
response_message
Alphanumeric
Max: 150
The 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

Update Token Service

This service enables you to update your card associated with a token and the status of a token via API calls.

Test Environment URL:

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

Production Environment URL:

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

REST POST request using JSON.

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

ATTRIBUTES Description
service_command
Alpha
Mandatory
Max: 20
Command.
Possible/ expected values: UPDATE_TOKEN
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
token_name
Alphanumeric
Mandatory
Max: 100
The token received from the Tokenization process.
Example: Op9Vmp
Special characters: . @ - _
signature
Alphanumeric
Mandatory
Max: 200
A string hashed using the Secure Hash Algorithm. Please refer to section Signature
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
expiry_date
Numeric
Optional
Max: 4
The card’s expiry date.
Example: 2105
card_holder_name
Alpha
Optional
Max: 50
The card holder name.
Example: John Smith
Special characters: ' - .
currency
Alpha
Optional
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: USD
token_status
Alpha
Optional
Max: 8
Presents the token status.
Possible/ expected values:
- ACTIVE
- INACTIVE
new_token_name
Alphanumeric
Optional
Max: 100
The new name used to update the existing token.
Example: Test1
Special characters: _ - @ .

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

ATTRIBUTES Description
service_command
Alpha
Max: 20
Command.
Possible/ expected values: UPDATE_TOKEN
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
token_name
Alphanumeric
Max: 100
The Token received from the Tokenization process.
Example: Op9Vmp
signature
Alphanumeric
Max: 200
A string hashed using the Secure Hash Algorithm. Please refer to section Signature
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
expiry_date
Numeric
Max: 4
The card’s expiry date.
Example: 2105
card_number
Numeric
Max: 19
The masked credit card’s number.
Only the MEEZA payment option takes 19 digits card number.
*AMEX payment option takes 15 digits card number.
*Otherwise, they take 16 digits card number
Example: 400555
*****0001
card_holder_name
Alpha
Max: 50
The card holder name.
Example: John Smith
currency
Alpha
Max: 3
The currency of the transaction’s amount in ISO code 3.
Example: USD
response_message
Alphanumeric
Max: 150
The 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: 58000
token_status
Alpha
Max: 8
Presents the token status.
Possible/ expected values:
-ACTIVE
-INACTIVE
creation_date
Alphanumeric
Max: 30
Creation date of content in UTC format.
Example: 2017-03-13T10:09:19+02:00
card_brand
Alpha
Max: 10
Issuer account type.
Possible/ expected values:
- MASTERCARD
- VISA
- AMEX
card_bin
Numeric
Max: 8
The first 6 digits of the card number.*If the card number for MEEZA was of length 19 then the card bin will be the first 8 digits.
Example: 478773
status
Numeric
Max: 2
A two-digit numeric value that indicates the status of the transaction.
Possible/ expected values: Please refer to section statuses

Currency Exchange Service

This service allows the merchant to convert the transaction amount from one currency into another currency using live currency exchange rate.

Currency Exchange 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.

Currency Exchange - Request

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

ATTRIBUTES Description
service_command
Alpha
Mandatory
max: 20
Command.
Possible/ expected values: CURRENCY_CONVERSION
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
amount
Numeric
Mandatory
max: 10
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount.
Example: 10000
currency
Alpha
Mandatory
max: 3
The currency of the transaction’s amount in ISO code 3.
Example: USD
language
Alpha
Mandatory
max: 2
The checkout page and messages language.
Possible/ expected values: en / ar
converted_currency
Alpha
Mandatory
max: 3
The ISO3 currency code of the currency you are converting the amount to.
Example: AED
signature
Alphanumeric
Mandatory
max: 200
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a

Currency Exchange - Response

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

ATTRIBUTES Description
service_command
Alpha
max: 20
Command.
Possible/ expected values: CURRENCY_CONVERSION
access_code
Alphanumeric
max: 20
Access code.
Example: zx0IPmPy5jp1vAz
merchant_identifier
Alphanumeric
max: 20
The ID of the Merchant.
Example: CycHZxVj
amount
Numeric
max: 10
The transaction’s amount.
Example: 10000
currency
Alpha
max: 3
The currency of the transaction’s amount in ISO code 3.
Example: USD
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 for more details).
Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
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).
converted_amount
Alpha
max: 3
The amount after converting to another currency.
Example: 100 USD = 367.298 AED
converted_currency
Alpha
max: 3
The ISO3 currency code of the currency you are converting the amount to.
Example: AED
conversion_number
Alphanumeric
max: 20
A unique number generated by PayFort for every valid currency conversion request.
Example: 1443796866848

In Common

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
return_third_party_response_codes
Alpha
Optional
Max: 3
This parameter allows you to return the 3rd party response codes in the transaction’s response.
Possible/ expected values:
- YES
- NO

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
authorization_code
Alphanumeric
Max: 100
Authorization Code returned from the 3rd party.
Example: 017201
processor_response_code
Alphanumeric
Max: 100
Response code returns from the Processor.
Example: APPROVED
acquirer_response_code
Alphanumeric
Max: 10
Response code returns from the Acquirer.
Example: 00

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

<?php
// How to calculate request signature
$shaString  = '';
// array request
$arrData    = array(
'command'            =>'AUTHORIZATION',
'access_code'        =>'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier'=>'CycHZxVj',
'merchant_reference' =>'XYZ9239-yu898',
'amount'             =>'10000',
'currency'           =>'AED',
'language'           =>'en',
'customer_email'     =>'test@payfort.com',
'order_description'  =>'iPhone 6-S',
);
// sort an array by key
ksort($arrData);
foreach ($arrData as $key => $value) {
    $shaString .= "$key=$value";
}
// make sure to fill your sha request pass phrase
$shaString = "YOUR_SHA_REQUEST_PASSPHRASE" . $shaString . "YOUR_SHA_REQUEST_PASSPHRASE";
$signature = hash("YOUR_SHA_TYPE", $shaString);
// your request signature
echo $signature;
?>
Map<String, Object>requestMap = new HashedMap();
    requestMap.put("command", "PURCHASE");
    requestMap.put("merchant_reference", "Test010");
    requestMap.put("amount", "1000");
    requestMap.put("access_code", "SILgpo7pWbmzuURp2qri");
    requestMap.put("merchant_identifier", "MxvOupuG");
    requestMap.put("currency", "USD");
    requestMap.put("language", "en");
    requestMap.put("customer_email", "test@gmail.com");

//order by key
requestMap = requestMap.entrySet().stream().sorted(Map.Entry.comparingByKey())
          .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue,
          (oldValue, newValue) -> oldValue, LinkedHashMap::new));

String requestString = "PASS";
for(Entry<String, Object> entry: requestMap.entrySet())
    requestString += entry.getKey() + "=" + entry.getValue();  
requestString+= "PASS";

MessageDigest digest = MessageDigest.getInstance("SHA-256");
byte[] hashed = digest.digest(requestString.getBytes(StandardCharsets.UTF_8));
String signature = javax.xml.bind.DatatypeConverter.printHexBinary(hashed);

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:

*The following is an example for the Reporting API request signature calculations: *

*Assume you have the below parameters included in the request of Reporting API: *

• query_command = GENERATE_REPORT • access_code = zx0IPmPy5jp1vAz8Kpg7 • merchant_identifier = CycHZxVj • merchant_reference = XYZ9239-yu898 • columns = [order_description, customer_ip, eci, geolocation_ip, merchant_reference, card_holder_name, currency, amount, payment_option, fort_id, customer_email, customer_name, operation] • filters = [{key=currency, value=USD}, {key=payment_option, value= VISA}] • from_date = 2017-08-03T00:00:01+03:00 • to_date = 2017-08-03T23:59:59+03:00 • response_format = JSON • language = en

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.
44 3ds success.
45 3ds 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.
80 Credit card verified successfully.
81 Failed to verify credit card.

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”.

FORT Transaction Feedback

Overview

The FORT transaction Feedback system provides Merchants with two types of configurable notifications:
1. Direct Transaction Feedback, PayFort will send Merchants HTTPs notifications that inform Merchants of the transaction’s final status whenever a transaction is processed.
2. Notification Transaction Feedback, PayFort will send Merchants HTTPs notifications that inform Merchants of the transaction’s final status whenever a transaction status is updated.

Registering Transaction Feedback URLs

1. Log in to your back-office account.
2. Select the active channel under Integration Settings > Technical Settings.
3. Enter your Direct Transaction Feedback URL and Notification Transaction Feedback URL.
4. Click “Save Changes” button.

Transaction Feedback implementation

The Transaction Feedback URL is required to send the Merchant the response parameters after processing the transaction on the Merchant’s server side.
For the Direct Transaction Feedback, it sends the immediate payments response in all cases , like if the user closed the browser before getting redirected to the Redirection URL due to a drop in the internet connection or he closed the browser during the Redirection , the Merchant will create an endpoint which accepts the notifications received from PayFort side as POST Method.
For the Notification Transaction Feedback , it’s required to provide the Merchant the transaction final status update whenever received , like if the Transaction was pending due to the unavailability for any party , the final update will be pushed to the Notification Feedback URL as POST Method.
Beyond whatever your Transaction Feedback URL does with the data received, it must also return a 2xx (like 200 , 201 , etc…) or 302 HTTP status code to update the FORT system that the notification was received. If your URL does not return 2xx or 302, the FORT will continue to retry the notification for 10 times with 10 seconds in between until it’s properly acknowledged.
Beyond whatever your Transaction Feedback URL does with the data received, it must also return a 2xx (like 200 , 201 , etc…) or 302 HTTP status code to update the FORT system that the notification was received. If your URL does not return 2xx or 302, the FORT will continue to retry the notification for 10, times with 10 seconds in between until it’s properly acknowledged.