Before Starting the Integration
These are the steps you need to know; to start building an integration with PayFort:
Step 1: Access your test account
You have to make sure that you have an access to a test account, its a full test environment allow you to simulate and process simulation transactions.
Step 2: make sure that you are using the correct integration type
Before building the integration, you need to make sure that you are selecting and using the proper parameters in the API calls as per the required integration type.
All the mandatory parameters mentioned under every section in the API document.
Step 3: Create the transaction request
Process the valid API request depends on transaction parameters included, you need to check the documentation and read every parameter possible values in order to reduce the errors in processing the transaction.
Step 4: Process the transaction response
After every payment, PayFort return the transaction response on the URL configured in your account under Technical Settings channel configuration.
You can find more details in the API documentation section Direct Transaction Feedback.
You need to validate the response parameters returned on this URL by calculating the signature for the response parameters using the SHA Response Phrase configured in your account under Security Settings.
Step 5: Test and Go Live
You can use our testing cards to test your integration and simulate your test cases.
PayFort team may require to test your integration before going live to assure your application integration.
Redemption Service
This service allows Merchant to redeem point or monetary value in exchange for goods, services or Merchant credits. For example, redeeming a Gift Card that will be used to top up the user account balance or in exchange for goods or services the Merchant is offering in return.
Redemption Service - Overview
There are two ways to integrate the redemption service:
1. PayFort hosted redemption service: the redemption service pages are hosted on the FORT. Users are redirected from the Merchant side to PayFort redemption pages. Below is a list of all the operations available for this integration:
a. Redeem: this operation allows the Merchant Gift Card holder to pay for his purchase using a Gift Card. This operation should be used if the balance available
on the card should be enough to pay for the purchase.
b. Full Redemption: this operation allows Merchant Gift Card holder to redeem the card’s full balance to credit the user’s account balance.
c. Partial Redemption: this operation allows Merchant Gift Card holder to redeem a partial amount of the card’s balance. This amount can be used to credit the
user balance or pay for purchases.
2. PayFort RESTful APIs: Merchants have full control to develop the user experience for the redemption pages. PayFort will offer the following redemption operations to make this possible:
a. Redeem: this operation allows the Merchant to redeem a specific amount from a Merchant Gift Card.
b. Reverse: this operation allows the Merchant to reverse a specific transaction.
c. Check Balance: this operation allows the Merchant to check the available balance and the currency of the Merchant Gift Card.
PayFort RESTful API 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.
REDEEM
This operation allows the Merchant to redeem a specific amount from a Merchant Gift Card.
REDEEM - 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: REDEEM |
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: - _ . |
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: _ - . @ + |
gift_card_number Alphanumeric Mandatory max: 100 |
The gift card number, the customer will use it to redeem its balance in exchange of goods or services. Example: 123455U48Q44455 Special characters: _ - . @ |
signature Alphanumeric Mandatory max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
customer_name Alpha Optional max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' Space |
REDEEM - Response
The following parameters will be returned in PayFort’s Response:
ATTRIBUTES | Description |
---|---|
service_command Alpha max: 20 |
Command. Possible/ expected values: REDEEM |
access_code Alphanumeric max: 20 |
Access code. 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: USD |
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: customer@domain.com |
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 |
customer_name Alpha max: 40 |
The customer’s name. Example: John Smith |
expiry_date Numeric max: 4 |
The card’s expiry date. Example: 2105 |
status Numeric max: 2 |
A two-digit numeric value that indicates the status of the transaction Possible/ expected values: (Please refer to section statuses). |
redemption_id Numeric max: 20 |
The reference to a specific redemption operation. Example: 1983887193719 |
card_bin Numeric max: 6 |
The first 6 digits of the card number. Example: 478773 |
remaining_balance Numeric max: 10 |
This is the amount left in the user gift card. Example: 200.0 |
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 |
REVERSE
This operation allows the Merchant to reverse a specific transaction.
REVERSE - Request
Include the following parameters in the Request you will send to PayFort:
ATTRIBUTES | Description |
---|---|
service_command Alpha Mandatory max: 13 |
Command. Possible/ expected values: REVERSE |
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 |
redemption_id Numeric Mandatory max: 20 |
The reference to a specific redemption operation. Example: 1983887193719 |
signature Alphanumeric Mandatory max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
REVERSE - Response
The following parameters will be returned in PAYFORT’s Response:
ATTRIBUTES | Description |
---|---|
service_command Alpha max: 20 |
Command. Possible/ expected values: REVERSE |
access_code Alphanumeric max: 20 |
Access code. 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 |
language Alpha max: 2 |
The checkout page and messages language. Possible/ expected values: en / ar |
redemption_id Numeric max: 20 |
The reference to a specific redemption operation. Example: 1983887193719 |
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). |
remaining_balance Numeric max: 10 |
This is the amount left in the user gift card. Example: 200.0 |
Check_balance
This operation allows the Merchant to check the available balance and the currency of the Merchant Gift Card.
Check_balance - 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: CHECK_BALANCE 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 |
merchant_reference Alphanumeric Mandatory max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
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 |
signature Alphanumeric Mandatory max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
gift_card_number Alphanumeric Optional max: 100 |
The Gift card number the customer will use to redeem its balance in exchange of goods or services. Example: 123455U48Q44455 Special characters: - _ . @ |
Check_balance - Response
The following parameters will be returned in PayFort’s Response:
ATTRIBUTES | Description |
---|---|
service_command Alpha max: 20 |
Command. Possible/ expected values: CHECK_BALANCE |
access_code Alphanumeric max: 20 |
Access code. 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: 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 |
expiry_date Numeric max: 4 |
The card’s expiry date. Example: 2105 |
status Numeric max: 2 |
A two-digit numeric value that indicates the status of the transaction Possible/ expected values: (Please refer to section statuses). |
gift_card_number Alphanumeric max: 100 |
The Gift card number the customer will use to redeem its balance in exchange of goods or services. Example: 123455U48Q44455 |
remaining_balance Numeric max: 10 |
The amount of the transaction. Example: 200.0 |