NAV Navbar
Logo

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.

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

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: 93eec76cbedaedca44648e3d5c314766906e4e78ce33cd3b8396f105a1c0daed
apple_ephemeralPublicKey
Alphanumeric
Mandatory
max: 200
Ephemeral public key bytes.
Example: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEM9JqF04vDlGI…
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: 5173d4e05f2e07dc4e7ea9669bda185712ffffe1d6cfce2d4e854d7661e70d67…
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

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