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.
Read more about how PayFort evolved into Amazon Payment Services here.
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.
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.
Amazon Payment Services requires to test your integration before going live to verify the integration and make sure it’s implemented properly.
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.
Read more about integration options here.
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 |
| 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) - 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: $ ! = ? # & - _ / : . |
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 |
| 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) - 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 |
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.
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.
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.
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.
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 |
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 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 |
| 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: $ ! = ? # & - _ / : . |
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 |
| 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 |
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
Wrapperclass: responsible for the total width of the form container and the background. - The
Containerclass: responsible for the form’s shape and width. - The
Popoverclass: responsible for the error messages. - The
Half-containerclass: used to merge the date and CVV fields into one block if needed. - The
Inputclass: is the container of each single input field. - The
Payclass: responsible for the submit button. - The
Visa/ MasterCardclasses: used to change the color of the Visa/ MasterCard colors.
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 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 |
| 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: $ ! = ? # & - _ / : . |
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 |
| 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 |
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.
Mobile SDK
Easily integrate native, in-app mobile payments right into your Android or iOS app by using the Amazon Payment Services mobile SDK.
When you integrate in-app payment processing your customers no longer need to follow the time-consuming and complex route of redirection to a mobile browser to pay.
Our pre-packaged SDKs require less development effort and skills compared to custom-coding your own in-app payment experience.
Read more about our mobile SDKs and the mobile SDK integration workflow here.
Download
Get started by downloading the SDK for Android or iOS below. You can also download a comprehensive PDF integration guide for each environment.
API authentication tokens for the Mobile SDK
A unique mobile SDK authentication token is required for every request sent to the SDK. You use the mobile SDK authentication token every time you process a payment operation through the mobile SDK.
SDK authentication token URLs
Test Environment URL:
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production Environment URL:
https://paymentservices.payfort.com/FortAPI/paymentApi
Parameters Submission Type
REST POST request using JSON.
SDK authentication token - request
Include the following parameters in the request you will send to the Amazon Payment Services SDK:
| ATTRIBUTES | Description |
|---|---|
| service_command Alpha Mandatory max: 20 |
Command. Possible/ expected values: SDK_TOKEN Special characters: _ |
| access_code Alphanumeric Mandatory Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
| merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
| language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
| device_id Alphanumeric Mandatory Max: 100 |
A unique device identifier. Example: ffffffff-a9fa-0b44-7b27-29e70033c587 Special characters: - |
| signature Alphanumeric Mandatory Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
SDK authentication token - response
The following parameters will be returned in the Amazon Payment Services SDK response:
| ATTRIBUTES | Description |
|---|---|
| service_command Alpha Max: 20 |
Command. Possible/ expected values: SDK_TOKEN |
| access_code Alphanumeric Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
| merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
| language Alpha Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
| device_id Alphanumeric Max: 100 |
A unique device identifier. Example: ffffffff-a9fa-0b44-7b27-29e70033c587 |
| signature Alphanumeric Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
| sdk_token Alphanumeric Max: 100 |
An SDK Token to enable using the 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 |
Integrating the Android SDK
To process a transaction using the Android mobile SDK, you must create a mobile SDK authentication token. Please refer to the section Create a mobile SDK authentication token. Next, proceed through the following sections.
Important facts about the Android SDK
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. The mobile SDK supports both English and Arabic.
Portrait orientation is the only supported screen orientation. The Amazon Payment Services Android mobile SDK does not support landscape orientation.
Note that the Android mobile SDK does not offer the same range of payment options as our web-based integration routes. This version of the Android mobile SDK can only process payments made with ordinary debit or credit cards. The supported payment card payment options are Visa, Mastercard, American Express, Mada, and Meeza.
You can read more about the Android SDK here.
IDE Configurations
To start using the Android mobile SDK, do the following:
1. Extract this folder.
2. Download the SDK for Android.
3. Unzip the downloaded Android SDK.
4. The folder content is as follows:
* Dependencies folder which includes:
- Eclipse folder:
a. .jar files for the SDK dependencies.
b. LINKS_README text file that contains a list for sources of the above jars and a
list of required libraries to be added as dependencies
as well (Manual configuration).
- AndroidStudio_gradle text file; add the compile command for what your project
does not include.
* Res folder which includes:
- Layout
- Layout-ar
* FORTSDKv1.6.1.aar-release.
To continue the integration, please proceed with the following steps:
1. Go to File → New → New Module.
2. Select “Import .JAR/.AAR Package” and click next.
3. Enter the path to .aar file and click finish.
4. Browse to the dependencies folder and open the “AndroidStudio_gradle” text file.
5. Copy and paste the implementation/ api lines that are NOT already supported in your dependency block. (All listed dependencies are required).
6. Click the “Sync the project with gradle files” button.
7. Clean the project.
8. The SDK is now ready for your use.
The integration will include two main steps. For the first step, you need to create a library project by following the below steps:
1. Create a new project (from this time it’s called “library project”) in your workspace.
2. Do not forget to mark it as library.
3. Clear the src folder of the library project.
4. Unzip the .aar file. You can rename it to zip and then unzip it or use any tool.
5. Copy the classes.jar file to libs folder on the library project.
6. Replace the res folder on library project with the res folder of the .aar file.
The project you have created contains almost everything you need. Now let’s start configuring your project to reference this library project by following the below points:
1. In the target project, use the library created in step one (mentioned above) as a dependency.
2. Open the AndroidManifest.xml file inside .aar file and make sure to copy everything it takes (permissions, activities, services, receivers …) in the AndroidManifest.xml file of the target project.
3. Copy the entire contents (if any) inside the assets folder of the .aar file to the assets folder of the target project.
4. Copy the entire contents (if any) inside the libs folder of the .aar file to the libs folder of the target project.
5. Open the dependencies file → Eclipse, then copy all .jar files and add them to the libs folder of the target project.
6. Check if your target project has the project dependencies included in the LINKS_README text file under the LINKS_README text file under the libraries (Projects/aar). Otherwise use the links included in the previously mentioned file and add them as a dependency project on your target project.
7. Clean and rebuild your target project.
OS Permissions
The Android mobile SDK requires the following permissions to work properly:
Using the Android Mobile SDK
Please take a look at the Java model/bean of the Android Mobile SDK request on the right side of the page.
The following are the Mobile SDK Call Parameters:
// FORT Mobile SDK request
public class FortRequest implements Serializable{
private Map<String, Object> requestMap;
private boolean showResponsePage;
public Map<String, Object> getRequestMap() {
return requestMap;
}
public void setRequestMap(Map<String, Object> requestMap) {
this.requestMap = requestMap;
}
public boolean isShowResponsePage() {
return showResponsePage;
}
public void setShowResponsePage(boolean showResponsePage) {
this.showResponsePage = showResponsePage;
}
}
- The “requestMap” must contain all the parameters of the order/ transaction.
- “showResponsePage” is the Boolean field where you can determine if you want the Amazon Payment Services response page to be displayed or not.
Define and initialize an instance of the FortCallBackManager in your activity as appears on the right side of the page (Java section):
// FORT Callback Manager Instance
private FortCallBackManager fortCallback = null;
fortCallback = FortCallback.Factory.create();
You need to add the statement that appears on the right side of the page (Java section) to the onActivityResult function.
//Callback Statement
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
super.onActivityResult(requestCode, resultCode, data);
fortCallback.onActivityResult(requestCode,resultCode,data);
}
For every transaction that needs to be processed, do the call that appears on the right side of the page and handle the callback methods according to your business flow.
//FORT Mobile SDK Call
FortSdk.getInstance().registerCallback(this,fortRequest,5, fortCallback, showLoading, new FortInterfaces.OnTnxProcessed() {
@Override
public void onCancel(Map<String, Object> requestParamsMap,Map<String, Object> responseMap) {
//TODO: handle me
}
@Override
public void onSuccess(Map<String, Object> requestParamsMap, Map<String, Object> fortResponseMap) {
//TODO: handle me
}
@Override
public void onFailure(Map<String, Object> requestParamsMap, Map<String, Object> fortResponseMap) {
//TODO: handle me
}
@Override
public void onSuccess(Map<String, Object> requestParamsMap, Map<String, Object> fortResponseMap) {
//TODO: handle me
}
});
The Android Mobile SDK call registers a new callback for a new request. The registerCallBack requires the inputs found on the right side of the page (Java section).
//The registerCallBack Request
public void registerCallback(
Activity context,
final FortRequest fortRequest,
String environment,
final int requestCode,
final FortCallBackManager callbackManager,
boolean showLoading,
final FortInterfaces.OnTnxProcessed callback)
| Parameter | Description |
|---|---|
| context | Passes the currency activity context. |
| fortRequest | An instance of the model mentioned in Collect the 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. |
Please Make sure to use the FortSDK function found on the right side of the page (Java section) to generate the device_id parameter value that must be used for creating the sdk_token from your business security server.
//FortSDK function
String device_id = FortSdk.getDeviceId(this);
We provide you with the res folder that includes the source code of the pages in order to customize the design, themes, etc. You can customize both English and Arabic layouts as needed. However, please take the following tips into consideration:
1. Don’t change the layout name because it’s considered an override process. 2. Make sure to use all the views that has the ID property in order to avoid the NullPointerException. 3. Redesign the view for portrait orientation. Note that Landscape orientation isn’t supported. 4. You can support as much layout densities as you want. 5. Don’t forget to redesign the layout-ar file too (right-to-left). 6. Don’t change, rename, or remove onClick functions.
 Our Mobile SDK v 1.6 consists one of the following three main activities design: * activity_cc_payment.xml * activity_cc_response.xml * activity_init_secure_conn
