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 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
- Native in-app payment.
- Fully secure.
- Fully customized.
Download
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
Supported Platforms
The first version of the solution is available only for the Android OS.
The FORT Mobile SDK supports all devices running Android (Ice cream sandwich) v4 up to (Android Q) v10.
Localization
The FORT Mobile SDK supports both English and Arabic languages.
Screen Orientation
Portrait is the only orientation supported within the FORT Mobile SDK.
Supported Payment Methods
Through the first version of the FORT Mobile SDK, the Merchant has the ability to process a CREDIT CARD transactions only.
Supported Payment Options
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.6.aar-release.
Android Studio
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.
Eclipse
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
Collect the FORT Mobile SDK Request
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;
}
}
- The “requestMap” must contain all the FORT parameters of the order/ transaction.
- “showResponsePage” is the Boolean field where you can determine if you want the FORT response page to be displayed or not.
Define a Callback Manager
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();
Attach the Callback to the Activity
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);
}
Call the FORT Mobile SDK
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. |
FORT Mobile SDK Device ID Value
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);
Customizing the Mobile SDK Payment Layout
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.
- Design Customization Codes:
The following code was used to customize the way the “Amount” is displayed in the Standard Mobile SDK Payment Page:
The following code was used to customize the way the “Amount” is displayed in the Customized Mobile SDK Payment Page:
- As appears in the previous codes, elements with IDs haven’t been changed in type or removed. For example: android:id=“@+id/amountTV”.
- We were able to add static elements such as: ImageView element that contains the Merchant’s logo, and TextView that contains the Merchant’s name.
- To sum up, you can add any static elements or redesign the view, while keeping the views’ elements used in the Standard layout that hold IDs.
SDK Operations
The FORT Mobile SDK allows the Merchant’s application to process Authorization and Purchase operations.
Operations Request
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 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: - _ . |
| 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: . ; / _ - , ' @ |
Operations Response
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 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 |
| 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 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.
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).
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.
- Call getDeviceID on a previous activity or in your application class to make sure that the permission request was triggered before you reach the payment step.
Sample code
Integrate iOS SDK
To process a transaction using the FORT Mobile SDK, create a Mobile SDK Token (Please refer to section Create SDK Token) and proceed through the following sections.
About the Software
Supported Platforms
IOS 8+
Localization
The FORT Mobile SDK supports both English and Arabic languages.
Screen Orientation
Portrait is the only orientation supported within the FORT Mobile SDK.
Supported Payment Methods
Through the first version of the FORT Mobile SDK, the Merchant has the ability to process a CREDIT CARD transactions only.
Supported Payment Options
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
Objective C
(void)applicationDidEnterBackground:(UIApplication *)application {
__block UIBackgroundTaskIdentifier backgroundTask; backgroundTask =
[application beginBackgroundTaskWithExpirationHandler: ^ {
[application endBackgroundTask:backgroundTask];
backgroundTask = UIBackgroundTaskInvalid; }];
Swift
func applicationDidEnterBackground(_ application: UIApplication) {
var bgTask: UIBackgroundTaskIdentifier = 0
bgTask = application.beginBackgroundTask(expirationHandler: {
application.endBackgroundTask(bgTask)
bgTask = UIBackgroundTaskInvalid
})
}
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:
- Create your nibFile .xib and set the name of Arabic xib same name with English one with suffix -ar.
- Link the xib with PayFortView and bind all the IBOutlets in interface section
- Assign new created xib file to PayFort Controller.
FORT Mobile SDK Operations
The FORT Mobile SDK allows the Merchant’s application to process Authorization and Purchase operations.
FORT Mobile SDK 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 |
| 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 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: - _ . |
| 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: . ; / _ - , ' @ |
FORT Mobile SDK Operations - Response
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 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 |
| 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 |
| 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 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.
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.
Sample Code
Initialize the Mobile SDK
Objective-C
Swift