NAV Navbar
Logo

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: http://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