Before starting your integration follow these steps:

Note that throughout the API reference you will notice the words PayFort and FORT. Both refer to Amazon Payment Services.

Step 1: Access your test account
You have to make sure that you get access to a test account, our full test environment that allows you to simulate and process simulation transactions. You can contact merchantsupport-ps@amazon.com to get your test account.

Find values of Access code and Merchant Identifier

Once you are logged into your Amazon Payment services account, Choose Merchant Management from the Left navigation list.
Select Security Settings, A new window with all security related details page will appear.
We can find the Access Code, Merchant Identifier and SHA Request/Response details from that section.

Step 2: Use the correct integration type
You must take a moment to choose an integration type for your use case. Read more about integration options in our API documentation.

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 are mentioned in every section in the API reference.

Step 3: Create the transaction request
Processing a valid API request depends on specifying the right transaction parameters, you need to check the documentation and read every parameter’s range of possible values in order to reduce the errors in processing the transaction.

Step 4: Process the transaction response
After each payment is processed, Amazon Payment Services 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 Transaction Feedback Implementation.

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.

Amazon Payment Services accepts configuring HTTPS URLs only in your Account Technical Settings and for return_url parameter. Amazon Payment Services supports the return_url type to be POST method only under your Technical Settings. Please make sure that your redirection or return_url handles the response as POST Method. For any further support please contact: integration-ps@amazon.com

Step 5: Test and go-live
You can use our testing payment card numbers to test your integration and to simulate your test cases. Amazon Payment Services requires that you test your integration before going live to verify the integration and to make sure it is implemented properly.

Was this helpful? Yes No

Redirection

What is redirection?

Compared to merchant page integration, redirection integration involves a redirection step to a separate website. Consider redirection if you have a unique use case or technical barrier, or if you want to make minimal changes to your site code. Otherwise we recommend standard merchant page integration for a better customer experience.

Redirection 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.

Authorization/ Purchase - Request

Please take a look at the Authorization/ Purchase Request Example on the right side of the page.

Authorization/ Purchase Request Example

$requestParams = array(
'command' => 'AUTHORIZATION',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'amount' => '10000',
'currency' => 'AED',
'language' => 'en',
'customer_email' => 'test@payfort.com',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
);


$redirectUrl = 'https://sbcheckout.payfort.com/FortAPI/paymentPage';
echo "<html xmlns='https://www.w3.org/1999/xhtml'>\n<head></head>\n<body>\n";
echo "<form action='$redirectUrl' method='post' name='frm'>\n";
foreach ($requestParams as $a => $b) {
    echo "\t<input type='hidden' name='".htmlentities($a)."' value='".htmlentities($b)."'>\n";
}
echo "\t<script type='text/javascript'>\n";
echo "\t\tdocument.frm.submit();\n";
echo "\t</script>\n";
echo "</form>\n</body>\n</html>";

import cgi

requestParams = {
'command' => 'AUTHORIZATION',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'amount' => '10000',
'currency' => 'AED',
'language' => 'en',
'customer_email' => 'test@payfort.com',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
};


redirectUrl = 'https://sbcheckout.payfort.com/FortAPI/paymentPage';
print "<html xmlns='https://www.w3.org/1999/xhtml'>\n<head></head>\n<body>\n";
print "<form action='redirectUrl' method='post' name='frm'>\n";
for (slug, title) in requestParams.items():
    print "\t<input type='hidden' name='"+ cgi.escape(slug)+"' value='"+ cgi.escape(title)+"'>\n";

print "</form>";
print "\t<script type='text/javascript'>\n";
print "\t\tdocument.frm.submit();\n";
print "\t</script>\n";
print "\n</body>\n</html>";

require 'cgi'
requestParams = {
'command' => 'AUTHORIZATION',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'amount' => '10000',
'currency' => 'AED',
'language' => 'en',
'customer_email' => 'test@payfort.com',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
};
requestParams.each {|key, value|
  puts key +value ;
}

redirectUrl = 'https://sbcheckout.payfort.com/FortAPI/paymentPage';
puts "<html xmlns='https://www.w3.org/1999/xhtml'>\n<head></head>\n<body>\n";
puts "<form action='redirectUrl' method='post' name='frm'>\n";
requestParams.each {|key, value|
    puts "\t<input type='hidden' name='"+ CGI.escapeHTML(key)+"' value='"+ CGI.escapeHTML(value)+"'>\n";
}
puts "</form>\n";
puts "\t<script type='text/javascript'>\n";
puts "\t\tdocument.frm.submit();\n";
puts "\t</script>\n";
puts "</body>\n</html>";

Include the following parameters in the request you will send to Amazon Payment Services:

ATTRIBUTES	Description
command Alpha Mandatory Max: 20	A command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences.
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 check the note after this table. 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: _ - . @ +
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: . @ - _
payment_option Alpha Optional Max: 10	Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - SADAD (for Purchase operations only) - NAPS (for Purchase operations only) - KNET(for Purchase operations only) - OMANNET (for Purchase operations and eci Ecommerce only) - BENEFIT (for Purchase operations and eci Ecommerce only) - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only)
sadad_olp Alphanumeric Optional Max: 12	SADAD Online Payment ID Alias. The merchant sends this value if the OLP ID is collected on the merchant checkout. Example: SABBP2P_UAT2 Special characters: @ . _
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: . ; / _ - , `'` @
remember_me Alpha Optional Max: 2	This parameter provides you with an indication to whether to save this token for the user based on the user selection. Possible/ expected values: 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 that will be displayed to the customer when the order is processed. Example: https://www.merchant.com Special characters: $ ! = ? # & - _ / : .
billing_stateProvince Alphanumeric Optional max: 20	The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
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. Reference: ISO_3166-2 Example1: AM Example2: AT
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.
agreement_id Alphanumeric Optional max: 100	identifier for the agreement with the payer to process payments to be used in recurring payments ( Required for MADA )
recurring_mode Alphanumeric Optional max: 20	Indicates if the subsequent payments within the agreement has same/different amount or unscheduled (unknown interval/amount). ( Required for MADA ) Possible/ expected values: UNSCHEDULED, VARIABLE, FIXED
recurring_transactions_count Alphanumeric Optional max: 100	The number of merchant-initiated payments within the recurring payment agreement. ( Required for MADA and only if recurring_mode = VARIABLE or FIXED )

Redirection - Response

(Please take a look at the Authorization/ Purchase Response Example on the right side of the page.)

Authorization/ Purchase Response Example

{"command":"AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","customer_email":"test@payfort.com","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","payment_option":"VISA","eci":"ECOMMERCE","order_description":"iPhone6-S","customer_ip":"192.178.1.10","customer_name":"John","response_message":"Success","response_code":"20064","status":"04","card_holder_name":"John Smith","expiry_date":"2105","card_number":"400555******0001"}

{"command":"AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","customer_email":"test@payfort.com","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","payment_option":"VISA","eci":"ECOMMERCE","order_description":"iPhone6-S","customer_ip":"192.178.1.10","customer_name":"John","response_message":"Success","response_code":"20064","status":"04","card_holder_name":"John Smith","expiry_date":"2105","card_number":"400555******0001"}

{"command":"AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","customer_email":"test@payfort.com","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","payment_option":"VISA","eci":"ECOMMERCE","order_description":"iPhone6-S","customer_ip":"192.178.1.10","customer_name":"John","response_message":"Success","response_code":"20064","status":"04","card_holder_name":"John Smith","expiry_date":"2105","card_number":"400555******0001"}

The following parameters will be returned in PayFort’s Response:

ATTRIBUTES	Description
command Alpha Max: 20	A command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences.
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
token_name Alphanumeric max: 100	The Token received from the Tokenization process. Example: Op9Vmp
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 - SADAD (for Purchase operations only) - NAPS (for Purchase operations only) - KNET(for Purchase operations only) - OMANNET (for Purchase operations and eci Ecommerce only) - BENEFIT (for Purchase operations and eci Ecommerce only) - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only)
sadad_olp Alphanumeric Max: 12	SADAD Online Payment ID Alias. The merchant sends this value if the OLP ID is collected on the merchant checkout. Example: SABBP2P_UAT2
knet_ref_number Alphanmeric Max: 100	The reference number of KNET. *In case of sending KNET payment option. Example: 832911577112
third_party_transaction_number Alphanmeric Max: 50	The third party transaction number. *In case of sending KNET payment option. Example: 9547069411183290
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. 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
remember_me Alpha Max: 2	This parameter provides you with an indication to whether to save this token for the user based on the user selection. Possible/ expected values: 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. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
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. Reference: ISO_3166-2 Example1: AM Example2: AT
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.

Sample Redirection Request

Redirection request should be submitted as HTTPs POST Form request from the browser. Then you will get redirected to our payment gateway to fill payment details

Using Safe service (Tokenization) with redirection

The Safe service is integrated in the Redirection Channel through the below steps:
1. Your customer enables the remember_me option displayed in the payment page.
2. You process a first PURCHASE/ AUTHORIZATION payment successfully.
3. TYou receive a token_name in the response. This token_name is the permanent token name, and it can be used in the future for the customer’s payments by submitting the token_name in the next PURCHASE/ AUTHORIZATION payment.

If your customer wants to update or delete their card you can accommodate their request – check the Update Token section.

Was this helpful? Yes No

Redirection Customization

Amazon Payment page for credit card is fully customizable to match your website’s look and feel.

The payment page customization is possible only in Credit Card page , the other payment options allowed on Redirection channel are not customizable like SADAD , KNET , Installments Standalone and NAPS.

How it works

From your back-office go to the tab Payment Page Template, Click on Add Payment Page Template , You will find two options for customizing the payment page:
1. Using our back-office live editor.
2. Uploading your own css and html files.

Customization using our back-office live editor

We have added a full online editor on the back-office to simplify the CSS customization and change the look and feel without any coding , also your changes could be checked on the same tab Customize .

This option allows you to change the following :

Primary color ( in Hexa )
Secondary color ( In Hexa )
Background Color ( In Hexa )

Using HTML and CSS files

If you want to have more control on the payment page design and add more edits , you have two file options to upload:

1. HTML Template:

You can implement and create your own html file that you want to load in the payment page and change the look and feel for the payment page as you wish.

Your edits and customization must be added between the following tag in a separated <div> as below : <div>$$PZ$$</div> to inject your changes in our payment zone pages
The scripts aren’t allowed in the templates.

Sample HTML file: Sample Redirection HTML file

2.CSS Theme :

Develop your CSS file that edit our colors and theme in the payment page here you have to edit our existing CSS classes by inspecting the elements of the payment page , then include your changes on a CSS file .

Sample CSS file : Sample Redirection CSS file

Customizing the loading page

Our loading page is customizable , you can implement and create your own html file with your content and design that you want to load in the loading page
From your back-office go to the tab Payment Page Template, Click on Add Payment Page Template , Then upload your html files

Your edits and customization must be added between the below tag in a separated <div> as following to inject your changes : <div>$$PZ$$</div>

Payment maintenance operations

Maintenance operations are operations that can be executed only if an amount has already been authorized. The following sections illustrate the maintenance operations:

Capture Operation

An operation that allows the Merchant to capture the authorized amount to their account. The capture could be partial or full, and depends on the Merchant requirements. Multiple capture requests can be made up to the authorized amount.

How To Capture An Authorized Amount

1. Using Backoffice:

Through your back office by accessing your account and navigating to the “Order Transaction Management” tab, choose the transaction that you want to capture, and finally choose “Capture” from the Action button. You can apply a full or partial capture operation.

2. Using API:

Using Capture Api Request.

Capture Operation 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.

Capture Operation - Request

(Please take a look at the Capture Request Example on the right side of the page.)

Capture Request Example


error_reporting(E_ALL);
ini_set('display_errors', '1');

$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';

$arrData = array(
'command' => 'CAPTURE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'amount' => '10000',
'currency' => 'AED',
'language' => 'en',
'fort_id' => '149295435400084008',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
);


$ch = curl_init( $url );
# Setup request to send json via POST.
$data = json_encode($arrData);
curl_setopt( $ch, CURLOPT_POSTFIELDS, $data );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
# Return response instead of printing.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
# Send request.
$result = curl_exec($ch);
curl_close($ch);
# Print response.
echo "<pre>$result</pre>";

curl -H "Content-Type: application/json" -d '{"command":"CAPTURE","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","fort_id":"149295435400084008","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone6-S"}'
https://sbpaymentservices.payfort.com/FortAPI/paymentApi

import urllib
import urllib2
import json

url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command':'CAPTURE',
'access_code':'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier':'CycHZxVj',
'merchant_reference':'XYZ9239-yu898',
'amount':'10000',
'currency':'AED',
'language':'en',
'fort_id':'149295435400084008',
'signature':'7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description':'iPhone 6-S',
};

values = json.dumps(arrData)
data = urllib.urlencode(values)
req = urllib2.Request(url, data)
response = urllib2.urlopen(req)
page = response.read()
print page + '\n\n'

String jsonRequestString = "{\"command\" : \"CAPTURE\" , \"access_code\" : \"zx0IPmPy5jp1vAz8Kpg7\", \"merchant_identifier\" : \"CycHZxVj\", " + "\"merchant_reference\" : \"XYZ9239-yu898\", \"amount\" : \"10000\", \"currency\" : \"AED\"," + "\"language\" : \"en\", \"fort_id\" : \"149295435400084008\", " + "\"signature\" : \"7cad05f0212ed933c9a5d5dffa31661acf2c827a\", \"order_description\" : \"iPhone 6-S\"}";

// Define and Initialize HttpClient
HttpClient httpClient = HttpClientBuilder.create().build();
// Intialize HttpPOST with FORT Payment services URL
HttpPost request = new HttpPost("https://sbpaymentservices.payfort.com/FortAPI/paymentApi");
// Setup Http POST entity with JSON String
StringEntity params = new StringEntity(jsonRequestString);
// Setup request type as JSON
request.addHeader("content-type", "application/json");
request.setEntity(params);
// Post request to FORT
HttpResponse response = httpClient.execute(request);
// Read response using StringBuilder
StringBuilder sb = new StringBuilder();
BufferedReader reader = new BufferedReader(new InputStreamReader(
   response.getEntity().getContent()), 65728);
String line = null;
while ((line = reader.readLine()) != null) {
 sb.append(line);
}
// Print response
System.out.println(sb.toString());

require 'json'
require 'net/http'
require 'net/https'
require 'uri'
require 'openssl'

arrData = {
'command' => 'CAPTURE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'amount' => '10000',
'currency' => 'AED',
'language' => 'en',
'fort_id' => '149295435400084008',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
};

arrData = arrData.to_json
uri = URI.parse("https://sbpaymentservices.payfort.com/FortAPI/paymentApi")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new("/v1.1/auth")
request.add_field('Content-Type', 'application/json')
request.body = arrData
response = http.request(request)

Include the following parameters in the request you will send to Amazon Payment Services:

ATTRIBUTES	Description
command Alpha Mandatory Max: 20	A command. Possible/ expected values: CAPTURE
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. * You have the option to send “fort_id” instead of “merchant_reference”, or you can send them BOTH. 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
signature Alphanumeric Mandatory max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
fort_id Numeric Optional Max: 20	The order’s unique reference returned by our system. Example: 149295435400084008
order_description Alphanumeric Optional Max: 150	It holds the description of the order. Example: iPhone 6-S Special characters: `'` / . _ - # : $ Space

Capture Operation - Response

(Please take a look at the Capture Response Example on the right side of the page.)

Capture Response Example

