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.
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
- No Customer redirection.
- No PCI-Compliance needed.
- A replica of your website appearance and your payment flow.
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: https://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: https://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 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 to be displayed to the customer when the order is processed. Example: https://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: https://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 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 |
| billing_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. |
| billing_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
| billing_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
| billing_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
| billing_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
| billing_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
| billing_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
| billing_city Alphanumeric Optional max: 100 |
The city portion of the address. |
| shipping_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. |
| shipping_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
| shipping_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
| shipping_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
| shipping_source Alphanumeric Optional |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
| shipping_sameAsBilling Alphanumeric Optional |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
| shipping_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
| shipping_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
| shipping_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
| shipping_city Alphanumeric Optional max: 100 |
The city portion of the address. |
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.
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.
Merchant Page Customization
This is a list with all customizable CSS classes on the basic merchant page:
- The
Wrapperclass: responsible for the total width of the form container and the background. - The
Containerclass: responsible for the form’s shape and width. - The
Popoverclass: responsible for the error messages. - The
Half-containerclass: used to merge the date and CVV fields into one block if needed. - The
Inputclass: is the container of each single input field. - The
Payclass: responsible for the submit button. - The
Visa/ MasterCardclasses: used to change the color of the Visa/ MasterCard colors.