NAV Navbar
Logo
PHP Python Ruby

Before Starting the Integration

These are the steps you need to know; to start building an integration with PayFort:

Step 1: Access your test account
You have to make sure that you have an access to a test account, its a full test environment allow you to simulate and process simulation transactions.

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 under every section in the API document.

Step 3: Create the transaction request
Process the 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 every payment, PayFort return the transaction response on the URL configured in your account under Technical Settings channel configuration.

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

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 team may require to test your integration before going live to assure your application integration.

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.
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: . @ - _

<<<<<<< HEAD

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) |

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 only) |

afab9efee05062736a63157e6b5a09357f9ac5ba 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. 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| 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: . ; / _ - , ’ @| 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 unique value to Amazon Payment Services. 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: https://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

<<<<<<< HEAD

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) |

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 only) |

afab9efee05062736a63157e6b5a09357f9ac5ba 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 | 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: 16 | The clear credit card’s 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 unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file.
Example: XYZ9239-yu898 |

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 submission

The FORT will send Transaction Feedback data as form POST Parameters to the Merchant’s Transaction Feedback URLs.
However if you want to change the submission type to JSON or XML, you can contact us on integration@payfort.com.
This configuration can be enabled by internal PayFort team only
The specifics of the data will differ based upon the financial operation that has been processed.
Please refer to the FORT integration guide for more details.

Responding to FORT Transaction Feedback

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 tell the FORT that the notification was received. If your URL does not return 2xx or 302, the FORT will continue to retry the notification until it’s properly acknowledged.
In case the FORT does not receive 200 or 302 HTTP status code it will attempt to send the notification for 10 times with 10 seconds in between.
This configuration is editable as well, if you want to change the grace period or the time interval between the retries please contact us on integration@payfort.com.