{"command":"CAPTURE","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","fort_id":"149295435400084008","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}

{"command":"CAPTURE","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","fort_id":"149295435400084008","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}

{"command":"CAPTURE","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","fort_id":"149295435400084008","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}

{"command":"CAPTURE","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","fort_id":"149295435400084008","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}

{"command":"CAPTURE","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","fort_id":"149295435400084008","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}

The following parameters will be returned in Amazon Payment Services’ Response:

ATTRIBUTES	Description
command Alpha Max: 20	A command. Possible/ expected values: CAPTURE
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
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
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

Void authorization operation

An operation that allows you to cancel the authorized amount after you have sent a successful authorize request.

How To Void An Authorized Amount

1. Using Backoffice:

Through your back office by accessing your account and navigating to the “Order Transaction Management” tab, choose the transaction that you want to Void authorization, and finally choose “Void authorization” from the Action button.

2. Using API

Using Capture Api Request.

Void authorization operation 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.

Void authorization operation - request

(Please take a look at the Void authorization request example on the right side of the page.)

Void-Authorization Request Example


error_reporting(E_ALL);
ini_set('display_errors', '1');

$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';

$arrData = array(
'command' => 'VOID_AUTHORIZATION',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
);


$ch = curl_init( $url );
# Setup request to send json via POST.
$data = json_encode($arrData);
curl_setopt( $ch, CURLOPT_POSTFIELDS, $data );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
# Return response instead of printing.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
# Send request.
$result = curl_exec($ch);
curl_close($ch);
# Print response.
echo "<pre>$result</pre>";


curl -H "Content-Type: application/json" -d '{"command":"VOID_AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj",merchant_reference":"XYZ9239-yu898","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone6-S"}' https://sbpaymentservices.payfort.com/FortAPI/paymentApi

String jsonRequestString = "{\"command\" : \"VOID_AUTHORIZATION\" , "
      + "\"access_code\" : \"zx0IPmPy5jp1vAz8Kpg7\", \"merchant_identifier\" : \"CycHZxVj\", \"merchant_reference\" : \"XYZ9239-yu898\","
      + "\"language\" : \"en\", \"signature\" : \"7cad05f0212ed933c9a5d5dffa31661acf2c827a\", "
      + "\"order_description\" : \"iPhone 6-S\"}";

// Define and Initialize HttpClient
HttpClient httpClient = HttpClientBuilder.create().build();
// Intialize HttpPOST with FORT Payment services URL
HttpPost request = new HttpPost("https://sbpaymentservices.payfort.com/FortAPI/paymentApi");
// Setup Http POST entity with JSON String
StringEntity params = new StringEntity(jsonRequestString);
// Setup request type as JSON
request.addHeader("content-type", "application/json");
request.setEntity(params);
// Post request to FORT
HttpResponse response = httpClient.execute(request);
// Read response using StringBuilder
StringBuilder sb = new StringBuilder();
BufferedReader reader = new BufferedReader(new InputStreamReader(
  response.getEntity().getContent()), 65728);
String line = null;
while ((line = reader.readLine()) != null) {
sb.append(line);
}
// Print response
System.out.println(sb.toString());

import urllib
import urllib2
import json

url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command':'VOID_AUTHORIZATION',
'access_code':'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier':'CycHZxVj',
'merchant_reference':'XYZ9239-yu898',
'language':'en',
'signature':'7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description':'iPhone 6-S',
};

values = json.dumps(arrData)
data = urllib.urlencode(values)
req = urllib2.Request(url, data)
response = urllib2.urlopen(req)
page = response.read()
print page + '\n\n'

require 'json'
require 'net/http'
require 'net/https'
require 'uri'
require 'openssl'

arrData = {
'command' => 'VOID_AUTHORIZATION',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
};

arrData = arrData.to_json
uri = URI.parse("https://sbpaymentservices.payfort.com/FortAPI/paymentApi")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new("/v1.1/auth")
request.add_field('Content-Type', 'application/json')
request.body = arrData
response = http.request(request)

Include the following parameters in the request you will send to Amazon Payment Services:

ATTRIBUTES	Description
command Alpha Mandatory Max: 20	Command. Possible/ expected values: VOID_AUTHORIZATION. 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
merchant_reference Alphanumeric Mandatory Max: 40	The Merchant’s unique order number. *You have the option to send “fort_id” instead of “merchant_reference”, or you can send them BOTH. 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
fort_id Numeric Optional Max: 20	The order’s unique reference returned by our system. Example: 149295435400084008
order_description Alphanumeric Optional Max: 150	It holds the description of the order. Example: iPhone 6-S Special characters: `'` / . _ - # : $ Space

Void authorization operation response

(Please take a look at the Void authorization response example on the right side of the page.)

Void-Authorization Response Example


{"command":"VOID_AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone6-S","fort_id":"149295435400084008","response_message":"Success","response_code":"20064","status":"04"}


{"command":"VOID_AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone6-S","fort_id":"149295435400084008","response_message":"Success","response_code":"20064","status":"04"}


{"command":"VOID_AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone6-S","fort_id":"149295435400084008","response_message":"Success","response_code":"20064","status":"04"}


{"command":"VOID_AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone6-S","fort_id":"149295435400084008","response_message":"Success","response_code":"20064","status":"04"}


{"command":"VOID_AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone6-S","fort_id":"149295435400084008","response_message":"Success","response_code":"20064","status":"04"}

The following parameters will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
command Alpha Max: 20	Command. Possible/ expected values: VOID_AUTHORIZATION
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
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
fort_id Numeric Max: 20	The order’s unique reference returned by our system. Example: 149295435400084008
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

Refund operation

An operation that returns the entire amount of a transaction, or returns part of it, after you have captured an amount.

How To Refund Captured Amount

How To Refund Captured Amount

1. Using Backoffice:

Through your back office by accessing your account and navigating to the “Order Transaction Management” tab, choose the transaction that you want to Refund, and finally choose “Refund” from the Action button.

2. Using API: Using Refund Api Request.

Refund operation 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.

Refund operation - request

(Please take a look at the Refund request example on the right side of the page.)

Refund request example


error_reporting(E_ALL);
ini_set('display_errors', '1');

$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';

$arrData = array(
'command' => 'REFUND',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => ' XYZ9239-yu898',
'amount' => '10000',
'currency' => 'AED',  
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'fort_id' => '149295435400084008',
'order_description' => 'iPhone 6-S',
);


$ch = curl_init( $url );
# Setup request to send json via POST.
$data = json_encode($arrData);
curl_setopt( $ch, CURLOPT_POSTFIELDS, $data );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
# Return response instead of printing.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
# Send request.
$result = curl_exec($ch);
curl_close($ch);
# Print response.
echo "<pre>$result</pre>";

curl -H "Content-Type: application/json" -d
'{"command":"REFUND","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","order_description":"iPhone6-S"}'
https://sbpaymentservices.payfort.com/FortAPI/paymentApi

import urllib
import urllib2
import json

url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command':'REFUND',
'access_code':'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier':'CycHZxVj',
'merchant_reference':' XYZ9239-yu898',
'amount':'10000',
'currency':'AED',  
'language':'en',
'signature':'7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'fort_id':'149295435400084008',
'order_description':'iPhone 6-S',
};

values = json.dumps(arrData)
data = urllib.urlencode(values)
req = urllib2.Request(url, data)
response = urllib2.urlopen(req)
page = response.read()
print page + '\n\n'

String jsonRequestString = "{\"command\" : \"REFUND\" , \"access_code\" : \"zx0IPmPy5jp1vAz8Kpg7\", \"merchant_identifier\" : \"CycHZxVj\", "
       + "\"merchant_reference\" : \"XYZ9239-yu898\", \"amount\" : \"10000\", \"currency\" : \"AED\","
       + "\"language\" : \"en\", \"signature\" : \"7cad05f0212ed933c9a5d5dffa31661acf2c827a\", "
       + "\"fort_id\" : \"149295435400084008\", \"order_description\" : \"iPhone 6-S\"}";

// Define and Initialize HttpClient
HttpClient httpClient = HttpClientBuilder.create().build();
// Intialize HttpPOST with FORT Payment services URL
HttpPost request = new HttpPost("https://sbpaymentservices.payfort.com/FortAPI/paymentApi");
// Setup Http POST entity with JSON String
StringEntity params = new StringEntity(jsonRequestString);
// Setup request type as JSON
request.addHeader("content-type", "application/json");
request.setEntity(params);
// Post request to FORT
HttpResponse response = httpClient.execute(request);
// Read response using StringBuilder
StringBuilder sb = new StringBuilder();
BufferedReader reader = new BufferedReader(new InputStreamReader(
   response.getEntity().getContent()), 65728);
String line = null;
while ((line = reader.readLine()) != null) {
 sb.append(line);
}
// Print response
System.out.println(sb.toString());

require 'json'
require 'net/http'
require 'net/https'
require 'uri'
require 'openssl'

arrData = {
'command' => 'REFUND',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => ' XYZ9239-yu898',
'amount' => '10000',
'currency' => 'AED',  
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'fort_id' => '149295435400084008',
'order_description' => 'iPhone 6-S',
};

arrData = arrData.to_json
uri = URI.parse("https://sbpaymentservices.payfort.com/FortAPI/paymentApi")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new("/v1.1/auth")
request.add_field('Content-Type', 'application/json')
request.body = arrData
response = http.request(request)

Include the following parameters in the request you will send to Amazon Payment Services:

ATTRIBUTES	Description
command Alpha Mandatory Max: 20	A command. Possible/ expected values: REFUND
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. *You have the option to send “fort_id” instead of “merchant_reference”, or you can send them BOTH. 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
signature Alphanumeric Mandatory max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
maintenance_reference Alphanumeric Optional Max: 200	The Refund’s unique order number. * You will be able to retry on the refund request using the same maintenance reference if the refund transaction was declined. Example: customer123
fort_id Numeric Optional Max: 20	The order’s unique reference returned by our system. Example: 149295435400084008
order_description Alphanumeric Optional Max: 150	It holds the description of the order. Example: iPhone 6-S Special characters: `'` / . _ - # : $ Space

Refund operation - response

(Please take a look at the Refund Response Example on the right side of the page.)

Refund Response Example

{"command":"REFUND","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}

{"command":"REFUND","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}

{"command":"REFUND","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}

{"command":"REFUND","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}

{"command":"REFUND","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}

The following parameters will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
command Alpha Max: 20	Command. Possible/ expected values: REFUND
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
signature Alphanumeric Max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
maintenance_reference Alphanumeric Max: 200	The Refund’s unique order number. * You will be able to retry on the refund request using the same maintenance reference if the refund transaction was declined. Example: customer123
fort_id Numeric Max: 20	The order’s unique reference returned by our system. Example: 149295435400084008
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

Was this helpful? Yes No

Standard merchant page integration

Standard merchant page integration from Amazon Payment Services uses an HTML iframe to insert a customizable payment form right into your checkout page. It is easy to integrate into your existing website and offers your customers a seamless experience.

Standard merchant page integration 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

Standard merchant page integration - request

Include the following parameters in the request you will send to Amazon Payment Services:

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: $ ! = ? # & - _ / : .

Standard Merchant Page Tokenization - Sample request

The request parameters should be inside an iframe. Here below HTML sample contains the mandatory parameter should be submitted :

<html>
<head>
<title>Standard Merchant Page Sample</title>
</head>
<body>
<h1 style=“text-align:center”>Standard Merchant Page iFrame Sample</h1>
<center><iframe style=“border:6px dotted green” name=“myframe” src = “” width=“600” height=“500”></iframe></center>
<form action=“https://sbcheckout.payfort.com/FortAPI/paymentPage” method=“post” id=“” target=“ myframe”>
<INPUT type=“hidden” NAME=“service_command” value=“TOKENIZATION”>
<INPUT type=“hidden” NAME=“language” value=“ ”>
<INPUT type=“hidden” NAME=“merchant_identifier” value=“ ”>
<INPUT type=“hidden” NAME=“access_code” value=“ ”>
<INPUT type=“hidden” NAME=“signature” value=“ ”>
<INPUT type=“hidden” NAME=“return_url” value=“ ”>
<INPUT type=“hidden” NAME=“merchant_reference” value=“ ”>
<input value=“Show Payment Form” type=“submit” id=“form1”>
</form>
</body>
</html>

Standard merchant page integration - response

The following parameters will be returned in Amazon Payment Services’ 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

Standard merchant page integration operations

Standard merchant page integration 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 Amazon Payment Services:

ATTRIBUTES	Description
command Alpha Mandatory max: 20	Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences.
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: $ ! = ? # & - _ / : .
billing_stateProvince Alphanumeric Optional max: 20	The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
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. Reference: ISO_3166-2 Example1: AM Example2: AT
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.
agreement_id Alphanumeric Optional max: 100	identifier for the agreement with the payer to process payments to be used in recurring payments ( Required for MADA )
recurring_mode Alphanumeric Optional max: 20	Indicates if the subsequent payments within the agreement has same/different amount or unscheduled (unknown interval/amount). ( Required for MADA ) Possible/ expected values: UNSCHEDULED, VARIABLE, FIXED
recurring_transactions_count Alphanumeric Optional max: 100	The number of merchant-initiated payments within the recurring payment agreement. ( Required for MADA and only if recurring_mode = VARIABLE or FIXED )

Operations - Response

The following parameters will be returned in Amazon Payment Services’s response:

ATTRIBUTES	Description
command Alpha max: 20	Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences.
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 3D 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. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
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. Reference: ISO_3166-2 Example1: AM Example2: AT
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 do you add Safe service (Tokenization) to standard merchant page integration?

The tokenization service can be integrated through standard merchant page integration through the below steps:
1. Your customer processes their first authorization or purchase transaction successfully.
2. You 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 or authorization transaction, alongside the card_security_code parameter.
3. Your customer does not need to complete all their card details again in the next checkout.

If your customer wants to update or delete their card, you can facilitate the request by updating the token check out the Update Token section.

Customizing standard merchant page integration

This is a list with all customizable CSS classes for standard merchant page integration:

The Wrapper class: responsible for the total width of the form container and the background.
The Container class: responsible for the form’s shape and width.
The Popover class: responsible for the error messages.
The Half-container class: used to merge the date and CVV fields into one block if needed.
The Input class: is the container of each single input field.
The Pay class: responsible for the submit button.
The Visa/ MasterCard classes: used to change the color of the Visa/ MasterCard colors.

Was this helpful? Yes No

Custom merchant page integration

When you use our custom merchant page integration route you build your own payment form that captures payment data and that directly submits that data to Amazon Payment Services for payment authorization.

Custom merchant page integration is a good choice if you want the highest level of on-page customization, or if your ecommerce use case has unique technical requirements.

Custom merchant page integration 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.

Custom merchant page integration - request

Include the following parameters in the Request you will send to Amazon Payment Services:

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
expiry_date Numeric Mandatory Max: 4	The card’s expiry date. Example: 2105
card_number Numeric Mandatory Max: 19	The clear 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: 4005550000000001
card_security_code Numeric Mandatory Max: 4	A security code for the card. * Only AMEX accepts card security code of 4 digits. Example: 123
signature Alphanumeric Mandatory Max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature *Please don’t include the following parameters in calculating the signature if you are using Merchant Page 2.0 tokenization request: card_security_code, card number, expiry_date, card_holder_name, remember_me Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
token_name Alphanumeric Optional Max: 100	The Token received from the Tokenization process. Example: Op9Vmp Special characters: . @ - _
card_holder_name Alpha Optional max: 50	The card holder name. Example: John Smith 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. Possible/ expected values: -YES -NO
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: $ ! = ? # & - _ / : .

Custom Merchant Page Tokenization - Sample request

Custom merchant page integration - response

The following parameters will be returned in Amazon Payment Services 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: 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
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
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: COp9Vmp
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
card_holder_name Alpha Max: 50	The card holder name. Example: John Smith
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
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

Custom merchant page integration operations

Custom merchant page integration 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 Amazon Payment Services:

ATTRIBUTES	Description
command Alpha Mandatory max: 20	Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences.
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: _ - . @ +
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 for more details). 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: $ ! = ? # & - _ / : .
billing_stateProvince Alphanumeric Optional max: 20	The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
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. Reference: ISO_3166-2 Example1: AM Example2: AT
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.
agreement_id Alphanumeric Optional max: 100	identifier for the agreement with the payer to process payments to be used in recurring payments ( Required for MADA )
recurring_mode Alphanumeric Optional max: 20	Indicates if the subsequent payments within the agreement has same/different amount or unscheduled (unknown interval/amount). ( Required for MADA ) Possible/ expected values: UNSCHEDULED, VARIABLE, FIXED
recurring_transactions_count Alphanumeric Optional max: 100	The number of merchant-initiated payments within the recurring payment agreement. ( Required for MADA and only if recurring_mode = VARIABLE or FIXED )

Operations - Response

The following parameters will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
command Alpha max: 20	Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences.
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	It holds the 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 3D 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. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
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. Reference: ISO_3166-2 Example1: AM Example2: AT
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.

Using Safe service (Tokenization) in the custom merchant page integration channel

You can use tokenization when you make use of custom merchant page integration by following these steps:
1. Your customer processes their first authorization or purchase transaction.
2. You receive a token_name in the response. This token_name should be considered a permanent token name, and it can be used in the future for your customer’s payments by submitting the token_name in subsequent authorize or purchase transactions alongside the card_security_code parameter.
3. Your customer does not need to complete all their card details in the next checkout.

If your customer wants to update or delete their card details you can accommodate the request by updating the token. Review the Update Token section.

Was this helpful? Yes No

Android Mobile SDK

Before you start the integration

Read through the following steps first to understand how the integration process works. This will help you to understand why these steps are required and why you need to follow a specific sequence.

Step 1: Access your test account

You need to make sure that you have access to a test account with Amazon Payment Services. It is a full test environment that allows you to fully simulate transactions.

Step 2: Choose between a standardized or custom payment UI

The Amazon Payment Services Android SDK provides you with a standard payment UI that you can use to quickly integrate in-app payments. The standard UI offers limited customizability.

Alternatively, you can choose to build your own payment UI using Amazon Payment Services Android SDK building blocks, we describe this in the section on custom-coding a payment processing UI.

Step 3: Make sure that you are using the correct integration type

Prior to 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 are mentioned under every section in the API document

Step 4: Install the Amazon Payment Services Android SDK in your development environment

You need to add the repositories to your build file and add the SDK to your build.gradle, also setting the correct Android permissions.

Step 5: Create a test transaction request

You need to create a test transaction request. Processing a valid API request depends on transaction parameters included, you need to check the documentation and read every parameter possible to reduce the errors in processing the transaction.

Step 6: Process a transaction response

After every payment, Amazon Payment Services returns the transaction response on the URL configured in your account under Technical Settings, Channel Configuration.

For more details check the transaction feedback instructions. 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 7: Test and Go Live

You can use our test card numbers to test your integration and simulate your test cases. The Amazon Payment Services team may need to test your integration before going live to assure your application integration.

Mobile SDK transaction workflow

Below, we describe the transaction workflow when you process a payment using the Amazon Payment Service Android Mobile SDK.

Your customer clicks on the Pay button in your app.
Your merchant system (back-end) generates a mobile SDK token using the Amazon Payment Services API
Your app passes the parameters, including the SDK token, to the Android mobile SDK
The Android mobile SDK starts a secure connection and sends the transaction request to the Amazon Payment Services server to be validated.
The Amazon Payment Services API validates the SDK token, device_ID and other request parameters and returns the validation response to the Android SDK.
Assuming validation is passed your merchant app displays a payment page to the customer.
Your customer enters their payment details on the payment page in the Android SDK prompt on their device.
The Amazon Payment Services Android SDK validates your customer’s details and sends a transaction (Authorization or Purchase) request to the relevant payment processor and issuing bank.
The payment processor processes the transaction request and returns a transaction response to the Android SDK
The Amazon Payment Services Android SDK returns the transaction response to your merchant app
Your merchant app displays the response to your customer

transaction workflow

Installing the Mobile SDK

These are the first steps you need to follow to integrate the Amazon Payment Services Android SDK into your Android application.

Installing the Android Mobile SDK

You need to complete two steps to install the Amazon Payment Services Android SDK.

Step 1

First, you need to add the repository to your build file. Add it in your root build.gradle at the end of repositories:

allprojects {
  repositories {
    ...
    maven { url https://android-sdk.payfort.com }
  }
}

Step 2

Add the Add fortSDK to your build.gradle dependencies using this code:

apply plugin: 'com.android.application' 
android { ... } 
dependencies {
  implementation("com.amazon:fortpayment:+:release@aar"){
    transitive = true
}  
}

Setting Android OS permissions

You need to set the following two permission so that the Android mobile SDK works properly:

< uses-permission android:name="android.permission.INTERNET" />
< uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Creating a mobile SDK token

A mobile SDK authentication token is required to authenticate every request sent to the SDK. The token is also significant to process payment operations with Amazon Payment Services through our Android mobile SDK.

To get started with our Android mobile SDK you must first establish the ability to generate a mobile SDK token.

NOTE: The creation and initiation of a mobile SDK token happens on your server – your server must generate the token by sending a request to the Amazon Payment Services API.

A unique authentication token must be created for each transaction. Each authentication token has a life-time of only one hour if no new request from the same device is sent.

Android mobile SDK token URLs

These are the URLs you need to use when you request a mobile SDK token for your Android app:

Test Environment URL

https://sbpaymentservices.payfort.com/FortAPI/paymentApi

Production Environment URL

https://paymentservices.payfort.com/FortAPI/paymentApi

Submitting token request parameters

You need to submit parameters as a REST POST request using JSON. Below we list the range of parameters for the Android mobile SDK token request.

Android Mobile SDK Token Request Parameters

When you send your request for an Android mobile SDK token you must send the following parameters to Amazon Payment Services:

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

NOTE: device_id is a value to be generated from the UUID Class Reference, you can generate this parameter by using the following command: FortSdk.getDeviceId(appContext)

Android Mobile SDK Token Response Parameters

These parameters will be returned in the Amazon Payment Services 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 Amazon Payment Services 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

NOTE: Every parameter the merchant sends in the request should be received by the merchant in the response - even the optional parameters.

Processing transactions with the Android SDK

In this section we outline how you process a transaction using the Android mobile SDK. Your first step is to create a mobile SDK token as described above.

Two routes for in-app payment processing

As a merchant you have two ways in which you can process payments using the Amazon Payment Services Android mobile SDK.

Standard payment processing UI

You can use the standard Amazon Payment Services Android SDK interface to display a standard payment UI screen. This option is customizable in two ways – you can hide the loading screen, and some of the UI elements can be customized. We address standard UI customization options in this section.
Custom payment processing UI

Alternatively, you can choose to build your own payment processing UI by custom-coding an in-app payment processing feature. With this mobile SDK feature we allow Amazon Payment Services merchants to integrate and implement a native app checkout experience without displaying a default payment screen.

Using this integration method your customers can securely enter their payment card details on a fully customized merchant checkout landing page using the your customized payment UI.

The Amazon Payment Services Android SDK provides key building blocks including payment card input fields and an action pay button that you can encapsulate inside the checkout landing page and to provide your own inline customer experience.

Amazon Payment Services’ SDK card input fields will securely transmit the completed payment card data to Amazon Payment Services APIs for processing and to complete the transaction placement.

Read more about a customized payment processing UI in this section.

Standard checkout implementation

1: Define a Callback Manager

Define and initialize an instance of the FortCallBackManager in your activity as follows:

private FortCallBackManager fortCallback= null;
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    if (fortCallback == null)
        fortCallback = FortCallback.Factory.create();
}

2: Attach the Callback to the Activity

You need to add the following statement to the onActivityResult function as follows:

@Override protected void onActivityResult(int requestCode, int resultCode, Intent  data){  
super.onActivityResult(requestCode, resultCode,  data); fortCallback.onActivityResult(requestCode,resultCode,data);
}

3: Call the Android Mobile SDK and Collecting the Android SDK request

The below code registers a new callback for a new request. The registerCallBack requires the following inputs:

public void registerCallback(
        Activity context, final FortRequest fortRequest, String
        environment, final int requestCode, final FortCallBackManager callbackManager, boolean   showLoading, final
        FortInterfaces.OnTnxProcessed callback)

Below is a description for each parameter:

Parameter	Description
context	Passes the currency activity context.
fortRequest	An instance of the model mentioned in Collect the Android 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.

The Java model/ bean of the Android Mobile SDK request is as follows:

public class FortRequest implements Serializable {
    private Map requestMap;
    private boolean showResponsePage;

    public Map getRequestMap() {
        return
                requestMap;
    }

    public void setRequestMap(Map requestMap) {
        this.requestMap = requestMap;
    }

    public boolean isShowResponsePage() {
        return showResponsePage;
    }

    public void setShowResponsePage(boolean showResponsePage) {
        this.showResponsePage = showResponsePage;
    }
}

NOTE: You can choose to display the Amazon Payment Services response page by passing “showResponsePage” value as “True”.

The “requestMap” must contain all the Amazon Payment Services parameters for the order/ transaction. (Detailed information can be found in our Amazon Payment Services Merchant Integration Guide).

Example:

private Map collectRequestMap(String sdkToken) {
        Map requestMap = new HashMap<>();
        requestMap.put("command", "PURCHASE");
        requestMap.put("customer_email", "Sam@gmail.com");
        requestMap.put("currency", "SAR");
        requestMap.put("amount", "100");
        requestMap.put("language", "en");
        requestMap.put("merchant_reference", "merchant_reference ");
   
        requestMap.put("sdk_token", sdkToken);
        return requestMap;
    }

Initiate a checkout request:

For every transaction that needs to be processed, do the following call and handle the callback methods upon your business flow:

Example for register callback:

FortSdk.getInstance().registerCallback(this,fortRequest,5,fortCallback, showLoading,new
    FortInterfaces.OnTnxProcessed() {
    @Override public void onCancel (Map < String, Object > requestParamsMap, Map < String, Object > responseMap)
    {       
    }

    @Override public void onSuccess (Map < String, Object > requestParamsMap, Map < String, Object > fortResponseMap)
    {
    }

    @Override public void onFailure (Map < String, Object > requestParamsMap, Map < String, Object > fortResponseMap)
    {    
    } 
}

Android Mobile SDK Device ID Value

Please make sure to use the following Android SDK function to generate the device_id parameter value that must be used for creating the sdk_token from your business security server:

  String device_id = FortSdk.getDeviceId(this);

Android mobile SDK parameters

Request parameters

This is a list of the parameters you need to send when you send a request to the Android SDK.

ATTRIBUTES	Description
command Alpha Mandatory max: 20	Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences.
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 Amazon Payment Services 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: . ; / _ - , `'` @
billing_stateProvince Alphanumeric Optional max: 20	The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
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. Reference: ISO_3166-2 Example1: AM Example2: AT
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.
agreement_id Alphanumeric Optional max: 100	identifier for the agreement with the payer to process payments to be used in recurring payments ( Required for MADA )
recurring_mode Alphanumeric Optional max: 20	Indicates if the subsequent payments within the agreement has same/different amount or unscheduled (unknown interval/amount). ( Required for MADA ) Possible/ expected values: UNSCHEDULED, VARIABLE, FIXED
recurring_transactions_count Alphanumeric Optional max: 100	The number of merchant-initiated payments within the recurring payment agreement. ( Required for MADA and only if recurring_mode = VARIABLE or FIXED )

[NOTE]: Before sending the transaction value you must multiply the value by a factor that matches the ISO 4217 specification for that currency. Multiplication is necessary to accommodate decimal values. Each currency’s 3-digit ISO code will have a specification for the number of digits after the decimal separator.

For example: If the transaction value is 500 AED; according to ISO 4217, you should multiply the value with 100 (to accommodate 2 decimal points). You will therefore send an AED 500 purchase amount as a value of 50000.

Another example: If the amount value was 100 JOD; according to ISO 4217, you should multiply the value with 1000 (to accommodate 3 decimal points). You therefore send a JOD 100 purchase amount as a value of 100000

Response parameters

ATTRIBUTES	Description
command Alpha Max: 20	Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences.
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 Amazon Payment Services 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
billing_stateProvince Alphanumeric max: 20	The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
billing_provinceCode Alphanumeric 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. Reference: ISO_3166-2 Example1: AM Example2: AT
billing_street Alphanumeric 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 max: 100	The second line of the address (if provided).
billing_postcode Alphanumeric max: 10	The post code or zip code of the address.
billing_country Alphanumeric min:3, max: 3	The 3 letter ISO standard Alphanumeric country code of the address.
billing_company Alphanumeric max: 100	The name of the company associated with this address.
billing_city Alphanumeric max: 100	The city portion of the address.
shipping_stateProvince Alphanumeric max: 20	The state or province of the address.
shipping_provinceCode Alphanumeric 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 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 max: 100	The second line of the address (if provided).
shipping_source Alphanumeric	How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE
shipping_sameAsBilling Alphanumeric	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 max: 10	The post code or zip code of the address.
shipping_country Alphanumeric min:3, max: 3	The 3 letter ISO standard Alphanumeric country code of the address.
shipping_company Alphanumeric max: 100	The name of the company associated with this address.
shipping_city Alphanumeric max: 100	The city portion of the address.
agreement_id Alphanumeric max: 100	identifier for the agreement with the payer to process payments to be used in recurring payments

Standard checkout UI sample code

Below we include a complete sample code section illustrating the full checkout process when you use the standard checkout UI. The sample includes capturing payment card data, initializing the Amazon Payment Services Android SDK, submitting payment card data and processing a transaction.


public class PayFortSdkSample extends Activity {
    private FortCallBackManager fortCallback = null;
    String deviceId = "", sdkToken = "";

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

     // create Fort callback instance
        fortCallback = FortCallback.Factory.create();

        // Generating deviceId
        deviceId = FortSdk.getDeviceId(PayFortSdkSample.this);
        Log.d("DeviceId ", deviceId);

        // prepare payment request
        FortRequest fortrequest = new FortRequest();
        fortrequest.setRequestMap(collectRequestMap("PASS_THE_GENERATED_SDK_TOKEN_HERE"));
        fortrequest.setShowResponsePage(true); // to [display/use] the SDK response page
        // execute payment request callSdk(fortrequest);
    }

    private Map collectRequestMap(String sdkToken) {
        Map requestMap = new HashMap<>();
        requestMap.put("command", "PURCHASE");
        requestMap.put("customer_email", "Sam@gmail.com");
        requestMap.put("currency", "SAR");
        requestMap.put("amount", "100");
        requestMap.put("language", "en");
        requestMap.put("merchant_reference", "ORD-0000007682");
        requestMap.put("customer_name", "Sam");
        requestMap.put("customer_ip", "172.150.16.10");
        requestMap.put("payment_option", "VISA");
        requestMap.put("eci", "ECOMMERCE");
        requestMap.put("order_description", "DESCRIPTION");
        requestMap.put("sdk_token", sdkToken);
        return requestMap;
    }

    private void callSdk(FortRequest fortrequest) {

        FortSdk.getInstance().registerCallback(PayFortSdkSample.this, fortrequest,
                FortSdk.ENVIRONMENT.TEST, 5, fortCallback, new FortInterfaces.OnTnxProcessed() {
                    @Override
                    public void onCancel(Map requestParamsMap, Map responseMap) {
                        Log.d("Cancelled ", responseMap.toString());
                    }
                    @Override
                    public void onSuccess(Map requestParamsMap, Map fortResponseMap) {    //TODO: handle me
                        Log.i("Success ", fortResponseMap.toString());
                    }
                    @Override
                    public void onFailure(Map requestParamsMap,
                                          Map fortResponseMap) {
                        Log.e("Failure ", fortResponseMap.toString());
                    }

                });


    }


    @Override
    public void onActivityResult(int requestCode, int resultCode, Intent data) {
        super.onActivityResult(requestCode, resultCode, data);
        fortCallback.onActivityResult(requestCode, resultCode, data);
    }

}

Customizing the payment UI

You can customize the payment UI presented by our Android SDK in a number of ways to better reflect your business. This is when you use the standard UI.

Customizing the Android 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:

Don’t change the layout name because it is considered an override process.
Make sure to use all the views that has the ID property in order to avoid the NullPointerException.
Redesign the view for portrait orientation. Note that Landscape orientation isn’t supported.
You can support as much layout densities as you want.

Our Mobile SDK v 1.9 consists one of the following three main activities design:

activity_cc_payment.xml
activity_cc_response.xml
activity_init_secure_conn

payment layout

Figure : Standard vs. Customized Mobile SDK Payment Page Design

Design Customization Codes:

The following code was used to customize the way the Amount is displayed in the Standard Mobile SDK Payment Page:

 < TextView
    android:id="@+id/amountTV"
    android:layout_width="match_parent"
    android:layout_height=”38dp"
    android:background="@color/pf_light_gray"
    android:gravity="center_horizontal|center_vertical"
    android:textColor="@color/colorBlack"
    android:textSize="@dimen/_13ssp"    app:layout_constraintTop_toBottomOf="@+id/appbarLayout />

The following code was used to customize the way the Amount is displayed in the Customized Mobile SDK Payment Page:


< LinearLayout
    android:id="@+id/amountContainer"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:background="@color/pf_light_gray"
    android:gravity="center"
    app:layout_constraintTop_toBottomOf="@+id/appbarLayout">


    < ImageView
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_marginEnd="10dp"
        android:src="@drawable/merchant"
        android:layout_marginRight="10dp" />

    < TextView
        android:id="@+id/amountTV"
        android:layout_width="wrap_content"
        android:layout_height="@dimen/_38sdp"
        android:gravity="center_horizontal|center_vertical"
        android:textColor="@color/colorBlack"
        android:textSize="@dimen/_13ssp"
        tools:text="10.00 USD" />
< / LinearLayout >

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.

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.

[NOTE] The customized XML file should be added to the layout file in the target project (Merchant Application) to override the SDK file.

Custom-coding a payment processing UI

In this section we outline key information that you need to create your own payment processing UI using the tools in our Android SDK.

Stage 1: Generate an SDK token

You need to generate an SDK token before you can start processing payments using your custom payment processing UI. Refer to the SDK token section earlier in this document for instructions on creating an SDK token.

Stage 2: Creating the card components

You create your custom payment screen by using the following five components included in the Amazon Payment Services Android SDK:

Table of components

The Android Mobile SDK allows merchants to securely integrate the payment functions through Custom Components:

FortCardNumberView (Check CardBrand,CardNumber)
CardCvvView (Check if cvv match cardBrand)
CardExpiryView (Check date)
CardHolderNameView
PayfortPayButton (Collect data from previous Components)

Attributes	Type	Description
app:boxBackgroundShape	Enum 1- none 2- filled 3- outlione	Whether the text input area should be drawn as a filled box, an outline box, or not as a box.
app:hintTextColor	Reference or color Ex : #fff123	Color of the hint text.
app:hintText	String	Hint text to display when the text is empty.
app:textSize	Dimension Ex : 12sp	Size of the text. Recommended dimension type for text is “sp”
app:textColor	Reference or color Ex : #fff123	text Color of the text displayed in the text input area
app:boxStrokeErrorColor	Color Ex : #fff123	The color to use for the box’s stroke in outline box mode when an error is being displayed. If not set, it defaults to errorTextColor if on error state
app:errorTextColor	Color Ex : #fff123	Text color for any error message displayed. If set, this takes precedence over errorTextAppearance.
app:errorTextAppearance	Reference Ex: @style/customStyle	TextAppearance of any error message displayed.
app:boxBackgroundColor	Color Ex : #fff123	The color to use for the box’s background color when in filled box mode.If a non-stateful color resource is specified, default colors will be used for the hover and disabled states.

XML Usage

Card components



   < com.payfort.fortpaymentsdk.views.FortCardNumberView
                android:id="@+id/etCardNumberView"
                android:layout_width="match_parent"
                android:layout_height="wrap_content"
                app:boxBackgroundShape="outline"
                />
 
   
    < com.payfort.fortpaymentsdk.views.CardExpiryView
                    android:id="@+id/etCardExpiry"
                    android:layout_width="match_parent"
                    android:layout_height="wrap_content"
                    app:boxBackgroundShape="outline" />
 
              
                < com.payfort.fortpaymentsdk.views.CardCvvView
                    android:id="@+id/etCardCvv"
                    android:layout_width="match_parent"
                    android:layout_height="wrap_content"
                    app:boxBackgroundShape="outline" />
 
        
       < com.payfort.fortpaymentsdk.views.CardHolderNameView
                android:id="@+id/cardHolderNameView"
                android:layout_width="match_parent"
                android:layout_height="wrap_content"
                app:boxBackgroundShape="outline" />

Stage 3: Initiate the actual payment.

PayfortPayButton

Responsible for collecting card data from Card Components above and Submit Successful payment with simple Few steps also it’s had the capability to do Direct Pay without needs for Card Components


    < com.payfort.fortpaymentsdk.views.PayfortPayButton
        android:id="@+id/btntPay"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        />

PayfortPayButton Methods

/**
 * Responsible for Save token or not
 * @param isRememberMe Boolean
 */
fun isRememberMeEnabled(isRememberMe: Boolean)

/**
 * Update Request After doing Setup
 * @param fortRequest FortRequest
 */
fun updateRequest(fortRequest: FortRequest)


/**
 * this Setup used with Pay with Full Components from outside SDK
 * @param environment String
 * @param request FortRequest
 * @param payComponents PayComponents
 * @param payFortCallback PayFortCallback
 */
fun setup(environment: String,
          request: FortRequest,
          payComponents: PayComponents,
          payFortCallback: PayFortCallback)

/**
 * this Setup used with DirectPay only
 * @param environment String
 * @param request FortRequest
 * @param payFortCallback PayFortCallback?
 */
fun setup(environment: String,
          request: FortRequest,
          payFortCallback: PayFortCallback?)

Sample Code

In this example we explain how to use PayfortPayButton with Card Components in the custom UI screen.

Kotlin

//You Need to Create PayComponents Object that holds all Card Components
val payComponents = PayComponents(etCardNumberView, cvvView = etCardCvv, etCardExpiry, holderNameView = cardHolderNameView)

//then you need to Create FortRequest via FortRequest.class
val fortRequest= FortRequest() // fill all the parameters required 

//then you need to choose the environment Via FortSdk.ENVIRONMENT it's contains TEST and PRODUCTION ENVIRONMENTS 
val  environment=  FortSdk.ENVIRONMENT.TEST

// Finally you need to decleare a PayFortCallback 
var callback=  object : PayFortCallback {
    override fun startLoading() {   }
    override fun onSuccess(requestParamsMap: Map, fortResponseMap: Map) {}
    override fun onFailure(requestParamsMap: Map, fortResponseMap: Map) { }
}

btnPay.setup(environment, fortRequest, payComponents, callback)

Java

//You Need to Create PayComponents Object that holds all Card Components
PayComponents payComponents = new PayComponents(etCardNumberView,  etCardCvv, etCardExpiry,  cardHolderNameView);

//then you need to Create FortRequest via FortRequest.class
FortRequest fortRequest = new FortRequest(); // fill all the parameters required 

//then you need to chsose the environment Via FortSdk.ENVIRONMENT it's contains   TEST and PRODUCTION ENVIRONMENTS
String environment = FortSdk.ENVIRONMENT.TEST;

// Finally you need to decleare a PayFortCallback 
PayFortCallback callback = new PayFortCallback() {
    @Override
    public void startLoading() { }
    @Override
    public void onSuccess(@NotNull Map requestParamsMap, @NotNull Map fortResponseMap) { }
    @Override
    public void onFailure(@NotNull Map requestParamsMap, @NotNull Map fortResponseMap) { }
};

    btnPay.setup(environment, fortRequest, payComponents, callback)

Using Direct Pay

The Direct Pay feature enables Amazon Payment Services merchants to securely process e-commerce transactions using tokenized payment card details.

For customers that already supplied their payment card details in a previous transaction and where a card token was generated, customers need to just provide the card security code to complete their purchase.

The card token and provided card security code can be sent to the Amazon Payment Services Android mobile SDK to complete the customer purchase through Direct Pay operation to complete the order placement using eCommerce channel.

Note you can use Direct Pay both with the standard payment UI or with a customized payment UI.

Direct Pay sample code

In this example we demonstrate how to use PayfortPayButton with DirectPay. This Method is required to pass card_security_code and token_name to FortRequest.

Kotlin

private fun collectRequestMap(sdkToken: String): FortRequest {
    val fortRequest = FortRequest()
    val requestMap: MutableMap = HashMap()
    requestMap["command"] = "AUTHORIZATION"
    requestMap["customer_email"] = "Sam@gmail.com"
    requestMap["currency"] = "AED"
    requestMap["amount"] = "100"
    requestMap["language"] = "en"
    requestMap["card_security_code"] = "123"
    requestMap["token_name"] = "payfort"
    requestMap["merchant_reference"] = "merchant_reference"
    requestMap["sdk_token"] = sdkToken
    fortRequest.requestMap = requestMap
    fortRequest.isShowResponsePage = false
    return fortRequest
}
//you need to Create FortRequest via FortRequest.class
val fortRequest=collectRequestMap("SDK_TOKEN")

//then you need to chsose the environment Via FortSdk.ENVIRONMENT it's contains TEST and PRODUCTION ENVIRONMENTS
val  environment=  FortSdk.ENVIRONMENT.TEST

// Finally you need to decleare a PayFortCallback
var callback=  object : PayFortCallback {
    override fun startLoading() {   }
    override fun onSuccess(requestParamsMap: Map, fortResponseMap: Map) {}
    override fun onFailure(requestParamsMap: Map, fortResponseMap: Map) { }
}

btnPay.setup(environment, fortRequest, callback)

Java

private FortRequest collectRequestMap(String sdkToken) {
    FortRequest fortRequest= new FortRequest();
    Map requestMap = new HashMap<>();
    requestMap.put("command", "AUTHORIZATION");
    requestMap.put("customer_email", "Sam@gmail.com");
    requestMap.put("currency", "AED");
    requestMap.put("amount", "100");
    requestMap.put("language", "en");
    requestMap.put("card_security_code", "123");
    requestMap.put("token_name", "payfort");
    requestMap.put("merchant_reference", "merchant_reference");
    requestMap.put("sdk_token", sdkToken);
    fortRequest.setRequestMap(requestMap);
    fortRequest.setShowResponsePage(false);
    return fortRequest;
}

//you need to Create FortRequest via FortRequest.class
FortRequest fortRequest = collectRequestMap(“SDK_TOKEN”);


//then you need to chsose the environment Via FortSdk.ENVIRONMENT it's contains TEST and PRODUCTION ENVIRONMENTS
String environment = FortSdk.ENVIRONMENT.TEST;

// Finally you need to decleare a PayFortCallback 
PayFortCallback callback = new PayFortCallback() {
    @Override
    public void startLoading() {}

    @Override
    public void onSuccess(@NotNull Map requestParamsMap, @NotNull Map fortResponseMap) {}


    @Override
    public void onFailure(@NotNull Map requestParamsMap, @NotNull   Map fortResponseMap) {}
};

    btnPay.setup(environment, fortRequest, callback);

Amazon Payment Services Android SDK transaction feedback

While a transaction is completed, we will send a response directly to your direct transaction feedback URL. In theory, direct response feedback cannot be interrupted unless the URL you provided for responses is not functional at the time of the response.

We do this so that your server receives a response even if your customer does not successfully redirect to the return URL on your website, which may happen if your customer’s browser or connection fails during the transaction.

Receiving transaction feedback

There are two ways in which you receive transaction feedback:

Direct transaction feedback. Amazon Payment Services sends an immediate payment processing response whenever a transaction is completed.

You can rely on this response for transaction feedback even where your user closed the browser before getting redirected successfully to the redirection URL or where your user was not redirected due to a drop in the internet connection.

Notification feedback. Were we need to provide you with the status of a transaction once it is received. In other words, we send notification feedback to alert you to any changes in the status of a transaction.

For example, if the transaction was pending due to the unavailability of any party to the transaction, the final update will be pushed to your notification feedback endpoint.

Notification feedback deals with a wide range of scenarios and it is critical that your website is configured to receive notification feedback correctly. For example, transaction feedback can alert you to any transactions that were stuck in “uncertain” status, but which have recovered to final status.

Direct feedback allows you to subscribe to transaction updates for uncertain transactions whenever you process a payment. It is a method for receiving the transaction response automatically once the transaction had completed or if there was an update.

Registering Transaction Feedback URLs

To receive transaction feedback, you must register with Amazon Payment Services the transaction feedback URLs you set up on your server. Follow these steps:

Log in to your back-office account.
Select the active channel under Integration Settings > Technical Settings.
Enter your Direct Transaction Feedback URL and Notification Transaction Feedback URL.
Click “Save Changes” button.

Transaction Feedback Implementation

We will send the response via HTTP POST request in POST form format to your webhook URL. The submission type can be changed from POST form to JSON or XML in your APS account settings. We only permit configuring URLs in HTTPS for direct feedback and for notification feedback.

To acknowledge receiving the direct feedback and notification successfully, the webhook URL must return a 2xx or 302 HTTP status. In case the URL returns different HTTP responses, our server will keep retrying up to 10 times until we receive a success response. We wait ten seconds between retries.

You can change and configure the retry mechanism attributes to increase or decrease the number of retries, time between retries and the grace period before we send the notifications.

You must create endpoints that accept direct transaction feedback and notification feedback from us via a webhook. You can customize how transaction feedback works – for example, by including the grace period before a direct feedback notification is sent, and the time elapsed between retrying feedback submission.

To customize transaction feedback, email integration-ps@amazon.com. You can request to change the submission type to JSON or XML. You can also change the grace period or the time interval between the retries please contact us on integration@payfort.com

[NOTE] You can check the direct and notification feedback logs in your back office account to check the details related to the submission like the Transaction Feedback URL which was triggered, The response which our system pushed, the response Code and Status retuned from your Transaction Feedback URL.

[NOTE] The specifics of the data will differ based upon the financial operation that has been processed. Your code must be able to accommodate different data.

Validate API call

Amazon Payment Services offers an API to request validation of the payment card details without performing an actual transaction.

Validate API can help you to initiate an API request in order to validate the input parameters values, this will reduce the possibility of encountered API errors due to wrong user inputs before processing the actual payment card transaction.

Fort SDK has a new method (validate) in FortSdk.class This method can validate FortRequest to check all parameters for validity.

/**
 * Responsible for Validating FortRequest
 * @param context Context
 * @param environment String
 * @param fortRequest FortRequest
 * @param fortCallback PayFortCallback
 */
fun validate(context: Context,
             environment: String
             ,fortRequest: FortRequest,
             fortCallback: PayFortCallback)

Example:

Java


// you need to Create FortRequest via FortRequest.class
FortRequest fortRequest = new FortRequest(); // fill all the parameters required
//then you need to chsose the environment Via FortSdk.ENVIRONMENT
//it's contains TEST and PRODUCTION ENVIRONMENTS
String environment = FortSdk.ENVIRONMENT.TEST;
// Finally you need to decleare a PayFortCallback
PayFortCallback callback = new PayFortCallback() {
    @Override
    public void startLoading() { }
    @Override
    public void onSuccess(@NotNull Map requestParamsMap, @NotNull Map fortResponseMap) { }
    @Override
    public void onFailure(@NotNull Map requestParamsMap, @NotNull Map fortResponseMap) { }
};

FortSdk fortSdk = FortSdk.getInstance();
    fortSdk.validate(this,environment,fortRequest,callback);

Kotlin


// you need to Create FortRequest via FortRequest.class
val fortRequest = FortRequest() // fill all the parameters required
//then you need to chsose the environment Via FortSdk.ENVIRONMENT it's contains TEST and PRODUCTION ENVIRONMENTS
val environment = FortSdk.ENVIRONMENT.TEST
// Finally you need to decleare a PayFortCallback
val callback: PayFortCallback = object : PayFortCallback {
    override fun startLoading() {}
    override fun onSuccess(requestParamsMap: Map, fortResponseMap: Map) {}

    override fun onFailure(requestParamsMap: Map, fortResponseMap: Map) {}
}

val fortSdk = FortSdk.getInstance()
fortSdk.validate(this, environment, fortRequest, callback)

[NOTE] When you make use of the Validate API call you still need to generate a mobile SDK token even though you are not processing a transaction.

Migrating the previous version

In this section we outline the steps you need to take to migrate the Amazon Payment Services Android SDK to the latest release. To complete the migration, follow these steps:

Remove old SDK from Libs Folder
Remove old dependencies from Gradle file that related to old SDK

dependencies {
    implementation  fileTree(include: ['*.jar'], dir: 'libs')
    api project(path: ':FORTSDKv1.6')
    api 'com.android.support:design:29+'
    implementation 'androidx.appcompat:appcompat:1.1.0'
    api 'com.victor:lib:1.0.1'
    api 'com.google.code.gson:gson:2.8.0'
    api 'com.shamanland:fonticon:0.1.8'
    api('com.nispok:snackbar:2.11.+') {
        // exclusion is not necessary, but generally a good idea.
        exclude group: 'com.google.android', module: 'support-v4'
    }
    api 'com.google.guava:guava:19.0'
    api 'org.bouncycastle:bcprov-jdk16:1.46'
}

3: Check the installation steps in section 3

4: Make sure to sync new SDK in your Gradle File

  **File \> Sync Project with Gradle Files**

5: For merchants that already use custom layout feature, they need to replace their custom layout xml files that related to previous SDK versions (< 2.0) and override it with new one.

Note: if you override Arabic xml files you need to delete it since new SDK support it without the need to override it.

Below the difference between old SDK layout and new one:

XML Files	old SDK	new SDK
activity_cc_payment	Download	Download
activity_cc_response	Download	Download
activity_init_secure_conn	Download	Download

6: Change old imports to new imports

Old imports

import com.payfort.fort.android.sdk.base.FortSdk;
import com.payfort.sdk.android.dependancies.commons.Constants.FORT_PARAMS;
import com.payfort.fort.android.sdk.base.FortSdk;
import com.payfort.fort.android.sdk.base.callbacks.FortCallBackManager;
import com.payfort.fort.android.sdk.base.callbacks.FortCallback;
import com.payfort.sdk.android.dependancies.base.FortInterfaces;
import com.payfort.sdk.android.dependancies.models.FortRequest;

New imports

import com.payfort.fortpaymentsdk.constants.Constants.FORT_PARAMS;
import com.payfort.fortpaymentsdk.FortSdk;
import com.payfort.fortpaymentsdk.callbacks.FortCallBackManager;
import com.payfort.fortpaymentsdk.callbacks.FortCallback;
import com.payfort.fortpaymentsdk.callbacks.FortInterfaces;
import com.payfort.fortpaymentsdk.domain.model.FortRequest;

7: Make Sure to enable ViewBinding in your project

To enable view binding in a module, set the viewBinding build option to true in the module-level build.gradle file, as shown in the following example:

android {
    ...
    buildFeatures {
        viewBinding true  
   }
}

8: Make Sure to use Java 8

To start using supported Java 8 language features, update the Android plugin to 3.0.0 (or higher). After that, for each module that uses Java 8 language features (either in its source code or through dependencies), update the module’s build.gradle file, as shown below:

android {
    ...
    // Configure only for each module that uses Java 8
    // language features (either in its source code or
    // through dependencies).
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
                targetCompatibility JavaVersion.VERSION_1_8
    }
    // For Kotlin projects
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Appendix: About the Software

About this software

The Amazon Payment Services Android mobile SDK allows merchants to securely integrate payment functionality into a native Android app. It 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 easily be offered thanks to the Android Mobile SDK. In turn, this gives the merchants’ customers a smooth, pleasing user experience thanks to in-app payment functions through the native applications. (move to about this software)

Supported Platforms

The Amazon Payment Services Android SDK supports devices running Android 4.1.x and later (API level 16). In other words, Android Ice Cream Sandwich or higher is supported. This release supports Android Pie API 28.

Localization

You can use both English and Arabic when you implement the Android SDK.

Screen Orientation

Currently, portrait is the only orientation supported within the Amazon Payment Services mobile SDK – unless you build a customized payment integration.

Supported Payment Methods

Using the Android SDK the merchant can process debit or credit card transactions only.

Supported Payment Options

The supported credit card payment options are VISA, MASTERCARD, American Express (AMEX), MADA and MEEZA.

iOS Mobile SDk

Before you start the integration

Read through the following steps first to understand how the integration process works. This will help you to understand why these steps are required and why you need to follow a specific sequence.

Step 1: Access your test account

You need to make sure that you have access to a test account with Amazon Payment Services. It is a full test environment that allows you to fully simulate transactions.

Step 2: Choose between a standardized or custom payment UI

The Amazon Payment Services iOS SDK provides you with a standard payment UI that you can use to quickly integrate in-app payments. The standard UI offers limited customizability.

Alternatively, you can choose to build your own payment UI using Amazon Payment Services iOS SDK building blocks, we describe this in the section on custom-coding a payment processing UI.

Step 3: Make sure that you are using the correct integration type

Step 4: Install the Amazon Payment Services iOS SDK in your development environment

You need to download our iOS SDK from the link provided. Next you need to include the iOS SDK in your Xcode project by following the steps in the next section. You are also required to install the library and to integrate the iOS SDK into your app.

Step 5: Create a test transaction request

You need to create a test transaction request. Processing a valid API request depends on the transaction parameters included, you need to check the documentation and review every parameter to reduce the errors in processing the transaction.

Step 6: Process a transaction response

After every payment, Amazon Payment Services returns the transaction response on the URL configured in your account under Technical Settings, Channel Configuration.

For more details review the transaction feedback instructions in this section. 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 7: Test and Go Live

Mobile SDK transaction workflow

Below we describe the transaction workflow that occurs when you process a payment using the Amazon Payment Service iOS Mobile SDK.

Your customer clicks on the Pay button in your app.
Your merchant system (back-end) generates a mobile SDK token using the Amazon Payment Services API.
Your app passes the parameters, including the SDK token, to the iOS mobile SDK.
The iOS mobile SDK starts a secure connection and sends the transaction request to the Amazon Payment Services server to be validated.
The Amazon Payment Services API validates the SDK token, device_ID and other request parameters and returns the validation response to the iOS SDK.
Assuming validation is passed your merchant app displays a payment page to the customer.
Your customer enters their payment details on the payment page in the iOS SDK prompt on their device.
The Amazon Payment Services iOS SDK validates your customer’s details and sends a transaction (Authorization or Purchase) request to the relevant payment processor and issuing bank.
The payment processor processes the transaction request and returns a transaction response to the iOS SDK.
The Amazon Payment Services iOS SDK returns the transaction response to your merchant app.
Your merchant app displays the response to your customer.

transaction-workflow

Installing the Mobile SDK

These are the first steps you need to follow to install the Amazon Payment Services iOS SDK in your iOS application.

Include the SDK in your Xcode project

You have two options for including the SDK in your Xcode project. You can do so manually, or you can include the SDK by using CocoaPods

Manual installation

Obtain the Amazon Payment Services iOS Mobile SDK by downloading it from the Amazon Payment Services website.
Extract the folder you downloaded in the previous step.
Drag PayFortSDK.xcframework into the Frameworks, Libraries, and Embedded Content section of your target.

Installation using CocoaPods:

[NOTE]: The PayFort SDK is distributed as an XCFramework, therefore you are required to use Cocoapods 1.9.0 or newer.

Add the following code to your Podfile (inside the target section):

 
pod 'PayFortSDK'

Add the following to the bottom of your Podfile:

 
 post_install do |installer|
      installer.pods_project.targets.each do |target|
        if ['PayFortSDK'].include? target.name
          target.build_configurations.each do |config|
              config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
          end
        end
      end
    end

Run the following command:

pod install

[NOTE]: Ensure it is linked once in the Linked Framework and Libraries or just drag the PayFortSDK.xcframework to Embedded Binaries in the general tab in the project settings.

[NOTE]: In Xcode, secondary-click your project’s .plist file and select Open As Source Code. Insert the following XML snippet into the body of your file just before the final, as below:

< dict>element
NSAppTransportSecurity
< dict>
NSAllowsArbitraryLoads
< /dict>

Ensuring your application does not disconnect in background mode

To ensure that your app does not disconnect from the SDK when it goes into the background make sure to add this code:

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
})
}

Creating a mobile SDK token

To get started with our iOS mobile SDK you must first establish the ability to generate a mobile SDK token.

[NOTE]: The creation and initiation of a mobile SDK token happens on your server – your server must generate the token by sending a request to the Amazon Payment Services API.

[NOTE:] A unique authentication token must be created for each transaction. Each authentication token has a life-time of only one hour if no new request from the same device is sent.

Mobile SDK token URLs

These are the URLs you need to use when you request a mobile SDK token for your iOS app:

Test Environment URL

https://sbpaymentservices.payfort.com/FortAPI/paymentApi

Production Environment URL

https://paymentservices.payfort.com/FortAPI/paymentApi

Submitting token request parameters

You need to submit parameters as a REST POST request using JSON. Below we list the range of parameters for the iOS mobile SDK token request.

iOS Mobile SDK Token Request Parameters

When you send your request for an iOS mobile SDK token you must send the following parameters to Amazon Payment Services:

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

[NOTE:] device_id - This value to be generated from the UIDevice Class Reference, and you can generate this parameter by using the following command: [payFort getUDID]

iOS Mobile SDK Token Response Parameters

These parameters will be returned in the Amazon Payment Services 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 Amazon Payment Services 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

NOTE: Every parameter the merchant sends in the request should be received by the merchant in the response - even the optional parameters.

Processing transactions with the iOS SDK

In this section we outline how you process a transaction using the iOS mobile SDK.

Two routes for payment processing

As a merchant you have two ways in which you can process payments using the Amazon Payment Services iOS mobile SDK.

Standard payment screen. You can use the standard Amazon Payment Services iOS SDK interface to display a standard payment screen.

This standard payment view is customizable in three ways. You can hide the loading screen, and you can change the presentation style from full screen to OS default. You can also customize some of the UI elements. We address customizing the standard payment screen in this section.
Custom integration. You can choose to build your own payment processing screen by coding your own payment processing screen. With this mobile SDK feature, we allow merchants to integrate a native app checkout experience without displaying our standard payment screen – while still using SDK features for rapid go-live.

With this integration route your customers can securely pay using a custom merchant checkout interface. The SDK provides card input fields and a pay button that merchants can encapsulate inside their checkout interface to match their own inline customer experience.

The Amazon Payment Services SDK will securely transmit the completed card details to the Amazon Payment Services API for processing in order to complete the transaction. We discuss the custom-coded payment UI in this section.

Steps for standard checkout

These are the steps you need to follow to perform a checkout using our standard UI. See the next section for building your own customized payment UI.

1- Import the framework into your app

Start by importing the Amazon Payment Service iOS SDK library. You do so by using the following code:

Objective-C

  #import < PayFortSDK/PayFortSDK-Swift.h>

Swift

  import PayFortSDK

2- Initialize the controllers

Initialize PayFortController within the targeted environment. You set the target environment by setting one of the two ENUM, either PayFortEnviromentSandBox or PayFortEnviromentProduction

Objective-C

  PayFortController *payFort = [[PayFortController alloc]initWithEnviroment: PayFortEnviromentSandBox];

Swift

  let payFort = PayFortController.init(enviroment: .sandBox)

3- Preparing Request Parameters

Set a dictionary that contains all keys and values for the SDK

Objective-C

NSMutableDictionary *request = [[NSMutableDictionary alloc]init];
[request setValue:@"10000" forKey:@"amount"];
[request setValue:@"AUTHORIZATION" forKey:@"command"];
[request setValue:@"USD" forKey:@"currency"];
[request setValue:@ "email@domain.com" forKey:@"customer_email"]
[request setValue:@"en" forKey:@"language"]; 
[request setValue:@"112233682686" forKey:@"merchant_reference"]
[request setValue:@"SDK TOKEN GOES HERE" forKey:@"sdk_token"];
[request setValue:@"" forKey:@"payment_option"];
[request setValue:@"gr66zzwW9" forKey:@"token_name"];

Swift

let request = ["amount" : "1000",
    "command" : "AUTHORIZATION",
    "currency" : "AED",
    "customer_email" : "rzghebrah@payfort.com",
    "installments" : "",
    "language" : "en",
    "sdk_token" : "token"]

4 . Response callback function

Amazon Payment Services allows you retrieve and receive the response parameters after processing a transaction once the transaction is completed. It only happens during the installation process. This is the code you need to use: Objective-C

[payFort callPayFortWithRequest:request currentViewController:self
                            success:^(NSDictionary *requestDic, NSDictionary *responeDic) { NSLog(@"Success");
        NSLog(@"responeDic=%@",responeDic);
    }
                           canceled:^(NSDictionary *requestDic, NSDictionary *responeDic) { NSLog(@"Canceled");
        NSLog(@"responeDic=%@",responeDic);
    }
                              faild:^(NSDictionary *requestDic, NSDictionary *responeDic, NSString *message) {
        NSLog(@"Faild");
        NSLog(@"responeDic=%@",responeDic);
    }];

Swift

payFort.callPayFort(withRequest: request, currentViewController: self, success: { (requestDic, responeDic) in    print("success")
        },
        canceled: { (requestDic, responeDic) in
            print("canceled")
        },    faild: { (requestDic, responeDic, message) in print("faild")
})

iOS mobile SDK operations

Request parameters

This is a list of the parameters you need to send when you send a request to the iOS SDK.

ATTRIBUTES	Description
command Alpha Mandatory max: 20	Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences.
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 Amazon Payment Services 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: . ; / _ - , `'` @
billing_stateProvince Alphanumeric Optional max: 20	The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
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. Reference: ISO_3166-2 Example1: AM Example2: AT
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.
agreement_id Alphanumeric Optional max: 100	identifier for the agreement with the payer to process payments to be used in recurring payments ( Required for MADA )
recurring_mode Alphanumeric Optional max: 20	Indicates if the subsequent payments within the agreement has same/different amount or unscheduled (unknown interval/amount). ( Required for MADA ) Possible/ expected values: UNSCHEDULED, VARIABLE, FIXED
recurring_transactions_count Alphanumeric Optional max: 100	The number of merchant-initiated payments within the recurring payment agreement. ( Required for MADA and only if recurring_mode = VARIABLE or FIXED )

Response parameters

ATTRIBUTES	Description
command Alpha Max: 20	Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences.
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 Amazon Payment Services 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
billing_stateProvince Alphanumeric max: 20	The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
billing_provinceCode Alphanumeric 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. Reference: ISO_3166-2 Example1: AM Example2: AT
billing_street Alphanumeric 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 max: 100	The second line of the address (if provided).
billing_postcode Alphanumeric max: 10	The post code or zip code of the address.
billing_country Alphanumeric min:3, max: 3	The 3 letter ISO standard Alphanumeric country code of the address.
billing_company Alphanumeric max: 100	The name of the company associated with this address.
billing_city Alphanumeric max: 100	The city portion of the address.
shipping_stateProvince Alphanumeric max: 20	The state or province of the address.
shipping_provinceCode Alphanumeric 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 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 max: 100	The second line of the address (if provided).
shipping_source Alphanumeric	How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE
shipping_sameAsBilling Alphanumeric	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 max: 10	The post code or zip code of the address.
shipping_country Alphanumeric min:3, max: 3	The 3 letter ISO standard Alphanumeric country code of the address.
shipping_company Alphanumeric max: 100	The name of the company associated with this address.
shipping_city Alphanumeric max: 100	The city portion of the address.
agreement_id Alphanumeric max: 100	identifier for the agreement with the payer to process payments to be used in recurring payments

[NOTE:] Every parameter the Merchant sends in the Request should be received by the Merchant in the Response - even the optional ones.

Complete sample code for standard UI checkout:

The following sample code shows you how to process a payment using the standard view. The code sample illustrates how you send a request operation in the mobile SDK.

Objective-C

- (void)viewDidLoad {
    [super viewDidLoad];
    payfort = [[PayFortController alloc] initWithEnviroment:PayFortEnviromentSandBox];
}    

NSMutableDictionary *requestDictionary = [[NSMutableDictionary alloc]init]; 
[requestDictionary setValue:@"10000" forKey:@"amount"];
[requestDictionary setValue:@"AUTHORIZATION" forKey:@"command"]; 
[requestDictionary setValue:@"USD" forKey:@"currency"];
[requestDictionary setValue:@"email@domain.com" forKey:@"customer_email"];
[requestDictionary setValue:@"en" forKey:@"language"];
[requestDictionary setValue:@"112233682686" forKey:@"merchant_reference"];
[requestDictionary setValue:@"" forKey:@"payment_option"];
[requestDictionary setValue:@"gr66zzwW9" forKey:@"token_name"];
    
    [payFort callPayFortWithRequest:requestDictionary currentViewController:self success:^(NSDictionary *requestDic, NSDictionary *responeDic) {
        
    } canceled:^(NSDictionary *requestDic, NSDictionary *responeDic) {
    } faild:^(NSDictionary *requestDic, NSDictionary *responeDic, NSString *message) {
        
    }];

Swift

let request = ["amount" : "1000",
                           "command" : "AUTHORIZATION",
                           "currency" : "AED",
                           "customer_email" : "rzghebrah@payfort.com",
                           "installments" : "",
                           "language" : "en",
                           "sdk_token" : "token"]

payFort.callPayFort(withRequest: request, currentViewController: self,
                                      success: { (requestDic, responeDic) in
                                        print("success")
                                        print("responeDic=\(responeDic)")
                                        print("responeDic=\(responeDic)")
                                        
                                      },
                                      canceled: { (requestDic, responeDic) in
                                        print("canceled")
                                        print("responeDic=\(responeDic)")
                                        print("responeDic=\(responeDic)")
 
                                      },
                                      faild: { (requestDic, responeDic, message) in
                                        print("faild")
                                        print("responeDic=\(responeDic)")
                                        print("responeDic=\(responeDic)")
                    })

Customizing the standard payment UI

When you use the standard payment UI you can customize the payment UI presented by our iOS SDK in a number of ways to better reflect your business. We outline your options below.

Customizing the standard payment UI

You can customize the standard payment user interface in your iOS app. This is an example of a customized payment UI:

iOS payment layout

Standard vs. Customized Mobile SDK Payment Page

Follow these steps to configure a customized payment UI:

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 IBOutlet UILabel *titleLbl;

IBOutlet UIButton *BackBtn;
IBOutlet UILabel *PriceLbl;
IBOutlet JVFloatLabeledTextField *CardNameTxt; 
IBOutlet JVFloatLabeledTextField *CardNumberTxt; 
IBOutlet JVFloatLabeledTextField *CVCNumberTxt; 
IBOutlet JVFloatLabeledTextField *ExpDateTxt; 
IBOutlet UILabel *cardNumberErrorlbl;
IBOutlet UILabel *cVCNumberErrorlbl;
IBOutlet UILabel *expDateErrorlbl;
IBOutlet UISwitch *savedCardSwitch;
IBOutlet UIButton *paymentBtn;
IBOutlet UILabel *saveCardLbl;
IBOutlet UIImageView *imageCard;

Assign new created xib file to Amazon Payment Services controller.

[payFort setPayFortCustomViewNib:@\"PayFortView2\"\];

[NOTE]. If you call Arabic view and the Arabic view not existed the application will crash.\ Don’t forget to set the custom view field in the identity inspector

Hiding the Amazon Payment Service loading prompt

There is an option to hide the loading prompt when the iOS SDK initializes the connection request. You can disable the loading prompt by using following option:

Objective-C

  
payFort.hideLoading = YES;

Swift

  
 payFort.hideLoading = true

Changing the presentation style

It’s easy to change the presentation style from full screen to default by using the following property:

Objective-C

  
payFort.presentAsDefault  = YES;

Swift

  
 payFort.presentAsDefault  = true

[NOTE]: The default type is full screen when you set the value to false, when set to true it will appear according to the OS default.

iOS SDK response

There is an option to show the response view more directly in an elegant view that shows the response results either as success or failed. You do so by activating the following option:

Objective-C

  
payFort.isShowResponsePage   = YES;

Swift

  
 payFort.isShowResponsePage  = true

Using a custom payment processing UI

In this section we outline the key information you need to create your own payment processing screen using the tools in the iOS SDK.

Stage 1: Generate an SDK token

Stage 2: Create the card components

You create your custom payment screen by using the following five components included in the Amazon Payment Services iOS SDK:

CardNumberView
CVCNumberView
ExpiryDateView
CardHolderNameView
PayButton

Attributes	Type	Description
textColor	UIColor	The input text filed text color
fontStyle	UIFont	The input text filed font style
backgroundColor	UIColor	The input text filed background color
errorText	String	The Error Label text
errorFontStyle	UIFont	The Error Label text Font Style
errorTextColor	UIColor	The Error Label text Text Color
titleText	String	The Title Label text
titleTextColor	UIColor	The Title Label text Color
titleErrorTextColor	UIColor	The Error Title Label text Color
titleFontStyle	UIFont	The Title Label Font style

Components Views

Item property, all these properties are available for each component.

Swift

let property = Property()
        property.textColor
        property.fontStyle
        property.backgroundColor
        property.errorFontStyle
        property.errorTextColor
        property.titleTextColor
        property.titleErrorTextColor
        property.titleFontStyle

Objective-c

Property *property = [[Property alloc] init]
        property.textColor
        property.fontStyle
        property.backgroundColor
        property.errorFontStyle
        property.errorTextColor
        property.titleTextColor
        property.titleErrorTextColor
        property.titleFontStyle

CardNumberView:

The CardNumberView inheritance from UIView, CardNumberView is used to validate the card number, card brand and card number length.

Swift

@IBOutlet private weak var cardNumberView: CardNumberView!
cardNumberView.property = property

Objective-c

@property (nonatomic, weak) IBOutlet CardNumberView *cardNumberView;
cardNumberView.property = property

ExpiryDateView:

The ExpiryDateView inheritance from UIView, ExpiryDateView is used to check the expiry date for the credit card.

Swift

@IBOutlet private weak var expiryDateView: ExpiryDateView!
     expiryDateView.property = property

Objective-c

@property (nonatomic, weak) IBOutlet ExpiryDateView *expiryDateView;
     expiryDateView.property = property

CVCNumberView

The CVCNumberView inheritance from UIView, CVCNumberView used to check if cvc matches cardBrad.

Swift

@IBOutlet private weak var cvcNumberView: CVCNumberView!
   cvcNumberView.property = property

Objective-c

@property (nonatomic, weak) IBOutlet CVCNumberView *cvcNumberView;
     cvcNumberView.property = property

HolderNameView

The HolderNameView inheritance from UIView, HolderNameView is used to fill the card holder name.

Swift

@IBOutlet private weak var holderNameView: HolderNameView!
     holderNameView.property = property

Objective-c

@property (nonatomic, weak) IBOutlet holderNameView *holderNameView;
     holderNameView.property = property

ErrorLabel

It will show any error message for owner card view, you can set your custom UILabel, Example:

Swift

@IBOutlet private weak var cardNumberErrorLabel: ErrorLabel!
   cardNumberView.errorLabel = cardNumberErrorLabel

Objective-c

@property (nonatomic, weak) IBOutlet ErrorLabel *cardNumberErrorLabel;
   cardNumberView.errorLabel = cardNumberErrorLabel

Example of components views in Objective-C and Swift

This is one example of how to customize the component:

Swift

let property = Property()
    property.textColor = .yellow
    property.backgroundColor = .green
    property.errorTextColor = .green
    property.titleTextColor = .red    
    cardNumberView.property = property

Objective-c

Property * property = [[Property alloc] init];
    property.textColor = UIColor.yellowColor;
    property.backgroundColor = UIColor.greenColor;
    property.errorTextColor = UIColor.greenColor;
    property.titleTextColor = UIColor.redColor;    
    cardNumberView.property = property;

Stage 3: Initiate the payment

PayButton

Used to collect the card data from card components above and to submit successful payment. With a few simple steps it also has the capability to perform Direct Pay without the need for the card component, see the next section.

PayfortPayButton methods

/**
     Update Request After doing Setup
     - Parameter request: a new request dictionary
     */
    public func updateRequest(request: [String: String])
    
 /**
     Responsible for Save token or not
     - Parameter enabled: a new bool value
     */
    public func isRememberEnabled(_ enabled: Bool)

Sample code

In this section we illustrate how you use the PayButton using sample code for Swift and Objective-C.

Swift

@IBOutlet weak var payButton: PayButton!
    
    let builder = PayComponents(cardNumberView: cardNumberView, expiryDateView: expiryDateView, cvcNumberView: cvcNumberView, holderNameView: holderNameView, rememberMe: saveCardSwitch.isOn)

    payButton.setup(with: request, enviroment: enviroment, payComponents: builder, viewController: self) {
    // Process started
    } success: { (requestDic, responeDic) in
    // Process success
    } faild: { (requestDic, responeDic, message) in
    // Process faild
    }

Objective-C

@property (nonatomic, weak) IBOutlet PayButton *payButton;
    
    PayComponents *builder = [[PayComponents alloc] initWithCardNumberView:cardNumberView expiryDateView: expiryDateView cvcNumberView: cvcNumberView, holderNameView: holderNameView rememberMe: saveCardSwitch.on];
    
    [payButton setupWithRequest: request
                     enviroment: enviroment
                  payComponents: builder
          currentViewController: self
                        Success:^(NSDictionary *requestDic, NSDictionary *responeDic) {
    } Canceled:^(NSDictionary *requestDic, NSDictionary *responeDic) {
    } Faild:^(NSDictionary *requestDic, NSDictionary *responeDic, NSString *message) {
    }];

Using Direct Pay

The Direct Pay feature enables Amazon Payment Services merchants to securely process e-commerce transactions using tokenized payment card details.

For customers that already supplied their payment card details in a previous transaction and where a card token was generated, customers need to just provide the card_security_code to complete their purchase.

The card token and provided card security code can be sent to the Amazon Payment Services iOS mobile SDK to complete the customer purchase through Direct Pay operation to complete the order placement using eCommerce channel.

Note you can use Direct Pay both with the standard payment UI or with a customized payment UI.

Direct Pay sample code

\ Swift

@IBOutlet weak var directPayButton: PayButton!
    
    // request should has all mandatory params and also you need to send card_security_code, token_name
    
    let request = ["amount" : "1000",
                   "command" : "AUTHORIZATION",
                   "currency" : "AED",
                   "customer_email" : "test@payfort.com",
                   "language" : "en",
                   "card_security_code" : "123",
                   "token_name" : "payfort",
                   "merchant_reference" : "merchant reference",
                   "sdk_token" : "token"]
    
    directPayButton.setup(with: request, enviroment: enviroment, viewController: self) {
    // Process started
    } success: { (requestDic, responeDic) in
    // Process success
    } faild: { (requestDic, responeDic, message) in
    // Process faild
    }

Objective-c

@property (nonatomic, weak) IBOutlet PayButton *directPayButton;
    
    NSMutableDictionary *requestDictionary = [[NSMutableDictionary alloc]init];
    [requestDictionary setValue:@"10000" forKey:@"amount"];
    [requestDictionary setValue:@"AUTHORIZATION" forKey:@"command"];
    [requestDictionary setValue:@"USD" forKey:@"currency"];
    [requestDictionary setValue:@"email@domain.com" forKey:@"customer_email"];
    [requestDictionary setValue:@"en" forKey:@"language"];
    [requestDictionary setValue:@"112233682686" forKey:@"merchant_reference"];
    [requestDictionary setValue:@"payfort" forKey:@"token_name"];
    [requestDictionary setValue:@"123" forKey:@"card_security_code"];
    [requestDictionary setValue:@"token" forKey:@"sdk_token"];
    
    [directPayButton setupWithRequest: request
                           enviroment: enviroment
                currentViewController: self
                              Success:^(NSDictionary *requestDic, NSDictionary *responeDic) {
    } Canceled:^(NSDictionary *requestDic, NSDictionary *responeDic) {
    } Faild:^(NSDictionary *requestDic, NSDictionary *responeDic, NSString *message) {
    }];

Amazon Payment Services iOS SDK transaction feedback

While a transaction is processed, we will send a response directly to your direct transaction feedback URL. In theory, direct response feedback cannot be interrupted unless the URL you provided for responses is not functional at the time of the response.

Receiving transaction feedback

There are two ways in which you receive transaction feedback:

Direct transaction feedback. Amazon Payment Services sends an immediate payment processing response whenever a transaction is completed.

For example, if the transaction was pending due to the unavailability of any party to the transaction, the final update will be pushed to your notification feedback endpoint.

Notification feedback deals with a wide range of scenarios and it is critical that your website is configured to receive notification feedback correctly. For example, transaction feedback can alert you to any transactions that were stuck in \“uncertain\” status, but which have recovered to final status.

Registering Transaction Feedback URLs

To receive transaction feedback, you must register with Amazon Payment Services the transaction feedback URLs you set up on your server. Follow these steps:

Log in to your back-office account.
Select the active channel under Integration Settings > Technical Settings.
Enter your Direct Transaction Feedback URL and Notification Transaction Feedback URL.
Click the “Save Changes” button.

Transaction Feedback Implementation

You can change and configure the retry mechanism attributes to increase or decrease the number of retries, time between retries and the grace period before we send the notifications.

[NOTE]: You can check the direct and notification feedback logs in your back office account to check the details related to the submission like the Transaction Feedback URL which was triggered, The response which our system pushed, the response Code and Status retuned from your Transaction Feedback URL.

[NOTE]: The specifics of the data will differ based upon the financial operation that has been processed. Your code must be able to accommodate different data.

Validate API

Amazon Payment Services offers an API to request validation of the payment card details without performing an actual transaction.

ValidateAPI can help you to initiate an API request in order to validate the input parameters values, this will reduce the possibility of encountered API errors due to wrong user inputs before processing the actual payment card transaction.

Swift

let request = ["amount" : "1000",
               "command" : "AUTHORIZATION",
               "currency" : "AED",
               "customer_email" : "test@payfort.com",
               "language" : "en",
               "sdk_token" : "token"]
 
   payFortController.callValidateAPI(with: request) {
                 // Process started
                } success: {
                 // Process success
                } faild: { (requestDic, responeDic, message) in
                 // Process faild
                })

Objective-c

NSMutableDictionary *request = [[NSMutableDictionary alloc]init];
    [requestDictionary setValue:@"10000" forKey:@"amount"];
    [requestDictionary setValue:@"AUTHORIZATION" forKey:@"command"];
    [requestDictionary setValue:@"USD" forKey:@"currency"];
    [requestDictionary setValue:@"email@domain.com" forKey:@"customer_email"];
    [requestDictionary setValue:@"en" forKey:@"language"];
    [requestDictionary setValue:@"112233682686" forKey:@"merchant_reference"];
    [requestDictionary setValue:@"token" forKey:@"sdk_token"];
    
    
    [payFortController callValidateAPIWithRequest: request
                                       ShowLoader:^() {
    } Success:^(NSDictionary *requestDic, NSDictionary *responeDic) {
    } Faild:^(NSDictionary *requestDic, NSDictionary *responeDic, NSString *message) {
    }];

[NOTE]: When you make use of the Validate API call you still need to generate a mobile SDK token even though you are not processing a transaction.

Migrating from version 2.3 of the SDK

In this section we outline the steps you need to take to migrate from version 2.3 of the Amazon Payment Services iOS SDK to the latest release. To complete the migration follow these steps:

Remove PayFortSDK.framework and PayFortSDK.bundle
Use CocoaPods or manual integration – by dragging the PayFortSDK.xcframework into your project
Import PayFortSDK.xcframework:

Objective-C

The replace import is shown below

//From
#import 
//To 
#import

Swift import

If you’re using Swift you can import PayFortSDK directly on your controller, there is no need to use Bridging-Header any more

  import PayFortSDK

Change callPayFortWithRequest method as below:

Objective-C

//From 
[payFort callPayFortWithRequest:myRequest currentViewController:self
                Success:^(NSDictionary *requestDic, NSDictionary *responeDic) {
 
                } Canceled:^(NSDictionary *requestDic, NSDictionary *responeDic) {
                            
                } Faild:^(NSDictionary *requestDic, NSDictionary *responeDic,                                 
                }];
                        
//TO
[payFort callPayFortWithRequest:myRequest currentViewController:self
            success:^(NSDictionary *requestDic, NSDictionary *responeDic) {
 
            } canceled:^(NSDictionary *requestDic, NSDictionary *responeDic) {
                            
            } faild:^(NSDictionary *requestDic, NSDictionary *responeDic,                                 
            }];

Swift

Chane the callPayFortWithRequest request param from NSMutableDictionary to Dictionary

Change callPayFortForApplePayWithRequest method as below:

Objective-C

//From
[payFort callPayFortForApplePayWithRequest:myRequest
                    applePayPayment:payment
              currentViewController:self
                            Success:^(NSDictionary *requestDic, NSDictionary *responeDic) {
 
                            }
                              Faild:^(NSDictionary *requestDic, NSDictionary *responeDic, NSString *message) {
                                  completion(PKPaymentAuthorizationStatusFailure);
                                 
                              }];
 
//To 
 
[payFort callPayFortForApplePayWithRequest:myRequest
                    applePayPayment:payment
              currentViewController:self
                            success:^(NSDictionary *requestDic, NSDictionary *responeDic) {
 
                            }
                              faild:^(NSDictionary *requestDic, NSDictionary *responeDic, NSString *message) {
                                  completion(PKPaymentAuthorizationStatusFailure);
                               
                              }];

Swift

Change callPayFortForApplePay request param from NSMutableDictionary to Dictionary

Change callPayFortForApplePay method as below

Objective-C

//From
paycontroller.callPayFortForApplePay(withRequest: ["":""],
                                             applePay: payment,
                                             currentViewController: self) { (requestDic, responeDic) in
                                             } faild: { (requestDic, responeDic, message) in
        }
 
//To
paycontroller.callPayFortForApplePay(withRequest: ["":""],
                                             applePayPayment: payment,
                                             currentViewController: self) { (requestDic, responeDic) in
                                             } faild: { (requestDic, responeDic, message) in
        }

Swift

No changes necessary

Change environment as follows:

Objective-C

From KPayFortEnviromentSandBox to PayFortEnviromentSandBox

From KPayFortEnviromentProduction to PayFortEnviromentProduction

Swift

From KPayFortEnviromentSandBox to .sandbox

From KPayFortEnviromentProduction to *.production\ *

Modify the IsShowResponsePage property:

Objective-C:

From IsShowResponsePage to isShowResponsePage

Swift

No changes needed

HideLoading property:

Objective-C:

From HideLoading to hideLoading

Swift

No changes needed.

Appendix: About the Software

About this software

The Amazon Payment Services iOS mobile SDK allows merchants to securely integrate payment functionality into a native iOS app. It 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 easily be offered thanks to the iOS Mobile SDK.

In turn, this gives the merchants’ customers a smooth, pleasing user experience thanks to in-app payment functions through the native applications.

Supported Platforms

The Amazon Payment Services iOS SDK supports IOS 12.2+ and Xcode 11.0 and above.

Localization

You can use both English and Arabic when you implement the iOS SDK.

Screen Orientation

Currently, portrait is the only orientation supported within the Amazon Payment Services mobile SDK – unless you build a customized payment integration.

Supported Payment Methods

Using the iOS SDK the merchant can process debit or credit card transactions only.

Supported Payment Options

The supported credit card payment options are VISA, MASTERCARD, American Express (AMEX), MADA and MEEZA.

React Native Mobile SDK

Before you start the integration

Read through the following steps first to understand how the integration process works. This will help you to understand why these steps are required and why you need to follow a specific sequence.

Step 1: Access your test account

You need to make sure that you have access to a test account with Amazon Payment Services. It is a full test environment that allows you to fully simulate transactions.

Step 2: Choose between a standardized or custom payment UI

The Amazon Payment Services React Native SDK provides you with a standard payment UI that you can use to quickly integrate in-app payments. The standard UI offers limited customizability.

Alternatively, you can choose to build your own payment UI using Amazon Payment Services React Native SDK building blocks, we describe this in the section on custom-coding a payment processing UI.

Step 3: Make sure that you are using the correct integration type

Step 4: Install the Amazon Payment Services React Native SDK in your development environment

You need to add the repositories to your build file and add the SDK to your build.gradle.

Step 5: Create a test transaction request

Step 6: Process a transaction response

After every payment, Amazon Payment Services returns the transaction response on the URL configured in your account under Technical Settings, Channel Configuration.

Step 7: Test and Go Live

Mobile SDK transaction workflow

Below, we describe the transaction workflow when you process a payment using the Amazon Payment Service React Native Mobile SDK.

Your customer clicks on the Pay button in your app.
Your merchant system (back-end) generates a mobile SDK token using the Amazon Payment Services API
Your app passes the parameters, including the SDK token, to the React Native mobile SDK
The React Native mobile SDK starts a secure connection and sends the transaction request to the Amazon Payment Services server to be validated.
The Amazon Payment Services API validates the SDK token, device_ID and other request parameters and returns the validation response to the React Native SDK.
Assuming validation is passed your merchant app displays a payment page to the customer.
Your customer enters their payment details on the payment page in the React Native SDK prompt on their device.
The Amazon Payment Services React Native SDK validates your customer’s details and sends a transaction (Authorization or Purchase) request to the relevant payment processor and issuing bank.
The payment processor processes the transaction request and returns a transaction response to the React Native SDK
The Amazon Payment Services React Native SDK returns the transaction response to your merchant app
Your merchant app displays the response to your customer

transaction workflow

Installing the Mobile SDK

These are the first steps you need to follow to integrate the Amazon Payment Services React Native SDK into your React Native application.

Installing the React Native Mobile SDK

You need to complete below steps to install the Amazon Payment Services React Native SDK.

Step 1

Install the React Native Package.

npm install rn-amazon-payment-services

Android Specific Installations

a. You need to add the repository to your build file. Add it in your root build.gradle at the end of repositories:

allprojects {
  repositories {
    ...
    maven { url https://android-sdk.payfort.com }
  }
}

b. You need to set the following two permission so that the React Native mobile SDK works properly:

  < uses-permission android:name="android.permission.INTERNET" />
  < uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

iOS Specific Installations

a. Add the following code to your Podfile (inside the target section):

 
pod 'PayFortSDK'

b. Add the following to the bottom of your Podfile:

 
 post_install do |installer|
      installer.pods_project.targets.each do |target|
        if ['PayFortSDK'].include? target.name
          target.build_configurations.each do |config|
              config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
          end
        end
      end
    end

c. Run the following command inside /iOS folder:

pod install

Creating a mobile SDK token

To get started with our React Native mobile SDK you must first establish the ability to generate a mobile SDK token.

NOTE: The creation and initiation of a mobile SDK token happens on your server – your server must generate the token by sending a request to the Amazon Payment Services API.

A unique authentication token must be created for each transaction. Each authentication token has a life-time of only one hour if no new request from the same device is sent.

Mobile SDK token URLs

These are the URLs you need to use when you request a mobile SDK token for your React Native app:

Test Environment URL

https://sbpaymentservices.payfort.com/FortAPI/paymentApi

Production Environment URL

https://paymentservices.payfort.com/FortAPI/paymentApi

Submitting token request parameters

You need to submit parameters as a REST POST request using JSON. Below we list the range of parameters for the React Native mobile SDK token request.

React Native Mobile SDK Token Request Parameters

(Please take a look at the React Native Mobile SDK Token Request Example on the right side of the page.)

React Native Mobile SDK Token Request Example

error_reporting(E_ALL);
ini_set('display_errors', '1');

$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';

$arrData = array(
'command' => 'SDK_TOKEN',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'language' => 'en',
'device_id'=> 'ffffffff-a9fa-0b44-7b27-29e70033c587',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
);


$ch = curl_init( $url );
# Setup request to send json via POST.
$data = json_encode($arrData);
curl_setopt( $ch, CURLOPT_POSTFIELDS, $data );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
# Return response instead of printing.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
# Send request.
$result = curl_exec($ch);
curl_close($ch);
# Print response.
echo "<pre>$result</pre>";

curl -H "Content-Type: application/json" -d
'{"command":"SDK_TOKEN","language":"en","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj",,"language":"en","device_id":"ffffffff-a9fa-0b44-7b27-29e70033c587",
"signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a"}'
https://sbpaymentservices.payfort.com/FortAPI/paymentApi

import urllib
import urllib2
import json

url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command' => 'SDK_TOKEN',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'language' => 'en',
'device_id'=> 'ffffffff-a9fa-0b44-7b27-29e70033c587',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
};

values = json.dumps(arrData)
data = urllib.urlencode(values)
req = urllib2.Request(url, data)
response = urllib2.urlopen(req)
page = response.read()
print page + '\n\n'

String jsonRequestString = "{\"command\" : \"SDK_TOKEN\" , "
       +"\"access_code\" : \"zx0IPmPy5jp1vAz8Kpg7\", "
       +"\"merchant_identifier\" : \"CycHZxVj\", "
       + "\"language\" : \"en\","
       + "\"device_id\"\"ffffffff-a9fa-0b44-7b27-29e70033c587\", "
       + "\"signature\" : \"7cad05f0212ed933c9a5d5dffa31661acf2c827a\"}";

// Define and Initialize HttpClient
HttpClient httpClient = HttpClientBuilder.create().build();
// Intialize HttpPOST with FORT Payment services URL
HttpPost request = new HttpPost("https://sbpaymentservices.payfort.com/FortAPI/paymentApi");
// Setup Http POST entity with JSON String
StringEntity params = new StringEntity(jsonRequestString);
// Setup request type as JSON
request.addHeader("content-type", "application/json");
request.setEntity(params);
// Post request to FORT
HttpResponse response = httpClient.execute(request);
// Read response using StringBuilder
StringBuilder sb = new StringBuilder();
BufferedReader reader = new BufferedReader(new InputStreamReader(
   response.getEntity().getContent()), 65728);
String line = null;
while ((line = reader.readLine()) != null) {
 sb.append(line);
}
// Print response
System.out.println(sb.toString());

require 'json'
require 'net/http'
require 'net/https'
require 'uri'
require 'openssl'

arrData = {
'command' => 'SDK_TOKEN',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'language' => 'en',
'device_id'=> 'ffffffff-a9fa-0b44-7b27-29e70033c587',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
};

arrData = arrData.to_json
uri = URI.parse("https://sbpaymentservices.payfort.com/FortAPI/paymentApi")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new("/v1.1/auth")
request.add_field('Content-Type', 'application/json')
request.body = arrData
response = http.request(request)

When you send your request for an React Native mobile SDK token you must send the following parameters to Amazon Payment Services:

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

NOTE: device_id can be generated using the following command: RnAmazonPaymentServiceSdk.getDeviceID();

React Native Mobile SDK Token Response Parameters

These parameters will be returned in the Amazon Payment Services 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 Amazon Payment Services 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

Processing transactions with the React Native SDK

In this section we outline how you process a transaction using the React Native mobile SDK. Your first step is to create a mobile SDK token as described above.

Two routes for in-app payment processing

As a merchant you have two ways in which you can process payments using the Amazon Payment Services React Native mobile SDK.

Standard payment processing UI

You can use the standard Amazon Payment Services React Native SDK interface to display a standard payment UI screen. This option is customizable in two ways – you can hide the loading screen, and some of the UI elements can be customized.
Custom payment processing UI

Alternatively, you can choose to build your own payment processing UI by custom-coding an in-app payment processing feature. With this mobile SDK feature we allow Amazon Payment Services merchants to integrate and implement a native app checkout experience without displaying a default payment screen.

Using this integration method your customers can securely enter their payment card details on a fully customized merchant checkout landing page using the your customized payment UI.

The Amazon Payment Services React Native SDK provides key building blocks including payment card input fields and an action pay button that you can encapsulate inside the checkout landing page and to provide your own inline customer experience.

Amazon Payment Services’ SDK card input fields will securely transmit the completed payment card data to Amazon Payment Services APIs for processing and to complete the transaction placement.

React Native Mobile SDK Device ID Value

Please make sure to use the following React Native SDK function to generate the device_id parameter value that must be used for creating the sdk_token from your business security server:

  const setupDeviceId = async () => {
    const id: string = await getDeviceId();
    setDeviceId(id);
  };

React Native mobile SDK parameters

React Native Mobile SDK request and response parameters are listed below

Request parameters

This is a list of the parameters you need to send when you send a request to the React Native SDK.

ATTRIBUTES	Description
command Alpha Mandatory max: 20	Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences.
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 Amazon Payment Services 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: . ; / _ - , `'` @
billing_stateProvince Alphanumeric Optional max: 20	The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
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. Reference: ISO_3166-2 Example1: AM Example2: AT
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.
agreement_id Alphanumeric Optional max: 100	identifier for the agreement with the payer to process payments to be used in recurring payments ( Required for MADA )
recurring_mode Alphanumeric Optional max: 20	Indicates if the subsequent payments within the agreement has same/different amount or unscheduled (unknown interval/amount). ( Required for MADA ) Possible/ expected values: UNSCHEDULED, VARIABLE, FIXED
recurring_transactions_count Alphanumeric Optional max: 100	The number of merchant-initiated payments within the recurring payment agreement. ( Required for MADA and only if recurring_mode = VARIABLE or FIXED )

Response parameters

ATTRIBUTES	Description
command Alpha Max: 20	Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences.
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 Amazon Payment Services 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
billing_stateProvince Alphanumeric max: 20	The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
billing_provinceCode Alphanumeric 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. Reference: ISO_3166-2 Example1: AM Example2: AT
billing_street Alphanumeric 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 max: 100	The second line of the address (if provided).
billing_postcode Alphanumeric max: 10	The post code or zip code of the address.
billing_country Alphanumeric min:3, max: 3	The 3 letter ISO standard Alphanumeric country code of the address.
billing_company Alphanumeric max: 100	The name of the company associated with this address.
billing_city Alphanumeric max: 100	The city portion of the address.
shipping_stateProvince Alphanumeric max: 20	The state or province of the address.
shipping_provinceCode Alphanumeric 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 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 max: 100	The second line of the address (if provided).
shipping_source Alphanumeric	How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE
shipping_sameAsBilling Alphanumeric	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 max: 10	The post code or zip code of the address.
shipping_country Alphanumeric min:3, max: 3	The 3 letter ISO standard Alphanumeric country code of the address.
shipping_company Alphanumeric max: 100	The name of the company associated with this address.
shipping_city Alphanumeric max: 100	The city portion of the address.
agreement_id Alphanumeric max: 100	identifier for the agreement with the payer to process payments to be used in recurring payments

Standard checkout implementation

Follow below steps to implement standard checkout

1: Import from SDK

import {
  getDeviceId,
  FortRequestObject,
  StandardCheckout,
} from 'rn-amazon-payment-services';

2: Implement On Activity result function

export default function App() {

  const [deviceId, setDeviceId] = useState('');
  const [showStandardCheckout, setShowStandardCheckout] = useState(false);

  const setupDeviceId = async () => {
    const id: string = await getDeviceId();
    setDeviceId(id);
  };

  const onSuccess = (response: any) => {
    console.log('success', response);
    
  };

  const onFailure = (response: any) => {
    console.log('failure', response);
    
  };

  const onCancel = (response: any) => {
    console.log('cancel', response);

  };

3: Create Request Object Map

const requestObject: FortRequestObject = {
    command: 'PURCHASE',
    merchant_reference: 'ORD-0000007682',
    amount: '100',
    currency: 'AED',
    language: 'en',
    customer_email: 'sam@gmail.com',
    sdk_token: sdkToken,
    payment_option: 'VISA',
  };

4: Implement Standard Checkout

return(
    < StandardCheckout
        showStandardCheckoutPage={showStandardCheckout}
        environment={'TEST'}
        requestCode={123455}
        showLoading={true}
        showResponsePage={true}
        requestObject={requestObject}
        onSuccess={onSuccess}
        onFailure={onFailure}
        onCancel={onCancel}
    />
)

Standard Checkout Props

Below is a description for each parameter:

Parameter	Description
showStandardCheckoutPage Boolean Mandatory	Navigates to Amazon Payment Service Standard Checkout screen.
environment Alpha Mandatory	This parameter used to determine whether the request is going to be submitted to the test or production environment. It has two possible values: - TEST - PRODUCTION
requestCode Numeric Mandatory	A unique ID for this request.
showLoading Boolean Mandatory	Flag to show or hide the loading dialog.
showResponsePage Boolean Mandatory	Flag to show or hide the response page.
requestObject Object Mandatory	Parameters you need to send when you send a request (the full list of parameters is in the last section of the document)
onSuccess Boolean Mandatory	Callback to handle when the transaction is processed successfully.
onFailure Boolean Mandatory	Callback to handle when the transaction is failed.
onCancel Boolean Optional	Callback to handle when the user cancels the payment by clicking the back button.

Customized Payment Processing

You can customize the payment UI presented by our React Native SDK in a number of ways to better reflect your business.

1: Import custom checkout view

Define and initialize an instance of the FortCallBackManager in your activity as follows:

 import {
  CustomCheckoutView,
}

2: Create Call back function

You need to add the following statement to the onActivityResult function as follows:

export default function App() {

  const onSuccess = (response: any) => {
    console.log('success', response);
    
  };

  const onFailure = (response: any) => {
    console.log('failure', response);
    
  };

3: Create Request Object Map

const requestObject: FortRequestObject = {
    command: 'PURCHASE',
    merchant_reference: 'ORD-0000007682',
    amount: '100',
    currency: 'AED',
    language: 'en',
    customer_email: 'sam@gmail.com',
    sdk_token: sdkToken,
    payment_option: 'VISA',
  };

4: Custom Checkout UI Component

return(
    < CustomCheckoutView
      requestObject={requestObject}
      environment={'TEST'}
      style={{ width: 300, height: 400 }}
      payButtonProps={{
        marginLeft: 20,
        marginTop: 20,
        backgroundColor: '#026cff',
        text: 'Pay',
        textSize: 20,
        textColor: '#ffffff',
        buttonWidth: 40,
        buttonHeight: 40,
        borderRadius: 20,
        borderWidth: 1,
        borderColor: '#383333',
      }}
      onFailure={onFailure}
      onSuccess={onSuccess}
    />
  )

Custom Checkout Props

Below is a description for each parameter:

Parameter	Description
environment Alpha Mandatory	This parameter used to determine whether the request is going to be submitted to the test or production environment. It has two possible values: - TEST - PRODUCTION
style Object Mandatory	Set the height and width of the view.
payButtonProps Numeric Mandatory	Customization of the pay button
requestObject Object Mandatory	Parameters you need to send when you send a request
onSuccess Boolean Mandatory	Callback to handle when the transaction is processed successfully.
onFailure Boolean Mandatory	Callback to handle when the transaction is failed.

Using Direct Pay

The Direct Pay feature enables Amazon Payment Services merchants to securely process e-commerce transactions using tokenized payment card details.

The card token and provided card security code can be sent to the Amazon Payment Services React Native mobile SDK to complete the customer purchase through Direct Pay operation to complete the order placement using eCommerce channel.

1: Import Direct Pay button and FortRequest Objects

import {
  DirectPayButton,
  FortRequestObjectDirectPay,
} from 'rn-amazon-payment-services';

2: Create Call back function

You need to add the following statement to the onActivityResult function as follows:

export default function App() {

  const onSuccess = (response: any) => {
    console.log('success', response);
    
  };

  const onFailure = (response: any) => {
    console.log('failure', response);
    
  };

3: Create Request Object Map

const requestObjectDirectPay: FortRequestObjectDirectPay = {
    command: 'AUTHORIZATION',
    merchant_reference: 'ORD-0000007682',
    amount: '100',
    currency: 'AED',
    language: 'en',
    customer_email: 'sam@gmail.com',
    sdk_token: sdkToken,
    payment_option: 'VISA',
    token_name: tokenName,
    card_security_code: '123',
  };

4: Direct Pay Checkout UI Component

return(
      < DirectPayButton
        requestObject={requestObjectDirectPay}
        environment={'TEST'}
        style={{ width: 200, height: 100 }}
        payButtonProps={{
          marginLeft: 20,
          marginTop: 20,
          backgroundColor: '#026cff',
          text: 'Pay',
          textSize: 20,
          textColor: '#ffffff',
          buttonWidth: 40,
          buttonHeight: 40,
          borderRadius: 20,
          borderWidth: 1,
          borderColor: '#383333',
        }}
        onFailure={onFailure}
        onSuccess={onSuccess}
      />
    )

Direct Pay Checkout Props

Below is a description for each parameter:

Parameter	Description
environment Alpha Mandatory	This parameter used to determine whether the request is going to be submitted to the test or production environment. It has two possible values: - TEST - PRODUCTION
style Object Mandatory	Set the height and width of the view.
payButtonProps Numeric Mandatory	Customization of the pay button
requestObject Object Mandatory	Parameters you need to send when you send a request
onSuccess Boolean Mandatory	Callback to handle when the transaction is processed successfully.
onFailure Boolean Mandatory	Callback to handle when the transaction is failed.

Amazon Payment Services React Native SDK transaction feedback

Receiving transaction feedback

There are two ways in which you receive transaction feedback:

Direct transaction feedback. Amazon Payment Services sends an immediate payment processing response whenever a transaction is completed.

For example, if the transaction was pending due to the unavailability of any party to the transaction, the final update will be pushed to your notification feedback endpoint.

Registering Transaction Feedback URLs

To receive transaction feedback, you must register with Amazon Payment Services the transaction feedback URLs you set up on your server. Follow these steps:

Log in to your back-office account.
Select the active channel under Integration Settings > Technical Settings.
Enter your Direct Transaction Feedback URL and Notification Transaction Feedback URL.
Click “Save Changes” button.

Transaction Feedback Implementation

You can change and configure the retry mechanism attributes to increase or decrease the number of retries, time between retries and the grace period before we send the notifications.

[NOTE] The specifics of the data will differ based upon the financial operation that has been processed. Your code must be able to accommodate different data.

Appendix

Supported Platforms

The Amazon Payment Services React Native SDK supports devices running Android 4.1.x and later (API level 16). In other words, Android Ice Cream Sandwich or higher is supported. This release supports Android Pie API 28.

The Amazon Payment Services React Native SDK supports iOS 12.2+ and Xcode 11.0 and above.

Localization

You can use both English and Arabic when you implement the React Native SDK.

Screen Orientation

Currently, portrait is the only orientation supported within the Amazon Payment Services mobile SDK – unless you build a customized payment integration.

Supported Payment Methods

Using the React Native SDK the merchant can process debit or credit card transactions only.

Supported Payment Options

The supported credit card payment options are VISA, MASTERCARD, American Express (AMEX), MADA and MEEZA.

Flutter Mobile SDK

Before you start the integration

Read through the following steps first to understand how the integration process works. This will help you to understand why these steps are required and why you need to follow a specific sequence.

Step 1: Access your test account

You need to make sure that you have access to a test account with Amazon Payment Services. It is a full test environment that allows you to fully simulate transactions.

Step 2: Make sure that you are using the correct integration type

Step 3: Install the Amazon Payment Services Flutter SDK in your development environment

You need to add the dependencies and have to set the PodFile version

Step 4: Create a test transaction request

Step 5: Process a transaction response

After every payment, Amazon Payment Services returns the transaction response on the URL configured in your account under Technical Settings, Channel Configuration.

Step 6: Test and Go Live

Mobile SDK transaction workflow

Below, we describe the transaction workflow when you process a payment using the Amazon Payment Service Flutter Mobile SDK.

Your customer clicks on the Pay button in your app.
Your merchant system (back-end) generates a mobile SDK token using the Amazon Payment Services API
Your app passes the parameters, including the SDK token, to the Flutter mobile SDK
The Flutter mobile SDK starts a secure connection and sends the transaction request to the Amazon Payment Services server to be validated.
The Amazon Payment Services API validates the SDK token, device_ID and other request parameters and returns the validation response to the Flutter SDK.
Assuming validation is passed your merchant app displays a payment page to the customer.
Your customer enters their payment details on the payment page in the Flutter SDK prompt on their device.
The Amazon Payment Services Flutter SDK validates your customer’s details and sends a transaction (Authorization or Purchase) request to the relevant payment processor and issuing bank.
The payment processor processes the transaction request and returns a transaction response to the Flutter SDK
The Amazon Payment Services Flutter SDK returns the transaction response to your merchant app
Your merchant app displays the response to your customer

transaction workflow

Installing the Flutter Mobile SDK

You need to complete below steps to install the Amazon Payment Services Flutter SDK.

Step 1

You need to add the dependencies to your package’s pubspec.yaml file: flutter_amazonpaymentservices

Step 2

You need to import the plugin

import 'package:flutter_amazonpaymentservices/environment_type.dart';
import 'package:flutter_amazonpaymentservices/flutter_amazonpaymentservices.dart';

Android Specific Installations

No additional work required

iOS Specific Installations

The SDK build for >= iOS 10.0, so you need to set the platform version in the Podfile to iOS 10 or above.

Creating SDK token

SDK authentication token is required to authenticate every request sent to the SDK. The token is also significant to process payment operations with Amazon Payment Services through our Flutter SDK.

To get started with our Flutter SDK you must first establish the ability to generate a SDK token.

NOTE: The creation and initiation of a SDK token happens on your server – your server must generate the token by sending a request to the Amazon Payment Services API.

A unique authentication token must be created for each transaction. Each authentication token has a life-time of only one hour if no new request from the same device is sent.

SDK token URLs

These are the URLs you need to use when you request a SDK token for your Flutter app:

Test Environment URL

https://sbpaymentservices.payfort.com/FortAPI/paymentApi

Production Environment URL

https://paymentservices.payfort.com/FortAPI/paymentApi

Submitting token request parameters

You need to submit parameters as a REST POST request using JSON. Below we list the range of parameters for the Flutter SDK token request.

Flutter SDK Token Request Parameters

(Please take a look at the Flutter SDK Token Request Example on the right side of the page.)

Flutter SDK Token Request Example

error_reporting(E_ALL);
ini_set('display_errors', '1');

$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';

$arrData = array(
'command' => 'SDK_TOKEN',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'language' => 'en',
'device_id'=> 'ffffffff-a9fa-0b44-7b27-29e70033c587',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
);


$ch = curl_init( $url );
# Setup request to send json via POST.
$data = json_encode($arrData);
curl_setopt( $ch, CURLOPT_POSTFIELDS, $data );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
# Return response instead of printing.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
# Send request.
$result = curl_exec($ch);
curl_close($ch);
# Print response.
echo "<pre>$result</pre>";

curl -H "Content-Type: application/json" -d
'{"command":"SDK_TOKEN","language":"en","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj",,"language":"en","device_id":"ffffffff-a9fa-0b44-7b27-29e70033c587",
"signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a"}'
https://sbpaymentservices.payfort.com/FortAPI/paymentApi

import urllib
import urllib2
import json

url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command' => 'SDK_TOKEN',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'language' => 'en',
'device_id'=> 'ffffffff-a9fa-0b44-7b27-29e70033c587',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
};

values = json.dumps(arrData)
data = urllib.urlencode(values)
req = urllib2.Request(url, data)
response = urllib2.urlopen(req)
page = response.read()
print page + '\n\n'

String jsonRequestString = "{\"command\" : \"SDK_TOKEN\" , "
       +"\"access_code\" : \"zx0IPmPy5jp1vAz8Kpg7\", "
       +"\"merchant_identifier\" : \"CycHZxVj\", "
       + "\"language\" : \"en\","
       + "\"device_id\"\"ffffffff-a9fa-0b44-7b27-29e70033c587\", "
       + "\"signature\" : \"7cad05f0212ed933c9a5d5dffa31661acf2c827a\"}";

// Define and Initialize HttpClient
HttpClient httpClient = HttpClientBuilder.create().build();
// Intialize HttpPOST with FORT Payment services URL
HttpPost request = new HttpPost("https://sbpaymentservices.payfort.com/FortAPI/paymentApi");
// Setup Http POST entity with JSON String
StringEntity params = new StringEntity(jsonRequestString);
// Setup request type as JSON
request.addHeader("content-type", "application/json");
request.setEntity(params);
// Post request to FORT
HttpResponse response = httpClient.execute(request);
// Read response using StringBuilder
StringBuilder sb = new StringBuilder();
BufferedReader reader = new BufferedReader(new InputStreamReader(
   response.getEntity().getContent()), 65728);
String line = null;
while ((line = reader.readLine()) != null) {
 sb.append(line);
}
// Print response
System.out.println(sb.toString());

require 'json'
require 'net/http'
require 'net/https'
require 'uri'
require 'openssl'

arrData = {
'command' => 'SDK_TOKEN',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'language' => 'en',
'device_id'=> 'ffffffff-a9fa-0b44-7b27-29e70033c587',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
};

arrData = arrData.to_json
uri = URI.parse("https://sbpaymentservices.payfort.com/FortAPI/paymentApi")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new("/v1.1/auth")
request.add_field('Content-Type', 'application/json')
request.body = arrData
response = http.request(request)

When you send your request for an Flutter SDK token you must send the following parameters to Amazon Payment Services:

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

NOTE: device_id can be generated using the following command: await FlutterAmazonpaymentservices.getUDID;

Flutter Mobile SDK Token Response Parameters

These parameters will be returned in the Amazon Payment Services 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 Amazon Payment Services 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

Processing transactions with the Flutter SDK

In this section we outline how you process a transaction using the Flutter SDK. Your first step is to create a SDK token as described above.

In-app payment processing

As a merchant you can process payments using the Amazon Payment Services Flutter SDK.

Standard payment processing UI

You can use the standard Amazon Payment Services Flutter SDK interface to display a standard payment UI screen. This option is customizable in two ways – you can hide the loading screen, and some of the UI elements can be customized.

Flutter SDK Device ID Value

Please make sure to use the following Flutter SDK function to generate the device_id parameter value that must be used for creating the sdk_token from your business security server:

  var deviceId = await FlutterAmazonpaymentservices.getUDID ;

Flutter SDK parameters

Flutter SDK request and response parameters are listed below

Request parameters

This is a list of the parameters you need to send when you send a request to the Flutter SDK.

ATTRIBUTES	Description
command Alpha Mandatory max: 20	Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences.
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 Amazon Payment Services 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: . ; / _ - , `'` @
billing_stateProvince Alphanumeric Optional max: 20	The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
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. Reference: ISO_3166-2 Example1: AM Example2: AT
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.
agreement_id Alphanumeric Optional max: 100	identifier for the agreement with the payer to process payments to be used in recurring payments ( Required for MADA )
recurring_mode Alphanumeric Optional max: 20	Indicates if the subsequent payments within the agreement has same/different amount or unscheduled (unknown interval/amount). ( Required for MADA ) Possible/ expected values: UNSCHEDULED, VARIABLE, FIXED
recurring_transactions_count Alphanumeric Optional max: 100	The number of merchant-initiated payments within the recurring payment agreement. ( Required for MADA and only if recurring_mode = VARIABLE or FIXED )

Response parameters

ATTRIBUTES	Description
command Alpha Max: 20	Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences.
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 Amazon Payment Services 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
billing_stateProvince Alphanumeric max: 20	The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
billing_provinceCode Alphanumeric 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. Reference: ISO_3166-2 Example1: AM Example2: AT
billing_street Alphanumeric 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 max: 100	The second line of the address (if provided).
billing_postcode Alphanumeric max: 10	The post code or zip code of the address.
billing_country Alphanumeric min:3, max: 3	The 3 letter ISO standard Alphanumeric country code of the address.
billing_company Alphanumeric max: 100	The name of the company associated with this address.
billing_city Alphanumeric max: 100	The city portion of the address.
shipping_stateProvince Alphanumeric max: 20	The state or province of the address.
shipping_provinceCode Alphanumeric 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 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 max: 100	The second line of the address (if provided).
shipping_source Alphanumeric	How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE
shipping_sameAsBilling Alphanumeric	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 max: 10	The post code or zip code of the address.
shipping_country Alphanumeric min:3, max: 3	The 3 letter ISO standard Alphanumeric country code of the address.
shipping_company Alphanumeric max: 100	The name of the company associated with this address.
shipping_city Alphanumeric max: 100	The city portion of the address.
agreement_id Alphanumeric max: 100	identifier for the agreement with the payer to process payments to be used in recurring payments

Standard checkout implementation

Follow below to implement standard checkout

var requestParam = {
"amount": 100,
"command": "AUTHORIZATION",
"currency": "USD",
"customer_email": "test@gmail.com",
"language": "en",
"merchant_reference": "f74689b50cb54fcab4664b4331163d5e", 
"sdk_token": "f74689b50cb54fcab4664b4331163d5e"
}; try {
result = await FlutterAmazonpaymentservices.normalPay( requestParam, EnvironmentType.production, isShowResponsePage: true);
} on PlatformException catch (e) {
print("Error ${e.message} details:${e.details}"); return;
}
print("Success ${ result}");

Standard Checkout Props

Below is a description for each parameter:

Parameter	Description
environment Alpha Mandatory	This parameter used to determine whether the request is going to be submitted to the test or production environment. It has two possible values: - SANDBOX - PRODUCTION
showResponsePage Boolean Mandatory	Flag to show or hide the response page.

Validate API

This is an API to check request validation is successfull or unsuccessful by passing the following params:

 Future < void> validateApi() async { var result;
 var requestParam = {
 "amount": 100,
 "command": "AUTHORIZATION",
 "currency": "USD",
 "customer_email": "test@gmail.com",
 "language": "en",
 "merchant_reference": "f74689b50cb54fcab4664b4331163d5e", "sdk_token": "f74689b50cb54fcab4664b4331163d5e"
 };
 try {
 result = await FlutterAmazonpaymentservices.validateApi(
      requestParam,
 EnvironmentType.production, );
 } on PlatformException catch (e) {
 print("Error ${e.message} details:${e.details}"); return;
 }
 print("Success ${result}"); }

NOTE: There are two values for EnvironmentType Sandbox and Production

Amazon Payment Services Flutter SDK transaction feedback

Receiving transaction feedback

There are two ways in which you receive transaction feedback:

Direct transaction feedback. Amazon Payment Services sends an immediate payment processing response whenever a transaction is completed.

Notification feedback. Where we need to provide you with the status of a transaction once it is received. In other words, we send notification feedback to alert you to any changes in the status of a transaction.

For example, if the transaction was pending due to the unavailability of any party to the transaction, the final update will be pushed to your notification feedback endpoint.

Registering Transaction Feedback URLs

To receive transaction feedback, you must register with Amazon Payment Services the transaction feedback URLs you set up on your server. Follow these steps:

Log in to your back-office account.
Select the active channel under Integration Settings > Technical Settings.
Enter your Direct Transaction Feedback URL and Notification Transaction Feedback URL.
Click “Save Changes” button.

Transaction Feedback Implementation

You can change and configure the retry mechanism attributes to increase or decrease the number of retries, time between retries and the grace period before we send the notifications.

[NOTE] The specifics of the data will differ based upon the financial operation that has been processed. Your code must be able to accommodate different data.

Appendix

Supported Platforms

The Amazon Payment Services Flutter SDK supports devices running Android 4.1.x and later (API level 16). In other words, Android Ice Cream Sandwich or higher is supported. This release supports Android Pie API 28.

The Amazon Payment Services Flutter SDK supports iOS 12.2+ and Xcode 11.0 and above.

Localization

You can use both English and Arabic when you implement the Flutter SDK.

Screen Orientation

Currently, portrait is the only orientation supported within the Amazon Payment Services mobile SDK – unless you build a customized payment integration.

Supported Payment Methods

Using the Flutter SDK the merchant can process debit or credit card transactions only.

Supported Payment Options

The supported credit card payment options are VISA, MASTERCARD, American Express (AMEX), MADA and MEEZA.

Apple Pay Service

Amazon Payment Services fully supports Apple Pay. You can offer your customers a seamless payment process via their Apple mobile device. Supported payment networks include American Express, Mastercard, and Visa as well as local payment methods such as mada.

Merchants that use Amazon Payment Services can offer payments via Apple Pay in iOS applications as long as the user uses iOS 8.1 and above.

Apple Pay Service URLs

Test Environment URL:

https://sbpaymentservices.payfort.com/FortAPI/paymentApi

Production Environment URL:

https://paymentservices.payfort.com/FortAPI/paymentApi

Get Started With Apple Pay

Before you start the 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 you received from Apple in your Amazon Payment Services account under “Apple Pay Settings” tab.
After completing the integration with Apple Pay proceed with Amazon Payment Services 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 Amazon Payment Services:

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. Please refer to this section to know more about the differences.
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: 93eec76cbedaedca44648e3d5c314766906e4e78ce33cd3b8 396f105a1c0daed
apple_ephemeralPublicKey Alphanumeric Mandatory max: 200	Ephemeral public key bytes. Example: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEM9JqF04vD lGI…
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: 5173d4e05f2e07dc4e7ea9669bda185712ffffe1d6 cfce2d4e854d7661e70d67…
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 Mandatory 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 Amazon Payment Services’ 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. Please refer to this section to know more about the differences.
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 your customers to make payments using different Apple devices via the Amazon Payment Services iOS SDK. Your customer authenticates their identity using Touch ID 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 an iOS device 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 Amazon Payment Services iOS Mobile SDK, click here.

Get Started

Before you start Apple Pay integration 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 the mobile SDK:

Objective C:

#pragma mark - PKPaymentAuthorizationViewControllerDelegate

(void)paymentAuthorizationViewController:
(PKPaymentAuthorizationViewController *)controller
didAuthorizePayment:(PKPayment *)payment
completion:(void (^)(PKPaymentAuthorizationStatus status))completion
{
BOOL asyncSuccessful = payment.token.paymentData.length != 0;

if(asyncSuccessful) {

PayFortController *payFort = [[PayFortController alloc]initWithEnviroment:(KPayFortEnviroment)_enviromentSegment.selectedSegmentIndex];

NSMutableDictionary *request = [[NSMutableDictionary alloc]init];
[request setValue:@“10000” forKey:@“amount”];
[request setValue:@“AUTHORIZATION” forKey:@“command”];
[request setValue:@“USD” forKey:@“currency”];
[request setValue:@“email@domain.com” forKey:@“customer_email”];
[request setValue:@“en” forKey:@“language”];
[request setValue:@“merchant” forKey:@“merchant_reference”];
[request setValue:@“” forKey:@“sdk_token”];
[request setValue:@“APPLE_PAY” forKey:@“digital_wallet”];

[payFort callPayFortForApplePayWithRequest:request
applePayPayment:payment
currentViewController:self
Success:^(NSDictionary *requestDic, NSDictionary *responeDic) {
completion(PKPaymentAuthorizationStatusSuccess);

}
Faild:^(NSDictionary *requestDic, NSDictionary *responeDic, NSString *message) {
completion(PKPaymentAuthorizationStatusFailure);

}];
} else {
completion(PKPaymentAuthorizationStatusFailure);
}
}

Swift:

func paymentAuthorizationController(_ controller: PKPaymentAuthorizationController,
didAuthorizePayment payment: PKPayment, completion: @escaping (PKPaymentAuthorizationStatus) -> Void) {

//Perform some very basic validation on the provided contact information
let asyncSuccessful = payment.token.paymentData.count != 0

if asyncSuccessful {
let payFort = PayFortController.init(enviroment: KPayFortEnviromentSandBox)
let request = NSMutableDictionary.init()
request.setValue(“100100000”, forKey: “amount”)
request.setValue(“AUTHORIZATION”, forKey: “command”)
request.setValue(“USD”, forKey: “currency”)
request.setValue(“email@domain.com”, forKey: “customer_email”)
request.setValue(“en”, forKey: “language”)
request.setValue(“merchant”, forKey: “merchant_reference”)
request.setValue(“gr66zzwW9” , forKey: “sdk_token”)
request.setValue(“APPLE_PAY” , forKey: “digital_wallet”)

payFort?.callPayFortForApplePay(withRequest: request,
applePay: payment,
currentViewController: self
, success: { (requestDic, responeDic) in
completion(.success)
}, faild:{ (requestDic, responeDic, message) in
completion(.failure)
})
}else {
completion(.failure)
}
}

Apple Pay SDK Authorization/ Purchase - Request

Include the following parameters in the request you will send to Amazon Payment Services:

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. Please refer to this section to know more about the differences.
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 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 Mandatory 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 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: . ; / _ - , `'` @

Request Sample { "digital_wallet":"APPLE_PAY", "command":"AUTHORIZATION", "access_code":"E8OHT1raKV9pdPBMishi", "merchant_identifier":"XMWzLQPu", "merchant_reference":"merchantTest-100118", "amount":"100", "currency":"SAR", "language":"en", "customer_email":"test@merchantdomain.com", "apple_data":"abcdefgh1234567KEuM/lC6IW7KGO7ydRs95KmLyQC58K4griC/mnAtAYXM/abcdefgh12345678xnEVGMroqTQj/==", "apple_signature":"abcdefgh12345678AACggDCCA+abcdefgh12345678IVd+abcdefgh12345678B+g+abcdefgh12345678AO8T9hfo/NooRtvK+Sd48AiEAyAGWQH4jbioivj7Y/abcdefgh12345678AA==", "apple_header":{ "apple_transactionId":"abcdefgh12345678", "apple_ephemeralPublicKey":"abcdefgh123456784t3guu+mX+abcdefgh12345678/J4kDgFLnwQ==", "apple_publicKeyHash":"AAbbCC+abcdefgh12345678Pbo==" }, "apple_paymentMethod":{ "apple_displayName":"Visa 000", "apple_network":"Visa", "apple_type":"debit" }, "signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a" }

Apple Pay SDK Authorization/ Purchase - Response

The following parameters will be returned in Amazon Payment Services’ 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. Please refer to this section to know more about the differences.
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 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 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

Was this helpful? Yes No

Recurring Transactions

You can effortlessly configure secure, recurring payments for any defined billing cycle – whether daily, weekly, monthly, or annual. You do so through a workflow that is not much different from the normal checkout process. Simply charge to your customer’s card a specific amount on regular basis using the Purchase operation configured in single message mode.

Recurring transactions can be integrated in two ways:

1- Manually from FORT backoffice through subscription service.
2- Using APIs through Recurring integration.

Subscription Service

The subscription service allows a Merchant to create recurring payments for a customer for a specific period of time called billing cycle “ with weekly or monthly” biases. The Merchant can integrate this service through Amazon Payment Services back-office only without any development effort needed.

Before starting :

Before you start integrating this service you need to be aware of the following:
1-You should have a recurring MID issued from your acquiring bank
2- You need to collect the card information from the customer through a manual order from the back-office before processing a recurring, request.
3-You should have a MOTO MID issued from your acquiring bank, this process will be liaised with the business development and underwriting teams to get the bank approvals.

Subscription Integration from backoffice:

The subscription service management can be done from the your back-office after activating this service.

You need to follow these steps in order to create the subscriptions :

Go to Subscription Management tab to start creating the subscription/ The two options which you can start using are :

1-New Customer Subscription.
2-Existing Customer Subscription.

New Customer Subscription

Under this tab , you can create a new customer subscription by collecting the card details through the manual order. Under this tab you should get the clear card information such as, “card number , expiry date” from the customer in addition to more details such as :

ATTRIBUTES	Description
command Alpha Mandatory	command. Possible/ expected values: PURCHASE or AUTHORIZATION
merchant_reference Alphanumeric Mandatory	The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ .
amount Numeric Mandatory	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	The currency of the transaction’s amount in ISO code 3. Example: AED
language Alpha Mandatory	The checkout page and messages language. Possible/ expected values: en / ar
customer_email Alphanumeric Mandatory	The customer’s email. Example: customer@domain.com Special characters: _ - . @ +
customer_name Alphanumeric Optional	The customer’s name. Example : John Smith
order_description Alphanumeric Mandatory	A description of the order. Example : iPhone 12 Pro Special Characters: # ’/ ._- :$ space indicator.
card_number Numeric Mandatory	The clear credit card’s number. Example: 4005550000000001
expiry_date Numeric Mandatory	The card’s expiry date. Example: 2505.

After you complete this step you will get a page that contains the response of the manual order you should save the Token Name returned in. If the payment is processed successfully, you can start create the subscription by clicking the Create Subscription button displayed or you can choose the Existing Customer Subscription option under Subscription Management tab.

Existing Customer Subscription

Under this tab ,you can start creating the subscription for the customer using the Token Name. The fields required to create a particular subscription for the customers are:

ATTRIBUTES	Description
token_name Alphanumeric Mandatory	The Token received from the first payment “through the manual order or any other channel the merchant integrated for the first payment Example: Op9Vmp Special characters: . @ - _
Subscription ID Numeric Mandatory	It refers to the subscription reference , this ID will be used to identify the subscription for each customer and the merchant can search for any subscription from the subscription reports using it
merchant_reference Alphanumeric Mandatory	The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ .
amount Numeric Mandatory	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	The currency of the transaction’s amount in ISO code 3. Example: AED
customer_email Alphanumeric Mandatory	The customer’s email. Example: customer@domain.com Special characters: _ - . @ +
customer_name Alphanumeric Optional	The customer’s name. Example : John Smith
Billing Cycle Numeric Mandatory	It refers to the duration ( Months / Weeks ) when the Merchant needs to deduct the amount from the customer one time. For example if the Merchant set this field as 5 Monthly , we will deduct the amount from the customer one time for each 5 months.
Number Of Billing Cycle Numeric Optional	Number of times the customer will be charged the subscription amount. Example: if the merchant chooses the number of cycles as 2 and the billing cycle is one per month , we will deduct the amount 2 times only ( for two months ). A customer will be charged infinite number of times if this field is empty.
Next Execution Date Numeric Mandatory	The Merchant should set the date on which he needs to deduct the next subscription amount from the customer. This date will be updated automatically after each subscription cycle.

After you create the subscription for the customer , it will be listed under the Subscription Management tab in the account , if you click on any subscription through the subscription ID , you can modify the subscription details for the customer like "Billing Cycle , Number of billing cycle , Customer Name , Customer Email , Currency , Next Execution Date”. If you wish to stop the subscription , you should choose “Suspend” after choosing the subscriptionID that you want to stop, we will stop the recurring payment for this subscription.
You can view the recurring payments which have been processed for all the subscriptions from Subscription Report .

Recurring Integration

Merchant can integrate recurring service through APIs in order to charge customers offline using permenant tokens.

Recurring 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.

Recurring - Request

Include the following parameters in the request you will send to Amazon Payment Services:

ATTRIBUTES	Description
command Alpha Mandatory max: 20	command. Possible/ expected values: PURCHASE
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: _ - . @ +
eci Alpha Mandatory max: 16	Ecommerce indicator. Possible/ expected values: RECURRING
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 for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
payment_option Alpha Optional Max: 10	Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX
order_description Alphanumeric Optional max: 150	It holds the description of the order. Example: iPhone 6-S Special characters: `'` / . _ - # : $ Space
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
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: - _ .
agreement_id Alphanumeric Optional max: 100	identifier for the agreement with the payer to process payments to be used in recurring payments ( Required for MADA )

Sample Recurring Purchase Request :

Redirection / Merchant Page integration :

Trusted integration :

MADA RECURRING :

Recurring - Response

The following parameters will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
command Alpha max: 20	command. Possible/ expected values: PURCHASE
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: 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: customer@domain.com
eci Alpha max: 16	Ecommerce indicator. Possible/ expected values: RECURRING
token_name Alphanumeric max: 100	The Token received from the Tokenization process. Example: Op9Vmp
signature Alphanumeric max: 200	A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). 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
order_description Alphanumeric max: 150	It holds the description of the order. Example: iPhone 6-S
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: 16	The clear credit card’s number. Example: 400555******0001
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
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

Was this helpful? Yes No

Installments

Your customers can enjoy installment payments thanks to a partnership between Amazon Payment Services and several issuing banks and credit card providers.

Note that installments are charged to your customer’s credit card. As the merchant you are always paid the full transaction amount immediately – it is the responsibility of the customer’s bank to collect the installments that are due from your customer’s credit card.

You have two options for installments on redirection:
1. Standalone
2. Easy redirection installments

Easy Installments Redirection

This option does not required adding additional parameters into the Redirection request
The installment option will be displayed inside the redirection payment form if the customer’s card and the amount is eligible for installments.
Upon selection the installment option ,the banks and the plans which offered will persist.

Standalone Installments Redirection Service

Standalone installments require adding additional parameter to the redirection request, where the customer will be Re-directed to a standalone installments page.

Standalone Installments Redirection Service - Request

Include the following parameters in the Purchase - Request Parameters you will send to Amazon Payment Services:

ATTRIBUTES	Description
installments Alpha Optional max: 10	Used to specify the type of the Installments service. Possible/ expected values: STANDALONE

Standalone Installments Redirection Service - Response

The following parameters will be returned in Amazon Payment Services’ response in addition to the Purchase - Response Parameters:

ATTRIBUTES	Description
installments Alpha max: 10	Used to specify the type of the Installments service. Possible/ expected values: STANDALONE
number_of_installments Numeric max: 2	The number of installments the customer has selected in the payment page. Example: 3

Installments Redirection Service - Sample Request:

Installments and Standard Merchant Page Integration (Iframe)

Installments and Standard Merchant Page Integration Service - Request

Include the following parameters in the Request Parameters you will send to Amazon Payment Services:

ATTRIBUTES	Description
installments Alpha Mandatory max: 10	Used to specify the type of the Installments service. Possible/ expected values: STANDALONE
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: USD
customer_country_code Alpha Optional Max: 3	The Customer’s country code. ISO 3 digit country code. Example: JOR

Installments and Standard Merchant Page Integration - Response

The following parameters will be returned in Amazon Payment Services’ response in addition to the Merchant Page - Response Parameters:

ATTRIBUTES	Description
installments Alpha max: 10	Used to specify the type of the Installments service. Possible/ expected values: STANDALONE
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
customer_country_code Alpha Max: 3	The Customer’s country code. ISO 3-digit country code. Example: JOR
number_of_installments Numeric Max: 2	The number of installments the customer has selected in payment page. Example: 3
plan_code Alphanumeric Max: 8	A code that refers to the “installments plan” the customer selected from the merchant page. Example: NNNN89JJ
issuer_code Alphanumeric Max: 8	A code that refers to the “card issuer” the customer selected from the merchant page. Example: 12HP34SE

Installments and Standard Merchant Page Integration Service - Sample Request

Installments Purchase Service - Request

Include the following parameters in the Operation - Request Parameters you will send to Amazon Payment Services:

ATTRIBUTES	Description
installments Alpha Mandatory max: 10	Used to specify the type of the Installments service. Possible/ expected values: YES
plan_code Alphanumeric Mandatory Max: 8	A code that refers to the “installments plan” the customer selected from the merchant page. Example: NNNN89JJ
issuer_code Alphanumeric Mandatory Max: 8	A code that refers to the “card issuer” the customer selected from the merchant page. Example: 12HP34SE

Installments Purchase Service - Response

The following parameters will be returned in Amazon Payment Services’ response in addition to the Operation - Response Parameters:

ATTRIBUTES	Description
installments Alpha max: 10	Used to specify the type of the Installments service. Possible/ expected values: YES
plan_code Alphanumeric Max: 8	A code that refers to the “installments plan” the customer selected from the merchant page. Example: NNNN89JJ
issuer_code Alphanumeric Max: 8	A code that refers to the “card issuer” the customer selected from the merchant page. Example: 12HP34SE
number_of_installments Numeric Max: 2	The number of installments the customer has selected in payment page. Example: 3

Installments Purchase Service - Sample Request

Installments Hosted Checkout

Get Installments Plans API

This service allows you to know the installment plan details and issuers configured in your account for the installment service.

Get Installments Plans 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.

Get Installments Plans API - Request

Include the following parameters in the request you will send to Amazon Payment Services:

ATTRIBUTES	Description
query_command Alpha Mandatory max: 50	Query operations command. Possible/ expected values: GET_INSTALLMENTS_PLANS 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
signature Alphanumeric Mandatory max: 200	A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
amount Numeric Optional 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 Optional max: 3	The currency of the transaction’s amount in ISO code 3. Example: USD
language Alpha Optional max: 2	The checkout page and messages language. Possible/ expected values: en / ar
issuer_code Alphanumeric Optional max: 8	A code that refers to the “card issuer” the customer selected from the merchant page. Example: 12HP34SE

Get Installments Plans API - Response

The following parameters will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
query_command Alpha max: 50	Query operations command. Possible/ expected values: GET_INSTALLMENTS_PLANS
access_code Alphanumeric max: 20	Access code. Example: zx0IPmPy5jp1vAz
merchant_identifier Alphanumeric max: 20	The ID of the Merchant. Example: CycHZxVj
signature Alphanumeric max: 200	A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
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
issuer_code Alphanumeric max: 8	A code that refers to the “card issuer” the customer selected from the merchant page. Example: 12HP34SE
response_message Alphanumeric max: 150	Message description of the response code. It returns according to the request language. Example: Insufficient Funds
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).
installment_detail List max: -	This parameter is a parent parameter for other parameters that contain the details of installment. Possible/ expected values: (Please refer to the below section issuer_detal).

issuer_detail This parameter is a sub parameter of the “installment_detail” parameter, the table below shows the children parameters of the “issuer_detail”:

ATTRIBUTES	Description
issuer_code Alphanumeric max: 8	A code that refers to the “card issuer” the customer selected from the merchant page. Example: 12HP34SE
issuer_name_ar Alphanumeric max: 50	The issuer name in Arabic. Example: Issuer2عربي
issuer_name_en Alphanumeric max: 50	The issuer name in English. Example: Issuer2
terms_and_condition_ar Alphanumeric max: 200	The Arabic terms and condition URL. Example: https://www.gmail.com
terms_and_condition_en Alphanumeric max: 200	The English terms and condition URL. Example: https://www.yahoo.com
country_code Alpha max: 3	The country’s code in ISO 3-digits. Example: JOR
issuer_logo_ar Alphanumeric max: 350	The issuer logo for the Arabic version. Example: https://payfort-fort-images-lt.s3.amazonaws.com/frontend/files/logos/issuer/logo_en_164.jpg
issuer_logo_en Alphanumeric max: 350	The issuer logo for the English version. Example: https://payfort-fort-images-lt.s3.amazonaws.com/frontend/files/logos/issuer/logo_en_164.jpg
banking_system Alpha max: 11	The type of institutions that provide financial services. Possible/ expected values: -Non Islamic -Islamic
formula Alphanumeric max: 100	The equation of calculating the installment value. Example: (amount +(amount *effective rate/100))/period Please check the note below the table for more details.
plan_details List max: -	This parameter contain all the plans for this issuer. Possible/ expected values: (Please refer to next plan_detail section).
bins List max: -	List of 6 digits of the card number related to this issuer. Possible/ expected values: (Please refer to next bins section).
confirmation_message_ar Alphanumeric max: 500	This parameter shows to the customer the confirmation message in Arabic.
disclaimer_message_ar Alphanumeric max: 500	This parameter shows to the customer the disclaimer message in Arabic.
processing_fees_message_ar Alphanumeric max: 500	This parameter shows to the customer the processing fee message in Arabic.
confirmation_message_en Alphanumeric max: 500	This parameter shows the customer to the confirmation message in English.
disclaimer_message_en Alphanumeric max: 500	This parameter shows to the customer the disclaimer message in English.
processing_fees_message_en Alphanumeric max: 500	This parameter shows to the customer the processing fee message in English.

plan_detail Parameter This parameter is a sub parameter of the “issuer_detail” parameter, the table below shows the children parameters of the “plan_detail”:

ATTRIBUTES	Description
plan_code Alphanumeric max: 8	A code that refers to the “installments plan”. Example: NNNN89JJ
currency_code Alpha max: 3	The currency of the transaction’s amount in ISO code 3. Example: USD
number_of_installment Numeric max: 2	The number of installments. Example: 3
fees_type Alpha max: 10	The type of the fee. Possible/ expected values: -Fixed -Percentage *Please refer to the below formulas section to know the difference.
fees_amount Numeric max: 10	The amount of the fee. Example: 11
processing_fees_type Alpha max: 10	The type of the processing fee. Possible/ expected values: -Fixed -Percentage *Please refer to the below formulas section to know the difference.
processing_fees_amount Numeric max: 10	The amount of the processing fee. Example: 11
rate_type Alpha max: 15	The type of the rate. Possible/ expected values: -Reducing Balance -Flat
plan_merchant_type Alpha max: 11	The type of agreement between the plan and Merchant. Possible/ expected values: -Partner -Non Partner
plan_type Alpha max: 12	The type of the installments plan. Possible/ expected values: -Local -Cross-Border
fee_display_value Numeric max:	The display value that represent the fees amount. Example: 11.0
minimum_amount Numeric max: 10	The minimum range of the accepted amount for this plan. Example: 11
maximum_amount Numeric max: 10	The maximum range of the accepted amount for this plan. Example: 110000000
amountPerMonth Numeric max: 10	The payable amount per month. Example: 3.00

bins This parameter is a sub parameter of the “issuer_detail” parameter, the table below shows the children parameters of the “bins”:

ATTRIBUTES	Description
bin Numeric max: 6	The first 6 digits of the card number. Example: 478773
currency_code Alpha max: 3	The currency of the transaction’s amount in ISO code 3. Example: JOR
card_brand_code Alpha max: 16	The type of the credit card. Possible/ expected values: -VISA -Master Card -American Express

Get Installments Plans API formulas The monthly installments amount that are displayed on Amazon Payment Services payment pages are calculated based on the below formulas:

• Percentage Fees: Installments interest rate in percent (%) charged to the customer by the bank.

• Fixed Fees: Installments fees in fixed amount charged to the customer by the bank.

Get Installments Plans API - Request Sample

Get Installments Plans API - Response Sample The following is sample of a response of an Get Installments Plans API request:

{
“response_code”: “62000”,
“response_message”: “Success”,
“signature”: “9b02960d319318256efbc17cf57dbc1f7e7fd046e20e49215d0bed32a065c3ae”,
“merchant_identifier”: “bxgOIxIz”,
“access_code”: “Ru8n1ciSJXWm8WFHLKsR”,
“query_command”: “GET_INSTALLMENTS_PLANS”,
“issuer_code”: “fHkigRtu”,
“installment_detail”: {
    “issuer_detail”: [
    {
         “issuer_code”: “fHkigRtu”,
        “issuer_name_ar”: “بنك الامارات دبي الوطني”,
        “issuer_name_en”: “Emirates NBD Egypt”,
        “terms_and_condition_ar”: “https://www.emiratesnbd.com.eg/egypt-en/index.cfm/retail-banking/cards/special-offers/”,
        “terms_and_condition_en”: “https://www.emiratesnbd.com.eg/egypt-en/index.cfm/retail-banking/cards/special-offers/”,
        “country_code”: “EGY”,
        “issuer_logo_ar”: “https://stgstatic.payfort.com/frontend/files/logos/issuer/logo_ar_7.jpeg”,
         “issuer_logo_en”: “https://stgstatic.payfort.com/frontend/files/logos/issuer/logo_en_7.jpg”,
        “banking_system”: “Non Islamic”,
        “formula”: “((amount + ((amount * (effective rate/100)) * period))) / period”,
    “plan_details”: [
    {
        “plan_code”: “zAS4XyG2”,
        “currency_code”: “USD”,
        “number_of_installment”: 33,
        “fees_type”: “Percentage”,
        “fees_amount”: 300,
         “processing_fees_type”: null,
        “processing_fees_amount”: null,
        “rate_type”: “Flat”,
        “plan_merchant_type”: “Non Partner”,
        “plan_type”: “Cross-Border”,
        “fee_display_value”: 400,
        “minimum_amount”: 300,
        “maximum_amount”: 33333300,
        “amountPerMonth”: “3.00”
        }
        ],
“bins”: [
{
    “bin”: “427838”,
    “country_code”: “EGY”,
    “currency_code”: “EGP”,
    “card_brand_code”: “VISA”
},
{
    “bin”: “522025”,
    “country_code”: “EGY”,
    “currency_code”: “EGP”,
    “card_brand_code”: “Master Card”
},
{
    “bin”: “543173”,
    “country_code”: “EGY”,
    “currency_code”: “EGP”,
    “card_brand_code”: “Master Card”
},
],
    “confirmation_message_ar”: null,
    “disclaimer_message_ar”: null,
    “processing_fees_message_ar”: null,
    “confirmation_message_en”: null,
    “disclaimer_message_en”: null,
    “processing_fees_message_en”: null
}
]
},
“status”: “62”
}

Custom merchant page integration tokenization

Custom merchant page integration tokenization 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

Custom merchant page integration tokenization - Request

Include the following parameters in the Request you will send to Amazon Payment Services:

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
expiry_date Numeric Mandatory Max: 4	The card’s expiry date. Example: 2105
card_number Numeric Mandatory Max: 16	The clear credit card’s number. Example: 4005550000000001
card_security_code Numeric Mandatory Max: 4	A security code for the card. * Only AMEX accepts card security code of 4 digits. Example: 123
signature Alphanumeric Mandatory Max: 200	A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). *Please don’t include the following parameters in calculating the signature of Merchant Page 2.0 tokenization request: card_security_code, card number, expiry_date, card_holder_name, remember_me. Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
token_name Alphanumeric Optional Max: 100	The token received from the Tokenization process. Example: Op9Vmp Special characters: . @ - _
card_holder_name Alpha Optional Max: 50	The card holder name. Example: John Smith 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. Possible/ expected values: - YES - NO
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: $ ! = ? # & - _ / : .

Custom merchant page integration tokenization - Response

The following parameters will be returned in Amazon Payment Services’ 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: 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
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
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: COp9Vmp
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
card_holder_name Alpha Max: 50	The card holder name. Example: John Smith
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
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

Custom merchant page integration tokenization - Sample Request

</FORM>

Custom merchant page integration operations

Custom merchant page integration 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.

Custom merchant page integration Operations - Request

Include the following parameters in the request you will send to Amazon Payment Services:

ATTRIBUTES	Description
command Alpha Mandatory max: 20	Command. Possible/ expected values: PURCHASE
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: _ - . @ +
token_name Alphanumeric Mandatory Max: 100	The Token received from the Tokenization process. Example: Op9Vmp Special characters: _ - . @
installments Alpha Mandatory Max: 10	Used to specify the type of the Installments service. Possible/ expected values: HOSTED
issuer_code Alphanumeric Mandatory Max: 8	A code that refers to the “card issuer” the customer selected from the merchant page. Example: 12HP34SE
plan_code Alphanumeric Mandatory Max: 8	A code that refers to the “installments plan” the customer selected from the merchant page. Example: NNNN89JJ
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: . :
signature Alphanumeric Mandatory Max: 200	A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
payment_option Alpha Optional Max: 10	Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX
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
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: $ ! = ? # & - _ / : .
billing_stateProvince Alphanumeric Optional max: 20	The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
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. Reference: ISO_3166-2 Example1: AM Example2: AT
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.

Custom merchant page integration - Response

The following parameters will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
command Alpha max: 20	Command. Possible/ expected values: 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
token_name Alphanumeric max: 100	The Token received from the Tokenization process. Example: COp9Vmp
installments Alpha Max: 10	Used to specify the type of the Installments service. Possible/ expected values: HOSTED
issuer_code Alphanumeric Max: 8	A code that refers to the “card issuer” the customer selected from the merchant page. Example: 12HP34SE
plan_code Alphanumeric Max: 8	A code that refers to the “installments plan” the customer selected from the merchant page. Example: NNNN89JJ
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
signature Alphanumeric Max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: d7c185c475ac0e3
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
eci Alpha Max: 16	Ecommerce indicator. Possible/ expected values: ECOMMERCE
order_description Alphanumeric Max: 150	It holds the 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. 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 3D 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 max: 20	The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
billing_provinceCode Alphanumeric 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. Reference: ISO_3166-2 Example1: AM Example2: AT
billing_street Alphanumeric 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 max: 100	The second line of the address (if provided).
billing_postcode Alphanumeric max: 10	The post code or zip code of the address.
billing_country Alphanumeric min:3, max: 3	The 3 letter ISO standard Alphanumeric country code of the address.
billing_company Alphanumeric max: 100	The name of the company associated with this address.
billing_city Alphanumeric max: 100	The city portion of the address.
shipping_stateProvince Alphanumeric max: 20	The state or province of the address.
shipping_provinceCode Alphanumeric 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 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 max: 100	The second line of the address (if provided).
shipping_source Alphanumeric	How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE
shipping_sameAsBilling Alphanumeric	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 max: 10	The post code or zip code of the address.
shipping_country Alphanumeric min:3, max: 3	The 3 letter ISO standard Alphanumeric country code of the address.
shipping_company Alphanumeric max: 100	The name of the company associated with this address.
shipping_city Alphanumeric max: 100	The city portion of the address.

Custom merchant page integration Operations - Sample Request

Installments Hosted for Trusted Channel

Installments Hosted for Trusted – Request

Include the following parameters in the Trusted Channel – Request Parameters you will send to Amazon Payment Services:

ATTRIBUTES	Description
installments Alpha Mandatory Max: 10	Used to specify the type of the Installments service. Possible/ expected values: HOSTED
issuer_code Alphanumeric Mandatory Max: 8	A code that refers to the “card issuer” the customer selected from the merchant page. Example: 12HP34SE
plan_code Alphanumeric Mandatory Max: 8	A code that refers to the “installments plan” the customer selected from the merchant page. Example: NNNN89JJ

Installments Hosted for Trusted – Response

The following parameters will be returned in Amazon Payment Services’ response in addition to Trusted Channel – Response parameters:

ATTRIBUTES	Description
installments Alpha Max: 10	Used to specify the type of the Installments service. Possible/ expected values: HOSTED
issuer_code Alphanumeric Max: 8	A code that refers to the “card issuer” the customer selected from the merchant page. Example: 12HP34SE
plan_code Alphanumeric Max: 8	A code that refers to the “installments plan” the customer selected from the merchant page. Example: NNNN89JJ

Installments Standard Merchant Page Integration - Style Sheet

This is a list with all customizable CSS classes when you use Installments via the standard Merchant Page:

The installments-container class: responsible for the total width of the form container and the background.
The receipt-container class: responsible for the receipt section you can customize / hide it by changing the CSS values
The full-width class: responsible for the plans and switching the view from dropdown to a table.
The credit-card-container class: responsible for the credit card form`s shape look.
The error class: responsible for the error messages.
The half1, half2 class: used to merge the date and CVV fields into one block or each one on block if needed.
The bank class: is responsible for the bank agreement section.
The floatl class: is the container of each single input field.
The Pay class: responsible for the submit button.
The Visa/ MasterCard classes: used to change the color of the Visa/ MasterCard colors.

Was this helpful? Yes No

MOTO Channel

Amazon Payment’s Services’ MOTO channel enables you to process a range of transactions that do not follow the standard online shopping workflow.

For example, your customer may want to pay you offline. By sending an order in the post, by calling you, or indeed in a face to face transaction. You can process offline transactions using the MOTO channel.

Note that the MOTO (Mobile Order/ Telephone Order) channel allows you to process MOTO transactions through the Amazon Payment Services API only if you have already established a token for your customer’s payment card.

MOTO Channel 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.

MOTO Channel - MOTO Request

Include the following parameters in the Request you will send to Amazon Payment Services:

ATTRIBUTES	Description
command Alpha Mandatory max: 20	Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences.
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: _ - . @ +
eci Alpha Mandatory max: 16	Ecommerce indicator. Possible/ expected values: MOTO
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 for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
payment_option Alpha Optional max: 10	Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX
order_description Alphanumeric Optional max: 150	It holds the description of the order. Example: iPhone 6-S Special characters: `'` / . _ - # : $ Space
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: . :
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
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: . ; / _ - , `'` @
return_url Alphanumeric Optional max: 400	The URL of the Merchant’s page to be redirected to when the order is processed. Example: https://www.merchant.com Special characters: $ ! = ? # & - _ / : .

Redirection / Merchant Page integration :

{

    "command": "AUTHORIZATION",
    "access_code": "E8OHT1raKV9pdPBMishi",
    "merchant_identifier": "XMWzLQPu",
    "merchant_reference": "merchantTest-10131",
    "amount": "20000",
    "currency": "AED",
    "language": "en",
    "customer_email": "test@merchantdomain.com",
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a'",
    "eci":"MOTO",
    "token_name":"abcdefgh12345678"
}

Trusted integration :

{

    "command": "PURCHASE",
    "access_code": "E8OHT1raKV9pdPBMishi",
    "merchant_identifier": "XMWzLQPu",
    "merchant_reference": "merchantTest-10131",
    "amount": "20000",
    "currency": "AED",
    "language": "en",
    "customer_email": "test@merchantdomain.com",
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a'",
    "eci":"MOTO",
    "expiry_date":,
    "token_name":"abcdefgh12345678"
}

MOTO Channel - MOTO Response

The following parameters will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
command Alpha max: 20	Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences.
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: 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: customer@domain.com
eci Alpha max: 16	Ecommerce indicator. Possible/ expected values: MOTO
token_name Alphanumeric max: 100	The token received from the Tokenization process. Example: Op9Vmp
signature Alphanumeric max: 200	A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). 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
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
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
status Numeric max: 2	A two-digit numeric value that indicates the status of the transaction Possible/ expected values: (Please refer to section statuses).
expiry_date Numeric max: 4	The card’s expiry date. Example: 2105
card_number Numeric max: 16	The card’s number masked based on a certain standard that is selected in the technical settings. Example: 400555******0001
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
return_url Alphanumeric max: 400	The URL of the Merchant’s page to be redirected to when the order is processed. Example: https://www.merchant.com

