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 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 requires to test your integration before going live to verify the integration and make sure it’s implemented properly.
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.
FORT Tokenization Service 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.
Create New Token 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: 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: https://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: ' - . |
Create New Token Service - Response
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: https://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.
Update Token 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.
Update Token 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: 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 |
| 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: _ - @ . |
Update Token Service – Response
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 |
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.