Every file is available for both English and Arabic alignments; layout and layout-ar.
Design Customization Codes:
The following code was used to customize the way the “Amount” is displayed in the Standard Mobile SDK Payment Page:
The following code was used to customize the way the “Amount” is displayed in the Customized Mobile SDK Payment Page:
- As appears in the previous codes, elements with IDs haven’t been changed in type or removed. For example: android:id=“@+id/amountTV”.
- We were able to add static elements such as: ImageView element that contains the Merchant’s logo, and TextView that contains the Merchant’s name.
- To sum up, you can add any static elements or redesign the view, while keeping the views’ elements used in the Standard layout that hold IDs.
SDK Operations
The Android Mobile SDK allows the Merchant’s application to process Authorization and Purchase operations.
Include the following parameters in the Request you will send to the Android SDK:
| ATTRIBUTES | Description |
|---|---|
| command Alpha Mandatory max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE |
| merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
| amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
| currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
| language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
| customer_email Alphanumeric Mandatory Max: 254 |
The customer’s email. Example: customer@domain.com Special characters: _ - . @ + |
| sdk_token Alphanumeric Mandatory Max: 100 |
An SDK Token to enable using the 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: . ; / _ - , ' @ |
The following parameters will be returned in the Android SDK Response:
| ATTRIBUTES | Description |
|---|---|
| command Alpha Max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE |
| merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
| amount Numeric Max: 10 |
The transaction’s amount.*Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
| currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
| customer_email Alphanumeric Max: 254 |
The customer’s email. Example: customer1@domain.com |
| fort_id Numeric Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
| sdk_token Alphanumeric Max: 100 |
An SDK Token to enable using the 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 |
Android SDK – Device ID permission
This section helps the developers to understand the need and usage of the permission requested by the Android Payment SDK to generate a unique device ID.
Developers should stay aware of the need for, and the usage of, the permissions requested by the Amazon Payment Services payment SDK to facilitate the generation of a unique device ID.
One goal of the Amazon Payment Services mobile SDK workflow is to acquire a unique ID for the device. It is important to try to generate the device ID based on more than one input: collecting as much information as possible will lead to a highly unique ID.
You might not face this issue through your payment flow. It depends on exactly when you are requesting the getDeviceID function and when you request the permission for the first time.
To avoid the mismatch flow we are suggesting you the following solutions:
* Handle the 1st SDK call in the onActivityResults().
Since The Android SDK is a module running within the main application context the requested permission response will be returned to the merchant context. Once the activity that called geDeviceId for the 1st received a call-back in the onActivityResult() with request code = 222 you can for sure starts the payment flow of creating an SDK authentication token and calling the SDK afterwards.
- Call getDeviceID on a previous activity or in your application class to make sure that the permission request was triggered before you reach the payment step.
Sample code
Integrating the iOS SDK
To process a transaction using the iOS mobile SDK, create a mobile SDK authentication token. Please refer to section create mobile SDK authentication token and proceed through the following sections.
About the iOS SDK
The Amazon Payment Services iOS SDK is supported on devices running iOS 8 and above. We support both English and Arabic in our iOS SDK, but note that there is no support for landscape orientation: our SDK only supports the portrait orientation.
Note that the iOS mobile SDK does not offer the same range of payment options as our web-based integration routes. This version of the iOS mobile SDK can only process payments made with an ordinary debit or credit card. The supported card payment options are Visa, Mastercard, American Express, Mada, and Meeza.
Including the SDK in your Xcode Project
1. Extract this folder.
2. Drag PayFortSDK.framework & PayFortSDK.bundle to Frameworks in Project Navigator.
3. Create a new group Frameworks if it does not exist:
* Choose Create groups for any added folders.
* Make Sure to select Copy files if needed.
4. Set -ObjC in the Other Linker Flags in the Target → Build Settings Tab.
5. For Swift Projects Don’t forget to add the #import
Objective C
(void)applicationDidEnterBackground:(UIApplication *)application {
__block UIBackgroundTaskIdentifier backgroundTask; backgroundTask =
[application beginBackgroundTaskWithExpirationHandler: ^ {
[application endBackgroundTask:backgroundTask];
backgroundTask = UIBackgroundTaskInvalid; }];
Swift
func applicationDidEnterBackground(_ application: UIApplication) {
var bgTask: UIBackgroundTaskIdentifier = 0
bgTask = application.beginBackgroundTask(expirationHandler: {
application.endBackgroundTask(bgTask)
bgTask = UIBackgroundTaskInvalid
})
}
Installation
1. Import the PayFort Library.
2. Initialize PayFortConrtoller with targeted environment, You set the target environment by setting one the two ENUM KPayFortEnviromentSandBox or KPayFortEnviromentProduction.
Objective C
Swift
3. Set Dictionary contain all keys and values for SDK.
Objective C
Swift
4. Call PayFort and Response callback
Objective C
Swift
iOS SDK - Response
By default the response will be dictionary to show the sent data in addition to the status, response message and response code.
The response will be ready in the registered call back handler with success, failed and cancelled. You can view the response by log the result as the followings:
Objective C
Swift
Also there is an option to show response view directly in elegant view that show response results either its success or failed. By activating the following option:
Objective C
Swift
Hidden Amazon Payment Services loading prompt
There is an option to hide loading view when SDK initialize the connection request. By disable the following option:
Objective C
Swift
Custom Payment Designing
You have the option to provide your custom UI theme for the payment view by the followings:
- Create your nibFile .xib and set the name of Arabic xib same name with English one with suffix -ar.
- Link the xib with PayFortView and bind all the IBOutlets in interface section
- Assign new created xib file to PayFort Controller.
iOS Mobile SDK Operations
The iOS Mobile SDK allows the Merchant’s application to process Authorization and Purchase operations.
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 |
| 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 Paymnet 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 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
| customer_ip Alphanumeric Optional max: 45 |
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf Special characters: . : |
| customer_name Alpha Optional Max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' |
| phone_number Alphanumeric Optional max: 19 |
The customer’s phone number. Example: 00962797219966 Special characters: + - ( ) Space |
| settlement_reference Alphanumeric Optional max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 Special characters: - _ . |
| merchant_extra Alphanumeric Optional Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
| merchant_extra1 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
| merchant_extra2 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
| merchant_extra3 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
| merchant_extra4 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
| merchant_extra5 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
The following parameters will be returned in the iOS SDK response:
| ATTRIBUTES | Description |
|---|---|
| command Alpha Max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE |
| merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. *The amount parameter is returned by our system according to the predefined allowed decimal points per currency. Example: XYZ9239-yu898 |
| amount Numeric Max: 10 |
The transaction’s amount. Example: 10000 |
| currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
| customer_email Alphanumeric Max: 254 |
The customer’s email. Example: customer1@domain.com |
| fort_id Numeric Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
| sdk_token Alphanumeric Max: 100 |
An SDK Token to enable using the Mobile SDK. Example: Dwp78q3 |
| token_name Alphanumeric max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp |
| payment_option Alpha Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) |
| eci Alpha Max: 16 |
The E-commerce indicator. Possible/ expected values: ECOMMERCE |
| authorization_code Alphanumeric Max: 100 |
The authorization code returned from the 3rd party. Example: P1000000000000372136 |
| order_description Alphanumeric Max: 150 |
It holds the description of the order. Example: iPhone 6-S |
| response_message Alphanumeric Max: 150 |
The message description of the response code; it returns according to the request language. Possible/ expected values: Please refer to section messages |
| response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
| status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
| customer_ip Alphanumeric max: 45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf |
| expiry_date Numeric Max: 4 |
The card’s expiry date. Example: 2105 |
| card_number Numeric Max: 16 |
The masked credit card’s number. Only the MEEZA payment option takes 19 digits card number. *AMEX payment option takes 15 digits card number. *Otherwise, they take 16 digits card number. Example: 400555*****0001 |
| customer_name Alpha Max: 40 |
The customer’s name. Example: John Smith |
| phone_number Alphanumeric max: 19 |
The customer’s phone number. Example: 00962797219966 |
| settlement_reference Alphanumeric max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 |
| merchant_extra Alphanumeric Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
| merchant_extra1 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
| merchant_extra2 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
| merchant_extra3 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
| merchant_extra5 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
Using Safe service (tokenization) with the iOS SDK
You can use tokenization service through the iOS SDK through the below steps:
1. Your customer enables the remember_me option displayed in the SDK payment page.
2. You process the first authorization or purchased transaction successfully.
3. 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 authorization or purchase transaction.
If your customer wants to update or delete their payment card, you can facilitate the request – view the Update Token section.
Tokenization Sample Code
Objective-C
Swift
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 |
| 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 Optional max: 45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf Special characters: . : |
| customer_name Alpha Optional Max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' Space |
| merchant_extra Alphanumeric Optional Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
| merchant_extra1 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
| merchant_extra2 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
| merchant_extra3 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
| merchant_extra4 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
| merchant_extra5 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
| phone_number Alphanumeric Optional max: 19 |
The customer’s phone number. Example: 00962797219966 Special characters: + - ( ) Space |
Example 1
Example 2
Example 3
Apple Pay Authorization/ Purchase - Response
The following parameters will be returned in 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 |
| 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:
- Swift:
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 |
| 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 Optional max: 45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf Special characters: . : |
| customer_name Alpha Optional Max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' Space |
| phone_number Alphanumeric Optional max: 19 |
The customer’s phone number. Example: 00962797219966 Special characters: + - ( ) Space |
| token_name Alphanumeric Optional max: 100 |
The Token name. Example: Op9Vmp Special characters: - _ . @ |
| settlement_reference Alphanumeric Optional max: 34 |
The Merchant submits 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: . ; / _ - , ' @ |
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 |
| 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 |
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.
Read more about how recurring transactions work here.
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: - _ . |
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 |
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.
Read more about installments here.
Installments Redirection
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 |
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 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 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 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.
Test Environment URL:
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production Environment URL:
https://paymentservices.payfort.com/FortAPI/paymentApi
REST POST request using JSON.
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 |
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). |
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. |
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 |
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 |
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.
The following is sample of a response of an Get Installments Plans API request:
Custom merchant page integration tokenization
Test Environment URL:
https://sbcheckout.payfort.com/FortAPI/paymentPage
Production Environment URL:
https://checkout.payfort.com/FortAPI/paymentPage
HTTPs Form Post 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: $ ! = ? # & - _ / : . |
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 operations
Test Environment URL:
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production Environment URL:
https://paymentservices.payfort.com/FortAPI/paymentApi
REST POST request using JSON.
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: $ ! = ? # & - _ / : . |
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 |
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-containerclass: responsible for the total width of the form container and the background. - The
receipt-containerclass: responsible for the receipt section you can customize / hide it by changing the CSS values - The
full-widthclass: responsible for the plans and switching the view from dropdown to a table. - The
credit-card-containerclass: responsible for the credit card form`s shape look. - The
errorclass: responsible for the error messages. - The
half1, half2class: used to merge the date and CVV fields into one block or each one on block if needed. - The
bankclass: is responsible for the bank agreement section. - The
floatlclass: is the container of each single input field. - The
Payclass: responsible for the submit button. - The
Visa/ MasterCardclasses: used to change the color of the Visa/ MasterCard colors.
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 |
| 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 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 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: $ ! = ? # & - _ / : . |
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 |
| 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 |
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.
Read more about the trusted channel here.
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 |
| 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: $ ! = ? # & - _ / : . |
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 |
| 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 |
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.
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.
You can read more about 3D Secure and Amazon Payment Services on this page.
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.
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.
Read more about Flex 3D Secure here.
Include the following parameter in the Request you will send to Amazon Payment Services:
| ATTRIBUTES | Description |
|---|---|
| flex_value Alphanumeric Optional max: 255 |
This parameter reflects the custom field value you had configure in the Back-office. *Only English values are applicable. Example: Sale50 Special characters: _ / \ - . # $ % & @ * |
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.
Read more about external 3D Secure here.
Test Environment URL:
https://sbpaymentservices.PayFort.com/FortAPI/paymentApi
Production Environment URL:
https://paymentservices.PayFort.com/FortAPI/paymentApi
REST POST request using JSON.
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 |
| 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 Optional Max: 28 |
Unique transaction Identification number to identify the 3DS transaction. Example: 6kQGHEiZDU0H4+mUWF7zELHAcqM= |
| 3ds_enrolled Alpha Optional Max: 1 |
Parameter that hold if the card is enrolled or not. Possible/ expected values: - Y (Yes) - N (No) |
| 3ds_status Alpha Optional 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 Optional Max: 2 |
The eCommerce indicator returned from the MPI. Possible/ expected values: - 05 - 06 |
| ver_token Alphanumeric Optional 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: $ ! = ? # & - _ / : . |
The following parameters will be returned in Amazon Payment Services’ response:
| ATTRIBUTES | Description |
|---|---|
| command Alpha Mandatory max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE |
| 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.
Read more about standalone 3D Secure here.
Test Environment URL:
https://sbpaymentservices.PayFort.com/FortAPI/paymentApi
Production Environment URL:
https://paymentservices.PayFort.com/FortAPI/paymentApi
REST POST request using JSON.
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 |
3D Secure Enrollment Request Example!
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 |
| 3ds_xid Alphanumeric max: 28 |
Unique transaction Identification number to identify the 3DS transaction. Example: 6kQGHEiZDU0H4+mUWF7zELHAcqM= |
| 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 |
3D Secure Enrollment Response Example!
• 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 “MIGS” processor; Copy the returned 3ds_url in a new browser. Then, select all the returned parameters to be send in the next request “3Ds Authentication”.
- In case you are on “Cybersource”/ “MPGS” processor; two parameters will returns in the “3Ds Enrollment”; as below:
• MD
• PaRes
And you have to copy them in the “3Ds Authentication” request; as you will see in the 3Ds Authentication request example.
Test Environment URL:
https://sbpaymentservices.PayFort.com/FortAPI/paymentApi
Production Environment URL:
https://paymentservices.PayFort.com/FortAPI/paymentApi
REST POST request using JSON.
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 MIGS processor Example!
3D Secure Authentication Request on Cybersource/ MPGS Processors Example!
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_xid Alphanumeric Max: 28 |
Unique transaction Identification number to identify the 3DS transaction. Example: 6kQGHEiZDU0H4+mUWF7zELHAcqM= |
| 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 MIGS Processor Example!
3D Secure Authentication Response on Cybersource/ MPGS Processors Example!
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.
Test Environment URL:
https://sbpaymentservices.PayFort.com/FortAPI/paymentApi
Production Environment URL:
https://paymentservices.PayFort.com/FortAPI/paymentApi
REST POST request using JSON.
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 |
3D Secure Enrollment Request Example!
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 |
| 3ds_xid Alphanumeric max: 28 |
Unique transaction Identification number to identify the 3DS transaction. Example: 6kQGHEiZDU0H4+mUWF7zELHAcqM= |
| 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 “MIGS” processor; Copy the returned 3ds_url in a new browser. Then, select all the returned parameters to be send in the next request “3D Secure Authentication”.
- In case you are on “Cybersource”/ “MPGS” processor; two parameters will returns in the “3D Secure Enrollment”; as below:
• MD
• PaRes
And you have to copy them in the “3D Secure Authentication” request; as you will see in the 3Ds Authentication request example.
Test Environment URL:
https://sbpaymentservices.PayFort.com/FortAPI/paymentApi
Production Environment URL:
https://paymentservices.PayFort.com/FortAPI/paymentApi
REST POST request using JSON.
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 MIGS processor Example!
3D Secure Authentication Request on Cybersource/ MPGS Processors Example!
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_xid Alphanumeric Max: 28 |
Unique transaction Identification number to identify the 3DS transaction. Example: 6kQGHEiZDU0H4+mUWF7zELHAcqM= |
| 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 MIGS Processor Example!
3D Secure Authentication Response on Cybersource/ MPGS Processors Example!
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.
Read more about Protect Plus here.
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 + * 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.
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, Masterpass, and Visa Checkout.
Read more about our support for digital wallets here
Masterpass Service
Masterpass is a digital wallet that securely stores your customer’s credit card details and shipping addresses. Masterpass is operated and managed by Mastercard – you can view the Masterpass website here.
Amazon Payment Services now supports Masterpass Redirect v7 in addition to Redirect v6.
Masterpass Redirection
1. You submit a form that includes all the parameters.
You call the following URL to be redirected to Amazon Payment Services:
https://checkout.payfort.com/FortAPI/paymentPage
2. Amazon Payment Services returns a response to you.
3. Amazon Payment Services inserts the response parameters into a JavaScript.
4. A lightbox appears to your customer where they enter their credentials, selects the card type and the shipping address, and clicks “Finish Shopping”.
5. Amazon Payment Services proceeds with an authorize or purchase transaction based on the value of the command parameter sent in the Merchant’s form.
6. Amazon Payment Services returns a response to the Merchant.(Please refer to section Masterpass Service - Response for the Response Parameters).
Test Environment URL:
 https://sbcheckout.payfort.com/FortAPI/paymentPage
Production Environment URL:
 https://checkout.payfort.com/FortAPI/paymentPage
HTTPs Form Post Request.
(Please take a look at the Request Example on the right side of the page.)
Include the following parameters in the Request you will send to Amazon Payment Services:
Masterpass Request Example
<form action="https://sbcheckout.payfort.com/FortAPI/paymentPage"method="post"id="simulatorForm">
<input type="hidden" name="digital_wallet" id="digital_wallet" value="MASTERPASS"/>
<input type="hidden" name="command"id="command" value="AUTHORIZATION"/>
<input type="hidden" name="access_code" id="access_code" value="zx0IPmPy5jp1vAz"/>
<input type="hidden" name="merchant_identifier" id="merchant_identifier" value="CycHZxVj"/>
<input type="hidden" name="merchant_reference" id="merchant_reference" value="XYZ9239-yu898"/>
<input type="hidden" name="amount" id="amount" value="10000"/>
<input type="hidden" name="currency" id="currency" value="AED"/>
<input type="hidden" name="language" id="language" value="en"/>
<input type="hidden" name="customer_email" id="customer_email" value="someone@email.com"/>
<input type="hidden" name="signature" id="signature" value="7cad05f0212ed933c9a5d5dffa31661acf2c827a"/>
<input type="hidden" name="payment_option"id="payment_option" value="VISA"/>
<input type="hidden" name="order_description" id="order_description" value="iPhone 6-S"/>
<input type="hidden" name="customer_ip" id="customer_ip" value="192.178.1.10"/>
<input type="hidden" name="customer_name" id="customer_name" value="John Smith"/>
<input type="hidden" name="cart_details" id="cart_details" value='{"sub_total":"900","cart_items":[{"item_description":"Xbox","item_image":"https://image.com","item_name":"Xbo x 360","item_price":"300","item_quantity":"2"},{"item_description":"Playstation 3","item_image":"https://image.com","item_name":"Playstation 3","item_price":"150","item_quantity":"2"}]}'/>
<input type="hidden" name="return_url" id="return_url" value="https://backtothemerchanturl.com"/>
<input value="Send" type="submit"> </form>
| ATTRIBUTES | Description |
|---|---|
| digital_wallet Alpha Mandatory max: 100 |
The buyer’s digital wallet. Possible/ expected values: MASTERPASS |
| command Alpha Mandatory max: 20 |
Command. Possible/ expected values: AUTHORIZATION, 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: _ - . @ + |
| cart_details Alphanumeric Mandatory 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 check the note below the table. Special characters: $ |
| cart_items Alphanumeric Mandatory max: 999 |
The items of the shopping cart. Example: Tshirt Special characters: $ |
| item_price Numeric Mandatory max: 10 |
The price of a cart item. Example: 700 |
| sub_total Numeric Mandatory max: 10 |
The total price of the cart items. Example: 550 |
| item_description Alphanumeric Mandatory max: 256 |
A description of a cart’s item. Example: iPhone 6-S Special characters: - _ ' , . Space |
| item_image Alphanumeric Mandatory max: 500 |
A URL to the item’s image. Example: https://www.image.com Special characters: # / : . = ? & - _ |
| item_name Alphanumeric Mandatory max: 100 |
The name of an item in the shopping cart. Example: Item1 Special characters: Space |
| item_quantity Alphanumeric Mandatory max: 10 |
The quantity of a cart item. Example: 4 |
| signature Alphanumeric Mandatory max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
| order_description Alphanumeric Optional Max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
| payment_option Alpha Optional max: 10 |
Payment Option. Possible/ expected values: MASTERCARD, VISA |
| 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 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: $ ! = ? # & - _ / : . |
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: MASTERPASS |
| command Alpha max: 20 |
Command. Possible/ expected values: AUTHORIZATION, 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 |
| cart_details Alphanumeric max: 999 |
This parameter is a parent parameter for other parameters that contain the details of the shopping cart created by the Merchant. |
| cart_items Alphanumeric max: 999 |
The items of the shopping cart. Example: Tshirt |
| item_price Numeric max: 10 |
The price of a cart item. Example: 700 |
| sub_total Numeric max: 10 |
The total price of the cart items. Example: 550 |
| item_description Alphanumeric max: 256 |
A description of a cart’s item. Example: iPhone 6-S |
| item_image Alphanumeric max: 500 |
A URL to the item’s image. Example: https://www.image.com |
| item_name Alphanumeric max: 100 |
The name of an item in the shopping cart. Example: Item1 |
| item_quantity Alphanumeric max: 10 |
The quantity of a cart item. Example: 4 |
| signature Alphanumeric max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
| order_description Alphanumeric Max: 150 |
It holds the description of the order. Example: iPhone 6-S |
| payment_option Alpha max: 10 |
Payment Option. Possible/ expected values: MASTERCARD, VISA |
| 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 |
| 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 |
| authorization_code Alphanumeric Max: 100 |
The authorization code returned from the 3rd party. Example: P1000000000000372136 |
| 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 |
| lightbox_callback_url Alphanumeric max: 400 |
The URL where Masterpass is redirected to Amazon Payment Services. |
| lightbox_merchant_checkout_id Alphanumeric max: 100 |
When a Merchant is added to Masterpass, Masterpass generates this ID. Example: a4a6w4cmliej1igb8j5ha1igi4spzo4xxx |
| lightbox_version Alphanumeric max: 5 |
The lightbox version to determine which version to be used. Example: V2 |
| lightbox_allowed_card_types Alpha max: 150 |
The card types supported by the Merchant. (A Masterpass parameter). Example: MasterCard |
| lightbox_request_token Alphanumeric max: 100 |
A Token sent by Masterpass to identify the lightbox transaction. (A Masterpass parameter). Example: 61c593e2b3524bc7694f893098cbb6dc8611b63a |
| 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 |
Masterpass Hosted
Instead of redirecting your customers to a Masterpass lightbox, you can make use of Masterpass Hosted to process digital wallet transactions without redirecting your customer to the Masterpass page. Instead, the Masterpass authentication process is hosted on your merchant website.
Test Environment URL:
 https://sbcheckout.payfort.com/FortAPI/paymentPage
Production Environment URL:
 https://checkout.payfort.com/FortAPI/paymentPage
REST POST request using JSON.
(Please take a look at the Request Example on the right side of the page.)
Include the following parameters in the Request you will send to Amazon Payment Services:
Masterpass Request Example
<form action="https://sbcheckout.payfort.com/FortAPI/paymentPage"method="post"id="simulatorForm">
<input type="hidden" name="digital_wallet" id="digital_wallet" value="MASTERPASS"/>
<input type="hidden" name="command"id="command" value="AUTHORIZATION"/>
<input type="hidden" name="access_code" id="access_code" value="zx0IPmPy5jp1vAz"/>
<input type="hidden" name="merchant_identifier" id="merchant_identifier" value="CycHZxVj"/>
<input type="hidden" name="merchant_reference" id="merchant_reference" value="XYZ9239-yu898"/>
<input type="hidden" name="amount" id="amount" value="10000"/>
<input type="hidden" name="currency" id="currency" value="AED"/>
<input type="hidden" name="language" id="language" value="en"/>
<input type="hidden" name="customer_email" id="customer_email" value="someone@email.com"/>
<input type="hidden" name="signature" id="signature" value="7cad05f0212ed933c9a5d5dffa31661acf2c827a"/>
<input type="hidden" name="payment_option"id="payment_option" value="VISA"/>
<input type="hidden" name="order_description" id="order_description" value="iPhone 6-S"/>
<input type="hidden" name="customer_ip" id="customer_ip" value="192.178.1.10"/>
<input type="hidden" name="oauth_verifier" id="oauth_verifier" value="ed91ead4afaa0c00673fe771c1027f247f7ddf04"/>
<input type="hidden" name="customer_name" id="customer_name" value="John Smith"/>
<input type="hidden" name="cart_details" id="cart_details" value='{"sub_total":"900","cart_items":[{"item_description":"Xbox","item_image":"https://image.com","item_name":"Xbo x 360","item_price":"300","item_quantity":"2"},{"item_description":"Playstation 3","item_image":"https://image.com","item_name":"Playstation 3","item_price":"150","item_quantity":"2"}]}'/>
<input type="hidden" name="return_url" id="return_url" value="https://backtothemerchanturl.com"/>
<input value="Send" type="submit"> </form>
| ATTRIBUTES | Description |
|---|---|
| digital_wallet Alpha Mandatory max: 100 |
The buyer’s digital wallet. Possible/ expected values: MASTERPASS |
| command Alpha Mandatory max: 20 |
Command. Possible/ expected values: AUTHORIZATION, 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: _ - . @ + |
| oauth_verifier Alphanumeric Mandatory max: 100 |
Masterpass transaction ID, returned by Masterpass light box response. Example: ed91ead4afaa0c00673fe771c1027f247f7ddf04 |
| cart_details Alphanumeric Mandatory 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 check the note below the table. Special characters: $ |
| cart_items Alphanumeric Mandatory max: 999 |
The items of the shopping cart. Example: Tshirt Special characters: $ |
| item_price Numeric Mandatory max: 10 |
The price of a cart item. Example: 700 |
| sub_total Numeric Mandatory max: 10 |
The total price of the cart items. Example: 550 |
| item_description Alphanumeric Mandatory max: 256 |
A description of a cart’s item. Example: iPhone 6-S Special characters: - _ ' , . Space |
| item_image Alphanumeric Mandatory max: 500 |
A URL to the item’s image. Example: https://www.image.com Special characters: # / : . = ? & - _ |
| item_name Alphanumeric Mandatory max: 100 |
The name of an item in the shopping cart. Example: Item1 Special characters: Space |
| item_quantity Alphanumeric Mandatory max: 10 |
The quantity of a cart item. Example: 4 |
| signature Alphanumeric Mandatory max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
| order_description Alphanumeric Optional Max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
| payment_option Alpha Optional max: 10 |
Payment Option. Possible/ expected values: MASTERCARD, VISA |
| 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 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: $ ! = ? # & - _ / : . |
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: MASTERPASS |
| command Alpha max: 20 |
Command. Possible/ expected values: AUTHORIZATION, 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 |
| oauth_verifier Alphanumeric max: 100 |
Masterpass transaction ID, returned by Masterpass light box response. Example: ed91ead4afaa0c00673fe771c1027f247f7ddf04 |
| cart_details Alphanumeric max: 999 |
This parameter is a parent parameter for other parameters that contain the details of the shopping cart created by the Merchant. |
| cart_items Alphanumeric max: 999 |
The items of the shopping cart. Example: Tshirt |
| item_price Numeric max: 10 |
The price of a cart item. Example: 700 |
| sub_total Numeric max: 10 |
The total price of the cart items. Example: 550 |
| item_description Alphanumeric max: 256 |
A description of a cart’s item. Example: iPhone 6-S |
| item_image Alphanumeric max: 500 |
A URL to the item’s image. Example: https://www.image.com |
| item_name Alphanumeric max: 100 |
The name of an item in the shopping cart. Example: Item1 |
| item_quantity Alphanumeric max: 10 |
The quantity of a cart item. Example: 4 |
| signature Alphanumeric max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
| order_description Alphanumeric Max: 150 |
It holds the description of the order. Example: iPhone 6-S |
| payment_option Alpha max: 10 |
Payment Option. Possible/ expected values: MASTERCARD, VISA |
| 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 |
| 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 |
| authorization_code Alphanumeric Max: 100 |
The authorization code returned from the 3rd party. Example: P1000000000000372136 |
| 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 |
| lightbox_callback_url Alphanumeric max: 400 |
The URL where Masterpass is redirected to Amazon Payment Services. |
| lightbox_merchant_checkout_id Alphanumeric max: 100 |
When a Merchant is added to Masterpass, Masterpass generates this ID. Example: a4a6w4cmliej1igb8j5ha1igi4spzo4xxx |
| lightbox_version Alphanumeric max: 5 |
The lightbox version to determine which version to be used. Example: V2 |
| lightbox_allowed_card_types Alpha max: 150 |
The card types supported by the Merchant. (A Masterpass parameter). Example: MasterCard |
| lightbox_request_token Alphanumeric max: 100 |
A Token sent by Masterpass to identify the lightbox transaction. (A Masterpass parameter). Example: 61c593e2b3524bc7694f893098cbb6dc8611b63a |
| 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 |
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
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.
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:
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 |
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.
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: _ |
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 |
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.
Read more about generating invoices using Collect
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 - 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 |
| 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 - 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 |
| 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 |
| 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 |
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.
Read more about batch processing here
Before Starting
Before starting you have to know the following:
1. You’re only allowed to send one of the following transactions in your batch file or a mixture of them:
* Recurring: PURCHASE command.
* Maintenance operations (capture, refund, and void authorization): after completing a successful Authorization or Purchase transactions through one of Amazon Payment Services’ channels.
2. You must activate the batch processing service before attempting to upload a batch file.
How it works - Steps
1. Upload 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 file and to check that the merchant reference for each and every transaction is unique.
3. Process Batch File:
In this last step you initiate the processing of the transactions in the batch file. In order to start the processing; the file you submitted should have been validated and passed the validation process.
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.
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.
Before Starting
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.
How it Works
1. Upload Invoicing Batch File:
With this request you upload the invoice batch file to Amazon Payment Services. You can download the invoice batch file template from your back office.
2. Get Invoicing 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 Invoicing 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.
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.
Read more about the reporting API here
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
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
Download Report “XML” Response Example
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).
- Amazon Payment Services returns the “Get Report” response including the records you requested.
- 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
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
Get Report “XML” Response Example
Verify Service Command
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.
Read more about the verify service.
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
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.
Read more about tokenization here
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.
Read more about the create token service here.
Test Environment URL:
https://sbcheckout.PayFort.com/FortAPI/paymentPage
Production Environment URL:
https://checkout.PayFort.com/FortAPI/paymentPage
HTTPs Form Post 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: ' - . |
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 Amazon Payment Services. For example, your customer’s payment card details may change over time. This service enables you to update your card associated with a token and the status of a token via API calls.
Read more about updating tokens.
Test Environment URL:
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production Environment URL:
https://paymentservices.payfort.com/FortAPI/paymentApi
REST POST request using JSON.
Include the following parameters in the Request you send to Amazon Payment Services:
| ATTRIBUTES | Description |
|---|---|
| service_command Alpha Mandatory Max: 20 |
Command. Possible/ expected values: UPDATE_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 |
| 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 |
| 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 |
| card_holder_name Alpha Optional Max: 50 |
The card holder name. Example: John Smith Special characters: ' - . |
| currency Alpha Optional Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: USD |
| token_status Alpha Optional Max: 8 |
Presents the token status. Possible/ expected values: - ACTIVE - INACTIVE |
| new_token_name Alphanumeric Optional Max: 100 |
The new name used to update the existing token. Example: Test1 Special characters: _ - @ . |
The following parameters will be returned in Amazon Payment Services’s response:
| ATTRIBUTES | Description |
|---|---|
| service_command Alpha Max: 20 |
Command. Possible/ expected values: UPDATE_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 |
| 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 Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
| 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 |
| card_holder_name Alpha Max: 50 |
The card holder name. Example: John Smith |
| currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: USD |
| 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: 58000 |
| token_status Alpha Max: 8 |
Presents the token status. Possible/ expected values: -ACTIVE -INACTIVE |
| creation_date Alphanumeric Max: 30 |
Creation date of content in UTC format. Example: 2017-03-13T10:09:19+02:00 |
| card_brand Alpha Max: 10 |
Issuer account type. Possible/ expected values: - MASTERCARD - VISA - AMEX |
| 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 |
| status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
Live currency conversion
You can use our live currency conversion service to dynamically render prices in your customer’s local currency, making it much easier for your customers to shop without the need to constantly convert between currencies.
When you use live currency conversion from Amazon Payment Services you rely on us to automatically convert the prices you hold on your server, in your domestic currency, into the local currency of your customer.
Read more about live currency conversion.
Currency Exchange 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.
Currency Exchange - 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: CURRENCY_CONVERSION 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 |
| 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 |
| language Alpha Mandatory max: 2 |
The checkout page and messages language. Possible/ expected values: en / ar |
| converted_currency Alpha Mandatory max: 3 |
The ISO3 currency code of the currency you are converting the amount to. Example: AED |
| signature Alphanumeric Mandatory max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
Currency Exchange - Response
The following parameters will be returned in Amazon Payment Services’ response:
| ATTRIBUTES | Description |
|---|---|
| service_command Alpha max: 20 |
Command. Possible/ expected values: CURRENCY_CONVERSION |
| access_code Alphanumeric max: 20 |
Access code. Example: zx0IPmPy5jp1vAz |
| merchant_identifier Alphanumeric max: 20 |
The ID of the Merchant. Example: CycHZxVj |
| amount Numeric max: 10 |
The transaction’s amount. Example: 10000 |
| currency Alpha max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: USD |
| language Alpha max: 2 |
The checkout page and messages language. Possible/ expected values: en / ar |
| signature Alphanumeric max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
| response_message Alphanumeric max: 150 |
Message description of the response code. It returns according to the request language. Possible/ expected values: (Please refer to section messages). |
| response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
| status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: (Please refer to section statuses). |
| converted_amount Alpha max: 3 |
The amount after converting to another currency. Example: 100 USD = 367.298 AED |
| converted_currency Alpha max: 3 |
The ISO3 currency code of the currency you are converting the amount to. Example: AED |
| conversion_number Alphanumeric max: 20 |
A unique number generated by Amazon Payment Services for every valid currency conversion request. Example: 1443796866848 |
In common
Query Operations
A type of query that can be requested through our system, which includes the “Check Status” query.
Check Status
If you need to verify the status of a transaction in progress you can easily do so using the check status command.
With check status you can verify whether a transaction was completed successfully, check the authorized amount on a transaction, and verify the response generated when the transaction was processed.
Check Status 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 - Request
(Please take a look at the Check Status Request Example on the right side of the page.)
Check Status Request Example
curl -H "Content-Type: application/json" -d
'{"query_command":"CHECK_STATUS","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":" XYZ9239-yu898 ","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a"}'
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'query_command' => 'CHECK_STATUS',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'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>";
String jsonRequestString = "{\"query_command\" : \"CHECK_STATUS\" \"access_code\" : \"zx0IPmPy5jp1vAz8Kpg7\", \"merchant_identifier\" : \"CycHZxVj\","
+ "\"merchant_reference\" : \"XYZ9239-yu898\", \"language\" : \"en\", "
+ "\"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());
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'query_command' : 'CHECK_STATUS',
'access_code' : 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' : 'CycHZxVj',
'merchant_reference' : 'XYZ9239-yu898',
'language' : 'en',
'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'
require 'json'
require 'net/http'
require 'net/https'
require 'uri'
require 'openssl'
arrData = {
'query_command' => 'CHECK_STATUS',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'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)
Include the following parameters in the request you send to Amazon Payment Services:
| ATTRIBUTES | Description |
|---|---|
| query_command Alpha Mandatory max: 50 |
The query operations command. Possible/ expected values: CHECK_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 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 |
| fort_id Numeric Optional Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
| return_third_party_response_codes Alpha Optional Max: 3 |
This parameter allows you to return the 3rd party response codes in the transaction’s response. Possible/ expected values: - YES - NO |
Check Status - Response
(Please take a look at the Check Status Example Response on the right side of the page.)
Check Status Response Example
{"query_command":"CHECK_STATUS","access_code":"s31bpM1ebfNnwqo","merchant_identifier":"FD1Ptq","merchant_reference":"141127176","language":"en","signature":"90f7092923c9eea8b0df6d509453a1791a36e2cd4a80eaef366e235b169a40e0","fort_id":"21722423333","response_message":"Success","response_code":"12000","status":"12","transaction_status":"12","transaction_code":"12000","transaction_message":"Success"}
{"query_command":"CHECK_STATUS","access_code":"s31bpM1ebfNnwqo","merchant_identifier":"FD1Ptq","merchant_reference":"141127176","language":"en","signature":"90f7092923c9eea8b0df6d509453a1791a36e2cd4a80eaef366e235b169a40e0","fort_id":"21722423333","response_message":"Success","response_code":"12000","status":"12","transaction_status":"12","transaction_code":"12000","transaction_message":"Success"}
{"query_command":"CHECK_STATUS","access_code":"s31bpM1ebfNnwqo","merchant_identifier":"FD1Ptq","merchant_reference":"141127176","language":"en","signature":"90f7092923c9eea8b0df6d509453a1791a36e2cd4a80eaef366e235b169a40e0","fort_id":"21722423333","response_message":"Success","response_code":"12000","status":"12","transaction_status":"12","transaction_code":"12000","transaction_message":"Success"}
{"query_command":"CHECK_STATUS","access_code":"s31bpM1ebfNnwqo","merchant_identifier":"FD1Ptq","merchant_reference":"141127176","language":"en","signature":"90f7092923c9eea8b0df6d509453a1791a36e2cd4a80eaef366e235b169a40e0","fort_id":"21722423333","response_message":"Success","response_code":"12000","status":"12","transaction_status":"12","transaction_code":"12000","transaction_message":"Success"}
{"query_command":"CHECK_STATUS","access_code":"s31bpM1ebfNnwqo","merchant_identifier":"FD1Ptq","merchant_reference":"141127176","language":"en","signature":"90f7092923c9eea8b0df6d509453a1791a36e2cd4a80eaef366e235b169a40e0","fort_id":"21722423333","response_message":"Success","response_code":"12000","status":"12","transaction_status":"12","transaction_code":"12000","transaction_message":"Success"}
The following parameters will be returned in Amazon Payment Services’ response:
| ATTRIBUTES | Description |
|---|---|
| query_command Alpha max: 50 |
The query operations command. Possible/ expected values: CHECK_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 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 |
| 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 |
| transaction_status Numeric Max: 2 |
The status of the last operation performed on a specific order. Possible/ expected values: Please refer to section statuses |
| transaction_code Numeric Max: 5 |
The message code returned for the last operation performed on a specific order. Possible/ expected values: Please refer to section messages |
| transaction_message Alphanumeric Max: 150 |
The message returned for the last operation performed on a specific order. Example: Success |
| refunded_amount Numeric Max: 10 |
The total refunded amount for the order. Example: 10000 |
| captured_amount Numeric Max: 10 |
The total captured amount for the order. Example: 10000 |
| authorized_amount Numeric Max: 10 |
The total authorized amount for the order. Example: 10000 |
| authorization_code Alphanumeric Max: 100 |
Authorization Code returned from the 3rd party. Example: 017201 |
| processor_response_code Alphanumeric Max: 100 |
Response code returns from the Processor. Example: APPROVED |
| acquirer_response_code Alphanumeric Max: 10 |
Response code returns from the Acquirer. Example: 00 |
Services Activation
Services are activated for our merchants by our back-office team. You can view the services activated for your merchant account by opening your merchant account and clicking “Payment Stack” under the Services tab.
The additional services provided by Amazon Payment Services are:
- Fraud Prevention.
- 3-D Secure.
- Installments.
- Tokenization.
- Batch service.
Signature
The Signature is a parameter that holds the digital signature value calculated by the SHA algorithm. The digital signature is used to authenticate the sender and receiver of the message and allows the receiver to verify the integrity of the message.
Message Digest
| Name | Description |
|---|---|
| SHA Type | The Secure Hash Algorithm is a family of cryptographic hash functions published by the National Institute of Standards as a US Federal information processing standard (FIPS) including: SHA-0, SHA-2, and SHA-3. Values: SHA-256, SHA 512, and SHA-128 (not recommended). |
| SHA Request Phrase | This value is used when the Merchant generates the request signature. Values: Dynamic value defined by the Merchant. |
| SHA Response Phrase | This value is used by our system to generate the response signature for the Merchant’s Request. Values: Dynamic value defined by the Merchant. |
Signature Pattern
The below steps describe how you generate a signature pattern:
Sort all Amazon Payment Services request parameters (both mandatory and optional) in an ascending alphabetical order based on the parameters names.
Concatenate the parameter name with the value separated by ’=’ (param_name=param_value).
Concatenate all the parameters directly without any separator. (param_name1=param_value1param_name2=param_value2).
Add the Merchant’s Passphrase at the beginning and end of the parameters string. (REQUESTPHRASEparam_name1=param_value1param_name2=param_value2RE QUESTPHRASE).
Use the SHA or HMAC SHA function to generate the SHA or HMAC SHA value of the resulted string depending on the type of SHA or HMAC SHA selected by the Merchant.
Create Signature Value
<?php
// How to calculate request signature
$shaString = '';
// array request
$arrData = array(
'command' =>'AUTHORIZATION',
'access_code' =>'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier'=>'CycHZxVj',
'merchant_reference' =>'XYZ9239-yu898',
'amount' =>'10000',
'currency' =>'AED',
'language' =>'en',
'customer_email' =>'test@payfort.com',
'order_description' =>'iPhone 6-S',
);
// sort an array by key
ksort($arrData);
foreach ($arrData 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("YOUR_SHA_TYPE", $shaString);
// your request signature
echo $signature;
?>
Map<String, Object>requestMap = new HashedMap();
requestMap.put("command", "PURCHASE");
requestMap.put("merchant_reference", "Test010");
requestMap.put("amount", "1000");
requestMap.put("access_code", "SILgpo7pWbmzuURp2qri");
requestMap.put("merchant_identifier", "MxvOupuG");
requestMap.put("currency", "USD");
requestMap.put("language", "en");
requestMap.put("customer_email", "test@gmail.com");
//order by key
requestMap = requestMap.entrySet().stream().sorted(Map.Entry.comparingByKey())
.collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue,
(oldValue, newValue) -> oldValue, LinkedHashMap::new));
String requestString = "PASS";
for(Entry<String, Object> entry: requestMap.entrySet())
requestString += entry.getKey() + "=" + entry.getValue();
requestString+= "PASS";
MessageDigest digest = MessageDigest.getInstance("SHA-256");
byte[] hashed = digest.digest(requestString.getBytes(StandardCharsets.UTF_8));
String signature = javax.xml.bind.DatatypeConverter.printHexBinary(hashed);
In this section, you can find examples on how to create the signature value for request and response messages. Please note that all values mentioned in the examples are fictitious.
The following is an example of the Request Parameters:
- signature = b88db48baaa600c3fadac502c75a832e3470029f
- command = PURCHASE
- merchant_reference = Test010
- amount = 1000
- access_code = SILgpo7pWbmzuURp2qri
- merchant_identifier = MxvOupuG
- currency = USD
- language = en
- customer_email = test@gmail.com
Below are the Merchant signature settings from the back-office:
- SHA Request Phrase: PASS.
- SHA-Type: SHA-256.
After sorting the parameters and completing step 4 of the Signature Pattern, the result will be the following concatenated string:
After applying step 5 of the Signature Pattern, the result will be as follows:
- HMAC Request key: value of SHA Request Phrase from BackOffice Security Settings.
HMAC Response key: value of SHA Response Phrase from BackOffice Security Settings.
HMAC Sample
Request signature = hmac(‘sha512’, Concatenated string from step 4, SHA Request Phrase from backoffice).
Response signature = hmac('sha512’, Concatenated string from step 4, SHA Response Phrase from BackOffice).
Note : You Can select your SHA Type [HMAC 256 or HMAC 512] from your account on BackOffice Security Settings.
The following is an example for the custom merchant page integration request signature calculations:
Assume you have the below parameters included in the request of Merchant Page 2.0:
- service_command = TOKENIZATION
- language = en
- merchant_identifier = MxvOupuG
- access_code = SILgpo7pWbmzuURp2qri
- merchant_reference = MyReference0001
- card_security_code = 123
- card_number = 4005550000000001
- expiry_date = 2105
- remember_me = YES
- card_holder_name = John Smith
Below are the merchant signature settings from the back-office:
- SHA Request Phrase: PASS.
- SHA-Type: SHA-256.
The string to hash should be prepared for the above request is the following step 4 of the Signature Pattern:
After applying step 5 of the Signature Pattern, the result will be as follows:
*The following is an example for the Reporting API request signature calculations: *
*Assume you have the below parameters included in the request of Reporting API: *
• query_command = GENERATE_REPORT • access_code = zx0IPmPy5jp1vAz8Kpg7 • merchant_identifier = CycHZxVj • merchant_reference = XYZ9239-yu898 • 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}] • from_date = 2017-08-03T00:00:01+03:00 • to_date = 2017-08-03T23:59:59+03:00 • response_format = JSON • language = en
Below are the merchant signature settings from the back-office:
- SHA Request Phrase: PASS.
- SHA-Type: SHA-256.
The string to hash should be prepared for the above request is the following step 4 of the Signature Pattern:
After applying step 5 of the Signature Pattern, the result will be as follows:
Amazon Payment Services Gateway includes the signature in the response so you can check the integrity of the received data. You do this by calculating the secure hash using the above method, then comparing your calculation with the value you received from Amazon Payment Services Gateway. If the values match, then you can be assured that we received the data you sent, and you received the data we sent.
Try It Yourself
<?php
// How to calculate request signature
$shaString = '';
// array request
$arrData = array(
'command' =>'AUTHORIZATION',
'access_code' =>'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier'=>'CycHZxVj',
'merchant_reference' =>'XYZ9239-yu898',
'amount' =>'10000',
'currency' =>'AED',
'language' =>'en',
'customer_email' =>'test@payfort.com',
'order_description' =>'iPhone 6-S',
);
// sort an array by key
ksort($arrData);
foreach ($arrData 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("YOUR_SHA_TYPE", $shaString);
// your request signature
echo $signature;
?>
Map<String, Object>requestMap = new HashedMap();
requestMap.put("command", "PURCHASE");
requestMap.put("merchant_reference", "Test010");
requestMap.put("amount", "1000");
requestMap.put("access_code", "SILgpo7pWbmzuURp2qri");
requestMap.put("merchant_identifier", "MxvOupuG");
requestMap.put("currency", "USD");
requestMap.put("language", "en");
requestMap.put("customer_email", "test@gmail.com");
//order by key
requestMap = requestMap.entrySet().stream().sorted(Map.Entry.comparingByKey())
.collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue,
(oldValue, newValue) -> oldValue, LinkedHashMap::new));
String requestString = "PASS";
for(Entry<String, Object> entry: requestMap.entrySet())
requestString += entry.getKey() + "=" + entry.getValue();
requestString+= "PASS";
MessageDigest digest = MessageDigest.getInstance("SHA-256");
byte[] hashed = digest.digest(requestString.getBytes(StandardCharsets.UTF_8));
String signature = javax.xml.bind.DatatypeConverter.printHexBinary(hashed);
In this section, you can create the concatenated string to calculate signature value for request and response messages. Please note that you need to replace “PASS” phrase with yours.
Amazon Payment Services XML Response Builder
Through this section you can discover our service that enables you to receive the Amazon Payment Services response in XML format.
Structure
The XML response builder results specifications are:
1. The root node name is ‘response’.
2. The FORT_PARAMETER of type “List” has a special tag name format; where the parent node tag name format is:
<FORT_PARAMETER + “_list”>
3. The list child nodes tag name’s is the name of the parameter name itself.
Sample Code
Transactions Response Codes
The response code is made up of 5 digits; a combination of a 2-digit status (Please see section statuses) and a 3-digit message (Please see section messages).
Statuses
| Status Code | Description |
|---|---|
| 00 | Invalid Request. |
| 01 | Order Stored. |
| 02 | Authorization Success. |
| 03 | Authorization Failed. |
| 04 | Capture Success. |
| 05 | Capture failed. |
| 06 | Refund Success. |
| 07 | Refund Failed. |
| 08 | Authorization Voided Successfully. |
| 09 | Authorization Void Failed. |
| 10 | Incomplete. |
| 11 | Check status Failed. |
| 12 | Check status success. |
| 13 | Purchase Failure. |
| 14 | Purchase Success. |
| 15 | Uncertain Transaction. |
| 17 | Tokenization failed. |
| 18 | Tokenization success. |
| 19 | Transaction pending. |
| 20 | On hold. |
| 21 | SDK Token creation failure. |
| 22 | SDK Token creation success. |
| 23 | Failed to process Digital Wallet service. |
| 24 | Digital wallet order processed successfully. |
| 27 | Check card balance failed. |
| 28 | Check card balance success. |
| 29 | Redemption failed. |
| 30 | Redemption success. |
| 31 | Reverse Redemption transaction failed. |
| 32 | Reverse Redemption transaction success. |
| 40 | Transaction In review. |
| 42 | Currency conversion success. |
| 43 | Currency conversion failed. |
| 44 | 3ds success. |
| 45 | 3ds failed. |
| 46 | Bill creation success. |
| 47 | Bill creation failed. |
| 48 | Generating invoice payment link success. |
| 49 | Generating invoice payment link failed. |
| 50 | Batch file upload successfully. |
| 51 | Upload batch file failed. |
| 52 | Token created successfully. |
| 53 | Token creation failed. |
| 54 | Get Tokens Success. |
| 55 | Get Tokens Failed. |
| 56 | Reporting Request Success. |
| 57 | Reporting Request Failed. |
| 58 | Token updated successfully. |
| 59 | Token updated failed. |
| 62 | Get Installment Plans Successfully. |
| 63 | Get Installment plans Failed. |
| 66 | Delete Token Success. |
| 70 | Get batch results successfully. |
| 71 | Get batch results failed. |
| 72 | Batch processing success. |
| 73 | Batch processing failed. |
| 74 | Bank transfer successfully. |
| 75 | Bank transfer failed. |
| 76 | Batch validation successfully. |
| 77 | Batch validation failed. |
| 80 | Credit card verified successfully. |
| 81 | Failed to verify credit card. |
Messages
| Message Code | Message Value |
|---|---|
| 000 | Success. |
| 001 | Missing parameter. |
| 002 | Invalid parameter format. |
| 003 | Payment option is not available for this merchant’s account. |
| 004 | Invalid command. |
| 005 | Invalid amount. |
| 006 | Technical problem. |
| 007 | Duplicate order number. |
| 008 | Signature mismatch. |
| 009 | Invalid merchant identifier. |
| 010 | Invalid access code. |
| 011 | Order not saved. |
| 012 | Card expired. |
| 013 | Invalid currency. |
| 014 | Inactive payment option. |
| 015 | Inactive merchant account. |
| 016 | Invalid card number. |
| 017 | Operation not allowed by the acquirer. |
| 018 | Operation not allowed by processor. |
| 019 | Inactive acquirer. |
| 020 | Processor is inactive. |
| 021 | Payment option deactivated by acquirer. |
| 023 | Currency not accepted by acquirer. |
| 024 | Currency not accepted by processor. |
| 025 | Processor integration settings are missing. |
| 026 | Acquirer integration settings are missing. |
| 027 | Invalid extra parameters. |
| 029 | Insufficient funds. |
| 030 | Authentication failed. |
| 031 | Invalid issuer. |
| 032 | Invalid parameter length. |
| 033 | Parameter value not allowed. |
| 034 | Operation not allowed. |
| 035 | Order created successfully. |
| 036 | Order not found. |
| 037 | Missing return URL. |
| 038 | Token service inactive. |
| 039 | No active payment option found. |
| 040 | Invalid transaction source. |
| 042 | Operation amount exceeds the authorized amount. |
| 043 | Inactive Operation. |
| 044 | Token name does not exist. |
| 046 | Channel is not configured for the selected payment option. |
| 047 | Order already processed. |
| 048 | Operation amount exceeds captured amount. |
| 049 | Operation not valid for this payment option. |
| 050 | Merchant per transaction limit exceeded. |
| 051 | Technical error. |
| 052 | Consumer is not in OLP database. |
| 053 | Merchant is not found in OLP Engine DB. |
| 054 | Transaction cannot be processed at this moment. |
| 055 | OLP ID Alias is not valid. Please contact your bank. |
| 056 | OLP ID Alias does not exist. Please enter a valid OLP ID Alias. |
| 057 | Transaction amount exceeds the daily transaction limit. |
| 058 | Transaction amount exceeds the per transaction limit. |
| 059 | Merchant Name and SADAD Merchant ID do not match. |
| 060 | The entered OLP password is incorrect. Please provide a valid password. |
| 062 | Token has been created. |
| 063 | Token has been updated. |
| 064 | 3D Secure check requested. |
| 065 | Transaction waiting for customer’s action. |
| 066 | Merchant reference already exists. |
| 067 | Dynamic Descriptor not configured for selected payment option. |
| 068 | SDK service is inactive. |
| 069 | Mapping not found for the given error code. |
| 070 | device_id mismatch. |
| 071 | Failed to initiate connection. |
| 072 | Transaction has been cancelled by the consumer. |
| 073 | Invalid request format. |
| 074 | Transaction failed. |
| 075 | Transaction failed. |
| 076 | Transaction not found in OLP. |
| 077 | Error transaction code not found. |
| 078 | Failed to check fraud screen. |
| 079 | Transaction challenged by fraud rules. |
| 080 | Invalid payment option. |
| 082 | Inactive fraud service. |
| 083 | Unexpected user behavior. |
| 084 | Transaction amount is either bigger than maximum or less than minimum amount accepted for the selected plan. |
| 086 | Installment plan is not configured for Merchant account. |
| 087 | Card BIN does not match accepted issuer bank. |
| 088 | Token name was not created for this transaction. |
| 089 | Failed to retrieve digital wallet details. |
| 090 | Transaction in review. |
| 092 | Invalid issuer code. |
| 093 | service inactive. |
| 094 | Invalid Plan Code. |
| 095 | Inactive Issuer. |
| 096 | Inactive Plan. |
| 097 | Operation not allowed for service. |
| 098 | Invalid or expired call_id. |
| 099 | Failed to execute service. |
| 100 | Invalid expiry date. |
| 101 | Bill number not found. |
| 102 | Apple Pay order has been expired. |
| 103 | Duplicate subscription ID. |
| 104 | No plans valid for request. |
| 105 | Invalid bank code. |
| 106 | Inactive bank. |
| 107 | Invalid transfer_date. |
| 110 | Contradicting parameters, please refer to the integration guide. |
| 111 | Service not applicable for payment option. |
| 112 | Service not applicable for payment operation. |
| 113 | Service not applicable for e-commerce indicator. |
| 114 | Token already exist. |
| 115 | Expired invoice payment link. |
| 116 | Inactive notification type. |
| 117 | Invoice payment link already processed. |
| 118 | Order bounced. |
| 119 | Request dropped. |
| 120 | Payment link terms and conditions not found. |
| 121 | Card number is not verified. |
| 122 | Invalid date interval. |
| 123 | You have exceeded the maximum number of attempts. |
| 124 | Account successfully created. |
| 125 | Invoice already paid. |
| 126 | Duplicate invoice ID. |
| 127 | Merchant reference is not generated yet. |
| 128 | The generated report is still pending, you can’t download it now. |
| 129 | “Downloaded report” queue is full. Wait till its empty again. |
| 134 | Your search results have exceeded the maximum number of records. |
| 136 | The Batch file validation is failed. |
| 137 | Invalid Batch file execution date. |
| 138 | The Batch file still under validation. |
| 140 | The Batch file still under processing. |
| 141 | The Batch reference does not exist. |
| 142 | The Batch file header is invalid. |
| 144 | Invalid Batch file. |
| 146 | The Batch reference is already exist. |
| 147 | The Batch process request has been received. |
| 148 | Batch file will be processed. |
| 149 | Payment link request id not found. |
| 150 | Payment link is already open. |
| 151 | 3ds_id does not exist. |
| 152 | 3Ds verification doesn’t match the request details. |
| 154 | You have reached the maximum number of upload retries. |
| 155 | The upload retries is not configured. |
| 662 | Operation not allowed. The specified order is not confirmed yet. |
| 666 | Transaction declined. |
| 773 | Transaction closed. |
| 777 | The transaction has been processed, but failed to receive confirmation. |
| 778 | Session timed-out. |
| 779 | Transformation error. |
| 780 | Transaction number transformation error. |
| 781 | Message or response code transformation error. |
| 783 | Installments service inactive. |
| 784 | Transaction still processing you can’t make another transaction. |
| 785 | Transaction blocked by fraud check. |
| 787 | Failed to authenticate the user. |
| 788 | Invalid bill number. |
| 789 | Expired bill number. |
| 790 | Invalid bill type code. |
Security Settings
You can edit several key security settings in your merchant account. The security settings you have access to differ based on your merchant account configuration. The validation takes place based on the settings pertaining to each merchant account.
Security Settings Configuration
To configure your security settings, do the following:
- Select “Security Settings” under the Integration Settings tab.
- Click “Generate” to generate your Access Code.
- Select the SHA Type from the available drop-down list.
- Enter the SHA Request Phrase and the SHA Response Phrase.
- Enter the Origin IP or the Origin URL.
- Click “Save Changes”.
Transaction Feedback
Overview
The Amazon Payment Services transaction Feedback system provides Merchants with two types of configurable notifications:
1. Direct Transaction Feedback, Amazon Payment Services will send Merchants HTTPs notifications that inform Merchants of the transaction’s final status whenever a transaction is processed.
2. Notification Transaction Feedback, Amazon Payment Services will send Merchants HTTPs notifications that inform Merchants of the transaction’s final status whenever a transaction status is updated.
Registering Transaction Feedback URLs
1. Log in to your back office account.
2. Select the active channel under Integration Settings > Technical Settings.
3. Enter your Direct Transaction Feedback URL and Notification Transaction Feedback URL.
4. Click “Save Changes” button.
Transaction Feedback implementation
The Transaction Feedback URL is required to send the Merchant the response parameters after processing the transaction on the Merchant’s server side.
For the Direct Transaction Feedback, it sends the immediate payments response in all cases , like if the user closed the browser before getting redirected to the Redirection URL due to a drop in the internet connection or he closed the browser during the Redirection , the Merchant will create an endpoint which accepts the notifications received from Amazon Payment Services side as POST Method.
For the Notification Transaction Feedback , it’s required to provide the Merchant the transaction final status update whenever received , like if the Transaction was pending due to the unavailability for any party , the final update will be pushed to the Notification Feedback URL as POST Method.
Beyond whatever your Transaction Feedback URL does with the data received, it must also return a 2xx (like 200 , 201 , etc…) or 302 HTTP status code to update the Amazon Payment Services system that the notification was received. If your URL does not return 2xx or 302, the Amazon Payment Services will continue to retry the notification for 10 times with 10 seconds in between until it’s properly acknowledged.
Beyond whatever your Transaction Feedback URL does with the data received, it must also return a 2xx (like 200 , 201 , etc…) or 302 HTTP status code to update the Amazon Payment Services system that the notification was received. If your URL does not return 2xx or 302, the Amazon Payment Services will continue to retry the notification for 10, times with 10 seconds in between until it’s properly acknowledged.