Was this helpful? Yes No

Trusted Channel

If you are a PCI-certified merchant you can collect your customers’ credit card details on your checkout page and store the sensitive payment card data on your server. Read more about PCI compliance here.

PCI-compliant merchants can use the Amazon Payment Services trusted channel to submit payment card details so that Amazon Payment Services can execute transactions using the payment card data. Trusted Channel URLs.

Pre requisite

Trusted integration type is allowed only for the merchants who are PCI compliant , once a merchant requests to integrate with trusted integration type , the Merchant should share the PCI certificate (Payment Card Industry certificate) as well the AOC (Attestation of Compliance for onsite assessments), this in order for APS Infosec to validate certificate and confirm the merchant is eligible to collecting card details .

Trusted Channel 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.

Trusted Channel - Request

Include the following parameters in the Request you will send to Amazon Payment Services:

ATTRIBUTES	Description
command Alpha Mandatory max: 20	Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences.
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: _ - . @ +
eci Alpha Mandatory max: 16	Ecommerce indicator. Possible/ expected values: - MOTO - RECURRING - ECOMMERCE
expiry_date Numeric Mandatory max: 4	The card’s expiry date. Example: 2105
card_number Numeric Mandatory max: 19	The clear 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: 4005550000000001
card_security_code Numeric max: 4	The clear card security code collect on the merchant’s checkout page. It’s ONLY mandatory in the ecommerce requests. Only AMEX accepts card security code of 4 digits. Example: 123
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: . :
signature Alphanumeric Mandatory max: 200	A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
card_holder_name Alpha Optional max: 50	The card holder name. Example: John Smith Special characters: `'` - .
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)
order_description Alphanumeric Optional max: 150	It holds the description of the order. Example: iPhone 6-S Special characters: `'` / . _ - # : $ Space
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
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: . ; / _ - , `'` @
return_url Alphanumeric Optional max: 400	The URL of the Merchant’s page to be redirected to when the order is processed. Example: https://www.merchant.com Special characters: $ ! = ? # & - _ / : .
billing_stateProvince Alphanumeric Optional max: 20	The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
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. Reference: ISO_3166-2 Example1: AM Example2: AT
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.
agreement_id Alphanumeric Optional max: 100	identifier for the agreement with the payer to process payments to be used in recurring payments ( Required for MADA )
recurring_mode Alphanumeric Optional max: 20	Indicates if the subsequent payments within the agreement has same/different amount or unscheduled (unknown interval/amount). ( Required for MADA ) Possible/ expected values: UNSCHEDULED, VARIABLE, FIXED
recurring_transactions_count Alphanumeric Optional max: 100	The number of merchant-initiated payments within the recurring payment agreement. ( Required for MADA and only if recurring_mode = VARIABLE or FIXED )

Trusted Request Example!

Trusted Channel - Response

The following parameters will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
command Alpha max: 20	Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences.
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: 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: customer@domain.com
eci Alpha max: 16	Ecommerce indicator. Possible/ expected values: - MOTO - RECURRING - ECOMMERCE
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_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
signature Alphanumeric max: 200	A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
card_holder_name Alpha Max: 50	The card holder name. Example: John Smith
token_name Alphanumeric max: 100	The Token received from the Tokenization process. Example: Op9Vmp
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)
order_description Alphanumeric max: 150	It holds the description of the order. Example: iPhone 6-S
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	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).
3ds_url Alphanumeric Max: 300	The URL where the Merchant redirects a customer whose card is 3D Secure for authentication. Example: https://www.3dsecure.com
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. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
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. Reference: ISO_3166-2 Example1: AM Example2: AT
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.

Using Safe service (Tokenization) across the trusted channel

You can use tokenization across the Trusted Channel by following these steps:
1. You process the first authorization or purchase transaction successfully.
2. You 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 transaction alongside the card_security_code parameter.
3. Your customer does not need to complete all of their payment card details again when they check out the next time.

If your customer wants to update or delete their card you can facilitate the request - review the Update Token section.

Was this helpful? Yes No

ValU Consumer Finance

ValU consumer finance is a simple and secure financing platform where your customers can do online purchases on short-term financing and repay the amount based on specific installment plans at an interest rate offered by the financing company. For now, we have partnered with ValU in Egypt to offer consumer financing services.

Before Starting

Before you start, remember:

Your customer should be registered with ValU in order to have this benefit of installments.
You should have a valid SHA signature, to configure signatures, refer Signature and Signature Calculation Tool.
To fetch your merchant reference and merchant access code, go to Merchant Management, search and select the test merchant account and click Security Settings.

OTP Generate

This request to generate an OTP for the customer, where the customer should fill down his phone number in the merchant’s check-out page. ValU will generate the OTP code and send it to customer as SMS.

Purchase

This request allows the customer to purchase his selected items. https://paymentservices.payfort.com/FortAPI/paymentApi

URLs

Test Environment URL: https://sbpaymentservices.payfort.com/FortAPI/paymentApi

Production Environment URL: https://paymentservices.payfort.com/FortAPI/paymentApi

OTP Generate

You can now generate an OTP for the customer, where the customer should fill in their phone number in the merchant’s check-out page. ValU will generate the OTP code and send it to customer as SMS.

OTP Generate – Request

OTP Generate Request Example

{
    "merchant_reference":"TEST-009967",
    "merchant_identifier":"CycHZxVj", 
    "access_code":"zx0IPmPy5jp1vAz8Kpg7",
    "signature":"27c1303138f8718e56f311d1b3d823b5a644e6bcd4fac43d5454955b13b5b337",
    "service_command":"OTP_GENERATE",
    "language":"en",
    "payment_option":"VALU",
    "phone_number":"01220422223",
    "amount":"100000",
    "currency":"EGP",
    "include_installments":"YES",
    "wallet_amount":"500000",
    "cashback_wallet_amount":"300000"
}

OTP Generate Request Parameters

Parameter Name	Description
service_command Alpha Mandatory Max: 20	Command. Posssible values: OTP_GENERATE
access_code Alphanumeric Mandatory Max: 20	Access code. Example: zx0IPmPy5jp1vAz8Kp g7
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. The merchant reference should be the same for all APIs. For example: XYZ9239yu898
language Alpha Mandatory Max: 2	The checkout page and messages language. Possible values: - en - ar
payment_option Alpha Mandatory Max: 10	Payment option. Possible values: VALU
include_installments Alpha Optional Max: 3	Defines whether the customer can pay in installments. Possible Values YES/NO. Default Value is YES.
total_downpayment Numeric Optional Max: 100	Defines the total down-payment amount payable by the customer. *Decimal values are not accepted. For example:1200
phone_number Alphanumeric Mandatory Max: 19	The customer’s phone number registered for ValU. For example: 00008557694
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. For example: 10000
currency Alpha Mandatory Max: 3	The currency of the transaction amount in ISO code 3. For example: EGP
signature Alphanumeric Mandatory Max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature . For example,7cad05f0212ed933c9a5d5dffa31661acf2c827a
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. Special characters.;/_-,’@ For example: JohnSmith
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. Special characters.;/_-,’@ JohnSmith
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. Special characters.;/_-,’@ For example: JohnSmith
wallet_amount Numeric Mandatory Max:10	Wallet amount or ToU is a gift balance that you can purchase using your valU limit and can pay in flexible installment plans from 6-60 months. You can transfer ToU balance to all of your loved ones, they don’t need to be valU customers. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000
cashback_wallet_amount Numeric Mandatory Max:10	Amount stored in cashback wallet. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000

OTP Generate – Response

Generate Response Example

{
    "amount": "100000",
    "response_code": "88000",
    "merchant_order_id": "169996200000330196",
    "signature": "838b5a01394e51c16c1975f18301e1cbdc082517b9f1f58979bbc66ae1596987",
    "merchant_identifier": "XMWzLQPu",
    "access_code": "z1gW9QUmty6lMIN3E8u1",
    "payment_option": "VALU",
    "language": "en",
    "service_command": "OTP_GENERATE",
    "response_message": "Success",
    "merchant_reference": "TEST-009967",
    "phone_number": "01220422223",
    "currency": "EGP",
    "wallet_amount":"500000",
    "cashback_wallet_amount":"300000",
    "installment_detail": {
        "financed_amount": 100000,
        "plan_details": [
            {
                "fees_amount": 3000,
                "amount_per_month": 18900,
                "number_of_installments": 6
            },
            {
                "fees_amount": 3000,
                "amount_per_month": 16500,
                "number_of_installments": 7
            },
           {
                "fees_amount": 3000,
                "amount_per_month": 4200,
                "number_of_installments": 60
            }
        ]
    },
    "status": "88"
}

OTP Generate Response Parameters

Parameter Name	Description
service_command Alpha Max: 20	Command. For example: OTP_GENERATE
access_code Alphanumeric Max: 20	Access code. For example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier Alphanumeric Max: 20	The ID of the Merchant. For example: CycHZxVj
merchant_reference Alphanumeric Max: 40	The Merchant’s unique order number. For example:XYZ2939-yu898
language Alpha Max: 2	The checkout page and messages language.For example: - en - ar
payment_option Alpha 10	Payment option. For example:VALU
phone_number Alphanumeric Max: 19	The customer’s phone number registered for ValU. For example: 00008557694
merchant_order_id Alphanumeric 100	The Merchant’s unique order id. * It should be unique per each transaction and you should use the same merchant_order_id value for all APIs. For example: Valu123
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. For example: 10000
currency Alpha Max: 3	The currency of the transaction amount in ISO code 3. For example:EGP
total_downpayment Numeric Max: 100	Defines the total down-payment amount payable by the customer. For example: 10000
installment_detail List	Defines installment plan details as selected by the customer. This is displayed if include_installments is set to YES. Lists the fee amount, installment amount, installment per month and total installment.
signature Alphanumeric Max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature For example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
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. For 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.
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.
response_message Alphanumeric Max: 150	Message description of the response code. It returns according to the request language. 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 message. For example: 88000
status Numeric Max: 2	A two-digit numeric value that indicates the status of the transaction.Please refer to section statuses.
wallet_amount Numeric Mandatory Max:10	Wallet amount or ToU is a gift balance that you can purchase using your valU limit and can pay in flexible installment plans from 6-60 months. You can transfer ToU balance to all of your loved ones, they don’t need to be valU customers. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000
cashback_wallet_amount Numeric Mandatory Max:10	Amount stored in cashback wallet. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000

Purchase

This request allows the Customer to Purchase his selected items through the selected consumer finance.

Purchase – Request

Purchase Request Example

{
"merchant_reference":"XYZ9239-yu898", 
"merchant_identifier":"CycHZxVj", 
"access_code":"zx0IPmPy5jp1vAz8Kpg7",
"signature":"b574e362cc08d7504d8277e71400132f06064ee1537cd570717569b583dec0b5", 
"command":"PURCHASE",
"language":"en",
"payment_option":"VALU", 
"phone_number":"00008557694", 
"amount":"10000",
"currency":"EGP", 
"customer_email":"customer@domain.com", 
"otp":"123456",
"tenure":"6", 
"total_down_payment":"1200",
"purchase_description":"Test",
"wallet_amount":"500000",
"cashback_wallet_amount":"300000"
}

Purchase Request Parameters

Parameter Name	Description
command Alpha Mandatory Max: 20	Command. Possible values: PURCHASE
access_code Alphanumeric Mandatory Max: 20	Access code.
merchant_identifier Alphanumeric Mandatory Max: 20	The ID of the Merchant. For example: CycHZxVj
merchant_reference Alphanumeric Mandatory Max:40	The Merchant’s unique order number. The merchant reference should be the same for all APIs. -_. For example: XYZ9239-yu898
payment_option Alpha Mandatory Max: 10	Payment option. Possible Values: VALU
phone_number Alphanumeric Mandatory 19	The customer’s phone number registered for ValU. For example: 00008557694
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. For example: 10000
currency Alpha Mandatory Max: 3	The currency of the transaction’s amount in ISO code 3. For example: EGP
language Alpha Mandatory Max: 2	The checkout page and messages language.For example - en - ar
customer_email Alphanumeric Mandatory Max:254	The customer’s email. Special Characters: _-.@+ For example: customer@domain.com
otp Alphanumeric Mandatory Max: 10	OTP sent by mobile. For example, 123456
tenure Alphanumeric Mandatory Max: 100	The tenure for the installment payments. For example: 6
signature Alphanumeric Mandatory Max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature For example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
purchase_ description Alphanumeric Mandatory Max:100	The purchase description. For example: Test
total_down_payment Alphanumeric Mandatory Max:100	The total transaction’s down payment.Decimal values are not accepted.For example:0
wallet_amount Numeric Mandatory Max:10	Wallet amount or ToU is a gift balance that you can purchase using your valU limit and can pay in flexible installment plans from 6-60 months. You can transfer ToU balance to all of your loved ones, they don’t need to be valU customers. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000
cashback_wallet_amount Numeric Mandatory Max:10	Amount stored in cashback wallet. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000

Purchase – Response

Purchase Response Example

{
"amount":"10000",
"response_code":"14000", 
"signature":"afac5bd50250743cbd87ce208b1aabcae1080b9060bdb7212cf2c36e201cd6d0", 
"merchant_identifier":"CycHZxVj",
"access_code":"zx0IPmPy5jp1vAz8Kpg7", 
"payment_option":"VALU", 
"customer_ip":"192.178.1.10", 
"language":"en",
"eci":"ECOMMERCE", 
"fort_id":"149295435400084008",
"command":"PURCHASE",
"response_message":"Success", 
"merchant_reference":"XYZ2939-yu898", 
"customer_email":"customer@domain.com", 
"currency":"EGP", 
"phone_number":"00008557694", 
"status":"14",
"wallet_amount":"500000",
"cashback_wallet_amount":"300000"
}

Purchase Response Parameters

Parameter Name	Description
command Alpha Max:20	Command. Possible Values: PURCHASE
access_code Alphanumeric Max: 20	Access code. For example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier Alphanumeric Max: 20	The ID of the Merchant. For example: CycHZxVj
merchant_reference Alphanumeric Max: 40	The Merchant’s unique order number. For example: XYZ2939-yu898
payment_option Alpha Max:10	Payment option. Possible values: VALU
phone_number Alphanumeric Max: 19	The customer’s phone number registered for ValU. For example: 00008557694
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. For example: 10000
currency Alpha Max: 3	The currency of the transaction’s amount in ISO code 3. For example: EGP
language Alpha Max:2	The checkout page and messages language.For example - en - ar
customer_email Alphanumeric Max: 254	The customer’s email. For example: customer@domain.com
signature Alphanumeric Max:200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature For example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
purchase_description Alphanumeric Max:100	The purchase description. For example: Test
customer_ip Alphanumeric Max:45	It holds the customer’s IP address. We support IPv4 and IPv6 as shown in the example on the right hand side. IPv4è192.17 8.1.10 IPv6*è2001:0db8:3042:0002:5a55:caff:fef6:bdbf
eci Alpha Max:16	E-commerce indicator. Possible values: ECOMMERCE
fort_id Numeric Max: 20	The order’s unique reference returned by our system.For example: 149295435400084008
response_message Alphanumeric Max:150	Message description of the response code. It returns according to the request language. 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 message. For example: 14000
status Numeric Max: 2	A two-digit numeric value that indicates the status of the transaction. Please refer to section statuses.
wallet_amount Numeric Mandatory Max:10	Wallet amount or ToU is a gift balance that you can purchase using your valU limit and can pay in flexible installment plans from 6-60 months. You can transfer ToU balance to all of your loved ones, they don’t need to be valU customers. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000
cashback_wallet_amount Numeric Mandatory Max:10	Amount stored in cashback wallet. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000

Refund API

The refund API has been implemented to follow the same standards for all the other payment option refund flow. Please use the following document to understand the flow: https://docs.payfort.com/docs/api/build/index.html#refund-operation

Note; The refund API of ValU supports the full refund and partial.

Get Installment Plans Request

Using this API, you can fetch the installment plans the customer has selected.

Request Example

{
"service_command": "GET_INSTALLMENTS_PLANS",
"merchant_reference":"XYZ9239-yu898",
"merchant_identifier":"CycHZxVj", 
"access_code":"zx0IPmPy5jp1vAz8Kpg7",
"signature":"b574e362cc08d7504d8277e71400132f06064ee1537cd570717569b583dec0b5",
"phone_number": "01220422223",
"payment_option":"VALU",
"language": "en",
"amount":"100000",
"total_downpayment":"1200",
"wallet_amount":"500000",
"cashback_wallet_amount":"300000"

}

Get Installment Plan Parameters

Parameter Name	Description
service_command Alpha Mandatory Max:20	Command. For example:GET_INSTALLMENTS_PLANS
access_code Alphanumeric Mandatory Max:20	Access code. For example:zx0IPmPy5jp1vAz8Kpg7
merchant_identifier Alphanumeric Mandatory Max: 20	The ID of the Merchant. For example: CycHZxVj
merchant_reference Alphanumeric Mandatory Max: 40	The Merchant’s unique order number. The merchant reference should be the same for all APIs. Special Characters-_. For example:XYZ9239-yu898
language Alpha Mandatory Max:2	The checkout page and messages language.Possible - en - ar
payment_option Alpha Mandatory Max: 10	Payment option. For example: VALU
total_downpayment Numeric Optional Max:100	Defines the total down-payment amount payable by the customer. *Decimal values are not accepted. For example: 1200
phone_number Alphanumeric Mandatory Max:19	The customer’s phone number registered for ValU. For example:00008557694
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. For example:10000
currency Alpha Mandatory Max: 3	The currency of the transaction amount in ISO code 3. For example: EGP
signature Alphanumeric Mandatory Max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature For example 7cad05f0212ed933c9a5d5dffa31661acf2c827a
wallet_amount Numeric Mandatory Max:10	Wallet amount or ToU is a gift balance that you can purchase using your valU limit and can pay in flexible installment plans from 6-60 months. You can transfer ToU balance to all of your loved ones, they don’t need to be valU customers. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000
cashback_wallet_amount Numeric Mandatory Max:10	Amount stored in cashback wallet. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000

Get Installment Plans Response

Response Example

{
"amount": "100000",
"response_code": "62000",
"signature": "0d3eace32f45ef9d54bf290bb65bebfbbb5b8ad4e3a0d61d95c60023d4c65c18",
"merchant_identifier": "XMWzLQPu",
"access_code": "z1gW9QUmty6lMIN3E8u1",
"payment_option": "VALU",
"language": "en",
"total_downpayment": "1200",
"service_command": "GET_INSTALLMENTS_PLANS",
"response_message": "Success",
"merchant_reference": "10055",
"phone_number": "01220422223",
"currency": "EGP", 
"wallet_amount":"500000",
"cashback_wallet_amount":"300000",
"installment_detail": 
{
"financed_amount": 98800,
"plan_details": [
{
"fees_amount": 0,
"amount_per_month": 18700,
"number_of_installments": 6
},
{
"fees_amount": 0,
"amount_per_month": 4800,
"number_of_installments": 39
},
{
"fees_amount": 0,
"amount_per_month": 4700,
"number_of_installments": 42
},
{
"fees_amount": 0,
"amount_per_month": 4500,
"number_of_installments": 45
}
]
},
"status": "62"
}

Get Installment Response Parameters

Parameter Name	Description
service_command Alpha Max: 20	Command. Possible Values: GET_INSTALLMENTS_PLANS
access_code Alphanumeric Max: 20	Access code. For example: Lzx0IPmPy5 jp1vAz8Kpg7
merchant_identifier Alphanumeric Max:20	The ID of the Merchant. For example:CycHZxVj
merchant_reference Alphanumeric Max: 40	The Merchant’s unique order number. The merchant reference should be the same for all APIs. Special Characters-_=. XYZ9239-yu898
language Alpha Max: 2	The checkout page and messages language. For example - en - ar
payment_option Alpha Max: 10	Payment option. For example VALU
total_downpayment Numeric Max: 100	Defines the total down-payment amount payable by the customer. *Decimal values are not accepted. Special Characters - For example: 1200
phone_number Alphanumeric Max: 19	The customer’s phone number registered for ValU. 00008557694
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. For example: 10000
currency Alpha Max: 3	The currency of the transaction amount in ISO code 3. For example: EGP
signature Alphanumeric Max: 200	A string hashed using the Secure Hash Algorithm.Please refer to section Signature
installment_detail List	A list of all the details of installments, such as number of installments, fees due every month.
wallet_amount Numeric Mandatory Max:10	Wallet amount or ToU is a gift balance that you can purchase using your valU limit and can pay in flexible installment plans from 6-60 months. You can transfer ToU balance to all of your loved ones, they don’t need to be valU customers. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000
cashback_wallet_amount Numeric Mandatory Max:10	Amount stored in cashback wallet. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000

Customer Verify

This request allows the Merchant to identify whether the customer is a ValU registered customer or not; by verifying the Customer’s phone number.

Customer Verify – Request

Customer Verify Request Example

{

"service_command":"CUSTOMER_VERIFY", "merchant_reference":"XYZ9239-yu898", "merchant_identifier":"CycHZxVj", "access_code":"zx0IPmPy5jp1vAz8Kpg7", "language":"en",
"payment_option":"VALU",

"phone_number":"00008557694",

"signature":"54efbd76bd644e9ef237c39137bf5d2304dc1bfdf6f6302065b448f2456a07a7"

}

Customer Verify Request Parameters

Parameter Name	Description
service_command Alpha Max: 20 Mandatory	Command For example:CUSTOMER_VERIFY
access_code Alphanumeric Mandatory Max:20	Access code. For example:zx0IPmPy5jp1vAz8Kpg7
merchant_identifier Alphanumeric Mandatory Max: 20	The ID of the Merchant. For example:CycHZxVj
merchant_reference Alphanumeric Mandatory Max:40	The Merchant’s unique order number. The merchant reference should be the same for all APIs. Special Characters:-_. For example: XYZ9239-yu898
language Alpha Mandatory Max: 2	The checkout page and messages language.
payment_option Alpha Mandatory Max: 10	Payment option. For example:VALU
phone_number Alphanumeric Mandatory Max:19	The customer’s phone number registered for ValU. For example: 00008557694
signature Alphanumeric Mandatory Max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature 7cad05f0212ed933c9a5d5dffa31661acf2c827a

Customer Verify – Response

Customer Verify Response Example!

{
"response_code":"90000", 
"response_message":"Success", 
"service_command":"CUSTOMER_VERIFY",
"signature":"27c1303138f8718e56f311d1b3d823b5a644e6bcd4fac43d5454955b13b5b337", 
"merchant_identifier":"CycHZxVj",
"merchant_reference":"XYZ2939-yu898", 
"access_code":"zx0IPmPy5jp1vAz8Kpg7", 
"payment_option":"VALU", 
"language":"en", 
"phone_number":"00008557694", 
"status":"90"
}

Customer Verify Response Parameters

Parameter Name	Description
service_command Alpha Max: 20	Command. For example: CUSTOMER_VERIFY
access_code Alphanumeric Max:20	Access code. For example:zx0IPmPy5jp1vAz8Kpg7
merchant_identifier Alphanumeric Max: 20	The ID of the Merchant. For example: CycHZxVj
merchant_reference Alphanumeric Max: 40	The Merchant’s unique order number. The merchant reference should be the same for all APIs. Special Characters: -_. For example: XYZ9239-yu898
language Alpha Max: 2	The checkout page and messages language. For example - en - ar
payment_option Alpha Max:10	Payment option.For example VALU
total_downpayment Numeric Max: 100	Defines the total down-payment amount payable by the customer. *Decimal values are not accepted. For example: 1200
phone_number Alphanumeric Max: 19	The customer’s phone number registered for ValU. For example:00008557694
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. Max: 10000
currency Alpha Max: 3	The currency of the transaction amount in ISO code 3. For example: EGP
signature Alphanumeric Max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature For example: aa7cad05f0212ed933c9a5d5dffa31661acf2c827a
response_message Alphanumeric Max: 150	Message description of the response code. It returns according to the request language.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 message. For example: 88000
status Numeric Max: 2	A two-digit numeric value that indicates the status of the transaction.Please refer to section statuses

KNET

KNET is a local payment option which operating in Kuwait owed by Central Bank of Kuwait , this option supports only the Debit Cards , means that the customers can use their own debit cards only to process the payments through KNET , as being said this option is supported through the Redirection channel only , means that the customers will get redirected to KNET page to complete the payment process then return back to the merchant’s confirmation page.

To integrate KNET payment option in your checkout pages, you need to follow Redirection, it’s just adding a new parameter to the Redirection API request called “payment_option” with “KNET” value .

The integration flow , How it works :

The customer will reach checkout page and choose KNET option to pay through it .
The Merchant will submit Redirection request from his side and the customer will get redirected to KNET page to complete the payment process .
A response from the API call will be sent to the merchant on his redirection url contains the response parameters .
As a mandatory KNET requirement the merchant must display the below transaction details in the receipt pages to the customer “the page which the customer getting redirected to it after processing the payment” :

knet_ref_number
third_party_transaction_number
payment amount
transaction date
Success message/Failed message

Sample KNET Redirection Request

3D Secure services

3D Secure (3DS) adds a layer of authentication on top of the CVV code commonly used to prevent payment card fraud. Customers who use a 3D Secure-enrolled card perform an additional verification step during the payment process.

Amazon Payment Services offers you four ways to treat 3D Secure:

Standard 3D Secure where we automatically pass customers through the 3D Secure steps if the customer’s payment card is enrolled in 3D Secure.
Flex 3D Secure where merchants can fine-tune the 3D Secure response to bypass 3D Secure on some transactions.
External 3D Secure service where you can choose to use an external 3D Secure processor instead of Amazon Payment Services 3D Secure processing.
Standalone 3D Secure where you can take advantage of our efficient 3D Secure process to handle 3D Secure as a distinct step.

3DS2 (EMV) Service

Visa and Mastercard issued a new mandate to card issuers covering 3DS 2.0. The new version of 3DS, version 2.0, is a risk-based version of 3DS authentication where the merchants mush adhere to the requirements and APS will minimize the efforts on merchants by passing the mandatory fields to the processor, the merchant can submit additional fields in the API request. The following are optional fields for 3DS2 service:

ATTRIBUTES	Description
billing_stateProvince Alphanumeric Optional max: 20	The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
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. Reference: ISO_3166-2 Example1: AM Example2: AT
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. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
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. Reference: ISO_3166-2 Example1: AM Example2: AT
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.

Standard 3D Secure & Flex 3D Secure Services

Standard 3D Secure Service

This service provides cardholders a decreased risk of other people being able to use their payment cards fraudulently on the Merchant’s site.

Include the following parameter in the Request you will send to Amazon Payment Services:

ATTRIBUTES	Description
check_3ds Alpha Optional max: 2	This parameter allows the Merchant to deactivate the 3D Secure service per transaction. This parameter can be used with both Authorization and Purchase transactions. Possible/ expected values: NO

Flex 3D Secure Service

Under certain circumstances you may choose to bypass the 3D Secure process to reduce the number of actions your customer has to take – and to deliver a more seamless payment experience.

Amazon Payment Services gives you the option to waive the 3D Secure process where a transaction meets conditions that you set. It’s called Flex 3D Secure.

This service gives you the flexibility to downgrade the 3D Secure authentication in the transaction processing, based on a set of rules of your choice. You can activate/ deactivate this service under the “Flex Management” tab in your back office.

External 3D Secure Service

Where you have an existing, preferred 3D Secure verification provider you can opt to use your preferred external 3D Secure service when processing payments with us. This service allows the Amazon Payment Services server to accept purchase and authorization transactions where 3D Secure verification check is performed externally using an external MPI.

External 3D Secure 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.

External 3D Secure - Request

Include the following parameters in the Request you will send to Amazon Payment Services:

ATTRIBUTES	Description
command Alpha Mandatory max: 20	Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences.
access_code Alphanumeric Mandatory max: 20	Merchant account Access Code. Example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier Alphanumeric Mandatory max: 20	Amazon Payment Services Merchant Account identifier. Example: CycHZxVj
merchant_reference Alphanumeric Mandatory max: 40	The Merchant’s unique reference for a specific request. 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: _ - . @ +
eci Alpha Optional Max: 16	Ecommerce indicator. Possible/ expected values: - ECOMMERCE - MOTO
expiry_date Numeric Mandatory Max: 4	The card’s expiry date. Example: 2105
card_number Numeric Mandatory Max: 19	The clear 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: 4005550000000001
card_security_code Numeric Max: 4	A security code for the card. * Only AMEX accepts card security code of 4 digits. Example: 123
signature Alphanumeric Mandatory max: 200	A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
3ds_xid Alphanumeric Mandatory Max: 28	Unique transaction Identification number to identify the 3DS transaction. Example: 6kQGHEiZDU0H4+mUWF7zELHAcqM=
3ds_enrolled Alpha Mandatory Max: 1	Parameter that hold if the card is enrolled or not. Possible/ expected values: - Y (Yes) - N (No)
3ds_status Alpha Mandatory Max: 1	The status of the 3ds check just like 3-DSEnrolled but this parameter is available after a check is completed. Possible/ expected values: - Y - N - U - A
3ds_eci Numeric Mandatory Max: 2	The eCommerce indicator returned from the MPI. Possible/ expected values: - 05 - 06
ver_token Alphanumeric Mandatory Max: 28	Verification token generated by the issuer to prove that the cardholders has been authenticated. Example: gIGCg4SFhoeIiYqLjI2Oj5CRkpM=
card_holder_name Alpha Optional max: 50	The card holder name. Example: John Smith Special characters: `'` - .
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)
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: _ \ / - . `'` Space
phone_number Numeric 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: . ; / _ - , `'` @
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: $ ! = ? # & - _ / : .
agreement_id Alphanumeric Optional max: 100	identifier for the agreement with the payer to process payments to be used in recurring payments ( Required for MADA )
ds_transaction_id Alphanumeric Optional Max: 40	The Directory Server Transaction ID generated during the authentication transaction.

External 3D Secure - Response

The following parameters will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
command Alpha Mandatory max: 20	Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences.
access_code Alphanumeric Mandatory max: 20	Merchant account Access Code. Example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier Alphanumeric Mandatory max: 20	FORT Merchant Account identifier. Example: CycHZxVj
merchant_reference Alphanumeric Mandatory max: 40	The Merchant’s unique reference for a specific request. 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: _ - . @ +
eci Alpha Optional Max: 16	Ecommerce indicator. Possible/ expected values: - ECOMMERCE - MOTO
expiry_date Numeric Mandatory Max: 4	The card’s expiry date. Example: 2105
card_number Numeric Mandatory Max: 19	The clear 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: 4005550000000001
signature Alphanumeric Mandatory max: 200	A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
card_holder_name Alpha Optional max: 50	The card holder name. Example: John Smith Special characters: `'` - .
token_name Alphanumeric Optional Max: 100	The Token received from the Tokenization process. Example: Op9Vmp Special characters: . @ - _
fort_id Numeric Max: 20	The order’s unique reference returned by our system. Example: 149295435400084008
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)
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: _ \ / - . `'` Space
phone_number Numeric 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: . ; / _ - , `'` @
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: $ ! = ? # & - _ / : .
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
3ds_url Alphanumeric Max: 300	The URL where the Merchant redirects a customer whose card is 3D Secure for authentication. Example: https://www.3dsecure.com

Standalone 3D Secure service

Standalone 3D Secure Service for PCI-compliant Merchants

You can use the standalone 3D Secure service to process 3D Secure authentication at a specific point in your transaction workflow.

Ordinarily, your customer would be requested to complete 3D Secure once a purchase is made and when you are attempting to apply a charge to your customer’s payment card. However, in some instances, you may want to process 3D Secure as a distinct step.

3D Secure Enrollment Service Command 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.

3D Secure Enrollment Service Command - Request

Include the following parameters in the Request you will send to Amazon Payment Services:

ATTRIBUTES	Description
service_command Alpha Mandatory max: 20	Command. Possible/ expected values: 3DS_ENROLLMENT Special characters: _
access_code Alphanumeric Mandatory max: 20	Merchant account Access Code. Example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier Alphanumeric Mandatory max: 20	Amazon Payment Services Merchant Account identifier. Example: CycHZxVj
merchant_reference Alphanumeric Mandatory max: 40	The Merchant’s unique reference for a specific request. 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
expiry_date Numeric Mandatory Max: 4	The card’s expiry date. Example: 2105
card_number Numeric Mandatory Max: 19	The clear credit card’s number. Example: 4005550000000001
merchant_3ds_url Alphanumeric Mandatory max: 300	The URL where the Merchant will be redirected to see the returned 3ds parameters. Example: https://www.merchant.com 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
confirm_3ds Alpha Optional max: 3	To trigger confirm 3d secure data received automatically, include this parameter in the enrollment api call. This will eliminate the need of initiating 3ds_authentication API call after receiving 3ds data on merchant_3d_url Possible/ expected values: -YES -NO
billing_stateProvince Alphanumeric Optional max: 20	The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
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. Reference: ISO_3166-2 Example1: AM Example2: AT
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.

3D Secure Enrollment Request Example!

3D Secure Enrollment Service Command - Response

The following parameters will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
service_command Alpha max: 50	Command. Possible/ expected values: 3DS_ENROLLMENT Special characters: _
access_code Alphanumeric max: 20	Merchant account Access Code. Example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier Alphanumeric max: 20	Amazon Payment Services Merchant Account identifier. Example: CycHZxVj
merchant_reference Alphanumeric max: 40	The Merchant’s unique reference for a specific request. 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
language Alpha Max: 2	The checkout page and messages language. Possible/ expected values: en/ ar
expiry_date Numeric Max: 4	The card’s expiry date. Example: 2105
card_number Numeric > Max: 19	The masked credit card’s number. Example: 400555******0001
merchant_3ds_url Alphanumeric max: 300	The URL where the Merchant will be redirected to see the returned 3ds parameters. Example: https://www.merchant.com Special characters: - & ? = _ . : / #
3ds_enrolled Alpha Max: 1	Parameter that hold if the card is enrolled or not. Possible/ expected values: - Y (Yes) - N (No) - U (Unspecified failure)
threeds_id Alphanumeric Max: 100	The 3ds operations unique reference. Example: 153606397100001061
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. Example: Insufficient Funds
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: 44000
status Numeric max: 2	A two-digit numeric value that indicates the status of the transaction Possible/ expected values: (Please refer to section statuses).
confirm_3ds Alpha max: 3	To trigger confirm 3d secure data received automatically, include this parameter in the enrollment api call. This will eliminate the need of initiating 3ds_authentication API call after receiving 3ds data on merchant_3d_url Possible/ expected values: -YES -NO
billing_stateProvince Alphanumeric max: 20	The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
billing_provinceCode Alphanumeric 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. Reference: ISO_3166-2 Example1: AM Example2: AT
billing_street Alphanumeric 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 max: 100	The second line of the address (if provided).
billing_postcode Alphanumeric max: 10	The post code or zip code of the address.
billing_country Alphanumeric min:3, max: 3	The 3 letter ISO standard Alphanumeric country code of the address.
billing_company Alphanumeric max: 100	The name of the company associated with this address.
billing_city Alphanumeric max: 100	The city portion of the address.
shipping_stateProvince Alphanumeric max: 20	The state or province of the address.
shipping_provinceCode Alphanumeric 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 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 max: 100	The second line of the address (if provided).
shipping_source Alphanumeric	How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE
shipping_sameAsBilling Alphanumeric	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 max: 10	The post code or zip code of the address.
shipping_country Alphanumeric min:3, max: 3	The 3 letter ISO standard Alphanumeric country code of the address.
shipping_company Alphanumeric max: 100	The name of the company associated with this address.
shipping_city Alphanumeric max: 100	The city portion of the address.

3D Secure Enrollment Response Example!

{
“amount”: “10000”,
“response_code”: “44000”,
“card_number”: “400555******0001”,
“signature”: “44d80139e9557661822c2e2d571983cc84a2de5a85e7499835dffd19f6192040”,
“merchant_identifier”: “CycHZxVj”,
“access_code”: “zx0IPmPy5jp1vAz8Kpg7”,
“expiry_date”: “2105”,
“merchant_3ds_url”: “https://www.merchant.com”,
“language”: “en”,
“threeds_id”: “153606397100001061”,
“3ds_url”: “https://migs.mastercard.com.au/vpcpay?paymentId=3499269050937443526&DOID=E870F0B65189A7128A86B7FC206F136E&o=pt&action=retry”,
“service_command”: “3DS_ENROLLMENT”,
“response_message”: “Success”,
“merchant_reference”: “XYZ9239-yu898”,
“3ds_enrolled”: “Y”,
“currency”: “AED”,
“status”: “44”
}

• After you get back a 3Ds Enrollment response that includes the parameter “3ds_enrolled” of value “Y”; follow the below steps for the 3Ds Authentication request:

In case you are on “MPGS” processor; four parameters will be returned in the “3D Secure Enrollment”; as below:
    • order.id
    • transaction.id
    • response.gatewayRecommendation
    • result
And you have to copy them in the “3D Secure Authentication” request; as you will see in the 3Ds Authentication request example.
In case you are on “Cybersource” processor; two parameters returns in the “3D Secure Enrollment”; as below:
• MD
• TransactionId
And you have to copy them in the “3D Secure Authentication” request; as you will see in the 3Ds Authentication request example.

3D Secure Authentication Service Command 3D Secure Authentication Service Command 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.

3D Secure Authentication Service Command - Request Include the following parameters in the Request you will send to Amazon Payment Services:

ATTRIBUTES	Description
service_command Alpha Mandatory max: 20	Command. Possible/ expected values: 3DS_AUTHENTICATION 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
merchant_reference Alphanumeric Mandatory max: 40	The Merchant’s unique number. *Please, use the same merchant reference you used in the “generate report” request. Example: XYZ9239-yu898
language Alpha Mandatory Max: 2	The checkout page and messages language. Possible/ expected values: en/ ar
third_party_body Alphanumeric Mandatory Max: 6000	Combinations of 3ds parameters from the 3ds_enrollment. Example: Check the examples below 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

3D Secure Authentication Request on Cybersource Processor Example!

3D Secure Authentication Request on MPGS Processor Example!

3D Secure Authentication Service Command - Response The following parameters will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
service_command Alpha max: 20	Command. Possible/ expected values: 3DS_AUTHENTICATION
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 reference for a specific request. Example: XYZ9239-yu898
language Alpha Max: 2	The checkout page and messages language. Possible/ expected values: en/ ar
threeds_id Alphanumeric Max: 100	The 3ds operations unique reference. Example: 153606397100001061
3ds_enrolled Alpha Max: 1	Parameter that hold if the card is enrolled or not. Possible/ expected values: - Y (Yes) - N (No)
3ds_status Alpha Max: 1	The status of the 3ds check just like 3DSEnrolled but this parameter is available after a check is completed. Possible/ expected values: - Y - N - U - A
3ds_eci Numeric Max: 2	The eCommerce indicator returned from the MPI. Possible/ expected values: - 05 - 06
ver_type Alphanumeric Max: 3	The type of verification used for 3DS. Possible/ expected values: - 3DS - SPA
ver_token Alphanumeric Max: 28	Verification token generated by the issuer to prove that the cardholders has been authenticated. Example: gIGCg4SFhoeIiYqLjI2Oj5CRkpM=
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. Example: Insufficient Funds
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: 44000
status Numeric max: 2	A two-digit numeric value that indicates the status of the transaction Possible/ expected values: (Please refer to section statuses).

3D Secure Authentication Response on Cybersource/ MPGS Processors Example!

Was this helpful? Yes No

Standalone 3D secure service for merchants that are not PCI compliant

This service allows you to use the 3D Secure service in a standalone request without processing an authorization or purchase transaction. Instead, you trigger 3D Secure authentication separately to get user authentication in a distinct step. You can execute a authorization or purchase transaction at a later time based on pre-acquired authentication.

3D Secure Enrollment Service Command 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.

3D Secure Enrollment Service Command - Request

Include the following parameters in the request you will send to Amazon Payment Services:

ATTRIBUTES	Description
service_command Alpha Mandatory max: 20	Command. Possible/ expected values: 3DS_ENROLLMENT Special characters: _
access_code Alphanumeric Mandatory max: 20	Merchant account Access Code. Example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier Alphanumeric Mandatory max: 20	Amazon Payment Services Merchant Account identifier. Example: CycHZxVj
merchant_reference Alphanumeric Mandatory max: 40	The Merchant’s unique reference for a specific request. 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
token_name Alphanumeric Mandatory Max: 100	The Token received from the Tokenization process. Example: Op9Vmp Special characters: . @ - _
merchant_3ds_url Alphanumeric Mandatory max: 300	The URL where the Merchant will be redirected to see the returned 3ds parameters. Example: https://www.merchant.com 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
confirm_3ds Alpha Optional max: 3	To trigger confirm 3d secure data received automatically, include this parameter in the enrollment api call. This will eliminate the need of initiating 3ds_authentication API call after receiving 3ds data on merchant_3d_url Possible/ expected values: -YES -NO
billing_stateProvince Alphanumeric Optional max: 20	The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH
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. Reference: ISO_3166-2 Example1: AM Example2: AT
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.

3D Secure Enrollment Request Example!

3D Secure Enrollment Service Command - Response

The following parameters will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
service_command Alpha max: 50	Query operations command. Possible/ expected values: 3DS_ENROLLMENT
access_code Alphanumeric max: 20	Merchant account Access Code. Example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier Alphanumeric max: 20	Amazon Payment Services Merchant Account identifier. Example: CycHZxVj
merchant_reference Alphanumeric max: 40	The Merchant’s unique reference for a specific request. 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
language Alpha Max: 2	The checkout page and messages language. Possible/ expected values: en/ ar
token_name Alphanumeric Max: 100	The Token received from the Tokenization process. Example: Op9Vmp Special characters: . @ - _
merchant_3ds_url Alphanumeric max: 300	The URL where the Merchant will be redirected to see the returned 3ds parameters. Example: https://www.merchant.com Special characters: - & ? = _ . : / #
3ds_enrolled Alpha Max: 1	Parameter that hold if the card is enrolled or not. Possible/ expected values: - Y (Yes) - N (No) - U (Unspecified failure)
threeds_id Alphanumeric Max: 100	The 3ds operations unique reference. Example: 153606397100001061
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. Example: Insufficient Funds
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: 44000
status Numeric max: 2	A two-digit numeric value that indicates the status of the transaction Possible/ expected values: (Please refer to section statuses).
confirm_3ds Alpha Optional max: 3	To trigger confirm 3d secure data received automatically, include this parameter in the enrollment api call. This will eliminate the need of initiating 3ds_authentication API call after receiving 3ds data on merchant_3d_url Possible/ expected values: -YES -NO

3D Secure Enrollment Response Example

• After you get back a 3D Secure Enrollment response that includes the parameter “3ds_enrolled” of value “Y”; follow the below steps for the 3D Secure Authentication request:

In case you are on “MPGS” processor; four parameters will be returned in the “3D Secure Enrollment”; as below:
    • order.id
    • transaction.id
    • response.gatewayRecommendation
    • result
And you have to copy them in the “3D Secure Authentication” request; as you will see in the 3Ds Authentication request example.
In case you are on “Cybersource” processor; two parameters returns in the “3D Secure Enrollment”; as below:
• MD
• TransactionId
And you have to copy them in the “3D Secure Authentication” request; as you will see in the 3Ds Authentication request example.

3D Secure Authentication Service Command 3D Secure Authentication Service Command 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.

3D Secure Authentication Service Command - Request Include the following parameters in the Request you will send to Amazon Payment Services:

ATTRIBUTES	Description
service_command Alpha Mandatory max: 20	Command. Possible/ expected values: 3DS_AUTHENTICATION 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
merchant_reference Alphanumeric Mandatory max: 40	The Merchant’s unique number. *Please, use the same merchant reference you used in the “generate report” request. Example: XYZ9239-yu898
language Alpha Mandatory Max: 2	The checkout page and messages language. Possible/ expected values: en/ ar
third_party_body Alphanumeric Mandatory Max: 6000	Combinations of 3ds parameters from the 3ds_enrollment. Example: Check the examples below 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

3D Secure Authentication Request on Cybersource Processor Example!

3D Secure Authentication Request on MPGS Processor Example!

3D Secure Authentication Service Command - Response The following parameters will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
service_command Alpha max: 20	Command. Possible/ expected values: 3DS_AUTHENTICATION
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 reference for a specific request. Example: XYZ9239-yu898
language Alpha Max: 2	The checkout page and messages language. Possible/ expected values: en/ ar
threeds_id Alphanumeric Max: 100	The 3ds operations unique reference. Example: 153606397100001061
3ds_enrolled Alpha Max: 1	Parameter that hold if the card is enrolled or not. Possible/ expected values: - Y (Yes) - N (No)
3ds_status Alpha Max: 1	The status of the 3ds check just like 3-DSEnrolled but this parameter is available after a check is completed. Possible/ expected values: - Y - N - U - A
3ds_eci Numeric Max: 2	The eCommerce indicator returned from the MPI. Possible/ expected values: - 05 - 06
ver_type Alphanumeric Max: 3	The type of verification used for 3DS. Possible/ expected values: - 3DS - SPA
ver_token Alphanumeric Max: 28	Verification token generated by the issuer to prove that the cardholders has been authenticated. Example: gIGCg4SFhoeIiYqLjI2Oj5CRkpM=
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. Example: Insufficient Funds
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: 44000
status Numeric max: 2	A two-digit numeric value that indicates the status of the transaction Possible/ expected values: (Please refer to section statuses).

3D Secure Authentication Response on Cybersource/ MPGS Processors Example!

Was this helpful? Yes No

Protect Service

Offer your customers an essential layer of fraud protection by enabling our standard fraud protection service on your merchant account. It’s called Protect.

Protect is an anti-fraud service that uses predefined rules to evaluate transactions and to flag transactions that may potentially be fraudulent. Protect can be used for both authorization and purchase operations. Protect must be activated by the Amazon Payment Services team.

Protect - Request and Response

Include the following parameter in the request you will send to Amazon Payment Services, and the same parameter will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
customer_ip Alphanumeric Mandatory max: 45	Refers to the customer’s IP Geolocation. *We support IPv4 and IPv6 as shown in the example below. Example: 192.178.1.10 Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf Special characters: . :

Protect Plus Service

For maximum anti-fraud capabilities, you should consider activating our advanced fraud protection service, called Protect Plus.

Protect Plus uses intelligent, real-time analysis that uses machine learning models to detect fraudulent activity.

Protect Plus - Request

Include the following parameters in the Request you will send to Amazon Payment Services:

ATTRIBUTES	Description
customer_type Alpha Optional max: 1	This parameter is required if any customer detail is present. Example: B
customer_id Alphanumeric Optional max: 16	The Customer’s ID/ account number. Example: Au8vJ9HxLo Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
customer_first_name Alpha Optional max: 30	The Customer’s first name. Example: Osama Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
customer_middle_initial Alpha Optional max: 1	The Customer’s middle name’s initial. Example: M Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
customer_last_name Alpha Optional max: 30	The Customer’s last name. Example: Kamal Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
customer_address1 Alphanumeric Optional max: 30	The Customer/ Billing address line 1. Example: Amman - Khalda Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
customer_address2 Alphanumeric Optional max: 30	The Customer/ Billing address line 2 (for extra details). Example: Al Sati St. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
customer_apartment_no Alphanumeric Optional max: 30	The Customer/ Billing apartment number. Example: 12 Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
customer_city Alphanumeric Optional max: 20	The Customer/ Billing city. Example: Amman Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
customer_state Alpha Optional max: 10	The Customer/ Billing state code. Example: Jordan
customer_zip_code Alphanumeric Optional max: 9	The Customer/ Billing post/ zip code. Example: 11183 Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
customer_country_code Alpha Optional max: 3	The Customer’s country code; ISO 3-digit country code. Example: JOR
customer_phone Numeric Optional max: 19	The Customer’s home phone number. Example: 00962797219966
customer_alt_phone Numeric Optional max: 19	The Customer’s alternative phone. * For the Telecommunications sector, send: MSISDN. Example: 00962797256645
customer_date_birth Alphanumeric Optional max: 10	The Customer’s date of birth. Format: YYYY-MM- DD. Example: 1977-10-03 Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
ship_type Alpha Optional max: 1	Shipping details present flag. * This parameter is not applicable for the Gaming sector. Example: S
ship_first_name Alpha Optional max: 30	Ship to first name. * This parameter is not applicable for the Gaming sector. Example: Rana Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
ship_middle_name Alpha Optional max: 1	Ship to middle initial. * This parameter is not applicable for the Gaming sector. Example: A Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
ship_last_name Alpha Optional max: 30	Ship to last name. * This parameter is not applicable for the Gaming sector. Example: Rashdan Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
ship_address1 Alphanumeric Optional max: 30	Ship to address line 1. * This parameter is not applicable for the Gaming sector. Example: Cairo - Egypt Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ , Space
ship_address2 Alphanumeric Optional max: 30	Ship to address line 2. * This parameter is not applicable for the Gaming sector. Example: Garden City Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ , Space
ship_apartment_no Alphanumeric Optional max: 30	Ship to appartment number. * This parameter is not applicable for the Gaming sector. Example: 22 Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
ship_address_city Alphanumeric Optional max: 20	Ship to address city. * This parameter is not applicable for the Gaming sector. Example: Dubai Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
ship_address_state Alpha Optional max: 3	Ship to address state. * This parameter is not applicable for the Gaming sector. Example: UAE
ship_zip_code Alphanumeric Optional max: 9	Ship to post/ zip code. * This parameter is not applicable for the Gaming sector. Example: 11183
ship_country_code Alpha Optional max: 3	Ship to country code; ISO 3-Digit country code. * This parameter is not applicable for the Gaming sector. Example: JOR
ship_phone Numeric Optional max: 19	Ship to home phone number. * This parameter is not applicable for the Gaming sector. Example: 0096265534256
ship_alt_phone Numeric Optional max: 12	Ship To alternative phone. * This parameter is not applicable for the Gaming sector. Example: 0797334465
ship_email Alphanumeric Optional max: 254	Ship to email address. * For the Gaming sector, send: Player Email Address. Example: ship@gmail.com Special characters: @ - . _ Space
ship_comments Alphanumeric Optional max: 160	Any shipping comments. * For the Gaming sector, send: Player Email Address. Example: (Any shipping comments can be entered) Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
ship_method Alpha Optional max: 1	The shipping method. * This parameter is not applicable for the Gaming sector. Possible/ expected values: - N (Next Day Service) - T (Two-Day Service) - W (Three- Day Service) - C (Low-Cost Carrier) - D (Customer Choice) - I (International) - M (Military) - P (Collect at Store) - O (Other)
fraud_extra1 Alphanumeric Optional max: 256	If the sector is Retail, Gaming, Travel, or Telecommunications, then the field value must contain the “Concatenated Billing Address”. * For the Gaming sector, send: Player Email Address. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra2 Alphanumeric Optional max: 256	If the sector is Retail, Travel, or Telecommunications, the value of the field must be the “Concatenated Shipping Address” as follows: street + + shipzip if the address is particularly long and space is lim ited then truncate the first portion of the address and send the postcode/Zip code in full. * This parameter is not applicable for the Gaming sector. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra3 Alphanumeric Optional max: 256	If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the “Address Verification (PayPal)”. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra4 Alphanumeric Optional max: 256	If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the “Account Status (PayPal)”. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra5 Alphanumeric Optional max: 256	If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the “Eligibility Status (PayPal)”. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra6 Alphanumeric Optional max: 256	If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the “Outstanding Balance on the Account (PayPal)”. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra7 Alphanumeric Optional max: 256	If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the “Credit Score (PayPal)”. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra8 Alphanumeric Optional max: 256	If the sector is Telecommunications, the value must be the “Account Number” (if multiple MSISDN per account). Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra9 Alphanumeric Optional max: 265	If the sector is Telecommunications, the value must be the “MSISDN Age in days”. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra10 Alphanumeric Optional max: 256	- If the sector is Travel, the value must be the “Full Travel Itinerary”. - If the sector is Telecommunications, the value must be the “Earliest Account Activity/ First Call Date”. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra11 Alphanumeric Optional max: 30	If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the “Account Age”. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra12 Alphanumeric Optional max: 30	If the sector is Retail, Travel, or Telecommunications, the value must be the “Number of Previous Orders Sent to the Shipping Address”. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra13 Alphanumeric Optional max: 30	If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the “Number of Days Since the Email Attached to the Account has Changed”. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra14 Alphanumeric Optional max: 30	If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the “Number of Days Since the Password was Changed”. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra16 Alphanumeric Optional max: 30	If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the “Number of Previous Orders Associated with the Card and Email”. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra17 Alphanumeric Optional max: 30	If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the “Event/ Promotion Flag”. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra18 Alphanumeric Optional max: 30	- If the sector is Retail, Gaming, or Telecommunications, the value must be the “Sales Channel”. - If the sector is Travel, the value must be the “Third Party Booking Flag, Yes or No”. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra19 Alphanumeric Optional max: 30	- If the sector is Retail, Travel, or Telecommunications, the value must be the “Private/ Business/ Trade” (customerType). - If the sector is Gaming, the value must be the “Customer Gaming ID”. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra20 Alphanumeric Optional max: 30	- If the sector is Retail, Gaming, or Telecommunications, the value must be the “Number of Previous Successful Transactions”. - If the sector is Travel, the value must be the “Number of Previous Successful Bookings”. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra21 Alphanumeric Optional max: 30	- If the sector is Gaming, the values must be the “Gift for Other Player Flag”. - If the sector is Travel, the value must be the “Booking Type”. - If the sector is Telecommunications, the value must be the “Payment Type”. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra22 Alphanumeric Optional max: 30	- If the sector is Gaming, the values must be the “Playing Time”. - If the sector is Travel, the value must be the “Time to First Departure in Hours”. - If the sector is Telecommunications, the value must be the “Number of Previous Successful Top-ups”. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra23 Alphanumeric Optional max: 30	If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the “Channel (IVR vs. Web vs. Mobile Application, etc.). Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra24 Alphanumeric Optional max: 30	- If the sector is Gaming, the values must be the "Premium Account Balance”. - If the sector is Travel, the value must be the “Loyalty Scheme”. - If the sector is Telecommunications, the value must be the “Sim IMSI (International Mobile Subscriber Identity)”. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
fraud_extra25 Alphanumeric Optional max: 30	- If the sector is Gaming, the values must be the “Game Account Balance”. - If the sector is Travel, the value must be the “Loyalty Scheme Member Number”. - If the sector is Telecommunications, the value must be the “IMEI (International Mobile Equipment Identity)”. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
cart_details Alphanumeric Optional max: 999	This parameter is a parent parameter for other parameters that contain the details of the shopping cart created by the Merchant. Example: (Please refer to section Cart Details Example Value Special characters: $
device_fingerprint Alphanumeric max: 4000	Unique device ID generated by Script. please refer to Fraud Native Mobile SDK Guide to generate device fingerprint. Example: 04003hQUMXGB0po… Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ % + ! Space

Protect Plus - Request

Include the following parameters in the Request you will send to Amazon Payment Services:

ATTRIBUTES	Description
item_quantity Alphanumeric Optional max: 10	The item’s quantity. * For the Gaming sector, send: Clan. Example: 4
item_sku Alphanumeric Optional max: 12	The item’s commodity or “Stock Keeping Unit” code. * For the Gaming sector, send: Gold balance. Example: 1ShirtBlueM Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
item_prod_code Alphanumeric Optional max: 12	The item’s product code. * For the Gaming sector, send: Silver balance. Example: MOB111 Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
item_part_no Alphanumeric Optional max: 30	The item’s Manufacturers Part or EAN number. * For the Gaming sector, send: Exp balance. * For the Travel sector, send: Flight/ Train/ Bus Number. Example: TSR-1002 Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
item_description Alphanumeric Optional max: 256	The item’s description. * For the Gaming sector, send: Date of first credit. * For the Travel sector, send: Ticket Delivery Method. Example: iPhone 6-S Special characters: - _ `'` , . Space
item_price Numeric Optional max: 10	The item’s unit price (lowest denomination). * For the Travel sector, send: Ticket Price. Example: 700
item_shipping_no Alphanumeric Optional max: 19	The item’s shipping/ tracking number. * For the Travel sector, send: Ticket Departure Date And Time. Example: AB586985609GB Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
item_shipping_method Alpha Optional max: 1	The item’s shipping method. * For the Retail, Travel, Telecommunications sectors, send: New Shipping Address Flag. * This parameter is not applicable for the Gaming sector. Possible/ expected values: - N (Next Day Service) - T (Two-Day Service) - W (Three- Day Service) - C (Low-Cost Carrier) - D (Customer Choice) - I (International) - M (Military) - P (Collect at Store) - O (Other)
item_shipping_comments Alphanumeric Optional max: 160	The item’s shipping comments. * For the Travel sector, send: Ticket Itinerary. Example: (Any shipping comments can be entered). Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
item_gift_msg Alphanumeric Optional max: 160	The item’s gift message. * For the Retail and Telecommunications sectors, send: High Risk Product Flag. Example: Congrats! Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
rcpt_title Alphanumeric Optional max: 5	The Recipient’s title. * For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available. * For the Travel sector, send: Adult/Child/Infant flag. Example: Mr. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
rcpt_first_name Alphanumeric Optional max: 30	The Recipient’s first name. * For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available. * For the Travel sector, send: Passenger First Name. Example: Mohammad Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
rcpt_middle_initial Alphanumeric Optional max: 1	The Recipient’s middle initial. * For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available. * For the Travel sector, send: Passenger Middle Initial. Example: R Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
rcpt_last_name Alphanumeric Optional max: 30	The Recipient’s last name. * For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available. * For the Travel sector, send: Passenger Last Name. Example: Tawfeeq Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
rcpt_apartment_no Alphanumeric Optional max: 30	The Recipient’s apartment number. * For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available. * For the Travel sector, send: Travel Class; i.e.: Standard/ Economy etc. Example: 12 Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
rcpt_address1 Alphanumeric Optional max: 30	The Recipient’s address line 1. * For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available. * For the Travel sector, send: Departure Airport/ Station Code/ City. Example: Amman - Khalda Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
rcpt_address2 Alphanumeric Optional max: 30	The Recipient’s address line 2 (for extra details). * For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available. * For the Travel sector, send: Arrival Airport/ Station Code/ City. Example: Al Sati St. Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
rcpt_city Alphanumeric Optional max: 30	The Recipient’s city. * For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available. * For the Travel sector, send: Booking Type. Example: Sharjah Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
rcpt_state Alphanumeric Optional max: 10	The Recipient’s state. * For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available. * For the Travel sector, send: Departure Country 3 Digit ISO Code. Example: Qatar Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
rcpt_zip_code Alphanumeric Optional max: 10	The Recipient’s post/ zip code. * For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available. * For the Travel sector, send: Ticket Type; i.e.: One Way/ Return etc. Example: 11183 Special characters: @ - . _ `'` / # \ : = ? & ; ( ) $ Space
rcpt_country_code Alpha Optional max: 3	The Recipient’s country code; ISO 3-Digit country code. * For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available. * For the Travel sector, send: Arrival Country. Example: JOR
rcpt_phone Numeric Optional max: 19	The Recipient’s phone number. * For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available. Example: 00962797675543
rcpt_email Alphanumeric Optional max: 45	The Recipient’s email address. * For the Retail and Telecommunications sectors, this parameter should be sent if multiple shipping addresses are available. * For the Travel sector, send: Passenger Name Record. Example: recipient@hotmail.com Special characters: @ - . _ Space

Protect Plus - Response

The following parameter will be returned in the Response:

ATTRIBUTES	Description
fraud_comment Alphanumeric max: 1000	“fraud_comment” this value represents the feedback of the agent reviewing “in review” transaction. This parameter is part of the Authorization/ Purchase response parameters returned on the notification URL after the In review transaction is updated. Example: Close

Cart Details Example Value

The following is an example value of the “cart_details”:

Device fingerprint script

Device finger script is the module used to generate the device fingerprint (information collected about a remote computing device for the purpose of identification). For web checkout, use the following JS file to generate the device fingerprint.

For Mobile checkout, you can find the SDK to generate the device fingerprint in the following links

Android : https://github.com/iovation/deviceprint-SDK-Android

IOS : https://github.com/iovation/deviceprint-SDK-iOS

The generated value must be sent in the parameter “device_fingerprint” in the operation MOBILE SDK or Merchant Page operations for mobile and desktop respectively.

The Amazon Payment Services gateway will pass the value received to Red Fraud Services to enhance the transactions’ fraud monitoring and apply the configured rules with respect to device fingerprint.

Was this helpful? Yes No

Digital wallets

Digital wallets offer shoppers a more convenient way to manage the payment cards that they carry in their wallets every day. Amazon Payment Services supports three popular digital wallets: Apple Pay, STCPAY, and Visa Checkout.

Visa Checkout Service

Very similar to Masterpass, Visa Checkout is a digital wallet that securely stores your customer’s credit card details and shipping addresses. It speeds up the checkout process across thousands of online shopping websites because your customer no longer needs to retype their credit card number every time that they shop.

Visa Checkout can be offered through two different integrations:

Merchant Hosted Checkout Button.
Amazon Payment Services Hosted Checkout Button.

Merchant Hosted Checkout Button

This integration allows you to host Visa Checkout button on your website giving you maximum control over the look and feel and user experience. The following steps describe how this integration works:

1. You include the following JavaScript in the HTML header of its checkout page. This JavaScript loads the Visa Checkout library and defines handlers to initialization and payment events.

<head>
<script type=“text/javascript”>
function onVisaCheckoutReady() {
V.init({
apikey : “#API_KEY#”, // This will be provided by Amazon Payment Services
externalProfileId : “#PROFILE_NAME#”, // This will be provided by Amazon Payment Services
settings : {
locale : “en_AE”,
countryCode : “AE”, // depends on ISO-3166-1 alpha-2 standard codes
review : {
message : “Merchant defined message”, //
buttonAction : “Continue” // The button label
},
threeDSSetup : {
threeDSActive : “false” // true to enable the 3ds false to disable it
}
},
paymentRequest : {
currencyCode : “USD”, //depends on ISO 4217 standard alpha-3 code values
subtotal : “10.00”, // Subtotal of the payment.
}
});
V.on(“payment.success”, function(payment) {
document.write(JSON.stringify(payment)); // response when received success operation
});
V.on(“payment.cancel”, function(payment) {
document.write(JSON.stringify(payment)); // response when cancel operation
});
V.on(“payment.error”, function(payment, error) {
document.write(JSON.stringify(payment));// response when received error operation
document.write(error);
});
}
</script>
</head>

2. Amazon Payment Services use the following class to render Visa Checkout button that your customer clicks to initiate a payment.

Use the following URLs for test and production environments:

Test Environment URL:

https://sandbox.secure.checkout.visa.com/wallet-services-web/xo/button.png

Production Environment URL:

https://secure.checkout.visa.com/wallet-services-web/xo/button.png

3. You need to use the following JavaScript to control the operation on Visa Checkout on the website.

Use the following URLs for test and production environments:

Test Environment URL:

https://sandbox-assets.secure.checkout.visa.com/checkout-widget/resources/js/integration/v1/sdk.js

Production Environment URL:

https://assets.secure.checkout.visa.com/checkout-widget/resources/js/integration/v1/sdk.js

4. After completing the previous steps, your customer clicks on the Visa Checkout button, the Visa Checkout light box appears and your customer completes the checkout process.

5. You will receive a success response. The response associated with the payment success event returns a list of parameters. You must collect the value of “call_id” parameter to be used in the following step.

6. You submit the Purchase request to Amazon Payment Services adding two extra parameters: digital-wallet, call_id. Please refer to Merchant Hosted Visa Checkout - Request for more details.

7. Your system receives the Amazon Payment Services purchase request and then uses Visa Checkout update image pixel. Below you can find an example of how to use Visa Checkout update image pixel. Please refer to “Visa checkout Amazon Payment Services documentation” for more details.

The following example shows an HTML web page that loads the Visa Checkout library, defines handlers for initialization and payment events, and creates a Visa Checkout button:

<html>
<head>
<script type=“text/javascript”>
function onVisaCheckoutReady() {
V.init({
apikey : “#API_KEY#”, // This will be provided by Amazon Payment Services
externalProfileId : “#PROFILE_NAME#”, // This will be provided by Amazon Payment Services
settings : {
locale : “en_AE”,
countryCode : “AE”, // depends on ISO-3166-1 alpha-2 standard codes
review : {
message : “Merchant defined message”, //
buttonAction : “Continue” // The button label
},
threeDSSetup : {
threeDSActive : “false” // true to enable the 3ds false to disable it
}
},
paymentRequest : {
currencyCode : “USD”, //depends on ISO 4217 standard alpha-3 code values
subtotal : “10.00”, // Subtotal of the payment.
}
});
V.on(“payment.success”, function(payment) {
document.write(JSON.stringify(payment)); // response when received success operation
});
V.on(“payment.cancel”, function(payment) {
document.write(JSON.stringify(payment)); // response when cancel operation
});
V.on(“payment.error”, function(payment, error) {
document.write(JSON.stringify(payment));// response when received error operation
document.write(error);
});
}
</script>
</head>
<body>
<img alt=“Visa Checkout” class=“v-button” role=“button"src="https://sandbox.secure.checkout.visa.com/wallet-services-web/xo/button.png?cardBrands=VISA,MASTERCARD,DISCOVER,AMEX” />
<script type=“text/javascript” src=“https://sandbox-assets.secure.checkout.visa.com/checkout-widget/resources/js/integration/v1/sdk.js”>
</script>
</body>
</html>

Merchant Hosted Visa Checkout - Request

Include the following the parameters to the Merchant page operation - Request parameters.

ATTRIBUTES	Description
digital_wallet Alpha Mandatory max: 100	The buyer’s digital wallet. Possible/ expected values: VISA_CHECKOUT Special characters: _
call_id Alphanumeric Mandatory max: 100	Visa Checkout transaction ID, returned by Visa Checkout light box response as “callId” parameter. Example: 3000545511479392001

Merchant Hosted Visa Checkout - Response

The following parameters will be returned in Amazon Payment Services’ response in additional to the Merchant page operation - Response parameters:

ATTRIBUTES	Description
digital_wallet Alpha max: 100	The buyer’s digital wallet. Possible/ expected values: VISA_CHECKOUT
call_id Alphanumeric max: 100	Visa Checkout transaction ID, returned by Visa Checkout light box response as “callId” parameter. Example: 3000545511479392001

Amazon Payment Services Hosted Checkout Button

This integration allows you to offer Visa Checkout using a checkout button hosted by Amazon Payment Services. The following steps describe how this integration works:
1. Your customer clicks on the pay button on your checkout page.
2. You Merchant submits an authorization or purchase request and include one extra parameter: digital_wallet. (Please refer to Amazon Payment Services Hosted Visa Checkout - Request for more details).
3. Your customer is redirected to a page hosted on Amazon Payment Services where the Visa Checkout light-box page is displayed.

4. Your customer enters their credentials and completes the Visa Checkout process.
5. Amazon Payment Services processes the transaction and returns a valid response back to you.

Amazon Payment Services Hosted Visa Checkout - Request

Include the following parameter to the redirection request parameters (Please refer to Authorization/ Purchase – Request section)

ATTRIBUTES	Description
digital_wallet Alpha Mandatory max: 100	The buyer’s digital wallet. Possible/ expected values: VISA_CHECKOUT Special characters: _

Amazon Payment Services Hosted Visa Checkout - Response

The following parameters will be returned in Amazon Payment Services’ response in additional to the Authorization/ Purchase – Response parameters:

ATTRIBUTES	Description
digital_wallet Alpha Mandatory max: 100	The buyer’s digital wallet. Possible/ expected values: VISA_CHECKOUT

Was this helpful? Yes No

STCPAY

STC Pay is a mobile wallet used to pay your day to day expenses, it is a local payment option which is supported in KSA.

To complete a payment, the customer can check out using the phone number , and the OTP is received as an SMS.

Supported Channels

You can integrate STC Pay through the following options:

Redirection: Means you will redirect your customer to a payment page hosted on the Amazon Payment Services to submit their payment details and completes the payment then redirects the customer to your website.

Merchant page: For a smoother payment experience you can choose to integrate STC Pay checkout into your website. Means your customer will complete the payment inside your website without redirection( Integrating it directly into your checkout page).

STCPAY And Tokenization

Tokenization is supported with the two channels “Redirection” , “Merchant Page”.

By using Tokenization, your customer does not need to enter their phone number to proceed with checkout. Instead, your customer’s phone number will be displayed in a masked format on the checkout screen.
Its also removes the requirement to verify transactions with an OTP because using a token name with STC Pay implies a downgraded transaction.

Tokenization work flow:

1- The customer should complete the first payment through STCPAY successfully which will always be protected by requesting an OTP.
as well activation the tokenization in the customer STC Pay app is mandatory.

2- In the second payment for the customer , the saved phone number will be listed in the checkout page in order to proceed with the payment directly without submitting the OTP number.

Please refer to the sections below for more technical details:
Redirection checkout flow using a token
Merchant page integration checkout flow using a token

Checkout Workflows

Redirection checkout using a one-time PIN

When your customer is ready to pay, your website redirects your customer to the Amazon Payment Services payment page. Your customer completes their payment details on the Amazon Payment Services in a two-step process.

First, your customer enters their phone number on the Amazon Payment Services payment page. That generates an STC Pay OTP code, which is sent to your customer via SMS.
On the next screen, your customer enters the OTP to complete the payment. Your customer is then redirected back to your website.

Redirection checkout flow using a token

1- For the first customer payment, You need to process the APi request STCPAY Redirection ,if the payment simulated successfully with submitting a proper customer OTP, as well the tokenization is active in the customer STC Pay app then we will return in the response an extra parameter called “token_name”.
2- For the next customer payment ,Your customer simply needs to select their masked phone number to complete the transaction in a single step. You should include the token_name received from the first checkout in your STCPAY Redirection.

Merchant page integration checkout flow using a one-time PIN

When you choose to build your own payment page and you do not use a token, you need to process a payment in two steps:

Generate OTP: First, your server needs to send a request to the Amazon Payment Services server in order to generate an OTP for the customer. In this request you include your customer’s phone number. Amazon Payment Services generates an OTP based on this number. The OTP is sent to your customer’s mobile phone by SMS and your customer enters the OTP on your checkout page.
Purchase: Next, once the OTP is validated, you send a purchase request to Amazon Payment Services to complete the payment. You need to include the same merchant reference number that you use to request the OTP.

Merchant page integration checkout flow using a token

When you build your own payment page and your customer completes a payment using a token, you only need to build one step into your checkout process.

Purchase: Because the OTP has already been validated, you can simply send a purchase request to Amazon Payment Services to complete the payment. It enables your customer to complete their purchase while skipping the OTP process.

NOTE: You need to perform OTP workflow at least once to generate a token before you can process a payment without the OTP

STCPAY Redirection

Redirection URLs

Test Environment URL:

Test URL: https://sbcheckout.payfort.com/FortAPI/paymentPage

Production Environment URL:

Production URL: https://checkout.payfort.com/FortAPI/paymentPage

Parameters Submission Type

HTTPs Form Post Request.

Purchase - Request

Include the following parameters in the request you will send to Amazon Payment Services:

ATTRIBUTES	Description
command Alpha Mandatory Max: 20	A command. Possible/ expected values: PURCHASE
access_code Alphanumeric Mandatory Max: 20	Access code. Example: zx0IPmPy5jp1vAz8Kpg7
digital_wallet Alpha Mandatory Max: 20	Digital wallet used for transaction. Possible/ expected values: STCPAY
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 check the note after this table. Example: 10000
currency Alpha Mandatory Max: 3	The currency of the transaction’s amount in ISO code 3. Possible/ expected values: SAR
token_name Alphanumeric Optional Max: 100	The Token received from the Tokenization process. Example: Op9Vmp Special characters: . @ - _
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: _ - . @ +
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: . :
signature Alphanumeric Mandatory Max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
order_description Alphanumeric Optional Max: 150	It holds the description of the order. Example: iPhone 6-S Special characters: `'` / . _ - # : $ Space
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: . ; / _ - , `'` @
remember_me Alpha Optional Max: 2	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
payment_option Alpha Optional Max: 10	Payment option. Possible/ expected values: STCPAY
phone_number Alphanumeric Optional max: 19	The customer’s phone number.
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 that will be displayed to the customer when the order is processed. Example: https://www.merchant.com Special characters: $ ! = ? # & - _ / : .

Redirection - Response

The following parameters will be returned in PayFort’s Response:

ATTRIBUTES	Description
command Alpha Max: 20	A command. Possible/ expected values: PURCHASE
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
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
access_code Alphanumeric Max: 20	Access code. Example: zx0IPmPy5jp1vAz8Kpg7
digital_wallet Alpha Max: 20	Digital wallet used for transaction. Possible/ expected values: STCPAY
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. Possible/ expected values: SAR
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
signature Alphanumeric Max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
eci Alpha Max: 16	Ecommerce indicator. Possible/ expected values: ECOMMERCE
payment_option Alpha Max: 10	Payment option. Possible/ expected values: STCPAY
fort_id Numeric Max: 20	The order’s unique reference returned by our system. Example: 149295435400084008
status Numeric Max: 2	A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses
token_name Alphanumeric max: 100	The Token received from the Tokenization process. Example: COp9Vmp
order_description Alphanumeric Max: 150	A description of the order. Example: iPhone 6-S
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
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. It will be returned if it is shared in request.
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

Redirection Sample request

STCPAY Merchant Page

Generate OTP URLs

Test Environment URL:

Test URL: https://sbpaymentservices.payfort.com/FortAPI/paymentApi

Production Environment URL:

Production URL: https://paymentservices.payfort.com/FortAPI/paymentApi

Parameters Submission Type

REST POST request using JSON.

Generate OTP - Request

Include the following parameters in the request you will send to Amazon Payment Services:

ATTRIBUTES	Description
service_command Alpha Mandatory Max: 20	Command. Possible/ expected values: GENERATE_OTP
access_code Alphanumeric Mandatory Max: 20	Access code. Example: zx0IPmPy5jp1vAz8Kpg7
amount Numeric Mandatory Max: 10	The transaction amount to generate the OTP, this amount must also be used for the purchase transaction. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount check the note after this table. Example: 10000
digital_wallet Alpha Mandatory Max: 20	Digital wallet used for transaction. Possible/ expected values: STCPAY
signature Alphanumeric Mandatory Max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
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. Possible/ expected values: SAR
language Alpha Mandatory Max: 2	The checkout page and messages language. Possible/ expected values: en/ ar
phone_number Alphanumeric Mandatory max: 19	The customer’s phone number. Example: 0548220713 Special characters: + - ( ) Space

Generate OTP - Response

The following parameters will be returned in PayFort’s Response:

ATTRIBUTES	Description
service_command Alpha Max: 20	A command. Possible/ expected values: GENERATE_OTP
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
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
access_code Alphanumeric Max: 20	Access code. Example: zx0IPmPy5jp1vAz8Kpg7
amount Numeric Max: 10	The transaction’s amount. Example: 10000
signature Alphanumeric Max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
merchant_identifier Alphanumeric Max: 20	The ID of the Merchant. Example: CycHZxVj
digital_wallet Alpha Max: 20	Digital wallet used for transaction. Possible/ expected values: STCPAY
merchant_reference Alphanumeric Max: 40	The Merchant’s unique order number. Example: XYZ9239-yu898
currency Alpha Max: 3	The currency of the transaction’s amount in ISO code 3. Possible/ expected values: SAR
language Alpha Max: 2	The checkout page and messages language. Possible/ expected values: en/ ar
phone_number Alphanumeric max: 19	The customer’s phone number. Example: 0548220713

Generate OTP Sample Request

Purchase URLs

Test Environment URL:

Test URL: https://sbpaymentservices.payfort.com/FortAPI/paymentApi

Production Environment URL:

Production URL: https://paymentservices.payfort.com/FortAPI/paymentApi

Parameters Submission Type

REST POST request using JSON.

Purchase - Request

Include the following parameters in the request you will send to Amazon Payment Services:

ATTRIBUTES	Description
command Alpha Mandatory Max: 20	A command. Possible/ expected values: PURCHASE
access_code Alphanumeric Mandatory Max: 20	Access code. Example: zx0IPmPy5jp1vAz8Kpg7
digital_wallet Alpha Mandatory Max: 20	Digital wallet used for transaction. Possible/ expected values: STCPAY
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. This needs to be the same as the amount supplied when generating the OTP. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount check the note after this table. Example: 10000
currency Alpha Mandatory Max: 3	The currency of the transaction’s amount in ISO code 3. Possible or Expected Values: SAR
token_name Alphanumeric Optional Max: 100	The Token received from the Tokenization process. Example: Op9Vmp Special characters: . @ - _
otp Numeric Mandatory Max: 10	OTP sent to your customer’s phone number. Example: 1234
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: _ - . @ +
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: . :
signature Alphanumeric Mandatory Max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
order_description Alphanumeric Optional Max: 150	It holds the description of the order. Example: iPhone 6-S Special characters: `'` / . _ - # : $ Space
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: . ; / _ - , `'` @

Purchase - Response

The following parameters will be returned in PayFort’s Response:

ATTRIBUTES	Description
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
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
access_code Alphanumeric Max: 20	Access code. Example: zx0IPmPy5jp1vAz8Kpg7
command Alpha Max: 20	A command. Possible/ expected values: PURCHASE
digital_wallet Alpha Max: 20	Digital wallet used for transaction. Possible/ expected values: STCPAY
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. Possible or Expected Values: SAR
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
signature Alphanumeric Mandatory Max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
eci Alpha Max: 16	Ecommerce indicator. Possible/ expected values: ECOMMERCE
payment_option Alpha Max: 10	Payment option. Possible/ expected values: STCPAY
fort_id Numeric Max: 20	The order’s unique reference returned by our system. Example: 149295435400084008
status Numeric Max: 2	A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses
token_name Alphanumeric max: 100	The Token received from the Tokenization process. Example: COp9Vmp
order_description Alphanumeric Max: 150	A description of the order. Example: iPhone 6-S
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

Purchase Sample Request

Collect Service (Invoicing)

You can send your customers an invoice that includes a convenient payment link using the invoice generating capabilities of Amazon Payment Services. We call this service Collect. When your customer clicks on the payment link they can conveniently pay for the invoiced amount using the currency and payment method that they prefer.

The payment link included in the invoice is directly connected to your merchant account so that your customer’s payment is simply and efficiently processed by Amazon Payment Services.

You have two options for collect service:
1. Using the backoffice.
2. Using our APIs.

Collect Service - Backoffice

If you need to integrate collect ( Invoicing service) manually from the back-office, you need follow the below steps to start testing the payments and generating invoices and simulate the process:

Login to Sandbox account and Go to the Account Profile tab
Add the Terms and Conditions URLs in the fields “English terms and conditions” & “Arabic terms and conditions” in the back-office account under General Information Tab
Save the settings
Go to invoices Management Tab and click on Generate New Invoice
Generate invoices by filling the mandatory fields which are Merchant Reference, Customer Email , Amount, Expiry date, and Currency
Please check below the explanations for the fields.

The invoice will be sent to the customer as Email,SMS based on your notification type selection.

The invoice can be tested on sandbox environment using our Testing Cards

ATTRIBUTES	Description
Invoice Number Alphanumeric Optional max: 40	The invoice number. Example: InvoiceAPS-0123
Merchant Reference Alphanumeric Mandatory max: 40	A unique order number. Example: APSInvoiceTransaction01
Customer Email Alphanumeric Mandatory max: 254	The customer’s email. Example: customer@domain.com 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: 100 USD=1.00 USD
Notification Type Optional	The notification type the customer recieves Example: SMS/Email
Expiry Date Calendar Mandatory max: 25	The invoice link expiry date. Example: 2017-12-20T15:36:55+03:00 Special characters: + : -
Payment Option Drop down Optional	The payment option Possible/ expected values: VISA/MasterCard/MADA/AMEX
Order Description Alphanumeric Optional max: 150	It holds the description of the order. Example: iPhone 6-S Special characters: `'` / . _ - # : $ Space
Customer Name Alpha Optional max: 40	The customer’s name. Example: John Smith Special characters: _ \ / - . `'` Space
Language Drop down Optional	The invoice and the received messages language. Possible/ expected values: English / Arabic
Mobile Number Numeric Optional max: 19	The Customer mobile number. It’s mandatory when selecting SMS as notification type. Example: 00962797219966

Collect Service API

Collect Service 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.

Collect Service - Request

Include the following parameters in the Request you will send to Amazon Payment Services:

ATTRIBUTES	Description
service_command Alpha Mandatory max: 20	Command. Possible/ expected values: PAYMENT_LINK 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: - _ .
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: 100 USD=1.00 USD
currency Alpha Mandatory max: 3	The currency of the transaction’s amount in ISO code 3. Example: USD
language Alpha Mandatory max: 2	The invoice and the received messages language. Possible/ expected values: en / ar
customer_email Alphanumeric Mandatory max: 254	The customer’s email. Example: customer@domain.com Special characters: _ - . @ +
request_expiry_date Alphanumeric Mandatory max: 25	The invoice link expiry date. Example: 2017-12-20T15:36:55+03:00 Special characters: + : -
notification_type Alpha Mandatory max: 20	The way the Customer wants to use to get his notification. The Merchant can choose more than one way. * If the Customer chooses NONE with “EMAIL” or “SMS”, then the NONE will be taken as notification type. Possible/ expected values: - SMS - EMAIL - NONE 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
link_command Alphanumeric Optional max: 15	Link operation to be executed. Possible/ expected values: AUTHORIZATION/ PURCHASE. Please refer to this section to know more about the differences.
payment_link_id Alphanumeric Optional max: 20	The ID of the generated Invoice payment link. Example: 148708392700020346 Special characters: - _ .
payment_option Alpha Optional max: 10	Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - SADAD (for Purchase operations only) - NAPS (for Purchase operations only) - KNET(for Purchase operations only) - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only)
order_description Alphanumeric Optional max: 150	It holds the description of the order. Example: iPhone 6-S Special characters: `'` / . _ - # : $ Space
customer_name Alpha Optional max: 40	The customer’s name. Example: John Smith Special characters: _ \ / - . `'` Space
customer_phone Numeric Optional max: 19	The Customer mobile number. It’s mandatory when selecting SMS as notification type. Example: 00962797219966
return_url Alphanumeric Optional max: 400	The URL of the Merchant’s page to be redirected to when the order is processed. Example: https://www.merchant.com Special characters:$ ! = ? # & _ - / : .

Collect Service - Response

The following parameters will be returned in Amazon Payment Services’s response:

ATTRIBUTES	Description
service_command Alpha max: 20	Command. Possible/ expected values: PAYMENT_LINK
access_code Alphanumeric max: 20	Access code. Possible/ expected 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: XYZ2939-yu898
amount Numeric max: 10	The transaction’s amount. Example: 100 USD=1.00 USD
currency Alpha max: 3	The currency of the transaction’s amount in ISO code 3. Example: USD
language Alpha max: 2	The invoice and received messages language. Possible/ expected values: en / ar
customer_email Alphanumeric max: 254	The customer’s email. Example: customer@domain.com
request_expiry_date Alphanumeric max: 25	The invoice link expiry date. Example: 2017-12-20T15:36:55+03:00
notification_type Alpha max: 20	The way the Customer wants to use to get his notification. The Merchant can choose more than one way. *If the Customer chooses NONE with “EMAIL” or “SMS”, then the NONE will be taken as notification type. Possible/ expected values: - SMS - EMAIL - NONE
signature Alphanumeric max: 200	A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
link_command Alphanumeric max: 15	Link operation to be executed. Possible/ expected values: AUTHORIZATION/ PURCHASE. Please refer to this section to know more about the differences.
payment_link_id Alphanumeric max: 20	The ID of the generated Invoice payment link. Example: 148708392700020346
payment_link Alphanumeric max: 150	The generated invoice link notified to the Customer by one of the notification types, used to complete the payment process. Example: https://checkout.payfort.com/dfc3d762
payment_option Alpha max: 10	Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - SADAD (for Purchase operations only) - NAPS (for Purchase operations only) - KNET(for Purchase operations only) - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only)
order_description Alphanumeric max: 150	It holds the description of the order. Example: iPhone 6-S
customer_name Alpha max: 40	The customer’s name. Example: John Smith
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 is made up of five digits, the first 2 digits refer to the request status, and the last 3 digits refer to the request messages. Example: 20064
status Numeric max: 2	A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: statuses
customer_phone Numeric max: 19	The Customer mobile number. Example: 00962797219966
return_url Alphanumeric max: 400	The URL of the Merchant’s page to be redirected to when the order is processed. Example: https://www.merchant.com

After completing the checkout process through the payment link; the following list of parameters will be returned under the “Direct Transaction Feedback”:

ATTRIBUTES	Description
command Alpha Max: 20	A command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences.
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
payment_link_id Alphanumeric max: 20	The ID of the generated Invoice payment link. Example: 148708392700020346
token_name Alphanumeric max: 100	The Token received from the Tokenization process. Example: Op9Vmp
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 - SADAD (for Purchase operations only) - NAPS (for Purchase operations only) - KNET(for Purchase operations only) - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only)
sadad_olp Alphanumeric Max: 12	SADAD Online Payment ID Alias. The merchant sends this value if the OLP ID is collected on the merchant checkout. Example: SABBP2P_UAT2
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. 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
remember_me Alpha Max: 2	This parameter provides you with an indication to whether to save this token for the user based on the user selection. Possible/ expected values: 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

Was this helpful? Yes No

Collect Service - Customization

Amazon Payment link for credit card is fully customizable to match your website’s look and feel.

How it works

From your back-office go to the tab Payment Link Template, Click on Add Payment Link Template , You will find two options for customizing the payment page:
1. Using our back-office live editor.
2. Uploading your own css and html files.

Customization using our back-office live editor

This option allows you to change the following :

Primary color ( in Hexa )
Secondary color ( In Hexa )
Background Color ( In Hexa )

Using HTML and CSS files

If you want to have more control on the payment link design and add more edits , you have two file options to upload:

1. HTML Template:

You can implement and create your own html file that you want to load in the payment link and change the look and feel for the payment link as you wish.

2.CSS Theme :

Develop your CSS file that edit our colors and theme in the payment link here you have to edit our existing CSS classes by inspecting the elements of the payment link , then include your changes on a CSS file.

Batch Service

Amazon Payment Services offers batch processing as an alternative where it is not practical or desirable for you to write code to automate a process on your server. Instead, you can upload a batch file to our server that contains the instructions that you want to execute.

Batch Service API

We support Batch service using our API for the following options below:

1. You’re only allowed to send one of the following transactions in your batch file or a mixture of them:

2. You must activate the batch processing service before attempting to upload a batch file.

* Recurring: PURCHASE command.

Please refer to the following sample

* Maintenance operations (capture, refund, and void authorization): after completing a successful Authorization or Purchase transactions through one of Amazon Payment Services’ channels.

Please refer to the following sample

* Invoicing: PURCHASE command.

Please refer to the following sample

How it works - Steps

1. Upload the batch file:

This request enables you to upload the batch file to Amazon Payment Services.

2. Get Batch Results::
With this request you validate the format of the batch file you uploaded and check that the merchant reference for each and every transaction is unique. After validation the “Account Administrator” will receive an email notification including a count of the invoices successfully sent.

3. Process Batch File:
When you send this request you initiate the processing of transactions. To start the processing you must ensure that the batch file was validated and passed the validation process. After processing the “Account Administrator” will receive an email notification with a count of the invoices sent successfully.

Upload Batch file

This request enables you to upload your batch file to Amazon Payment Services. You specify the order of the fields in the batch file. You will receive a success message (response code: 50000) indicating that the batch file was received successfully by Amazon Payment Services. Amazon Payment Services will then start the validation process on the uploaded file

Upload Batch File URLs

Test Environment URL:

https://sbpaymentservices.payfort.com/FortAPI/upload/

Production Environment URL:

https://paymentservices.payfort.com/FortAPI/upload/

Parameters Submission Type

Host to Host Form Post Request (From the backend)

Upload Batch File - Request

<!DOCTYPE html>
    <body>
        <form method="post" action="" enctype="multipart/form-data">
            <input type="text" name="service_command" value="UPLOAD_BATCH_FILE">
            <input type="text" name="access_code" value="ACCESS CODE">
            <input type="text" name="merchant_identifier" value="MERCHANT IDENTIFIER" >
            <input type="text" name="batch_reference" value="BATCH REFERENCE">
            <input type="text" name="language" value="en">
            <input type="file" name="file">
            <input name="submitButton" type="submit" value="Process request">
        </form>
    </body>
</html>

<?php
// Display errors 
ini_set('display_errors', 1);
ini_set('display_startup_errors', 1);
error_reporting(E_ALL);
// Production Environment URL
$productionUrl  = "https://paymentservices.payfort.com/FortAPI/upload/";
// Test Environment URL
$testUrl        = "https://sbpaymentservices.payfort.com/FortAPI/upload/";

if(isset($_POST['submitButton'])){
// Array data
$arrayData = array(
    'service_command'        => $_POST['service_command'],
    'access_code'            => $_POST['access_code'],
    'merchant_identifier'    => $_POST['merchant_identifier'],
    'batch_reference'        => $_POST['batch_reference'],
    'language'               => $_POST['language'],
    'file'                   => $_FILES['file']['name']
);

// Generate signature and add it to the arrayData
$signature              = calculateSignature($arrayData);
$arrayData['signature'] = $signature;
// file data
$cfile = new CURLFile($_FILES['file']['tmp_name'], $_FILES['file']['type'], $_FILES['file']['name']);
$arrayData['file'] = $cfile;

$ch = curl_init( $testUrl );
curl_setopt($ch, CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type:multipart/form-data"));
curl_setopt( $ch, CURLOPT_POSTFIELDS, $arrayData );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
$result = curl_exec($ch);
curl_close($ch);
// Display the resualt 
echo "<pre>$result</pre>";

}
// this function is for signature calculation
function calculateSignature($arrayData) {
    $shaString = '';
// sort an array by key
    ksort($arrayData);
    foreach ($arrayData as $key => $value) {
        $shaString .= "$key=$value";
    }
// make sure to fill your sha request pass phrase
    $shaString = "YOUR_SHA_REQUEST_PASSPHRASE" . $shaString . "YOUR_SHA_REQUEST_PASSPHRASE";
    $signature = hash("sha256", $shaString);
// your request signature
    return $signature;
}
?>

Include the following parameters in the Request you will send to Amazon Payment Services:

ATTRIBUTES	Description
service_command Alpha Mandatory Max: 20	Command. Possible/ expected values: UPLOAD_BATCH_FILE 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
batch_reference Alphanumeric Mandatory Max: 20	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
file Alphanumeric Mandatory Max: 50	The file that contain a batch of transactions. The file should be of type CSV. Example: test.csv Special characters: . - ! @ # $ % ^ & ( ) _ + , Space
signature Alphanumeric Mandatory Max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a

Upload Batch File - Response

The following parameters will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
service_command Alpha Max: 20	Command. Possible/ expected values: UPLOAD_BATCH_FILE
access_code Alphanumeric Max: 20	Access code. Example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier Alphanumeric Max: 20	The ID of the Merchant. Example: CycHZxVj
batch_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
batch_id Numeric Max: 20	The Merchant’s unique batch ID. Example: 150754364000030895
signature Alphanumeric Mandatory Max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
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: 50000
status Numeric Max: 2	A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses

Get Batch Results

This request enables you to validate the format of your batch file and to check that the merchant reference for each and every transaction is unique. In the response of this request you receive the batch file validation results, which could be any one of: batch validation success, validation done with errors, batch file is still under validation.

Note: Your batch file cannot be processed if the validation status is “the batch file still under validation”.

Get Batch Results URLs

Test Environment URL:

https://sbpaymentservices.payfort.com/FortAPI/batchApi/

Production Environment URL:

https://paymentservices.payfort.com/FortAPI/batchApi/

Parameters Submission Type

REST POST request using JSON.

Get Batch Results - Request

Include the following parameters in the Request you will send to Amazon Payment Services:

ATTRIBUTES	Description
service_command Alpha Mandatory Max: 20	Command. Possible/ expected values: GET_BATCH_RESULTS 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
batch_reference Alphanumeric Mandatory Max: 20	The Merchant’s unique order number. *You have to use the same batch reference you used in the upload_batch_file. 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
batch_id Numeric Optional Max: 20	The Merchant’s unique batch ID returned when uploading a file successfully. Example: 150754364000030895

Get Batch Results - Response

The following parameters will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
service_command Alpha Max: 20	Command. Possible/ expected values: GET_BATCH_RESULTS
access_code Alphanumeric Max: 20	Access code. Example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier Alphanumeric Max: 20	The ID of the Merchant. Example: CycHZxVj
batch_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 Mandatory Max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
batch_id Numeric Max: 20	The Merchant’s unique batch ID. Example: 150754364000030895
transactions_count Numeric Max: 10	A parameter that counts the total number of transactions inside the file. Example: 9
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: 70000
status Numeric Max: 2	A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses

Process Batch file

With this request you initiate the processing of transactions. To start processing, the batch file must be validated and passed the validation successfully regarding less the validation done without/with errors.

Process Batch File URLs

Test Environment URL:

https://sbbatch.payfort.com/integration-batch/batchApi/

Production Environment URL:

https://paymentservices.payfort.com/FortAPI/batchApi/

Parameters Submission Type

REST POST request using JSON.

Process Batch File - Request

Include the following parameters in the Request you will send to Amazon Payment Services:

ATTRIBUTES	Description
service_command Alpha Mandatory Max: 20	Command. Possible/ expected values: PROCESS_BATCH 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
batch_reference Alphanumeric Mandatory Max: 20	The Merchant’s unique order number. *You have to use the same batch reference you used in the upload_batch_file. 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
batch_id Numeric Optional Max: 20	The Merchant’s unique batch ID returned when uploading a file successfully. Example: 150754364000030895

Process Batch File - Response

The following parameters will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
service_command Alpha Max: 20	Command. Possible/ expected values: PROCESS_BATCH
access_code Alphanumeric Max: 20	Access code. Example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier Alphanumeric Max: 20	The ID of the Merchant. Example: CycHZxVj
batch_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 Mandatory Max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
batch_id Numeric Max: 20	The Merchant’s unique batch ID. Example: 150754364000030895
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: 72147
status Numeric Max: 2	A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses

After processing the batch file successfully; you can send “Get Batch Results – Request” again to see the final status for each transaction inside the file.

Get Batch Results - After Processing - Response Example
Line_Number,response_code,response_message,status,eci,fort_id,merchant_reference,
amount,card_number,expiry_date,currency “5”,“14000”,“Success”,“14”,“RECURRING”,“151792390600095202”,“newww33”,“10003”,
“400555******0001”,“2105”,“USD”
“4”,“14000”,“Success”,“14”,“RECURRING”,“151792390600095203”,“newww32”,“10002”,
“400555******0001”,“2105”,“USD”
“10”,“14000”,“Success”,“14”,“RECURRING”,“151792390600095208”,“newww38”,“10008”,
“400555******0001”,“2105”,“USD”
“8”,“14000”,“Success”,“14”,“RECURRING”,“151792390600095204”,“newww36”,“10006”,
“400555******0001”,“2105”,“USD”
“9”,“14000”,“Success”,“14”,“RECURRING”,“151792390600095205”,“newww37”,“10007”,
“400555******0001”,“2105”,“USD”
“2”,“14000”,“Success”,“14”,“RECURRING”,“151792390600095206”,“newww30”,“10000”,
“400555******0001”,“2105”,“USD”
“6”,“14000”,“Success”,“14”,“RECURRING”,“151792390600095201”,“newww34”,“10004”,
“400555******0001”,“2105”,“USD”
“7”,“14000”,“Success”,“14”,“RECURRING”,“151792390600095207”,“newww35”,“10005”,
“400555******0001”,“2105”,“USD”
“3”,“14000”,“Success”,“14”,“RECURRING”,“151792390600095200”,“newww31”,“10001”,
“400555******0001”,“2105”,“USD”

Batch Invoicing

You can bulk-generate invoices and collect payment using our Collect service by simply uploading a batch file for automated invoice generation. You can upload a file containing the invoice data by writing code that uses our batch invoice API. Our API will generate and send the invoices for you.

Batch Invoicing Backoffice

Before starting you have to know the following:
1. You’re only allowed to send the PAYMENT_LINK service command in the invoice batch file.
2. You must activate batch processing and invoicing services in the back office.
3. You can download the invoice batch file template from the back office by clicking on the “Batch invoicing” tab. Note that this tab will appear only if you activated the batch invoicing service.

Please from the back-office go through the below simple manual steps:

Login to your Sandbox account and Go to the Batch Invoicing tab.
Click Download batch template file. “This template will be downloaded as CSV format in your computer”.
Fill the template fields with the correct values according to below table .
Save the file with “.csv” extension and click browse and upload the file to your back-office.
Process the batch file validated by clicking on process button.
The invoices will be created as a bulk and sent to customer either by EMAIL or SMS.
On sandbox environment, the invoices created through Batch service can be tested on sandbox environment using our testing cards mentioned in our API Documentation: https://paymentservices.amazon.com/docs/EN/12.html

Please refer to the following sample For any explanation about the headers/values included in this file , Please refer to the table listed below

ATTRIBUTES	Description
service_command Alpha Mandatory max: 20	Command. Possible/ expected values: PAYMENT_LINK
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: _ - . @ +
request_expiry_date Alphanumeric Mandatory max: 25	The expiry date of invoice, format must be of the following format Example: 20T15:36:55+03:00
link_command Alphanumeric Mandatory Max: 15	Depending on the merchant account and payment stack Possible/ expected values: PURCHASE / AUTHORIZATION
notification_type Alphanumeric Mandatory Max: 20	How will the customer be notified about this invoice. Possible/ expected values:“EMAIL”, “SMS”, “EMAIL,SMS”
customer_phone Alpha Optional Max: 19	The phone of the customer on which they will recieve the SMS format should be 9ccxxxxxxxxx Possible values: 966551234567
cusotmer_name Alpha Mandatory Max: 40	The customer name. Possible/ expected values: Jon Doe
order_description Alphanumeric Optional Max: 150	It holds the description of the order. Example: iPhone 6-S Special characters: `'` / . _ - # : $ Space
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: $ ! = ? # & - _ / : .
payment_link_id Alphanumeric Optional Max: 20	The unique ID of link generated by the merchant for search purpose Example: 123456432
payment_option Alpha Optional Max: 10	What are the payment options the customer can be pay in. Possible/ expected values: - MASTERCARD - VISA - AMEX - MADA - KNET - NAPS

Was this helpful? Yes No

Data-Mine (Reporting API)

Reporting API

Merchants that process large volumes of e-commerce transactions can gain deep insight into transaction performance and behavior by data-mining transaction data thanks to the Amazon Payment Services reporting API. You can specify the columns to be included as well as filters, the report has a query limit of 200,000 transactions.

Report Builder URLs

Test Environment URL:

https://sbpaymentservices.payfort.com/FortAPI/reportingApi

Production Environment URL:

https://paymentservices.payfort.com/FortAPI/reportingApi

Parameters Submission Type

REST POST request using JSON.

How it Works

1. You submit a “Generate report” request. This request allows you to specify the filters and columns included in the downloaded report.
2. Amazon Payment Services returns the “Generate Report” response.
3. You submit a “download report:” request using the same merchant reference used to generate the report.

Generate Report - Request

Include the following parameters in the Request you will send to Amazon Payment Services:

ATTRIBUTES	Description
query_command Alpha Mandatory max: 50	Query operations command. Possible/ expected values: GENERATE_REPORT Special characters: _
access_code Alphanumeric Mandatory max: 20	Merchant account Access Code. Example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier Alphanumeric Mandatory max: 20	Amazon Payment Services Merchant Account identifier. Example: CycHZxVj
merchant_reference Alphanumeric Mandatory max: 40	The Merchant’s unique reference for a specific request. Example: XYZ9239-yu898 Special characters: _ - .
from_date Alphanumeric Mandatory max: 30	Query parameter to filter from a specific date. Example: 2017-01-01T14:36:55+03:00 Special characters: + - :
to_date Alphanumeric Mandatory max: 30	Query parameter to filter the results till a specific date. Example: 2017-06-28T14:36:55+03:00 Special characters: + - :
columns List Mandatory max: 110	The columns you want to appear in your report. Possible/ expected values: (Please refer to section column parameters). 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
language Alpha Optional max: 2	The checkout page and messages language. Possible/ expected values: en / ar
response_format Alpha Optional max: 4	The Amazon Payment Services response format; whether it’s JSON or XML. *The default response format is “JSON”. Possible/ expected values: - JSON - XML
filters List Optional max: 10	The filters the merchant wants to use to filter the generated report results. possible/ expected values: (Please refer to section filters parameters).

Columns Parameter

The following table contains all the possible values you want to revert in your response, you can choose any of them:

Value	Description
fort_id	The order’s unique reference returned by our system.
merchant_reference	The Merchant’s unique order number.
authorization_code	The authorization code returned from the 3rd party responsible for processing the transaction.
customer_name	The Customer’s name.
customer_ip	The customer’s IP address; where the Merchant sends as part of the authorization/ purchase request.
geolocation_ip	The card for the Customer’s computer.
customer_email	The Customer’s email; where the Merchant sends with the authorization/purchase request.
acquirer_name	The name of the Acquirer.
payment_option	The payment option use to process the authorization/ purchase request.
channel	The Amazon Payment Services channel used to receive the authorization/purchase request.
transaction_date	The date of the transaction.
card_number	The card number used to process the transaction.
expiry_date	The card’s expiry date.
card_holder_name	The cardholder’s name.
amount	The transaction’s amount.
currency	The currency of the transaction’s amount in ISO code 3.
card_bin	The bank identification number (BIN); which is the initial four to eight numbers that appear on a credit card.
eci	The E-commerce indicator associated with the transactions authorization/ purchase request.
operation	The operation type (authorization, purchase, void authorization, capture, and refund)
token_name	The Token associated with the card used to process the transaction.
3ds_indicator	This indicator will hold the value “yes” in case 3D Secure check was performed on a specific transaction. Otherwise, it will holds the value “no”.
fraud_indicator	This indicator will hold the value “yes” in case fraud check was performed on a specific transaction. Otherwise, it will holds the value “no”.
installments_indicator	This indicator will hold the value “yes” in case installments service was applied on a specific transaction. Otherwise, it will holds the value “no”.
status	A two-digit numeric value that indicates the status of the transaction.
response_code	Carries the value of our system’s response.
response_message	The Message description of the response code. It returns according to the request language.
third_party_message	The message retrieved from the third party.
third_party_code	The code retrieved from the third party.
order_date	The creation date of the order.
order_description	The description of the order provided by the merchant.
acquirer_mid	The Acquirer Merchant identifier.
acquirer_response_code	The code the Acquirer returns.
acquirer_response_message	The code the Acquirer returns.
processor_response_code	The code the Acquirer returns.
sadad_olp	SADAD Online Payment ID Alias. The value that SADAD’s Customer provides to process SADAD order.
sadad_transaction_id	The identifier returned by SADAD for a specific SADAD transaction.
payment_link_id	Payment link unique identifier.
Invoice_id	The identification for a specific subscription service.
digital_wallet	The buyer’s digital wallet.
reconciliation_reference	The reconciliation reference number (RRN)

Filters Parameter

Include the following parameters into “filters” parameter you will send to Amazon Payment Services:

ATTRIBUTES	Description
key Alphanumeric max: 110	The name of the column you want to filter. You can choose more than one. Possible/ expected values: (Please refer to section Key parameter). Special characters: # `'` \ / . _ - @ : Space
value Alphanumeric max: -	The value of the key you want to revert in your response. It depends on the key you have chosen to revert.

Key Parameter

The following table contains all the possible values of the “key” parameter, you can choose any of them:

Key	Description & Possible Values
fort_id	The order’s unique reference returned by our system.
merchant_reference	The Merchant’s unique order number.
authorization_code	The authorization code returned from the 3rd party responsible for processing the transaction.
customer_name	The Customer’s name.
customer_ip	The customer’s IP address; where the Merchant sends as part of the authorization/ purchase request.
geolocation_ip	The card for the Customer’s computer.
customer_email	The Customer’s email; where the Merchant sends with the authorization/purchase request.
acquirer_name	The name of the Acquirer.
payment_option	The payment option use to process the authorization/ purchase request. Possible/ Expected Values: - MASTERCARD - VISA - AMEX - SADAD - NAPS - KNET - MADA - MEEZA
channel	The Amazon Payment Services channel used to receive the authorization/purchase request. Possible/ Expected Values: - MOTO - Trusted - Merchant Page - Redirection - eTerminal - Recurring
transaction_date	The date of the transaction.
card_number	The card number used to process the transaction.
expiry_date	The card’s expiry date.
card_holder_name	The cardholder’s name.
amount	The transaction’s amount.
currency	The currency of the transaction’s amount in ISO code 3.
card_bin	The bank identification number (BIN); which is the initial four to eight numbers that appear on a credit card.
eci	The E-commerce indicator associated with the transactions authorization/ purchase request. Possible/ Expected Values: - ECOMMERCE - RECURRING - MOTO
operation	The operation type (authorization, purchase, void authorization, capture, and refund).
token_name	The Token associated with the card used to process the transaction.
3ds_indicator	This indicator will hold the value “yes” in case 3D Secure check was performed on a specific transaction. Otherwise, it will holds the value “no”. Possible/ Expected Values: - YES - NO
fraud_indicator	This indicator will hold the value “yes” in case fraud check was performed on a specific transaction. Otherwise, it will holds the value “no”. Possible/ Expected Values: - YES - NO
installments_indicator	This indicator will hold the value “yes” in case installments service was applied on a specific transaction. Otherwise, it will holds the value “no”. Possible/ Expected Values: - YES - NO
status	A transaction status value that indicates the status of the transaction.
response_code	Carries the value of our system’s response.
response_message	The Message description of the response code. It returns according to the request language.
third_party_message	The message retrieved from the third party.
third_party_code	The code retrieved from the third party.
order_date	The creation date of the order.
order_description	The description of the order provided by the merchant.
acquirer_mid	The Acquirer Merchant identifier.
acquirer_response_code	The code the Acquirer returns.
acquirer_response_message	The code the Acquirer returns.
processor_response_code	The code the Acquirer returns.
sadad_olp	SADAD Online Payment ID Alias. The value that SADAD’s Customer provides to process SADAD order.
sadad_transaction_id	The identifier returned by SADAD for a specific SADAD transaction.
payment_link_id	Payment link unique identifier.
Invoice_id	The identification for a specific subscription service.
digital_wallet	The buyer’s digital wallet. Possible/ Expected Values: - MASTERPASS - VISA_CHECKOUT - APPLE_PAY
reconciliation_reference	The reconciliation reference number (RRN)

Generate Report Request Example

{
“query_command”: “GENERATE_REPORT”,
“access_code”: “zx0IPmPy5jp1vAz8Kpg7”,
“merchant_identifier”: “CycHZxVj”,
“merchant_reference”: “XYZ9239-yu898”,
“from_date”: “2017-08-03T00:00:01+03:00”,
“to_date”: “2017-08-03T23:59:59+03:00”,
“response_format”: “JSON”,
“language”: “en”,
“columns”: [
    “order_description”,
    “customer_ip”,
    “eci”,
    “geolocation_ip”,
    “merchant_reference”,
    “card_holder_name”,
    “currency”,
    “amount”,
    “payment_option”,
    “fort_id”,
    “customer_email”,
    “customer_name”,
    “operation”,
],
“filters”: [
    {
    “key”: “currency”,
    “value”: “USD”
    },
    {
    “key”: “payment_option”,
    “value”: “VISA”
    }
],
“signature”: “03a36d58acfc611f521528f2039a2228031d7ae4248d95181f2a24cfbe9f7865”
}

Generate Report - Response

The following parameters will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
query_command Alpha max: 50	Query operations command. Possible/ expected values: GENERATE_REPORT
access_code Alphanumeric max: 20	Merchant account Access Code. Example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier Alphanumeric max: 20	Amazon Payment Services Merchant Account identifier. Example: CycHZxVj
merchant_reference Alphanumeric max: 40	The Merchant’s unique reference for a specific request. Example: XYZ9239-yu898
from_date Alphanumeric Mandatory max: 30	Query parameter to filter from a specific date. Example: 2017-01-01T14:36:55+03:00
to_date Alphanumeric Mandatory max: 30	Query parameter to filter the results till a specific date. Example: 2017-06-28T14:36:55+03:00
signature Alphanumeric max: 200	A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
language Alpha max: 2	The checkout page and messages language. Possible/ expected values: en / ar
response_format Alpha Max: 4	The Amazon Payment Services response format; whether it’s JSON or XML. *The default response format is “JSON”. Possible/ expected values: - JSON - XML
response_message Alphanumeric max: 150	Message description of the response code. It returns according to the request language. Example: Insufficient Funds
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: 56000
status Numeric max: 2	A two-digit numeric value that indicates the status of the transaction Possible/ expected values: (Please refer to section statuses).

Generate Report “JSON” Response Example

Generate Report “XML” Response Example

Download Report - Request

Include the following parameters in the Request you will send to Amazon Payment Services:

ATTRIBUTES	Description
query_command Alpha Mandatory max: 50	Query operations command. Possible/ expected values: DOWNLOAD_REPORT 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
merchant_reference Alphanumeric Mandatory max: 40	The Merchant’s unique number. *Please, use the same merchant reference you used in the “generate report” request. Example: XYZ9239-yu898
signature Alphanumeric Mandatory max: 200	A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a

Download Report Request Example

Download Report - Response

The following parameters will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
query_command Alpha max: 50	Query operations command. Possible/ expected values: DOWNLOAD_REPORT
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 reference for a specific request. Example: XYZ9239-yu898
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. Example: Insufficient Funds
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: 56000
status Numeric max: 2	A two-digit numeric value that indicates the status of the transaction Possible/ expected values: (Please refer to section statuses).

Download Report “JSON” Response Example

[
{
    “data_count”: 2
},
[
{
    “order_description”: “iphone”,
    “customer_ip”: “2001:0002:6c::430”,
    “eci”: “ECOMMERCE”,
    “merchant_reference”: “XYZ9239-yu898”,
    “currency”: “USD”,
    “geolocation_ip”: “192.168.33.18”,
    “amount”: “1000”,
    “payment_option”: “VISA”,
    “fort_id”: “150701416400054912”,
    “customer_email”: “customer@amazon.com”,
    “customer_name”: “duaaدعاء”,
    “operation”: “AUTHORIZATION”,
},
{
    “order_description”: “iphone”,
    “customer_ip”: “2001:0002:6c::430”,
    “eci”: “ECOMMERCE”,
    “merchant_reference”: “XYZ9239-yu898”,
    “currency”: “USD”,
    “geolocation_ip”: “192.168.33.18”,
    “amount”: “1000”,
    “payment_option”: “VISA”,
    “fort_id”: “150701415400054909”,
    “customer_email”: “customer@amazon.com”,
    “customer_name”: “duaaدعاء”,
    “operation”: “AUTHORIZATION”,
}
]
]

Download Report “XML” Response Example

<report>
<metadata>
<data_count>2</data_count>
</metadata>
<transactions>
   <transaction>
      <order_description>iphone</order_description>
      <customer_ip>2001:0002:6c::430</customer_ip>
      <eci>ECOMMERCE</eci>
      <merchant_reference>reference1</merchant_reference>
      <currency>USD</currency>
      <geolocation_ip>192.168.33.18</geolocation_ip>
      <amount>1000</amount>
      <payment_option>VISA</payment_option>
      <fort_id>150701416400054912</fort_id>
      <customer_email>customer@amazon.com</customer_email>
      <customer_name>John Smith</customer_name>
      <operation>AUTHORIZATION</operation>
</transaction>
<transaction>
      <order_description>iphone</order_description>
      <customer_ip>2001:0002:6c::431</customer_ip>
      <eci>ECOMMERCE</eci>
      <merchant_reference>reference2</merchant_reference>
      <currency>USD</currency>
      <geolocation_ip>192.168.33.18</geolocation_ip>
      <amount>1000</amount>
      <payment_option>VISA</payment_option>
      <fort_id>150701416400054912</fort_id>
      <customer_email>customer@amazon.com</customer_email>
      <customer_name>John Smith</customer_name>
      <operation>AUTHORIZATION</operation>
</transaction>
</transactions>
</report>

Reporting Pagination API

This service allows Merchants to specify the number of pages via Amazon Payment Services API. The Merchant will receive back specified pages based on the search criteria. The Merchant is allowed to search for 20,000 transactions per each request.

Reporting Pagination API URLs

Test Environment URL:

https://sbpaymentservices.payfort.com/FortAPI/reportingApi

Production Environment URL:

https://paymentservices.payfort.com/FortAPI/reportingApi

Parameters Submission Type

REST POST request using JSON.

How it Works

You submit a “Get Report” request. This request enables you to specify the number of pages via the Amazon Payment Services API; where you send the page size (the number of records you want to retrieve in each request) and the start index (the record to start retrieve records from).
1. Amazon Payment Services returns the “Get Report” response including the records you requested.

Reporting Pagination API - Request

Include the following parameters in the Request you will send to Amazon Payment Services:

ATTRIBUTES	Description
query_command Alpha Mandatory max: 50	Query operations command. Possible/ expected values: GET_REPORT 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
from_date Alphanumeric Mandatory max: 30	Query parameter to filter from a specific date. Example: 2017-01-01T14:36:55+03:00 Special characters: + - :
to_date Alphanumeric Mandatory max: 30	Query parameter to filter the results till a specific date. Example: 2017-06-28T14:36:55+03:00 Special characters: + - :
columns List Mandatory max: 110	The columns the merchant wants to include in the generated report. Possible/ expected values: (Please refer to section columns parameters). Special characters: _
page_size Numeric Mandatory max: 2	The number of records each request. *The maximum page size is 50 records per page. Example: 10
start_index Numeric Mandatory max: 5	From where you want to start getting the records. Example: 19000
signature Alphanumeric Mandatory max: 200	A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
language Alpha Optional max: 2	The checkout page and messages language. Possible/ expected values: en / ar
response_format Alpha Optional max: 4	The Amazon Payment Services response format; whether it’s JSON or XML. *The default response format is “JSON”. Possible/ expected values: - JSON - XML
filters List Optional max: 10	The filters the merchant wants to use to filter the generated report results. Possible/ expected values: (Please refer to section filters parameters).

Columns Parameters

The following table contains all the possible values you want to revert in your response. You can choose any of:

Value	Description
fort_id	The order’s unique reference returned by our system.
merchant_reference	The Merchant’s unique order number.
authorization_code	The authorization code returned from the 3rd party responsible for processing the transaction.
customer_name	The Customer’s name.
customer_ip	The customer’s IP address; where the Merchant sends as part of the authorization/ purchase request.
geolocation_ip	The card for the Customer’s computer.
customer_email	The Customer’s email; where the Merchant sends with the authorization/purchase request.
acquirer_name	The name of the Acquirer.
payment_option	The payment option use to process the authorization/ purchase request.
channel	The Amazon Payment Services channel used to receive the authorization/purchase request.
transaction_date	The date of the transaction.
card_number	The card number used to process the transaction.
expiry_date	The card’s expiry date.
card_holder_name	The cardholder’s name.
amount	The transaction’s amount.
currency	The currency of the transaction’s amount in ISO code 3.
card_bin	The bank identification number (BIN); which is the initial four to eight numbers that appear on a credit card.
eci	The E-commerce indicator associated with the transactions authorization/ purchase request.
operation	The operation type (authorization, purchase, void authorization, capture, and refund)
token_name	The Token associated with the card used to process the transaction.
3ds_indicator	This indicator will hold the value “yes” in case 3D Secure check was performed on a specific transaction. Otherwise, it will holds the value “no”.
fraud_indicator	This indicator will hold the value “yes” in case fraud check was performed on a specific transaction. Otherwise, it will holds the value “no”.
installments_indicator	This indicator will hold the value “yes” in case installments service was applied on a specific transaction. Otherwise, it will holds the value “no”.
status	A two-digit numeric value that indicates the status of the transaction.
response_code	Carries the value of our system’s response.
response_message	The Message description of the response code. It returns according to the request language.
third_party_message	The message retrieved from the third party.
third_party_code	The code retrieved from the third party.
order_date	The creation date of the order.
order_description	The description of the order provided by the merchant.
acquirer_mid	The Acquirer Merchant identifier.
acquirer_response_code	The code the Acquirer returns.
sadad_olp	SADAD Online Payment ID Alias. The value that SADAD’s Customer provides to process SADAD order.
sadad_transaction_id	The identifier returned by SADAD for a specific SADAD transaction.
payment_link_id	Payment link unique identifier.
Invoice_id	The identification for a specific subscription service.
digital_wallet	The buyer’s digital wallet.
reconciliation_reference	The reconciliation reference number (RRN)

Filters Parameter

Include the following parameters into “filters” parameter you send to Amazon Payment Services:

ATTRIBUTES	Description
key Alphanumeric max: 110	The name of the column you want to filter. You can choose more than one. Possible/ expected values: (Please refer to section Key parameter). Special characters: # `'` \ / . _ - @ : Space
value Alphanumeric max: -	The value of the key you want to revert in your response. It depends on the key you have chosen to revert.

Key Parameters

The following table contains all the possible values of the “key” parameter, you can choose any of them:

Key	Description & Possible Values
fort_id	The order’s unique reference returned by our system.
merchant_reference	The Merchant’s unique order number.
authorization_code	The authorization code returned from the 3rd party responsible for processing the transaction.
customer_name	The Customer’s name.
customer_ip	The customer’s IP address; where the Merchant sends as part of the authorization/ purchase request.
geolocation_ip	The card for the Customer’s computer.
customer_email	The Customer’s email; where the Merchant sends with the authorization/purchase request.
acquirer_name	The name of the Acquirer.
payment_option	The payment option use to process the authorization/ purchase request. Possible/ Expected Values: - MASTERCARD - VISA - AMEX - SADAD - NAPS - KNET - MADA - MEEZA
channel	The Amazon Payment Services channel used to receive the authorization/purchase request. Possible/ Expected Values: - MOTO - Trusted - Merchant Page - Redirection - eTerminal - Recurring
transaction_date	The date of the transaction.
card_number	The card number used to process the transaction.
expiry_date	The card’s expiry date.
card_holder_name	The cardholder’s name.
amount	The transaction’s amount.
currency	The currency of the transaction’s amount in ISO code 3.
card_bin	The bank identification number (BIN); which is the initial four to eight numbers that appear on a credit card.
eci	The E-commerce indicator associated with the transactions authorization/ purchase request. Possible/ Expected Values: - ECOMMERCE - RECURRING - MOTO
operation	The operation type (authorization, purchase, void authorization, capture, and refund).
token_name	The Token associated with the card used to process the transaction.
3ds_indicator	This indicator will hold the value “yes” in case 3D Secure check was performed on a specific transaction. Otherwise, it will holds the value “no”. Possible/ Expected Values: - YES - NO
fraud_indicator	This indicator will hold the value “yes” in case fraud check was performed on a specific transaction. Otherwise, it will holds the value “no”. Possible/ Expected Values: - YES - NO
installments_indicator	This indicator will hold the value “yes” in case installments service was applied on a specific transaction. Otherwise, it will holds the value “no”. Possible/ Expected Values: - YES - NO
status	A two-digit numeric value that indicates the status of the transaction.
response_code	Carries the value of our system’s response.
response_message	The Message description of the response code. It returns according to the request language.
third_party_message	The message retrieved from the third party.
third_party_code	The code retrieved from the third party.
order_date	The creation date of the order.
order_description	The description of the order provided by the merchant.
acquirer_mid	The Acquirer Merchant identifier.
acquirer_response_code	The code the Acquirer returns.
sadad_olp	SADAD Online Payment ID Alias. The value that SADAD’s Customer provides to process SADAD order.
sadad_transaction_id	The identifier returned by SADAD for a specific SADAD transaction.
payment_link_id	Payment link unique identifier.
Invoice_id	The identification for a specific subscription service.
digital_wallet	The buyer’s digital wallet. Possible/ Expected Values: - MASTERPASS - VISA_CHECKOUT - APPLE_PAY
reconciliation_reference	The reconciliation reference number (RRN)

Get Report Request Example

{
“query_command”: “GET_REPORT”,
“access_code”: “zx0IPmPy5jp1vAz8Kpg7”,
“merchant_identifier”: “CycHZxVj”,
“from_date”: “2017-08-03T00:00:01+03:00”,
“to_date”: “2017-08-03T23:59:59+03:00”,
“response_format”: “JSON”,
“language”: “en”,
“page_size”:10,
“start_index”:19000,
“columns”: [
    “acquirer_name”,
    “authorization_code”,
    “amount”,
    “card_number”,
    “card_holder_name”,
    “channel”,
    “currency”,
],
“filters”: [
{
    “key”: “currency”,
    “value”: “USD”
},
{
    “key”: “payment_option”,
    “value”: “VISA”
}
],
“signature”: “03a36d58acfc611f521528f2039a2228031d7ae4248d95181f2a24cfbe9f7865”
}

Reporting Pagination API - Response

The following parameters will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
query_command Alpha max: 50	Query operations command. Possible/ expected values: GET_REPORT
access_code Alphanumeric max: 20	Access code. Example: zx0IPmPy5jp1vAz
merchant_identifier Alphanumeric max: 20	The ID of the Merchant. Example: CycHZxVj
from_date Alphanumeric max: 30	Query parameter to filter from a specific date. Example: 2017-01-01T14:36:55+03:00 Special characters: + - :
to_date Alphanumeric max: 30	Query parameter to filter the results till a specific date. Example: 2017-06-28T14:36:55+03:00 Special characters: + - :
page_size Numeric max: 2	The number of records each request. *The maximum page size is 50 records per page. Example: 10
start_index Numeric max: 5	From where you want to start getting the records. Example: 19000
signature Alphanumeric max: 200	A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
transactions List max: -	Records you have in your account. They are retrieved according to your request.
transactions_count Numeric max: 5	The total number of records you have in your account. Example: 1913
language Alpha max: 2	The checkout page and messages language. Possible/ expected values: en / ar
response_format Alpha max: 4	The Amazon Payment Services response format; whether it’s JSON or XML. *The default response format is “JSON”. Possible/ expected values: - JSON - XML
response_message Alphanumeric max: 150	Message description of the response code. It returns according to the request language. Example: Insufficient Funds
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).

Get Report “JSON” Response Example

{
“query_command”: “GET_REPORT”,
“access_code”: “zx0IPmPy5jp1vAz8Kpg7”,
“merchant_identifier”: “CycHZxVj”,
“from_date”: “2017-08-03T00:00:01+03:00”,
“to_date”: “2017-08-03T23:59:59+03:00”,
“response_format”: “JSON”,
“page_size”:10,
“start_index”:19000,
“transactions”: [
{
    “acquirer_name”: “SABB-TEST”,
    “authorization_code”: “362477”,
    “amount”: “1000”,
    “card_number”: “400555******0001”,
    “card_holder_name”: “John Smith”,
    “channel”: “Redirection”,
    “currency”: “USD”,
}
],
“transactions_count”: “1913”,
“signature”: “521d32010a9988de86e16b49f6303985508d5f244784474da1184d457b53ded2”,
“language”: “en”,
“response_message”: “Success”,
“response_code”: “56000”,
“status”: “56”
}

Get Report “XML” Response Example

<response>
<transactions_count>1913</transactions_count>
<response_code>56000</response_code>
<from_date>2017-08-03T00:00:01+03:00</from_date>
<signature>521d32010a9988de86e16b49f6303985508d5f244784474da1184d457b53ded2</signature>
<merchant_identifier>CycHZxVj</merchant_identifier>
<access_code>zx0IPmPy5jp1vAz8Kpg7</access_code>
<language>en</language>
<transactions_list>
   <transactions>
      <acquirer_name>SABB-TEST</acquirer_name>
      <authorization_code>362477v/authorization_code>
      <amount>1000</amount>
      <card_number>400555******0001</card_number>
      <card_holder_name>John Smith</card_holder_name>
      <channel>Redirection</channel>
      <currency>USD</currency>
   </transactions>
</transactions_list>
<response_format>XML</response_format>
<response_messagevSuccess</response_message>
<to_date>2017-08-03T23:59:59+03:00</to_date>
<start_index>19000</start_index>
<query_command>GET_REPORT</query_command>
<status>56</status>
<page_size>10</page_size>
</response>

Was this helpful? Yes No

Verify Service Command

If you are a PCI-compliant merchant you can use our API to check that the payment card details that your customer supplied to you is valid and in good standing. Our verify service allows you to pre-validate a payment card issued by Visa, Mastercard or American Express (AMEX) as part of your risk management process.

Before Starting

Before you start integrating this service you need to be aware of the following:
• This service command is can be used across two channels only and you have to configure the channel you want to add this service to via the back office. Your choice is between:
1. Merchant page integration.
2. Trusted channel.
• You can only use this service command via the “MOTO” e-commerce indicator.
• You must include the amount you want to authorize or capture from your customer in your verification request.
• The authorized or captured amount will be voided or refunded after checking the card validity.
• The verification transactions will be recorded under the section “Card Verification Report” in the back-office.

Verify Service Command on Trusted 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.

Verify Service Command on Trusted Channel - Request

Include the following parameters in the Request you will send to Amazon Payment Services:

ATTRIBUTES	Description
service_command Alpha Mandatory max: 20	Command. Possible/ expected values: VERIFY_CARD Special characters: _
access_code Alphanumeric Mandatory max: 20	Merchant account Access Code. Example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier Alphanumeric Mandatory max: 20	Amazon Payment Services Merchant Account identifier. Example: CycHZxVj
merchant_reference Alphanumeric Mandatory max: 40	The Merchant’s unique reference for a specific request. 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
expiry_date Numeric Mandatory max: 4	The card’s expiry date. Example: 2105
card_number Numeric Mandatory max: 16	The clear credit card’s number. Example: 4005550000000001
signature Alphanumeric Mandatory max: 200	A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
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: example Special characters: _ - .

Verify Service Command on Trusted Channel Example

Verify Service Command on Trusted Channel - Response

The following parameters will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
service_command Alpha max: 20	Command. Possible/ expected values: VERIFY_CARD Special characters: _
access_code Alphanumeric max: 20	Merchant account Access Code. Example: zx0IPmPy5jp1vAz8Kpg7
merchant_identifier Alphanumeric max: 20	Amazon Payment Services Merchant Account identifier. Example: CycHZxVj
merchant_reference Alphanumeric max: 40	The Merchant’s unique reference for a specific request. Example: XYZ9239-yu898 Special characters: _ - .
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
expiry_date Numeric max: 4	The card’s expiry date. Example: 2105
card_number Numeric max: 16	The masked credit card’s number. Example: 400555******0001
signature Alphanumeric max: 200	A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
language Alpha max: 2	The checkout page and messages language. Possible/ expected values: en / ar
response_message Alphanumeric max: 150	Message description of the response code. It returns according to the request language. Example: Insufficient Funds
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: 80000
status Numeric max: 2	A two-digit numeric value that indicates the status of the transaction Possible/ expected values: (Please refer to section statuses).
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: example

Verify Service Command on Trusted Channel Response Example

Check Status for Verify Service Command

You can retrieve the results of a verify command by making use of the check status API command.

Check Status for Verify Service Command 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.

Check Status for Verify Service - Request

Include the following parameters in the Request you will send to Amazon Payment Services:

ATTRIBUTES	Description
query_command Alpha Mandatory max: 50	Query operations command. Possible/ expected values: CHECK_VERIFY_CARD_STATUS 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
merchant_reference Alphanumeric Mandatory max: 40	The Merchant’s unique number. *Please, use the same merchant reference you used in the “Verify Card Service Command” request. Example: XYZ9239-yu898
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

Check Status on Verify Service Command Request Example

Check Status for Verify Service Command - Response

The following parameters will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
query_command Alpha max: 50	Query operations command. Possible/ expected values: CHECK_VERIFY_CARD_STATUS
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 reference for a specific request. 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 for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
response_message Alphanumeric max: 150	Message description of the response code. It returns according to the request language. Example: Insufficient Funds
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: 56000
status Numeric max: 2	A two-digit numeric value that indicates the status of the transaction Possible/ expected values: (Please refer to section statuses).
transaction_status Numeric max: 2	The status of the last verify operation performed on a specific card. Possible/ expected values: (Please refer to section statuses).
transaction_message Alphanumeric Max: 150	The message returned for the last verify operation performed on a specific card. Example: success

Check Status on Verify Service Command Response Example

Was this helpful? Yes No

Safe (Tokenization)

Tokenization gives your business the ability to process payments in a fast and convenient way without the need for your server to receive, manipulate, or store sensitive payment card data.

Thanks to tokens you can rely on Amazon Payment Services to handle sensitive payment card data, reducing your compliance obligations.

Tokens also enable you to offer your customers convenience options including a faster checkout experience and the effortless processing of recurring payments.

Create a token in the transaction flow

Most payment processing configurations in Amazon Payment Services will require you to process transactions by making use of tokenization. In other words, to successfully process a transaction, you must generate a token during the transaction flow.

To create a new token as part of the transaction workflow you need to include the following parameter in the authorization or purchase request you send to Amazon Payment Services; the same parameter will then contain the token name in Amazon Payment Services’ response:

ATTRIBUTES	Description
token_name Alphanumeric Optional max: 100	Holds the name of the Token to update the Token or rename it. Example: OpVmp Special characters: . @ - _

Create New Token Service

In some circumstances, tokenization will occur as a distinct step that does not necessarily involve a payment. A simple example would be where your customer wants to sign up and store their payment card details for future transactions – without making a purchase at the time that they sign up.

Amazon Payment Services Tokenization Service 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.

Create New Token Service - Request

Include the following parameters in the Request you will send to Amazon Payment Services:

ATTRIBUTES	Description
service_command Alpha Mandatory Max: 20	Command. Possible/ expected values: CREATE_TOKEN
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: - _ .
language Alpha Mandatory Max: 2	The checkout page and messages language. Possible/ expected values: en/ ar
card_number Numeric Mandatory Max: 19	The clear card data collect on the Merchant page form, developed by the Merchant. 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: 4005550000000001
expiry_date Numeric Mandatory Max: 4	The card’s expiry date. Example: 2105
return_url Alphanumeric Mandatory Max: 400	The URL of the Merchant’s page that will be displayed to the customer when the order is processed. Example: https://www.merchant.com Special characters: $ ! = ? # & - _ / : .
signature Alphanumeric Mandatory Max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
currency Alpha Optional Max: 3	The currency of the transaction’s amount in ISO code 3. Example: USD
token_name Alphanumeric Optional Max: 100	The Token received from the Tokenization process. Example: Op9Vmp Special characters: . @ - _
card_holder_name Alpha Optional Max: 50	The card holder name. Example: John Smith Special characters: `'` - .

Create New Token Service - Response

The following parameters will be returned in Amazon Payment Services’ response:

ATTRIBUTES	Description
service_command Alpha Max: 20	Command. Possible/ expected values: CREATE_TOKEN
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
language Alpha Max: 2	The checkout page and messages language. Possible/ expected values: en/ ar
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
expiry_date Numeric Max: 4	The card’s expiry date. Example: 2105
return_url Alphanumeric Max: 400	The URL of the Merchant’s page that will be displayed to the customer when the order is processed. Example: https://www.merchant.com
signature Alphanumeric Max: 200	A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a
currency Alpha Max: 3	The currency of the transaction’s amount in ISO code 3. Example: USD
token_name Alphanumeric Max: 100	The Token received from the Tokenization process. Example: Op9Vmp
card_holder_name Alpha Max: 50	The card holder name. Example: John Smith
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

Update Token Service

There are several reasons why you may want to update a token with Amaz