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.
Find values of Access code and Merchant Identifier
- Once you are logged into your Amazon Payment services, Choose Merchant Management from the Left navigation list.
- Select Security Settings, A new window with all security related details page will appear.
- We can find the Access Code, Merchant Identifier and SHA Request/Response details from that section.
Step 2: Use the correct integration type
You must take a moment to choose an integration type for your use case. Read more about integration options in our API documentation.
Before building the integration, you need to make sure that you are selecting and using the proper parameters in the API calls as per the required integration type. All the mandatory parameters are mentioned in every section in the API reference.
Step 3: Create the transaction request
Processing a valid API request depends on specifying the right transaction parameters, you need to check the documentation and read every parameter’s range of possible values in order to reduce the errors in processing the transaction.
Step 4: Process the transaction response
After each payment is processed, Amazon Payment Services returns the transaction’s response on the URL configured in your account under Technical Settings channel configuration.
You can find more details in the API documentation section Transaction Feedback Implementation.
You need to validate the response parameters returned on this URL by calculating the signature for the response parameters using the SHA Response Phrase configured in your account under Security Settings.
Amazon Payment Services accepts configuring HTTPS URLs only in your Account Technical Settings and for return_url parameter. Amazon Payment Services supports the return_url type to be POST method only under your Technical Settings. Please make sure that your redirection or return_url handles the response as POST Method. For any further support please contact: integration-ps@amazon.com
Step 5: Test and go-live
You can use our testing payment card numbers to test your integration and to simulate your test cases. Amazon Payment Services requires that you test your integration before going live to verify the integration and to make sure it is implemented properly.
Amazon Payment Services TLS Certificates
Secure Sockets Layer (SSL) and Transport Layer Security (TLS) certificates allow systems to verify the identity and establish an encrypted network connection using specific protocols. SSL and TLS certificates function as digital identity cards to secure network communication, and to check the identity of websites and resources on private networks.
You can securely connect to the Amazon Payment Services servers using TLS certificates to utilize the plugins, cURL, and other HTTP clients to access Amazon Payment Services APIs. TLS certificates ensure that the API calls remain secure, and are safeguarded against unauthorized access. The SSL and TLS certificates are constantly validated, each time you connect to the Amazon Payment Services server.
Certificate Pinning
Certificate pinning is a security measure that is implemented in applications in order to authenticate remote hosts. Certificate pinning directly associates the host with its certificate or public key, instead of relying on a certificate hierarchy. This enables the application to bypass the standard SSL/TLS certificate chain validation process. In a typical scenario, SSL validation involves verifying the signature along the certificate chain, beginning from the root certificate authority (CA) through any subordinate CA certificates, and ultimately checking the certificate for the remote host at the lowest level of the hierarchy.
Certificate pinning enables the application to trust the certificate of the remote host. It does not trust the root certificate or any other certificates that are available in the chain. This certificate or the public key can be integrated into the application at the development stage. The application can also incorporate the certificate while establishing the first connection with the host.
How will you be affected?
Amazon Payment Services does not recommend certificate pinning to avoid intricate merchant integration setup, especially when the domain certificates are being rotated. For more information on certificate pinning, see Certificate pinning problems.
However, if your internal policies demand that certificate pinning be enabled, Amazon Payment Services recommends you to maintain an internal standard operating procedure (SOP). The SOP can help your team keep track of certificate updates. The admin email ID in your account receives regular email updates about upcoming schedules for certificates rotation for the associated domains.
NOTE: Certificate pinning might introduce new challenges when you update certificates on the server side. Ensure that you build a strategy to handle certificate updates and revocations. If you have explicitly specified a list of acceptable CAs for domains, your services might be impacted when a new TLS certificate is released.
Certificate Update
Amazon Payment Services does not track merchant accounts, while enabling certificate pinning and adding domain certificates. However, Amazon Payment Services sends regular updates to the merchant account email ID, to inform about the schedules for domain certificate updates. Amazon Payment Services issues new certificates to replace expired certificates as per the schedule.
NOTE: When a certificate update is notified, ensure that you add the new TLC certificate to the trust and whitelist group. Your business transactions will be affected if your system continues to pin the expired certificates.
Certificates for Amazon Payment Services Endpoints
Amazon Payment Services provides certificates for the following endpoints to a merchant to authenticate when merchants establish secure connections to our API endpoints. Ensure that you whitelist or trust certificates before you connect to the endpoints.
Endpoint | URL |
---|---|
checkout.payfort.com | https://checkout.payfort.com/ |
paymentservices.payfort.com | https://paymentservices.amazon.com/ |
*.payfort.com | https://paymentservices.amazon.com/ |
NOTE * indicate the sub-domains that can be used with PayFort.
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. Please refer to this section to know more about the differences. |
access_code Alphanumeric Mandatory Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount check the note after this table. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Mandatory Max: 254 |
The customer’s email. Example: customer1@domain.com Special characters: _ - . @ + |
signature Alphanumeric Mandatory Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
token_name Alphanumeric Optional Max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp Special characters: . @ - _ |
payment_option Alpha Optional Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - SADAD (for Purchase operations only) - NAPS (for Purchase operations only) - KNET(for Purchase operations only) - OMANNET (for Purchase operations and eci Ecommerce only) - BENEFIT (for Purchase operations and eci Ecommerce only) - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) TABBY |
sadad_olp Alphanumeric Optional Max: 12 |
SADAD Online Payment ID Alias. The merchant sends this value if the OLP ID is collected on the merchant checkout. Example: SABBP2P_UAT2 Special characters: @ . _ |
eci Alpha Optional Max: 16 |
E-commerce indicator. *MOTO and E-commerce indicator clickable in VISA, MASTERCARD and AMEX. Possible/ expected values: - ECOMMERCE - MOTO |
order_description Alphanumeric Optional Max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
customer_ip Alphanumeric Optional max: 45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf Special characters: . : |
customer_name Alpha Optional Max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' Space |
merchant_extra Alphanumeric Optional Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra1 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra2 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra3 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra4 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra5 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
remember_me Alpha Optional Max: 2 |
This parameter provides you with an indication to whether to save this token for the user based on the user selection. Possible/ expected values: NO |
phone_number Alphanumeric Optional max: 19 |
The customer’s phone number. Example: 00962797219966 Special characters: + - ( ) Space |
settlement_reference Alphanumeric Optional max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 Special characters: - _ . |
return_url Alphanumeric Optional Max: 400 |
The URL of the Merchant’s page that will be displayed to the customer when the order is processed. Example: https://www.merchant.com Special characters: $ ! = ? # & - _ / : . |
billing_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric Optional max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric Optional |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric Optional |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric Optional max: 100 |
The city portion of the address. |
agreement_id Alphanumeric Optional max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
recurring_mode Alphanumeric Optional max: 20 |
Indicates if the subsequent payments within the agreement has same/different amount or unscheduled (unknown interval/amount). Possible/ expected values: UNSCHEDULED, VARIABLE, FIXED |
recurring_transactions_count Alphanumeric Optional max: 100 |
The number of merchant-initiated payments within the recurring payment agreement. ( Required only if recurring_mode = VARIABLE or FIXED ) |
recurring_expiry_date |
The date where the merchant needs to end the recurring. The format is YY-MM-DD [Numeric] with special character - |
recurring_days_between_payments |
The number of days between payments agreed with the payer under your agreement with them. The allowed data type is: Numeric only. |
Redirection - Response
Authorization/ Purchase Response Example
{"command":"AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","customer_email":"test@payfort.com","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","payment_option":"VISA","eci":"ECOMMERCE","order_description":"iPhone6-S","customer_ip":"192.178.1.10","customer_name":"John","response_message":"Success","response_code":"20064","status":"04","card_holder_name":"John Smith","expiry_date":"2105","card_number":"400555******0001"}
{"command":"AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","customer_email":"test@payfort.com","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","payment_option":"VISA","eci":"ECOMMERCE","order_description":"iPhone6-S","customer_ip":"192.178.1.10","customer_name":"John","response_message":"Success","response_code":"20064","status":"04","card_holder_name":"John Smith","expiry_date":"2105","card_number":"400555******0001"}
{"command":"AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","customer_email":"test@payfort.com","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","payment_option":"VISA","eci":"ECOMMERCE","order_description":"iPhone6-S","customer_ip":"192.178.1.10","customer_name":"John","response_message":"Success","response_code":"20064","status":"04","card_holder_name":"John Smith","expiry_date":"2105","card_number":"400555******0001"}
The following parameters will be returned in PayFort’s Response:
ATTRIBUTES | Description |
---|---|
command Alpha Max: 20 |
A command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
access_code Alphanumeric Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
amount Numeric Max: 10 |
The transaction’s amount. Example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Max: 254 |
The customer’s email. Example: customer1@domain.com |
signature Alphanumeric Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
token_name Alphanumeric max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp |
fort_id Numeric Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
payment_option Alpha Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - SADAD (for Purchase operations only) - NAPS (for Purchase operations only) - KNET(for Purchase operations only) - OMANNET (for Purchase operations and eci Ecommerce only) - BENEFIT (for Purchase operations and eci Ecommerce only) - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) TABBY |
sadad_olp Alphanumeric Max: 12 |
SADAD Online Payment ID Alias. The merchant sends this value if the OLP ID is collected on the merchant checkout. Example: SABBP2P_UAT2 |
knet_ref_number Alphanmeric Max: 100 |
The reference number of KNET. *In case of sending KNET payment option. Example: 832911577112 |
third_party_transaction_number Alphanmeric Max: 50 |
The third party transaction number. *In case of sending KNET payment option. Example: 9547069411183290 |
eci Alpha Max: 16 |
The E-commerce indicator. Possible/ expected values: - ECOMMERCE - MOTO |
order_description Alphanumeric Max: 150 |
It holds the description of the order. Example: iPhone 6-S |
customer_ip Alphanumeric max: 45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf |
customer_name Alpha Max: 40 |
The customer’s name. Example: John Smith |
merchant_extra Alphanumeric Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra1 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra2 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra3 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra4 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra5 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
authorization_code Alphanumeric Max: 100 |
The authorization code returned from the 3rd party. Example: P1000000000000372136 |
response_message Alphanumeric Max: 150 |
The message description of the response code; it returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
card_holder_name Alpha Max: 50 |
The card holder name. Example: John Smith |
expiry_date Numeric Max: 4 |
The card’s expiry date. Example: 2105 |
card_number Numeric Max: 19 |
The masked credit card’s number. Only the MEEZA payment option takes 19 digits card number. *AMEX payment option takes 15 digits card number. *Otherwise, they take 16 digits card number. Example: 400555*****0001 |
remember_me Alpha Max: 2 |
This parameter provides you with an indication to whether to save this token for the user based on the user selection. Possible/ expected values: NO |
phone_number Alphanumeric max: 19 |
The customer’s phone number. Example: 00962797219966 |
settlement_reference Alphanumeric max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 |
billing_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric Optional max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric Optional |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric Optional |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric Optional max: 100 |
The city portion of the address. |
agreement_id Alphanumeric max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
Sample Redirection Request
Redirection request should be submitted as HTTPs POST Form request from the browser. Then you will get redirected to our payment gateway to fill payment details
Using Safe service (Tokenization) with redirection
The Safe service is integrated in the Redirection Channel through the below steps:
1. Your customer enables the remember_me option displayed in the payment page.
2. You process a first PURCHASE/ AUTHORIZATION payment successfully.
3. TYou receive a token_name in the response. This token_name is the permanent token name, and it can be used in the future for the customer’s payments by submitting the token_name in the next PURCHASE/ AUTHORIZATION payment.
If your customer wants to update or delete their card you can accommodate their request – check the Update Token section.
Redirection Customization
Amazon Payment page for credit card is fully customizable to match your website’s look and feel.
The payment page customization is possible only in Credit Card page , the other payment options allowed on Redirection channel are not customizable like SADAD , KNET , Installments Standalone and NAPS.
How it works
From your back-office go to the tab Payment Page Template, Click on Add Payment Page Template , You will find two options for customizing the payment page:
1. Using our back-office live editor.
2. Uploading your own css and html files.
Customization using our back-office live editor
We have added a full online editor on the back-office to simplify the CSS customization and change the look and feel without any coding , also your changes could be checked on the same tab Customize .
This option allows you to change the following :
- Primary color ( in Hexa )
- Secondary color ( In Hexa )
- Background Color ( In Hexa )
Using HTML and CSS files
If you want to have more control on the payment page design and add more edits , you have two file options to upload:
HTML Template:
You can implement and create your own html file that you want to load in the payment page and change the look and feel for the payment page as you wish.
Your edits and customization must be added between the following tag in a separated <div> as below :
<div>$$PZ$$</div> to inject your changes in our payment zone pages
The scripts aren’t allowed in the templates.
Sample HTML file: Sample Redirection HTML file
CSS Theme :
Develop your CSS file that edit our colors and theme in the payment page here you have to edit our existing CSS classes by inspecting the elements of the payment page , then include your changes on a CSS file .
Sample CSS file : Sample Redirection CSS file
Customizing the loading page
Our loading page is customizable , you can implement and create your own html file with your content and design that you want to load in the loading page
From your back-office go to the tab Payment Page Template, Click on Add Payment Page Template , Then upload your html files
Your edits and customization must be added between the below tag in a separated <div> as following to inject your changes : <div>$$PZ$$</div> The scripts aren’t allowed in the templates.
Sample HTML File: Sample Loading Page HTML file
Payment maintenance operations
Maintenance operations are operations that can be executed only if an amount has already been authorized. The following sections illustrate the maintenance operations:
Capture Operation
An operation that allows the Merchant to capture the authorized amount to their account. The capture could be partial or full, and depends on the Merchant requirements. Multiple capture requests can be made up to the authorized amount.
How To Capture An Authorized Amount
1. Using Backoffice:
Through your back office by accessing your account and navigating to the “Order Transaction Management” tab, choose the transaction that you want to capture, and finally choose “Capture” from the Action button. You can apply a full or partial capture operation.
2. Using API:
Using Capture Api Request.
Capture Operation URLs
Test Environment URL:
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production Environment URL:
https://paymentservices.payfort.com/FortAPI/paymentApi
Parameters Submission Type
REST POST request using JSON.
Capture Operation - Request
(Please take a look at the Capture Request Example on the right side of the page.)
Capture Request Example
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'command' => 'CAPTURE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'amount' => '10000',
'currency' => 'AED',
'language' => 'en',
'fort_id' => '149295435400084008',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
);
$ch = curl_init( $url );
# Setup request to send json via POST.
$data = json_encode($arrData);
curl_setopt( $ch, CURLOPT_POSTFIELDS, $data );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
# Return response instead of printing.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
# Send request.
$result = curl_exec($ch);
curl_close($ch);
# Print response.
echo "<pre>$result</pre>";
curl -H "Content-Type: application/json" -d '{"command":"CAPTURE","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","fort_id":"149295435400084008","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone6-S"}'
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command':'CAPTURE',
'access_code':'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier':'CycHZxVj',
'merchant_reference':'XYZ9239-yu898',
'amount':'10000',
'currency':'AED',
'language':'en',
'fort_id':'149295435400084008',
'signature':'7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description':'iPhone 6-S',
};
values = json.dumps(arrData)
data = urllib.urlencode(values)
req = urllib2.Request(url, data)
response = urllib2.urlopen(req)
page = response.read()
print page + '\n\n'
String jsonRequestString = "{\"command\" : \"CAPTURE\" , \"access_code\" : \"zx0IPmPy5jp1vAz8Kpg7\", \"merchant_identifier\" : \"CycHZxVj\", " + "\"merchant_reference\" : \"XYZ9239-yu898\", \"amount\" : \"10000\", \"currency\" : \"AED\"," + "\"language\" : \"en\", \"fort_id\" : \"149295435400084008\", " + "\"signature\" : \"7cad05f0212ed933c9a5d5dffa31661acf2c827a\", \"order_description\" : \"iPhone 6-S\"}";
// Define and Initialize HttpClient
HttpClient httpClient = HttpClientBuilder.create().build();
// Intialize HttpPOST with FORT Payment services URL
HttpPost request = new HttpPost("https://sbpaymentservices.payfort.com/FortAPI/paymentApi");
// Setup Http POST entity with JSON String
StringEntity params = new StringEntity(jsonRequestString);
// Setup request type as JSON
request.addHeader("content-type", "application/json");
request.setEntity(params);
// Post request to FORT
HttpResponse response = httpClient.execute(request);
// Read response using StringBuilder
StringBuilder sb = new StringBuilder();
BufferedReader reader = new BufferedReader(new InputStreamReader(
response.getEntity().getContent()), 65728);
String line = null;
while ((line = reader.readLine()) != null) {
sb.append(line);
}
// Print response
System.out.println(sb.toString());
require 'json'
require 'net/http'
require 'net/https'
require 'uri'
require 'openssl'
arrData = {
'command' => 'CAPTURE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'amount' => '10000',
'currency' => 'AED',
'language' => 'en',
'fort_id' => '149295435400084008',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
};
arrData = arrData.to_json
uri = URI.parse("https://sbpaymentservices.payfort.com/FortAPI/paymentApi")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new("/v1.1/auth")
request.add_field('Content-Type', 'application/json')
request.body = arrData
response = http.request(request)
Include the following parameters in the request you will send to Amazon Payment Services:
ATTRIBUTES | Description |
---|---|
command Alpha Mandatory Max: 20 |
A command. Possible/ expected values: CAPTURE |
access_code Alphanumeric Mandatory Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. * You have the option to send “fort_id” instead of “merchant_reference”, or you can send them BOTH. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
signature Alphanumeric Mandatory max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
fort_id Numeric Optional Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
order_description Alphanumeric Optional Max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
Capture Operation - Response
Capture Response Example
{"command":"CAPTURE","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","fort_id":"149295435400084008","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}
{"command":"CAPTURE","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","fort_id":"149295435400084008","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}
{"command":"CAPTURE","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","fort_id":"149295435400084008","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}
{"command":"CAPTURE","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","fort_id":"149295435400084008","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}
{"command":"CAPTURE","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","fort_id":"149295435400084008","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}
The following parameters will be returned in Amazon Payment Services’ Response:
ATTRIBUTES | Description |
---|---|
command Alpha Max: 20 |
A command. Possible/ expected values: CAPTURE |
access_code Alphanumeric Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
amount Numeric Max: 10 |
The transaction’s amount. Example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
signature Alphanumeric Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
fort_id Numeric Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
order_description Alphanumeric Max: 150 |
It holds the description of the order. Example: iPhone 6-S |
response_message Alphanumeric Max: 150 |
The message description of the response code; it returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
Void authorization operation
An operation that allows you to cancel the authorized amount after you have sent a successful authorize request.
How To Void An Authorized Amount
1. Using Backoffice:
Through your back office by accessing your account and navigating to the “Order Transaction Management” tab, choose the transaction that you want to Void authorization, and finally choose “Void authorization” from the Action button.
2. Using API
Using Void_authorization Request.
Void authorization operation URLs
Test Environment URL:
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production Environment URL:
https://paymentservices.payfort.com/FortAPI/paymentApi
Parameters Submission Type
REST POST request using JSON.
Void authorization operation - request
(Please take a look at the Void authorization request example on the right side of the page.)
Void-Authorization Request Example
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'command' => 'VOID_AUTHORIZATION',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
);
$ch = curl_init( $url );
# Setup request to send json via POST.
$data = json_encode($arrData);
curl_setopt( $ch, CURLOPT_POSTFIELDS, $data );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
# Return response instead of printing.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
# Send request.
$result = curl_exec($ch);
curl_close($ch);
# Print response.
echo "<pre>$result</pre>";
curl -H "Content-Type: application/json" -d '{"command":"VOID_AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj",merchant_reference":"XYZ9239-yu898","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone6-S"}' https://sbpaymentservices.payfort.com/FortAPI/paymentApi
String jsonRequestString = "{\"command\" : \"VOID_AUTHORIZATION\" , "
+ "\"access_code\" : \"zx0IPmPy5jp1vAz8Kpg7\", \"merchant_identifier\" : \"CycHZxVj\", \"merchant_reference\" : \"XYZ9239-yu898\","
+ "\"language\" : \"en\", \"signature\" : \"7cad05f0212ed933c9a5d5dffa31661acf2c827a\", "
+ "\"order_description\" : \"iPhone 6-S\"}";
// Define and Initialize HttpClient
HttpClient httpClient = HttpClientBuilder.create().build();
// Intialize HttpPOST with FORT Payment services URL
HttpPost request = new HttpPost("https://sbpaymentservices.payfort.com/FortAPI/paymentApi");
// Setup Http POST entity with JSON String
StringEntity params = new StringEntity(jsonRequestString);
// Setup request type as JSON
request.addHeader("content-type", "application/json");
request.setEntity(params);
// Post request to FORT
HttpResponse response = httpClient.execute(request);
// Read response using StringBuilder
StringBuilder sb = new StringBuilder();
BufferedReader reader = new BufferedReader(new InputStreamReader(
response.getEntity().getContent()), 65728);
String line = null;
while ((line = reader.readLine()) != null) {
sb.append(line);
}
// Print response
System.out.println(sb.toString());
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command':'VOID_AUTHORIZATION',
'access_code':'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier':'CycHZxVj',
'merchant_reference':'XYZ9239-yu898',
'language':'en',
'signature':'7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description':'iPhone 6-S',
};
values = json.dumps(arrData)
data = urllib.urlencode(values)
req = urllib2.Request(url, data)
response = urllib2.urlopen(req)
page = response.read()
print page + '\n\n'
require 'json'
require 'net/http'
require 'net/https'
require 'uri'
require 'openssl'
arrData = {
'command' => 'VOID_AUTHORIZATION',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
};
arrData = arrData.to_json
uri = URI.parse("https://sbpaymentservices.payfort.com/FortAPI/paymentApi")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new("/v1.1/auth")
request.add_field('Content-Type', 'application/json')
request.body = arrData
response = http.request(request)
Include the following parameters in the request you will send to Amazon Payment Services:
ATTRIBUTES | Description |
---|---|
command Alpha Mandatory Max: 20 |
Command. Possible/ expected values: VOID_AUTHORIZATION. Special characters: _ |
access_code Alphanumeric Mandatory Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. *You have the option to send “fort_id” instead of “merchant_reference”, or you can send them BOTH. Example: XYZ9239-yu898 Special characters: - _ . |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
signature Alphanumeric Mandatory max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
fort_id Numeric Optional Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
order_description Alphanumeric Optional Max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
Void authorization operation response
(Please take a look at the Void authorization response example on the right side of the page.)
Void-Authorization Response Example
{"command":"VOID_AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone6-S","fort_id":"149295435400084008","response_message":"Success","response_code":"20064","status":"04"}
{"command":"VOID_AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone6-S","fort_id":"149295435400084008","response_message":"Success","response_code":"20064","status":"04"}
{"command":"VOID_AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone6-S","fort_id":"149295435400084008","response_message":"Success","response_code":"20064","status":"04"}
{"command":"VOID_AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone6-S","fort_id":"149295435400084008","response_message":"Success","response_code":"20064","status":"04"}
{"command":"VOID_AUTHORIZATION","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","order_description":"iPhone6-S","fort_id":"149295435400084008","response_message":"Success","response_code":"20064","status":"04"}
The following parameters will be returned in Amazon Payment Services’ response:
ATTRIBUTES | Description |
---|---|
command Alpha Max: 20 |
Command. Possible/ expected values: VOID_AUTHORIZATION |
access_code Alphanumeric Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
language Alpha Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
signature Alphanumeric Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
fort_id Numeric Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
order_description Alphanumeric Max: 150 |
It holds the description of the order. Example: iPhone 6-S |
response_message Alphanumeric Max: 150 |
The message description of the response code; it returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
Refund operation
An operation that returns the entire amount of a transaction, or returns part of it, after you have captured an amount.
How To Refund Captured Amount
How To Refund Captured Amount
1. Using Backoffice:
Through your back office by accessing your account and navigating to the “Order Transaction Management” tab, choose the transaction that you want to Refund, and finally choose “Refund” from the Action button.
2. Using API: Using Refund Api Request.
Refund operation URLs
Test Environment URL:
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production Environment URL:
https://paymentservices.payfort.com/FortAPI/paymentApi
Parameters Submission Type
REST POST request using JSON.
Refund operation - request
(Please take a look at the Refund request example on the right side of the page.)
Refund request example
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'command' => 'REFUND',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => ' XYZ9239-yu898',
'amount' => '10000',
'currency' => 'AED',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'fort_id' => '149295435400084008',
'order_description' => 'iPhone 6-S',
);
$ch = curl_init( $url );
# Setup request to send json via POST.
$data = json_encode($arrData);
curl_setopt( $ch, CURLOPT_POSTFIELDS, $data );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
# Return response instead of printing.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
# Send request.
$result = curl_exec($ch);
curl_close($ch);
# Print response.
echo "<pre>$result</pre>";
curl -H "Content-Type: application/json" -d
'{"command":"REFUND","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","order_description":"iPhone6-S"}'
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command':'REFUND',
'access_code':'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier':'CycHZxVj',
'merchant_reference':' XYZ9239-yu898',
'amount':'10000',
'currency':'AED',
'language':'en',
'signature':'7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'fort_id':'149295435400084008',
'order_description':'iPhone 6-S',
};
values = json.dumps(arrData)
data = urllib.urlencode(values)
req = urllib2.Request(url, data)
response = urllib2.urlopen(req)
page = response.read()
print page + '\n\n'
String jsonRequestString = "{\"command\" : \"REFUND\" , \"access_code\" : \"zx0IPmPy5jp1vAz8Kpg7\", \"merchant_identifier\" : \"CycHZxVj\", "
+ "\"merchant_reference\" : \"XYZ9239-yu898\", \"amount\" : \"10000\", \"currency\" : \"AED\","
+ "\"language\" : \"en\", \"signature\" : \"7cad05f0212ed933c9a5d5dffa31661acf2c827a\", "
+ "\"fort_id\" : \"149295435400084008\", \"order_description\" : \"iPhone 6-S\"}";
// Define and Initialize HttpClient
HttpClient httpClient = HttpClientBuilder.create().build();
// Intialize HttpPOST with FORT Payment services URL
HttpPost request = new HttpPost("https://sbpaymentservices.payfort.com/FortAPI/paymentApi");
// Setup Http POST entity with JSON String
StringEntity params = new StringEntity(jsonRequestString);
// Setup request type as JSON
request.addHeader("content-type", "application/json");
request.setEntity(params);
// Post request to FORT
HttpResponse response = httpClient.execute(request);
// Read response using StringBuilder
StringBuilder sb = new StringBuilder();
BufferedReader reader = new BufferedReader(new InputStreamReader(
response.getEntity().getContent()), 65728);
String line = null;
while ((line = reader.readLine()) != null) {
sb.append(line);
}
// Print response
System.out.println(sb.toString());
require 'json'
require 'net/http'
require 'net/https'
require 'uri'
require 'openssl'
arrData = {
'command' => 'REFUND',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => ' XYZ9239-yu898',
'amount' => '10000',
'currency' => 'AED',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'fort_id' => '149295435400084008',
'order_description' => 'iPhone 6-S',
};
arrData = arrData.to_json
uri = URI.parse("https://sbpaymentservices.payfort.com/FortAPI/paymentApi")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new("/v1.1/auth")
request.add_field('Content-Type', 'application/json')
request.body = arrData
response = http.request(request)
Include the following parameters in the request you will send to Amazon Payment Services:
ATTRIBUTES | Description |
---|---|
command Alpha Mandatory Max: 20 |
A command. Possible/ expected values: REFUND |
access_code Alphanumeric Mandatory Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. *You have the option to send “fort_id” instead of “merchant_reference”, or you can send them BOTH. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
signature Alphanumeric Mandatory max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
maintenance_reference Alphanumeric Optional Max: 200 |
The Refund’s unique order number. * You will be able to retry on the refund request using the same maintenance reference if the refund transaction was declined. Example: customer123 |
fort_id Numeric Optional Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
order_description Alphanumeric Optional Max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
Refund operation - response
(Please take a look at the Refund Response Example on the right side of the page.)
Refund Response Example
{"command":"REFUND","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}
{"command":"REFUND","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}
{"command":"REFUND","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}
{"command":"REFUND","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}
{"command":"REFUND","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj","merchant_reference":"XYZ9239-yu898","amount":"10000","currency":"AED","language":"en","signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a","fort_id":"149295435400084008","order_description":"iPhone 6-S","response_message":"Success","response_code":"20064",status":"04"}
The following parameters will be returned in Amazon Payment Services’ response:
ATTRIBUTES | Description |
---|---|
command Alpha Max: 20 |
Command. Possible/ expected values: REFUND |
access_code Alphanumeric Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
amount Numeric Max: 10 |
The transaction’s amount. Example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
signature Alphanumeric Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
maintenance_reference Alphanumeric Max: 200 |
The Refund’s unique order number. * You will be able to retry on the refund request using the same maintenance reference if the refund transaction was declined. Example: customer123 |
fort_id Numeric Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
order_description Alphanumeric Max: 150 |
It holds the description of the order. Example: iPhone 6-S |
response_message Alphanumeric Max: 150 |
The message description of the response code; it returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
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: $ ! = ? # & - _ / : . |
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: . ; / _ - , ' @ |
Standard Merchant Page Tokenization - Sample request
The request parameters should be inside an iframe. Here below HTML sample contains the mandatory parameter should be submitted :
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:
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'command' => 'PURCHASE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
'customer_email' => 'test@payfort.com',
'signature' => 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b',
'token_name' => '7288fc8155014c57ad809d8e9574575e'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command':'PURCHASE',
'access_code':'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier':'CycHZxVj',
'merchant_reference':'XYZ9239-yu898',
'language':'en',
'signature':'7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description':'iPhone 6-S',
'customer_email':'test@payfort.com',
'signature' : 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b',
'token_name' : '7288fc8155014c57ad809d8e9574575e'
};
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' => 'PURCHASE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
'customer_email => 'test@payfort.com',
'signature' => 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b',
'token_name' => '7288fc8155014c57ad809d8e9574575e'
};
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)
String jsonRequestString = "{\n \"command\": \"PURCHASE\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"Abhitest-10052\",\n \"amount\": \"20000\",\n \"currency\": \"AED\",\n \"language\": \"en\",\n \"customer_email\": \"test@payfort.com\",\n \"signature\": \"fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b\",\n \"token_name\": \"7288fc8155014c57ad809d8e9574575e\"\n}";
// 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());
{
"command": "PURCHASE",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "Abhitest-10052",
"amount": "20000",
"currency": "AED",
"language": "en",
"customer_email": "test@payfort.com",
"signature": "fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b",
"token_name": "7288fc8155014c57ad809d8e9574575e"
}
ATTRIBUTES | Description |
---|---|
command Alpha Mandatory max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
access_code Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: zx0IPmPy5jp1vAz |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Mandatory Max: 254 |
The customer’s email. Example: customer@domain.com Special characters: _ - . @ + |
customer_ip Alphanumeric Mandatory max: 45 |
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf Special characters: . : |
token_name Alphanumeric Mandatory Max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp Special characters: _ - . @ |
signature Alphanumeric Mandatory Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
payment_option Alpha Optional Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) |
eci Alpha Optional Max: 16 |
Ecommerce indicator. Possible/ expected values: - ECOMMERCE - MOTO - RECCURING |
order_description Alphanumeric Optional Max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
card_security_code Numeric Optional Max: 4 |
A security code for the card. * Only AMEX accepts card security code of 4 digits. Example: 123 |
customer_name Alpha Optional Max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' Space |
merchant_extra Alphanumeric Optional Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra1 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra2 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra3 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra4 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra5 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
remember_me Alpha Optional Max: 3 |
This parameter provides you with an indication to whether to save this token for the user based on the user selection. *The Tokenization service MUST be activated in order to be able to send “remember_me” parameter. Possible/ expected values: -YES -NO |
phone_number Alphanumeric Optional max: 19 |
The customer’s phone number. Example: 00962797219966 Special characters: + - ( ) Space |
settlement_reference Alphanumeric Optional max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 Special characters: - _ . |
return_url Alphanumeric Optional Max: 400 |
The URL of the Merchant’s page to be displayed to the customer when the order is processed. Example: https://www.merchant.com Special characters: $ ! = ? # & - _ / : . |
billing_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric Optional max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric Optional |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric Optional |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric Optional max: 100 |
The city portion of the address. |
agreement_id Alphanumeric Optional max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
recurring_mode Alphanumeric Optional max: 20 |
Indicates if the subsequent payments within the agreement has same/different amount or unscheduled (unknown interval/amount). Possible/ expected values: UNSCHEDULED, VARIABLE, FIXED |
recurring_transactions_count Alphanumeric Optional max: 100 |
The number of merchant-initiated payments within the recurring payment agreement. ( Required if recurring_mode = VARIABLE or FIXED ) |
recurring_expiry_date |
The date where the merchant needs to end the recurring. The format is YY-MM-DD [Numeric] with special character - |
recurring_days_between_payments |
The number of days between payments agreed with the payer under your agreement with them. The allowed data type is: Numeric only. |
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'command' => 'PURCHASE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
'customer_email' => 'test@payfort.com',
'signature' => 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b',
'token_name' => '7288fc8155014c57ad809d8e9574575e'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command':'PURCHASE',
'access_code':'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier':'CycHZxVj',
'merchant_reference':'XYZ9239-yu898',
'language':'en',
'signature':'7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description':'iPhone 6-S',
'customer_email':'test@payfort.com',
'signature' : 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b',
'token_name' : '7288fc8155014c57ad809d8e9574575e'
};
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' => 'PURCHASE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
'customer_email => 'test@payfort.com',
'signature' => 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b',
'token_name' => '7288fc8155014c57ad809d8e9574575e'
};
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)
String jsonRequestString = "{\n \"command\": \"PURCHASE\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"Abhitest-10052\",\n \"amount\": \"20000\",\n \"currency\": \"AED\",\n \"language\": \"en\",\n \"customer_email\": \"test@payfort.com\",\n \"signature\": \"fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b\",\n \"token_name\": \"7288fc8155014c57ad809d8e9574575e\"\n}";
// 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());
{
"command": "PURCHASE",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "Abhitest-10052",
"amount": "20000",
"currency": "AED",
"language": "en",
"customer_email": "test@payfort.com",
"signature": "fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b",
"token_name": "7288fc8155014c57ad809d8e9574575e"
}
Operations - Response
The following parameters will be returned in Amazon Payment Services’s response:
ATTRIBUTES | Description |
---|---|
command Alpha max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
access_code Alphanumeric Max: 20 |
The ID of the Merchant. Example: zx0IPmPy5jp1vAz |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
amount Numeric Max: 10 |
The transaction’s amount. Example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Max: 254 |
The customer’s email. Example: customer1@domain.com |
customer_ip Alphanumeric max: 45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf |
token_name Alphanumeric max: 100 |
The Token received from the Tokenization process. Example: COp9Vmp |
signature Alphanumeric Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
fort_id Numeric Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
payment_option Alpha Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) |
eci Alpha Max: 16 |
Ecommerce indicator. Possible/ expected values: - ECOMMERCE - MOTO - RECCURING |
order_description Alphanumeric Max: 150 |
A description of the order. Example: iPhone 6-S |
authorization_code Alphanumeric Max: 100 |
The authorization code returned from the 3rd party. Example: P1000000000000372136 |
response_message Alphanumeric Max: 150 |
Message description of the response code. It returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
customer_name Alpha Max: 40 |
The customer’s name. Example: John Smith |
merchant_extra Alphanumeric Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra1 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra2 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra3 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra4 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra5 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
expiry_date Numeric Max: 4 |
The card’s expiry date. Example: 2105 |
card_number Numeric Max: 19 |
The masked credit card’s number. Only the MEEZA payment option takes 19 digits card number. *AMEX payment option takes 15 digits card number. *Otherwise, they take 16 digits card number. Example: 400555*****0001 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
card_holder_name Alpha Max: 50 |
The card holder name. Example: John Smith |
3ds_url Alphanumeric Max: 300 |
The URL where the Merchant redirects a customer whose card is 3D Secure for authentication. Example: https://www.3dsecure.com |
remember_me Alpha Max: 3 |
This parameter provides you with an indication to whether to save this token for the user based on the user selection. Possible/ expected values: -YES -NO |
phone_number Alphanumeric max: 19 |
The customer’s phone number. Example: 00962797219966 |
settlement_reference Alphanumeric max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 |
billing_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric Optional max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric Optional |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric Optional |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric Optional max: 100 |
The city portion of the address. |
agreement_id Alphanumeric max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
How do you add Safe service (Tokenization) to standard merchant page integration?
The tokenization service can be integrated through standard merchant page integration through the below steps:
1. Your customer processes their first authorization or purchase transaction successfully.
2. You receive a token_name in the response. This token_name should be considered as a permanent token name, and it can be used in the future customer’s payments by submitting the token_name in the next purchase or authorization transaction, alongside the card_security_code parameter.
3. Your customer does not need to complete all their card details again in the next checkout.
If your customer wants to update or delete their card, you can facilitate the request by updating the token check out the Update Token section.
Customizing standard merchant page integration
This is a list with all customizable CSS classes for standard merchant page integration:
- The
Wrapper
class: responsible for the total width of the form container and the background. - The
Container
class: responsible for the form’s shape and width. - The
Popover
class: responsible for the error messages. - The
Half-container
class: used to merge the date and CVV fields into one block if needed. - The
Input
class: is the container of each single input field. - The
Pay
class: responsible for the submit button. - The
Visa/ MasterCard
classes: used to change the color of the Visa/ MasterCard colors.
Custom merchant page integration
When you use our custom merchant page integration route you build your own payment form that captures payment data and that directly submits that data to Amazon Payment Services for payment authorization.
Custom merchant page integration is a good choice if you want the highest level of on-page customization, or if your ecommerce use case has unique technical requirements.
Custom merchant page integration URLs
Test Environment URL:
https://sbcheckout.PayFort.com/FortAPI/paymentPage
Production Environment URL:
https://checkout.PayFort.com/FortAPI/paymentPage
Parameters Submission Type
HTTPs Form Post Request.
Custom merchant page integration - request
Include the following parameters in the Request you will send to Amazon Payment Services:
ATTRIBUTES | Description |
---|---|
service_command Alpha Mandatory max: 20 |
Command. Possible/ expected values: TOKENIZATION |
access_code Alphanumeric Mandatory Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
expiry_date Numeric Mandatory Max: 4 |
The card’s expiry date. Example: 2105 |
card_number Numeric Mandatory Max: 19 |
The clear credit card’s number. *Only the MEEZA payment option takes 19 digits card number. *AMEX payment option takes 15 digits card number. *Otherwise, they take 16 digits card number. Example: 4005550000000001 |
card_security_code Numeric Mandatory Max: 4 |
A security code for the card. * Only AMEX accepts card security code of 4 digits. Example: 123 |
signature Alphanumeric Mandatory Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature *Please don’t include the following parameters in calculating the signature if you are using Merchant Page 2.0 tokenization request: card_security_code, card number, expiry_date, card_holder_name, remember_me Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
token_name Alphanumeric Optional Max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp Special characters: . @ - _ |
card_holder_name Alpha Optional max: 50 |
The card holder name. Example: John Smith Special characters: ' - . |
remember_me Alpha Optional Max: 3 |
This parameter provides you with an indication to whether to save this token for the user based on the user selection. Possible/ expected values: -YES -NO |
return_url Alphanumeric Optional Max: 400 |
The URL of the Merchant’s page to be displayed to the customer when the order is processed. Example: https://www.merchant.com Special characters: $ ! = ? # & - _ / : . |
Custom Merchant Page Tokenization - Sample request
APS Validation JS
(function( $ ) { 'use strict'; /** * All of the code for your checkout functionality placed here. * should reside in this file. */ /** * Sandbox Url - /sbcheckout.payfort.com/ * Production Url - /checkout.payfort.com/ */ const formElement = $( 'form' ).filter( function(){ return this.action.match(/sbcheckout.payfort.com/i); }); /** * MADA bins are applicable only for KSA based payments. * MEEZA bins are applicable only for Egypt based payments. * */ const bins = { mada : '446404|440795|440647|421141|474491|588845|968208|457997|457865|468540|468541|468542|468543|417633|446393|636120|968201|410621|409201|403024|458456|462220|968205|455708|484783|588848|455036|968203|486094|486095|486096|504300|440533|489318|489319|445564|968211|410685|406996|432328|428671|428672|428673|968206|446672|543357|434107|407197|407395|42689700|412565|431361|604906|521076|588850|968202|529415|535825|543085|524130|554180|549760|968209|524514|529741|537767|535989|536023|513213|442463|520058|558563|605141|968204|422817|422818|422819|410834|428331|483010|483011|483012|589206|968207|406136|419593|439954|407520|530060|531196|420132|242030|22402030', meeza : '507803[0-6][0-9]|507808[3-9][0-9]|507809[0-9][0-9]|507810[0-2][0-9]', } const apsPaymentErrors = { invalid_card: 'Invalid Card', invalid_card_length: 'Invalid Card Length', card_empty: 'Card Number Empty', invalid_card_holder_name: 'Invalid Card Holder Name', invalid_card_cvv: 'Invalid Card CVV', invalid_expiry_date: 'Invalid Expiry Date', invalid_expiry_year : 'Invalid Expiry Year. Expected as YYMM', invalid_expiry_month : 'Invalid Expiry Month. Expected as YYMM' }; const cardNumberSelector = '[name=\'card_number\']'; const cardHolderSelector = '[name=\'card_holder_name\']'; const expirySelector = '[name=\'expiry_date\']'; //Validation control let APSValidation = { validateCard: function (card_number) { let card_type = ""; let card_validity = true; let message = ''; let card_length = 0; if (card_number) { card_number = card_number.replace(/ /g, '').replace(/-/g, ''); // Visa let visa_regex = new RegExp('^4[0-9]{0,15}$'); // MasterCard let mastercard_regex = new RegExp('^5$|^5[0-5][0-9]{0,16}$'); // American Express let amex_regex = new RegExp('^3$|^3[47][0-9]{0,13}$'); //mada let mada_regex = new RegExp('^' + bins.mada); //meeza let meeza_regex = new RegExp(bins.meeza, 'gm'); if (card_number.match(mada_regex)) { card_type = 'mada'; card_length = 16; } else if (card_number.match(meeza_regex)) { card_type = 'meeza'; card_length = 19; } else if (card_number.match(visa_regex)) { card_type = 'visa'; card_length = 16; } else if (card_number.match(mastercard_regex)) { card_type = 'mastercard'; card_length = 16; } else if (card_number.match(amex_regex)) { card_type = 'amex'; card_length = 15; } else { card_validity = false; message = apsPaymentErrors.invalid_card; } if (card_number.length < 15) { card_validity = false; message = apsPaymentErrors.invalid_card_length; } else { let cardValidByAlgorithm = APSValidation.validateCardNumber(card_number); if (!cardValidByAlgorithm) { card_validity = false; message = apsPaymentErrors.invalid_card; } } } else { message = apsPaymentErrors.card_empty; card_validity = false; } return { card_type, validity: card_validity, msg: message, card_length } }, validateCardNumberByAlgorithm : function (card_number){ let checksum = 0; // running checksum total let j = 1; // takes value of 1 or 2 // Process each digit one by one starting from the last for (let i = card_number.length - 1; i >= 0; i--) { let calc = 0; // Extract the next digit and multiply by 1 or 2 on alternative digits. calc = Number(card_number.charAt(i)) * j; // If the result is in two digits add 1 to the checksum total if (calc > 9) { checksum = checksum + 1; calc = calc - 10; } // Add the units element to the checksum total checksum = checksum + calc; // Switch the value of j if (j === 1) { j = 2; } else { j = 1; } } //Check if it is divisible by 10 or not. return (checksum % 10) === 0; }, validateCardNumber : function (card_number){ //Check if the number contains only numeric value //and is of between 13 to 19 digits const regex = new RegExp("^[0-9]{13,19}$"); if (!regex.test(card_number)){ return false; } return APSValidation.validateCardNumberByAlgorithm(card_number); }, validateHolderName: function (card_holder_name) { let validity = true; let message = ''; card_holder_name = card_holder_name.trim(); if (card_holder_name.length > 51 || card_holder_name.length === 0) { validity = false; message = apsPaymentErrors.invalid_card_holder_name; } const regex = new RegExp("^[a-zA-Z- '.]+$"); if (!regex.test(card_number)){ return false; } return { validity, msg: message } }, validateCVV: function (card_cvv, card_type) { let validity = false; let message = apsPaymentErrors.invalid_card_cvv; if (card_cvv.length > 0) { card_cvv = card_cvv.trim(); if (!card_type.length || card_type.length === 0) { if (card_cvv.length === 3 && card_cvv !== '000') { validity = true; message = ''; } else if (card_cvv.length === 4 && card_type === 'amex' && card_cvv !== '0000') { validity = true; message = ''; } } } return { validity, msg: message } }, validateCardExpiry: function (card_expiry_month, card_expiry_year) { let validity = true; let message = ''; if (card_expiry_month === '' || !card_expiry_month) { validity = false; message = apsPaymentErrors.invalid_expiry_month; } else if (card_expiry_year === '' || !card_expiry_year) { validity = false; message = apsPaymentErrors.invalid_expiry_year; } else if (parseInt(card_expiry_month) <= 0 || parseInt(card_expiry_month) > 12) { validity = false; message = apsPaymentErrors.invalid_expiry_month; } else { let cur_date, exp_date; card_expiry_month = ('0' + parseInt(card_expiry_month - 1)).slice(-2); cur_date = new Date(); exp_date = new Date(parseInt('20' + card_expiry_year), card_expiry_month, 30); if (exp_date.getTime() < cur_date.getTime()) { message = apsPaymentErrors.invalid_expiry_date; validity = false; } } return { validity, msg: message } } }; //Defining of payment functions let apsPayment = { validatePayment: function ( ) { let status = true; let payment_box = formElement; let card_value = payment_box.find( "[name=\'card_number\']" ).val(); let holdername_value = payment_box.find( "[name=\'card_holder_name\']" ).val(); let cvv_value = payment_box.find( "[name=\'card_security_code\']" ).val(); let expiry = payment_box.find( "[name=\'expiry_date\']" ).val(); let expiry_year = expiry.substring(0, 2); let expiry_month = expiry.substring(2, 4); let validateCard = APSValidation.validateCard( card_value ); let validateHolderName = APSValidation.validateHolderName( holdername_value ); let validateCardCVV = APSValidation.validateCVV( cvv_value, validateCard.card_type); let validateExpiry = APSValidation.validateCardExpiry( expiry_month, expiry_year ); let message; if ( validateCard.validity === false ) { message = validateCard.msg; status = false; } if ( validateHolderName.validity === false ) { message = validateHolderName.msg; status = false; } if ( validateCardCVV.validity === false ) { message = validateCardCVV.msg; status = false; } if ( validateExpiry.validity === false ) { message = validateExpiry.msg; status = false; } return status; }, parseExpiry : function( monthYear ){ } }; formElement.on( 'submit', function(e) { return apsPayment.validatePayment(); } ); })( jQuery );
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:
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'command' => 'PURCHASE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
'customer_email' => 'test@payfort.com',
'signature' => 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b',
'token_name' => '7288fc8155014c57ad809d8e9574575e'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command':'PURCHASE',
'access_code':'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier':'CycHZxVj',
'merchant_reference':'XYZ9239-yu898',
'language':'en',
'signature':'7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description':'iPhone 6-S',
'customer_email':'test@payfort.com',
'signature' : 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b',
'token_name' : '7288fc8155014c57ad809d8e9574575e'
};
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' => 'PURCHASE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
'customer_email => 'test@payfort.com',
'signature' => 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b',
'token_name' => '7288fc8155014c57ad809d8e9574575e'
};
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)
String jsonRequestString = "{\n \"command\": \"PURCHASE\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"Abhitest-10052\",\n \"amount\": \"20000\",\n \"currency\": \"AED\",\n \"language\": \"en\",\n \"customer_email\": \"test@payfort.com\",\n \"signature\": \"fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b\",\n \"token_name\": \"7288fc8155014c57ad809d8e9574575e\"\n}";
// 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());
{
"command": "PURCHASE",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "Abhitest-10052",
"amount": "20000",
"currency": "AED",
"language": "en",
"customer_email": "test@payfort.com",
"signature": "fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b",
"token_name": "7288fc8155014c57ad809d8e9574575e"
}
ATTRIBUTES | Description |
---|---|
command Alpha Mandatory max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
access_code Alphanumeric Mandatory Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Mandatory Max: 254 |
The customer’s email. Example: customer@domain.com Special characters: _ - . @ + |
customer_ip Alphanumeric Mandatory max: 45 |
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf Special characters: . : |
token_name Alphanumeric Mandatory Max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp Special characters: _ - . @ |
signature Alphanumeric Mandatory Max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
payment_option Alpha Optional Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) |
eci Alpha Optional Max: 16 |
Ecommerce indicator. Possible/ expected values: - ECOMMERCE - MOTO - RECCURING |
order_description Alphanumeric Optional Max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
card_security_code Numeric Optional Max: 4 |
A security code for the card. * Only AMEX accepts card security code of 4 digits. Example: 123 |
customer_name Alpha Optional Max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' Space |
merchant_extra Alphanumeric Optional Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra1 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra2 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra3 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra4 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra5 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
remember_me Alpha Optional Max: 3 |
This parameter provides you with an indication to whether to save this token for the user based on the user selection. *The Tokenization service MUST be activated in order to be able to send “remember_me” parameter. Possible/ expected values: -YES -NO |
phone_number Alphanumeric Optional max: 19 |
The customer’s phone number. Example: 00962797219966 Special characters: + - ( ) Space |
settlement_reference Alphanumeric Optional max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 Special characters: - _ . |
return_url Alphanumeric Optional Max: 400 |
The URL of the Merchant’s page to be displayed to the customer when the order is processed. Example: https://www.merchant.com Special characters: $ ! = ? # & - _ / : . |
billing_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric Optional max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric Optional |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric Optional |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric Optional max: 100 |
The city portion of the address. |
agreement_id Alphanumeric Optional max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
recurring_mode Alphanumeric Optional max: 20 |
Indicates if the subsequent payments within the agreement has same/different amount or unscheduled (unknown interval/amount). Possible/ expected values: UNSCHEDULED, VARIABLE, FIXED |
recurring_transactions_count Alphanumeric Optional max: 100 |
The number of merchant-initiated payments within the recurring payment agreement. ( Required if recurring_mode = VARIABLE or FIXED ) |
recurring_expiry_date |
The date where the merchant needs to end the recurring. The format is YY-MM-DD [Numeric] with special character - |
recurring_days_between_payments |
The number of days between payments agreed with the payer under your agreement with them. The allowed data type is: Numeric only. |
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'command' => 'PURCHASE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
'customer_email' => 'test@payfort.com',
'signature' => 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b',
'token_name' => '7288fc8155014c57ad809d8e9574575e'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command':'PURCHASE',
'access_code':'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier':'CycHZxVj',
'merchant_reference':'XYZ9239-yu898',
'language':'en',
'signature':'7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description':'iPhone 6-S',
'customer_email':'test@payfort.com',
'signature' : 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b',
'token_name' : '7288fc8155014c57ad809d8e9574575e'
};
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' => 'PURCHASE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
'customer_email => 'test@payfort.com',
'signature' => 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b',
'token_name' => '7288fc8155014c57ad809d8e9574575e'
};
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)
String jsonRequestString = "{\n \"command\": \"PURCHASE\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"Abhitest-10052\",\n \"amount\": \"20000\",\n \"currency\": \"AED\",\n \"language\": \"en\",\n \"customer_email\": \"test@payfort.com\",\n \"signature\": \"fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b\",\n \"token_name\": \"7288fc8155014c57ad809d8e9574575e\"\n}";
// 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());
{
"command": "PURCHASE",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "Abhitest-10052",
"amount": "20000",
"currency": "AED",
"language": "en",
"customer_email": "test@payfort.com",
"signature": "fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b",
"token_name": "7288fc8155014c57ad809d8e9574575e"
}
Operations - Response
The following parameters will be returned in Amazon Payment Services’ response:
ATTRIBUTES | Description |
---|---|
command Alpha max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
access_code Alphanumeric Max: 20 |
The ID of the Merchant. Example: zx0IPmPy5jp1vAz |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
amount Numeric Max: 10 |
The transaction’s amount. Example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Max: 254 |
The customer’s email. Example: customer1@domain.com |
customer_ip Alphanumeric max: 45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf |
token_name Alphanumeric max: 100 |
The Token received from the Tokenization process. Example: COp9Vmp |
signature Alphanumeric Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
fort_id Numeric Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
payment_option Alpha Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) |
eci Alpha Max: 16 |
Ecommerce indicator. Possible/ expected values: - ECOMMERCE - MOTO - RECCURING |
order_description Alphanumeric Max: 150 |
It holds the description of the order. Example: iPhone 6-S |
authorization_code Alphanumeric Max: 100 |
The authorization code returned from the 3rd party. Example: P1000000000000372136 |
response_message Alphanumeric Max: 150 |
Message description of the response code. It returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
customer_name Alpha Max: 40 |
The customer’s name. Example: John Smith |
merchant_extra Alphanumeric Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra1 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra2 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra3 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra4 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra5 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
expiry_date Numeric Max: 4 |
The card’s expiry date. Example: 2105 |
card_number Numeric Max: 19 |
The masked credit card’s number. Only the MEEZA payment option takes 19 digits card number. *AMEX payment option takes 15 digits card number. *Otherwise, they take 16 digits card number. Example: 400555*****0001 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
card_holder_name Alpha Max: 50 |
The card holder name. Example: John Smith |
3ds_url Alphanumeric Max: 300 |
The URL where the Merchant redirects a customer whose card is 3D Secure for authentication. Example: https://www.3dsecure.com |
remember_me Alpha Max: 3 |
This parameter provides you with an indication to whether to save this token for the user based on the user selection. Possible/ expected values: - YES, - NO |
phone_number Alphanumeric max: 19 |
The customer’s phone number. Example: 00962797219966 |
settlement_reference Alphanumeric max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 |
billing_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric Optional max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric Optional |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric Optional |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric Optional max: 100 |
The city portion of the address. |
agreement_id Alphanumeric max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
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.
Android Mobile SDK
Before you start the integration
Read through the following steps first to understand how the integration process works. This will help you to understand why these steps are required and why you need to follow a specific sequence.
Step 1: Access your test account
You need to make sure that you have access to a test account with Amazon Payment Services. It is a full test environment that allows you to fully simulate transactions.
Step 2: Choose between a standardized or custom payment UI
The Amazon Payment Services Android SDK provides you with a standard payment UI that you can use to quickly integrate in-app payments. The standard UI offers limited customizability.
Alternatively, you can choose to build your own payment UI using Amazon Payment Services Android SDK building blocks, we describe this in the section on custom-coding a payment processing UI.
Step 3: Make sure that you are using the correct integration type
Prior to building the integration, you need to make sure that you are selecting and using the proper parameters in the API calls as per the required integration type. All the mandatory parameters are mentioned under every section in the API document
Step 4: Install the Amazon Payment Services Android SDK in your development environment
You need to add the repositories to your build file and add the SDK to your build.gradle, also setting the correct Android permissions.
Step 5: Create a test transaction request
You need to create a test transaction request. Processing a valid API request depends on transaction parameters included, you need to check the documentation and read every parameter possible to reduce the errors in processing the transaction.
Step 6: Process a transaction response
After every payment, Amazon Payment Services returns the transaction response on the URL configured in your account under Technical Settings, Channel Configuration.
For more details check the transaction feedback instructions. You need to validate the response parameters returned on this URL by calculating the signature for the response parameters using the SHA response phrase configured in your account under security settings.
Step 7: Test and Go Live
You can use our test card numbers to test your integration and simulate your test cases. The Amazon Payment Services team may need to test your integration before going live to assure your application integration.
Mobile SDK transaction workflow
Below, we describe the transaction workflow when you process a payment using the Amazon Payment Service Android Mobile SDK.
Your customer clicks on the Pay button in your app.
Your merchant system (back-end) generates a mobile SDK token using the Amazon Payment Services API
Your app passes the parameters, including the SDK token, to the Android mobile SDK
The Android mobile SDK starts a secure connection and sends the transaction request to the Amazon Payment Services server to be validated.
The Amazon Payment Services API validates the SDK token, device_ID and other request parameters and returns the validation response to the Android SDK.
Assuming validation is passed your merchant app displays a payment page to the customer.
Your customer enters their payment details on the payment page in the Android SDK prompt on their device.
The Amazon Payment Services Android SDK validates your customer’s details and sends a transaction (Authorization or Purchase) request to the relevant payment processor and issuing bank.
The payment processor processes the transaction request and returns a transaction response to the Android SDK
The Amazon Payment Services Android SDK returns the transaction response to your merchant app
Your merchant app displays the response to your customer
Installing the Mobile SDK
These are the first steps you need to follow to integrate the Amazon Payment Services Android SDK into your Android application.
Installing the Android Mobile SDK
You need to complete two steps to install the Amazon Payment Services Android SDK.
Step 1
First, you need to add the repository to your build file. Add it in your root build.gradle at the end of repositories:
allprojects { repositories { ... maven { url https://android-sdk.payfort.com } } }
Step 2
Add the Add fortSDK to your build.gradle dependencies using this code:
apply plugin: 'com.android.application' android { ... } dependencies { implementation("com.amazon:fortpayment:+:release@aar"){ transitive = true } }
Setting Android OS permissions
You need to set the following two permission so that the Android mobile SDK works properly:
< uses-permission android:name="android.permission.INTERNET" /> < uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
Creating a mobile SDK token
A mobile SDK authentication token is required to authenticate every request sent to the SDK. The token is also significant to process payment operations with Amazon Payment Services through our Android mobile SDK.
To get started with our Android mobile SDK you must first establish the ability to generate a mobile SDK token.
NOTE: The creation and initiation of a mobile SDK token happens on your server – your server must generate the token by sending a request to the Amazon Payment Services API.
A unique authentication token must be created for each transaction. Each authentication token has a life-time of only one hour if no new request from the same device is sent.
Android mobile SDK token URLs
These are the URLs you need to use when you request a mobile SDK token for your Android app:
Test Environment URL
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production Environment URL
https://paymentservices.payfort.com/FortAPI/paymentApi
Submitting token request parameters
You need to submit parameters as a REST POST request using JSON. Below we list the range of parameters for the Android mobile SDK token request.
Android Mobile SDK Token Request Parameters
When you send your request for an Android mobile SDK token you must send the following parameters to Amazon Payment Services:
Mobile SDK Token Request Parameters
(Please take a look at the ** Mobile SDK Token Request Example** on the right side of the page.)
Mobile SDK Token Request Example
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'service_command' => 'SDK_TOKEN',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'language' => 'en',
'device_id'=> 'ffffffff-a9fa-0b44-7b27-29e70033c587',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a'
);
$ch = curl_init( $url );
# Setup request to send json via POST.
$data = json_encode($arrData);
curl_setopt( $ch, CURLOPT_POSTFIELDS, $data );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
# Return response instead of printing.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
# Send request.
$result = curl_exec($ch);
curl_close($ch);
# Print response.
echo "<pre>$result</pre>";
curl -H "Content-Type: application/json" -d
'{"service_command":"SDK_TOKEN","language":"en","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj",,"language":"en","device_id":"ffffffff-a9fa-0b44-7b27-29e70033c587",
"signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a"}'
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'service_command' : 'SDK_TOKEN',
'access_code' : 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' : 'CycHZxVj',
'language' : 'en',
'device_id': 'ffffffff-a9fa-0b44-7b27-29e70033c587',
'signature' : '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
};
values = json.dumps(arrData)
data = urllib.urlencode(values)
req = urllib2.Request(url, data)
response = urllib2.urlopen(req)
page = response.read()
print page + '\n\n'
String jsonRequestString = "{\"service_command\" : \"SDK_TOKEN\" , "
+"\"access_code\" : \"zx0IPmPy5jp1vAz8Kpg7\", "
+"\"merchant_identifier\" : \"CycHZxVj\", "
+ "\"language\" : \"en\","
+ "\"device_id\"\"ffffffff-a9fa-0b44-7b27-29e70033c587\", "
+ "\"signature\" : \"7cad05f0212ed933c9a5d5dffa31661acf2c827a\"}";
// Define and Initialize HttpClient
HttpClient httpClient = HttpClientBuilder.create().build();
// Intialize HttpPOST with FORT Payment services URL
HttpPost request = new HttpPost("https://sbpaymentservices.payfort.com/FortAPI/paymentApi");
// Setup Http POST entity with JSON String
StringEntity params = new StringEntity(jsonRequestString);
// Setup request type as JSON
request.addHeader("content-type", "application/json");
request.setEntity(params);
// Post request to FORT
HttpResponse response = httpClient.execute(request);
// Read response using StringBuilder
StringBuilder sb = new StringBuilder();
BufferedReader reader = new BufferedReader(new InputStreamReader(
response.getEntity().getContent()), 65728);
String line = null;
while ((line = reader.readLine()) != null) {
sb.append(line);
}
// Print response
System.out.println(sb.toString());
require 'json'
require 'net/http'
require 'net/https'
require 'uri'
require 'openssl'
arrData = {
'service_command' => 'SDK_TOKEN',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'language' => 'en',
'device_id'=> 'ffffffff-a9fa-0b44-7b27-29e70033c587',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a'
};
arrData = arrData.to_json
uri = URI.parse("https://sbpaymentservices.payfort.com/FortAPI/paymentApi")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new("/v1.1/auth")
request.add_field('Content-Type', 'application/json')
request.body = arrData
response = http.request(request)
ATTRIBUTES | Description |
---|---|
service_command Alpha Mandatory max: 20 |
Command. Possible/ expected values: SDK_TOKEN Special characters: _ |
access_code Alphanumeric Mandatory Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
device_id Alphanumeric Mandatory Max: 100 |
A unique device identifier. Example: ffffffff-a9fa-0b44-7b27-29e70033c587 Special characters: - |
signature Alphanumeric Mandatory Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
NOTE: device_id is a value to be generated from the UUID Class Reference, you can generate this parameter by using the following command: FortSdk.getDeviceId(appContext)
Android Mobile SDK Token Response Parameters
These parameters will be returned in the Amazon Payment Services response:
ATTRIBUTES | Description |
---|---|
service_command Alpha Max: 20 |
Command. Possible/ expected values: SDK_TOKEN |
access_code Alphanumeric Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
language Alpha Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
device_id Alphanumeric Max: 100 |
A unique device identifier. Example: ffffffff-a9fa-0b44-7b27-29e70033c587 |
signature Alphanumeric Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
sdk_token Alphanumeric Max: 100 |
An SDK Token to enable using the Amazon Payment Services Mobile SDK. Example: dwp78q3 |
response_message Alphanumeric Max: 150 |
Message description of the response code. It returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
NOTE: Every parameter the merchant sends in the request should be received by the merchant in the response - even the optional parameters.
Processing transactions with the Android SDK
In this section we outline how you process a transaction using the Android mobile SDK. Your first step is to create a mobile SDK token as described above.
Two routes for in-app payment processing
As a merchant you have two ways in which you can process payments using the Amazon Payment Services Android mobile SDK.
Standard payment processing UI
You can use the standard Amazon Payment Services Android SDK interface to display a standard payment UI screen. This option is customizable in two ways – you can hide the loading screen, and some of the UI elements can be customized. We address standard UI customization options in this section.
Custom payment processing UI
Alternatively, you can choose to build your own payment processing UI by custom-coding an in-app payment processing feature. With this mobile SDK feature we allow Amazon Payment Services merchants to integrate and implement a native app checkout experience without displaying a default payment screen.
Using this integration method your customers can securely enter their payment card details on a fully customized merchant checkout landing page using the your customized payment UI.
The Amazon Payment Services Android SDK provides key building blocks including payment card input fields and an action pay button that you can encapsulate inside the checkout landing page and to provide your own inline customer experience.
Amazon Payment Services’ SDK card input fields will securely transmit the completed payment card data to Amazon Payment Services APIs for processing and to complete the transaction placement.
Read more about a customized payment processing UI in this section.
Standard checkout implementation
1: Define a Callback Manager
Define and initialize an instance of the FortCallBackManager in your activity as follows:
private FortCallBackManager fortCallback= null; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); if (fortCallback == null) fortCallback = FortCallback.Factory.create(); }
2: Attach the Callback to the Activity
You need to add the following statement to the onActivityResult function as follows:
@Override protected void onActivityResult(int requestCode, int resultCode, Intent data){ super.onActivityResult(requestCode, resultCode, data); fortCallback.onActivityResult(requestCode,resultCode,data); }
3: Call the Android Mobile SDK and Collecting the Android SDK request
The below code registers a new callback for a new request. The registerCallBack requires the following inputs:
public void registerCallback( Activity context, final FortRequest fortRequest, String environment, final int requestCode, final FortCallBackManager callbackManager, boolean showLoading, final FortInterfaces.OnTnxProcessed callback)
Below is a description for each parameter:
Parameter | Description |
---|---|
context | Passes the currency activity context. |
fortRequest | An instance of the model mentioned in Collect the Android Mobile SDK Request section. |
environment | This parameter used to determine whether the request is going to be submitted to the test or production environment. It has two possible values: - ENVIRONMENT.TEST - ENVIRONMENT.PRODUCTION |
requestCode | A unique ID for this request. |
callBackManager | The instance defined in section Define a Callback Manager. |
showLoading | A Boolean flag to show or hide the loading dialog. |
callback | A transaction callback listener that overrides the following three callback options: - onCancel(): called when the user cancels the payment by clicking the back button. - onSuccess(): called when the transaction is processed successfully. - onFailure(): called when the transaction is failed. |
The Java model/ bean of the Android Mobile SDK request is as follows:
public class FortRequest implements Serializable { private MaprequestMap; private boolean showResponsePage; public Map getRequestMap() { return requestMap; } public void setRequestMap(Map requestMap) { this.requestMap = requestMap; } public boolean isShowResponsePage() { return showResponsePage; } public void setShowResponsePage(boolean showResponsePage) { this.showResponsePage = showResponsePage; } }
NOTE: You can choose to display the Amazon Payment Services response page by passing “showResponsePage” value as “True”.
The “requestMap” must contain all the Amazon Payment Services parameters for the order/ transaction. (Detailed information can be found in our Amazon Payment Services Merchant Integration Guide).
Example:
private MapcollectRequestMap(String sdkToken) { Map requestMap = new HashMap<>(); requestMap.put("command", "PURCHASE"); requestMap.put("customer_email", "Sam@gmail.com"); requestMap.put("currency", "SAR"); requestMap.put("amount", "100"); requestMap.put("language", "en"); requestMap.put("merchant_reference", "merchant_reference "); requestMap.put("sdk_token", sdkToken); return requestMap; }
- Initiate a checkout request:
For every transaction that needs to be processed, do the following call and handle the callback methods upon your business flow:
Example for register callback:
FortSdk.getInstance().registerCallback(this,fortRequest,5,fortCallback, showLoading,new FortInterfaces.OnTnxProcessed() { @Override public void onCancel (Map < String, Object > requestParamsMap, Map < String, Object > responseMap) { } @Override public void onSuccess (Map < String, Object > requestParamsMap, Map < String, Object > fortResponseMap) { } @Override public void onFailure (Map < String, Object > requestParamsMap, Map < String, Object > fortResponseMap) { } }
Android Mobile SDK Device ID Value
Please make sure to use the following Android SDK function to generate the device_id parameter value that must be used for creating the sdk_token from your business security server:
String device_id = FortSdk.getDeviceId(this);
Android mobile SDK parameters
Request parameters
This is a list of the parameters you need to send when you send a request to the Android SDK.
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'command' => 'PURCHASE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
'customer_email' => 'test@payfort.com',
'token_name' => '7288fc8155014c57ad809d8e9574575e',
'sdk_token' => 'Dwp78q3'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command':'PURCHASE',
'access_code':'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier':'CycHZxVj',
'merchant_reference':'XYZ9239-yu898',
'language':'en',
'signature':'7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description':'iPhone 6-S',
'customer_email':'test@payfort.com',
'token_name' : '7288fc8155014c57ad809d8e9574575e',
'sdk_token' : 'Dwp78q3'
};
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' => 'PURCHASE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
'customer_email => 'test@payfort.com',
'token_name' => '7288fc8155014c57ad809d8e9574575e',
'sdk_token' => 'Dwp78q3'
};
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)
String jsonRequestString = "{\n \"command\": \"PURCHASE\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"test-10052\",\n \"amount\": \"20000\",\n \"currency\": \"AED\",\n \"language\": \"en\",\n \"customer_email\": \"test@payfort.com\",\n \"signature\": \"fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b\",\n \"token_name\": \"7288fc8155014c57ad809d8e9574575e\",\n“sdk_token” : “Dwp78q3”\n\n
}";
// 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());
{
"command": "PURCHASE",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "test-10052",
"amount": "20000",
"currency": "AED",
"language": "en",
"customer_email": "test@payfort.com",
"signature": "fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b",
"token_name": "7288fc8155014c57ad809d8e9574575e",
"sdk_token" : “Dwp78q3”
}
ATTRIBUTES | Description |
---|---|
command Alpha Mandatory max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Mandatory Max: 254 |
The customer’s email. Example: customer@domain.com Special characters: _ - . @ + |
sdk_token Alphanumeric Mandatory Max: 100 |
An SDK Token to enable using the Amazon Payment Services Mobile SDK. Example: Dwp78q3 |
token_name Alphanumeric Optional Max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp Special characters: . @ - _ |
payment_option Alpha Optional Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) |
eci Alpha Optional Max: 16 |
Ecommerce indicator. Possible/ expected values: ECOMMERCE |
order_description Alphanumeric Optional Max: 150 |
A description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
customer_ip Alphanumeric Optional max: 45 |
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf Special characters: . : |
customer_name Alpha Optional Max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' |
phone_number Alphanumeric Optional max: 19 |
The customer’s phone number. Example: 00962797219966 Special characters: + - ( ) Space |
settlement_reference Alphanumeric Optional max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 Special characters: - _ . |
merchant_extra Alphanumeric Optional Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra1 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra2 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra3 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra4 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra5 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
billing_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric Optional max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric Optional |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric Optional |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric Optional max: 100 |
The city portion of the address. |
agreement_id Alphanumeric Optional max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
recurring_mode Alphanumeric Optional max: 20 |
Indicates if the subsequent payments within the agreement has same/different amount or unscheduled (unknown interval/amount). Possible/ expected values: UNSCHEDULED, VARIABLE, FIXED |
recurring_transactions_count Alphanumeric Optional max: 100 |
The number of merchant-initiated payments within the recurring payment agreement. ( Required if recurring_mode = VARIABLE or FIXED ) |
recurring_expiry_date |
The date where the merchant needs to end the recurring. The format is YY-MM-DD [Numeric] with special character - |
recurring_days_between_payments |
The number of days between payments agreed with the payer under your agreement with them. The allowed data type is: Numeric only. |
[NOTE]: Before sending the transaction value you must multiply the value by a factor that matches the ISO 4217 specification for that currency. Multiplication is necessary to accommodate decimal values. Each currency’s 3-digit ISO code will have a specification for the number of digits after the decimal separator.
For example: If the transaction value is 500 AED; according to ISO 4217, you should multiply the value with 100 (to accommodate 2 decimal points). You will therefore send an AED 500 purchase amount as a value of 50000.
Another example: If the amount value was 100 JOD; according to ISO 4217, you should multiply the value with 1000 (to accommodate 3 decimal points). You therefore send a JOD 100 purchase amount as a value of 100000
Response parameters
ATTRIBUTES | Description |
---|---|
command Alpha Max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
amount Numeric Max: 10 |
The transaction’s amount.*Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
customer_email Alphanumeric Max: 254 |
The customer’s email. Example: customer1@domain.com |
fort_id Numeric Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
sdk_token Alphanumeric Max: 100 |
An SDK Token to enable using the Amazon Payment Services Mobile SDK. Example: Dwp78q3 |
token_name Alphanumeric max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp |
payment_option Alpha Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) |
eci Alpha Max: 16 |
The E-commerce indicator. Possible/ expected values: ECOMMERCE |
authorization_code Alphanumeric Max: 100 |
The authorization code returned from the 3rd party. Example: P1000000000000372136 |
order_description Alphanumeric Max: 150 |
It holds the description of the order. Example: iPhone 6-S |
response_message Alphanumeric Max: 150 |
The message description of the response code; it returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
customer_ip Alphanumeric max: 45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf |
customer_name Alpha Max: 40 |
The customer’s name. Example: John Smith |
expiry_date Numeric Max: 4 |
The card’s expiry date. Example: 2105 |
card_number Numeric Max: 16 |
The masked credit card’s number. Only the MEEZA payment option takes 19 digits card number. *AMEX payment option takes 15 digits card number. *Otherwise, they take 16 digits card number. Example: 400555*****0001 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
phone_number Alphanumeric max: 19 |
The customer’s phone number. Example: 00962797219966 |
settlement_reference Alphanumeric max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 |
merchant_extra Alphanumeric Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra1 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra2 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra3 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra4 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra5 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
billing_stateProvince Alphanumeric max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric max: 100 |
The city portion of the address. |
agreement_id Alphanumeric max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
Standard checkout UI sample code
Below we include a complete sample code section illustrating the full checkout process when you use the standard checkout UI. The sample includes capturing payment card data, initializing the Amazon Payment Services Android SDK, submitting payment card data and processing a transaction.
public class PayFortSdkSample extends Activity { private FortCallBackManager fortCallback = null; String deviceId = "", sdkToken = ""; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); // create Fort callback instance fortCallback = FortCallback.Factory.create(); // Generating deviceId deviceId = FortSdk.getDeviceId(PayFortSdkSample.this); Log.d("DeviceId ", deviceId); // prepare payment request FortRequest fortrequest = new FortRequest(); fortrequest.setRequestMap(collectRequestMap("PASS_THE_GENERATED_SDK_TOKEN_HERE")); fortrequest.setShowResponsePage(true); // to [display/use] the SDK response page // execute payment request callSdk(fortrequest); } private MapcollectRequestMap(String sdkToken) { Map requestMap = new HashMap<>(); requestMap.put("command", "PURCHASE"); requestMap.put("customer_email", "Sam@gmail.com"); requestMap.put("currency", "SAR"); requestMap.put("amount", "100"); requestMap.put("language", "en"); requestMap.put("merchant_reference", "ORD-0000007682"); requestMap.put("customer_name", "Sam"); requestMap.put("customer_ip", "172.150.16.10"); requestMap.put("payment_option", "VISA"); requestMap.put("eci", "ECOMMERCE"); requestMap.put("order_description", "DESCRIPTION"); requestMap.put("sdk_token", sdkToken); return requestMap; } private void callSdk(FortRequest fortrequest) { FortSdk.getInstance().registerCallback(PayFortSdkSample.this, fortrequest, FortSdk.ENVIRONMENT.TEST, 5, fortCallback, new FortInterfaces.OnTnxProcessed() { @Override public void onCancel(Map requestParamsMap, Map responseMap) { Log.d("Cancelled ", responseMap.toString()); } @Override public void onSuccess(Map requestParamsMap, Map fortResponseMap) { //TODO: handle me Log.i("Success ", fortResponseMap.toString()); } @Override public void onFailure(Map requestParamsMap, Map fortResponseMap) { Log.e("Failure ", fortResponseMap.toString()); } }); } @Override public void onActivityResult(int requestCode, int resultCode, Intent data) { super.onActivityResult(requestCode, resultCode, data); fortCallback.onActivityResult(requestCode, resultCode, data); } }
Customizing the payment UI
You can customize the payment UI presented by our Android SDK in a number of ways to better reflect your business. This is when you use the standard UI.
Customizing the Android Mobile SDK Payment Layout
We provide you with the res folder that includes the source code of the pages in order to customize the design, themes, etc. You can customize both English and Arabic layouts as needed. However, please take the following tips into consideration:
Don’t change the layout name because it is considered an override process.
Make sure to use all the views that has the ID property in order to avoid the NullPointerException.
Redesign the view for portrait orientation. Note that Landscape orientation isn’t supported.
You can support as much layout densities as you want.
Our Mobile SDK v 1.9 consists one of the following three main activities design:
activity_cc_payment.xml
activity_cc_response.xml
activity_init_secure_conn
Figure : Standard vs. Customized Mobile SDK Payment Page Design
Design Customization Codes:
The following code was used to customize the way the Amount is displayed in the Standard Mobile SDK Payment Page:
< TextView android:id="@+id/amountTV" android:layout_width="match_parent" android:layout_height=”38dp" android:background="@color/pf_light_gray" android:gravity="center_horizontal|center_vertical" android:textColor="@color/colorBlack" android:textSize="@dimen/_13ssp" app:layout_constraintTop_toBottomOf="@+id/appbarLayout />
The following code was used to customize the way the Amount is displayed in the Customized Mobile SDK Payment Page:
< LinearLayout android:id="@+id/amountContainer" android:layout_width="match_parent" android:layout_height="wrap_content" android:background="@color/pf_light_gray" android:gravity="center" app:layout_constraintTop_toBottomOf="@+id/appbarLayout"> < ImageView android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginEnd="10dp" android:src="@drawable/merchant" android:layout_marginRight="10dp" /> < TextView android:id="@+id/amountTV" android:layout_width="wrap_content" android:layout_height="@dimen/_38sdp" android:gravity="center_horizontal|center_vertical" android:textColor="@color/colorBlack" android:textSize="@dimen/_13ssp" tools:text="10.00 USD" /> < / LinearLayout >
As appears in the previous codes, elements with IDs haven’t been changed in type or removed. For example: android:id=\“@+id/amountTV\”.
We were able to add static elements such as: “ImageView” element that contains the Merchant’s logo.
To sum up, you can add any static elements or redesign the view, while keeping the views’ elements used in the Standard layout that hold IDs.
[NOTE] The customized XML file should be added to the layout file in the target project (Merchant Application) to override the SDK file.
Custom-coding a payment processing UI
In this section we outline key information that you need to create your own payment processing UI using the tools in our Android SDK.
Stage 1: Generate an SDK token
You need to generate an SDK token before you can start processing payments using your custom payment processing UI. Refer to the SDK token section earlier in this document for instructions on creating an SDK token.
Stage 2: Creating the card components
You create your custom payment screen by using the following five components included in the Amazon Payment Services Android SDK:
Table of components
The Android Mobile SDK allows merchants to securely integrate the payment functions through Custom Components:
FortCardNumberView (Check CardBrand,CardNumber)
CardCvvView (Check if cvv match cardBrand)
CardExpiryView (Check date)
CardHolderNameView
PayfortPayButton (Collect data from previous Components)
Attributes | Type | Description |
---|---|---|
app:boxBackgroundShape | Enum 1- none 2- filled 3- outlione |
Whether the text input area should be drawn as a filled box, an outline box, or not as a box. |
app:hintTextColor | Reference or color Ex : #fff123 | Color of the hint text. |
app:hintText | String | Hint text to display when the text is empty. |
app:textSize | Dimension Ex : 12sp | Size of the text. Recommended dimension type for text is “sp” |
app:textColor | Reference or color Ex : #fff123 | text Color of the text displayed in the text input area |
app:boxStrokeErrorColor | Color Ex : #fff123 | The color to use for the box’s stroke in outline box mode when an error is being displayed. If not set, it defaults to errorTextColor if on error state |
app:errorTextColor | Color Ex : #fff123 | Text color for any error message displayed. If set, this takes precedence over errorTextAppearance. |
app:errorTextAppearance | Reference Ex: @style/customStyle | TextAppearance of any error message displayed. |
app:boxBackgroundColor | Color Ex : #fff123 | The color to use for the box’s background color when in filled box mode.If a non-stateful color resource is specified, default colors will be used for the hover and disabled states. |
XML Usage
Card components
< com.payfort.fortpaymentsdk.views.FortCardNumberView android:id="@+id/etCardNumberView" android:layout_width="match_parent" android:layout_height="wrap_content" app:boxBackgroundShape="outline" /> < com.payfort.fortpaymentsdk.views.CardExpiryView android:id="@+id/etCardExpiry" android:layout_width="match_parent" android:layout_height="wrap_content" app:boxBackgroundShape="outline" /> < com.payfort.fortpaymentsdk.views.CardCvvView android:id="@+id/etCardCvv" android:layout_width="match_parent" android:layout_height="wrap_content" app:boxBackgroundShape="outline" /> < com.payfort.fortpaymentsdk.views.CardHolderNameView android:id="@+id/cardHolderNameView" android:layout_width="match_parent" android:layout_height="wrap_content" app:boxBackgroundShape="outline" />
Stage 3: Initiate the actual payment.
PayfortPayButton
Responsible for collecting card data from Card Components above and Submit Successful payment with simple Few steps also it’s had the capability to do Direct Pay without needs for Card Components
< com.payfort.fortpaymentsdk.views.PayfortPayButton android:id="@+id/btntPay" android:layout_width="match_parent" android:layout_height="wrap_content" />
PayfortPayButton Methods
/** * Responsible for Save token or not * @param isRememberMe Boolean */ fun isRememberMeEnabled(isRememberMe: Boolean) /** * Update Request After doing Setup * @param fortRequest FortRequest */ fun updateRequest(fortRequest: FortRequest) /** * this Setup used with Pay with Full Components from outside SDK * @param environment String * @param request FortRequest * @param payComponents PayComponents * @param payFortCallback PayFortCallback */ fun setup(environment: String, request: FortRequest, payComponents: PayComponents, payFortCallback: PayFortCallback) /** * this Setup used with DirectPay only * @param environment String * @param request FortRequest * @param payFortCallback PayFortCallback? */ fun setup(environment: String, request: FortRequest, payFortCallback: PayFortCallback?)
Sample Code
In this example we explain how to use PayfortPayButton with Card Components in the custom UI screen.
Kotlin
//You Need to Create PayComponents Object that holds all Card Components val payComponents = PayComponents(etCardNumberView, cvvView = etCardCvv, etCardExpiry, holderNameView = cardHolderNameView)//then you need to Create FortRequest via FortRequest.class val fortRequest= FortRequest() // fill all the parameters required
//then you need to choose the environment Via FortSdk.ENVIRONMENT it's contains TEST and PRODUCTION ENVIRONMENTS val environment= FortSdk.ENVIRONMENT.TEST
// Finally you need to decleare a PayFortCallback var callback= object : PayFortCallback { override fun startLoading() { } override fun onSuccess(requestParamsMap: Map
, fortResponseMap: Map ) {} override fun onFailure(requestParamsMap: Map , fortResponseMap: Map ) { } } btnPay.setup(environment, fortRequest, payComponents, callback)
Java
//You Need to Create PayComponents Object that holds all Card Components PayComponents payComponents = new PayComponents(etCardNumberView, etCardCvv, etCardExpiry, cardHolderNameView); //then you need to Create FortRequest via FortRequest.class FortRequest fortRequest = new FortRequest(); // fill all the parameters required //then you need to chsose the environment Via FortSdk.ENVIRONMENT it's contains TEST and PRODUCTION ENVIRONMENTS String environment = FortSdk.ENVIRONMENT.TEST; // Finally you need to decleare a PayFortCallback PayFortCallback callback = new PayFortCallback() { @Override public void startLoading() { } @Override public void onSuccess(@NotNull MaprequestParamsMap, @NotNull Map fortResponseMap) { } @Override public void onFailure(@NotNull Map requestParamsMap, @NotNull Map fortResponseMap) { } }; btnPay.setup(environment, fortRequest, payComponents, callback)
Using Direct Pay
The Direct Pay feature enables Amazon Payment Services merchants to securely process e-commerce transactions using tokenized payment card details.
For customers that already supplied their payment card details in a previous transaction and where a card token was generated, customers need to just provide the card security code to complete their purchase.
The card token and provided card security code can be sent to the Amazon Payment Services Android mobile SDK to complete the customer purchase through Direct Pay operation to complete the order placement using eCommerce channel.
Note you can use Direct Pay both with the standard payment UI or with a customized payment UI.
Direct Pay sample code
In this example we demonstrate how to use PayfortPayButton with DirectPay. This Method is required to pass card_security_code and token_name to FortRequest.
Kotlin
private fun collectRequestMap(sdkToken: String): FortRequest { val fortRequest = FortRequest() val requestMap: MutableMap= HashMap() requestMap["command"] = "AUTHORIZATION" requestMap["customer_email"] = "Sam@gmail.com" requestMap["currency"] = "AED" requestMap["amount"] = "100" requestMap["language"] = "en" requestMap["card_security_code"] = "123" requestMap["token_name"] = "payfort" requestMap["merchant_reference"] = "merchant_reference" requestMap["sdk_token"] = sdkToken fortRequest.requestMap = requestMap fortRequest.isShowResponsePage = false return fortRequest } //you need to Create FortRequest via FortRequest.class val fortRequest=collectRequestMap("SDK_TOKEN") //then you need to chsose the environment Via FortSdk.ENVIRONMENT it's contains TEST and PRODUCTION ENVIRONMENTS val environment= FortSdk.ENVIRONMENT.TEST // Finally you need to decleare a PayFortCallback var callback= object : PayFortCallback { override fun startLoading() { } override fun onSuccess(requestParamsMap: Map , fortResponseMap: Map ) {} override fun onFailure(requestParamsMap: Map , fortResponseMap: Map ) { } } btnPay.setup(environment, fortRequest, callback)
Java
private FortRequest collectRequestMap(String sdkToken) { FortRequest fortRequest= new FortRequest(); MaprequestMap = new HashMap<>(); requestMap.put("command", "AUTHORIZATION"); requestMap.put("customer_email", "Sam@gmail.com"); requestMap.put("currency", "AED"); requestMap.put("amount", "100"); requestMap.put("language", "en"); requestMap.put("card_security_code", "123"); requestMap.put("token_name", "payfort"); requestMap.put("merchant_reference", "merchant_reference"); requestMap.put("sdk_token", sdkToken); fortRequest.setRequestMap(requestMap); fortRequest.setShowResponsePage(false); return fortRequest; } //you need to Create FortRequest via FortRequest.class FortRequest fortRequest = collectRequestMap(“SDK_TOKEN”); //then you need to chsose the environment Via FortSdk.ENVIRONMENT it's contains TEST and PRODUCTION ENVIRONMENTS String environment = FortSdk.ENVIRONMENT.TEST; // Finally you need to decleare a PayFortCallback PayFortCallback callback = new PayFortCallback() { @Override public void startLoading() {} @Override public void onSuccess(@NotNull Map requestParamsMap, @NotNull Map fortResponseMap) {} @Override public void onFailure(@NotNull Map requestParamsMap, @NotNull Map fortResponseMap) {} }; btnPay.setup(environment, fortRequest, callback);
Amazon Payment Services Android SDK transaction feedback
While a transaction is completed, we will send a response directly to your direct transaction feedback URL. In theory, direct response feedback cannot be interrupted unless the URL you provided for responses is not functional at the time of the response.
We do this so that your server receives a response even if your customer does not successfully redirect to the return URL on your website, which may happen if your customer’s browser or connection fails during the transaction.
Receiving transaction feedback
There are two ways in which you receive transaction feedback:
Direct transaction feedback. Amazon Payment Services sends an immediate payment processing response whenever a transaction is completed.
You can rely on this response for transaction feedback even where your user closed the browser before getting redirected successfully to the redirection URL or where your user was not redirected due to a drop in the internet connection.
Notification feedback. Were we need to provide you with the status of a transaction once it is received. In other words, we send notification feedback to alert you to any changes in the status of a transaction.
For example, if the transaction was pending due to the unavailability of any party to the transaction, the final update will be pushed to your notification feedback endpoint.
Notification feedback deals with a wide range of scenarios and it is critical that your website is configured to receive notification feedback correctly. For example, transaction feedback can alert you to any transactions that were stuck in “uncertain” status, but which have recovered to final status.
Direct feedback allows you to subscribe to transaction updates for uncertain transactions whenever you process a payment. It is a method for receiving the transaction response automatically once the transaction had completed or if there was an update.
Registering Transaction Feedback URLs
To receive transaction feedback, you must register with Amazon Payment Services the transaction feedback URLs you set up on your server. Follow these steps:
Log in to your back-office account.
Select the active channel under Integration Settings > Technical Settings.
Enter your Direct Transaction Feedback URL and Notification Transaction Feedback URL.
Click “Save Changes” button.
Transaction Feedback Implementation
We will send the response via HTTP POST request in POST form format to your webhook URL. The submission type can be changed from POST form to JSON or XML in your APS account settings. We only permit configuring URLs in HTTPS for direct feedback and for notification feedback.
To acknowledge receiving the direct feedback and notification successfully, the webhook URL must return a 2xx or 302 HTTP status. In case the URL returns different HTTP responses, our server will keep retrying up to 10 times until we receive a success response. We wait ten seconds between retries.
You can change and configure the retry mechanism attributes to increase or decrease the number of retries, time between retries and the grace period before we send the notifications.
You must create endpoints that accept direct transaction feedback and notification feedback from us via a webhook. You can customize how transaction feedback works – for example, by including the grace period before a direct feedback notification is sent, and the time elapsed between retrying feedback submission.
To customize transaction feedback, email integration-ps@amazon.com. You can request to change the submission type to JSON or XML. You can also change the grace period or the time interval between the retries please contact us on integration@payfort.com
[NOTE] You can check the direct and notification feedback logs in your back office account to check the details related to the submission like the Transaction Feedback URL which was triggered, The response which our system pushed, the response Code and Status retuned from your Transaction Feedback URL.
[NOTE] The specifics of the data will differ based upon the financial operation that has been processed. Your code must be able to accommodate different data.
Validate API call
Amazon Payment Services offers an API to request validation of the payment card details without performing an actual transaction.
Validate API can help you to initiate an API request in order to validate the input parameters values, this will reduce the possibility of encountered API errors due to wrong user inputs before processing the actual payment card transaction.
Fort SDK has a new method (validate) in FortSdk.class This method can validate FortRequest to check all parameters for validity.
/** * Responsible for Validating FortRequest * @param context Context * @param environment String * @param fortRequest FortRequest * @param fortCallback PayFortCallback */ fun validate(context: Context, environment: String ,fortRequest: FortRequest, fortCallback: PayFortCallback)
Example:
Java
// you need to Create FortRequest via FortRequest.class FortRequest fortRequest = new FortRequest(); // fill all the parameters required //then you need to chsose the environment Via FortSdk.ENVIRONMENT //it's contains TEST and PRODUCTION ENVIRONMENTS String environment = FortSdk.ENVIRONMENT.TEST; // Finally you need to decleare a PayFortCallback PayFortCallback callback = new PayFortCallback() { @Override public void startLoading() { } @Override public void onSuccess(@NotNull MaprequestParamsMap, @NotNull Map fortResponseMap) { } @Override public void onFailure(@NotNull Map requestParamsMap, @NotNull Map fortResponseMap) { } }; FortSdk fortSdk = FortSdk.getInstance(); fortSdk.validate(this,environment,fortRequest,callback);
Kotlin
// you need to Create FortRequest via FortRequest.class val fortRequest = FortRequest() // fill all the parameters required //then you need to chsose the environment Via FortSdk.ENVIRONMENT it's contains TEST and PRODUCTION ENVIRONMENTS val environment = FortSdk.ENVIRONMENT.TEST // Finally you need to decleare a PayFortCallback val callback: PayFortCallback = object : PayFortCallback { override fun startLoading() {} override fun onSuccess(requestParamsMap: Map, fortResponseMap: Map ) {} override fun onFailure(requestParamsMap: Map , fortResponseMap: Map ) {} } val fortSdk = FortSdk.getInstance() fortSdk.validate(this, environment, fortRequest, callback)
[NOTE] When you make use of the Validate API call you still need to generate a mobile SDK token even though you are not processing a transaction.
Migrating the previous version
In this section we outline the steps you need to take to migrate the Amazon Payment Services Android SDK to the latest release. To complete the migration, follow these steps:
Remove old SDK from Libs Folder
Remove old dependencies from Gradle file that related to old SDK
dependencies { implementation fileTree(include: ['*.jar'], dir: 'libs') api project(path: ':FORTSDKv1.6') api 'com.android.support:design:29+' implementation 'androidx.appcompat:appcompat:1.1.0' api 'com.victor:lib:1.0.1' api 'com.google.code.gson:gson:2.8.0' api 'com.shamanland:fonticon:0.1.8' api('com.nispok:snackbar:2.11.+') { // exclusion is not necessary, but generally a good idea. exclude group: 'com.google.android', module: 'support-v4' } api 'com.google.guava:guava:19.0' api 'org.bouncycastle:bcprov-jdk16:1.46' }
3: Check the installation steps in section 3
4: Make sure to sync new SDK in your Gradle File
**File \> Sync Project with Gradle Files**
5: For merchants that already use custom layout feature, they need to replace their custom layout xml files that related to previous SDK versions (< 2.0) and override it with new one.
Note: if you override Arabic xml files you need to delete it since new SDK support it without the need to override it.
Below the difference between old SDK layout and new one:
XML Files | old SDK | new SDK |
---|---|---|
activity_cc_payment | Download | Download |
activity_cc_response | Download | Download |
activity_init_secure_conn | Download | Download |
6: Change old imports to new imports
Old imports
import com.payfort.fort.android.sdk.base.FortSdk; import com.payfort.sdk.android.dependancies.commons.Constants.FORT_PARAMS; import com.payfort.fort.android.sdk.base.FortSdk; import com.payfort.fort.android.sdk.base.callbacks.FortCallBackManager; import com.payfort.fort.android.sdk.base.callbacks.FortCallback; import com.payfort.sdk.android.dependancies.base.FortInterfaces; import com.payfort.sdk.android.dependancies.models.FortRequest;
New imports
import com.payfort.fortpaymentsdk.constants.Constants.FORT_PARAMS; import com.payfort.fortpaymentsdk.FortSdk; import com.payfort.fortpaymentsdk.callbacks.FortCallBackManager; import com.payfort.fortpaymentsdk.callbacks.FortCallback; import com.payfort.fortpaymentsdk.callbacks.FortInterfaces; import com.payfort.fortpaymentsdk.domain.model.FortRequest;
7: Make Sure to enable ViewBinding in your project
To enable view binding in a module, set the viewBinding build option to true in the module-level build.gradle file, as shown in the following example:
android { ... buildFeatures { viewBinding true } }
8: Make Sure to use Java 8
To start using supported Java 8 language features, update the Android plugin to 3.0.0 (or higher). After that, for each module that uses Java 8 language features (either in its source code or through dependencies), update the module’s build.gradle file, as shown below:
android { ... // Configure only for each module that uses Java 8 // language features (either in its source code or // through dependencies). compileOptions { sourceCompatibility JavaVersion.VERSION_1_8 targetCompatibility JavaVersion.VERSION_1_8 } // For Kotlin projects kotlinOptions { jvmTarget = "1.8" } }
Appendix: About the Software
About this software
The Amazon Payment Services Android mobile SDK allows merchants to securely integrate payment functionality into a native Android app. It allows merchants to easily accept in-app payments.
Instead of the traditional, time-consuming, and complex way of being redirected to the mobile browser to complete the payment, in-app payments can easily be offered thanks to the Android Mobile SDK. In turn, this gives the merchants’ customers a smooth, pleasing user experience thanks to in-app payment functions through the native applications. (move to about this software)
Supported Platforms
The Amazon Payment Services Android SDK supports devices running Android 4.1.x and later (API level 16). In other words, Android Ice Cream Sandwich or higher is supported. This release supports Android Pie API 28.
Localization
You can use both English and Arabic when you implement the Android SDK.
Screen Orientation
Currently, portrait is the only orientation supported within the Amazon Payment Services mobile SDK – unless you build a customized payment integration.
Supported Payment Methods
Using the Android SDK the merchant can process debit or credit card transactions only.
Supported Payment Options
The supported credit card payment options are VISA, MASTERCARD, American Express (AMEX), MADA and MEEZA.
iOS Mobile SDk
Before you start the integration
Read through the following steps first to understand how the integration process works. This will help you to understand why these steps are required and why you need to follow a specific sequence.
Step 1: Access your test account
You need to make sure that you have access to a test account with Amazon Payment Services. It is a full test environment that allows you to fully simulate transactions.
Step 2: Choose between a standardized or custom payment UI
The Amazon Payment Services iOS SDK provides you with a standard payment UI that you can use to quickly integrate in-app payments. The standard UI offers limited customizability.
Alternatively, you can choose to build your own payment UI using Amazon Payment Services iOS SDK building blocks, we describe this in the section on custom-coding a payment processing UI.
Step 3: Make sure that you are using the correct integration type
Prior to building the integration, you need to make sure that you are selecting and using the proper parameters in the API calls as per the required integration type. All the mandatory parameters are mentioned under every section in the API document
Step 4: Install the Amazon Payment Services iOS SDK in your development environment
You need to download our iOS SDK from the link provided. Next you need to include the iOS SDK in your Xcode project by following the steps in the next section. You are also required to install the library and to integrate the iOS SDK into your app.
Step 5: Create a test transaction request
You need to create a test transaction request. Processing a valid API request depends on the transaction parameters included, you need to check the documentation and review every parameter to reduce the errors in processing the transaction.
Step 6: Process a transaction response
After every payment, Amazon Payment Services returns the transaction response on the URL configured in your account under Technical Settings, Channel Configuration.
For more details review the transaction feedback instructions in this section. You need to validate the response parameters returned on this URL by calculating the signature for the response parameters using the SHA response phrase configured in your account under security settings.
Step 7: Test and Go Live
You can use our test card numbers to test your integration and simulate your test cases. The Amazon Payment Services team may need to test your integration before going live to assure your application integration.
Mobile SDK transaction workflow
Below we describe the transaction workflow that occurs when you process a payment using the Amazon Payment Service iOS Mobile SDK.
Your customer clicks on the Pay button in your app.
Your merchant system (back-end) generates a mobile SDK token using the Amazon Payment Services API.
Your app passes the parameters, including the SDK token, to the iOS mobile SDK.
The iOS mobile SDK starts a secure connection and sends the transaction request to the Amazon Payment Services server to be validated.
The Amazon Payment Services API validates the SDK token, device_ID and other request parameters and returns the validation response to the iOS SDK.
Assuming validation is passed your merchant app displays a payment page to the customer.
Your customer enters their payment details on the payment page in the iOS SDK prompt on their device.
The Amazon Payment Services iOS SDK validates your customer’s details and sends a transaction (Authorization or Purchase) request to the relevant payment processor and issuing bank.
The payment processor processes the transaction request and returns a transaction response to the iOS SDK.
The Amazon Payment Services iOS SDK returns the transaction response to your merchant app.
Your merchant app displays the response to your customer.
Installing the Mobile SDK
These are the first steps you need to follow to install the Amazon Payment Services iOS SDK in your iOS application.
Include the SDK in your Xcode project
You have two options for including the SDK in your Xcode project. You can do so manually, or you can include the SDK by using CocoaPods
Manual installation
Obtain the Amazon Payment Services iOS Mobile SDK by downloading it from the Amazon Payment Services website.
Extract the folder you downloaded in the previous step.
Drag PayFortSDK.xcframework into the Frameworks, Libraries, and Embedded Content section of your target.
Installation using CocoaPods:
[NOTE]: The PayFort SDK is distributed as an XCFramework, therefore you are required to use Cocoapods 1.9.0 or newer.
- Add the following code to your Podfile (inside the target section):
pod 'PayFortSDK'
- Add the following to the bottom of your Podfile:
post_install do |installer| installer.pods_project.targets.each do |target| if ['PayFortSDK'].include? target.name target.build_configurations.each do |config| config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES' end end end end
- Run the following command:
pod install
[NOTE]: Ensure it is linked once in the Linked Framework and Libraries or just drag the PayFortSDK.xcframework to Embedded Binaries in the general tab in the project settings.
[NOTE]: In Xcode, secondary-click your project’s .plist file and select Open As Source Code. Insert the following XML snippet into the body of your file just before the final, as below:
< dict>elementNSAppTransportSecurity < dict>NSAllowsArbitraryLoads < /dict>
Ensuring your application does not disconnect in background mode
To ensure that your app does not disconnect from the SDK when it goes into the background make sure to add this code:
Objective-C:
(void)applicationDidEnterBackground:(UIApplication *)application { block UIBackgroundTaskIdentifier backgroundTask; backgroundTask = [application beginBackgroundTaskWithExpirationHandler: ^ { [application endBackgroundTask:backgroundTask]; backgroundTask = UIBackgroundTaskInvalid; }]; }
Swift
func applicationDidEnterBackground(_ application: UIApplication) { var bgTask: UIBackgroundTaskIdentifier = 0 bgTask = application.beginBackgroundTask(expirationHandler: { application.endBackgroundTask(bgTask) bgTask = UIBackgroundTaskInvalid }) }
Creating a mobile SDK token
A mobile SDK authentication token is required to authenticate every request sent to the SDK. The token is also significant to process payment operations with Amazon Payment Services through our iOS mobile SDK.
To get started with our iOS mobile SDK you must first establish the ability to generate a mobile SDK token.
[NOTE]: The creation and initiation of a mobile SDK token happens on your server – your server must generate the token by sending a request to the Amazon Payment Services API.
[NOTE:] A unique authentication token must be created for each transaction. Each authentication token has a life-time of only one hour if no new request from the same device is sent.
Mobile SDK token URLs
These are the URLs you need to use when you request a mobile SDK token for your iOS app:
Test Environment URL
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production Environment URL
https://paymentservices.payfort.com/FortAPI/paymentApi
Submitting token request parameters
You need to submit parameters as a REST POST request using JSON. Below we list the range of parameters for the iOS mobile SDK token request.
iOS Mobile SDK Token Request Parameters
When you send your request for an iOS mobile SDK token you must send the following parameters to Amazon Payment Services:
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'service_command' => 'SDK_TOKEN',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'language' => 'en',
'device_id'=> 'ffffffff-a9fa-0b44-7b27-29e70033c587',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
);
$ch = curl_init( $url );
# Setup request to send json via POST.
$data = json_encode($arrData);
curl_setopt( $ch, CURLOPT_POSTFIELDS, $data );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
# Return response instead of printing.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
# Send request.
$result = curl_exec($ch);
curl_close($ch);
# Print response.
echo "<pre>$result</pre>";
curl -H "Content-Type: application/json" -d
'{"service_command":"SDK_TOKEN","language":"en","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj",,"language":"en","device_id":"ffffffff-a9fa-0b44-7b27-29e70033c587",
"signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a"}'
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'service_command' : 'SDK_TOKEN',
'access_code' : 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' : 'CycHZxVj',
'language' : 'en',
'device_id': 'ffffffff-a9fa-0b44-7b27-29e70033c587',
'signature' : '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
};
values = json.dumps(arrData)
data = urllib.urlencode(values)
req = urllib2.Request(url, data)
response = urllib2.urlopen(req)
page = response.read()
print page + '\n\n'
String jsonRequestString = "{\"service_command\" : \"SDK_TOKEN\" , "
+"\"access_code\" : \"zx0IPmPy5jp1vAz8Kpg7\", "
+"\"merchant_identifier\" : \"CycHZxVj\", "
+ "\"language\" : \"en\","
+ "\"device_id\"\"ffffffff-a9fa-0b44-7b27-29e70033c587\", "
+ "\"signature\" : \"7cad05f0212ed933c9a5d5dffa31661acf2c827a\"}";
// Define and Initialize HttpClient
HttpClient httpClient = HttpClientBuilder.create().build();
// Intialize HttpPOST with FORT Payment services URL
HttpPost request = new HttpPost("https://sbpaymentservices.payfort.com/FortAPI/paymentApi");
// Setup Http POST entity with JSON String
StringEntity params = new StringEntity(jsonRequestString);
// Setup request type as JSON
request.addHeader("content-type", "application/json");
request.setEntity(params);
// Post request to FORT
HttpResponse response = httpClient.execute(request);
// Read response using StringBuilder
StringBuilder sb = new StringBuilder();
BufferedReader reader = new BufferedReader(new InputStreamReader(
response.getEntity().getContent()), 65728);
String line = null;
while ((line = reader.readLine()) != null) {
sb.append(line);
}
// Print response
System.out.println(sb.toString());
require 'json'
require 'net/http'
require 'net/https'
require 'uri'
require 'openssl'
arrData = {
'service_command' => 'SDK_TOKEN',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'language' => 'en',
'device_id'=> 'ffffffff-a9fa-0b44-7b27-29e70033c587',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
};
arrData = arrData.to_json
uri = URI.parse("https://sbpaymentservices.payfort.com/FortAPI/paymentApi")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new("/v1.1/auth")
request.add_field('Content-Type', 'application/json')
request.body = arrData
response = http.request(request)
ATTRIBUTES | Description |
---|---|
service_command Alpha Mandatory max: 20 |
Command. Possible/ expected values: SDK_TOKEN Special characters: _ |
access_code Alphanumeric Mandatory Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
device_id Alphanumeric Mandatory Max: 100 |
A unique device identifier. Example: ffffffff-a9fa-0b44-7b27-29e70033c587 Special characters: - |
signature Alphanumeric Mandatory Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
[NOTE:] device_id - This value to be generated from the UIDevice Class Reference, and you can generate this parameter by using the following command: [payFort getUDID]
iOS Mobile SDK Token Response Parameters
These parameters will be returned in the Amazon Payment Services response:
ATTRIBUTES | Description |
---|---|
service_command Alpha Max: 20 |
Command. Possible/ expected values: SDK_TOKEN |
access_code Alphanumeric Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
language Alpha Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
device_id Alphanumeric Max: 100 |
A unique device identifier. Example: ffffffff-a9fa-0b44-7b27-29e70033c587 |
signature Alphanumeric Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
sdk_token Alphanumeric Max: 100 |
An SDK Token to enable using the Amazon Payment Services Mobile SDK. Example: dwp78q3 |
response_message Alphanumeric Max: 150 |
Message description of the response code. It returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
NOTE: Every parameter the merchant sends in the request should be received by the merchant in the response - even the optional parameters.
Processing transactions with the iOS SDK
In this section we outline how you process a transaction using the iOS mobile SDK.
Two routes for payment processing
As a merchant you have two ways in which you can process payments using the Amazon Payment Services iOS mobile SDK.
Standard payment screen. You can use the standard Amazon Payment Services iOS SDK interface to display a standard payment screen.
This standard payment view is customizable in three ways. You can hide the loading screen, and you can change the presentation style from full screen to OS default. You can also customize some of the UI elements. We address customizing the standard payment screen in this section.
Custom integration. You can choose to build your own payment processing screen by coding your own payment processing screen. With this mobile SDK feature, we allow merchants to integrate a native app checkout experience without displaying our standard payment screen – while still using SDK features for rapid go-live.
With this integration route your customers can securely pay using a custom merchant checkout interface. The SDK provides card input fields and a pay button that merchants can encapsulate inside their checkout interface to match their own inline customer experience.
The Amazon Payment Services SDK will securely transmit the completed card details to the Amazon Payment Services API for processing in order to complete the transaction. We discuss the custom-coded payment UI in this section.
Steps for standard checkout
These are the steps you need to follow to perform a checkout using our standard UI. See the next section for building your own customized payment UI.
1- Import the framework into your app
Start by importing the Amazon Payment Service iOS SDK library. You do so by using the following code:
Objective-C
#import < PayFortSDK/PayFortSDK-Swift.h>
Swift
import PayFortSDK
2- Initialize the controllers
Initialize PayFortController within the targeted environment. You set the target environment by setting one of the two ENUM, either PayFortEnviromentSandBox or PayFortEnviromentProduction
Objective-C
PayFortController *payFort = [[PayFortController alloc]initWithEnviroment: PayFortEnviromentSandBox];
Swift
let payFort = PayFortController.init(enviroment: .sandBox)
3- Preparing Request Parameters
Set a dictionary that contains all keys and values for the SDK
Objective-C
NSMutableDictionary *request = [[NSMutableDictionary alloc]init]; [request setValue:@"10000" forKey:@"amount"]; [request setValue:@"AUTHORIZATION" forKey:@"command"]; [request setValue:@"USD" forKey:@"currency"]; [request setValue:@ "email@domain.com" forKey:@"customer_email"] [request setValue:@"en" forKey:@"language"]; [request setValue:@"112233682686" forKey:@"merchant_reference"] [request setValue:@"SDK TOKEN GOES HERE" forKey:@"sdk_token"]; [request setValue:@"" forKey:@"payment_option"]; [request setValue:@"gr66zzwW9" forKey:@"token_name"];
Swift
let request = ["amount" : "1000", "command" : "AUTHORIZATION", "currency" : "AED", "customer_email" : "rzghebrah@payfort.com", "installments" : "", "language" : "en", "sdk_token" : "token"]
4 . Response callback function
Amazon Payment Services allows you retrieve and receive the response parameters after processing a transaction once the transaction is completed. It only happens during the installation process. This is the code you need to use: Objective-C
[payFort callPayFortWithRequest:request currentViewController:self success:^(NSDictionary *requestDic, NSDictionary *responeDic) { NSLog(@"Success"); NSLog(@"responeDic=%@",responeDic); } canceled:^(NSDictionary *requestDic, NSDictionary *responeDic) { NSLog(@"Canceled"); NSLog(@"responeDic=%@",responeDic); } faild:^(NSDictionary *requestDic, NSDictionary *responeDic, NSString *message) { NSLog(@"Faild"); NSLog(@"responeDic=%@",responeDic); }];
Swift
payFort.callPayFort(withRequest: request, currentViewController: self, success: { (requestDic, responeDic) in print("success") }, canceled: { (requestDic, responeDic) in print("canceled") }, faild: { (requestDic, responeDic, message) in print("faild") })
iOS mobile SDK operations
Request parameters
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'command' => 'PURCHASE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
'customer_email' => 'test@payfort.com',
'token_name' => '7288fc8155014c57ad809d8e9574575e',
'sdk_token' => 'Dwp78q3'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command':'PURCHASE',
'access_code':'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier':'CycHZxVj',
'merchant_reference':'XYZ9239-yu898',
'language':'en',
'signature':'7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description':'iPhone 6-S',
'customer_email':'test@payfort.com',
'token_name' : '7288fc8155014c57ad809d8e9574575e',
'sdk_token' : 'Dwp78q3'
};
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' => 'PURCHASE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
'customer_email => 'test@payfort.com',
'token_name' => '7288fc8155014c57ad809d8e9574575e',
'sdk_token' => 'Dwp78q3'
};
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)
String jsonRequestString = "{\n \"command\": \"PURCHASE\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"test-10052\",\n \"amount\": \"20000\",\n \"currency\": \"AED\",\n \"language\": \"en\",\n \"customer_email\": \"test@payfort.com\",\n \"signature\": \"fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b\",\n \"token_name\": \"7288fc8155014c57ad809d8e9574575e\",\n“sdk_token” : “Dwp78q3”\n\n
}";
// 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());
{
"command": "PURCHASE",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "test-10052",
"amount": "20000",
"currency": "AED",
"language": "en",
"customer_email": "test@payfort.com",
"signature": "fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b",
"token_name": "7288fc8155014c57ad809d8e9574575e",
"sdk_token" : “Dwp78q3”
}
This is a list of the parameters you need to send when you send a request to the iOS SDK.
ATTRIBUTES | Description |
---|---|
command Alpha Mandatory max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Mandatory Max: 254 |
The customer’s email. Example: customer@domain.com Special characters: _ - . @ + |
sdk_token Alphanumeric Mandatory Max: 100 |
An SDK Token to enable using the Amazon Payment Services Mobile SDK. Example: Dwp78q3 |
token_name Alphanumeric Optional Max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp Special characters: . @ - _ |
payment_option Alpha Optional Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) |
eci Alpha Optional Max: 16 |
Ecommerce indicator. Possible/ expected values: ECOMMERCE |
order_description Alphanumeric Optional Max: 150 |
A description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
customer_ip Alphanumeric Optional max: 45 |
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf Special characters: . : |
customer_name Alpha Optional Max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' |
phone_number Alphanumeric Optional max: 19 |
The customer’s phone number. Example: 00962797219966 Special characters: + - ( ) Space |
settlement_reference Alphanumeric Optional max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 Special characters: - _ . |
merchant_extra Alphanumeric Optional Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra1 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra2 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra3 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra4 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra5 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
billing_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric Optional max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric Optional |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric Optional |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric Optional max: 100 |
The city portion of the address. |
agreement_id Alphanumeric Optional max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
recurring_mode Alphanumeric Optional max: 20 |
Indicates if the subsequent payments within the agreement has same/different amount or unscheduled (unknown interval/amount). Possible/ expected values: UNSCHEDULED, VARIABLE, FIXED |
recurring_transactions_count Alphanumeric Optional max: 100 |
The number of merchant-initiated payments within the recurring payment agreement. ( Required if recurring_mode = VARIABLE or FIXED ) |
recurring_expiry_date |
The date where the merchant needs to end the recurring. The format is YY-MM-DD [Numeric] with special character - |
recurring_days_between_payments |
The number of days between payments agreed with the payer under your agreement with them. The allowed data type is: Numeric only. |
Response parameters
ATTRIBUTES | Description |
---|---|
command Alpha Max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
amount Numeric Max: 10 |
The transaction’s amount.*Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
customer_email Alphanumeric Max: 254 |
The customer’s email. Example: customer1@domain.com |
fort_id Numeric Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
sdk_token Alphanumeric Max: 100 |
An SDK Token to enable using the Amazon Payment Services Mobile SDK. Example: Dwp78q3 |
token_name Alphanumeric max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp |
payment_option Alpha Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) |
eci Alpha Max: 16 |
The E-commerce indicator. Possible/ expected values: ECOMMERCE |
authorization_code Alphanumeric Max: 100 |
The authorization code returned from the 3rd party. Example: P1000000000000372136 |
order_description Alphanumeric Max: 150 |
It holds the description of the order. Example: iPhone 6-S |
response_message Alphanumeric Max: 150 |
The message description of the response code; it returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
customer_ip Alphanumeric max: 45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf |
customer_name Alpha Max: 40 |
The customer’s name. Example: John Smith |
expiry_date Numeric Max: 4 |
The card’s expiry date. Example: 2105 |
card_number Numeric Max: 16 |
The masked credit card’s number. Only the MEEZA payment option takes 19 digits card number. *AMEX payment option takes 15 digits card number. *Otherwise, they take 16 digits card number. Example: 400555*****0001 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
phone_number Alphanumeric max: 19 |
The customer’s phone number. Example: 00962797219966 |
settlement_reference Alphanumeric max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 |
merchant_extra Alphanumeric Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra1 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra2 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra3 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra4 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra5 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
billing_stateProvince Alphanumeric max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric max: 100 |
The city portion of the address. |
agreement_id Alphanumeric max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
[NOTE:] Every parameter the Merchant sends in the Request should be received by the Merchant in the Response - even the optional ones.
Complete sample code for standard UI checkout:
The following sample code shows you how to process a payment using the standard view. The code sample illustrates how you send a request operation in the mobile SDK.
Objective-C
- (void)viewDidLoad { [super viewDidLoad]; payfort = [[PayFortController alloc] initWithEnviroment:PayFortEnviromentSandBox]; } NSMutableDictionary *requestDictionary = [[NSMutableDictionary alloc]init]; [requestDictionary setValue:@"10000" forKey:@"amount"]; [requestDictionary setValue:@"AUTHORIZATION" forKey:@"command"]; [requestDictionary setValue:@"USD" forKey:@"currency"]; [requestDictionary setValue:@"email@domain.com" forKey:@"customer_email"]; [requestDictionary setValue:@"en" forKey:@"language"]; [requestDictionary setValue:@"112233682686" forKey:@"merchant_reference"]; [requestDictionary setValue:@"" forKey:@"payment_option"]; [requestDictionary setValue:@"gr66zzwW9" forKey:@"token_name"]; [payFort callPayFortWithRequest:requestDictionary currentViewController:self success:^(NSDictionary *requestDic, NSDictionary *responeDic) { } canceled:^(NSDictionary *requestDic, NSDictionary *responeDic) { } faild:^(NSDictionary *requestDic, NSDictionary *responeDic, NSString *message) { }];
Swift
let request = ["amount" : "1000", "command" : "AUTHORIZATION", "currency" : "AED", "customer_email" : "rzghebrah@payfort.com", "installments" : "", "language" : "en", "sdk_token" : "token"] payFort.callPayFort(withRequest: request, currentViewController: self, success: { (requestDic, responeDic) in print("success") print("responeDic=\(responeDic)") print("responeDic=\(responeDic)") }, canceled: { (requestDic, responeDic) in print("canceled") print("responeDic=\(responeDic)") print("responeDic=\(responeDic)") }, faild: { (requestDic, responeDic, message) in print("faild") print("responeDic=\(responeDic)") print("responeDic=\(responeDic)") })
Customizing the standard payment UI
When you use the standard payment UI you can customize the payment UI presented by our iOS SDK in a number of ways to better reflect your business. We outline your options below.
Customizing the standard payment UI
You can customize the standard payment user interface in your iOS app. This is an example of a customized payment UI:
Standard vs. Customized Mobile SDK Payment Page
Follow these steps to configure a customized payment UI:
Create your nibFile .xib and set the name of Arabic xib same name with English one with suffix -ar.
Link the xib with PayFortView and bind all the IBOutlets in interface section IBOutlet UILabel *titleLbl;
IBOutlet UIButton *BackBtn; IBOutlet UILabel *PriceLbl; IBOutlet JVFloatLabeledTextField *CardNameTxt; IBOutlet JVFloatLabeledTextField *CardNumberTxt; IBOutlet JVFloatLabeledTextField *CVCNumberTxt; IBOutlet JVFloatLabeledTextField *ExpDateTxt; IBOutlet UILabel *cardNumberErrorlbl; IBOutlet UILabel *cVCNumberErrorlbl; IBOutlet UILabel *expDateErrorlbl; IBOutlet UISwitch *savedCardSwitch; IBOutlet UIButton *paymentBtn; IBOutlet UILabel *saveCardLbl; IBOutlet UIImageView *imageCard;
- Assign new created xib file to Amazon Payment Services controller.
[payFort setPayFortCustomViewNib:@\"PayFortView2\"\];
[NOTE]. If you call Arabic view and the Arabic view not existed the application will crash.\ Don’t forget to set the custom view field in the identity inspector
Hiding the Amazon Payment Service loading prompt
There is an option to hide the loading prompt when the iOS SDK initializes the connection request. You can disable the loading prompt by using following option:
Objective-C
payFort.hideLoading = YES;
Swift
payFort.hideLoading = true
Changing the presentation style
It’s easy to change the presentation style from full screen to default by using the following property:
Objective-C
payFort.presentAsDefault = YES;
Swift
payFort.presentAsDefault = true
[NOTE]: The default type is full screen when you set the value to false, when set to true it will appear according to the OS default.
iOS SDK response
There is an option to show the response view more directly in an elegant view that shows the response results either as success or failed. You do so by activating the following option:
Objective-C
payFort.isShowResponsePage = YES;
Swift
payFort.isShowResponsePage = true
Using a custom payment processing UI
In this section we outline the key information you need to create your own payment processing screen using the tools in the iOS SDK.
Stage 1: Generate an SDK token
You need to generate an SDK token before you can start processing payments using your custom payment processing UI. Refer to the SDK token section earlier in this document for instructions on creating an SDK token.
Stage 2: Create the card components
You create your custom payment screen by using the following five components included in the Amazon Payment Services iOS SDK:
CardNumberView
CVCNumberView
ExpiryDateView
CardHolderNameView
PayButton
Attributes |
Type |
Description |
---|---|---|
textColor | UIColor | The input text filed text color |
fontStyle | UIFont | The input text filed font style |
backgroundColor | UIColor |
The input text filed background color |
errorText | String |
The Error Label text |
errorFontStyle | UIFont |
The Error Label text Font Style |
errorTextColor | UIColor |
The Error Label text Text Color |
titleText | String |
The Title Label text |
titleTextColor | UIColor |
The Title Label text Color |
titleErrorTextColor | UIColor |
The Error Title Label text Color |
titleFontStyle | UIFont |
The Title Label Font style |
Components Views
Item property, all these properties are available for each component.
Swift
let property = Property() property.textColor property.fontStyle property.backgroundColor property.errorFontStyle property.errorTextColor property.titleTextColor property.titleErrorTextColor property.titleFontStyle
Objective-c
Property *property = [[Property alloc] init] property.textColor property.fontStyle property.backgroundColor property.errorFontStyle property.errorTextColor property.titleTextColor property.titleErrorTextColor property.titleFontStyle
- CardNumberView:
The CardNumberView inheritance from UIView, CardNumberView is used to validate the card number, card brand and card number length.
Swift
@IBOutlet private weak var cardNumberView: CardNumberView! cardNumberView.property = property
Objective-c
@property (nonatomic, weak) IBOutlet CardNumberView *cardNumberView; cardNumberView.property = property
- ExpiryDateView:
The ExpiryDateView inheritance from UIView, ExpiryDateView is used to check the expiry date for the credit card.
Swift
@IBOutlet private weak var expiryDateView: ExpiryDateView! expiryDateView.property = property
Objective-c
@property (nonatomic, weak) IBOutlet ExpiryDateView *expiryDateView; expiryDateView.property = property
- CVCNumberView
The CVCNumberView inheritance from UIView, CVCNumberView used to check if cvc matches cardBrad.
Swift
@IBOutlet private weak var cvcNumberView: CVCNumberView! cvcNumberView.property = property
Objective-c
@property (nonatomic, weak) IBOutlet CVCNumberView *cvcNumberView; cvcNumberView.property = property
- HolderNameView
The HolderNameView inheritance from UIView, HolderNameView is used to fill the card holder name.
Swift
@IBOutlet private weak var holderNameView: HolderNameView! holderNameView.property = property
Objective-c
@property (nonatomic, weak) IBOutlet holderNameView *holderNameView; holderNameView.property = property
- ErrorLabel
It will show any error message for owner card view, you can set your custom UILabel, Example:
Swift
@IBOutlet private weak var cardNumberErrorLabel: ErrorLabel! cardNumberView.errorLabel = cardNumberErrorLabel
Objective-c
@property (nonatomic, weak) IBOutlet ErrorLabel *cardNumberErrorLabel; cardNumberView.errorLabel = cardNumberErrorLabel
Example of components views in Objective-C and Swift
This is one example of how to customize the component:
Swift
let property = Property() property.textColor = .yellow property.backgroundColor = .green property.errorTextColor = .green property.titleTextColor = .red cardNumberView.property = property
Objective-c
Property * property = [[Property alloc] init]; property.textColor = UIColor.yellowColor; property.backgroundColor = UIColor.greenColor; property.errorTextColor = UIColor.greenColor; property.titleTextColor = UIColor.redColor; cardNumberView.property = property;
Stage 3: Initiate the payment
PayButton
Used to collect the card data from card components above and to submit successful payment. With a few simple steps it also has the capability to perform Direct Pay without the need for the card component, see the next section.
PayfortPayButton methods
/** Update Request After doing Setup - Parameter request: a new request dictionary */ public func updateRequest(request: [String: String]) /** Responsible for Save token or not - Parameter enabled: a new bool value */ public func isRememberEnabled(_ enabled: Bool)
Sample code
In this section we illustrate how you use the PayButton using sample code for Swift and Objective-C.
Swift
@IBOutlet weak var payButton: PayButton! let builder = PayComponents(cardNumberView: cardNumberView, expiryDateView: expiryDateView, cvcNumberView: cvcNumberView, holderNameView: holderNameView, rememberMe: saveCardSwitch.isOn) payButton.setup(with: request, enviroment: enviroment, payComponents: builder, viewController: self) { // Process started } success: { (requestDic, responeDic) in // Process success } faild: { (requestDic, responeDic, message) in // Process faild }
Objective-C
@property (nonatomic, weak) IBOutlet PayButton *payButton; PayComponents *builder = [[PayComponents alloc] initWithCardNumberView:cardNumberView expiryDateView: expiryDateView cvcNumberView: cvcNumberView, holderNameView: holderNameView rememberMe: saveCardSwitch.on]; [payButton setupWithRequest: request enviroment: enviroment payComponents: builder currentViewController: self Success:^(NSDictionary *requestDic, NSDictionary *responeDic) { } Canceled:^(NSDictionary *requestDic, NSDictionary *responeDic) { } Faild:^(NSDictionary *requestDic, NSDictionary *responeDic, NSString *message) { }];
Using Direct Pay
The Direct Pay feature enables Amazon Payment Services merchants to securely process e-commerce transactions using tokenized payment card details.
For customers that already supplied their payment card details in a previous transaction and where a card token was generated, customers need to just provide the card_security_code to complete their purchase.
The card token and provided card security code can be sent to the Amazon Payment Services iOS mobile SDK to complete the customer purchase through Direct Pay operation to complete the order placement using eCommerce channel.
Note you can use Direct Pay both with the standard payment UI or with a customized payment UI.
Direct Pay sample code
\ Swift
@IBOutlet weak var directPayButton: PayButton! // request should has all mandatory params and also you need to send card_security_code, token_name let request = ["amount" : "1000", "command" : "AUTHORIZATION", "currency" : "AED", "customer_email" : "test@payfort.com", "language" : "en", "card_security_code" : "123", "token_name" : "payfort", "merchant_reference" : "merchant reference", "sdk_token" : "token"] directPayButton.setup(with: request, enviroment: enviroment, viewController: self) { // Process started } success: { (requestDic, responeDic) in // Process success } faild: { (requestDic, responeDic, message) in // Process faild }
Objective-c
@property (nonatomic, weak) IBOutlet PayButton *directPayButton; NSMutableDictionary *requestDictionary = [[NSMutableDictionary alloc]init]; [requestDictionary setValue:@"10000" forKey:@"amount"]; [requestDictionary setValue:@"AUTHORIZATION" forKey:@"command"]; [requestDictionary setValue:@"USD" forKey:@"currency"]; [requestDictionary setValue:@"email@domain.com" forKey:@"customer_email"]; [requestDictionary setValue:@"en" forKey:@"language"]; [requestDictionary setValue:@"112233682686" forKey:@"merchant_reference"]; [requestDictionary setValue:@"payfort" forKey:@"token_name"]; [requestDictionary setValue:@"123" forKey:@"card_security_code"]; [requestDictionary setValue:@"token" forKey:@"sdk_token"]; [directPayButton setupWithRequest: request enviroment: enviroment currentViewController: self Success:^(NSDictionary *requestDic, NSDictionary *responeDic) { } Canceled:^(NSDictionary *requestDic, NSDictionary *responeDic) { } Faild:^(NSDictionary *requestDic, NSDictionary *responeDic, NSString *message) { }];
Amazon Payment Services iOS SDK transaction feedback
While a transaction is processed, we will send a response directly to your direct transaction feedback URL. In theory, direct response feedback cannot be interrupted unless the URL you provided for responses is not functional at the time of the response.
We do this so that your server receives a response even if your customer does not successfully redirect to the return URL on your website, which may happen if your customer’s browser or connection fails during the transaction.
Receiving transaction feedback
There are two ways in which you receive transaction feedback:
Direct transaction feedback. Amazon Payment Services sends an immediate payment processing response whenever a transaction is completed.
You can rely on this response for transaction feedback even where your user closed the browser before getting redirected successfully to the redirection URL or where your user was not redirected due to a drop in the internet connection.
Notification feedback. Were we need to provide you with the status of a transaction once it is received. In other words, we send notification feedback to alert you to any changes in the status of a transaction.
For example, if the transaction was pending due to the unavailability of any party to the transaction, the final update will be pushed to your notification feedback endpoint.
Notification feedback deals with a wide range of scenarios and it is critical that your website is configured to receive notification feedback correctly. For example, transaction feedback can alert you to any transactions that were stuck in \“uncertain\” status, but which have recovered to final status.
Direct feedback allows you to subscribe to transaction updates for uncertain transactions whenever you process a payment. It is a method for receiving the transaction response automatically once the transaction had completed or if there was an update.
Registering Transaction Feedback URLs
To receive transaction feedback, you must register with Amazon Payment Services the transaction feedback URLs you set up on your server. Follow these steps:
Log in to your back-office account.
Select the active channel under Integration Settings > Technical Settings.
Enter your Direct Transaction Feedback URL and Notification Transaction Feedback URL.
Click the “Save Changes” button.
Transaction Feedback Implementation
We will send the response via HTTP POST request in POST form format to your webhook URL. The submission type can be changed from POST form to JSON or XML in your APS account settings. We only permit configuring URLs in HTTPS for direct feedback and for notification feedback.
To acknowledge receiving the direct feedback and notification successfully, the webhook URL must return a 2xx or 302 HTTP status. In case the URL returns different HTTP responses, our server will keep retrying up to 10 times until we receive a success response. We wait ten seconds between retries.
You can change and configure the retry mechanism attributes to increase or decrease the number of retries, time between retries and the grace period before we send the notifications.
You must create endpoints that accept direct transaction feedback and notification feedback from us via a webhook. You can customize how transaction feedback works – for example, by including the grace period before a direct feedback notification is sent, and the time elapsed between retrying feedback submission.
To customize transaction feedback, email integration-ps@amazon.com. You can request to change the submission type to JSON or XML. You can also change the grace period or the time interval between the retries – please contact us.
[NOTE]: You can check the direct and notification feedback logs in your back office account to check the details related to the submission like the Transaction Feedback URL which was triggered, The response which our system pushed, the response Code and Status retuned from your Transaction Feedback URL.
[NOTE]: The specifics of the data will differ based upon the financial operation that has been processed. Your code must be able to accommodate different data.
Validate API
Amazon Payment Services offers an API to request validation of the payment card details without performing an actual transaction.
ValidateAPI can help you to initiate an API request in order to validate the input parameters values, this will reduce the possibility of encountered API errors due to wrong user inputs before processing the actual payment card transaction.
Swift
let request = ["amount" : "1000", "command" : "AUTHORIZATION", "currency" : "AED", "customer_email" : "test@payfort.com", "language" : "en", "sdk_token" : "token"] payFortController.callValidateAPI(with: request) { // Process started } success: { // Process success } faild: { (requestDic, responeDic, message) in // Process faild })
Objective-c
NSMutableDictionary *request = [[NSMutableDictionary alloc]init]; [requestDictionary setValue:@"10000" forKey:@"amount"]; [requestDictionary setValue:@"AUTHORIZATION" forKey:@"command"]; [requestDictionary setValue:@"USD" forKey:@"currency"]; [requestDictionary setValue:@"email@domain.com" forKey:@"customer_email"]; [requestDictionary setValue:@"en" forKey:@"language"]; [requestDictionary setValue:@"112233682686" forKey:@"merchant_reference"]; [requestDictionary setValue:@"token" forKey:@"sdk_token"]; [payFortController callValidateAPIWithRequest: request ShowLoader:^() { } Success:^(NSDictionary *requestDic, NSDictionary *responeDic) { } Faild:^(NSDictionary *requestDic, NSDictionary *responeDic, NSString *message) { }];
[NOTE]: When you make use of the Validate API call you still need to generate a mobile SDK token even though you are not processing a transaction.
Migrating from version 2.3 of the SDK
In this section we outline the steps you need to take to migrate from version 2.3 of the Amazon Payment Services iOS SDK to the latest release. To complete the migration follow these steps:
Remove PayFortSDK.framework and PayFortSDK.bundle
Use CocoaPods or manual integration – by dragging the PayFortSDK.xcframework into your project
Import PayFortSDK.xcframework:
Objective-C
The replace import is shown below
//From #import//To #import
Swift import
If you’re using Swift you can import PayFortSDK directly on your controller, there is no need to use Bridging-Header any more
import PayFortSDK
Change callPayFortWithRequest method as below:
Objective-C
//From [payFort callPayFortWithRequest:myRequest currentViewController:self Success:^(NSDictionary *requestDic, NSDictionary *responeDic) { } Canceled:^(NSDictionary *requestDic, NSDictionary *responeDic) { } Faild:^(NSDictionary *requestDic, NSDictionary *responeDic, }]; //TO [payFort callPayFortWithRequest:myRequest currentViewController:self success:^(NSDictionary *requestDic, NSDictionary *responeDic) { } canceled:^(NSDictionary *requestDic, NSDictionary *responeDic) { } faild:^(NSDictionary *requestDic, NSDictionary *responeDic, }];
Swift
Chane the callPayFortWithRequest request param from NSMutableDictionary to Dictionary
- Change callPayFortForApplePayWithRequest method as below:
Objective-C
//From [payFort callPayFortForApplePayWithRequest:myRequest applePayPayment:payment currentViewController:self Success:^(NSDictionary *requestDic, NSDictionary *responeDic) { } Faild:^(NSDictionary *requestDic, NSDictionary *responeDic, NSString *message) { completion(PKPaymentAuthorizationStatusFailure); }]; //To [payFort callPayFortForApplePayWithRequest:myRequest applePayPayment:payment currentViewController:self success:^(NSDictionary *requestDic, NSDictionary *responeDic) { } faild:^(NSDictionary *requestDic, NSDictionary *responeDic, NSString *message) { completion(PKPaymentAuthorizationStatusFailure); }];
Swift
Change callPayFortForApplePay request param from NSMutableDictionary to Dictionary
- Change callPayFortForApplePay method as below
Objective-C
//From paycontroller.callPayFortForApplePay(withRequest: ["":""], applePay: payment, currentViewController: self) { (requestDic, responeDic) in } faild: { (requestDic, responeDic, message) in } //To paycontroller.callPayFortForApplePay(withRequest: ["":""], applePayPayment: payment, currentViewController: self) { (requestDic, responeDic) in } faild: { (requestDic, responeDic, message) in }
Swift
No changes necessary
- Change environment as follows:
Objective-C
From KPayFortEnviromentSandBox to PayFortEnviromentSandBox
From KPayFortEnviromentProduction to PayFortEnviromentProduction
Swift
From KPayFortEnviromentSandBox to .sandbox
From KPayFortEnviromentProduction to *.production\ *
- Modify the IsShowResponsePage property:
Objective-C:
From IsShowResponsePage to isShowResponsePage
Swift
No changes needed
- HideLoading property:
Objective-C:
From HideLoading to hideLoading
Swift
No changes needed.
Appendix: About the Software
About this software
The Amazon Payment Services iOS mobile SDK allows merchants to securely integrate payment functionality into a native iOS app. It allows merchants to easily accept in-app payments.
Instead of the traditional, time-consuming, and complex way of being redirected to the mobile browser to complete the payment, in-app payments can easily be offered thanks to the iOS Mobile SDK.
In turn, this gives the merchants’ customers a smooth, pleasing user experience thanks to in-app payment functions through the native applications.
Supported Platforms
The Amazon Payment Services iOS SDK supports IOS 12.2+ and Xcode 11.0 and above.
Localization
You can use both English and Arabic when you implement the iOS SDK.
Screen Orientation
Currently, portrait is the only orientation supported within the Amazon Payment Services mobile SDK – unless you build a customized payment integration.
Supported Payment Methods
Using the iOS SDK the merchant can process debit or credit card transactions only.
Supported Payment Options
The supported credit card payment options are VISA, MASTERCARD, American Express (AMEX), MADA and MEEZA.
React Native Mobile SDK
Before you start the integration
Read through the following steps first to understand how the integration process works. This will help you to understand why these steps are required and why you need to follow a specific sequence.
Step 1: Access your test account
You need to make sure that you have access to a test account with Amazon Payment Services. It is a full test environment that allows you to fully simulate transactions.
Step 2: Choose between a standardized or custom payment UI
The Amazon Payment Services React Native SDK provides you with a standard payment UI that you can use to quickly integrate in-app payments. The standard UI offers limited customizability.
Alternatively, you can choose to build your own payment UI using Amazon Payment Services React Native SDK building blocks, we describe this in the section on custom-coding a payment processing UI.
Step 3: Make sure that you are using the correct integration type
Prior to building the integration, you need to make sure that you are selecting and using the proper parameters in the API calls as per the required integration type. All the mandatory parameters are mentioned under every section in the API document
Step 4: Install the Amazon Payment Services React Native SDK in your development environment
You need to add the repositories to your build file and add the SDK to your build.gradle.
Step 5: Create a test transaction request
You need to create a test transaction request. Processing a valid API request depends on transaction parameters included, you need to check the documentation and read every parameter possible to reduce the errors in processing the transaction.
Step 6: Process a transaction response
After every payment, Amazon Payment Services returns the transaction response on the URL configured in your account under Technical Settings, Channel Configuration.
For more details check the transaction feedback instructions. You need to validate the response parameters returned on this URL by calculating the signature for the response parameters using the SHA response phrase configured in your account under security settings.
Step 7: Test and Go Live
You can use our test card numbers to test your integration and simulate your test cases. The Amazon Payment Services team may need to test your integration before going live to assure your application integration.
Mobile SDK transaction workflow
Below, we describe the transaction workflow when you process a payment using the Amazon Payment Service React Native Mobile SDK.
Your customer clicks on the Pay button in your app.
Your merchant system (back-end) generates a mobile SDK token using the Amazon Payment Services API
Your app passes the parameters, including the SDK token, to the React Native mobile SDK
The React Native mobile SDK starts a secure connection and sends the transaction request to the Amazon Payment Services server to be validated.
The Amazon Payment Services API validates the SDK token, device_ID and other request parameters and returns the validation response to the React Native SDK.
Assuming validation is passed your merchant app displays a payment page to the customer.
Your customer enters their payment details on the payment page in the React Native SDK prompt on their device.
The Amazon Payment Services React Native SDK validates your customer’s details and sends a transaction (Authorization or Purchase) request to the relevant payment processor and issuing bank.
The payment processor processes the transaction request and returns a transaction response to the React Native SDK
The Amazon Payment Services React Native SDK returns the transaction response to your merchant app
Your merchant app displays the response to your customer
Installing the Mobile SDK
These are the first steps you need to follow to integrate the Amazon Payment Services React Native SDK into your React Native application.
Installing the React Native Mobile SDK
You need to complete below steps to install the Amazon Payment Services React Native SDK.
Step 1
Install the React Native Package.
npm install rn-amazon-payment-services
Android Specific Installations
a. You need to add the repository to your build file. Add it in your root build.gradle at the end of repositories:
allprojects { repositories { ... maven { url https://android-sdk.payfort.com } } }
b. You need to set the following two permission so that the React Native mobile SDK works properly:
< uses-permission android:name="android.permission.INTERNET" /> < uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
iOS Specific Installations
a. Add the following code to your Podfile (inside the target section):
pod 'PayFortSDK'
b. Add the following to the bottom of your Podfile:
post_install do |installer| installer.pods_project.targets.each do |target| if ['PayFortSDK'].include? target.name target.build_configurations.each do |config| config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES' end end end end
c. Run the following command inside /iOS folder:
pod install
Creating a mobile SDK token
A mobile SDK authentication token is required to authenticate every request sent to the SDK. The token is also significant to process payment operations with Amazon Payment Services through our React Native mobile SDK.
To get started with our React Native mobile SDK you must first establish the ability to generate a mobile SDK token.
NOTE: The creation and initiation of a mobile SDK token happens on your server – your server must generate the token by sending a request to the Amazon Payment Services API.
A unique authentication token must be created for each transaction. Each authentication token has a life-time of only one hour if no new request from the same device is sent.
Mobile SDK token URLs
These are the URLs you need to use when you request a mobile SDK token for your React Native app:
Test Environment URL
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production Environment URL
https://paymentservices.payfort.com/FortAPI/paymentApi
Submitting token request parameters
You need to submit parameters as a REST POST request using JSON. Below we list the range of parameters for the React Native mobile SDK token request.
React Native Mobile SDK Token Request Parameters
(Please take a look at the React Native Mobile SDK Token Request Example on the right side of the page.)
React Native Mobile SDK Token Request Example
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'service_command' => 'SDK_TOKEN',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'language' => 'en',
'device_id'=> 'ffffffff-a9fa-0b44-7b27-29e70033c587',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
);
$ch = curl_init( $url );
# Setup request to send json via POST.
$data = json_encode($arrData);
curl_setopt( $ch, CURLOPT_POSTFIELDS, $data );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
# Return response instead of printing.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
# Send request.
$result = curl_exec($ch);
curl_close($ch);
# Print response.
echo "<pre>$result</pre>";
curl -H "Content-Type: application/json" -d
'{"service_command":"SDK_TOKEN","language":"en","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj",,"language":"en","device_id":"ffffffff-a9fa-0b44-7b27-29e70033c587",
"signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a"}'
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'service_command' : 'SDK_TOKEN',
'access_code' : 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' : 'CycHZxVj',
'language' : 'en',
'device_id': 'ffffffff-a9fa-0b44-7b27-29e70033c587',
'signature' : '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
};
values = json.dumps(arrData)
data = urllib.urlencode(values)
req = urllib2.Request(url, data)
response = urllib2.urlopen(req)
page = response.read()
print page + '\n\n'
String jsonRequestString = "{\"service_command\" : \"SDK_TOKEN\" , "
+"\"access_code\" : \"zx0IPmPy5jp1vAz8Kpg7\", "
+"\"merchant_identifier\" : \"CycHZxVj\", "
+ "\"language\" : \"en\","
+ "\"device_id\"\"ffffffff-a9fa-0b44-7b27-29e70033c587\", "
+ "\"signature\" : \"7cad05f0212ed933c9a5d5dffa31661acf2c827a\"}";
// Define and Initialize HttpClient
HttpClient httpClient = HttpClientBuilder.create().build();
// Intialize HttpPOST with FORT Payment services URL
HttpPost request = new HttpPost("https://sbpaymentservices.payfort.com/FortAPI/paymentApi");
// Setup Http POST entity with JSON String
StringEntity params = new StringEntity(jsonRequestString);
// Setup request type as JSON
request.addHeader("content-type", "application/json");
request.setEntity(params);
// Post request to FORT
HttpResponse response = httpClient.execute(request);
// Read response using StringBuilder
StringBuilder sb = new StringBuilder();
BufferedReader reader = new BufferedReader(new InputStreamReader(
response.getEntity().getContent()), 65728);
String line = null;
while ((line = reader.readLine()) != null) {
sb.append(line);
}
// Print response
System.out.println(sb.toString());
require 'json'
require 'net/http'
require 'net/https'
require 'uri'
require 'openssl'
arrData = {
'service_command' => 'SDK_TOKEN',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'language' => 'en',
'device_id'=> 'ffffffff-a9fa-0b44-7b27-29e70033c587',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
};
arrData = arrData.to_json
uri = URI.parse("https://sbpaymentservices.payfort.com/FortAPI/paymentApi")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new("/v1.1/auth")
request.add_field('Content-Type', 'application/json')
request.body = arrData
response = http.request(request)
When you send your request for an React Native mobile SDK token you must send the following parameters to Amazon Payment Services:
ATTRIBUTES | Description |
---|---|
service_command Alpha Mandatory max: 20 |
Command. Possible/ expected values: SDK_TOKEN Special characters: _ |
access_code Alphanumeric Mandatory Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
device_id Alphanumeric Mandatory Max: 100 |
A unique device identifier. Example: ffffffff-a9fa-0b44-7b27-29e70033c587 Special characters: - |
signature Alphanumeric Mandatory Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
NOTE: device_id can be generated using the following command: RnAmazonPaymentServiceSdk.getDeviceID();
React Native Mobile SDK Token Response Parameters
These parameters will be returned in the Amazon Payment Services response:
ATTRIBUTES | Description |
---|---|
service_command Alpha Max: 20 |
Command. Possible/ expected values: SDK_TOKEN |
access_code Alphanumeric Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
language Alpha Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
device_id Alphanumeric Max: 100 |
A unique device identifier. Example: ffffffff-a9fa-0b44-7b27-29e70033c587 |
signature Alphanumeric Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
sdk_token Alphanumeric Max: 100 |
An SDK Token to enable using the Amazon Payment Services Mobile SDK. Example: dwp78q3 |
response_message Alphanumeric Max: 150 |
Message description of the response code. It returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
Processing transactions with the React Native SDK
In this section we outline how you process a transaction using the React Native mobile SDK. Your first step is to create a mobile SDK token as described above.
Two routes for in-app payment processing
As a merchant you have two ways in which you can process payments using the Amazon Payment Services React Native mobile SDK.
Standard payment processing UI
You can use the standard Amazon Payment Services React Native SDK interface to display a standard payment UI screen. This option is customizable in two ways – you can hide the loading screen, and some of the UI elements can be customized.
Custom payment processing UI
Alternatively, you can choose to build your own payment processing UI by custom-coding an in-app payment processing feature. With this mobile SDK feature we allow Amazon Payment Services merchants to integrate and implement a native app checkout experience without displaying a default payment screen.
Using this integration method your customers can securely enter their payment card details on a fully customized merchant checkout landing page using the your customized payment UI.
The Amazon Payment Services React Native SDK provides key building blocks including payment card input fields and an action pay button that you can encapsulate inside the checkout landing page and to provide your own inline customer experience.
Amazon Payment Services’ SDK card input fields will securely transmit the completed payment card data to Amazon Payment Services APIs for processing and to complete the transaction placement.
React Native Mobile SDK Device ID Value
Please make sure to use the following React Native SDK function to generate the device_id parameter value that must be used for creating the sdk_token from your business security server:
const setupDeviceId = async () => { const id: string = await getDeviceId(); setDeviceId(id); };
React Native mobile SDK parameters
React Native Mobile SDK request and response parameters are listed below
Request parameters
This is a list of the parameters you need to send when you send a request to the React Native SDK.
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'command' => 'PURCHASE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
'customer_email' => 'test@payfort.com',
'token_name' => '7288fc8155014c57ad809d8e9574575e',
'sdk_token' => 'Dwp78q3'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command':'PURCHASE',
'access_code':'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier':'CycHZxVj',
'merchant_reference':'XYZ9239-yu898',
'language':'en',
'signature':'7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description':'iPhone 6-S',
'customer_email':'test@payfort.com',
'token_name' : '7288fc8155014c57ad809d8e9574575e',
'sdk_token' : 'Dwp78q3'
};
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' => 'PURCHASE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
'customer_email => 'test@payfort.com',
'token_name' => '7288fc8155014c57ad809d8e9574575e',
'sdk_token' => 'Dwp78q3'
};
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)
String jsonRequestString = "{\n \"command\": \"PURCHASE\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"test-10052\",\n \"amount\": \"20000\",\n \"currency\": \"AED\",\n \"language\": \"en\",\n \"customer_email\": \"test@payfort.com\",\n \"signature\": \"fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b\",\n \"token_name\": \"7288fc8155014c57ad809d8e9574575e\",\n“sdk_token” : “Dwp78q3”\n\n
}";
// 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());
{
"command": "PURCHASE",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "test-10052",
"amount": "20000",
"currency": "AED",
"language": "en",
"customer_email": "test@payfort.com",
"signature": "fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b",
"token_name": "7288fc8155014c57ad809d8e9574575e",
"sdk_token" : “Dwp78q3”
}
ATTRIBUTES | Description |
---|---|
command Alpha Mandatory max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Mandatory Max: 254 |
The customer’s email. Example: customer@domain.com Special characters: _ - . @ + |
sdk_token Alphanumeric Mandatory Max: 100 |
An SDK Token to enable using the Amazon Payment Services Mobile SDK. Example: Dwp78q3 |
token_name Alphanumeric Optional Max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp Special characters: . @ - _ |
payment_option Alpha Optional Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) |
eci Alpha Optional Max: 16 |
Ecommerce indicator. Possible/ expected values: ECOMMERCE |
order_description Alphanumeric Optional Max: 150 |
A description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
customer_ip Alphanumeric Optional max: 45 |
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf Special characters: . : |
customer_name Alpha Optional Max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' |
phone_number Alphanumeric Optional max: 19 |
The customer’s phone number. Example: 00962797219966 Special characters: + - ( ) Space |
settlement_reference Alphanumeric Optional max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 Special characters: - _ . |
merchant_extra Alphanumeric Optional Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra1 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra2 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra3 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra4 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra5 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
billing_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric Optional max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric Optional |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric Optional |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric Optional max: 100 |
The city portion of the address. |
agreement_id Alphanumeric Optional max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
recurring_mode Alphanumeric Optional max: 20 |
Indicates if the subsequent payments within the agreement has same/different amount or unscheduled (unknown interval/amount). Possible/ expected values: UNSCHEDULED, VARIABLE, FIXED |
recurring_transactions_count Alphanumeric Optional max: 100 |
The number of merchant-initiated payments within the recurring payment agreement. ( Required if recurring_mode = VARIABLE or FIXED ) |
recurring_expiry_date |
The date where the merchant needs to end the recurring. The format is YY-MM-DD [Numeric] with special character - |
recurring_days_between_payments |
The number of days between payments agreed with the payer under your agreement with them. The allowed data type is: Numeric only. |
Response parameters
ATTRIBUTES | Description |
---|---|
command Alpha Max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
amount Numeric Max: 10 |
The transaction’s amount.*Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
customer_email Alphanumeric Max: 254 |
The customer’s email. Example: customer1@domain.com |
fort_id Numeric Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
sdk_token Alphanumeric Max: 100 |
An SDK Token to enable using the Amazon Payment Services Mobile SDK. Example: Dwp78q3 |
token_name Alphanumeric max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp |
payment_option Alpha Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) |
eci Alpha Max: 16 |
The E-commerce indicator. Possible/ expected values: ECOMMERCE |
authorization_code Alphanumeric Max: 100 |
The authorization code returned from the 3rd party. Example: P1000000000000372136 |
order_description Alphanumeric Max: 150 |
It holds the description of the order. Example: iPhone 6-S |
response_message Alphanumeric Max: 150 |
The message description of the response code; it returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
customer_ip Alphanumeric max: 45 |
It holds the customer’s IP address. We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf |
customer_name Alpha Max: 40 |
The customer’s name. Example: John Smith |
expiry_date Numeric Max: 4 |
The card’s expiry date. Example: 2105 |
card_number Numeric Max: 16 |
The masked credit card’s number. Only the MEEZA payment option takes 19 digits card number. AMEX payment option takes 15 digits card number. Otherwise, they take 16 digits card number. Example: 400555*****0001 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
phone_number Alphanumeric max: 19 |
The customer’s phone number. Example: 00962797219966 |
settlement_reference Alphanumeric max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 |
merchant_extra Alphanumeric Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra1 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra2 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra3 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra4 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra5 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
billing_stateProvince Alphanumeric max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric max: 100 |
The city portion of the address. |
agreement_id Alphanumeric max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
Standard checkout implementation
Follow below steps to implement standard checkout
1: Import from SDK
import { getDeviceId, FortRequestObject, StandardCheckout, } from 'rn-amazon-payment-services';
2: Implement On Activity result function
export default function App() { const [deviceId, setDeviceId] = useState(''); const [showStandardCheckout, setShowStandardCheckout] = useState (false); const setupDeviceId = async () => { const id: string = await getDeviceId(); setDeviceId(id); }; const onSuccess = (response: any) => { console.log('success', response); }; const onFailure = (response: any) => { console.log('failure', response); }; const onCancel = (response: any) => { console.log('cancel', response); };
3: Create Request Object Map
const requestObject: FortRequestObject = { command: 'PURCHASE', merchant_reference: 'ORD-0000007682', amount: '100', currency: 'AED', language: 'en', customer_email: 'sam@gmail.com', sdk_token: sdkToken, payment_option: 'VISA', };
4: Implement Standard Checkout
return( < StandardCheckout showStandardCheckoutPage={showStandardCheckout} environment={'TEST'} requestCode={123455} showLoading={true} showResponsePage={true} requestObject={requestObject} onSuccess={onSuccess} onFailure={onFailure} onCancel={onCancel} /> )
Standard Checkout Props
Below is a description for each parameter:
Parameter | Description |
---|---|
showStandardCheckoutPage Boolean Mandatory |
Navigates to Amazon Payment Service Standard Checkout screen. |
environment Alpha Mandatory |
This parameter used to determine whether the request is going to be submitted to the test or production environment. It has two possible values: - TEST - PRODUCTION |
requestCode Numeric Mandatory |
A unique ID for this request. |
showLoading Boolean Mandatory |
Flag to show or hide the loading dialog. |
showResponsePage Boolean Mandatory |
Flag to show or hide the response page. |
requestObject Object Mandatory |
Parameters you need to send when you send a request (the full list of parameters is in the last section of the document) |
onSuccess Boolean Mandatory |
Callback to handle when the transaction is processed successfully. |
onFailure Boolean Mandatory |
Callback to handle when the transaction is failed. |
onCancel Boolean Optional |
Callback to handle when the user cancels the payment by clicking the back button. |
Customized Payment Processing
You can customize the payment UI presented by our React Native SDK in a number of ways to better reflect your business.
1: Import custom checkout view
Define and initialize an instance of the FortCallBackManager in your activity as follows:
import { CustomCheckoutView, }
2: Create Call back function
You need to add the following statement to the onActivityResult function as follows:
export default function App() { const onSuccess = (response: any) => { console.log('success', response); }; const onFailure = (response: any) => { console.log('failure', response); };
3: Create Request Object Map
const requestObject: FortRequestObject = { command: 'PURCHASE', merchant_reference: 'ORD-0000007682', amount: '100', currency: 'AED', language: 'en', customer_email: 'sam@gmail.com', sdk_token: sdkToken, payment_option: 'VISA', };
4: Custom Checkout UI Component
return( < CustomCheckoutView requestObject={requestObject} environment={'TEST'} style={{ width: 300, height: 400 }} payButtonProps={{ marginLeft: 20, marginTop: 20, backgroundColor: '#026cff', text: 'Pay', textSize: 20, textColor: '#ffffff', buttonWidth: 40, buttonHeight: 40, borderRadius: 20, borderWidth: 1, borderColor: '#383333', }} onFailure={onFailure} onSuccess={onSuccess} /> )
Custom Checkout Props
Below is a description for each parameter:
Parameter | Description |
---|---|
environment Alpha Mandatory |
This parameter used to determine whether the request is going to be submitted to the test or production environment. It has two possible values: - TEST - PRODUCTION |
style Object Mandatory |
Set the height and width of the view. |
payButtonProps Numeric Mandatory |
Customization of the pay button |
requestObject Object Mandatory |
Parameters you need to send when you send a request |
onSuccess Boolean Mandatory |
Callback to handle when the transaction is processed successfully. |
onFailure Boolean Mandatory |
Callback to handle when the transaction is failed. |
Using Direct Pay
The Direct Pay feature enables Amazon Payment Services merchants to securely process e-commerce transactions using tokenized payment card details.
For customers that already supplied their payment card details in a previous transaction and where a card token was generated, customers need to just provide the card security code to complete their purchase.
The card token and provided card security code can be sent to the Amazon Payment Services React Native mobile SDK to complete the customer purchase through Direct Pay operation to complete the order placement using eCommerce channel.
1: Import Direct Pay button and FortRequest Objects
import { DirectPayButton, FortRequestObjectDirectPay, } from 'rn-amazon-payment-services';
2: Create Call back function
You need to add the following statement to the onActivityResult function as follows:
export default function App() { const onSuccess = (response: any) => { console.log('success', response); }; const onFailure = (response: any) => { console.log('failure', response); };
3: Create Request Object Map
const requestObjectDirectPay: FortRequestObjectDirectPay = { command: 'AUTHORIZATION', merchant_reference: 'ORD-0000007682', amount: '100', currency: 'AED', language: 'en', customer_email: 'sam@gmail.com', sdk_token: sdkToken, payment_option: 'VISA', token_name: tokenName, card_security_code: '123', };
4: Direct Pay Checkout UI Component
return( < DirectPayButton requestObject={requestObjectDirectPay} environment={'TEST'} style={{ width: 200, height: 100 }} payButtonProps={{ marginLeft: 20, marginTop: 20, backgroundColor: '#026cff', text: 'Pay', textSize: 20, textColor: '#ffffff', buttonWidth: 40, buttonHeight: 40, borderRadius: 20, borderWidth: 1, borderColor: '#383333', }} onFailure={onFailure} onSuccess={onSuccess} /> )
Direct Pay Checkout Props
Below is a description for each parameter:
Parameter | Description |
---|---|
environment Alpha Mandatory |
This parameter used to determine whether the request is going to be submitted to the test or production environment. It has two possible values: - TEST - PRODUCTION |
style Object Mandatory |
Set the height and width of the view. |
payButtonProps Numeric Mandatory |
Customization of the pay button |
requestObject Object Mandatory |
Parameters you need to send when you send a request |
onSuccess Boolean Mandatory |
Callback to handle when the transaction is processed successfully. |
onFailure Boolean Mandatory |
Callback to handle when the transaction is failed. |
Amazon Payment Services React Native SDK transaction feedback
While a transaction is completed, we will send a response directly to your direct transaction feedback URL. In theory, direct response feedback cannot be interrupted unless the URL you provided for responses is not functional at the time of the response.
We do this so that your server receives a response even if your customer does not successfully redirect to the return URL on your website, which may happen if your customer’s browser or connection fails during the transaction.
Receiving transaction feedback
There are two ways in which you receive transaction feedback:
Direct transaction feedback. Amazon Payment Services sends an immediate payment processing response whenever a transaction is completed.
You can rely on this response for transaction feedback even where your user closed the browser before getting redirected successfully to the redirection URL or where your user was not redirected due to a drop in the internet connection.
Notification feedback. Were we need to provide you with the status of a transaction once it is received. In other words, we send notification feedback to alert you to any changes in the status of a transaction.
For example, if the transaction was pending due to the unavailability of any party to the transaction, the final update will be pushed to your notification feedback endpoint.
Notification feedback deals with a wide range of scenarios and it is critical that your website is configured to receive notification feedback correctly. For example, transaction feedback can alert you to any transactions that were stuck in “uncertain” status, but which have recovered to final status.
Direct feedback allows you to subscribe to transaction updates for uncertain transactions whenever you process a payment. It is a method for receiving the transaction response automatically once the transaction had completed or if there was an update.
Registering Transaction Feedback URLs
To receive transaction feedback, you must register with Amazon Payment Services the transaction feedback URLs you set up on your server. Follow these steps:
Log in to your back-office account.
Select the active channel under Integration Settings > Technical Settings.
Enter your Direct Transaction Feedback URL and Notification Transaction Feedback URL.
Click “Save Changes” button.
Transaction Feedback Implementation
We will send the response via HTTP POST request in POST form format to your webhook URL. The submission type can be changed from POST form to JSON or XML in your APS account settings. We only permit configuring URLs in HTTPS for direct feedback and for notification feedback.
To acknowledge receiving the direct feedback and notification successfully, the webhook URL must return a 2xx or 302 HTTP status. In case the URL returns different HTTP responses, our server will keep retrying up to 10 times until we receive a success response. We wait ten seconds between retries.
You can change and configure the retry mechanism attributes to increase or decrease the number of retries, time between retries and the grace period before we send the notifications.
You must create endpoints that accept direct transaction feedback and notification feedback from us via a webhook. You can customize how transaction feedback works – for example, by including the grace period before a direct feedback notification is sent, and the time elapsed between retrying feedback submission.
To customize transaction feedback, email integration-ps@amazon.com. You can request to change the submission type to JSON or XML. You can also change the grace period or the time interval between the retries please contact us on integration@payfort.com
[NOTE] You can check the direct and notification feedback logs in your back office account to check the details related to the submission like the Transaction Feedback URL which was triggered, The response which our system pushed, the response Code and Status retuned from your Transaction Feedback URL.
[NOTE] The specifics of the data will differ based upon the financial operation that has been processed. Your code must be able to accommodate different data.
Appendix
Supported Platforms
The Amazon Payment Services React Native SDK supports devices running Android 4.1.x and later (API level 16). In other words, Android Ice Cream Sandwich or higher is supported. This release supports Android Pie API 28.
The Amazon Payment Services React Native SDK supports iOS 12.2+ and Xcode 11.0 and above.
Localization
You can use both English and Arabic when you implement the React Native SDK.
Screen Orientation
Currently, portrait is the only orientation supported within the Amazon Payment Services mobile SDK – unless you build a customized payment integration.
Supported Payment Methods
Using the React Native SDK the merchant can process debit or credit card transactions only.
Supported Payment Options
The supported credit card payment options are VISA, MASTERCARD, American Express (AMEX), MADA and MEEZA.
Flutter Mobile SDK
Before you start the integration
Read through the following steps first to understand how the integration process works. This will help you to understand why these steps are required and why you need to follow a specific sequence.
Step 1: Access your test account
You need to make sure that you have access to a test account with Amazon Payment Services. It is a full test environment that allows you to fully simulate transactions.
Step 2: Make sure that you are using the correct integration type
Prior to building the integration, you need to make sure that you are selecting and using the proper parameters in the API calls as per the required integration type. All the mandatory parameters are mentioned under every section in the API document
Step 3: Install the Amazon Payment Services Flutter SDK in your development environment
You need to add the proper dependencies and have to set the PodFile version
Step 4: Create a test transaction request
You need to create a test transaction request. Processing a valid API request depends on transaction parameters included, you need to check the documentation and read every parameter possible to reduce the errors in processing the transaction.
Step 5: Process a transaction response
After every payment, Amazon Payment Services returns the transaction response on the URL configured in your account under Technical Settings, Channel Configuration.
For more details check the transaction feedback instructions. You need to validate the response parameters returned on this URL by calculating the signature for the response parameters using the SHA response phrase configured in your account under security settings.
Step 6: Test and Go Live
You can use our test card numbers to test your integration and simulate your test cases. The Amazon Payment Services team may need to test your integration before going live to assure your application integration.
Mobile SDK transaction workflow
Below, we describe the transaction workflow when you process a payment using the Amazon Payment Service Flutter Mobile SDK.
Your customer clicks on the Pay button in your app.
Your merchant system (back-end) generates a mobile SDK token using the Amazon Payment Services API
Your app passes the parameters, including the SDK token, to the Flutter mobile SDK
The Flutter mobile SDK starts a secure connection and sends the transaction request to the Amazon Payment Services server to be validated.
The Amazon Payment Services API validates the SDK token, device_ID and other request parameters and returns the validation response to the Flutter SDK.
Assuming validation is passed your merchant app displays a payment page to the customer.
Your customer enters their payment details on the payment page in the Flutter SDK prompt on their device.
The Amazon Payment Services Flutter SDK validates your customer’s details and sends a transaction (Authorization or Purchase) request to the relevant payment processor and issuing bank.
The payment processor processes the transaction request and returns a transaction response to the Flutter SDK
The Amazon Payment Services Flutter SDK returns the transaction response to your merchant app
Your merchant app displays the response to your customer
Installing the Flutter Mobile SDK
You need to complete below steps to install the Amazon Payment Services Flutter SDK.
Step 1
You need to add the dependencies to your package’s pubspec.yaml file: flutter_amazonpaymentservices
Step 2
You need to import the plugin
import 'package:flutter_amazonpaymentservices/environment_type.dart'; import 'package:flutter_amazonpaymentservices/flutter_amazonpaymentservices.dart';
Android Specific Installations
No additional work required
iOS Specific Installations
The SDK build for >= iOS 10.0, so you need to set the platform version in the Podfile to iOS 10 or above.
Creating SDK token
SDK authentication token is required to authenticate every request sent to the SDK. The token is also significant to process payment operations with Amazon Payment Services through our Flutter SDK.
To get started with our Flutter SDK you must first establish the ability to generate a SDK token.
NOTE: The creation and initiation of a SDK token happens on your server – your server must generate the token by sending a request to the Amazon Payment Services API.
A unique authentication token must be created for each transaction. Each authentication token has a life-time of only one hour if no new request from the same device is sent.
SDK token URLs
These are the URLs you need to use when you request a SDK token for your Flutter app:
Test Environment URL
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production Environment URL
https://paymentservices.payfort.com/FortAPI/paymentApi
Submitting token request parameters
You need to submit parameters as a REST POST request using JSON. Below we list the range of parameters for the Flutter SDK token request.
Flutter SDK Token Request Parameters
(Please take a look at the Flutter SDK Token Request Example on the right side of the page.)
Flutter SDK Token Request Example
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'service_command' => 'SDK_TOKEN',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'language' => 'en',
'device_id'=> 'ffffffff-a9fa-0b44-7b27-29e70033c587',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a'
);
$ch = curl_init( $url );
# Setup request to send json via POST.
$data = json_encode($arrData);
curl_setopt( $ch, CURLOPT_POSTFIELDS, $data );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
# Return response instead of printing.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
# Send request.
$result = curl_exec($ch);
curl_close($ch);
# Print response.
echo "<pre>$result</pre>";
curl -H "Content-Type: application/json" -d
'{"service_command":"SDK_TOKEN","language":"en","access_code":"zx0IPmPy5jp1vAz8Kpg7","merchant_identifier":"CycHZxVj",,"language":"en","device_id":"ffffffff-a9fa-0b44-7b27-29e70033c587",
"signature":"7cad05f0212ed933c9a5d5dffa31661acf2c827a"}'
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'service_command' : 'SDK_TOKEN',
'access_code' : 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' : 'CycHZxVj',
'language' : 'en',
'device_id': 'ffffffff-a9fa-0b44-7b27-29e70033c587',
'signature' : '7cad05f0212ed933c9a5d5dffa31661acf2c827a'
};
values = json.dumps(arrData)
data = urllib.urlencode(values)
req = urllib2.Request(url, data)
response = urllib2.urlopen(req)
page = response.read()
print page + '\n\n'
String jsonRequestString = "{\"service_command\" : \"SDK_TOKEN\" , "
+"\"access_code\" : \"zx0IPmPy5jp1vAz8Kpg7\", "
+"\"merchant_identifier\" : \"CycHZxVj\", "
+ "\"language\" : \"en\","
+ "\"device_id\"\"ffffffff-a9fa-0b44-7b27-29e70033c587\", "
+ "\"signature\" : \"7cad05f0212ed933c9a5d5dffa31661acf2c827a\"}";
// Define and Initialize HttpClient
HttpClient httpClient = HttpClientBuilder.create().build();
// Intialize HttpPOST with FORT Payment services URL
HttpPost request = new HttpPost("https://sbpaymentservices.payfort.com/FortAPI/paymentApi");
// Setup Http POST entity with JSON String
StringEntity params = new StringEntity(jsonRequestString);
// Setup request type as JSON
request.addHeader("content-type", "application/json");
request.setEntity(params);
// Post request to FORT
HttpResponse response = httpClient.execute(request);
// Read response using StringBuilder
StringBuilder sb = new StringBuilder();
BufferedReader reader = new BufferedReader(new InputStreamReader(
response.getEntity().getContent()), 65728);
String line = null;
while ((line = reader.readLine()) != null) {
sb.append(line);
}
// Print response
System.out.println(sb.toString());
require 'json'
require 'net/http'
require 'net/https'
require 'uri'
require 'openssl'
arrData = {
'service_command' => 'SDK_TOKEN',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'language' => 'en',
'device_id'=> 'ffffffff-a9fa-0b44-7b27-29e70033c587',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a'
};
arrData = arrData.to_json
uri = URI.parse("https://sbpaymentservices.payfort.com/FortAPI/paymentApi")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new("/v1.1/auth")
request.add_field('Content-Type', 'application/json')
request.body = arrData
response = http.request(request)
When you send your request for an Flutter SDK token you must send the following parameters to Amazon Payment Services:
ATTRIBUTES | Description |
---|---|
service_command Alpha Mandatory max: 20 |
Command. Possible/ expected values: SDK_TOKEN Special characters: _ |
access_code Alphanumeric Mandatory Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
device_id Alphanumeric Mandatory Max: 100 |
A unique device identifier. Example: ffffffff-a9fa-0b44-7b27-29e70033c587 Special characters: - |
signature Alphanumeric Mandatory Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
NOTE: device_id can be generated using the following command: await FlutterAmazonpaymentservices.getUDID;
Flutter Mobile SDK Token Response Parameters
These parameters will be returned in the Amazon Payment Services response:
ATTRIBUTES | Description |
---|---|
service_command Alpha Max: 20 |
Command. Possible/ expected values: SDK_TOKEN |
access_code Alphanumeric Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
language Alpha Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
device_id Alphanumeric Max: 100 |
A unique device identifier. Example: ffffffff-a9fa-0b44-7b27-29e70033c587 |
signature Alphanumeric Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
sdk_token Alphanumeric Max: 100 |
An SDK Token to enable using the Amazon Payment Services Mobile SDK. Example: dwp78q3 |
response_message Alphanumeric Max: 150 |
Message description of the response code. It returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
Processing transactions with the Flutter SDK
In this section we outline how you process a transaction using the Flutter SDK. Your first step is to create a SDK token as described above.
In-app payment processing
As a merchant you can process payments using the Amazon Payment Services Flutter SDK.
Standard payment processing UI
You can use the standard Amazon Payment Services Flutter SDK interface to display a standard payment UI screen. This option is customizable in two ways – you can hide the loading screen, and some of the UI elements can be customized.
Flutter SDK Device ID Value
Please make sure to use the following Flutter SDK function to generate the device_id parameter value that must be used for creating the sdk_token from your business security server:
var deviceId = await FlutterAmazonpaymentservices.getUDID ;
Flutter SDK parameters
Flutter SDK request and response parameters are listed below
Request parameters
This is a list of the parameters you need to send when you send a request to the Flutter SDK.
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'command' => 'PURCHASE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
'customer_email' => 'test@payfort.com',
'token_name' => '7288fc8155014c57ad809d8e9574575e',
'sdk_token' => 'Dwp78q3'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command':'PURCHASE',
'access_code':'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier':'CycHZxVj',
'merchant_reference':'XYZ9239-yu898',
'language':'en',
'signature':'7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description':'iPhone 6-S',
'customer_email':'test@payfort.com',
'token_name' : '7288fc8155014c57ad809d8e9574575e',
'sdk_token' : 'Dwp78q3'
};
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' => 'PURCHASE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
'customer_email => 'test@payfort.com',
'token_name' => '7288fc8155014c57ad809d8e9574575e',
'sdk_token' => 'Dwp78q3'
};
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)
String jsonRequestString = "{\n \"command\": \"PURCHASE\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"test-10052\",\n \"amount\": \"20000\",\n \"currency\": \"AED\",\n \"language\": \"en\",\n \"customer_email\": \"test@payfort.com\",\n \"signature\": \"fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b\",\n \"token_name\": \"7288fc8155014c57ad809d8e9574575e\",\n“sdk_token” : “Dwp78q3”\n\n
}";
// 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());
{
"command": "PURCHASE",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "test-10052",
"amount": "20000",
"currency": "AED",
"language": "en",
"customer_email": "test@payfort.com",
"signature": "fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b",
"token_name": "7288fc8155014c57ad809d8e9574575e",
"sdk_token" : “Dwp78q3”
}
ATTRIBUTES | Description |
---|---|
command Alpha Mandatory max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Mandatory Max: 254 |
The customer’s email. Example: customer@domain.com Special characters: _ - . @ + |
sdk_token Alphanumeric Mandatory Max: 100 |
An SDK Token to enable using the Amazon Payment Services Mobile SDK. Example: Dwp78q3 |
token_name Alphanumeric Optional Max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp Special characters: . @ - _ |
payment_option Alpha Optional Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) |
eci Alpha Optional Max: 16 |
Ecommerce indicator. Possible/ expected values: ECOMMERCE |
order_description Alphanumeric Optional Max: 150 |
A description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
customer_ip Alphanumeric Optional max: 45 |
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf Special characters: . : |
customer_name Alpha Optional Max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' |
phone_number Alphanumeric Optional max: 19 |
The customer’s phone number. Example: 00962797219966 Special characters: + - ( ) Space |
settlement_reference Alphanumeric Optional max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 Special characters: - _ . |
merchant_extra Alphanumeric Optional Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra1 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra2 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra3 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra4 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra5 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
billing_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric Optional max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric Optional |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric Optional |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric Optional max: 100 |
The city portion of the address. |
agreement_id Alphanumeric Optional max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
recurring_mode Alphanumeric Optional max: 20 |
Indicates if the subsequent payments within the agreement has same/different amount or unscheduled (unknown interval/amount). Possible/ expected values: UNSCHEDULED, VARIABLE, FIXED |
recurring_transactions_count Alphanumeric Optional max: 100 |
The number of merchant-initiated payments within the recurring payment agreement. ( Required if recurring_mode = VARIABLE or FIXED ) |
recurring_expiry_date |
The date where the merchant needs to end the recurring. The format is YY-MM-DD [Numeric] with special character - |
recurring_days_between_payments |
The number of days between payments agreed with the payer under your agreement with them. The allowed data type is: Numeric only. |
Response parameters
ATTRIBUTES | Description |
---|---|
command Alpha Max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
amount Numeric Max: 10 |
The transaction’s amount.*Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
customer_email Alphanumeric Max: 254 |
The customer’s email. Example: customer1@domain.com |
fort_id Numeric Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
sdk_token Alphanumeric Max: 100 |
An SDK Token to enable using the Amazon Payment Services Mobile SDK. Example: Dwp78q3 |
token_name Alphanumeric max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp |
payment_option Alpha Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) |
eci Alpha Max: 16 |
The E-commerce indicator. Possible/ expected values: ECOMMERCE |
authorization_code Alphanumeric Max: 100 |
The authorization code returned from the 3rd party. Example: P1000000000000372136 |
order_description Alphanumeric Max: 150 |
It holds the description of the order. Example: iPhone 6-S |
response_message Alphanumeric Max: 150 |
The message description of the response code; it returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
customer_ip Alphanumeric max: 45 |
It holds the customer’s IP address. We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf |
customer_name Alpha Max: 40 |
The customer’s name. Example: John Smith |
expiry_date Numeric Max: 4 |
The card’s expiry date. Example: 2105 |
card_number Numeric Max: 16 |
The masked credit card’s number. Only the MEEZA payment option takes 19 digits card number. AMEX payment option takes 15 digits card number. Otherwise, they take 16 digits card number. Example: 400555*****0001 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
phone_number Alphanumeric max: 19 |
The customer’s phone number. Example: 00962797219966 |
settlement_reference Alphanumeric max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 |
merchant_extra Alphanumeric Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra1 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra2 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra3 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra4 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra5 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
billing_stateProvince Alphanumeric max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric max: 100 |
The city portion of the address. |
agreement_id Alphanumeric max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
Standard checkout implementation
Follow below to implement standard checkout
var requestParam = { "amount": 100, "command": "AUTHORIZATION", "currency": "USD", "customer_email": "test@gmail.com", "language": "en", "merchant_reference": "f74689b50cb54fcab4664b4331163d5e", "sdk_token": "f74689b50cb54fcab4664b4331163d5e" }; try { result = await FlutterAmazonpaymentservices.normalPay( requestParam, EnvironmentType.production, isShowResponsePage: true); } on PlatformException catch (e) { print("Error ${e.message} details:${e.details}"); return; } print("Success ${ result}");
Standard Checkout Props
Below is a description for each parameter:
Parameter | Description |
---|---|
environment Alpha Mandatory |
This parameter used to determine whether the request is going to be submitted to the test or production environment. It has two possible values: - SANDBOX - PRODUCTION |
showResponsePage Boolean Mandatory |
Flag to show or hide the response page. |
Validate API
This is an API to check request validation is successfull or unsuccessful by passing the following params:
Future < void> validateApi() async { var result; var requestParam = { "amount": 100, "command": "AUTHORIZATION", "currency": "USD", "customer_email": "test@gmail.com", "language": "en", "merchant_reference": "f74689b50cb54fcab4664b4331163d5e", "sdk_token": "f74689b50cb54fcab4664b4331163d5e" }; try { result = await FlutterAmazonpaymentservices.validateApi( requestParam, EnvironmentType.production, ); } on PlatformException catch (e) { print("Error ${e.message} details:${e.details}"); return; } print("Success ${result}"); }
NOTE: There are two values for EnvironmentType Sandbox and Production
Amazon Payment Services Flutter SDK transaction feedback
While a transaction is completed, we will send a response directly to your direct transaction feedback URL. In theory, direct response feedback cannot be interrupted unless the URL you provided for responses is not functional at the time of the response.
We do this so that your server receives a response even if your customer does not successfully redirect to the return URL on your website, which may happen if your customer’s browser or connection fails during the transaction.
Receiving transaction feedback
There are two ways in which you receive transaction feedback:
Direct transaction feedback. Amazon Payment Services sends an immediate payment processing response whenever a transaction is completed.
You can rely on this response for transaction feedback even where your user closed the browser before getting redirected successfully to the redirection URL or where your user was not redirected due to a drop in the internet connection.
Notification feedback. Where we need to provide you with the status of a transaction once it is received. In other words, we send notification feedback to alert you to any changes in the status of a transaction.
For example, if the transaction was pending due to the unavailability of any party to the transaction, the final update will be pushed to your notification feedback endpoint.
Notification feedback deals with a wide range of scenarios and it is critical that your website is configured to receive notification feedback correctly. For example, transaction feedback can alert you to any transactions that were stuck in “uncertain” status, but which have recovered to final status.
Direct feedback allows you to subscribe to transaction updates for uncertain transactions whenever you process a payment. It is a method for receiving the transaction response automatically once the transaction had completed or if there was an update.
Registering Transaction Feedback URLs
To receive transaction feedback, you must register with Amazon Payment Services the transaction feedback URLs you set up on your server. Follow these steps:
Log in to your back-office account.
Select the active channel under Integration Settings > Technical Settings.
Enter your Direct Transaction Feedback URL and Notification Transaction Feedback URL.
Click “Save Changes” button.
Transaction Feedback Implementation
We will send the response via HTTP POST request in POST form format to your webhook URL. The submission type can be changed from POST form to JSON or XML in your APS account settings. We only permit configuring URLs in HTTPS for direct feedback and for notification feedback.
To acknowledge receiving the direct feedback and notification successfully, the webhook URL must return a 2xx or 302 HTTP status. In case the URL returns different HTTP responses, our server will keep retrying up to 10 times until we receive a success response. We wait ten seconds between retries.
You can change and configure the retry mechanism attributes to increase or decrease the number of retries, time between retries and the grace period before we send the notifications.
You must create endpoints that accept direct transaction feedback and notification feedback from us via a webhook. You can customize how transaction feedback works – for example, by including the grace period before a direct feedback notification is sent, and the time elapsed between retrying feedback submission.
To customize transaction feedback, email integration-ps@amazon.com. You can request to change the submission type to JSON or XML. You can also change the grace period or the time interval between the retries please contact us on integration@payfort.com
[NOTE] You can check the direct and notification feedback logs in your back office account to check the details related to the submission like the Transaction Feedback URL which was triggered, The response which our system pushed, the response Code and Status retuned from your Transaction Feedback URL.
[NOTE] The specifics of the data will differ based upon the financial operation that has been processed. Your code must be able to accommodate different data.
Appendix
Supported Platforms
The Amazon Payment Services Flutter SDK supports devices running Android 4.1.x and later (API level 16). In other words, Android Ice Cream Sandwich or higher is supported. This release supports Android Pie API 28.
The Amazon Payment Services Flutter SDK supports iOS 12.2+ and Xcode 11.0 and above.
Localization
You can use both English and Arabic when you implement the Flutter SDK.
Screen Orientation
Currently, portrait is the only orientation supported within the Amazon Payment Services mobile SDK – unless you build a customized payment integration.
Supported Payment Methods
Using the Flutter SDK the merchant can process debit or credit card transactions only.
Supported Payment Options
The supported credit card payment options are VISA, MASTERCARD, American Express (AMEX), MADA and MEEZA.
Install our pre-built web SDKs
Amazon Payment Services supports pre-built web SDKs. To minimize the developer efforts and enhance the user experience and the security standards to improve the quality of the integration.
<dependency> <groupId>com.payfort</groupId> <sartifactId>java-sdk</artifactId> <version>1.0</version> </dependency>
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 version 8.1 or 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:
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
{
'digital_wallet'=> 'APPLE_PAY',
'command'=> 'PURCHASE',
'access_code'=> '4yyoUrilpc0Hs7wolpcy',
'merchant_identifier'=> '0d60670d',
'merchant_reference'=> 'Test-100118',
'amount' => '100',
'currency' => 'SAR',
'language' => 'en',
'customer_email' => 'S00116-3@hef.org.sa',
'apple_data' => 'nIje+wQGTVVBgFqBxJoTk8Maig4D/KEuM/lC6IW7KGO7ydRs95KmLyQC58K4griC/mnAtAYXM/qMinDzpc6KxcFx0orSAaCYg0kGSbPDSsxnEVGMroqTQj/KSTYeooLPIWJudrWzTbNh6OZloI10fNN27AJur6nL5WFyxmUYMw7Ip+a8oWWNAjrfGISEFNJ3qs089zUNnRSQZSLwArwvXxoUwby+iCcUzNqcovn6auzKx8ajAth0LA8QWdfgGT45g5qu9YPos7BqfF70O+NgOLHKZ8Z3rtISpYvukz9ecUxBEA20uob8ZmQCCJAt6NHjv0gMqgEWbVtljE04c3RWULZJkB6htw3sgLvp2NjMjW2jmKVBb5Yv2lwrae0bM9ryJnpkMHgVw2gEyPuayGvk/rGFKyZGYT5WwIfVhIEodg==',
'apple_signature' => 'MIAGCSqGSIb3DQEHAqCAMIACAQExDTALBglghkgBZQMEAgEwgAYJKoZIhvcNAQcBAACggDCCA+MwggOIoAMCAQICCEwwQUlRnVQ2MAoGCCqGSM49BAMCMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xOTA1MTgwMTMyNTdaFw0yNDA1MTYwMTMyNTdaMF8xJTAjBgNVBAMMHGVjYy1zbXAtYnJva2VyLXNpZ25fVUM0LVBST0QxFDASBgNVBAsMC2lPUyBTeXN0ZW1zMRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABMIVd+3r1seyIY9o3XCQoSGNx7C9bywoPYRgldlK9KVBG4NCDtgR80B+gzMfHFTD9+syINa61dTv9JKJiT58DxOjggIRMIICDTAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFCPyScRPk+TvJ+bE9ihsP6K7/S5LMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDIwggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMB0GA1UdDgQWBBSUV9tv1XSBhomJdi9+V4UH55tYJDAOBgNVHQ8BAf8EBAMCB4AwDwYJKoZIhvdjZAYdBAIFADAKBggqhkjOPQQDAgNJADBGAiEAvglXH+ceHnNbVeWvrLTHL+tEXzAYUiLHJRACth69b1UCIQDRizUKXdbdbrF0YDWxHrLOh8+j5q9svYOAiQ3ILN2qYzCCAu4wggJ1oAMCAQICCEltL786mNqXMAoGCCqGSM49BAMCMGcxGzAZBgNVBAMMEkFwcGxlIFJvb3QgQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDUwNjIzNDYzMFoXDTI5MDUwNjIzNDYzMFowejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8BcRhBnXZIXVGl4lgQd26ICi7957rk3gjfxLk+EzVtVmWzWuItCXdg0iTnu6CP12F86Iy3a7ZnC+yOgphP9URaOB9zCB9DBGBggrBgEFBQcBAQQ6MDgwNgYIKwYBBQUHMAGGKmh0dHA6Ly9vY3NwLmFwcGxlLmNvbS9vY3NwMDQtYXBwbGVyb290Y2FnMzAdBgNVHQ4EFgQUI/JJxE+T5O8n5sT2KGw/orv9LkswDwYDVR0TAQH/BAUwAwEB/zAfBgNVHSMEGDAWgBS7sN6hWDOImqSKmd6+veuv2sskqzA3BgNVHR8EMDAuMCygKqAohiZodHRwOi8vY3JsLmFwcGxlLmNvbS9hcHBsZXJvb3RjYWczLmNybDAOBgNVHQ8BAf8EBAMCAQYwEAYKKoZIhvdjZAYCDgQCBQAwCgYIKoZIzj0EAwIDZwAwZAIwOs9yg1EWmbGG+zXDVspiv/QX7dkPdU2ijr7xnIFeQreJ+Jj3m1mfmNVBDY+d6cL+AjAyLdVEIbCjBXdsXfM4O5Bn/Rd8LCFtlk/GcmmCEm9U+Hp9G5nLmwmJIWEGmQ8Jkh0AADGCAYkwggGFAgEBMIGGMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUwIITDBBSVGdVDYwCwYJYIZIAWUDBAIBoIGTMBgGCSqGSIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTIyMDcyMjEyNTg0NVowKAYJKoZIhvcNAQk0MRswGTALBglghkgBZQMEAgGhCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEIKXwC6uKZzm2+EqzT6s5VPw0ebOu0HCJnNS+9tXlm5J7MAoGCCqGSM49BAMCBEgwRgIhAO8T9hfo/NooRtvK+KxFceuY1GfLf5Bz4/oxiVL/Sd48AiEAyAGWQH4jbioivj7Y/3NFIPe9pYLx0OBHJDKLxV4gAD8AAAAAAAA==',
'apple_header' => {
'apple_transactionId' => 'ee0c2dafa3a5a96f489226e2be7d7b4687e2c9cabaf3dfd13738bef7bb81cd62',
'apple_ephemeralPublicKey' => 'MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAETB1mCkKYTEcYDUMrEm04TVz4NWLX3qrYcoFbjQtn2Oji4t3guu+mX+7EReLtH1FzgX6U8PJzYwp/J4kDgFLnwQ==',
'apple_publicKeyHash' => 'YWEPi8j+nYJHD5C04PdGEFHam6mlIexZ8moIWNn6Pbo=='
},
'apple_paymentMethod' => {
'apple_displayName' => 'Visa 0253',
'apple_network' => 'Visa',
'apple_type' => 'debit'
},
'signature' => 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b'
}
};
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
{
'digital_wallet':'APPLE_PAY',
'command':'PURCHASE',
'access_code':'4yyoUrilpc0Hs7wolpcy',
'merchant_identifier':'0d60670d',
'merchant_reference':'Test-100118',
'amount':'100',
'currency':'SAR',
'language':'en',
'customer_email':'S00116-3@hef.org.sa',
'apple_data':'nIje+wQGTVVBgFqBxJoTk8Maig4D/KEuM/lC6IW7KGO7ydRs95KmLyQC58K4griC/mnAtAYXM/qMinDzpc6KxcFx0orSAaCYg0kGSbPDSsxnEVGMroqTQj/KSTYeooLPIWJudrWzTbNh6OZloI10fNN27AJur6nL5WFyxmUYMw7Ip+a8oWWNAjrfGISEFNJ3qs089zUNnRSQZSLwArwvXxoUwby+iCcUzNqcovn6auzKx8ajAth0LA8QWdfgGT45g5qu9YPos7BqfF70O+NgOLHKZ8Z3rtISpYvukz9ecUxBEA20uob8ZmQCCJAt6NHjv0gMqgEWbVtljE04c3RWULZJkB6htw3sgLvp2NjMjW2jmKVBb5Yv2lwrae0bM9ryJnpkMHgVw2gEyPuayGvk/rGFKyZGYT5WwIfVhIEodg==',
'apple_signature':'MIAGCSqGSIb3DQEHAqCAMIACAQExDTALBglghkgBZQMEAgEwgAYJKoZIhvcNAQcBAACggDCCA+MwggOIoAMCAQICCEwwQUlRnVQ2MAoGCCqGSM49BAMCMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xOTA1MTgwMTMyNTdaFw0yNDA1MTYwMTMyNTdaMF8xJTAjBgNVBAMMHGVjYy1zbXAtYnJva2VyLXNpZ25fVUM0LVBST0QxFDASBgNVBAsMC2lPUyBTeXN0ZW1zMRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABMIVd+3r1seyIY9o3XCQoSGNx7C9bywoPYRgldlK9KVBG4NCDtgR80B+gzMfHFTD9+syINa61dTv9JKJiT58DxOjggIRMIICDTAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFCPyScRPk+TvJ+bE9ihsP6K7/S5LMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDIwggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMB0GA1UdDgQWBBSUV9tv1XSBhomJdi9+V4UH55tYJDAOBgNVHQ8BAf8EBAMCB4AwDwYJKoZIhvdjZAYdBAIFADAKBggqhkjOPQQDAgNJADBGAiEAvglXH+ceHnNbVeWvrLTHL+tEXzAYUiLHJRACth69b1UCIQDRizUKXdbdbrF0YDWxHrLOh8+j5q9svYOAiQ3ILN2qYzCCAu4wggJ1oAMCAQICCEltL786mNqXMAoGCCqGSM49BAMCMGcxGzAZBgNVBAMMEkFwcGxlIFJvb3QgQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDUwNjIzNDYzMFoXDTI5MDUwNjIzNDYzMFowejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8BcRhBnXZIXVGl4lgQd26ICi7957rk3gjfxLk+EzVtVmWzWuItCXdg0iTnu6CP12F86Iy3a7ZnC+yOgphP9URaOB9zCB9DBGBggrBgEFBQcBAQQ6MDgwNgYIKwYBBQUHMAGGKmh0dHA6Ly9vY3NwLmFwcGxlLmNvbS9vY3NwMDQtYXBwbGVyb290Y2FnMzAdBgNVHQ4EFgQUI/JJxE+T5O8n5sT2KGw/orv9LkswDwYDVR0TAQH/BAUwAwEB/zAfBgNVHSMEGDAWgBS7sN6hWDOImqSKmd6+veuv2sskqzA3BgNVHR8EMDAuMCygKqAohiZodHRwOi8vY3JsLmFwcGxlLmNvbS9hcHBsZXJvb3RjYWczLmNybDAOBgNVHQ8BAf8EBAMCAQYwEAYKKoZIhvdjZAYCDgQCBQAwCgYIKoZIzj0EAwIDZwAwZAIwOs9yg1EWmbGG+zXDVspiv/QX7dkPdU2ijr7xnIFeQreJ+Jj3m1mfmNVBDY+d6cL+AjAyLdVEIbCjBXdsXfM4O5Bn/Rd8LCFtlk/GcmmCEm9U+Hp9G5nLmwmJIWEGmQ8Jkh0AADGCAYkwggGFAgEBMIGGMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUwIITDBBSVGdVDYwCwYJYIZIAWUDBAIBoIGTMBgGCSqGSIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTIyMDcyMjEyNTg0NVowKAYJKoZIhvcNAQk0MRswGTALBglghkgBZQMEAgGhCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEIKXwC6uKZzm2+EqzT6s5VPw0ebOu0HCJnNS+9tXlm5J7MAoGCCqGSM49BAMCBEgwRgIhAO8T9hfo/NooRtvK+KxFceuY1GfLf5Bz4/oxiVL/Sd48AiEAyAGWQH4jbioivj7Y/3NFIPe9pYLx0OBHJDKLxV4gAD8AAAAAAAA==',
'apple_header':{
'apple_transactionId':'ee0c2dafa3a5a96f489226e2be7d7b4687e2c9cabaf3dfd13738bef7bb81cd62',
'apple_ephemeralPublicKey':'MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAETB1mCkKYTEcYDUMrEm04TVz4NWLX3qrYcoFbjQtn2Oji4t3guu+mX+7EReLtH1FzgX6U8PJzYwp/J4kDgFLnwQ==',
'apple_publicKeyHash':'YWEPi8j+nYJHD5C04PdGEFHam6mlIexZ8moIWNn6Pbo=='
},
'apple_paymentMethod':{
'apple_displayName':'Visa 0253',
'apple_network':'Visa',
'apple_type':'debit'
},
'signature':'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b'
}'
};
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 = {
{
'digital_wallet'=> 'APPLE_PAY',
'command'=> 'PURCHASE',
'access_code': '4yyoUrilpc0Hs7wolpcy',
'merchant_identifier'=> '0d60670d',
'merchant_reference'=> 'Test-100118',
'amount' => '100',
'currency' => 'SAR',
'language' => 'en',
'customer_email' => 'S00116-3@hef.org.sa',
'apple_data' => 'nIje+wQGTVVBgFqBxJoTk8Maig4D/KEuM/lC6IW7KGO7ydRs95KmLyQC58K4griC/mnAtAYXM/qMinDzpc6KxcFx0orSAaCYg0kGSbPDSsxnEVGMroqTQj/KSTYeooLPIWJudrWzTbNh6OZloI10fNN27AJur6nL5WFyxmUYMw7Ip+a8oWWNAjrfGISEFNJ3qs089zUNnRSQZSLwArwvXxoUwby+iCcUzNqcovn6auzKx8ajAth0LA8QWdfgGT45g5qu9YPos7BqfF70O+NgOLHKZ8Z3rtISpYvukz9ecUxBEA20uob8ZmQCCJAt6NHjv0gMqgEWbVtljE04c3RWULZJkB6htw3sgLvp2NjMjW2jmKVBb5Yv2lwrae0bM9ryJnpkMHgVw2gEyPuayGvk/rGFKyZGYT5WwIfVhIEodg==',
'apple_signature' => 'MIAGCSqGSIb3DQEHAqCAMIACAQExDTALBglghkgBZQMEAgEwgAYJKoZIhvcNAQcBAACggDCCA+MwggOIoAMCAQICCEwwQUlRnVQ2MAoGCCqGSM49BAMCMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xOTA1MTgwMTMyNTdaFw0yNDA1MTYwMTMyNTdaMF8xJTAjBgNVBAMMHGVjYy1zbXAtYnJva2VyLXNpZ25fVUM0LVBST0QxFDASBgNVBAsMC2lPUyBTeXN0ZW1zMRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABMIVd+3r1seyIY9o3XCQoSGNx7C9bywoPYRgldlK9KVBG4NCDtgR80B+gzMfHFTD9+syINa61dTv9JKJiT58DxOjggIRMIICDTAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFCPyScRPk+TvJ+bE9ihsP6K7/S5LMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDIwggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMB0GA1UdDgQWBBSUV9tv1XSBhomJdi9+V4UH55tYJDAOBgNVHQ8BAf8EBAMCB4AwDwYJKoZIhvdjZAYdBAIFADAKBggqhkjOPQQDAgNJADBGAiEAvglXH+ceHnNbVeWvrLTHL+tEXzAYUiLHJRACth69b1UCIQDRizUKXdbdbrF0YDWxHrLOh8+j5q9svYOAiQ3ILN2qYzCCAu4wggJ1oAMCAQICCEltL786mNqXMAoGCCqGSM49BAMCMGcxGzAZBgNVBAMMEkFwcGxlIFJvb3QgQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDUwNjIzNDYzMFoXDTI5MDUwNjIzNDYzMFowejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8BcRhBnXZIXVGl4lgQd26ICi7957rk3gjfxLk+EzVtVmWzWuItCXdg0iTnu6CP12F86Iy3a7ZnC+yOgphP9URaOB9zCB9DBGBggrBgEFBQcBAQQ6MDgwNgYIKwYBBQUHMAGGKmh0dHA6Ly9vY3NwLmFwcGxlLmNvbS9vY3NwMDQtYXBwbGVyb290Y2FnMzAdBgNVHQ4EFgQUI/JJxE+T5O8n5sT2KGw/orv9LkswDwYDVR0TAQH/BAUwAwEB/zAfBgNVHSMEGDAWgBS7sN6hWDOImqSKmd6+veuv2sskqzA3BgNVHR8EMDAuMCygKqAohiZodHRwOi8vY3JsLmFwcGxlLmNvbS9hcHBsZXJvb3RjYWczLmNybDAOBgNVHQ8BAf8EBAMCAQYwEAYKKoZIhvdjZAYCDgQCBQAwCgYIKoZIzj0EAwIDZwAwZAIwOs9yg1EWmbGG+zXDVspiv/QX7dkPdU2ijr7xnIFeQreJ+Jj3m1mfmNVBDY+d6cL+AjAyLdVEIbCjBXdsXfM4O5Bn/Rd8LCFtlk/GcmmCEm9U+Hp9G5nLmwmJIWEGmQ8Jkh0AADGCAYkwggGFAgEBMIGGMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUwIITDBBSVGdVDYwCwYJYIZIAWUDBAIBoIGTMBgGCSqGSIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTIyMDcyMjEyNTg0NVowKAYJKoZIhvcNAQk0MRswGTALBglghkgBZQMEAgGhCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEIKXwC6uKZzm2+EqzT6s5VPw0ebOu0HCJnNS+9tXlm5J7MAoGCCqGSM49BAMCBEgwRgIhAO8T9hfo/NooRtvK+KxFceuY1GfLf5Bz4/oxiVL/Sd48AiEAyAGWQH4jbioivj7Y/3NFIPe9pYLx0OBHJDKLxV4gAD8AAAAAAAA==',
'apple_header' => {
'apple_transactionId' => 'ee0c2dafa3a5a96f489226e2be7d7b4687e2c9cabaf3dfd13738bef7bb81cd62',
'apple_ephemeralPublicKey' => 'MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAETB1mCkKYTEcYDUMrEm04TVz4NWLX3qrYcoFbjQtn2Oji4t3guu+mX+7EReLtH1FzgX6U8PJzYwp/J4kDgFLnwQ==',
'apple_publicKeyHash' => 'YWEPi8j+nYJHD5C04PdGEFHam6mlIexZ8moIWNn6Pbo=='
},
'apple_paymentMethod' => {
'apple_displayName' => 'Visa 0253',
'apple_network' => 'Visa',
'apple_type' => 'debit'
},
'signature' => 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b'
}
};
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)
String jsonRequestString = "{\n \"digital_wallet\":\"APPLE_PAY\",\n \"command\":\"PURCHASE\",\n \"access_code\":\"4yyoUrilpc0Hs7wolpcy\",\n \"merchant_identifier\":\"0d60670d\",\n \"merchant_reference\":\"Test-100118\",\n \"amount\":\"100\",\n \"currency\":\"SAR\",\n \"language\":\"en\",\n \"customer_email\":\"S00116-3@hef.org.sa\",\n \"apple_data\":\"nIje+wQGTVVBgFqBxJoTk8Maig4D/KEuM/lC6IW7KGO7ydRs95KmLyQC58K4griC/mnAtAYXM/qMinDzpc6KxcFx0orSAaCYg0kGSbPDSsxnEVGMroqTQj/KSTYeooLPIWJudrWzTbNh6OZloI10fNN27AJur6nL5WFyxmUYMw7Ip+a8oWWNAjrfGISEFNJ3qs089zUNnRSQZSLwArwvXxoUwby+iCcUzNqcovn6auzKx8ajAth0LA8QWdfgGT45g5qu9YPos7BqfF70O+NgOLHKZ8Z3rtISpYvukz9ecUxBEA20uob8ZmQCCJAt6NHjv0gMqgEWbVtljE04c3RWULZJkB6htw3sgLvp2NjMjW2jmKVBb5Yv2lwrae0bM9ryJnpkMHgVw2gEyPuayGvk/rGFKyZGYT5WwIfVhIEodg==\",\n \"apple_signature\":\"MIAGCSqGSIb3DQEHAqCAMIACAQExDTALBglghkgBZQMEAgEwgAYJKoZIhvcNAQcBAACggDCCA+MwggOIoAMCAQICCEwwQUlRnVQ2MAoGCCqGSM49BAMCMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xOTA1MTgwMTMyNTdaFw0yNDA1MTYwMTMyNTdaMF8xJTAjBgNVBAMMHGVjYy1zbXAtYnJva2VyLXNpZ25fVUM0LVBST0QxFDASBgNVBAsMC2lPUyBTeXN0ZW1zMRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABMIVd+3r1seyIY9o3XCQoSGNx7C9bywoPYRgldlK9KVBG4NCDtgR80B+gzMfHFTD9+syINa61dTv9JKJiT58DxOjggIRMIICDTAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFCPyScRPk+TvJ+bE9ihsP6K7/S5LMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDIwggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMB0GA1UdDgQWBBSUV9tv1XSBhomJdi9+V4UH55tYJDAOBgNVHQ8BAf8EBAMCB4AwDwYJKoZIhvdjZAYdBAIFADAKBggqhkjOPQQDAgNJADBGAiEAvglXH+ceHnNbVeWvrLTHL+tEXzAYUiLHJRACth69b1UCIQDRizUKXdbdbrF0YDWxHrLOh8+j5q9svYOAiQ3ILN2qYzCCAu4wggJ1oAMCAQICCEltL786mNqXMAoGCCqGSM49BAMCMGcxGzAZBgNVBAMMEkFwcGxlIFJvb3QgQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDUwNjIzNDYzMFoXDTI5MDUwNjIzNDYzMFowejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8BcRhBnXZIXVGl4lgQd26ICi7957rk3gjfxLk+EzVtVmWzWuItCXdg0iTnu6CP12F86Iy3a7ZnC+yOgphP9URaOB9zCB9DBGBggrBgEFBQcBAQQ6MDgwNgYIKwYBBQUHMAGGKmh0dHA6Ly9vY3NwLmFwcGxlLmNvbS9vY3NwMDQtYXBwbGVyb290Y2FnMzAdBgNVHQ4EFgQUI/JJxE+T5O8n5sT2KGw/orv9LkswDwYDVR0TAQH/BAUwAwEB/zAfBgNVHSMEGDAWgBS7sN6hWDOImqSKmd6+veuv2sskqzA3BgNVHR8EMDAuMCygKqAohiZodHRwOi8vY3JsLmFwcGxlLmNvbS9hcHBsZXJvb3RjYWczLmNybDAOBgNVHQ8BAf8EBAMCAQYwEAYKKoZIhvdjZAYCDgQCBQAwCgYIKoZIzj0EAwIDZwAwZAIwOs9yg1EWmbGG+zXDVspiv/QX7dkPdU2ijr7xnIFeQreJ+Jj3m1mfmNVBDY+d6cL+AjAyLdVEIbCjBXdsXfM4O5Bn/Rd8LCFtlk/GcmmCEm9U+Hp9G5nLmwmJIWEGmQ8Jkh0AADGCAYkwggGFAgEBMIGGMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUwIITDBBSVGdVDYwCwYJYIZIAWUDBAIBoIGTMBgGCSqGSIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTIyMDcyMjEyNTg0NVowKAYJKoZIhvcNAQk0MRswGTALBglghkgBZQMEAgGhCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEIKXwC6uKZzm2+EqzT6s5VPw0ebOu0HCJnNS+9tXlm5J7MAoGCCqGSM49BAMCBEgwRgIhAO8T9hfo/NooRtvK+KxFceuY1GfLf5Bz4/oxiVL/Sd48AiEAyAGWQH4jbioivj7Y/3NFIPe9pYLx0OBHJDKLxV4gAD8AAAAAAAA==\",\n \"apple_header\":{\n \"apple_transactionId\":\"ee0c2dafa3a5a96f489226e2be7d7b4687e2c9cabaf3dfd13738bef7bb81cd62\",\n \"apple_ephemeralPublicKey\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAETB1mCkKYTEcYDUMrEm04TVz4NWLX3qrYcoFbjQtn2Oji4t3guu+mX+7EReLtH1FzgX6U8PJzYwp/J4kDgFLnwQ==\",\n \"apple_publicKeyHash\":\"YWEPi8j+nYJHD5C04PdGEFHam6mlIexZ8moIWNn6Pbo==\"\n },\n \"apple_paymentMethod\":{\n \"apple_displayName\":\"Visa 0253\",\n \"apple_network\":\"Visa\",\n \"apple_type\":\"debit\"\n },\n \"signature\":\"fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b\"\n
}";
// 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());
{
"digital_wallet":"APPLE_PAY",
"command":"PURCHASE",
"access_code":"4yyoUrilpc0Hs7wolpcy",
"merchant_identifier":"0d60670d",
"merchant_reference":"AbhiTest-100118",
"amount":"100",
"currency":"SAR",
"language":"en",
"customer_email":"S00116-3@hef.org.sa",
"apple_data":"nIje+wQGTVVBgFqBxJoTk8Maig4D/KEuM/lC6IW7KGO7ydRs95KmLyQC58K4griC/mnAtAYXM/qMinDzpc6KxcFx0orSAaCYg0kGSbPDSsxnEVGMroqTQj/KSTYeooLPIWJudrWzTbNh6OZloI10fNN27AJur6nL5WFyxmUYMw7Ip+a8oWWNAjrfGISEFNJ3qs089zUNnRSQZSLwArwvXxoUwby+iCcUzNqcovn6auzKx8ajAth0LA8QWdfgGT45g5qu9YPos7BqfF70O+NgOLHKZ8Z3rtISpYvukz9ecUxBEA20uob8ZmQCCJAt6NHjv0gMqgEWbVtljE04c3RWULZJkB6htw3sgLvp2NjMjW2jmKVBb5Yv2lwrae0bM9ryJnpkMHgVw2gEyPuayGvk/rGFKyZGYT5WwIfVhIEodg==",
"apple_signature":"MIAGCSqGSIb3DQEHAqCAMIACAQExDTALBglghkgBZQMEAgEwgAYJKoZIhvcNAQcBAACggDCCA+MwggOIoAMCAQICCEwwQUlRnVQ2MAoGCCqGSM49BAMCMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xOTA1MTgwMTMyNTdaFw0yNDA1MTYwMTMyNTdaMF8xJTAjBgNVBAMMHGVjYy1zbXAtYnJva2VyLXNpZ25fVUM0LVBST0QxFDASBgNVBAsMC2lPUyBTeXN0ZW1zMRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABMIVd+3r1seyIY9o3XCQoSGNx7C9bywoPYRgldlK9KVBG4NCDtgR80B+gzMfHFTD9+syINa61dTv9JKJiT58DxOjggIRMIICDTAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFCPyScRPk+TvJ+bE9ihsP6K7/S5LMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDIwggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMB0GA1UdDgQWBBSUV9tv1XSBhomJdi9+V4UH55tYJDAOBgNVHQ8BAf8EBAMCB4AwDwYJKoZIhvdjZAYdBAIFADAKBggqhkjOPQQDAgNJADBGAiEAvglXH+ceHnNbVeWvrLTHL+tEXzAYUiLHJRACth69b1UCIQDRizUKXdbdbrF0YDWxHrLOh8+j5q9svYOAiQ3ILN2qYzCCAu4wggJ1oAMCAQICCEltL786mNqXMAoGCCqGSM49BAMCMGcxGzAZBgNVBAMMEkFwcGxlIFJvb3QgQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDUwNjIzNDYzMFoXDTI5MDUwNjIzNDYzMFowejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8BcRhBnXZIXVGl4lgQd26ICi7957rk3gjfxLk+EzVtVmWzWuItCXdg0iTnu6CP12F86Iy3a7ZnC+yOgphP9URaOB9zCB9DBGBggrBgEFBQcBAQQ6MDgwNgYIKwYBBQUHMAGGKmh0dHA6Ly9vY3NwLmFwcGxlLmNvbS9vY3NwMDQtYXBwbGVyb290Y2FnMzAdBgNVHQ4EFgQUI/JJxE+T5O8n5sT2KGw/orv9LkswDwYDVR0TAQH/BAUwAwEB/zAfBgNVHSMEGDAWgBS7sN6hWDOImqSKmd6+veuv2sskqzA3BgNVHR8EMDAuMCygKqAohiZodHRwOi8vY3JsLmFwcGxlLmNvbS9hcHBsZXJvb3RjYWczLmNybDAOBgNVHQ8BAf8EBAMCAQYwEAYKKoZIhvdjZAYCDgQCBQAwCgYIKoZIzj0EAwIDZwAwZAIwOs9yg1EWmbGG+zXDVspiv/QX7dkPdU2ijr7xnIFeQreJ+Jj3m1mfmNVBDY+d6cL+AjAyLdVEIbCjBXdsXfM4O5Bn/Rd8LCFtlk/GcmmCEm9U+Hp9G5nLmwmJIWEGmQ8Jkh0AADGCAYkwggGFAgEBMIGGMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUwIITDBBSVGdVDYwCwYJYIZIAWUDBAIBoIGTMBgGCSqGSIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTIyMDcyMjEyNTg0NVowKAYJKoZIhvcNAQk0MRswGTALBglghkgBZQMEAgGhCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEIKXwC6uKZzm2+EqzT6s5VPw0ebOu0HCJnNS+9tXlm5J7MAoGCCqGSM49BAMCBEgwRgIhAO8T9hfo/NooRtvK+KxFceuY1GfLf5Bz4/oxiVL/Sd48AiEAyAGWQH4jbioivj7Y/3NFIPe9pYLx0OBHJDKLxV4gAD8AAAAAAAA==",
"apple_header":{
"apple_transactionId":"ee0c2dafa3a5a96f489226e2be7d7b4687e2c9cabaf3dfd13738bef7bb81cd62",
"apple_ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAETB1mCkKYTEcYDUMrEm04TVz4NWLX3qrYcoFbjQtn2Oji4t3guu+mX+7EReLtH1FzgX6U8PJzYwp/J4kDgFLnwQ==",
"apple_publicKeyHash":"YWEPi8j+nYJHD5C04PdGEFHam6mlIexZ8moIWNn6Pbo=="
},
"apple_paymentMethod":{
"apple_displayName":"Visa 0253",
"apple_network":"Visa",
"apple_type":"debit"
},
"signature":"fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b"
}
ATTRIBUTES | Description |
---|---|
digital_wallet Alpha Mandatory Max: 100 |
The buyer’s digital wallet. Possible/ expected values: APPLE_PAY Special characters: _ |
command Alpha Mandatory Max: 20 |
A command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
access_code Alphanumeric Mandatory Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Mandatory Max: 254 |
The customer’s email. Example: customer1@domain.com Special characters: _ - . @ + |
apple_data Alphanumeric Mandatory Max: 500 |
This string represent the encrypted payment data. Example: Check Example 1 below the table. Special characters: / + = |
apple_signature Alphanumeric Mandatory Max: 3000 |
Signature of the payment and header data. The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm. Example: MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID5jCC… Special characters: / + = |
apple_header List Mandatory Max: - |
Additional version-dependent information used to decrypt and verify the payment. Example: Check Example 2 below the table. |
apple_transactionId Alphanumeric Mandatory Max: 100 |
Transaction identifier, generated on the device. Example: 93eec76cbedaedca44648e3d5c314766906e4e78ce33cd3b8 396f105a1c0daed |
apple_ephemeralPublicKey Alphanumeric Mandatory max: 200 |
Ephemeral public key bytes. Example: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEM9JqF04vD lGI… |
apple_publicKeyHash Alphanumeric Mandatory Max: 100 |
Hash of the X.509 encoded public key bytes of the merchant’s certificate. Example: bVTUiyTv0uCJgQz8SNYHBHOlHMD6sR1qDuCqTaETzkw= Special characters: / + = |
apple_paymentMethod List Mandatory Max: - |
The details of the credit card. Example: Check Example 3 below the table. Special characters: - |
apple_displayName Alphanumeric Mandatory Max: 50 |
The credit card name. Example: Visa 0492 Special characters: Space |
apple_network Alpha Mandatory Max: 20 |
The credit card name. Example: Visa 0492 Possible/ expected values: - Visa - MasterCard - AmEx |
apple_type Alpha Mandatory Max: 20 |
The credit card type. Example: Visa 0492 Example: credit |
signature Alphanumeric Mandatory Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
apple_applicationData Alphanumeric Optional Max: 200 |
Hash of the applicationData property of the original PKPaymentRequest object. Example: 5173d4e05f2e07dc4e7ea9669bda185712ffffe1d6 cfce2d4e854d7661e70d67… |
eci Alpha Optional Max: 16 |
E-commerce indicator. *MOTO and E-commerce indicator clickable in VISA, MASTERCARD and AMEX. Possible/ expected values: - ECOMMERCE - MOTO |
order_description Alphanumeric Optional Max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
customer_ip Alphanumeric Mandatory max: 45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf Special characters: . : |
customer_name Alpha Optional Max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' Space |
merchant_extra Alphanumeric Optional Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra1 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra2 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra3 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra4 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra5 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
phone_number Alphanumeric Optional max: 19 |
The customer’s phone number. Example: 00962797219966 Special characters: + - ( ) Space |
recurring_mode Alphanumeric Optional max: 20 |
Indicates if the subsequent payments within the agreement has unscheduled (unknown interval/amount). Possible/ expected values: UNSCHEDULED. |
Example 1
Example 2
Example 3
Apple Pay Authorization/ Purchase - Response
The following parameters will be returned in Amazon Payment Services’ response:
ATTRIBUTES | Description |
---|---|
digital_wallet Alpha Max: 100 |
The buyer’s digital wallet. Possible/ expected values: APPLE_PAY |
command Alpha Max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
access_code Alphanumeric Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
amount Numeric Max: 10 |
The transaction’s amount. Example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Max: 254 |
The customer’s email. Example: customer1@domain.com |
signature Alphanumeric Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
fort_id Numeric Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
payment_option Alpha Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - MADA (for Purchase operations and eci Ecommerce only) |
eci Alpha Max: 16 |
The E-commerce indicator. Possible/ expected values: - ECOMMERCE - MOTO |
order_description Alphanumeric Max: 150 |
It holds the description of the order. Example: iPhone 6-S |
customer_ip Alphanumeric max: 45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf |
customer_name Alpha Max: 40 |
The customer’s name. Example: John Smith |
merchant_extra Alphanumeric Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra1 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra2 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra3 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra4 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra5 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
authorization_code Alphanumeric Max: 100 |
The authorization code returned from the 3rd party. Example: P1000000000000372136 |
response_message Alphanumeric Max: 150 |
The message description of the response code; it returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
card_holder_name Alpha Max: 50 |
The card holder name. Example: John Smith |
expiry_date Numeric Max: 4 |
The card’s expiry date. Example: 2105 |
card_number Numeric Max: 19 |
The masked credit card’s number. AMEX payment option takes 15 digits card number. *Otherwise, they take 16 digits card number. Example: 400555*****0001 |
phone_number Alphanumeric max: 19 |
The customer’s phone number. Example: 00962797219966 |
agreement_id Alphanumeric Optional max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
recurring_mode Alphanumeric Optional max: 20 |
Indicates if the subsequent payments within the agreement has unscheduled (unknown interval/amount). Possible/ expected values: UNSCHEDULED. |
Apple Pay Recurring 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 and the merchant page channel. Your customer authenticates their identity using Touch ID verification to complete the payment.Using the Apple Pay Recurring service, a customer can make recurring payments for a service.
Apple Pay Recurring Authorization/ Purchase - Request
Include the following parameters in the request you will send to Amazon Payment Services:
Request Sample
{
"command": "PURCHASE",
"access_code": "XXXX",
"merchant_identifier": "XXXX",
"merchant_reference": "XXXXX-XXXXX",
"amount": "100",
"currency": "SAR",
"language": "en",
"customer_email": "test@merchantdomain.com",
"eci": "RECURRING",
"token_name": "XXXXX",
"digital_wallet": "APPLE_PAY",
"agreement_id": "MCC8891130504",
"recurring_mode": "UNSCHEDULED",
"signature": "XXXXXXXXXX"
}
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'command'=> 'PURCHASE',
'access_code'=> 'XXXX',
'merchant_identifier' => 'XXXX',
'merchant_reference'=> 'XXXXX-XXXXX',
'amount'=> '100',
'currency'=> 'SAR',
'language'=> 'en',
'customer_email'=> 'test@merchantdomain.com',
'eci'=> 'RECURRING',
'token_name'=> 'XXXXX',
'digital_wallet'=> 'APPLE_PAY',
'agreement_id'=> 'MCC8891130504',
'recurring_mode'=> 'UNSCHEDULED',
'signature'=>'XXXXXXXXXX'
);
$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>";
require 'json'
require 'net/http'
require 'net/https'
require 'uri'
require 'openssl'
arrData = {
'command'=> 'PURCHASE',
'access_code'=> 'XXXX',
'merchant_identifier' => 'XXXX',
'merchant_reference'=> 'XXXXX-XXXXX',
'amount'=> '100',
'currency'=> 'SAR',
'language'=> 'en',
'customer_email'=> 'test@merchantdomain.com',
'eci'=> 'RECURRING',
'token_name'=> 'XXXXX',
'digital_wallet'=> 'APPLE_PAY',
'agreement_id'=> 'MCC8891130504',
'recurring_mode'=> 'UNSCHEDULED',
'signature'=>'XXXXXXXXXX'
};
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)
String jsonRequestString = "{\n \"command\": \"PURCHASE\",\n \"access_code\": \"XXXX\",\n \"merchant_identifier\": \"XXXX\",\n \"merchant_reference\": \"XXXXX-XXXXX\",\n \"amount\": \"100\",\n \"currency\": \"SAR\",\n \"language\": \"en\",\n \"customer_email\": \"test@merchantdomain.com\",\n \"eci\": \"RECURRING\",\n \"token_name\": \"XXXXX\",\n \"digital_wallet\": \"APPLE_PAY\",\n \"agreement_id\": \"MCC8891130504\",\n \"recurring_mode\": \"UNSCHEDULED\",\n \"signature\": \"XXXXXXXXXX\"\n}";
// 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':'PURCHASE',
'access_code':'XXXX',
'merchant_identifier' :'XXXX',
'merchant_reference':'XXXXX-XXXXX',
'amount':'100',
'currency':'SAR',
'language':'en',
'customer_email':'test@merchantdomain.com',
'eci':'RECURRING',
'token_name':'XXXXX',
'digital_wallet':'APPLE_PAY',
'agreement_id':'MCC8891130504',
'recurring_mode':'UNSCHEDULED',
'signature':'XXXXXXXXXX'
};
values = json.dumps(arrData)
data = urllib.urlencode(values)
req = urllib2.Request(url, data)
response = urllib2.urlopen(req)
page = response.read()
print page + '\n\n'
ATTRIBUTES | Description |
---|---|
digital_wallet Alpha Mandatory Max: 100 |
The buyer’s digital wallet. Possible/ expected values: APPLE_PAY Special characters: _ |
command Alpha Mandatory Max: 20 |
A command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Mandatory Max: 254 |
The customer’s email. Example: customer1@domain.com Special characters: _ - . @ + |
payment_option Alpha Optional Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA |
eci Alpha Mandatory Max: 16 |
E-commerce indicator. Possible/ expected values: RECURRING |
order_description Alphanumeric Optional Max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
customer_ip Alphanumeric Mandatory max: 45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf Special characters: . : |
customer_name Alpha Optional Max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' Space |
phone_number Alphanumeric Optional max: 19 |
The customer’s phone number. Example: 00962797219966 Special characters: + - ( ) Space |
token_name Alphanumeric Mandatory max: 100 |
The Token name. Example: Op9Vmp Special characters: - _ . @ |
recurring_mode Alphanumeric Mandatory max: 20 |
Indicates if the subsequent payments within the agreement has unscheduled (unknown interval/amount). Possible/ expected values: UNSCHEDULED. |
agreement_id Alphanumeric Mandatory max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments. You can check the agreement id value from the section Apple Pay Response |
Apple Pay Recurring Authorization/ Purchase - Response
The following parameters will be returned in Amazon Payment Services’ response:
ATTRIBUTES | Description |
---|---|
digital_wallet Alpha Max: 100 |
The buyer’s digital wallet. Possible/ expected values: APPLE_PAY |
command Alpha Max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
access_code Alphanumeric Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
amount Numeric Max: 10 |
The transaction’s amount. Example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Max: 254 |
The customer’s email. Example: customer1@domain.com |
signature Alphanumeric Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
fort_id Numeric Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
payment_option Alpha Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA |
eci Alpha Max: 16 |
The E-commerce indicator. Possible/ expected values: recurring |
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 |
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 |
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 |
recurring_mode Alphanumeric Optional max: 20 |
Indicates if the subsequent payments within the agreement has unscheduled (unknown interval/amount). Possible/ expected values: UNSCHEDULED. |
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:
Request Sample
{
"command": "PURCHASE",
"access_code": "XXXX",
"merchant_identifier": "XXXX",
"merchant_reference": "XXXXX-XXXXX",
"amount": "100",
"currency": "SAR",
"language": "en",
"customer_email": test@merchantdomain.com,
"token_name": "XXXXX",
"digital_wallet": "APPLE_PAY",
"signature": "XXXXXXXXXX"
}
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'command'=> 'PURCHASE',
'access_code'=> 'XXXX',
'merchant_identifier' => 'XXXX',
'merchant_reference'=> 'XXXXX-XXXXX',
'amount'=> '100',
'currency'=> 'SAR',
'language'=> 'en',
'customer_email'=> 'test@merchantdomain.com',
'eci'=> 'RECURRING',
'token_name'=> 'XXXXX',
'digital_wallet'=> 'APPLE_PAY',
'signature'=>'XXXXXXXXXX'
);
$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>";
require 'json'
require 'net/http'
require 'net/https'
require 'uri'
require 'openssl'
arrData = {
'command'=> 'PURCHASE',
'access_code'=> 'XXXX',
'merchant_identifier' => 'XXXX',
'merchant_reference'=> 'XXXXX-XXXXX',
'amount'=> '100',
'currency'=> 'SAR',
'language'=> 'en',
'customer_email'=> 'test@merchantdomain.com',
'eci'=> 'RECURRING',
'token_name'=> 'XXXXX',
'digital_wallet'=> 'APPLE_PAY',
'signature'=>'XXXXXXXXXX'
};
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)
String jsonRequestString = "{\n \"command\": \"PURCHASE\",\n \"access_code\": \"XXXX\",\n \"merchant_identifier\": \"XXXX\",\n \"merchant_reference\": \"XXXXX-XXXXX\",\n \"amount\": \"100\",\n \"currency\": \"SAR\",\n \"language\": \"en\",\n \"customer_email\": \"test@merchantdomain.com\",\n \"eci\": \"RECURRING\",\n \"token_name\": \"XXXXX\",\n \"digital_wallet\": \"APPLE_PAY\",\n \"signature\": \"XXXXXXXXXX\"\n}";
// 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':'PURCHASE',
'access_code':'XXXX',
'merchant_identifier' :'XXXX',
'merchant_reference':'XXXXX-XXXXX',
'amount':'100',
'currency':'SAR',
'language':'en',
'customer_email':'test@merchantdomain.com',
'eci':'RECURRING',
'token_name':'XXXXX',
'digital_wallet':'APPLE_PAY',
'signature':'XXXXXXXXXX'
};
values = json.dumps(arrData)
data = urllib.urlencode(values)
req = urllib2.Request(url, data)
response = urllib2.urlopen(req)
page = response.read()
print page + '\n\n'
ATTRIBUTES | Description |
---|---|
digital_wallet Alpha Mandatory Max: 100 |
The buyer’s digital wallet. Possible/ expected values: APPLE_PAY Special characters: _ |
command Alpha Mandatory Max: 20 |
A command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Mandatory Max: 254 |
The customer’s email. Example: customer1@domain.com Special characters: _ - . @ + |
sdk_token Alphanumeric Mandatory Max: 100 |
An SDK token to enable using the Mobile SDK. Example: Dwp78q3 |
payment_option Alpha Optional Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - MADA (for Purchase operations and eci Ecommerce only) |
eci Alpha Optional Max: 16 |
E-commerce indicator. Possible/ expected values: ECOMMERCE |
order_description Alphanumeric Optional Max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
customer_ip Alphanumeric Mandatory max: 45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf Special characters: . : |
customer_name Alpha Optional Max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' Space |
phone_number Alphanumeric Optional max: 19 |
The customer’s phone number. Example: 00962797219966 Special characters: + - ( ) Space |
token_name Alphanumeric Optional max: 100 |
The Token name. Example: Op9Vmp Special characters: - _ . @ |
settlement_reference Alphanumeric Optional max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 Special characters: - _ . |
merchant_extra Alphanumeric Optional Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra1 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra2 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra3 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra4 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra5 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
Apple Pay SDK Authorization/ Purchase - Response
The following parameters will be returned in Amazon Payment Services’ response:
ATTRIBUTES | Description |
---|---|
digital_wallet Alpha Max: 100 |
The buyer’s digital wallet. Possible/ expected values: APPLE_PAY |
command Alpha Max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
access_code Alphanumeric Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
amount Numeric Max: 10 |
The transaction’s amount. Example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Max: 254 |
The customer’s email. Example: customer1@domain.com |
signature Alphanumeric Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
fort_id Numeric Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
sdk_token Alphanumeric Max: 100 |
An SDK token to enable using the Mobile SDK. Example: Dwp78q3 |
payment_option Alpha Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - MADA (for Purchase operations and eci Ecommerce only) |
eci Alpha Max: 16 |
The E-commerce indicator. Possible/ expected values: ECOMMERCE |
order_description Alphanumeric Max: 150 |
It holds the description of the order. Example: iPhone 6-S |
customer_ip Alphanumeric max: 45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf |
customer_name Alpha Max: 40 |
The customer’s name. Example: John Smith |
merchant_extra Alphanumeric Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra1 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra2 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra3 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra4 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra5 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
authorization_code Alphanumeric Max: 100 |
The authorization code returned from the 3rd party. Example: P1000000000000372136 |
response_message Alphanumeric Max: 150 |
The message description of the response code; it returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
card_holder_name Alpha Max: 50 |
The card holder name. Example: John Smith |
expiry_date Numeric Max: 4 |
The card’s expiry date. Example: 2105 |
card_number Numeric Max: 19 |
The masked credit card’s number. AMEX payment option takes 15 digits card number. *Otherwise, they take 16 digits card number. Example: 400555*****0001 |
phone_number Alphanumeric max: 19 |
The customer’s phone number. Example: 00962797219966 |
token_name Alphanumeric max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp |
settlement_reference Alphanumeric max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 |
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. Amazon Payment Services enables you to collect additional payment details related to your customer’s subscription and store them through APS to process subsequent payments as following:
- Provide the required subscription information in the initial transaction. APS will store the submitted details for customer’s recurring payments.
- Use the stored payment details to perform subsequent payments, initiated by you, as a result of a payment agreement with your customer.“
Read more about how recurring transactions work here.
Recurring transactions can be integrated in two ways:
1- Manually from FORT backoffice through subscription service.
2- Using APIs through Recurring integration.
Subscription Service
The subscription service allows a Merchant to create recurring payments for a customer for a specific period of time called billing cycle ” with weekly or monthly" biases. The Merchant can integrate this service through Amazon Payment Services back-office only without any development effort needed.
Before starting :
Before you start integrating this service you need to be aware of the following: 1-You should have a recurring MID issued from your acquiring bank 2- You need to collect the card information from the customer through a manual order from the back-office before processing a recurring, request. 3-You should have a MOTO MID issued from your acquiring bank, this process will be liaised with the business development and underwriting teams to get the bank approvals.
Subscription Integration from backoffice:
The subscription service management can be done from the your back-office after activating this service.
You need to follow these steps in order to create the subscriptions :
- Go to Subscription Management tab to start creating the subscription/ The two options which you can start using are :
1-New Customer Subscription.
2-Existing Customer Subscription.
New Customer Subscription
Under this tab , you can create a new customer subscription by collecting the card details through the manual order. Under this tab you should get the clear card information such as, “card number , expiry date” from the customer in addition to more details such as :
{
"command": "PURCHASE",
"access_code": "XXXX",
"merchant_identifier": "XXXX",
"merchant_reference": "XXXXX-XXXXX",
"amount": "100",
"currency": "SAR",
"language": "en",
"customer_email": test@merchantdomain.com,
"order_description": "iPhone12",
"card_number": "4005550000000001",
"expiry_date": "2505"
}
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'command'=> 'PURCHASE',
'access_code'=> 'XXXX',
'merchant_identifier'=> 'XXXX',
'merchant_reference'=> 'XXXXX-XXXXX',
'amount'=> '100',
'currency'=> 'SAR',
'language'=> 'en',
'customer_email'=> test@merchantdomain.com,
'order_description'=> 'iPhone12',
'card_number'=> '4005550000000001',
'expiry_date'=> '2505'
);
$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>";
require 'json'
require 'net/http'
require 'net/https'
require 'uri'
require 'openssl'
arrData = {
'command'=> 'PURCHASE',
'access_code'=> 'XXXX',
'merchant_identifier'=> 'XXXX',
'merchant_reference'=> 'XXXXX-XXXXX',
'amount'=> '100',
'currency'=> 'SAR',
'language'=> 'en',
'customer_email'=> test@merchantdomain.com,
'order_description'=> 'iPhone12',
'card_number'=> '4005550000000001',
'expiry_date'=> '2505'
};
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)
String jsonRequestString = "{\n \"command\": \"PURCHASE\",\n \"access_code\": \"XXXX\",\n \"merchant_identifier\": \"XXXX\",\n \"merchant_reference\": \"XXXXX-XXXXX\",\n \"amount\": \"100\",\n \"currency\": \"SAR\",\n \"language\": \"en\",\n \"customer_email\": test@merchantdomain.com,\n \"order_description\": \"iPhone12\",\n \"card_number\": \"4005550000000001\",\n \"expiry_date\": \"2505\"\n"
}";
// 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': 'PURCHASE',
'access_code': 'XXXX',
'merchant_identifier': 'XXXX',
'merchant_reference': 'XXXXX-XXXXX',
'amount': '100',
'currency': 'SAR',
'language': 'en',
'customer_email': test@merchantdomain.com,
'order_description': 'iPhone12',
'card_number': '4005550000000001',
'expiry_date': '2505'
};
values = json.dumps(arrData)
data = urllib.urlencode(values)
req = urllib2.Request(url, data)
response = urllib2.urlopen(req)
page = response.read()
print page + '\n\n'
ATTRIBUTES | Description |
---|---|
command Alpha Mandatory |
command. Possible/ expected values: PURCHASE or AUTHORIZATION |
merchant_reference Alphanumeric Mandatory |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory |
The checkout page and messages language. Possible/ expected values: en / ar |
customer_email Alphanumeric Mandatory |
The customer’s email. Example: customer@domain.com Special characters: _ - . @ + |
customer_name Alphanumeric Optional |
The customer’s name. Example : John Smith |
order_description Alphanumeric Mandatory |
A description of the order. Example : iPhone 12 Pro Special Characters: # ’/ ._- :$ space indicator. |
card_number Numeric Mandatory |
The clear credit card’s number. Example: 4005550000000001 |
expiry_date Numeric Mandatory |
The card’s expiry date. Example: 2505. |
After you complete this step you will get a page that contains the response of the manual order you should save the Token Name returned in. If the payment is processed successfully, you can start create the subscription by clicking the Create Subscription button displayed or you can choose the Existing Customer Subscription option under Subscription Management tab.
Existing Customer Subscription
Under this tab ,you can start creating the subscription for the customer using the Token Name. The fields required to create a particular subscription for the customers are:
ATTRIBUTES | Description |
---|---|
token_name Alphanumeric Mandatory |
The Token received from the first payment “through the manual order or any other channel the merchant integrated for the first payment Example: Op9Vmp Special characters: . @ - _ |
Subscription ID Numeric Mandatory |
It refers to the subscription reference , this ID will be used to identify the subscription for each customer and the merchant can search for any subscription from the subscription reports using it |
merchant_reference Alphanumeric Mandatory |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory |
The currency of the transaction’s amount in ISO code 3. Example: AED |
customer_email Alphanumeric Mandatory |
The customer’s email. Example: customer@domain.com Special characters: _ - . @ + |
customer_name Alphanumeric Optional |
The customer’s name. Example : John Smith |
Billing Cycle Numeric Mandatory |
It refers to the duration ( Months / Weeks ) when the Merchant needs to deduct the amount from the customer one time. For example if the Merchant set this field as 5 Monthly , we will deduct the amount from the customer one time for each 5 months. |
Number Of Billing Cycle Numeric Optional |
Number of times the customer will be charged the subscription amount. Example: if the merchant chooses the number of cycles as 2 and the billing cycle is one per month , we will deduct the amount 2 times only ( for two months ). A customer will be charged infinite number of times if this field is empty. |
Next Execution Date Numeric Mandatory |
The Merchant should set the date on which he needs to deduct the next subscription amount from the customer. This date will be updated automatically after each subscription cycle. |
- After you create the subscription for the customer , it will be listed under the Subscription Management tab in the account , if you click on any subscription through the subscription ID , you can modify the subscription details for the customer like "Billing Cycle , Number of billing cycle , Customer Name , Customer Email , Currency , Next Execution Date”. If you wish to stop the subscription , you should choose “Suspend” after choosing the subscriptionID that you want to stop, we will stop the recurring payment for this subscription.
- You can view the recurring payments which have been processed for all the subscriptions from Subscription Report .
Recurring Integration
Merchant can integrate recurring service through APIs in order to charge customers offline using permenant tokens.
Recurring URLs
Test Environment URL:
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production Environment URL:
https://paymentservices.payfort.com/FortAPI/paymentApi
Parameters Submission Type
REST POST request using JSON.
Recurring - Request
Include the following parameters in the request you will send to Amazon Payment Services:
{
"command": "PURCHASE",
"access_code": "XXXX",
"merchant_identifier": "XXXX",
"merchant_reference": "XXXXX-XXXXX",
"amount": "100",
"currency": "SAR",
"eci": "mandatory",
"language": "en",
"customer_email": test@merchantdomain.com,
"token_name": "XXXXX",
"signature": "XXXXXXXXXX"
}
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'command'=> 'PURCHASE',
'access_code'=> 'XXXX',
'merchant_identifier' => 'XXXX',
'merchant_reference'=> 'XXXXX-XXXXX',
'amount'=> '100',
'currency'=> 'SAR',
'language'=> 'en',
'customer_email'=> 'test@merchantdomain.com',
'eci'=> 'RECURRING',
'token_name'=> 'XXXXX'
'signature'=>'XXXXXXXXXX'
);
$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>";
require 'json'
require 'net/http'
require 'net/https'
require 'uri'
require 'openssl'
arrData = {
'command'=> 'PURCHASE',
'access_code'=> 'XXXX',
'merchant_identifier' => 'XXXX',
'merchant_reference'=> 'XXXXX-XXXXX',
'amount'=> '100',
'currency'=> 'SAR',
'language'=> 'en',
'customer_email'=> 'test@merchantdomain.com',
'eci'=> 'RECURRING',
'token_name'=> 'XXXXX',
'signature'=>'XXXXXXXXXX'
};
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)
String jsonRequestString = "{\n \"command\": \"PURCHASE\",\n \"access_code\": \"XXXX\",\n \"merchant_identifier\": \"XXXX\",\n \"merchant_reference\": \"XXXXX-XXXXX\",\n \"amount\": \"100\",\n \"currency\": \"SAR\",\n \"language\": \"en\",\n \"customer_email\": \"test@merchantdomain.com\",\n \"eci\": \"RECURRING\",\n \"token_name\": \"XXXXX\",\n \"signature\": \"XXXXXXXXXX\"\n}";
// 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':'PURCHASE',
'access_code':'XXXX',
'merchant_identifier' :'XXXX',
'merchant_reference':'XXXXX-XXXXX',
'amount':'100',
'currency':'SAR',
'language':'en',
'customer_email':'test@merchantdomain.com',
'eci':'RECURRING',
'token_name':'XXXXX',
'signature':'XXXXXXXXXX'
};
values = json.dumps(arrData)
data = urllib.urlencode(values)
req = urllib2.Request(url, data)
response = urllib2.urlopen(req)
page = response.read()
print page + '\n\n'
ATTRIBUTES | Description |
---|---|
command Alpha Mandatory max: 20 |
command. Possible/ expected values: PURCHASE |
access_code Alphanumeric Mandatory max: 20 |
Access code. Example: zx0IPmPy5jp1vAz |
merchant_identifier Alphanumeric Mandatory max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory max: 2 |
The checkout page and messages language. Possible/ expected values: en / ar |
customer_email Alphanumeric Mandatory max: 254 |
The customer’s email. Example: customer@domain.com Special characters: _ - . @ + |
eci Alpha Mandatory max: 16 |
Ecommerce indicator. Possible/ expected values: RECURRING |
token_name Alphanumeric Mandatory max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp Special characters: _ - . @ |
signature Alphanumeric Mandatory max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
payment_option Alpha Optional Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX |
order_description Alphanumeric Optional max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
customer_name Alpha Optional max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' Space |
merchant_extra Alphanumeric Optional Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra1 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra2 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra3 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra4 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra5 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
phone_number Alphanumeric Optional max: 19 |
The customer’s phone number. Example: 00962797219966 Special characters: + - ( ) Space |
settlement_reference Alphanumeric Optional max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 Special characters: - _ . |
agreement_id Alphanumeric Optional max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
Sample Recurring Purchase Request :
Redirection / Merchant Page integration :
Trusted integration :
MADA RECURRING :
Recurring - Response
The following parameters will be returned in Amazon Payment Services’ response:
ATTRIBUTES | Description |
---|---|
command Alpha max: 20 |
command. Possible/ expected values: PURCHASE |
access_code Alphanumeric max: 20 |
Access code. Example: zx0IPmPy5jp1vAz |
merchant_identifier Alphanumeric max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
amount Numeric max: 10 |
The transaction’s amount. Example: 10000 |
currency Alpha max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha max: 2 |
The checkout page and messages language. Possible/ expected values: en / ar |
customer_email Alphanumeric max: 254 |
The customer’s email. Example: customer@domain.com |
eci Alpha max: 16 |
Ecommerce indicator. Possible/ expected values: RECURRING |
token_name Alphanumeric max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp |
signature Alphanumeric max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
fort_id Numeric max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
payment_option Alpha Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX |
order_description Alphanumeric max: 150 |
It holds the description of the order. Example: iPhone 6-S |
customer_name Alpha max: 40 |
The customer’s name. Example: John Smith |
merchant_extra Alphanumeric Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra1 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra2 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra3 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra4 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra5 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
expiry_date Numeric Max: 4 |
The card’s expiry date. Example: 2105 |
card_number Numeric Max: 16 |
The clear credit card’s number. Example: 400555******0001 |
authorization_code Alphanumeric max: 100 |
The authorization code returned from the 3rd party. Example: P1000000000000372136 |
response_message Alphanumeric max: 150 |
Message description of the response code. It returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
status Numeric max: 2 |
A two-digit numeric value that indicates the status of the transaction Possible/ expected values: (Please refer to section statuses). |
phone_number Alphanumeric max: 19 |
The customer’s phone number. Example: 00962797219966 |
settlement_reference Alphanumeric max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 |
agreement_id Alphanumeric max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
Installments
Your customers can enjoy installment payments thanks to a partnership between Amazon Payment Services and several issuing banks and credit card providers.
Note that installments are charged to your customer’s credit card. As the merchant you are always paid the full transaction amount immediately – it is the responsibility of the customer’s bank to collect the installments that are due from your customer’s credit card.
You have two options for installments on redirection:
1. Standalone
2. Easy redirection installments
Read more about installments here.
Easy Installments Redirection
This option does not required adding additional parameters into the Redirection request
The installment option will be displayed inside the redirection payment form if the customer’s card and the amount is eligible for installments.
Upon selection the installment option ,the banks and the plans which offered will persist.
Standalone Installments Redirection Service
Standalone installments require adding additional parameter to the redirection request, where the customer will be Re-directed to a standalone installments page.
Standalone Installments Redirection Service - Request
Include the following parameters in the Purchase - Request Parameters you will send to Amazon Payment Services:
$requestParams = array(
'command' => 'PURCHASE',
'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',
'installments' => 'STANDALONE
);
$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' => 'PURCHASE',
'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',
'installments' => 'STANDALONE
};
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' => 'PURCHASE',
'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',
'installments' => 'STANDALONE
};
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>";
String jsonRequestString = "{\n “command“ => “PURCHASE”,\n”access_code” => “zx0IPmPy5jp1vAz8Kpg7”,\n”merchant_identifier” => “CycHZxVj”,\n”merchant_reference” => “XYZ9239-yu898”,\n”amount” => “10000”,\n”currency” => “AED”,\n”language” => “en”,\n”customer_email” => “test@payfort.com”,\n”signature” => “7cad05f0212ed933c9a5d5dffa31661acf2c827a”,\n”order_description” => “iPhone 6-S”,\n”installments” => “STANDALONE\n);
}";
// 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());
{
"command": "PURCHASE",
"access_code": "XXXX",
"merchant_identifier": "XXXX",
"merchant_reference": "XXXXX-XXXXX",
"amount": "100",
"currency": "SAR",
"language": "en",
"customer_email": test@merchantdomain.com,
"order_description": "iPhone12",
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'installments' => 'STANDALONE
}
ATTRIBUTES | Description |
---|---|
installments Alpha Optional max: 10 |
Used to specify the type of the Installments service. Possible/ expected values: STANDALONE |
Standalone Installments Redirection Service - Response
The following parameters will be returned in Amazon Payment Services’ response in addition to the Purchase - Response Parameters:
ATTRIBUTES | Description |
---|---|
installments Alpha max: 10 |
Used to specify the type of the Installments service. Possible/ expected values: STANDALONE |
number_of_installments Numeric max: 2 |
The number of installments the customer has selected in the payment page. Example: 3 |
Installments Redirection Service - Sample Request:
Installments and Standard Merchant Page Integration (Iframe)
Installments and Standard Merchant Page Integration Service - Request
Include the following parameters in the Request Parameters you will send to Amazon Payment Services:
$requestParams = array(
'command' => 'PURCHASE',
'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',
'installments' => 'STANDALONE
);
$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' => 'PURCHASE',
'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',
'installments' => 'STANDALONE
};
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' => 'PURCHASE',
'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',
'installments' => 'STANDALONE
};
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>";
String jsonRequestString = "{\n “command“ => “PURCHASE”,\n”access_code” => “zx0IPmPy5jp1vAz8Kpg7”,\n”merchant_identifier” => “CycHZxVj”,\n”merchant_reference” => “XYZ9239-yu898”,\n”amount” => “10000”,\n”currency” => “AED”,\n”language” => “en”,\n”customer_email” => “test@payfort.com”,\n”signature” => “7cad05f0212ed933c9a5d5dffa31661acf2c827a”,\n”order_description” => “iPhone 6-S”,\n”installments” => “STANDALONE\n);
}";
// 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());
{
"command": "PURCHASE",
"access_code": "XXXX",
"merchant_identifier": "XXXX",
"merchant_reference": "XXXXX-XXXXX",
"amount": "100",
"currency": "SAR",
"language": "en",
"customer_email": test@merchantdomain.com,
"order_description": "iPhone12",
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'installments' => 'STANDALONE
}
ATTRIBUTES | Description |
---|---|
installments Alpha Mandatory max: 10 |
Used to specify the type of the Installments service. Possible/ expected values: STANDALONE |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: USD |
customer_country_code Alpha Optional Max: 3 |
The Customer’s country code. ISO 3 digit country code. Example: JOR |
Installments and Standard Merchant Page Integration - Response
The following parameters will be returned in Amazon Payment Services’ response in addition to the Merchant Page - Response Parameters:
ATTRIBUTES | Description |
---|---|
installments Alpha max: 10 |
Used to specify the type of the Installments service. Possible/ expected values: STANDALONE |
amount Numeric Max: 10 |
The transaction’s amount. Example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: USD |
customer_country_code Alpha Max: 3 |
The Customer’s country code. ISO 3-digit country code. Example: JOR |
number_of_installments Numeric Max: 2 |
The number of installments the customer has selected in payment page. Example: 3 |
plan_code Alphanumeric Max: 8 |
A code that refers to the “installments plan” the customer selected from the merchant page. Example: NNNN89JJ |
issuer_code Alphanumeric Max: 8 |
A code that refers to the “card issuer” the customer selected from the merchant page. Example: 12HP34SE |
Installments and Standard Merchant Page Integration Service - Sample Request
Installments Purchase Service - Request
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'command' => 'PURCHASE',
'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',
'installments' : 'STANDALONE,
'card_security_code':'123',
'plan_code':'yNW32L',
'issuer_code':'Xylg7w',
'customer_ip':'192.178.1.10'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command' : 'PURCHASE',
'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',
'installments' : 'STANDALONE,
'card_security_code':'123',
'plan_code':'yNW32L',
'issuer_code':'Xylg7w',
'customer_ip':'192.178.1.10'
};
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' => 'PURCHASE',
'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',
'card_security_code'=>'123',
'installments'=>'STANDALONE',
'plan_code'=>'yNW32L',
'issuer_code'=>'Xylg7w',
'customer_ip'=>'192.178.1.10'
};
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)
String jsonRequestString = "{\n \"command\": \"PURCHASE\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"Test-10060\",\n \"amount\": \"200000\",\n \"currency\": \"AED\",\n \"language\": \"en\",\n \"customer_email\": \"test@payfort.com\",\n \"signature\": \"fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b\",\n \"token_name\": \"f90c5a2a0355448bbf9f87696671c318\",\n \"card_security_code\":\"123\",\n \"installments\":\"STANDALONE\",\n \"plan_code\":\"yNW32L\",\n \"issuer_code\":\"Xylg7w\",\n \"customer_ip\":\"192.178.1.10\"\n\n}";
// 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());
{
"command": "PURCHASE",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "Test-10060",
"amount": "200000",
"currency": "AED",
"language": "en",
"customer_email": "test@payfort.com",
"signature": "fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b",
"token_name": "f90c5a2a0355448bbf9f87696671c318",
"card_security_code":"123",
"installments":"STANDALONE",
"plan_code":"yNW32L",
"issuer_code":"Xylg7w",
"customer_ip":"192.178.1.10"
}
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:
{
"query_command": "GET_INSTALLMENTS_PLANS",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"amount": "100000",
"currency": "AED",
"language": "en",
"signature": "{{signature}}"
}
String jsonRequestString = "{\n \"query_command\": \"GET_INSTALLMENTS_PLANS\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"amount\": \"100000\",\n \"currency\": \"AED\",\n \"language\": \"en\",\n \"signature\": \"fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b\"\n}"
// 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());
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'query_command'=> 'GET_INSTALLMENTS_PLANS',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'amount'=> '100000',
'currency'=> 'AED',
'language'=> 'en',
'signature'=> '{{signature}}'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData =
{
'query_command' : 'GET_INSTALLMENTS_PLANS',
'access_code: '{{access_code}}',
'merchant_identifier: '{{merchant_identifier}}',
'amount: '100000',
'currency: 'AED',
'language: 'en',
'signature: '{{signature}}'
};
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'=> 'GET_INSTALLMENTS_PLANS',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'amount'=> '100000',
'currency'=> 'AED',
'language'=> 'en',
'signature'=> '{{signature}}'
};
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)
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 |
<FORM METHOD=“post” ACTION=“https://sbcheckout.payfort.com/FortAPI/paymentPage” id=form1 name=form1>
<INPUT type=“hidden” NAME=“service_command” value=“TOKENIZATION”>
<INPUT type=“hidden” NAME=“language” value=“en”>
<INPUT type=“hidden” NAME=“merchant_identifier” value=“bxgOIxIz”>
<INPUT type=“hidden” NAME=“access_code” value=“Ru8n1ciSJXWm8WFHLKsR”>
<INPUT type=“hidden” NAME=“signature” value=“fc64e90143bb6fb5c8a3f916a3593c756b691fa5f”>
<INPUT type=“hidden” NAME=“merchant_reference” value=“test”>
<INPUT type=“hidden” NAME=“card_number” value=“4546830000000003”>
<INPUT type=“hidden” NAME=“expiry_date” value=“2505”>
<INPUT type=“hidden” NAME=“card_security_code” value=“123”>
<INPUT type=“hidden” NAME=“card_holder_name” value=“testuser”>
<INPUT type=“submit” value=“” id=“submit2” name=“”>
</FORM>
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:
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'command' => 'PURCHASE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
'customer_email' => 'test@payfort.com',
'signature' => 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b',
'token_name' => '7288fc8155014c57ad809d8e9574575e'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command':'PURCHASE',
'access_code':'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier':'CycHZxVj',
'merchant_reference':'XYZ9239-yu898',
'language':'en',
'signature':'7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description':'iPhone 6-S',
'customer_email':'test@payfort.com',
'signature' : 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b',
'token_name' : '7288fc8155014c57ad809d8e9574575e'
};
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' => 'PURCHASE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
'customer_email => 'test@payfort.com',
'signature' => 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b',
'token_name' => '7288fc8155014c57ad809d8e9574575e'
};
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)
String jsonRequestString = "{\n \"command\": \"PURCHASE\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"Abhitest-10052\",\n \"amount\": \"20000\",\n \"currency\": \"AED\",\n \"language\": \"en\",\n \"customer_email\": \"test@payfort.com\",\n \"signature\": \"fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b\",\n \"token_name\": \"7288fc8155014c57ad809d8e9574575e\"\n}";
// 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());
{
"command": "PURCHASE",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "Abhitest-10052",
"amount": "20000",
"currency": "AED",
"language": "en",
"customer_email": "test@payfort.com",
"signature": "fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b",
"token_name": "7288fc8155014c57ad809d8e9574575e"
}
ATTRIBUTES | Description |
---|---|
command Alpha Mandatory max: 20 |
Command. Possible/ expected values: PURCHASE |
access_code Alphanumeric Mandatory Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Mandatory Max: 254 |
The customer’s email. Example: customer@domain.com Special characters: _ - . @ + |
token_name Alphanumeric Mandatory Max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp Special characters: _ - . @ |
installments Alpha Mandatory Max: 10 |
Used to specify the type of the Installments service. Possible/ expected values: HOSTED |
issuer_code Alphanumeric Mandatory Max: 8 |
A code that refers to the “card issuer” the customer selected from the merchant page. Example: 12HP34SE |
plan_code Alphanumeric Mandatory Max: 8 |
A code that refers to the “installments plan” the customer selected from the merchant page. Example: NNNN89JJ |
customer_ip Alphanumeric Mandatory max: 45 |
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf Special characters: . : |
signature Alphanumeric Mandatory Max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
payment_option Alpha Optional Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX |
eci Alpha Optional Max: 16 |
Ecommerce indicator. Possible/ expected values: ECOMMERCE |
order_description Alphanumeric Optional Max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
card_security_code Numeric Optional Max: 4 |
A security code for the card. * Only AMEX accepts card security code of 4 digits. Example: 123 |
customer_name Alpha Optional Max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' Space |
merchant_extra Alphanumeric Optional Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra1 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra2 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra3 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra4 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra5 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
remember_me Alpha Optional Max: 3 |
This parameter provides you with an indication to whether to save this token for the user based on the user selection. *The Tokenization service MUST be activated in order to be able to send “remember_me” parameter. Possible/ expected values: -YES -NO |
phone_number Alphanumeric Optional max: 19 |
The customer’s phone number. Example: 00962797219966 Special characters: + - ( ) Space |
settlement_reference Alphanumeric Optional max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 Special characters: - _ . |
return_url Alphanumeric Optional Max: 400 |
The URL of the Merchant’s page to be displayed to the customer when the order is processed. Example: https://www.merchant.com Special characters: $ ! = ? # & - _ / : . |
billing_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric Optional max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric Optional |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric Optional |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric Optional max: 100 |
The city portion of the address. |
The following parameters will be returned in Amazon Payment Services’ response:
ATTRIBUTES | Description |
---|---|
command Alpha max: 20 |
Command. Possible/ expected values: PURCHASE |
access_code Alphanumeric Max: 20 |
The ID of the Merchant. Example: zx0IPmPy5jp1vAz |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
amount Numeric Max: 10 |
The transaction’s amount. Example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Max: 254 |
The customer’s email. Example: customer1@domain.com |
token_name Alphanumeric max: 100 |
The Token received from the Tokenization process. Example: COp9Vmp |
installments Alpha Max: 10 |
Used to specify the type of the Installments service. Possible/ expected values: HOSTED |
issuer_code Alphanumeric Max: 8 |
A code that refers to the “card issuer” the customer selected from the merchant page. Example: 12HP34SE |
plan_code Alphanumeric Max: 8 |
A code that refers to the “installments plan” the customer selected from the merchant page. Example: NNNN89JJ |
customer_ip Alphanumeric max: 45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf |
signature Alphanumeric Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: d7c185c475ac0e3 |
fort_id Numeric Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
payment_option Alpha Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX |
eci Alpha Max: 16 |
Ecommerce indicator. Possible/ expected values: ECOMMERCE |
order_description Alphanumeric Max: 150 |
It holds the description of the order. Example: iPhone 6-S |
authorization_code Alphanumeric Max: 100 |
The authorization code returned from the 3rd party. Example: P1000000000000372136 |
response_message Alphanumeric Max: 150 |
Message description of the response code. It returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
customer_name Alpha Max: 40 |
The customer’s name. Example: John Smith |
merchant_extra Alphanumeric Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra1 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra2 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra3 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra4 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra5 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
expiry_date Numeric Max: 4 |
The card’s expiry date. Example: 2105 |
card_number Numeric Max: 19 |
The masked credit card’s number. AMEX payment option takes 15 digits card number. *Otherwise, they take 16 digits card number. Example: 400555*****0001 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
card_holder_name Alpha Max: 50 |
The card holder name. Example: John Smith |
3ds_url Alphanumeric Max: 300 |
The URL where the Merchant redirects a customer whose card is 3D Secure for authentication. Example: https://www.3dsecure.com |
remember_me Alpha Max: 3 |
This parameter provides you with an indication to whether to save this token for the user based on the user selection. Possible/ expected values: - YES - NO |
phone_number Alphanumeric max: 19 |
The customer’s phone number. Example: 00962797219966 |
settlement_reference Alphanumeric max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 |
billing_stateProvince Alphanumeric max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric max: 100 |
The city portion of the address. |
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:
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'command' => 'PURCHASE',
'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',
'card_security_code'=>'123',
'installments'=>'HOSTED',
'plan_code'=>'yNW32L',
'issuer_code'=>'Xylg7w',
'customer_ip'=>'192.178.1.10'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command' : 'PURCHASE',
'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',
'card_security_code':'123',
'installments':'HOSTED',
'plan_code':'yNW32L',
'issuer_code':'Xylg7w',
'customer_ip'=>'192.178.1.10'
};
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' : 'PURCHASE',
'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',
'card_security_code':'123',
'installments':'HOSTED',
'plan_code':'yNW32L',
'issuer_code':'Xylg7w',
'customer_ip':'192.178.1.10'
};
arrData.each {|key, value|
puts key +value ;
}
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)
String jsonRequestString = "{\n \"command\": \"PURCHASE\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"Test-10060\",\n \"amount\": \"200000\",\n \"currency\": \"AED\",\n \"language\": \"en\",\n \"customer_email\": \"test@payfort.com\",\n \"signature\": \"fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b\",\n \"token_name\": \"f90c5a2a0355448bbf9f87696671c318\",\n \"card_security_code\":\"123\",\n \"installments\":\"HOSTED\",\n \"plan_code\":\"yNW32L\",\n \"issuer_code\":\"Xylg7w\",\n \"customer_ip\":\"192.178.1.10\"\n\n}";
// 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());
{
"command": "PURCHASE",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "Test-10060",
"amount": "200000",
"currency": "AED",
"language": "en",
"customer_email": "test@payfort.com",
"signature": "fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b",
"token_name": "f90c5a2a0355448bbf9f87696671c318",
"card_security_code":"123",
"installments":"HOSTED",
"plan_code":"yNW32L",
"issuer_code":"Xylg7w",
"customer_ip":"192.178.1.10"
}
ATTRIBUTES | Description |
---|---|
installments Alpha Mandatory Max: 10 |
Used to specify the type of the Installments service. Possible/ expected values: HOSTED |
issuer_code Alphanumeric Mandatory Max: 8 |
A code that refers to the “card issuer” the customer selected from the merchant page. Example: 12HP34SE |
plan_code Alphanumeric Mandatory Max: 8 |
A code that refers to the “installments plan” the customer selected from the merchant page. Example: NNNN89JJ |
Installments Hosted for Trusted – Response
The following parameters will be returned in Amazon Payment Services’ response in addition to Trusted Channel – Response parameters:
ATTRIBUTES | Description |
---|---|
installments Alpha Max: 10 |
Used to specify the type of the Installments service. Possible/ expected values: HOSTED |
issuer_code Alphanumeric Max: 8 |
A code that refers to the “card issuer” the customer selected from the merchant page. Example: 12HP34SE |
plan_code Alphanumeric Max: 8 |
A code that refers to the “installments plan” the customer selected from the merchant page. Example: NNNN89JJ |
Installments Standard Merchant Page Integration - Style Sheet
This is a list with all customizable CSS classes when you use Installments via the standard Merchant Page:
- The
installments-container
class: responsible for the total width of the form container and the background. - The
receipt-container
class: responsible for the receipt section you can customize / hide it by changing the CSS values - The
full-width
class: responsible for the plans and switching the view from dropdown to a table. - The
credit-card-container
class: responsible for the credit card form`s shape look. - The
error
class: responsible for the error messages. - The
half1, half2
class: used to merge the date and CVV fields into one block or each one on block if needed. - The
bank
class: is responsible for the bank agreement section. - The
floatl
class: is the container of each single input field. - The
Pay
class: responsible for the submit button. - The
Visa/ MasterCard
classes: used to change the color of the Visa/ MasterCard colors.
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:
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'command' => 'PURCHASE',
'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',
'card_security_code'=>'123',
'installments'=>'MOTO',
'plan_code'=>'yNW32L',
'issuer_code'=>'Xylg7w',
'customer_ip'=>'192.178.1.10'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command' : 'PURCHASE',
'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',
'card_security_code':'123',
'installments':'MOTO',
'plan_code':'yNW32L',
'issuer_code':'Xylg7w',
'customer_ip'=>'192.178.1.10'
};
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' : 'PURCHASE',
'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',
'card_security_code':'123',
'installments':'MOTO',
'plan_code':'yNW32L',
'issuer_code':'Xylg7w',
'customer_ip':'192.178.1.10'
};
arrData.each {|key, value|
puts key +value ;
}
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)
String jsonRequestString = "{\n \"command\": \"PURCHASE\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"Test-10060\",\n \"amount\": \"200000\",\n \"currency\": \"AED\",\n \"language\": \"en\",\n \"customer_email\": \"test@payfort.com\",\n \"signature\": \"fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b\",\n \"token_name\": \"f90c5a2a0355448bbf9f87696671c318\",\n \"card_security_code\":\"123\",\n \"installments\":\"MOTO\",\n \"plan_code\":\"yNW32L\",\n \"issuer_code\":\"Xylg7w\",\n \"customer_ip\":\"192.178.1.10\"\n\n}";
// 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());
{
"command": "PURCHASE",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "Test-10060",
"amount": "200000",
"currency": "AED",
"language": "en",
"customer_email": "test@payfort.com",
"signature": "fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b",
"token_name": "f90c5a2a0355448bbf9f87696671c318",
"card_security_code":"123",
"installments":"MOTO",
"plan_code":"yNW32L",
"issuer_code":"Xylg7w",
"customer_ip":"192.178.1.10"
}
ATTRIBUTES | Description |
---|---|
command Alpha Mandatory max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
access_code Alphanumeric Mandatory max: 20 |
Access code. Example: zx0IPmPy5jp1vAz |
merchant_identifier Alphanumeric Mandatory max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory max: 2 |
The checkout page and messages language. Possible/ expected values: en / ar |
customer_email Alphanumeric Mandatory max: 254 |
The customer’s email. Example: customer@domain.com Special characters: _ - . @ + |
eci Alpha Mandatory max: 16 |
Ecommerce indicator. Possible/ expected values: MOTO |
token_name Alphanumeric Mandatory max: 100 |
The token received from the Tokenization process. Example: Op9Vmp Special characters: _ - . @ |
signature Alphanumeric Mandatory max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
payment_option Alpha Optional max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX |
order_description Alphanumeric Optional max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
customer_ip Alphanumeric Mandatory max: 45 |
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf Special characters: . : |
customer_name Alpha Optional max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' Space |
phone_number Alphanumeric Optional max: 19 |
The customer’s phone number. Example: 00962797219966 Special characters: + - ( ) Space |
settlement_reference Alphanumeric Optional max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 Special characters: - _ . |
merchant_extra Alphanumeric Optional Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra1 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra2 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra3 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra4 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra5 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
return_url Alphanumeric Optional max: 400 |
The URL of the Merchant’s page to be redirected to when the order is processed. Example: https://www.merchant.com Special characters: $ ! = ? # & - _ / : . |
Redirection / Merchant Page integration :
{
"command": "AUTHORIZATION",
"access_code": "E8OHT1raKV9pdPBMishi",
"merchant_identifier": "XMWzLQPu",
"merchant_reference": "merchantTest-10131",
"amount": "20000",
"currency": "AED",
"language": "en",
"customer_email": "test@merchantdomain.com",
"signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a'",
"eci":"MOTO",
"token_name":"abcdefgh12345678"
}
Trusted integration :
{
"command": "PURCHASE",
"access_code": "E8OHT1raKV9pdPBMishi",
"merchant_identifier": "XMWzLQPu",
"merchant_reference": "merchantTest-10131",
"amount": "20000",
"currency": "AED",
"language": "en",
"customer_email": "test@merchantdomain.com",
"signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a'",
"eci":"MOTO",
"expiry_date":,
"token_name":"abcdefgh12345678"
}
MOTO Channel - MOTO Response
The following parameters will be returned in Amazon Payment Services’ response:
ATTRIBUTES | Description |
---|---|
command Alpha max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
access_code Alphanumeric max: 20 |
Access code. Example: zx0IPmPy5jp1vAz |
merchant_identifier Alphanumeric max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
amount Numeric max: 10 |
The transaction’s amount. Example: 10000 |
currency Alpha max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha max: 2 |
The checkout page and messages language. Possible/ expected values: en / ar |
customer_email Alphanumeric max: 254 |
The customer’s email. Example: customer@domain.com |
eci Alpha max: 16 |
Ecommerce indicator. Possible/ expected values: MOTO |
token_name Alphanumeric max: 100 |
The token received from the Tokenization process. Example: Op9Vmp |
signature Alphanumeric max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
fort_id Numeric max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
payment_option Alpha max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX |
order_description Alphanumeric max: 150 |
It holds the description of the order. Example: iPhone 6-S |
customer_ip Alphanumeric max: 45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf |
customer_name Alpha max: 40 |
The customer’s name. Example: John Smith |
authorization_code Alphanumeric max: 100 |
The authorization code returned from the 3rd party. Example: P1000000000000372136 |
response_message Alphanumeric max: 150 |
Message description of the response code. It returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
status Numeric max: 2 |
A two-digit numeric value that indicates the status of the transaction Possible/ expected values: (Please refer to section statuses). |
expiry_date Numeric max: 4 |
The card’s expiry date. Example: 2105 |
card_number Numeric max: 16 |
The card’s number masked based on a certain standard that is selected in the technical settings. Example: 400555******0001 |
phone_number Alphanumeric max: 19 |
The customer’s phone number. Example: 00962797219966 |
settlement_reference Alphanumeric max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 |
merchant_extra Alphanumeric Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra1 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra2 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra3 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra4 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra5 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
return_url Alphanumeric max: 400 |
The URL of the Merchant’s page to be redirected to when the order is processed. Example: https://www.merchant.com |
Trusted Channel
If you are a PCI-certified merchant you can collect your customers’ credit card details on your checkout page and store the sensitive payment card data on your server. Read more about PCI compliance here.
PCI-compliant merchants can use the Amazon Payment Services trusted channel to submit payment card details so that Amazon Payment Services can execute transactions using the payment card data. Trusted Channel URLs.
Pre requisite
Trusted integration type is allowed only for the merchants who are PCI compliant , once a merchant requests to integrate with trusted integration type , the Merchant should share the PCI certificate (Payment Card Industry certificate) as well the AOC (Attestation of Compliance for onsite assessments), this in order for APS Infosec to validate certificate and confirm the merchant is eligible to collecting card details .
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:
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'command' => 'PURCHASE',
'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',
'card_security_code'=>'123',
'plan_code'=>'yNW32L',
'eci'=> 'ECOMMERCE',
'issuer_code'=>'Xylg7w',
'customer_ip'=>'192.178.1.10'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command' : 'PURCHASE',
'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',
'card_security_code':'123',
'plan_code':'yNW32L',
'issuer_code':'Xylg7w',
'eci': 'ECOMMERCE',
'customer_ip':'192.178.1.10'
};
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' => 'PURCHASE',
'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',
'card_security_code'=>'123',
'plan_code'=>'yNW32L',
'issuer_code'=>'Xylg7w',
'eci'=> 'ECOMMERCE',
'customer_ip'=>'192.178.1.10'
};
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)
String jsonRequestString = "{\n \"command\": \"PURCHASE\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"Test-10060\",\n \"amount\": \"200000\",\n \"eci\": \"ECOMMERCE\",\n \"currency\": \"AED\",\n \"language\": \"en\",\n \"customer_email\": \"test@payfort.com\",\n \"signature\": \"fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b\",\n \"token_name\": \"f90c5a2a0355448bbf9f87696671c318\",\n \"card_security_code\":\"123\",\n \"installments\":\"HOSTED\",\n \"plan_code\":\"yNW32L\",\n \"issuer_code\":\"Xylg7w\",\n \"customer_ip\":\"192.178.1.10\"\n\n}";
// 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());
{
"command": "PURCHASE",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "Test-10060",
"amount": "200000",
"currency": "AED",
"language": "en",
"customer_email": "test@payfort.com",
"signature": "fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b",
"token_name": "f90c5a2a0355448bbf9f87696671c318",
"card_security_code":"123",
"plan_code":"yNW32L",
"issuer_code":"Xylg7w",
"customer_ip":"192.178.1.10",
"eci": "ECOMMERCE",
}
ATTRIBUTES | Description |
---|---|
command Alpha Mandatory max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
access_code Alphanumeric Mandatory max: 20 |
Access code. Example: zx0IPmPy5jp1vAz |
merchant_identifier Alphanumeric Mandatory max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory max: 2 |
The checkout page and messages language. Possible/ expected values: en / ar |
customer_email Alphanumeric Mandatory max: 254 |
The customer’s email. Example: customer@domain.com Special characters: _ - . @ + |
eci Alpha Mandatory max: 16 |
Ecommerce indicator. Possible/ expected values: - MOTO - RECURRING - ECOMMERCE |
expiry_date Numeric Mandatory max: 4 |
The card’s expiry date. Example: 2105 |
card_number Numeric Mandatory max: 19 |
The clear credit card’s number. *Only the MEEZA payment option takes 19 digits card number. *AMEX payment option takes 15 digits card number. *Otherwise, they take 16 digits card number. Example: 4005550000000001 |
card_security_code Numeric max: 4 |
The clear card security code collect on the merchant’s checkout page. *It’s ONLY mandatory in the ecommerce requests. * Only AMEX accepts card security code of 4 digits. Example: 123 |
customer_ip Alphanumeric Mandatory max: 45 |
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf Special characters: . : |
signature Alphanumeric Mandatory max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
card_holder_name Alpha Optional max: 50 |
The card holder name. Example: John Smith Special characters: ' - . |
token_name Alphanumeric Optional Max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp Special characters: . @ - _ |
payment_option Alpha Optional max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) |
order_description Alphanumeric Optional max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
customer_name Alpha Optional max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' Space |
phone_number Alphanumeric Optional max: 19 |
The customer’s phone number. Example: 00962797219966 Special characters: + - ( ) Space |
settlement_reference Alphanumeric Optional max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 Special characters: - _ . |
merchant_extra Alphanumeric Optional Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra1 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra2 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra3 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra4 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra5 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
return_url Alphanumeric Optional max: 400 |
The URL of the Merchant’s page to be redirected to when the order is processed. Example: https://www.merchant.com Special characters: $ ! = ? # & - _ / : . |
billing_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric Optional max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric Optional |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric Optional |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric Optional max: 100 |
The city portion of the address. |
agreement_id Alphanumeric Optional max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
recurring_mode Alphanumeric Optional max: 20 |
Indicates if the subsequent payments within the agreement has same/different amount or unscheduled (unknown interval/amount). Possible/ expected values: UNSCHEDULED, VARIABLE, FIXED |
recurring_transactions_count Alphanumeric Optional max: 100 |
The number of merchant-initiated payments within the recurring payment agreement. ( Required only if recurring_mode = VARIABLE or FIXED ) |
recurring_expiry_date |
The date where the merchant needs to end the recurring. The format is YY-MM-DD [Numeric] with special character - |
recurring_days_between_payments |
The number of days between payments agreed with the payer under your agreement with them. The allowed data type is: Numeric only. |
Trusted Channel - Response
Include the following parameters in the Request you will send to Amazon Payment Services:
ATTRIBUTES | Description |
---|---|
command Alpha max: 20 |
Command. expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
access_code Alphanumeric max: 20 |
Access code. Example: zx0IPmPy5jp1vAz |
merchant_identifier Alphanumeric max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
amount Numeric max: 10 |
The transaction’s amount. Example: 10000 |
currency Alpha max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha max: 2 |
The checkout page and messages language. Possible/ expected values: en / ar |
customer_email Alphanumeric max: 254 |
The customer’s email. Example: customer@domain.com |
eci Alpha max: 16 |
Ecommerce indicator. Possible/ expected values: - MOTO - RECURRING - ECOMMERCE |
expiry_date Numeric max: 4 |
The card’s expiry date. Example: 2105 |
card_number Numeric max: 16 |
The masked credit card’s number. Only the MEEZA payment option takes 19 digits card number. *AMEX payment option takes 15 digits card number. *Otherwise, they take 16 digits card number. Example: 400555*****0001 |
customer_ip Alphanumeric max: 45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf |
signature Alphanumeric max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
card_holder_name Alpha Max: 50 |
The card holder name. Example: John Smith |
token_name Alphanumeric max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp |
fort_id Numeric max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
payment_option Alpha max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) |
order_description Alphanumeric max: 150 |
It holds the description of the order. Example: iPhone 6-S |
customer_name Alpha max: 40 |
The customer’s name. Example: John Smith |
merchant_extra Alphanumeric Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra1 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra2 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra3 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra4 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra5 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
authorization_code Alphanumeric max: 100 |
The authorization code returned from the 3rd party. Example: P1000000000000372136 |
response_message Alphanumeric max: 150 |
Message description of the response code. It returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
status Numeric max: 2 |
A two-digit numeric value that indicates the status of the transaction Possible/ expected values: (Please refer to section statuses). |
3ds_url Alphanumeric Max: 300 |
The URL where the Merchant redirects a customer whose card is 3D Secure for authentication. Example: https://www.3dsecure.com |
phone_number Alphanumeric max: 19 |
The customer’s phone number. Example: 00962797219966 |
settlement_reference Alphanumeric max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 |
billing_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric Optional max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric Optional |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric Optional |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric Optional max: 100 |
The city portion of the address. |
agreement_id Alphanumeric max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
APS Validation JS
(function( $ ) { 'use strict'; /** * All of the code for your checkout functionality placed here. * should reside in this file. */ /** * Sandbox Url - /sbcheckout.payfort.com/ * Production Url - /checkout.payfort.com/ */ const formElement = $( 'form' ).filter( function(){ return this.action.match(/sbcheckout.payfort.com/i); }); /** * MADA bins are applicable only for KSA based payments. * MEEZA bins are applicable only for Egypt based payments. * */ const bins = { mada : '446404|440795|440647|421141|474491|588845|968208|457997|457865|468540|468541|468542|468543|417633|446393|636120|968201|410621|409201|403024|458456|462220|968205|455708|484783|588848|455036|968203|486094|486095|486096|504300|440533|489318|489319|445564|968211|410685|406996|432328|428671|428672|428673|968206|446672|543357|434107|407197|407395|42689700|412565|431361|604906|521076|588850|968202|529415|535825|543085|524130|554180|549760|968209|524514|529741|537767|535989|536023|513213|442463|520058|558563|605141|968204|422817|422818|422819|410834|428331|483010|483011|483012|589206|968207|406136|419593|439954|407520|530060|531196|420132|242030|22402030', meeza : '507803[0-6][0-9]|507808[3-9][0-9]|507809[0-9][0-9]|507810[0-2][0-9]', } const apsPaymentErrors = { invalid_card: 'Invalid Card', invalid_card_length: 'Invalid Card Length', card_empty: 'Card Number Empty', invalid_card_holder_name: 'Invalid Card Holder Name', invalid_card_cvv: 'Invalid Card CVV', invalid_expiry_date: 'Invalid Expiry Date', invalid_expiry_year : 'Invalid Expiry Year. Expected as YYMM', invalid_expiry_month : 'Invalid Expiry Month. Expected as YYMM' }; const cardNumberSelector = '[name=\'card_number\']'; const cardHolderSelector = '[name=\'card_holder_name\']'; const expirySelector = '[name=\'expiry_date\']'; //Validation control let APSValidation = { validateCard: function (card_number) { let card_type = ""; let card_validity = true; let message = ''; let card_length = 0; if (card_number) { card_number = card_number.replace(/ /g, '').replace(/-/g, ''); // Visa let visa_regex = new RegExp('^4[0-9]{0,15}$'); // MasterCard let mastercard_regex = new RegExp('^5$|^5[0-5][0-9]{0,16}$'); // American Express let amex_regex = new RegExp('^3$|^3[47][0-9]{0,13}$'); //mada let mada_regex = new RegExp('^' + bins.mada); //meeza let meeza_regex = new RegExp(bins.meeza, 'gm'); if (card_number.match(mada_regex)) { card_type = 'mada'; card_length = 16; } else if (card_number.match(meeza_regex)) { card_type = 'meeza'; card_length = 19; } else if (card_number.match(visa_regex)) { card_type = 'visa'; card_length = 16; } else if (card_number.match(mastercard_regex)) { card_type = 'mastercard'; card_length = 16; } else if (card_number.match(amex_regex)) { card_type = 'amex'; card_length = 15; } else { card_validity = false; message = apsPaymentErrors.invalid_card; } if (card_number.length < 15) { card_validity = false; message = apsPaymentErrors.invalid_card_length; } else { let cardValidByAlgorithm = APSValidation.validateCardNumber(card_number); if (!cardValidByAlgorithm) { card_validity = false; message = apsPaymentErrors.invalid_card; } } } else { message = apsPaymentErrors.card_empty; card_validity = false; } return { card_type, validity: card_validity, msg: message, card_length } }, validateCardNumberByAlgorithm : function (card_number){ let checksum = 0; // running checksum total let j = 1; // takes value of 1 or 2 // Process each digit one by one starting from the last for (let i = card_number.length - 1; i >= 0; i--) { let calc = 0; // Extract the next digit and multiply by 1 or 2 on alternative digits. calc = Number(card_number.charAt(i)) * j; // If the result is in two digits add 1 to the checksum total if (calc > 9) { checksum = checksum + 1; calc = calc - 10; } // Add the units element to the checksum total checksum = checksum + calc; // Switch the value of j if (j === 1) { j = 2; } else { j = 1; } } //Check if it is divisible by 10 or not. return (checksum % 10) === 0; }, validateCardNumber : function (card_number){ //Check if the number contains only numeric value //and is of between 13 to 19 digits const regex = new RegExp("^[0-9]{13,19}$"); if (!regex.test(card_number)){ return false; } return APSValidation.validateCardNumberByAlgorithm(card_number); }, validateHolderName: function (card_holder_name) { let validity = true; let message = ''; card_holder_name = card_holder_name.trim(); if (card_holder_name.length > 51 || card_holder_name.length === 0) { validity = false; message = apsPaymentErrors.invalid_card_holder_name; } const regex = new RegExp("^[a-zA-Z- '.]+$"); if (!regex.test(card_number)){ return false; } return { validity, msg: message } }, validateCVV: function (card_cvv, card_type) { let validity = false; let message = apsPaymentErrors.invalid_card_cvv; if (card_cvv.length > 0) { card_cvv = card_cvv.trim(); if (!card_type.length || card_type.length === 0) { if (card_cvv.length === 3 && card_cvv !== '000') { validity = true; message = ''; } else if (card_cvv.length === 4 && card_type === 'amex' && card_cvv !== '0000') { validity = true; message = ''; } } } return { validity, msg: message } }, validateCardExpiry: function (card_expiry_month, card_expiry_year) { let validity = true; let message = ''; if (card_expiry_month === '' || !card_expiry_month) { validity = false; message = apsPaymentErrors.invalid_expiry_month; } else if (card_expiry_year === '' || !card_expiry_year) { validity = false; message = apsPaymentErrors.invalid_expiry_year; } else if (parseInt(card_expiry_month) <= 0 || parseInt(card_expiry_month) > 12) { validity = false; message = apsPaymentErrors.invalid_expiry_month; } else { let cur_date, exp_date; card_expiry_month = ('0' + parseInt(card_expiry_month - 1)).slice(-2); cur_date = new Date(); exp_date = new Date(parseInt('20' + card_expiry_year), card_expiry_month, 30); if (exp_date.getTime() < cur_date.getTime()) { message = apsPaymentErrors.invalid_expiry_date; validity = false; } } return { validity, msg: message } } }; //Defining of payment functions let apsPayment = { validatePayment: function ( ) { let status = true; let payment_box = formElement; let card_value = payment_box.find( "[name=\'card_number\']" ).val(); let holdername_value = payment_box.find( "[name=\'card_holder_name\']" ).val(); let cvv_value = payment_box.find( "[name=\'card_security_code\']" ).val(); let expiry = payment_box.find( "[name=\'expiry_date\']" ).val(); let expiry_year = expiry.substring(0, 2); let expiry_month = expiry.substring(2, 4); let validateCard = APSValidation.validateCard( card_value ); let validateHolderName = APSValidation.validateHolderName( holdername_value ); let validateCardCVV = APSValidation.validateCVV( cvv_value, validateCard.card_type); let validateExpiry = APSValidation.validateCardExpiry( expiry_month, expiry_year ); let message; if ( validateCard.validity === false ) { message = validateCard.msg; status = false; } if ( validateHolderName.validity === false ) { message = validateHolderName.msg; status = false; } if ( validateCardCVV.validity === false ) { message = validateCardCVV.msg; status = false; } if ( validateExpiry.validity === false ) { message = validateExpiry.msg; status = false; } return status; }, parseExpiry : function( monthYear ){ } }; formElement.on( 'submit', function(e) { return apsPayment.validatePayment(); } ); })( jQuery );
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.
For example: If the amount value was 500 AED; according to ISO code 3, you should multiply the value with 100 (2 decimal points); so it will be sent in the request as 50000.
Another example: If the amount value was 100 JOD; according to ISO code 3, you should multiply the value with 1000 (3 decimal points); so it will be sent in the request as 100000.
* If your currency has three decimal code according to ISO code 3 , Please be advised that VISA transactions for the 3 decimal point currencies must be rounded to zero (0). Transactions with decimals other than zero (0) will be declined. For example, if the amount is 3.475, it needs to be rounded to the nearest integer with the last decimal digit set to zero, resulting in 3480. This adjusted amount should then be included in the API request submitted to APS.
ValU Consumer Finance
ValU consumer finance is a simple and secure financing platform where your customers can do online purchases on short-term financing and repay the amount based on specific installment plans at an interest rate offered by the financing company. For now, we have partnered with ValU in Egypt to offer consumer financing services.
Before Starting
Before you start, remember:
- Your customer should be registered with ValU in order to have this benefit of installments.
- You should have a valid SHA signature, to configure signatures, refer Signature and Signature Calculation Tool.
- To fetch your merchant reference and merchant access code, go to Merchant Management, search and select the test merchant account and click Security Settings.
OTP Generate
This request to generate an OTP for the customer, where the customer should fill down his phone number in the merchant’s check-out page. ValU will generate the OTP code and send it to customer as SMS.
Purchase
This request allows the customer to purchase his selected items. https://paymentservices.payfort.com/FortAPI/paymentApi
URLs
Test Environment URL: https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production Environment URL: https://paymentservices.payfort.com/FortAPI/paymentApi
OTP Generate
You can now generate an OTP for the customer, where the customer should fill in their phone number in the merchant’s check-out page. ValU will generate the OTP code and send it to customer as SMS.
OTP Generate – Request
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'merchant_reference'=>'TEST-009967',
'merchant_identifier'=>'CycHZxVj',
'access_code'=>'zx0IPmPy5jp1vAz8Kpg7',
'signature'=>'27c1303138f8718e56f311d1b3d823b5a644e6bcd4fac43d5454955b13b5b337',
'service_command'=>'OTP_GENERATE',
'language'=>'en',
'payment_option'=>'VALU',
'phone_number'=>'01220422223',
'amount'=>'100000',
'currency'=>'EGP',
'include_installments'=>'YES',
'wallet_amount'=>'500000',
'cashback_wallet_amount'=>'300000'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'merchant_reference':'TEST-009967',
'merchant_identifier':'CycHZxVj',
'access_code':'zx0IPmPy5jp1vAz8Kpg7',
'signature':'27c1303138f8718e56f311d1b3d823b5a644e6bcd4fac43d5454955b13b5b337',
'service_command':'OTP_GENERATE',
'language':'en',
'payment_option':'VALU',
'phone_number':'01220422223',
'amount':'100000',
'currency':'EGP',
'include_installments':'YES',
'wallet_amount':'500000',
'cashback_wallet_amount':'300000'
};
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 = {
'merchant_reference'=>'TEST-009967',
'merchant_identifier'=>'CycHZxVj',
'access_code'=>'zx0IPmPy5jp1vAz8Kpg7',
'signature'=>'27c1303138f8718e56f311d1b3d823b5a644e6bcd4fac43d5454955b13b5b337',
'service_command'=>'OTP_GENERATE',
'language'=>'en',
'payment_option'=>'VALU',
'phone_number'=>'01220422223',
'amount'=>'100000',
'currency'=>'EGP',
'include_installments'=>'YES',
'wallet_amount'=>'500000',
'cashback_wallet_amount'=>'300000'
};
arrData.each {|key, value|
puts key +value ;
}
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)
String jsonRequestString = "{\n \"merchant_reference\":\"TEST-009967\",\n \"merchant_identifier\":\"CycHZxVj\", \n \"access_code\":\"zx0IPmPy5jp1vAz8Kpg7\",\n \"signature\":\"27c1303138f8718e56f311d1b3d823b5a644e6bcd4fac43d5454955b13b5b337\",\n \"service_command\":\"OTP_GENERATE\",\n \"language\":\"en\",\n \"payment_option\":\"VALU\",\n \"phone_number\":\"01220422223\",\n \"amount\":\"100000\",\n \"currency\":\"EGP\",\n \"include_installments\":\"YES\",\n \"wallet_amount\":\"500000\",\n \"cashback_wallet_amount\":\"300000\"\n}";
// 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());
{
"merchant_reference":"TEST-009967",
"merchant_identifier":"CycHZxVj",
"access_code":"zx0IPmPy5jp1vAz8Kpg7",
"signature":"27c1303138f8718e56f311d1b3d823b5a644e6bcd4fac43d5454955b13b5b337",
"service_command":"OTP_GENERATE",
"language":"en",
"payment_option":"VALU",
"phone_number":"01220422223",
"amount":"100000",
"currency":"EGP",
"include_installments":"YES",
"wallet_amount":"500000",
"cashback_wallet_amount":"300000"
}
OTP Generate Request Parameters
Parameter Name | Description |
---|---|
service_command Alpha Mandatory Max: 20 |
Command. Posssible values: OTP_GENERATE |
access_code Alphanumeric Mandatory Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kp g7 |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. The merchant reference should be the same for all APIs. For example: XYZ9239yu898 |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible values: - en - ar |
payment_option Alpha Mandatory Max: 10 |
Payment option. Possible values: VALU |
include_installments Alpha Optional Max: 3 |
Defines whether the customer can pay in installments. Possible Values YES/NO. Default Value is YES. |
total_downpayment Numeric Optional Max: 100 |
Defines the total down-payment amount payable by the customer. *Decimal values are not accepted. For example:1200 |
phone_number Alphanumeric Mandatory Max: 19 |
The customer’s phone number registered for ValU. For example: 00008557694 |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction amount in ISO code 3. For example: EGP |
signature Alphanumeric Mandatory Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature . For example,7cad05f0212ed933c9a5d5dffa31661acf2c827a |
merchant_extra1 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Special characters.;/_-,’@ For example: JohnSmith |
merchant_extra2 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Special characters.;/_-,’@ JohnSmith |
merchant_extra3 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Special characters.;/_-,’@ For example: JohnSmith |
wallet_amount Numeric Mandatory Max:10 |
Wallet amount or ToU is a gift balance that you can purchase using your valU limit and can pay in flexible installment plans from 6-60 months. You can transfer ToU balance to all of your loved ones, they don’t need to be valU customers. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000 |
cashback_wallet_amount Numeric Mandatory Max:10 |
Amount stored in cashback wallet. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000 |
OTP Generate – Response
Generate Response Example
OTP Generate Response Parameters
Parameter Name | Description |
---|---|
service_command Alpha Max: 20 |
Command. For example: OTP_GENERATE |
access_code Alphanumeric Max: 20 |
Access code. For example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. For example: CycHZxVj |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. For example:XYZ2939-yu898 |
language Alpha Max: 2 |
The checkout page and messages language.For example: - en - ar |
payment_option Alpha 10 |
Payment option. For example:VALU |
phone_number Alphanumeric Max: 19 |
The customer’s phone number registered for ValU. For example: 00008557694 |
merchant_order_id Alphanumeric 100 |
The Merchant’s unique order id. * It should be unique per each transaction and you should use the same merchant_order_id value for all APIs. For example: Valu123 |
amount Numeric Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction amount in ISO code 3. For example:EGP |
total_downpayment Numeric Max: 100 |
Defines the total down-payment amount payable by the customer. For example: 10000 |
installment_detail List |
Defines installment plan details as selected by the customer. This is displayed if include_installments is set to YES. Lists the fee amount, installment amount, installment per month and total installment. |
signature Alphanumeric Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature For example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
merchant_extra1 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. For example: JohnSmith |
merchant_extra2 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. |
merchant_extra3 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. |
response_message Alphanumeric Max: 150 |
Message description of the response code. It returns according to the request language. Please refer to section messages |
response_code Numeric Max: 5 |
Response code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response message. |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction.Please refer to section statuses. |
wallet_amount Numeric Mandatory Max:10 |
Wallet amount or ToU is a gift balance that you can purchase using your valU limit and can pay in flexible installment plans from 6-60 months. You can transfer ToU balance to all of your loved ones, they don’t need to be valU customers. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000 |
cashback_wallet_amount Numeric Mandatory Max:10 |
Amount stored in cashback wallet. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000 |
Purchase
This request allows the Customer to Purchase his selected items through the selected consumer finance.
Purchase – Request
Purchase Request Example
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'merchant_reference'=>'XYZ9239-yu898',
'merchant_identifier'=>'CycHZxVj',
'access_code'=>'zx0IPmPy5jp1vAz8Kpg7',
'signature'=>'b574e362cc08d7504d8277e71400132f06064ee1537cd570717569b583dec0b5',
'command'=>'PURCHASE',
'language'=>'en',
'payment_option'=>'VALU',
'phone_number'=>'00008557694',
'amount'=>'10000',
'currency'=>'EGP',
'customer_email'=>'customer@domain.com',
'otp'=>'123456',
'tenure'=>'6',
'total_down_payment'=>'1200',
'purchase_description'=>'Test',
'wallet_amount'=>'500000',
'cashback_wallet_amount'=>'300000'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'merchant_reference':'XYZ9239-yu898',
'merchant_identifier':'CycHZxVj',
'access_code':'zx0IPmPy5jp1vAz8Kpg7',
'signature':'b574e362cc08d7504d8277e71400132f06064ee1537cd570717569b583dec0b5',
'command':'PURCHASE',
'language':'en',
'payment_option':'VALU',
'phone_number':'00008557694',
'amount':'10000',
'currency':'EGP',
'customer_email':'customer@domain.com',
'otp':'123456',
'tenure':'6',
'total_down_payment':'1200',
'purchase_description':'Test',
'wallet_amount':'500000',
'cashback_wallet_amount':'300000'
};
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 = {
'merchant_reference'=>'XYZ9239-yu898',
'merchant_identifier'=>'CycHZxVj',
'access_code'=>'zx0IPmPy5jp1vAz8Kpg7',
'signature'=>'b574e362cc08d7504d8277e71400132f06064ee1537cd570717569b583dec0b5',
'command'=>'PURCHASE',
'language'=>'en',
'payment_option'=>'VALU',
'phone_number'=>'00008557694',
'amount'=>'10000',
'currency'=>'EGP',
'customer_email'=>'customer@domain.com',
'otp'=>'123456',
'tenure'=>'6',
'total_down_payment'=>'1200',
'purchase_description'=>'Test',
'wallet_amount'=>'500000',
'cashback_wallet_amount'=>'300000'
};
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)
String jsonRequestString = "{\n \"merchant_reference\":\"TEST-009967\",\n \"merchant_identifier\":\"CycHZxVj\", \n \"access_code\":\"zx0IPmPy5jp1vAz8Kpg7\",\n \"signature\":\"27c1303138f8718e56f311d1b3d823b5a644e6bcd4fac43d5454955b13b5b337\",\n \"service_command\":\"OTP_GENERATE\",\n \"language\":\"en\",\n \"payment_option\":\"VALU\",\n \"phone_number\":\"01220422223\",\n \"amount\":\"100000\",\n \"currency\":\"EGP\",\n \"include_installments\":\"YES\",\n \"wallet_amount\":\"500000\",\n \"cashback_wallet_amount\":\"300000\"\n}";
// 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());
{
"merchant_reference":"XYZ9239-yu898",
"merchant_identifier":"CycHZxVj",
"access_code":"zx0IPmPy5jp1vAz8Kpg7",
"signature":"b574e362cc08d7504d8277e71400132f06064ee1537cd570717569b583dec0b5",
"command":"PURCHASE",
"language":"en",
"payment_option":"VALU",
"phone_number":"00008557694",
"amount":"10000",
"currency":"EGP",
"customer_email":"customer@domain.com",
"otp":"123456",
"tenure":"6",
"total_down_payment":"1200",
"purchase_description":"Test",
"wallet_amount":"500000",
"cashback_wallet_amount":"300000"
}
Purchase Request Parameters
Parameter Name | Description |
---|---|
command Alpha Mandatory Max: 20 |
Command. Possible values: PURCHASE |
access_code Alphanumeric Mandatory Max: 20 |
Access code. |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. For example: CycHZxVj |
merchant_reference Alphanumeric Mandatory Max:40 |
The Merchant’s unique order number. The merchant reference should be the same for all APIs. -_. For example: XYZ9239-yu898 |
payment_option Alpha Mandatory Max: 10 |
Payment option. Possible Values: VALU |
phone_number Alphanumeric Mandatory 19 |
The customer’s phone number registered for ValU. |
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. |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. For example: EGP |
language Alpha Mandatory Max: 2 |
The checkout page and messages language.For example - en - ar |
customer_email Alphanumeric Mandatory Max:254 |
The customer’s email. Special Characters: _-.@+ For example: customer@domain.com |
otp Alphanumeric Mandatory Max: 10 |
OTP sent by mobile. For example, 123456 |
tenure Alphanumeric Mandatory Max: 100 |
The tenure for the installment payments. For example: 6 |
signature Alphanumeric Mandatory Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature For example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
purchase_ description Alphanumeric Mandatory Max:100 |
The purchase description. For example: Test |
total_down_payment Alphanumeric Mandatory Max:100 |
The total transaction’s down payment.Decimal values are not accepted.For example:0 |
wallet_amount Numeric Mandatory Max:10 |
Wallet amount or ToU is a gift balance that you can purchase using your valU limit and can pay in flexible installment plans from 6-60 months. You can transfer ToU balance to all of your loved ones, they don’t need to be valU customers. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000 |
cashback_wallet_amount Numeric Mandatory Max:10 |
Amount stored in cashback wallet. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000 |
Purchase – Response
Purchase Response Example
Purchase Response Parameters
Parameter Name | Description |
---|---|
command Alpha Max:20 |
Command. Possible Values: PURCHASE |
access_code Alphanumeric Max: 20 |
Access code. For example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. For example: CycHZxVj |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. For example: XYZ2939-yu898 |
payment_option Alpha Max:10 |
Payment option. Possible values: VALU |
phone_number Alphanumeric Max: 19 |
The customer’s phone number registered for ValU. For example: 00008557694 |
amount Numeric Max:10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. For example: EGP |
language Alpha Max:2 |
The checkout page and messages language.For example - en - ar |
customer_email Alphanumeric Max: 254 |
The customer’s email. For example: customer@domain.com |
signature Alphanumeric Max:200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature For example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
purchase_description Alphanumeric Max:100 |
The purchase description. For example: Test |
customer_ip Alphanumeric Max:45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example on the right hand side. IPv4è192.17 8.1.10 IPv6è2001:0db8:3042:0002:5a55:caff:fef6:bdbf |
eci Alpha Max:16 |
E-commerce indicator. Possible values: ECOMMERCE |
fort_id Numeric Max: 20 |
The order’s unique reference returned by our system.For example: 149295435400084008 |
response_message Alphanumeric Max:150 |
Message description of the response code. It returns according to the request language. Please refer to section messages |
response_code Numeric Max:5 |
Response code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response message. For example: 14000 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Please refer to section statuses. |
wallet_amount Numeric Mandatory Max:10 |
Wallet amount or ToU is a gift balance that you can purchase using your valU limit and can pay in flexible installment plans from 6-60 months. You can transfer ToU balance to all of your loved ones, they don’t need to be valU customers. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000 |
cashback_wallet_amount Numeric Mandatory Max:10 |
Amount stored in cashback wallet. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000 |
loan_number Alphanumeric Max:100 |
Number generated by Valu for each successful purchase transaction. |
valu_transaction_id Alphanumeric Max:100 |
Unique identifier for the transaction. |
Refund API
The refund API has been implemented to follow the same standards for all the other payment option refund flow. Please use the following document to understand the flow: https://docs.payfort.com/docs/api/build/index.html#refund-operation
Note; The refund API of ValU supports the full refund and partial.
Get Installment Plans Request
Using this API, you can fetch the installment plans the customer has selected.
Request Example
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'service_command'=> 'GET_INSTALLMENTS_PLANS',
'merchant_reference'=>'XYZ9239-yu898',
'merchant_identifier'=>'CycHZxVj',
'access_code'=>'zx0IPmPy5jp1vAz8Kpg7',
'signature'=>'b574e362cc08d7504d8277e71400132f06064ee1537cd570717569b583dec0b5',
'phone_number'=> '01220422223',
'payment_option'=>'VALU',
'language'=> 'en',
'amount'=>'100000',
'total_downpayment'=>'1200',
'wallet_amount'=>'500000',
'cashback_wallet_amount'=>'300000'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'service_command': 'GET_INSTALLMENTS_PLANS',
'merchant_reference':'XYZ9239-yu898',
'merchant_identifier':'CycHZxVj',
'access_code':'zx0IPmPy5jp1vAz8Kpg7',
'signature':'b574e362cc08d7504d8277e71400132f06064ee1537cd570717569b583dec0b5',
'phone_number': '01220422223',
'payment_option':'VALU',
'language': 'en',
'amount':'100000',
'total_downpayment':'1200',
'wallet_amount':'500000',
'cashback_wallet_amount':'300000'
};
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 = {
'service_command'=> 'GET_INSTALLMENTS_PLANS',
'merchant_reference'=>'XYZ9239-yu898',
'merchant_identifier'=>'CycHZxVj',
'access_code'=>'zx0IPmPy5jp1vAz8Kpg7',
'signature'=>'b574e362cc08d7504d8277e71400132f06064ee1537cd570717569b583dec0b5',
'phone_number'=> '01220422223',
'payment_option'=>'VALU',
'language'=> 'en',
'amount'=>'100000',
'total_downpayment'=>'1200',
'wallet_amount'=>'500000',
'cashback_wallet_amount'=>'300000'
};
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)
String jsonRequestString = "{\n\"service_command\": \"GET_INSTALLMENTS_PLANS\",\n\"merchant_reference\":\"XYZ9239-yu898\",\n\"merchant_identifier\":\"CycHZxVj\", \n\"access_code\":\"zx0IPmPy5jp1vAz8Kpg7\",\n\"signature\":\"b574e362cc08d7504d8277e71400132f06064ee1537cd570717569b583dec0b5\",\n\"phone_number\": \"01220422223\",\n\"payment_option\":\"VALU\",\n\"language\": \"en\",\n\"amount\":\"100000\",\n\"total_downpayment\":\"1200\",\n\"wallet_amount\":\"500000\",\n\"cashback_wallet_amount\":\"300000\"\n\n}";
// 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());
{
"service_command": "GET_INSTALLMENTS_PLANS",
"merchant_reference":"XYZ9239-yu898",
"merchant_identifier":"CycHZxVj",
"access_code":"zx0IPmPy5jp1vAz8Kpg7",
"signature":"b574e362cc08d7504d8277e71400132f06064ee1537cd570717569b583dec0b5",
"phone_number": "01220422223",
"payment_option":"VALU",
"language": "en",
"amount":"100000",
"total_downpayment":"1200",
"wallet_amount":"500000",
"cashback_wallet_amount":"300000"
}
Get Installment Plan Parameters
Parameter Name | Description |
---|---|
service_command Alpha Mandatory Max:20 |
Command. For example:GET_INSTALLMENTS_PLANS |
access_code Alphanumeric Mandatory Max:20 |
Access code. For example:zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. For example: CycHZxVj |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. The merchant reference should be the same for all APIs. Special Characters-_. For example:XYZ9239-yu898 |
language Alpha Mandatory Max:2 |
The checkout page and messages language.Possible - en - ar |
payment_option Alpha Mandatory Max: 10 |
Payment option. For example: VALU |
total_downpayment Numeric Optional Max:100 |
Defines the total down-payment amount payable by the customer. *Decimal values are not accepted. For example: 1200 |
phone_number Alphanumeric Mandatory Max:19 |
The customer’s phone number registered for ValU. For example:00008557694 |
amount Numeric Mandatory Max:10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction amount in ISO code 3. For example: EGP |
signature Alphanumeric Mandatory Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature For example 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
wallet_amount Numeric Mandatory Max:10 |
Wallet amount or ToU is a gift balance that you can purchase using your valU limit and can pay in flexible installment plans from 6-60 months. You can transfer ToU balance to all of your loved ones, they don’t need to be valU customers. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000 |
cashback_wallet_amount Numeric Mandatory Max:10 |
Amount stored in cashback wallet. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000 |
Get Installment Plans Response
Response Example
Parameter Name | Description |
---|---|
service_command Alpha Max: 20 |
Command. Possible Values: GET_INSTALLMENTS_PLANS |
access_code Alphanumeric Max: 20 |
Access code. For example: Lzx0IPmPy5 jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Max:20 |
The ID of the Merchant. For example:CycHZxVj |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. The merchant reference should be the same for all APIs. Special Characters-_=. XYZ9239-yu898 |
language Alpha Max: 2 |
The checkout page and messages language. For example - en - ar |
payment_option Alpha Max: 10 |
Payment option. For example VALU |
total_downpayment Numeric Max: 100 |
Defines the total down-payment amount payable by the customer. *Decimal values are not accepted. Special Characters - For example: 1200 |
phone_number Alphanumeric Max: 19 |
The customer’s phone number registered for ValU. 00008557694 |
amount Numeric Max:10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction amount in ISO code 3. For example: EGP |
signature Alphanumeric Max: 200 |
A string hashed using the Secure Hash Algorithm.Please refer to section Signature |
installment_detail List |
A list of all the details of installments, such as number of installments, fees due every month. |
wallet_amount Numeric Mandatory Max:10 |
Wallet amount or ToU is a gift balance that you can purchase using your valU limit and can pay in flexible installment plans from 6-60 months. You can transfer ToU balance to all of your loved ones, they don’t need to be valU customers. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000 |
cashback_wallet_amount Numeric Mandatory Max:10 |
Amount stored in cashback wallet. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. For example:10000 |
Customer Verify
This request allows the Merchant to identify whether the customer is a ValU registered customer or not; by verifying the Customer’s phone number.
Customer Verify – Request
Customer Verify Request Example
{
"service_command":"CUSTOMER_VERIFY", "merchant_reference":"XYZ9239-yu898", "merchant_identifier":"CycHZxVj", "access_code":"zx0IPmPy5jp1vAz8Kpg7", "language":"en",
"payment_option":"VALU",
"phone_number":"00008557694",
"signature":"54efbd76bd644e9ef237c39137bf5d2304dc1bfdf6f6302065b448f2456a07a7"
}
Customer Verify Request Parameters
{
"service_command":"CUSTOMER_VERIFY", "merchant_reference":"XYZ9239-yu898", "merchant_identifier":"CycHZxVj", "access_code":"zx0IPmPy5jp1vAz8Kpg7", "language":"en",
"payment_option":"VALU",
"phone_number":"00008557694",
"signature":"54efbd76bd644e9ef237c39137bf5d2304dc1bfdf6f6302065b448f2456a07a7"
}
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'service_command'=>'CUSTOMER_VERIFY', 'merchant_reference'=>'XYZ9239-yu898', 'merchant_identifier'=>'CycHZxVj', 'access_code'=>'zx0IPmPy5jp1vAz8Kpg7', 'language'=>'en',
'payment_option'=>'VALU',
'phone_number'=>'00008557694',
'signature'=>'54efbd76bd644e9ef237c39137bf5d2304dc1bfdf6f6302065b448f2456a07a7'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'service_command':'CUSTOMER_VERIFY', 'merchant_reference':'XYZ9239-yu898', 'merchant_identifier':'CycHZxVj', 'access_code':'zx0IPmPy5jp1vAz8Kpg7', 'language':'en',
'payment_option':'VALU',
'phone_number':'00008557694',
'signature':'54efbd76bd644e9ef237c39137bf5d2304dc1bfdf6f6302065b448f2456a07a7'
};
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 = {
'service_command'=>'CUSTOMER_VERIFY', 'merchant_reference'=>'XYZ9239-yu898', 'merchant_identifier'=>'CycHZxVj', 'access_code'=>'zx0IPmPy5jp1vAz8Kpg7', 'language'=>'en',
'payment_option'=>'VALU',
'phone_number'=>'00008557694',
'signature'=>'54efbd76bd644e9ef237c39137bf5d2304dc1bfdf6f6302065b448f2456a07a7'
};
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)
String jsonRequestString = "{\n\n\"service_command\":\"CUSTOMER_VERIFY\", \"merchant_reference\":\"XYZ9239-yu898\", \"merchant_identifier\":\"CycHZxVj\", \"access_code\":\"zx0IPmPy5jp1vAz8Kpg7\", \"language\":\"en\",\n\"payment_option\":\"VALU\",\n\n\"phone_number\":\"00008557694\",\n\n\"signature\":\"54efbd76bd644e9ef237c39137bf5d2304dc1bfdf6f6302065b448f2456a07a7\"\n\n}";
// 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());
Parameter Name | Description |
---|---|
service_command Alpha Max: 20 Mandatory |
Command For example:CUSTOMER_VERIFY |
access_code Alphanumeric Mandatory Max:20 |
Access code. For example:zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. For example:CycHZxVj |
merchant_reference Alphanumeric Mandatory Max:40 |
The Merchant’s unique order number. The merchant reference should be the same for all APIs. Special Characters:-_. For example: XYZ9239-yu898 |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. |
payment_option Alpha Mandatory Max: 10 |
Payment option. For example:VALU |
phone_number Alphanumeric Mandatory Max:19 |
The customer’s phone number registered for ValU. |
signature Alphanumeric Mandatory Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
Customer Verify – Response
Customer Verify Response Parameters
Parameter Name | Description |
---|---|
service_command Alpha Max: 20 |
Command. For example: CUSTOMER_VERIFY |
access_code Alphanumeric Max:20 |
Access code. For example:zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. For example: CycHZxVj |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. The merchant reference should be the same for all APIs. Special Characters: -_. For example: XYZ9239-yu898 |
language Alpha Max: 2 |
The checkout page and messages language. For example - en - ar |
payment_option Alpha Max:10 |
Payment option.For example VALU |
total_downpayment Numeric Max: 100 |
Defines the total down-payment amount payable by the customer. *Decimal values are not accepted. For example: 1200 |
phone_number Alphanumeric Max: 19 |
The customer’s phone number registered for ValU. For example:00008557694 |
amount Numeric Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Max: 10000 |
currency Alpha Max: 3 |
The currency of the transaction amount in ISO code 3. For example: EGP |
signature Alphanumeric Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature For example: aa7cad05f0212ed933c9a5d5dffa31661acf2c827a |
response_message Alphanumeric Max: 150 |
Message description of the response code. It returns according to the request language.Please refer to section messages |
response_code Numeric Max:5 |
Response code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response message. |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction.Please refer to section statuses |
KNET
KNET is a dominant debit card based payment method, based out of Kuwait, and owned by the Central Bank of Kuwait. Amazon Payment Services enables its customers to use their debit cards for online business transactions through KNET. Amazon Payment Services uses the redirection channel to enable KNET transactions. Customers will be redirected from the merchant’s confirmation page to the KNET submission page in order to complete the payment.
As a merchant, in order integrate the KNET in your checkout page, add the following parameters in the redirection POST request:
- payment_option
- KNET value
For more information about integrating KNET payment option in your checkout pages, see Redirection.
Integration Flow
The following steps define the integration flow that happens between the customer and the merchant, while using KNET to complete payment transactions:
- Customer accesses the Checkout page, and selects KNET.
- Merchant submits the redirection request.
- Customer is redirected to the KNET transaction page, and completes the payment.
- Merchant receives the Redirection API response, along with the response parameters in the redirection URL.
Resource
/FortAPI/paymentPage
Resource Example
https://sbcheckout.payfort.com/FortAPI/paymentPage
HTTP Method
POST
Sample Request Body
{
“amount”: “100”,
“signature”: “cafac0b0b4e5f6ebeafc727276dcb8878bd24dbed20e13ef10211077297c316f”,
“merchant_identifier”: “LTdsdcLmI”,
“access_code”: “A3xssxTpCgBWIMn2VG”,
“payment_option”: “KNET”,
“customer_ip”: “xx.xx.xx.xxx”,
“language”: “en”,
“command”: “PURCHASE”,
“merchant_reference”: “Test978”,
“customer_email”: “test@mail.com”,
“return_url”: “https://test.com/AutoReturnSimulator?redirect”,
“currency”: “KWD”,
“knet_token”: “822056”
}
NOTE: Since the processing currency for KNET is KWD (3-decimal points currency in Kuwait Dinar), should multiply the amount by 1000 in the API request.
Request Properties
Parameter Name | Type | Description | Required or Optional |
---|---|---|---|
signature | String | The digital signature value calculated by the SHA algorithm. | Required |
command | String | Indicates the nature of the transaction. Example: Purchase |
Required |
amount | String | The transaction value. Consider the predefined allowed decimal points limits for every transaction. |
Required |
access_code | String | Access code | Required |
merchant_identifer | String | Unique merchant identifier ID. | Required |
merchant_reference | String | Unique order number of the merchant. | |
currency | String | The currency of the transaction in ISO code 3 format. | Required |
language | String | The language in which the checkout page and the messages are configured. | Required |
customer_email | String | Email ID of the customer. | Required |
payment_option | String | The payment gateway that is used to perform the transaction. | Required |
return_url | String | The merchant page URL that is displayed to the customer when the order is processed. | Required |
customer ip | String | IP address of the machine from which the customer performs the transaction. IPv4 and IPv6 are supported. |
Optional |
knet_token | Numeric | The eight digit numeric token to enable KFAST on the KNET payment page. | Optional |
Sample Response Body
{
“amount”: “100”,
“response_code”: “14000”,
“signature”: “e41e238a1398343692ec7bb6481bccb21914eaae98bac9c10eb1654013d110d1”,
“merchant_identifier”: “LTcQiLmI”,
“access_code”: “A3vl1JpVTpCgBWIMn2VG”,
“payment_option”: “KNET”,
“knet_ref_number”: “335101000204”,
“customer_ip”: “xx.xx.xxx.xxx”,
“language”: “en”,
“eci”: “ECOMMERCE”,
“fort_id”: “169996200013301025”,
“command”: “PURCHASE”,
“response_message”: “Success”,
“merchant_reference”: “DinaTest978”,
“authorization_code”: “B43127”,
“customer_email”: “test@mail.com”,
“currency”: “KWD”,
“knet_token”: “89123056”,
“status”: “14”,
“third_party_transaction_number”: “100335101000003949”
}
Response Properties
Parameter Name | Type | Description |
---|---|---|
knet_ref_number | String | KNET transaction reference number. |
amount | String | The transaction value. |
response_code | String | The message description of the response code; it returns according to the request language. |
signature | String | The digital signature value calculated by the SHA algorithm. |
merchant_identifier | String | Unique merchant identifier ID. |
access_code | String | Access code of the merchant. |
payment_option | String | The payment gateway that is used to perform the transaction. Example: KNET |
knet_ref_number | String | The unique reference number for the KNET transaction. |
customer_ip | String | IP address of the machine from which the customer performs the transaction. |
language | String | The language in which the transaction details are communicated. |
eci | String | E-commerce indicator. |
fort_id | String | Unique PayFort transaction ID. |
command | String | Indicates the nature of the transaction. Example: Purchase |
response_message | String | Indicates if the transaction was successful or a failure. |
merchant_reference | String | Reference ID of the merchant. |
authorization_code | String | The authorization code returned from the 3rd party. |
customer_email | String | Email address of the customer. |
currency | String | The currency in which the transaction is performed. |
knet_token | String | Eight digit numeric token to enable KFAST on the KNET payment page. |
status | String |
Card authentication - 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.
Card authentication - 3DS2 (EMV) Service
Visa and Mastercard issued a new mandate to card issuers covering 3DS 2.0. The new version of 3DS, version 2.0, is a risk-based version of 3DS authentication where the merchants mush adhere to the requirements and APS will minimize the efforts on merchants by passing the mandatory fields to the processor, the merchant can submit additional fields in the API request. The following are optional fields for 3DS2 service:
ATTRIBUTES | Description |
---|---|
billing_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric Optional max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
shipping_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
shipping_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric Optional |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric Optional |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric Optional max: 100 |
The city portion of the address. |
Standard 3D Secure & Flex 3D Secure Services
Standard 3D Secure Service
This service provides cardholders a decreased risk of other people being able to use their payment cards fraudulently on the Merchant’s site.
Include the following parameter in the Request you will send to Amazon Payment Services:
ATTRIBUTES | Description |
---|---|
check_3ds Alpha Optional max: 2 |
This parameter allows the Merchant to deactivate the 3D Secure service per transaction. This parameter can be used with both Authorization and Purchase transactions. Possible/ expected values: NO |
Flex 3D Secure Service
Under certain circumstances you may choose to bypass the 3D Secure process to reduce the number of actions your customer has to take – and to deliver a more seamless payment experience.
Amazon Payment Services gives you the option to waive the 3D Secure process where a transaction meets conditions that you set. It’s called Flex 3D Secure.
This service gives you the flexibility to downgrade the 3D Secure authentication in the transaction processing, based on a set of rules of your choice. You can activate/ deactivate this service under the “Flex Management” tab in your back office.
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:
{
"command": "PURCHASE",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "99999999130",
"amount": "2000",
"currency": "SAR",
"language": "en",
"customer_email": "test@merchantdomain.com",
"signature": "{{signature}}",
"token_name":"abcdefgh12345678",
"card_security_code":"123",
"threeds_id":"11111111111",
"customer_ip": "192.0.0.0",
"return_url":"http://localhost:8080/purchase_response.html"
}
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'command'=> 'PURCHASE',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> '99999999130',
'amount'=> '2000',
'currency'=> 'SAR',
'language'=> 'en',
'customer_email'=> 'test@merchantdomain.com',
'signature'=> '{{signature}}',
'token_name'=>'abcdefgh12345678',
'card_security_code'=>'123',
'threeds_id'=>'11111111111',
'customer_ip'=> '192.0.0.0',
'return_url'=>'http://localhost:8080/purchase_response.html'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command': 'PURCHASE',
'access_code': '{{access_code}}',
'merchant_identifier': '{{merchant_identifier}}',
'merchant_reference': '99999999130',
'amount': '2000',
'currency': 'SAR',
'language': 'en',
'customer_email': 'test@merchantdomain.com',
'signature': '{{signature}}',
'token_name':'abcdefgh12345678',
'card_security_code':'123',
'threeds_id':'11111111111',
'customer_ip': '192.0.0.0',
'return_url':'http://localhost:8080/purchase_response.html'
};
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'=> 'PURCHASE',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> '99999999130',
'amount'=> '2000',
'currency'=> 'SAR',
'language'=> 'en',
'customer_email'=> 'test@merchantdomain.com',
'signature'=> '{{signature}}',
'token_name'=>'abcdefgh12345678',
'card_security_code'=>'123',
'threeds_id'=>'11111111111',
'customer_ip'=> '192.0.0.0',
'return_url'=>'http://localhost:8080/purchase_response.html'
};
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)
String jsonRequestString = "{\n \"command\": \"PURCHASE\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"99999999130\",\n \"amount\": \"2000\",\n \"currency\": \"SAR\",\n \"language\": \"en\",\n \"customer_email\": \"test@merchantdomain.com\",\n \"signature\": \"\",\n \"token_name\":\"abcdefgh12345678\",\n \"card_security_code\":\"123\",\n \"threeds_id\":\"11111111111\",\n \"customer_ip\": \"192.0.0.0\",\n \"return_url\":\"http://localhost:8080/purchase_response.html\"\n}";
// 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());
ATTRIBUTES | Description |
---|---|
command Alpha Mandatory max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
access_code Alphanumeric Mandatory max: 20 |
Merchant account Access Code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Mandatory max: 20 |
Amazon Payment Services Merchant Account identifier. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory max: 40 |
The Merchant’s unique reference for a specific request. Example: XYZ9239-yu898 Special characters: _ - . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Mandatory Max: 254 |
The customer’s email. Example: customer@domain.com Special characters: _ - . @ + |
eci Alpha Optional Max: 16 |
Ecommerce indicator. Possible/ expected values: - ECOMMERCE - MOTO |
expiry_date Numeric Mandatory Max: 4 |
The card’s expiry date. Example: 2105 |
card_number Numeric Mandatory Max: 19 |
The clear credit card’s number. *Only the MEEZA payment option takes 19 digits card number. *AMEX payment option takes 15 digits card number. *Otherwise, they take 16 digits card number. Example: 4005550000000001 |
card_security_code Numeric Max: 4 |
A security code for the card. * Only AMEX accepts card security code of 4 digits. Example: 123 |
signature Alphanumeric Mandatory max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
3ds_enrolled Alpha Mandatory Max: 1 |
Parameter that hold if the card is enrolled or not. Possible/ expected values: - Y (Yes) - N (No) |
3ds_status Alpha Mandatory Max: 1 |
The status of the 3ds check just like 3-DSEnrolled but this parameter is available after a check is completed. Possible/ expected values: - Y - N - U - A |
3ds_eci Numeric Mandatory Max: 2 |
The eCommerce indicator returned from the MPI. Possible/ expected values: - 05 - 06 |
ver_token Alphanumeric Mandatory Max: 28 |
Verification token generated by the issuer to prove that the cardholders has been authenticated. Example: gIGCg4SFhoeIiYqLjI2Oj5CRkpM= |
card_holder_name Alpha Optional max: 50 |
The card holder name. Example: John Smith Special characters: ' - . |
token_name Alphanumeric Optional Max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp Special characters: . @ - _ |
payment_option Alpha Optional Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) |
order_description Alphanumeric Optional Max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
customer_ip Alphanumeric Optional max: 45 |
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf Special characters: . : |
customer_name Alpha Optional Max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' Space |
phone_number Numeric Optional Max: 19 |
The customer’s phone number. Example: 00962797219966 Special characters: + - ( ) Space |
settlement_reference Alphanumeric Optional max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 Special characters: - _ . |
merchant_extra Alphanumeric Optional Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra1 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra2 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra3 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra4 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra5 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
return_url Alphanumeric Optional Max: 400 |
The URL of the Merchant’s page to be displayed to the customer when the order is processed. Example: https://www.merchant.com Special characters: $ ! = ? # & - _ / : . |
agreement_id Alphanumeric Optional max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
recurring_expiry_date |
The date where the merchant needs to end the recurring. The format is YY-MM-DD [Numeric] with special character - |
recurring_days_between_payments |
The number of days between payments agreed with the payer under your agreement with them. The allowed data type is: Numeric only. |
The following parameters will be returned in Amazon Payment Services’ response:
ATTRIBUTES | Description |
---|---|
command Alpha Mandatory max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
access_code Alphanumeric Mandatory max: 20 |
Merchant account Access Code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Mandatory max: 20 |
FORT Merchant Account identifier. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory max: 40 |
The Merchant’s unique reference for a specific request. Example: XYZ9239-yu898 Special characters: _ - . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Mandatory Max: 254 |
The customer’s email. Example: customer@domain.com Special characters: _ - . @ + |
eci Alpha Optional Max: 16 |
Ecommerce indicator. Possible/ expected values: - ECOMMERCE - MOTO |
expiry_date Numeric Mandatory Max: 4 |
The card’s expiry date. Example: 2105 |
card_number Numeric Mandatory Max: 19 |
The clear credit card’s number. *Only the MEEZA payment option takes 19 digits card number. *AMEX payment option takes 15 digits card number. *Otherwise, they take 16 digits card number. Example: 4005550000000001 |
signature Alphanumeric Mandatory max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
card_holder_name Alpha Optional max: 50 |
The card holder name. Example: John Smith Special characters: ' - . |
token_name Alphanumeric Optional Max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp Special characters: . @ - _ |
fort_id Numeric Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
payment_option Alpha Optional Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) |
order_description Alphanumeric Optional Max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
customer_ip Alphanumeric Optional max: 45 |
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf Special characters: . : |
customer_name Alpha Optional Max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' Space |
phone_number Numeric Optional Max: 19 |
The customer’s phone number. Example: 00962797219966 Special characters: + - ( ) Space |
settlement_reference Alphanumeric Optional max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 Special characters: - _ . |
merchant_extra Alphanumeric Optional Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra1 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra2 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra3 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra4 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra5 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
return_url Alphanumeric Optional Max: 400 |
The URL of the Merchant’s page to be displayed to the customer when the order is processed. Example: https://www.merchant.com Special characters: $ ! = ? # & - _ / : . |
response_message Alphanumeric Max: 150 |
Message description of the response code. It returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
3ds_url Alphanumeric Max: 300 |
The URL where the Merchant redirects a customer whose card is 3D Secure for authentication. Example: https://www.3dsecure.com |
agreement_id Alphanumeric max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
ds_transaction_id Alphanumeric Max: 40 |
The Directory Server Transaction ID generated during the authentication transaction. |
3ds_xid Alphanumeric Max: 28 |
Unique transaction Identification number to identify the 3DS transaction. Example: 6kQGHEiZDU0H4+mUWF7zELHAcqM= |
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:
{
"service_command": "3DS_ENROLLMENT",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "merchantTest-10084",
"amount": "2000",
"currency": "AED",
"language": "en",
"expiry_date":"5000",
"card_number":"1111112345678902",
"merchant_3ds_url":"http://localhost:8081/Merchant_Return_URL.html",
"confirm_3ds":"YES",
"signature": ""
}
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'service_command'=> '3DS_ENROLLMENT',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> 'merchantTest-10084',
'amount'=> '2000',
'currency'=> 'AED',
'language'=> 'en',
'expiry_date'=>'5000',
'card_number'=>'1111112345678902',
'merchant_3ds_url'=>'http://localhost:8081/Merchant_Return_URL.html',
'confirm_3ds'=> 'YES',
'signature'=> ''
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'service_command': '3DS_ENROLLMENT',
'access_code': '{{access_code}}',
'merchant_identifier': '{{merchant_identifier}}',
'merchant_reference': 'merchantTest-10084',
'amount':'2000',
'currency': 'AED',
'language': 'en',
'expiry_date':'5000',
'card_number':'1111112345678902',
'merchant_3ds_url':'http://localhost:8081/Merchant_Return_URL.html',
'confirm_3ds': 'YES',
'signature':''
};
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 = {
'service_command'=> '3DS_ENROLLMENT',
'access_code'=> 'access_code',
'merchant_identifier'=> 'merchant_identifier',
'merchant_reference'=> 'merchantTest-10084',
'amount'=> '2000',
'currency'=> 'AED',
'language'=> 'en',
'expiry_date'=>'5000',
'card_number'=>'1111112345678902',
'merchant_3ds_url'=>'http://localhost:8081/Merchant_Return_URL.html',
'confirm_3ds'=> 'YES',
'signature'=> ''
};
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)
String jsonRequestString = "{\n \"service_command\": \"3DS_ENROLLMENT\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"merchantTest-10084\",\n \"amount\": \"2000\",\n \"currency\": \"AED\",\n \"language\": \"en\",\n \"expiry_date\":\"5000\",\n \"card_number\":\"1111112345678902\",\n \"merchant_3ds_url\":\"http://localhost:8081/Merchant_Return_URL.html\",\n \"confirm_3ds\":\"YES\",\n \"signature\": \"\"\n}";
// 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());
ATTRIBUTES | Description |
---|---|
service_command Alpha Mandatory max: 20 |
Command. Possible/ expected values: 3DS_ENROLLMENT Special characters: _ |
access_code Alphanumeric Mandatory max: 20 |
Merchant account Access Code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Mandatory max: 20 |
Amazon Payment Services Merchant Account identifier. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory max: 40 |
The Merchant’s unique reference for a specific request. Example: XYZ9239-yu898 Special characters: _ - . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
expiry_date Numeric Mandatory Max: 4 |
The card’s expiry date. Example: 2105 |
card_number Numeric Mandatory Max: 19 |
The clear credit card’s number. Example: 4005550000000001 |
merchant_3ds_url Alphanumeric Mandatory max: 300 |
The URL where the Merchant will be redirected to see the returned 3ds parameters. Example: https://www.merchant.com Special characters: - & ? = _ . : / # |
signature Alphanumeric Mandatory max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
confirm_3ds Alpha Optional max: 3 |
To trigger confirm 3d secure data received automatically, include this parameter in the enrollment api call. This will eliminate the need of initiating 3ds_authentication API call after receiving 3ds data on merchant_3d_url Possible/ expected values: -YES -NO |
billing_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric Optional max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric Optional |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric Optional |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric Optional max: 100 |
The city portion of the address. |
agreement_id Alphanumeric Optional max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
recurring_mode Alphanumeric Optional max: 20 |
Indicates if the subsequent payments within the agreement has same/different amount or unscheduled (unknown interval/amount). Possible/ expected values: UNSCHEDULED, VARIABLE, FIXED |
recurring_expiry_date |
The date where the merchant needs to end the recurring. The format is YY-MM-DD [Numeric] with special character - |
recurring_days_between_payments |
The number of days between payments agreed with the payer under your agreement with them. The allowed data type is: Numeric only. |
The following parameters will be returned in Amazon Payment Services’ response:
ATTRIBUTES | Description |
---|---|
service_command Alpha max: 50 |
Command. Possible/ expected values: 3DS_ENROLLMENT Special characters: _ |
access_code Alphanumeric max: 20 |
Merchant account Access Code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric max: 20 |
Amazon Payment Services Merchant Account identifier. Example: CycHZxVj |
merchant_reference Alphanumeric max: 40 |
The Merchant’s unique reference for a specific request. Example: XYZ9239-yu898 |
amount Numeric Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
expiry_date Numeric Max: 4 |
The card’s expiry date. Example: 2105 |
card_number Numeric > Max: 19 |
The masked credit card’s number. Example: 400555******0001 |
merchant_3ds_url Alphanumeric max: 300 |
The URL where the Merchant will be redirected to see the returned 3ds parameters. Example: https://www.merchant.com Special characters: - & ? = _ . : / # |
3ds_enrolled Alpha Max: 1 |
Parameter that hold if the card is enrolled or not. Possible/ expected values: - Y (Yes) - N (No) - U (Unspecified failure) |
threeds_id Alphanumeric Max: 100 |
The 3ds operations unique reference. Example: 153606397100001061 |
signature Alphanumeric max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
response_message Alphanumeric max: 150 |
Message description of the response code. It returns according to the request language. Example: Insufficient Funds |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 44000 |
status Numeric max: 2 |
A two-digit numeric value that indicates the status of the transaction Possible/ expected values: (Please refer to section statuses). |
confirm_3ds Alpha max: 3 |
To trigger confirm 3d secure data received automatically, include this parameter in the enrollment api call. This will eliminate the need of initiating 3ds_authentication API call after receiving 3ds data on merchant_3d_url Possible/ expected values: -YES -NO |
billing_stateProvince Alphanumeric max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric max: 100 |
The city portion of the address. |
3D Secure Enrollment Response Example!
• After you get back a 3Ds Enrollment response that includes the parameter “3ds_enrolled” of value “Y”; follow the below steps for the 3Ds Authentication request:
- In case you are on “MPGS” processor; four parameters will be returned in the “3D Secure Enrollment”; as below:
• order.id
• transaction.id
• response.gatewayRecommendation
• result
And you have to copy them in the “3D Secure Authentication” request; as you will see in the 3Ds Authentication request example. - In case you are on “Cybersource” processor; two parameters returns in the “3D Secure Enrollment”; as below:
• MD
• TransactionId
And you have to copy them in the “3D Secure Authentication” request; as you will see in the 3Ds Authentication request example.
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:
{
"service_command": "3DS_AUTHENTICATION",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "19",
"language": "en",
"third_party_body": "MD=169996200001204473&PaRes=eAHNV1mzokgW/isVPY9GFTtiB2VEsoqy7/CGiKyCLAry6xuvVbduV1fPdMzDxPhi5seXJ8/Js2XSdtYlCWcl8a1LtrSS9H2UJp/y09ffEIpE1xsU+W1L68BM+i19T7o+b+ot8gX+gtLQ9+myqouzqB62dBS3jKRucYLAcJiGvk3pS9JJ3FYHgaCZNox/tgDDwDCM09DrCw39EKHfnsL6RZkpP21zTNbDlGR3TYHKcWYwZrZZftBeG7/S0JNBn6Ih2aIwisAYjHxC0N8J7HcEoaE3nL4+xYFLc1vUQ4ll00Wtjxi9GN4ldfzYktRi0/uMTqZrUyfPVTT0PqahH+pdo/pp6BpGUAwnyDW1gRfqE6Vtf0sP+eUvauEEDb3hdD9Ew63fBjT0bUTH0f2+TSWRTXFLyJpEyoNWLiRUKwjWLK/KYu4bhU7ifAsvgp7/b6tAlTZdPmSX7WL1k/MDoKGnKtA3/1l5Wi/bdsmn6VLV/dffsmG4/g5B4zh+GbEvTZdC6HJAELyBFsKpz9N/Lc5/rkpOUn1utjQb1U2dx1GVz9GwhIKSDFlz+vS+4a9E2iaEPF3mcZ8XqZ9jBK8/PwEEQYhFPPRrma9937T9J5u89Ebf9e766HOfRc/ghd7Nfgna0mZyTp4+X2KMy9OkH/6bHb5L/yjhuzw3qm7JVuKQu9vMdilzKIJhcbpGAtXfMP5aWpz5Wvdi0tAHld70/X7g77q/iFoh7+tBU/wrdEcFaSUwgZOZ7DjwuIjU2CDGtsqKqTlYxHWsyP1wsdA20q97o2iYMwm3sda0vIzd4U2869GqiSDRyufsgvhd5+DOWSGiAGlNKX/Uj77rhmgmVKPrmMktShwikaQr8rvo9vgZ83kA2StDsTbXpttjzVoLh0ritaZU/W41GJxUZWdSVe9qmiZyIGYGQhiseQz7oArxCdmhh7V2JLITorXXq3E931cjBvr1yUWtx9pjZUnbWyAcGVnD5ImtqkanHt4jAhHUjk5Bzj4sKamN373D5mFNGpEPSLpSk0jMKs+4Fp6E2BeTKofU7DIP23mPtIj1kQpuzUDa5OiS+ml1NuoKfF3c8dNB04fk8Qp5n4A3XDREW/o5YpNuyM9LBiw1R5EkluBYFpQwCwx+5Ixgf2hCKbvH6jLnGQOMMcfLCihFgDg8kyms4ToTx4EDk6ouA1IFIIJicrypAOrFGUfJqPfXGN1nx8tHbrNwTc2Zf3DZhevA7k4STMFBjGk3g9NLrqIIlfk4+SocesZsiy4aehMXicL1mCN7A+bHXRaril1OCscjChfPSiFN3hMr3rDHO1awTPrvbbD/YsOk/MkGcQbhS6/G5qvFhgfDPHWLL0IfeXzqiu584nhFAc3bGbCLVk+7FMsZpTHgXMPg+Gly4nrhiW6pwFN1uri9gWZZ5OGDt5jgoFV9vLiPxSeMVACVScs2K3NxM8LM4gsBAG3xEQWe39n08PQX6NYHCkGmzgqQOnR9arpRbdVbwLiOorW7rFfxYd+scXFG8pBEhBXcV8R1TVGcHwwxlrAaMFwVCdjKb+7a0Zkgx0xx7IDa00q2SG9kAFaWblpuePtkrciNfhkd9bLkxzm7wOcBghSGiFAuPSKMBK8kOe2kfYuNxKxXrkV5gWz1/lkSKndj8lPZS0cN6q0ePNTjXresjUgWnUFi2aoqzc4ocl6HeU5ghHmGXGmvhr25ku5lkxx8MINxH+uyrx6HK9s4skC2vhujVBLKebk+nicYjmbmYKWp1nn+Xj2v++MpEvibo23cRliyEHW8W6yRDDRCF1HR1Pww6tA13OgVZaxza5oITdEJmDmOEgcMwCgAFlmrFS3piHEGzzDAAQAXGQDOu+Cuw4a4rtlpECt53F8lpneZSwW5mBquItHEYUvhCDGa+DXBxgg8846NIgrpbNpjeMh3e0gPCNU2pyEMXe24RqaiKAlYvjR3yql2bX0IzkI0JUwFxgFO+Bi2ncSr1416d308Smdcmafqrt7F9Dgma9dJ72bpz3kjsDDCKAdPnU01FWjo54z/ZQmwi6UEHOO/LQHH+X9YAgoQv5cA929LAGfYIBFGeNJsflRsZ1RnZVLmfbRgjxcmvWPKDkzsDPYvuYENSsFVjHFk07fUXPytmjZvTLwN9BcnVlh+/4h8NQ88ovrAPSxcx66UD9xeYQVVMB+MY7qqo5jUuDNeKc8x4d+mvOWojCKJ55/DDBhvYaYCjmVyY6myBrcjA2a+7Ye1oYSb2l6b6/XGmj19IyaEIc97cjMrMxqt9ceZP4Z41xqE56vuTsenGoEdCbnLtWdxBPvg5TvXBoHu3FJfDK9tHD4wSrB0zVBPTJOXiUGZ3hzFs20lGtIIR0WmUo8b8Ac6sjwKFQ9SqlkHi9hzoXeiUvDhXMF1wOYBUlBc+J9SR5FZOXugj81mqs4rHCB7Rzu2iKQRMdW7CPEAcbpZTjKu7b7ZGwFJKTa8w3ZFtBscp0LKoBNE3Nucr/G4BmzaXYfOBv2A2xZ59/t0ds67MZQN9zyR1GXQqdYVZWPOk1aH9q0vbqqDkCky7DhJCOlrOxNZpERF/mwFrXigDgiRehqzvwae9Q9Tx7WfqYOz7HIvONQVW/ZMrtk/V+9eABxzV4x+ZF+hIfLjnnHtDx0DjJzjTLxiLl341TF2HMjY+FLNwUW4hR+56ci5PGF/4MoL1zadOHV513Y5PlGY8a0TgXF03d0eiTGzCjlVCf2wOvJqE3jVTX6GIIP7nM0Tig0m1QaYMoOHgjQLJr1hSvGOjf+fZYBl6vnn837rlkyx3F7SoFyynAezHqjw0hcaMJwPfR75qCA6Pp7BWrPZRMNSQW+rIHUrCTsKrZCj8OkmQHYQ6kESBPP0aDW0nDjcuFwZLS3Q82w61kawSya6k27rPta2YPsQf+AIffCKZNe3nf6osCWaZwrReyfHdhRnCUZ7PRp3qrhBTM9Fsn6440nN+l4pVDqAD9AmbngWjDwAv4ohoC3lgCXW6GVlQIxeVtXBxFTObYWDhSL7I85IZKYpTkvg2mEuINGQdD2BsEPYkuIpdkfvcmesw9IPq3sfUrcpOjpQz99uZVYpwU6AcvG+u5f720S2hL6Lw2VtPD+Ywq9cHiMk0gqxOjgr8Pjgd6tdbTG6J/cn3zwd3Css8boiQZUWgzyJVdKO3PR5Lf1LB3pDXvdR6P2O+uP2ujx3vr3hl9Gf3vZ/ACJtNGI=",
"signature": "fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b"
}
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'service_command'=> '3DS_AUTHENTICATION',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> '19',
'language'=> 'en',
'third_party_body'=> 'MD=169996200001204473&PaRes=eAHNV1mzokgW/isVPY9GFTtiB2VEsoqy7/CGiKyCLAry6xuvVbduV1fPdMzDxPhi5seXJ8/Js2XSdtYlCWcl8a1LtrSS9H2UJp/y09ffEIpE1xsU+W1L68BM+i19T7o+b+ot8gX+gtLQ9+myqouzqB62dBS3jKRucYLAcJiGvk3pS9JJ3FYHgaCZNox/tgDDwDCM09DrCw39EKHfnsL6RZkpP21zTNbDlGR3TYHKcWYwZrZZftBeG7/S0JNBn6Ih2aIwisAYjHxC0N8J7HcEoaE3nL4+xYFLc1vUQ4ll00Wtjxi9GN4ldfzYktRi0/uMTqZrUyfPVTT0PqahH+pdo/pp6BpGUAwnyDW1gRfqE6Vtf0sP+eUvauEEDb3hdD9Ew63fBjT0bUTH0f2+TSWRTXFLyJpEyoNWLiRUKwjWLK/KYu4bhU7ifAsvgp7/b6tAlTZdPmSX7WL1k/MDoKGnKtA3/1l5Wi/bdsmn6VLV/dffsmG4/g5B4zh+GbEvTZdC6HJAELyBFsKpz9N/Lc5/rkpOUn1utjQb1U2dx1GVz9GwhIKSDFlz+vS+4a9E2iaEPF3mcZ8XqZ9jBK8/PwEEQYhFPPRrma9937T9J5u89Ebf9e766HOfRc/ghd7Nfgna0mZyTp4+X2KMy9OkH/6bHb5L/yjhuzw3qm7JVuKQu9vMdilzKIJhcbpGAtXfMP5aWpz5Wvdi0tAHld70/X7g77q/iFoh7+tBU/wrdEcFaSUwgZOZ7DjwuIjU2CDGtsqKqTlYxHWsyP1wsdA20q97o2iYMwm3sda0vIzd4U2869GqiSDRyufsgvhd5+DOWSGiAGlNKX/Uj77rhmgmVKPrmMktShwikaQr8rvo9vgZ83kA2StDsTbXpttjzVoLh0ritaZU/W41GJxUZWdSVe9qmiZyIGYGQhiseQz7oArxCdmhh7V2JLITorXXq3E931cjBvr1yUWtx9pjZUnbWyAcGVnD5ImtqkanHt4jAhHUjk5Bzj4sKamN373D5mFNGpEPSLpSk0jMKs+4Fp6E2BeTKofU7DIP23mPtIj1kQpuzUDa5OiS+ml1NuoKfF3c8dNB04fk8Qp5n4A3XDREW/o5YpNuyM9LBiw1R5EkluBYFpQwCwx+5Ixgf2hCKbvH6jLnGQOMMcfLCihFgDg8kyms4ToTx4EDk6ouA1IFIIJicrypAOrFGUfJqPfXGN1nx8tHbrNwTc2Zf3DZhevA7k4STMFBjGk3g9NLrqIIlfk4+SocesZsiy4aehMXicL1mCN7A+bHXRaril1OCscjChfPSiFN3hMr3rDHO1awTPrvbbD/YsOk/MkGcQbhS6/G5qvFhgfDPHWLL0IfeXzqiu584nhFAc3bGbCLVk+7FMsZpTHgXMPg+Gly4nrhiW6pwFN1uri9gWZZ5OGDt5jgoFV9vLiPxSeMVACVScs2K3NxM8LM4gsBAG3xEQWe39n08PQX6NYHCkGmzgqQOnR9arpRbdVbwLiOorW7rFfxYd+scXFG8pBEhBXcV8R1TVGcHwwxlrAaMFwVCdjKb+7a0Zkgx0xx7IDa00q2SG9kAFaWblpuePtkrciNfhkd9bLkxzm7wOcBghSGiFAuPSKMBK8kOe2kfYuNxKxXrkV5gWz1/lkSKndj8lPZS0cN6q0ePNTjXresjUgWnUFi2aoqzc4ocl6HeU5ghHmGXGmvhr25ku5lkxx8MINxH+uyrx6HK9s4skC2vhujVBLKebk+nicYjmbmYKWp1nn+Xj2v++MpEvibo23cRliyEHW8W6yRDDRCF1HR1Pww6tA13OgVZaxza5oITdEJmDmOEgcMwCgAFlmrFS3piHEGzzDAAQAXGQDOu+Cuw4a4rtlpECt53F8lpneZSwW5mBquItHEYUvhCDGa+DXBxgg8846NIgrpbNpjeMh3e0gPCNU2pyEMXe24RqaiKAlYvjR3yql2bX0IzkI0JUwFxgFO+Bi2ncSr1416d308Smdcmafqrt7F9Dgma9dJ72bpz3kjsDDCKAdPnU01FWjo54z/ZQmwi6UEHOO/LQHH+X9YAgoQv5cA929LAGfYIBFGeNJsflRsZ1RnZVLmfbRgjxcmvWPKDkzsDPYvuYENSsFVjHFk07fUXPytmjZvTLwN9BcnVlh+/4h8NQ88ovrAPSxcx66UD9xeYQVVMB+MY7qqo5jUuDNeKc8x4d+mvOWojCKJ55/DDBhvYaYCjmVyY6myBrcjA2a+7Ye1oYSb2l6b6/XGmj19IyaEIc97cjMrMxqt9ceZP4Z41xqE56vuTsenGoEdCbnLtWdxBPvg5TvXBoHu3FJfDK9tHD4wSrB0zVBPTJOXiUGZ3hzFs20lGtIIR0WmUo8b8Ac6sjwKFQ9SqlkHi9hzoXeiUvDhXMF1wOYBUlBc+J9SR5FZOXugj81mqs4rHCB7Rzu2iKQRMdW7CPEAcbpZTjKu7b7ZGwFJKTa8w3ZFtBscp0LKoBNE3Nucr/G4BmzaXYfOBv2A2xZ59/t0ds67MZQN9zyR1GXQqdYVZWPOk1aH9q0vbqqDkCky7DhJCOlrOxNZpERF/mwFrXigDgiRehqzvwae9Q9Tx7WfqYOz7HIvONQVW/ZMrtk/V+9eABxzV4x+ZF+hIfLjnnHtDx0DjJzjTLxiLl341TF2HMjY+FLNwUW4hR+56ci5PGF/4MoL1zadOHV513Y5PlGY8a0TgXF03d0eiTGzCjlVCf2wOvJqE3jVTX6GIIP7nM0Tig0m1QaYMoOHgjQLJr1hSvGOjf+fZYBl6vnn837rlkyx3F7SoFyynAezHqjw0hcaMJwPfR75qCA6Pp7BWrPZRMNSQW+rIHUrCTsKrZCj8OkmQHYQ6kESBPP0aDW0nDjcuFwZLS3Q82w61kawSya6k27rPta2YPsQf+AIffCKZNe3nf6osCWaZwrReyfHdhRnCUZ7PRp3qrhBTM9Fsn6440nN+l4pVDqAD9AmbngWjDwAv4ohoC3lgCXW6GVlQIxeVtXBxFTObYWDhSL7I85IZKYpTkvg2mEuINGQdD2BsEPYkuIpdkfvcmesw9IPq3sfUrcpOjpQz99uZVYpwU6AcvG+u5f720S2hL6Lw2VtPD+Ywq9cHiMk0gqxOjgr8Pjgd6tdbTG6J/cn3zwd3Css8boiQZUWgzyJVdKO3PR5Lf1LB3pDXvdR6P2O+uP2ujx3vr3hl9Gf3vZ/ACJtNGI=',
'signature'=> 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'service_command':'3DS_AUTHENTICATION',
'access_code': '{{access_code}}',
'merchant_identifier':'{{merchant_identifier}}',
'merchant_reference': '19',
'language': 'en',
'third_party_body':'MD=11111111111&PaRes=eAHNV1mzokgW/abcdefgh123456781LB3pDXvdR6P2O+uP2ujx3vr3hl9Gf3vZ/=',
'signature': ''
};
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 = {
'service_command'=> '3DS_AUTHENTICATION',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> '19',
'language'=> 'en',
'third_party_body'=> 'MD=11111111111&PaRes=eAHNV1mzokgW/abcdefgh123456781LB3pDXvdR6P2O+uP2ujx3vr3hl9Gf3vZ/=',
'signature'=> ''
};
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)
String jsonRequestString = "{\n \"service_command\": \"3DS_AUTHENTICATION\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"19\",\n \"language\": \"en\",\n \"third_party_body\": \"MD=11111111111&PaRes=eAHNV1mzokgW/abcdefgh123456781LB3pDXvdR6P2O+uP2ujx3vr3hl9Gf3vZ/=\",\n \"signature\": \"\"\n}";
// 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());
ATTRIBUTES | Description |
---|---|
service_command Alpha Mandatory max: 20 |
Command. Possible/ expected values: 3DS_AUTHENTICATION Special characters: _ |
access_code Alphanumeric Mandatory max: 20 |
Access Code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Mandatory max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory max: 40 |
The Merchant’s unique number. *Please, use the same merchant reference you used in the “generate report” request. Example: XYZ9239-yu898 |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
third_party_body Alphanumeric Mandatory Max: 6000 |
Combinations of 3ds parameters from the 3ds_enrollment. Example: Check the examples below Special characters: + \ / : . _ = ? % # & - |
signature Alphanumeric Mandatory max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
3D Secure Authentication Request on Cybersource Processor Example!
3D Secure Authentication Request on MPGS Processor Example!
The following parameters will be returned in Amazon Payment Services’ response:
ATTRIBUTES | Description |
---|---|
service_command Alpha max: 20 |
Command. Possible/ expected values: 3DS_AUTHENTICATION |
access_code Alphanumeric max: 20 |
Access Code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric max: 40 |
The Merchant’s unique reference for a specific request. Example: XYZ9239-yu898 |
language Alpha Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
threeds_id Alphanumeric Max: 100 |
The 3ds operations unique reference. Example: 153606397100001061 |
3ds_enrolled Alpha Max: 1 |
Parameter that hold if the card is enrolled or not. Possible/ expected values: - Y (Yes) - N (No) |
3ds_status Alpha Max: 1 |
The status of the 3ds check just like 3DSEnrolled but this parameter is available after a check is completed. Possible/ expected values: - Y - N - U - A |
3ds_eci Numeric Max: 2 |
The eCommerce indicator returned from the MPI. Possible/ expected values: - 05 - 06 |
ver_type Alphanumeric Max: 3 |
The type of verification used for 3DS. Possible/ expected values: - 3DS - SPA |
ver_token Alphanumeric Max: 28 |
Verification token generated by the issuer to prove that the cardholders has been authenticated. Example: gIGCg4SFhoeIiYqLjI2Oj5CRkpM= |
signature Alphanumeric max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
response_message Alphanumeric max: 150 |
Message description of the response code. It returns according to the request language. Example: Insufficient Funds |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 44000 |
status Numeric max: 2 |
A two-digit numeric value that indicates the status of the transaction Possible/ expected values: (Please refer to section statuses). |
ds_transaction_id Alphanumeric Max: 40 |
The Directory Server Transaction ID generated during the authentication transaction. |
3ds_xid Alphanumeric Max: 28 |
Unique transaction Identification number to identify the 3DS transaction. Example: 6kQGHEiZDU0H4+mUWF7zELHAcqM= |
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:
{
"service_command": "3DS_ENROLLMENT",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "99999999129",
"amount": "2000",
"currency": "SAR",
"language": "en",
"token_name":"abcdefgh12345678",
"merchant_3ds_url":"http://localhost:8081/merchant_response.html",
"confirm_3ds":"YES",
"signature": ""
}
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'service_command'=>'3DS_ENROLLMENT',
'access_code'=>'{{access_code}}',
'merchant_identifier'=>'{{merchant_identifier}}',
'merchant_reference'=>'99999999129',
'amount'=>'2000',
'currency'=>'SAR',
'language'=>'en',
'token_name'=>'abcdefgh12345678',
'merchant_3ds_url'=>'http://localhost:8081/merchant_response.html',
'confirm_3ds'=>'YES',
'signature'=>''
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'service_command':'3DS_ENROLLMENT',
'access_code':'{{access_code}}',
'merchant_identifier':'{{merchant_identifier}}',
'merchant_reference':'99999999129',
'amount':'2000',
'currency':'SAR',
'language':'en',
'token_name':'abcdefgh12345678',
'merchant_3ds_url':'http://localhost:8081/merchant_response.html',
'confirm_3ds':'YES',
'signature':''
};
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 = {
'service_command'=>'3DS_ENROLLMENT',
'access_code'=>'{{access_code}}',
'merchant_identifier'=>'{{merchant_identifier}}',
'merchant_reference'=>'99999999129',
'amount'=>'2000',
'currency'=>'SAR',
'language'=>'en',
'token_name'=>'abcdefgh12345678',
'merchant_3ds_url'=>'http://localhost:8081/merchant_response.html',
'confirm_3ds'=>'YES',
'signature'=>''
};
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)
String jsonRequestString = "{\n \"service_command\": \"3DS_ENROLLMENT\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"99999999129\",\n \"amount\": \"2000\",\n \"currency\": \"SAR\",\n \"language\": \"en\",\n \"token_name\":\"abcdefgh12345678\",\n \"merchant_3ds_url\":\"http://localhost:8081/merchant_response.html\",\n \"confirm_3ds\":\"YES\",\n \"signature\": \"\"\n}";
// 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());
ATTRIBUTES | Description |
---|---|
service_command Alpha Mandatory max: 20 |
Command. Possible/ expected values: 3DS_ENROLLMENT Special characters: _ |
access_code Alphanumeric Mandatory max: 20 |
Merchant account Access Code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Mandatory max: 20 |
Amazon Payment Services Merchant Account identifier. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory max: 40 |
The Merchant’s unique reference for a specific request. Example: XYZ9239-yu898 Special characters: _ - . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
token_name Alphanumeric Mandatory Max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp Special characters: . @ - _ |
merchant_3ds_url Alphanumeric Mandatory max: 300 |
The URL where the Merchant will be redirected to see the returned 3ds parameters. Example: https://www.merchant.com Special characters: - & ? = _ . : / # |
signature Alphanumeric Mandatory max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
confirm_3ds Alpha Optional max: 3 |
To trigger confirm 3d secure data received automatically, include this parameter in the enrollment api call. This will eliminate the need of initiating 3ds_authentication API call after receiving 3ds data on merchant_3d_url Possible/ expected values: -YES -NO |
billing_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric Optional max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric Optional |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric Optional |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric Optional max: 100 |
The city portion of the address. |
agreement_id Alphanumeric Optional max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
recurring_mode Alphanumeric Optional max: 20 |
Indicates if the subsequent payments within the agreement has same/different amount or unscheduled (unknown interval/amount). Possible/ expected values: UNSCHEDULED, VARIABLE, FIXED |
recurring_expiry_date |
The date where the merchant needs to end the recurring. The format is YY-MM-DD [Numeric] with special character - |
recurring_days_between_payments |
The number of days between payments agreed with the payer under your agreement with them. The allowed data type is: Numeric only. |
The following parameters will be returned in Amazon Payment Services’ response:
ATTRIBUTES | Description |
---|---|
service_command Alpha max: 50 |
Query operations command. Possible/ expected values: 3DS_ENROLLMENT |
access_code Alphanumeric max: 20 |
Merchant account Access Code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric max: 20 |
Amazon Payment Services Merchant Account identifier. Example: CycHZxVj |
merchant_reference Alphanumeric max: 40 |
The Merchant’s unique reference for a specific request. Example: XYZ9239-yu898 |
amount Numeric Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
token_name Alphanumeric Max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp Special characters: . @ - _ |
merchant_3ds_url Alphanumeric max: 300 |
The URL where the Merchant will be redirected to see the returned 3ds parameters. Example: https://www.merchant.com Special characters: - & ? = _ . : / # |
3ds_enrolled Alpha Max: 1 |
Parameter that hold if the card is enrolled or not. Possible/ expected values: - Y (Yes) - N (No) - U (Unspecified failure) |
threeds_id Alphanumeric Max: 100 |
The 3ds operations unique reference. Example: 153606397100001061 |
signature Alphanumeric max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
response_message Alphanumeric max: 150 |
Message description of the response code. It returns according to the request language. Example: Insufficient Funds |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 44000 |
status Numeric max: 2 |
A two-digit numeric value that indicates the status of the transaction Possible/ expected values: (Please refer to section statuses). |
confirm_3ds Alpha Optional max: 3 |
To trigger confirm 3d secure data received automatically, include this parameter in the enrollment api call. This will eliminate the need of initiating 3ds_authentication API call after receiving 3ds data on merchant_3d_url Possible/ expected values: -YES -NO |
3D Secure Enrollment Response Example
• After you get back a 3D Secure Enrollment response that includes the parameter “3ds_enrolled” of value “Y”; follow the below steps for the 3D Secure Authentication request:
- In case you are on “MPGS” processor; four parameters will be returned in the “3D Secure Enrollment”; as below:
• order.id
• transaction.id
• response.gatewayRecommendation
• result
And you have to copy them in the “3D Secure Authentication” request; as you will see in the 3Ds Authentication request example. - In case you are on “Cybersource” processor; two parameters returns in the “3D Secure Enrollment”; as below:
• MD
• TransactionId
And you have to copy them in the “3D Secure Authentication” request; as you will see in the 3Ds Authentication request example.
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:
{
"service_command": "3DS_AUTHENTICATION",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "19",
"language": "en",
"third_party_body": "MD=169996200001204473&PaRes=eAHNV1mzokgW/isVPY9GFTtiB2VEsoqy7/CGiKyCLAry6xuvVbduV1fPdMzDxPhi5seXJ8/Js2XSdtYlCWcl8a1LtrSS9H2UJp/y09ffEIpE1xsU+W1L68BM+i19T7o+b+ot8gX+gtLQ9+myqouzqB62dBS3jKRucYLAcJiGvk3pS9JJ3FYHgaCZNox/tgDDwDCM09DrCw39EKHfnsL6RZkpP21zTNbDlGR3TYHKcWYwZrZZftBeG7/S0JNBn6Ih2aIwisAYjHxC0N8J7HcEoaE3nL4+xYFLc1vUQ4ll00Wtjxi9GN4ldfzYktRi0/uMTqZrUyfPVTT0PqahH+pdo/pp6BpGUAwnyDW1gRfqE6Vtf0sP+eUvauEEDb3hdD9Ew63fBjT0bUTH0f2+TSWRTXFLyJpEyoNWLiRUKwjWLK/KYu4bhU7ifAsvgp7/b6tAlTZdPmSX7WL1k/MDoKGnKtA3/1l5Wi/bdsmn6VLV/dffsmG4/g5B4zh+GbEvTZdC6HJAELyBFsKpz9N/Lc5/rkpOUn1utjQb1U2dx1GVz9GwhIKSDFlz+vS+4a9E2iaEPF3mcZ8XqZ9jBK8/PwEEQYhFPPRrma9937T9J5u89Ebf9e766HOfRc/ghd7Nfgna0mZyTp4+X2KMy9OkH/6bHb5L/yjhuzw3qm7JVuKQu9vMdilzKIJhcbpGAtXfMP5aWpz5Wvdi0tAHld70/X7g77q/iFoh7+tBU/wrdEcFaSUwgZOZ7DjwuIjU2CDGtsqKqTlYxHWsyP1wsdA20q97o2iYMwm3sda0vIzd4U2869GqiSDRyufsgvhd5+DOWSGiAGlNKX/Uj77rhmgmVKPrmMktShwikaQr8rvo9vgZ83kA2StDsTbXpttjzVoLh0ritaZU/W41GJxUZWdSVe9qmiZyIGYGQhiseQz7oArxCdmhh7V2JLITorXXq3E931cjBvr1yUWtx9pjZUnbWyAcGVnD5ImtqkanHt4jAhHUjk5Bzj4sKamN373D5mFNGpEPSLpSk0jMKs+4Fp6E2BeTKofU7DIP23mPtIj1kQpuzUDa5OiS+ml1NuoKfF3c8dNB04fk8Qp5n4A3XDREW/o5YpNuyM9LBiw1R5EkluBYFpQwCwx+5Ixgf2hCKbvH6jLnGQOMMcfLCihFgDg8kyms4ToTx4EDk6ouA1IFIIJicrypAOrFGUfJqPfXGN1nx8tHbrNwTc2Zf3DZhevA7k4STMFBjGk3g9NLrqIIlfk4+SocesZsiy4aehMXicL1mCN7A+bHXRaril1OCscjChfPSiFN3hMr3rDHO1awTPrvbbD/YsOk/MkGcQbhS6/G5qvFhgfDPHWLL0IfeXzqiu584nhFAc3bGbCLVk+7FMsZpTHgXMPg+Gly4nrhiW6pwFN1uri9gWZZ5OGDt5jgoFV9vLiPxSeMVACVScs2K3NxM8LM4gsBAG3xEQWe39n08PQX6NYHCkGmzgqQOnR9arpRbdVbwLiOorW7rFfxYd+scXFG8pBEhBXcV8R1TVGcHwwxlrAaMFwVCdjKb+7a0Zkgx0xx7IDa00q2SG9kAFaWblpuePtkrciNfhkd9bLkxzm7wOcBghSGiFAuPSKMBK8kOe2kfYuNxKxXrkV5gWz1/lkSKndj8lPZS0cN6q0ePNTjXresjUgWnUFi2aoqzc4ocl6HeU5ghHmGXGmvhr25ku5lkxx8MINxH+uyrx6HK9s4skC2vhujVBLKebk+nicYjmbmYKWp1nn+Xj2v++MpEvibo23cRliyEHW8W6yRDDRCF1HR1Pww6tA13OgVZaxza5oITdEJmDmOEgcMwCgAFlmrFS3piHEGzzDAAQAXGQDOu+Cuw4a4rtlpECt53F8lpneZSwW5mBquItHEYUvhCDGa+DXBxgg8846NIgrpbNpjeMh3e0gPCNU2pyEMXe24RqaiKAlYvjR3yql2bX0IzkI0JUwFxgFO+Bi2ncSr1416d308Smdcmafqrt7F9Dgma9dJ72bpz3kjsDDCKAdPnU01FWjo54z/ZQmwi6UEHOO/LQHH+X9YAgoQv5cA929LAGfYIBFGeNJsflRsZ1RnZVLmfbRgjxcmvWPKDkzsDPYvuYENSsFVjHFk07fUXPytmjZvTLwN9BcnVlh+/4h8NQ88ovrAPSxcx66UD9xeYQVVMB+MY7qqo5jUuDNeKc8x4d+mvOWojCKJ55/DDBhvYaYCjmVyY6myBrcjA2a+7Ye1oYSb2l6b6/XGmj19IyaEIc97cjMrMxqt9ceZP4Z41xqE56vuTsenGoEdCbnLtWdxBPvg5TvXBoHu3FJfDK9tHD4wSrB0zVBPTJOXiUGZ3hzFs20lGtIIR0WmUo8b8Ac6sjwKFQ9SqlkHi9hzoXeiUvDhXMF1wOYBUlBc+J9SR5FZOXugj81mqs4rHCB7Rzu2iKQRMdW7CPEAcbpZTjKu7b7ZGwFJKTa8w3ZFtBscp0LKoBNE3Nucr/G4BmzaXYfOBv2A2xZ59/t0ds67MZQN9zyR1GXQqdYVZWPOk1aH9q0vbqqDkCky7DhJCOlrOxNZpERF/mwFrXigDgiRehqzvwae9Q9Tx7WfqYOz7HIvONQVW/ZMrtk/V+9eABxzV4x+ZF+hIfLjnnHtDx0DjJzjTLxiLl341TF2HMjY+FLNwUW4hR+56ci5PGF/4MoL1zadOHV513Y5PlGY8a0TgXF03d0eiTGzCjlVCf2wOvJqE3jVTX6GIIP7nM0Tig0m1QaYMoOHgjQLJr1hSvGOjf+fZYBl6vnn837rlkyx3F7SoFyynAezHqjw0hcaMJwPfR75qCA6Pp7BWrPZRMNSQW+rIHUrCTsKrZCj8OkmQHYQ6kESBPP0aDW0nDjcuFwZLS3Q82w61kawSya6k27rPta2YPsQf+AIffCKZNe3nf6osCWaZwrReyfHdhRnCUZ7PRp3qrhBTM9Fsn6440nN+l4pVDqAD9AmbngWjDwAv4ohoC3lgCXW6GVlQIxeVtXBxFTObYWDhSL7I85IZKYpTkvg2mEuINGQdD2BsEPYkuIpdkfvcmesw9IPq3sfUrcpOjpQz99uZVYpwU6AcvG+u5f720S2hL6Lw2VtPD+Ywq9cHiMk0gqxOjgr8Pjgd6tdbTG6J/cn3zwd3Css8boiQZUWgzyJVdKO3PR5Lf1LB3pDXvdR6P2O+uP2ujx3vr3hl9Gf3vZ/ACJtNGI=",
"signature": "fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b"
}
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'service_command'=> '3DS_AUTHENTICATION',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> '19',
'language'=> 'en',
'third_party_body'=> 'MD=169996200001204473&PaRes=eAHNV1mzokgW/isVPY9GFTtiB2VEsoqy7/CGiKyCLAry6xuvVbduV1fPdMzDxPhi5seXJ8/Js2XSdtYlCWcl8a1LtrSS9H2UJp/y09ffEIpE1xsU+W1L68BM+i19T7o+b+ot8gX+gtLQ9+myqouzqB62dBS3jKRucYLAcJiGvk3pS9JJ3FYHgaCZNox/tgDDwDCM09DrCw39EKHfnsL6RZkpP21zTNbDlGR3TYHKcWYwZrZZftBeG7/S0JNBn6Ih2aIwisAYjHxC0N8J7HcEoaE3nL4+xYFLc1vUQ4ll00Wtjxi9GN4ldfzYktRi0/uMTqZrUyfPVTT0PqahH+pdo/pp6BpGUAwnyDW1gRfqE6Vtf0sP+eUvauEEDb3hdD9Ew63fBjT0bUTH0f2+TSWRTXFLyJpEyoNWLiRUKwjWLK/KYu4bhU7ifAsvgp7/b6tAlTZdPmSX7WL1k/MDoKGnKtA3/1l5Wi/bdsmn6VLV/dffsmG4/g5B4zh+GbEvTZdC6HJAELyBFsKpz9N/Lc5/rkpOUn1utjQb1U2dx1GVz9GwhIKSDFlz+vS+4a9E2iaEPF3mcZ8XqZ9jBK8/PwEEQYhFPPRrma9937T9J5u89Ebf9e766HOfRc/ghd7Nfgna0mZyTp4+X2KMy9OkH/6bHb5L/yjhuzw3qm7JVuKQu9vMdilzKIJhcbpGAtXfMP5aWpz5Wvdi0tAHld70/X7g77q/iFoh7+tBU/wrdEcFaSUwgZOZ7DjwuIjU2CDGtsqKqTlYxHWsyP1wsdA20q97o2iYMwm3sda0vIzd4U2869GqiSDRyufsgvhd5+DOWSGiAGlNKX/Uj77rhmgmVKPrmMktShwikaQr8rvo9vgZ83kA2StDsTbXpttjzVoLh0ritaZU/W41GJxUZWdSVe9qmiZyIGYGQhiseQz7oArxCdmhh7V2JLITorXXq3E931cjBvr1yUWtx9pjZUnbWyAcGVnD5ImtqkanHt4jAhHUjk5Bzj4sKamN373D5mFNGpEPSLpSk0jMKs+4Fp6E2BeTKofU7DIP23mPtIj1kQpuzUDa5OiS+ml1NuoKfF3c8dNB04fk8Qp5n4A3XDREW/o5YpNuyM9LBiw1R5EkluBYFpQwCwx+5Ixgf2hCKbvH6jLnGQOMMcfLCihFgDg8kyms4ToTx4EDk6ouA1IFIIJicrypAOrFGUfJqPfXGN1nx8tHbrNwTc2Zf3DZhevA7k4STMFBjGk3g9NLrqIIlfk4+SocesZsiy4aehMXicL1mCN7A+bHXRaril1OCscjChfPSiFN3hMr3rDHO1awTPrvbbD/YsOk/MkGcQbhS6/G5qvFhgfDPHWLL0IfeXzqiu584nhFAc3bGbCLVk+7FMsZpTHgXMPg+Gly4nrhiW6pwFN1uri9gWZZ5OGDt5jgoFV9vLiPxSeMVACVScs2K3NxM8LM4gsBAG3xEQWe39n08PQX6NYHCkGmzgqQOnR9arpRbdVbwLiOorW7rFfxYd+scXFG8pBEhBXcV8R1TVGcHwwxlrAaMFwVCdjKb+7a0Zkgx0xx7IDa00q2SG9kAFaWblpuePtkrciNfhkd9bLkxzm7wOcBghSGiFAuPSKMBK8kOe2kfYuNxKxXrkV5gWz1/lkSKndj8lPZS0cN6q0ePNTjXresjUgWnUFi2aoqzc4ocl6HeU5ghHmGXGmvhr25ku5lkxx8MINxH+uyrx6HK9s4skC2vhujVBLKebk+nicYjmbmYKWp1nn+Xj2v++MpEvibo23cRliyEHW8W6yRDDRCF1HR1Pww6tA13OgVZaxza5oITdEJmDmOEgcMwCgAFlmrFS3piHEGzzDAAQAXGQDOu+Cuw4a4rtlpECt53F8lpneZSwW5mBquItHEYUvhCDGa+DXBxgg8846NIgrpbNpjeMh3e0gPCNU2pyEMXe24RqaiKAlYvjR3yql2bX0IzkI0JUwFxgFO+Bi2ncSr1416d308Smdcmafqrt7F9Dgma9dJ72bpz3kjsDDCKAdPnU01FWjo54z/ZQmwi6UEHOO/LQHH+X9YAgoQv5cA929LAGfYIBFGeNJsflRsZ1RnZVLmfbRgjxcmvWPKDkzsDPYvuYENSsFVjHFk07fUXPytmjZvTLwN9BcnVlh+/4h8NQ88ovrAPSxcx66UD9xeYQVVMB+MY7qqo5jUuDNeKc8x4d+mvOWojCKJ55/DDBhvYaYCjmVyY6myBrcjA2a+7Ye1oYSb2l6b6/XGmj19IyaEIc97cjMrMxqt9ceZP4Z41xqE56vuTsenGoEdCbnLtWdxBPvg5TvXBoHu3FJfDK9tHD4wSrB0zVBPTJOXiUGZ3hzFs20lGtIIR0WmUo8b8Ac6sjwKFQ9SqlkHi9hzoXeiUvDhXMF1wOYBUlBc+J9SR5FZOXugj81mqs4rHCB7Rzu2iKQRMdW7CPEAcbpZTjKu7b7ZGwFJKTa8w3ZFtBscp0LKoBNE3Nucr/G4BmzaXYfOBv2A2xZ59/t0ds67MZQN9zyR1GXQqdYVZWPOk1aH9q0vbqqDkCky7DhJCOlrOxNZpERF/mwFrXigDgiRehqzvwae9Q9Tx7WfqYOz7HIvONQVW/ZMrtk/V+9eABxzV4x+ZF+hIfLjnnHtDx0DjJzjTLxiLl341TF2HMjY+FLNwUW4hR+56ci5PGF/4MoL1zadOHV513Y5PlGY8a0TgXF03d0eiTGzCjlVCf2wOvJqE3jVTX6GIIP7nM0Tig0m1QaYMoOHgjQLJr1hSvGOjf+fZYBl6vnn837rlkyx3F7SoFyynAezHqjw0hcaMJwPfR75qCA6Pp7BWrPZRMNSQW+rIHUrCTsKrZCj8OkmQHYQ6kESBPP0aDW0nDjcuFwZLS3Q82w61kawSya6k27rPta2YPsQf+AIffCKZNe3nf6osCWaZwrReyfHdhRnCUZ7PRp3qrhBTM9Fsn6440nN+l4pVDqAD9AmbngWjDwAv4ohoC3lgCXW6GVlQIxeVtXBxFTObYWDhSL7I85IZKYpTkvg2mEuINGQdD2BsEPYkuIpdkfvcmesw9IPq3sfUrcpOjpQz99uZVYpwU6AcvG+u5f720S2hL6Lw2VtPD+Ywq9cHiMk0gqxOjgr8Pjgd6tdbTG6J/cn3zwd3Css8boiQZUWgzyJVdKO3PR5Lf1LB3pDXvdR6P2O+uP2ujx3vr3hl9Gf3vZ/ACJtNGI=',
'signature'=> 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'service_command':'3DS_AUTHENTICATION',
'access_code': '{{access_code}}',
'merchant_identifier':'{{merchant_identifier}}',
'merchant_reference': '19',
'language': 'en',
'third_party_body':'MD=11111111111&PaRes=eAHNV1mzokgW/abcdefgh123456781LB3pDXvdR6P2O+uP2ujx3vr3hl9Gf3vZ/=',
'signature': ''
};
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 = {
'service_command'=> '3DS_AUTHENTICATION',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> '19',
'language'=> 'en',
'third_party_body'=> 'MD=11111111111&PaRes=eAHNV1mzokgW/abcdefgh123456781LB3pDXvdR6P2O+uP2ujx3vr3hl9Gf3vZ/=',
'signature'=> ''
};
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)
String jsonRequestString = "{\n \"service_command\": \"3DS_AUTHENTICATION\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"19\",\n \"language\": \"en\",\n \"third_party_body\": \"MD=11111111111&PaRes=eAHNV1mzokgW/abcdefgh123456781LB3pDXvdR6P2O+uP2ujx3vr3hl9Gf3vZ/=\",\n \"signature\": \"\"\n}";
// 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());
ATTRIBUTES | Description |
---|---|
service_command Alpha Mandatory max: 20 |
Command. Possible/ expected values: 3DS_AUTHENTICATION Special characters: _ |
access_code Alphanumeric Mandatory max: 20 |
Access Code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Mandatory max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory max: 40 |
The Merchant’s unique number. *Please, use the same merchant reference you used in the “generate report” request. Example: XYZ9239-yu898 |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
third_party_body Alphanumeric Mandatory Max: 6000 |
Combinations of 3ds parameters from the 3ds_enrollment. Example: Check the examples below Special characters: + \ / : . _ = ? % # & - |
signature Alphanumeric Mandatory max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
3D Secure Authentication Request on Cybersource Processor Example!
3D Secure Authentication Request on MPGS Processor Example!
The following parameters will be returned in Amazon Payment Services’ response:
ATTRIBUTES | Description |
---|---|
service_command Alpha max: 20 |
Command. Possible/ expected values: 3DS_AUTHENTICATION |
access_code Alphanumeric max: 20 |
Access Code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric max: 40 |
The Merchant’s unique reference for a specific request. Example: XYZ9239-yu898 |
language Alpha Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
threeds_id Alphanumeric Max: 100 |
The 3ds operations unique reference. Example: 153606397100001061 |
3ds_enrolled Alpha Max: 1 |
Parameter that hold if the card is enrolled or not. Possible/ expected values: - Y (Yes) - N (No) |
3ds_status Alpha Max: 1 |
The status of the 3ds check just like 3-DSEnrolled but this parameter is available after a check is completed. Possible/ expected values: - Y - N - U - A |
3ds_eci Numeric Max: 2 |
The eCommerce indicator returned from the MPI. Possible/ expected values: - 05 - 06 |
ver_type Alphanumeric Max: 3 |
The type of verification used for 3DS. Possible/ expected values: - 3DS - SPA |
ver_token Alphanumeric Max: 28 |
Verification token generated by the issuer to prove that the cardholders has been authenticated. Example: gIGCg4SFhoeIiYqLjI2Oj5CRkpM= |
signature Alphanumeric max: 200 |
A string hashed using the Secure Hash Algorithm. (Please refer to section Signature for more details). Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
response_message Alphanumeric max: 150 |
Message description of the response code. It returns according to the request language. Example: Insufficient Funds |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 44000 |
status Numeric max: 2 |
A two-digit numeric value that indicates the status of the transaction Possible/ expected values: (Please refer to section statuses). |
ds_transaction_id Alphanumeric Max: 40 |
The Directory Server Transaction ID generated during the authentication transaction. |
3ds_xid Alphanumeric Max: 28 |
Unique transaction Identification number to identify the 3DS transaction. Example: 6kQGHEiZDU0H4+mUWF7zELHAcqM= |
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, STCPAY, and Visa Checkout.
Read more about our support for digital wallets here
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 |
STC PAY
STC Pay, also known as Saudi Telecom Company Pay, is a digital wallet and payment service offered by Saudi Telecom Company (STC). It is a local payment service that is supported in the Kingdom of Saudi Arabia (KSA).
You can use STC Pay (SDK) to perform various financial transactions and payments using the mobile application. Customers can perform transactions on STC Pay using their mobile phone number. One Time Passwords (OTP) sent to the phone numbers are used to authenticate transactions.
Supported Channels
You can integrate STC Pay through the following channels:
Redirection
Redirect your customer to a payment page hosted on the Amazon Payment Services in order to:
Submit the payment details.
Complete the payment.
Re-direct the customer to your website.
Merchant page
Integrating the STC Pay directly into your check-out page enables you to provide a hassle-free payment experience for your customer. The customer can complete the payment while staying within your website without any redirection.
Mobile SDK
Integrating the STC Software Development Kit (SDK) enables your customers to virtually authorize and perform transactions for products and services.
STC PAY And Tokenization
Tokenization is supported on the Redirection and Merchant page channels.
Tokenization is a security measure in the context of payment processing that involves replacing sensitive information (such as credit card details or, in this case, a phone number) with a unique identifier called a token. The token is then used for transactions instead of the actual sensitive information.
Your customer need not enter their phone number to proceed with a checkout. Instead, the customer’s phone number is displayed (masked format) on the checkout screen.
Tokenization work-flow
1 The customer is required to successfully make the initial payment through STC PAY, a transaction that is always safeguarded by the obligatory request for a One-Time Password (OTP). Additionally, it is mandatory for the customer to activate tokenization within their STC Pay app.
2 For the subsequent customer payment, the saved phone number will be displayed on the checkout page, enabling a direct payment process without the need to input the OTP number.
For more information, see:
Checkout Workflows
Redirection checkout using a one-time PIN
Upon your customer’s readiness to make a payment, your website redirects them to the payment page of Amazon Payment Services. Subsequently, the customer completes their payment details in a two-step process facilitated by Amazon Payment Services.
1 Your customer provides their phone number on the payment page of Amazon Payment Services. This action triggers the generation of an STC Pay OTP code, delivered to your customer via SMS.
2 In the next screen, your customer adds the OTP to finalize the payment process. The customer is then redirected back to your website.
Redirection checkout flow using a token
1 To initiate the first customer payment, use the STC PAY redirection API. This involves simulating a successful payment by providing the correct customer OTP. It is mandatory to confirm the active tokenization in the customer’s STC Pay app. Upon successful completion, the response will include the additional parameter token_name.
2 For the subsequent customer payment, the customer selects their masked phone number to finalize the transaction seamlessly in a singular step. The STC PAY redirection API should contain the token_name that obtained from the initial checkout.
Merchant page integration checkout flow using a one-time PIN
To build your own payment page without token, perform the following steps to process payments:
1 Your server sends a OTP generation request to the Amazon Payment Services server. Ensure that the request contains the customer’s phone number. Amazon Payment Services generates an OTP based on the provided phone number, which is then dispatched to the customer’s mobile device via SMS. Subsequently, the customer adds the received OTP on your checkout page.
2 After the successful validation of the OTP, send a purchase request to Amazon Payment Services to finalize the payment. Ensure to include the identical merchant reference number used during the OTP request. Once the OTP is validated, send a purchase request to Amazon Payment Services to complete the payment. Ensure to include the same merchant reference number in the request that you used for OTP generation.
Merchant page integration checkout flow using a token
When you build your own payment page and your customer completes a payment using the token, add a purchase request step to your checkout process. As the OTP has been successfully validated, you can expedite the payment process by directly submitting a purchase request to Amazon Payment Services. This streamlines the customer’s purchase experience, bypassing the need for further OTP authentication.
STCPAY Redirection
Redirection URLs
Test Environment URL:
Test URL: https://sbcheckout.payfort.com/FortAPI/paymentPage
Production Environment URL:
Production URL: https://checkout.payfort.com/FortAPI/paymentPage
Parameters Submission Type
HTTPs Form Post Request.
Purchase - Request
{
{
"amount": "68557",
"digital_wallet": "STCPAY",
"signature": "{{signature}}",
"merchant_identifier": "{{merchant_identifier}}",
"access_code": "FIX7skJDGmjJF0WDh2oB",
"customer_ip": "127.0.0.1",
"language": "en",
"otp": "12345",
"command": "PURCHASE",
"merchant_reference": "merchantTest-10117",
"customer_email": "merchant07@merchantdomain.com",
"return_url": "http://127.0.0.1/merchantSHEK/payment/stcResponse",
"currency": "SAR",
"phone_number": "0551111111",
"remember_me": "YES"
}
}
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
{
'amount'=> '68557',
'digital_wallet'=> 'STCPAY',
'signature'=> '{{signature}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'access_code'=> 'FIX7skJDGmjJF0WDh2oB',
'customer_ip'=> '127.0.0.1',
'language'=> 'en',
'otp'=> '12345',
'command'=> 'PURCHASE',
'merchant_reference'=> 'merchantTest-10117',
'customer_email'=> 'merchant07@merchantdomain.com',
'return_url'=> 'http://127.0.0.1/merchantSHEK/payment/stcResponse',
'currency'=> 'SAR',
'phone_number'=> '0551111111',
'remember_me'=> 'YES'
}
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData =
{
'amount: '68557',
'digital_wallet: 'STCPAY',
'signature: '{{signature}}',
'merchant_identifier: '{{merchant_identifier}}',
'access_code: 'FIX7skJDGmjJF0WDh2oB',
'customer_ip: '127.0.0.1',
'language: 'en',
'otp: '12345',
'command: 'PURCHASE',
'merchant_reference: 'merchantTest-10117',
'customer_email: 'merchant07@merchantdomain.com',
'return_url: 'http://127.0.0.1/merchantSHEK/payment/stcResponse',
'currency: 'SAR',
'phone_number: '0551111111',
'remember_me: 'YES'
};
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 =
{
'amount'=> '68557',
'digital_wallet'=> 'STCPAY',
'signature'=> '{{signature}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'access_code'=> 'FIX7skJDGmjJF0WDh2oB',
'customer_ip'=> '127.0.0.1',
'language'=> 'en',
'otp'=> '12345',
'command'=> 'PURCHASE',
'merchant_reference'=> 'merchantTest-10117',
'customer_email'=> 'merchant07@merchantdomain.com',
'return_url'=> 'http://127.0.0.1/merchantSHEK/payment/stcResponse',
'currency'=> 'SAR',
'phone_number'=> '0551111111',
'remember_me'=> 'YES'
}
;
arrData.each {|key, value|
puts key +value ;
}
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)
String jsonRequestString = "{\n \"amount\": \"68557\",\n \"digital_wallet\": \"STCPAY\",\n \"signature\": \"\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"access_code\": \"FIX7skJDGmjJF0WDh2oB\",\n \"customer_ip\": \"127.0.0.1\",\n \"language\": \"en\",\n \"otp\": \"12345\",\n \"command\": \"PURCHASE\",\n \"merchant_reference\": \"merchantTest-10117\",\n \"customer_email\": \"merchant07@merchantdomain.com\",\n \"return_url\": \"http://127.0.0.1/merchantSHEK/payment/stcResponse\",\n \"currency\": \"SAR\",\n \"phone_number\": \"0551111111\",\n \"remember_me\": \"YES\"\n}";
// 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());
Parameter | Description |
---|---|
command Alpha Mandatory Max: 20 |
A command. Possible/expected values: PURCHASE |
access_code Alphanumeric Mandatory Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
digital_wallet Alpha Mandatory Max: 20 |
Digital wallet used for transaction. Possible/expected value: STCPAY |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Possible/expected value: SAR |
token_name Alphanumeric Optional Max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp Special characters: . @ - _ |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/expected value: en/ ar |
customer_email Alphanumeric Mandatory Max: 254 |
The customer’s email. Example: customer1@domain.com Special characters: _ - . @ + |
customer_ip Alphanumeric Optional max: 45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf Special characters: . : |
signature Alphanumeric Mandatory Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
order_description Alphanumeric Optional Max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
customer_name Alpha Optional Max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' Space |
merchant_extra Alphanumeric Optional Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra1 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra2 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra3 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra4 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
remember_me Alpha Optional Max: 2 |
This parameter provides you with an indication to whether to save this token for the user based on the user selection. Possible/expected value: -YES -NO |
payment_option Alpha Optional Max: 10 |
Payment option. Possible/expected value: STCPAY |
phone_number Alphanumeric Optional max: 19 |
The customer’s phone number. |
settlement_reference Alphanumeric Optional max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 Special characters: - _ . |
return_url Alphanumeric Optional Max: 400 |
The URL of the Merchant’s page that will be displayed to the customer when the order is processed. Example: https://www.merchant.com Special characters: $ ! = ? # & - _ / : . |
Redirection - Response
The following parameters will be returned in PayFort’s Response:
Paremeter | Description |
---|---|
command Alpha Max: 20 |
A command. Possible/expected value: PURCHASE |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
response_message Alphanumeric Max: 150 |
The message description of the response code; it returns according to the request language. Possible/expected value: Please refer to section messages |
access_code Alphanumeric Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
digital_wallet Alpha Max: 20 |
Digital wallet used for transaction. Possible/expected value: STCPAY |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
amount Numeric Max: 10 |
The transaction’s amount. Example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Possible/expected value: SAR |
language Alpha Max: 2 |
The checkout page and messages language. Possible/expected value: en/ ar |
customer_email Alphanumeric Max: 254 |
The customer’s email. Example: customer1@domain.com |
customer_ip Alphanumeric max: 45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf |
signature Alphanumeric Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
eci Alpha Max: 16 |
Ecommerce indicator. Possible/expected value: ECOMMERCE |
payment_option Alpha Max: 10 |
Payment option. Possible/expected value: STCPAY |
fort_id Numeric Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/expected value: Please refer to section statuses |
token_name Alphanumeric max: 100 |
The Token received from the Tokenization process. Example: COp9Vmp |
order_description Alphanumeric Max: 150 |
A description of the order. Example: iPhone 6-S |
customer_name Alpha Max: 40 |
The customer’s name. Example: John Smith |
merchant_extra Alphanumeric Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra1 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra2 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra3 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra4 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
remember_me Alpha Max: 3 |
This parameter provides you with an indication to whether to save this token for the user based on the user selection. Possible/expected value: -YES -NO |
phone_number Alphanumeric max: 19 |
The customer’s phone number. It will be returned if it is shared in request. |
settlement_reference Alphanumeric max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 |
STCPAY Merchant Page
Generate OTP URLs
Test Environment URL:
Test URL: https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production Environment URL:
Production URL: https://paymentservices.payfort.com/FortAPI/paymentApi
Parameters Submission Type
REST POST request using JSON.
Generate OTP - Request
{
"amount": "68557",
"service_command": "GENERATE_OTP",
"digital_wallet": "STCPAY",
"signature": "{{signature}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "merchantTest-10090",
"access_code": "{{access_code}}",
"currency": "SAR",
"language": "en",
"phone_number": "0551111111"
}
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
{
'amount'=> '68557',
'service_command'=> 'GENERATE_OTP',
'digital_wallet'=> 'STCPAY',
'signature'=> '{{signature}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> 'merchantTest-10090',
'access_code'=> '{{access_code}}',
'currency'=> 'SAR',
'language'=> 'en',
'phone_number'=> '0551111111'
}
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'amount': '68557',
'service_command': 'GENERATE_OTP',
'digital_wallet': 'STCPAY',
'signature': '{{signature}}',
'merchant_identifier': '{{merchant_identifier}}',
'merchant_reference': 'merchantTest-10090',
'access_code': '{{access_code}}',
'currency': 'SAR',
'language': 'en',
'phone_number': '0551111111'
};
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 =
{
'amount'=> '68557',
'service_command'=> 'GENERATE_OTP',
'digital_wallet'=> 'STCPAY',
'signature'=> '{{signature}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> 'merchantTest-10090',
'access_code'=> '{{access_code}}',
'currency'=> 'SAR',
'language'=> 'en',
'phone_number'=> '0551111111'
}
;
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)
String jsonRequestString = "{\n \"service_command\": \"GENERATE_OTP\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"AbhiTest-10080\",\n \"amount\": \"125000\",\n \"currency\": \"AED\",\n \"language\": \"en\",\n \"customer_email\": \"abhivit@amazon.com\",\n \"request_expiry_date\":\"2022-07-22T15:36:55+03:00\",\n \"notification_type\":\"EMAIL\",\n \"signature\": \"fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b\"\n}";
// 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());
Parameter | Description |
---|---|
service_command Alpha Mandatory Max: 20 |
Command. Possible/expected value: GENERATE_OTP |
access_code Alphanumeric Mandatory Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
amount Numeric Mandatory Max: 10 |
The transaction amount to generate the OTP, this amount must also be used for the purchase transaction. Example: 10000 |
digital_wallet Alpha Mandatory Max: 20 |
Digital wallet used for transaction. Possible/expected value: STCPAY |
signature Alphanumeric Mandatory Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Possible/expected value: SAR |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/expected value: en/ ar |
phone_number Alphanumeric Mandatory max: 19 |
The customer’s phone number. Example: 0548220713 Special characters: + - ( ) Space |
Generate OTP - Response
Parameter | Description |
---|---|
service_command Alpha Max: 20 |
A command. Possible/expected value: GENERATE_OTP |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
response_message Alphanumeric Max: 150 |
The message description of the response code; it returns according to the request language. Possible/expected value: Please refer to section messages |
access_code Alphanumeric Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
amount Numeric Max: 10 |
The transaction’s amount. Example: 10000 |
signature Alphanumeric Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
digital_wallet Alpha Max: 20 |
Digital wallet used for transaction. Possible/expected value: STCPAY |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Possible/expected value: SAR |
language Alpha Max: 2 |
The checkout page and messages language. Possible/expected value: en/ ar |
phone_number Alphanumeric max: 19 |
The customer’s phone number. Example: 0548220713 |
Purchase URLs
Test Environment URL:
Test URL: https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production Environment URL:
Production URL: https://paymentservices.payfort.com/FortAPI/paymentApi
Parameters Submission Type
REST POST request using JSON.
Purchase - Request
{
{
"amount": "68557",
"digital_wallet": "STCPAY",
"signature": "{{signature}}",
"merchant_identifier": "{{merchant_identifier}}",
"access_code": "FIX7skJDGmjJF0WDh2oB",
"customer_ip": "127.0.0.1",
"language": "en",
"otp": "12345",
"command": "PURCHASE",
"merchant_reference": "merchantTest-10117",
"customer_email": "merchant07@merchantdomain.com",
"return_url": "http://127.0.0.1/merchantSHEK/payment/stcResponse",
"currency": "SAR",
"phone_number": "0551111111",
"remember_me": "YES"
}
}
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
{
'amount'=> '68557',
'digital_wallet'=> 'STCPAY',
'signature'=> '{{signature}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'access_code'=> 'FIX7skJDGmjJF0WDh2oB',
'customer_ip'=> '127.0.0.1',
'language'=> 'en',
'otp'=> '12345',
'command'=> 'PURCHASE',
'merchant_reference'=> 'merchantTest-10117',
'customer_email'=> 'merchant07@merchantdomain.com',
'return_url'=> 'http://127.0.0.1/merchantSHEK/payment/stcResponse',
'currency'=> 'SAR',
'phone_number'=> '0551111111',
'remember_me'=> 'YES'
}
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData =
{
'amount: '68557',
'digital_wallet: 'STCPAY',
'signature: '{{signature}}',
'merchant_identifier: '{{merchant_identifier}}',
'access_code: 'FIX7skJDGmjJF0WDh2oB',
'customer_ip: '127.0.0.1',
'language: 'en',
'otp: '12345',
'command: 'PURCHASE',
'merchant_reference: 'merchantTest-10117',
'customer_email: 'merchant07@merchantdomain.com',
'return_url: 'http://127.0.0.1/merchantSHEK/payment/stcResponse',
'currency: 'SAR',
'phone_number: '0551111111',
'remember_me: 'YES'
};
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 =
{
'amount'=> '68557',
'digital_wallet'=> 'STCPAY',
'signature'=> '{{signature}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'access_code'=> 'FIX7skJDGmjJF0WDh2oB',
'customer_ip'=> '127.0.0.1',
'language'=> 'en',
'otp'=> '12345',
'command'=> 'PURCHASE',
'merchant_reference'=> 'merchantTest-10117',
'customer_email'=> 'merchant07@merchantdomain.com',
'return_url'=> 'http://127.0.0.1/merchantSHEK/payment/stcResponse',
'currency'=> 'SAR',
'phone_number'=> '0551111111',
'remember_me'=> 'YES'
}
;
arrData.each {|key, value|
puts key +value ;
}
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)
String jsonRequestString = "{\n \"amount\": \"68557\",\n \"digital_wallet\": \"STCPAY\",\n \"signature\": \"\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"access_code\": \"FIX7skJDGmjJF0WDh2oB\",\n \"customer_ip\": \"127.0.0.1\",\n \"language\": \"en\",\n \"otp\": \"12345\",\n \"command\": \"PURCHASE\",\n \"merchant_reference\": \"merchantTest-10117\",\n \"customer_email\": \"merchant07@merchantdomain.com\",\n \"return_url\": \"http://127.0.0.1/merchantSHEK/payment/stcResponse\",\n \"currency\": \"SAR\",\n \"phone_number\": \"0551111111\",\n \"remember_me\": \"YES\"\n}";
// 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());
Parameter | Description |
---|---|
command Alpha Mandatory Max: 20 |
A command. Possible/expected value: PURCHASE |
access_code Alphanumeric Mandatory Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
digital_wallet Alpha Mandatory Max: 20 |
Digital wallet used for transaction. Possible/expected value: STCPAY |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. This needs to be the same as the amount supplied when generating the OTP. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Possible or Expected Values: SAR |
token_name Alphanumeric Optional Max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp Special characters: . @ - _ |
otp Numeric Mandatory Max: 10 |
OTP sent to your customer’s phone number. The length of the OTP can be 4, 5 or 6 characters. During integration, update the OTP field to be dynamic, so it can accept any length. Example: 1234 |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/expected value: en/ ar |
customer_email Alphanumeric Mandatory Max: 254 |
The customer’s email. Example: customer1@domain.com Special characters: _ - . @ + |
customer_ip Alphanumeric Mandatory max: 45 |
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf Special characters: . : |
signature Alphanumeric Mandatory Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
order_description Alphanumeric Optional Max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
customer_name Alpha Optional Max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' Space |
merchant_extra Alphanumeric Optional Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra1 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra2 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra3 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra4 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
Purchase - Response
Parameter | Description |
---|---|
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
response_message Alphanumeric Max: 150 |
The message description of the response code; it returns according to the request language. Possible/expected value: Please refer to section messages |
access_code Alphanumeric Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
command Alpha Max: 20 |
A command. Possible/expected value: PURCHASE |
digital_wallet Alpha Max: 20 |
Digital wallet used for transaction. Possible/expected value: STCPAY |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
amount Numeric Max: 10 |
The transaction’s amount. Example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Possible or Expected Values: SAR |
language Alpha Max: 2 |
The checkout page and messages language. Possible/expected value: en/ ar |
customer_email Alphanumeric Max: 254 |
The customer’s email. Example: customer1@domain.com |
customer_ip Alphanumeric max: 45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf |
signature Alphanumeric Mandatory Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
eci Alpha Max: 16 |
Ecommerce indicator. Possible/expected value: ECOMMERCE |
payment_option Alpha Max: 10 |
Payment option. Possible/expected value: STCPAY |
fort_id Numeric Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/expected value: Please refer to section statuses |
token_name Alphanumeric max: 100 |
The Token received from the Tokenization process. Example: COp9Vmp |
order_description Alphanumeric Max: 150 |
A description of the order. Example: iPhone 6-S |
customer_name Alpha Max: 40 |
The customer’s name. Example: John Smith |
merchant_extra Alphanumeric Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra1 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra2 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra3 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra4 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
STC PAY SDK
Generate SDK Token
Test Environment URL:
Test URL: https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production Environment URL:
Production URL: https://paymentservices.payfort.com/FortAPI/paymentApi
Parameters Submission Type
REST POST request using JSON.
POST Request
{
"service_command": "SDK_TOKEN",
"device_id": "34354BB0-81C2-493E-9E71-198312EC2149",
"signature": "366b91c3a411968fd8e30e93dae8b4f82195eb635a82c98d50d02fe7947a7178",
"merchant_identifier": "e4c8e0dc",
"access_code": "EVHtwFMINwAMJCZUp54k",
"language": "en"
}
Request Parameters
Parameter | Description |
---|---|
service_command Alphanumeric Max: 20 |
The command. Possible/expected values: SDK_TOKEN |
device_id Alphanumeric Max: 100 |
The unique device identifier. Example: ffffffff-a9fa-0b44-7b27-29e70033c587 |
signature Alphanumeric Max: 100 |
A string hashed using the secure hash algorithm. Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
merchant_identifier Alphanumeric Max: 20 |
ID of the merchant. Example: CycHZxVj |
access_code Alphanumeric Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
language Alphanumeric Max: 250 |
The check-out page and message language. Possible/expected values: en/ ar |
Generate OTP
Test Environment URL:
Test URL: https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production Environment URL:
Production URL: https://paymentservices.payfort.com/FortAPI/paymentApi
Parameters Submission Type
REST POST request using JSON.
POST Request
{
"amount": "100",
"service_command": "GENERATE_OTP",
"digital_wallet": "STCPAY",
"sdk_token": "a8c4a35cfb094bee952b94f4f22bace9",
"merchant_reference": "a8c4a35cfb094bee952b94f4f22bace9",
"merchant_identifier": "e4c8e0dc",
"access_code": "EVHtwFMINwAMJCZUp54k",
"language": "en",
"currency": "SAR",
"phone_number": "0548220713"
}
Request Parameters
Parameter | Description |
---|---|
amount Numeric Max: 100 |
The transaction’s amount. Example: 10000 |
service_command Alphanumeric Max: 20 |
The command. Possible/expected values: STCPAY |
digital_wallet Alpha Mandatory Max: 20 |
Digital wallet used for transaction. Possible/expected value: STCPAY |
sdk_token Alphanumeric Max: 100 |
The SDK token to enable the Amazon Payment Services Mobile SDK. Example: dwp78q3 |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
access_code Alphanumeric Mandatory Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
language Alphanumeric Max: 250 |
The check-out page and message language. Possible/expected values: en/ ar |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
Purchase Request
Test Environment URL:
Test URL: https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production Environment URL:
Production URL: https://paymentservices.payfort.com/FortAPI/paymentApi
Parameters Submission Type
REST POST request using JSON.
POST Request
{
"amount": "100",
"digital_wallet": "STCPAY",
"sdk_token": "a8c4a35cfb094bee952b94f4f22bace9",
"merchant_reference": "a8c4a35cfb094bee952b94f4f22bace9",
"customer_email": "sdasd@mail.com",
"phone_number": "0548220713",
"language": "en",
"otp": "******",
"currency": "SAR",
"command": "PURCHASE"
}
Parameter | Description |
---|---|
digital_wallet Alpha Mandatory Max: 100 |
The buyer’s digital wallet. Possible/expected value: APPLE_PAY Special characters: _ |
sdk_token Alphanumeric Max: 100 |
The SDK token to enable the Amazon Payment Services Mobile SDK. Example: dwp78q3 |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
customer_email Alphanumeric Mandatory Max: 254 |
The customer’s email. Example: customer1@domain.com Special characters: _ - . @ + |
phone_number Alphanumeric Optional max: 19 |
The customer’s phone number. Example: 00962797219966 Special characters: + - ( ) Space |
otp Alphanumeric Mandatory Max: 10 |
OTP sent by mobile. For example, 123456 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
command Alpha Max: 20 |
A command. Possible/expected value: PURCHASE |
Amex Airline Integration
Amazon Payment Services currently offers AMEX as a payment method. For airlines to accept AMEX payments as transactions, airline (addendum) data has to be passed on by merchants in the submission requests to APS.
Purchase Operation
An operation that allows the Merchant to purchase the authorized amount to their account. Multiple purchase requests can be made up to the authorized amount. We only support “Trusted and merchant page” channels for Purchase operations.
How To Purchase An Authorized Amount
1. Using API:
Using Purchase Api Request.
Purchase Operation URLs
Test Environment URL:
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production Environment URL:
https://paymentservices.payfort.com/FortAPI/paymentApi
Operations - Request
Include the following parameters in the request you will send to Amazon Payment Services:
{
"command": "PURCHASE",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "{{$randomPassword}}",
"amount": "200",
"currency": "SAR",
"language": "en",
"customer_email": "test@merchantdomain.com",
"signature": "{{signature}}",
"eci": "ECOMMERCE",
"expiry_date": "3901",
"card_number": "340353278080900",
"card_security_code": "1234",
"airline_data": {
"airline_booking_reference": "12345666",
"airline_document_type": "KENNEL_CHARGE",
"airline_itinerary": {
"itinerary_leg": [
{
"leg_carrier_code": "EK/999",
"leg_conjunction_ticket_number": "12345678911",
"leg_coupon_number": "1",
"leg_departure_airport": "DXB",
"leg_departure_date": "2023-03-18",
"leg_departure_tax": "1000.0",
"leg_departure_time": "01:00:00Z",
"leg_destination_airport": "CAI",
"leg_destination_arrival_date": "2023-03-11",
"leg_destination_arrival_time": "01:00:00Z",
"leg_endorsements_restrictions": "4242342",
"leg_exchange_ticket_number": "12345678922",
"leg_fare": "42342342",
"leg_fare_basis": "4234234",
"leg_fees": "34234234",
"leg_flight_number": "123455",
"leg_stopover_permitted": "true",
"leg_taxes": "100",
"leg_travel_class": "A"
}
],
"itinerary_number_in_party": "2",
"itinerary_origin_country": "UAE"
},
"airline_passengers_list": [
{
"passenger_first_name": "xxxxx",
"passenger_frequent_flyer_number": "131231",
"passenger_last_name": "xxxxxx",
"passenger_middle_name": "xxxxx",
"passenger_specific_information": "hello",
"passenger_title": "SA"
},
{
"passenger_first_name": "xxxxx",
"passenger_frequent_flyer_number": "xxxxx",
"passenger_last_name": "xxxxxx",
"passenger_middle_name": "xxxxx",
"passenger_specific_information": "hi",
"passenger_title": "MNGR"
}
],
"airline_plan_number": "12",
"airline_ticket": {
"ticket_conjunction_ticket_indicator": "false",
"ticket_eTicket": "true",
"ticket_exchanged_ticket_number": "123444444444",
"ticket_issue": {
"issue_address": "32342",
"issue_carrier_code": "ZZ/999",
"issue_carrier_name": "XXXXXX",
"issue_city": "dubai",
"issue_country": "UAE",
"issue_date": "2023-03-10",
"issue_travel_agent_code": "12312312",
"issue_travel_agent_name": "test"
},
"ticket_restricted": "true",
"ticket_tax_or_fee": [
{
"tax_or_fee_amount": "123",
"tax_or_fee_type": "TT1"
}
],
"ticket_ticket_number": "123323487673",
"ticket_total_fare": "11",
"ticket_total_fees": "12",
"ticket_total_taxes": "121"
},
"airline_transaction_type": "EXCHANGE_TICKET"
},
"customer_ip": "10.0.0.1"
}
String jsonRequestString = "{\n \"command\": \"PURCHASE\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"M7bl0CMDio9kuJH\",\n \"amount\": \"200\",\n \"currency\": \"SAR\",\n \"language\": \"en\",\n \"customer_email\": \"test@merchantdomain.com\",\n \"signature\": \"\",\n \"eci\": \"ECOMMERCE\",\n \"expiry_date\": \"3901\",\n \"card_number\": \"340353278080900\",\n \"card_security_code\": \"1234\",\n \"airline_data\": {\n \"airline_booking_reference\": \"12345666\",\n \"airline_document_type\": \"KENNEL_CHARGE\",\n \"airline_itinerary\": {\n \"itinerary_leg\": [\n {\n \"leg_carrier_code\": \"EK/999\",\n \"leg_conjunction_ticket_number\": \"12345678911\",\n \"leg_coupon_number\": \"1\",\n \"leg_departure_airport\": \"DXB\",\n \"leg_departure_date\": \"2023-03-18\",\n \"leg_departure_tax\": \"1000.0\",\n \"leg_departure_time\": \"01:00:00Z\",\n \"leg_destination_airport\": \"CAI\",\n \"leg_destination_arrival_date\": \"2023-03-11\",\n \"leg_destination_arrival_time\": \"01:00:00Z\",\n \"leg_endorsements_restrictions\": \"4242342\",\n \"leg_exchange_ticket_number\": \"12345678922\",\n \"leg_fare\": \"42342342\",\n \"leg_fare_basis\": \"4234234\",\n \"leg_fees\": \"34234234\",\n \"leg_flight_number\": \"123455\",\n \"leg_stopover_permitted\": \"true\",\n \"leg_taxes\": \"100\",\n \"leg_travel_class\": \"A\"\n }\n ],\n \"itinerary_number_in_party\": \"2\",\n \"itinerary_origin_country\": \"UAE\"\n },\n \"airline_passengers_list\": [\n {\n \"passenger_first_name\": \"xxxx\",\n \"passenger_frequent_flyer_number\": \"131231\",\n \"passenger_last_name\": \"xxxxx\",\n \"passenger_middle_name\": \"xxxxx\",\n \"passenger_specific_information\": \"hello\",\n \"passenger_title\": \"SA\"\n },\n {\n \"passenger_first_name\": \"xxxxx\",\n \"passenger_frequent_flyer_number\": \"999\",\n \"passenger_last_name\": \"xxxxx\",\n \"passenger_middle_name\": \"xxxxxx\",\n \"passenger_specific_information\": \"hi\",\n \"passenger_title\": \"MNGR\"\n }\n ],\n \"airline_plan_number\": \"12\",\n \"airline_ticket\": {\n \"ticket_conjunction_ticket_indicator\": \"false\",\n \"ticket_eTicket\": \"true\",\n \"ticket_exchanged_ticket_number\": \"123444444444\",\n \"ticket_issue\": {\n \"issue_address\": \"32342\",\n \"issue_carrier_code\": \"ZZ/999\",\n \"issue_carrier_name\": \"XXXXXX\",\n \"issue_city\": \"dubai\",\n \"issue_country\": \"UAE\",\n \"issue_date\": \"2023-03-10\",\n \"issue_travel_agent_code\": \"12312312\",\n \"issue_travel_agent_name\": \"test\"\n },\n \"ticket_restricted\": \"true\",\n \"ticket_tax_or_fee\": [\n {\n \"tax_or_fee_amount\": \"123\",\n \"tax_or_fee_type\": \"TT1\"\n }\n ],\n \"ticket_ticket_number\": \"123323487673\",\n \"ticket_total_fare\": \"11\",\n \"ticket_total_fees\": \"12\",\n \"ticket_total_taxes\": \"121\"\n },\n \"airline_transaction_type\": \"EXCHANGE_TICKET\"\n },\n \"customer_ip\": \"10.0.0.1\"\n}"
// 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());
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
{
'command'=> 'PURCHASE',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> '{{$randomPassword}}',
'amount'=> '200',
'currency'=> 'SAR',
'language'=> 'en',
'customer_email'=> 'test@merchantdomain.com',
'signature'=> '{{signature}}',
'eci'=> 'ECOMMERCE',
'expiry_date'=> '3901',
'card_number'=> '340353278080900',
'card_security_code'=> '1234',
'airline_data'=> {
'airline_booking_reference'=> '12345666',
'airline_document_type'=> 'KENNEL_CHARGE',
'airline_itinerary'=> {
'itinerary_leg'=> [
{
'leg_carrier_code'=> 'EK/999',
'leg_conjunction_ticket_number'=> '12345678911',
'leg_coupon_number'=> '1',
'leg_departure_airport'=> 'DXB',
'leg_departure_date'=> '2023-03-18',
'leg_departure_tax'=> '1000.0',
'leg_departure_time'=> '01:00:00Z',
'leg_destination_airport'=> 'CAI',
'leg_destination_arrival_date'=> '2023-03-11',
'leg_destination_arrival_time'=> '01:00:00Z',
'leg_endorsements_restrictions'=> '4242342',
'leg_exchange_ticket_number'=> '12345678922',
'leg_fare'=> '42342342',
'leg_fare_basis'=> '4234234',
'leg_fees'=> '34234234',
'leg_flight_number'=> '123455',
'leg_stopover_permitted'=> 'true',
'leg_taxes'=> '100',
'leg_travel_class'=> 'A'
}
],
'itinerary_number_in_party'=> '2',
'itinerary_origin_country'=> 'UAE'
},
'airline_passengers_list'=> [
{
'passenger_first_name'=> 'XXXX',
'passenger_frequent_flyer_number'=> '131231',
'passenger_last_name'=> 'XXXXX',
'passenger_middle_name'=> 'XXXXXX',
'passenger_specific_information'=> 'hello',
'passenger_title'=> 'SA'
},
{
'passenger_first_name'=> 'XXXX',
'passenger_frequent_flyer_number'=> '999',
'passenger_last_name'=> 'XXXX',
'passenger_middle_name'=> 'XXXXX',
'passenger_specific_information'=> 'hi',
'passenger_title'=> 'MNGR'
}
],
'airline_plan_number'=> '12',
'airline_ticket'=> {
'ticket_conjunction_ticket_indicator'=> 'false',
'ticket_eTicket'=> 'true',
'ticket_exchanged_ticket_number'=> '123444444444',
'ticket_issue'=> {
'issue_address'=> '32342',
'issue_carrier_code'=> 'ZZ/999',
'issue_carrier_name'=> 'XXXXXX',
'issue_city'=> 'dubai',
'issue_country'=> 'UAE',
'issue_date'=> '2023-03-10',
'issue_travel_agent_code'=> '12312312',
'issue_travel_agent_name'=> 'test'
},
'ticket_restricted'=> 'true',
'ticket_tax_or_fee'=> [
{
'tax_or_fee_amount'=> '123',
'tax_or_fee_type'=> 'TT1'
}
],
'ticket_ticket_number'=> '123323487673',
'ticket_total_fare'=> '11',
'ticket_total_fees'=> '12',
'ticket_total_taxes'=> '121'
},
'airline_transaction_type'=> 'EXCHANGE_TICKET'
},
'customer_ip'=> '10.0.0.1'
}
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData =
{
'command': 'PURCHASE',
'access_code': '{{access_code}}',
'merchant_identifier': '{{merchant_identifier}}',
'merchant_reference': '{{$randomPassword}}',
'amount': '200',
'currency': 'SAR',
'language': 'en',
'customer_email': 'test@merchantdomain.com',
'signature': '{{signature}}',
'eci': 'ECOMMERCE',
'expiry_date': '3901',
'card_number': '340353278080900',
'card_security_code': '1234',
'airline_data': {
'airline_booking_reference': '12345666',
'airline_document_type': 'KENNEL_CHARGE',
'airline_itinerary': {
'itinerary_leg': [
{
'leg_carrier_code': 'EK/999',
'leg_conjunction_ticket_number': '12345678911',
'leg_coupon_number': '1',
'leg_departure_airport': 'DXB',
'leg_departure_date': '2023-03-18',
'leg_departure_tax': '1000.0',
'leg_departure_time': '01:00:00Z',
'leg_destination_airport': 'CAI',
'leg_destination_arrival_date': '2023-03-11',
'leg_destination_arrival_time': '01:00:00Z',
'leg_endorsements_restrictions': '4242342',
'leg_exchange_ticket_number': '12345678922',
'leg_fare': '42342342',
'leg_fare_basis': '4234234',
'leg_fees': '34234234',
'leg_flight_number': '123455',
'leg_stopover_permitted': 'true',
'leg_taxes': '100',
'leg_travel_class': 'A'
}
],
'itinerary_number_in_party': '2',
'itinerary_origin_country': 'UAE'
},
'airline_passengers_list': [
{
'passenger_first_name': 'XXXX',
'passenger_frequent_flyer_number': '131231',
'passenger_last_name': 'xxxxx',
'passenger_middle_name': 'xxxxxx',
'passenger_specific_information': 'hello',
'passenger_title': 'SA'
},
{
'passenger_first_name': 'XXXX',
'passenger_frequent_flyer_number': '999',
'passenger_last_name': 'XXXX',
'passenger_middle_name': 'XXXm',
'passenger_specific_information': 'hi',
'passenger_title': 'MNGR'
}
],
'airline_plan_number': '12',
'airline_ticket': {
'ticket_conjunction_ticket_indicator': 'false',
'ticket_eTicket': 'true',
'ticket_exchanged_ticket_number': '123444444444',
'ticket_issue': {
'issue_address': '32342',
'issue_carrier_code': 'ZZ/999',
'issue_carrier_name': 'XXXXXX',
'issue_city': 'dubai',
'issue_country': 'UAE',
'issue_date': '2023-03-10',
'issue_travel_agent_code': '12312312',
'issue_travel_agent_name': 'test'
},
'ticket_restricted': 'true',
'ticket_tax_or_fee': [
{
'tax_or_fee_amount': '123',
'tax_or_fee_type': 'TT1'
}
],
'ticket_ticket_number': '123323487673',
'ticket_total_fare': '11',
'ticket_total_fees': '12',
'ticket_total_taxes': '121'
},
'airline_transaction_type': 'EXCHANGE_TICKET'
},
'customer_ip': '10.0.0.1'
};
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'=> 'PURCHASE',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> '{{$randomPassword}}',
'amount'=> '200',
'currency'=> 'SAR',
'language'=> 'en',
'customer_email'=> 'test@merchantdomain.com',
'signature'=> '{{signature}}',
'eci'=> 'ECOMMERCE',
'expiry_date'=> '3901',
'card_number'=> '340353278080900',
'card_security_code'=> '1234',
'airline_data'=> {
'airline_booking_reference'=> '12345666',
'airline_document_type'=> 'KENNEL_CHARGE',
'airline_itinerary'=> {
'itinerary_leg'=> [
{
'leg_carrier_code'=> 'EK/999',
'leg_conjunction_ticket_number'=> '12345678911',
'leg_coupon_number'=> '1',
'leg_departure_airport'=> 'DXB',
'leg_departure_date'=> '2023-03-18',
'leg_departure_tax'=> '1000.0',
'leg_departure_time'=> '01:00:00Z',
'leg_destination_airport'=> 'CAI',
'leg_destination_arrival_date'=> '2023-03-11',
'leg_destination_arrival_time'=> '01:00:00Z',
'leg_endorsements_restrictions'=> '4242342',
'leg_exchange_ticket_number'=> '12345678922',
'leg_fare'=> '42342342',
'leg_fare_basis'=> '4234234',
'leg_fees'=> '34234234',
'leg_flight_number'=> '123455',
'leg_stopover_permitted'=> 'true',
'leg_taxes'=> '100',
'leg_travel_class'=> 'A'
}
],
'itinerary_number_in_party'=> '2',
'itinerary_origin_country'=> 'UAE'
},
'airline_passengers_list'=> [
{
'passenger_first_name'=> 'XXXXX',
'passenger_frequent_flyer_number'=> '131231',
'passenger_last_name'=> 'XXXXX',
'passenger_middle_name'=> 'XXXXX',
'passenger_specific_information'=> 'hello',
'passenger_title'=> 'SA'
},
{
'passenger_first_name'=> 'XXXXX',
'passenger_frequent_flyer_number'=> '999',
'passenger_last_name'=> 'XXXXX',
'passenger_middle_name'=> 'XXXXX',
'passenger_specific_information'=> 'hi',
'passenger_title'=> 'MNGR'
}
],
'airline_plan_number'=> '12',
'airline_ticket'=> {
'ticket_conjunction_ticket_indicator'=> 'false',
'ticket_eTicket'=> 'true',
'ticket_exchanged_ticket_number'=> '123444444444',
'ticket_issue'=> {
'issue_address'=> '32342',
'issue_carrier_code'=> 'ZZ/999',
'issue_carrier_name'=> 'XXXXX',
'issue_city'=> 'dubai',
'issue_country'=> 'UAE',
'issue_date'=> '2023-03-10',
'issue_travel_agent_code'=> '12312312',
'issue_travel_agent_name'=> 'test'
},
'ticket_restricted'=> 'true',
'ticket_tax_or_fee'=> [
{
'tax_or_fee_amount'=> '123',
'tax_or_fee_type'=> 'TT1'
}
],
'ticket_ticket_number'=> '123323487673',
'ticket_total_fare'=> '11',
'ticket_total_fees'=> '12',
'ticket_total_taxes'=> '121'
},
'airline_transaction_type'=> 'EXCHANGE_TICKET'
},
'customer_ip'=> '10.0.0.1'
};
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)
ATTRIBUTES | Description |
---|---|
command Alpha Mandatory max: 20 |
Command. Possible/ expected values: PURCHASE. Please refer to this section to know more about the differences. |
access_code Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: zx0IPmPy5jp1vAz |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Mandatory Max: 254 |
The customer’s email. Example: customer@domain.com Special characters: _ - . @ + |
customer_ip Alphanumeric Mandatory max: 45 |
It holds the customer’s IP address. *It’s Mandatory, if the fraud service is active. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf Special characters: . : |
token_name Alphanumeric Mandatory Max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp Special characters: _ - . @ |
signature Alphanumeric Mandatory Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
payment_option Alpha Optional Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) |
eci Alpha Optional Max: 16 |
Ecommerce indicator. Possible/ expected values: - ECOMMERCE - MOTO - RECCURING |
order_description Alphanumeric Optional Max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
card_security_code Numeric Optional Max: 4 |
A security code for the card. * Only AMEX accepts card security code of 4 digits. Example: 123 |
customer_name Alpha Optional Max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' Space |
merchant_extra Alphanumeric Optional Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra1 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra2 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra3 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra4 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
merchant_extra5 Alphanumeric Optional Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith Special characters: . ; / _ - , ' @ |
remember_me Alpha Optional Max: 3 |
This parameter provides you with an indication to whether to save this token for the user based on the user selection. *The Tokenization service MUST be activated in order to be able to send “remember_me” parameter. Possible/ expected values: -YES -NO |
phone_number Alphanumeric Optional max: 19 |
The customer’s phone number. Example: 00962797219966 Special characters: + - ( ) Space |
settlement_reference Alphanumeric Optional max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 Special characters: - _ . |
return_url Alphanumeric Optional Max: 400 |
The URL of the Merchant’s page to be displayed to the customer when the order is processed. Example: https://www.merchant.com Special characters: $ ! = ? # & - _ / : . |
billing_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric Optional max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric Optional |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric Optional |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric Optional max: 100 |
The city portion of the address. |
agreement_id Alphanumeric Optional max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
recurring_mode Alphanumeric Optional max: 20 |
Indicates if the subsequent payments within the agreement has same/different amount or unscheduled (unknown interval/amount). Possible/ expected values: UNSCHEDULED, VARIABLE, FIXED |
recurring_transactions_count Alphanumeric Optional max: 100 |
The number of merchant-initiated payments within the recurring payment agreement. ( Required only if recurring_mode = VARIABLE or FIXED ) |
recurring_expiry_date |
The date where the merchant needs to end the recurring. The format is YY-MM-DD [Numeric] with special character - |
recurring_days_between_payments |
The number of days between payments agreed with the payer under your agreement with them. The allowed data type is: Numeric only. |
airline_data List Optional |
List of parameters you can pass for the airline to process a transaction |
Parameters for the airline_data parameters:
ATTRIBUTES | Description |
---|---|
airline_booking_reference Alphanumeric Max: 15 |
The record locator used to access a specific Passenger Name Record (PNR) Example: 12345666 |
airline_document_type Alpha Optional |
The type of charge associated with the transaction. Example: ADDITIONAL_COLLECTION: Additional Collection AGENCY_EXCHANGE_ORDER: Agency Exchange Order AGENCY_GROUP_TICKET: Agency Group Ticket AGENCY_MISCELLANEOUS_CHARGE_ORDER: Agency Misc. Charge Order (MCO) AGENCY_PASSENGER_TICKET: Agency Passenger Ticket AGENCY_TOUR_ORDER_OR_VOUCHER: Agency Tour Order/Voucher AIR_FREIGHT SPD: Air Freight ANIMAL_TRANSPORTATION_CHARGE: Animal Transportation Charge CATALOGUE_MERCHANDISE_ORDERED: Catalogue Merchandise Ordered CLUB_MEMBERSHIP_FEE: Club Membership Fee COUPON_BOOK: Coupon Book CREDIT_CLASS_SERVICE_ADJUSTMENT: Credit Class of Service Adjustment CREDIT_DENIED_BOARDING: Credit Denied Boarding CREDIT_EXCHANGE_REFUND: Credit Exchange Refund CREDIT_LOST_TICKET_REFUND: Credit Lost Ticket Refund CREDIT_MISCELLANEOUS_REFUND: Credit Misc. Refund CREDIT_MULTIPLE_UNUSED_TICKETS: Credit Multiple Unused Tickets CREDIT_OVERCHARGE_ADJUSTMENT: Credit Overcharge Adjustment CREDIT_UNUSED_TRANSPORTATION: Credit Unused Transportation DEBT_ADJUSTMENT_DUPLICATE_REFUND_OR_USE: Debt Adjustment Duplicate Refund/Use DUTY_FREE_SALE: Duty Free Sale EXCESS_BAGGAGE: Excess Baggage EXCHANGE_ADJUSTMENT: Exchange Adjustment EXCHANGE_ORDER: Exchange Order FIREARMS_CASE Firearms: Case FREQUENT_FLYER_FEE_OR_PURCHASE: Frequent Flyer Fee/Purchase FREQUENT_FLYER_FULFILLMENT: Frequent Flyer Fulfillment FREQUENT_FLYER_OVERNIGHT_DELIVERY_CHARGE: Frequent Flyer Overnight Delivery Charge GROUP_TICKET: Group Ticket IN_FLIGHT_ADJUSTMENT: In-flight Adjustment IN_FLIGHT_CHARGES: In-flight Charges IN_FLIGHT_DUTY_FREE_PURCHASE: In-flight Duty Free Purchase IN_FLIGHT_MERCHANDISE_ORDERED: In-flight Merchandise Ordered IN_FLIGHT_PHONE_CHARGES: In-flight Phone Charges KENNEL_CHARGE: Kennel Charge LOST_TICKET_APPLICATION: Lost Ticket Application MISCELLANEOUS_CHARGE_ORDER_OR_PREPAID_TICKET_ADVICE: Misc. Charge Order (MCO) / Prepaid Ticket Auth. MISCELLANEOUS_TAXES_FEES: Miscellaneous Tax(es) Fee(s) PASSENGER_TICKET: Passenger Ticket SELF_SERVICE_TICKETS: Self-Service Ticket(s) SENIOR_CITIZEN_DISCOUNT_BOOKLETS: Senior Citizen Discount Booklets SMALL_PACKAGE_DELIVERY: Small Package Delivery SPECIAL_SERVICE_TICKET: Special Service Ticket SUPPORTED_REFUND: Supported Refund TICKET_BY_MAIL: Ticket by Mail TOUR_DEPOSIT: Tour Deposit TOUR_ORDER_VOUCHER: Tour Order Voucher UNDERCHARGE_ADJUSTMENT: Undercharge Adjustment UNSUPPORTED_REFUND: Unsupported Refund UPGRADE_CHARGE: Upgrade Charge VENDOR_REFUND_CREDIT: Vendor Refund Credit VENDOR_SALE: Vendor Sale |
airline_itinerary List Optional |
Itinerary details |
airline_passengers_list Array |
Passenger details. |
airline_plan_number Alphanumeric max: 2 |
Plan number supplied by the airline for this booking. Example: 12 |
airline_ticket List |
Ticket details. |
airline_transaction_type Alphanumeric |
The type of transaction performed against this airline booking. EXCHANGE_TICKET MISCELLANEOUS_CHARGE TICKET_PURCHASE TOUR_ORDER |
Parameters for the airline_itinerary:
ATTRIBUTES | Description |
---|---|
itinerary_number_in_party Integer max:3 |
Number of passengers associated with this booking. This parameter is to be passed within airline_itinerary. Example: 1 |
itinerary_origin_country Alpha max:3 |
The 3 character ISO 3166-1 alpha-3 country code of the country of origin for the itinerary. This parameter is to be passed within airline_itinerary. Example: UAE |
itinerary_leg Array Optional |
Travel leg details. This parameter is to be passed within airline_itinerary. |
Parameters for the itinerary_leg:
ATTRIBUTES | Description |
---|---|
leg_carrier_code Alphanumeric Max: 6 |
The 2-character IATA airline code or 3 digit accounting code or both of the airline carrier for the trip leg. Example: EK/999 |
leg_conjunction_ticket_number Alphanumeric Max:16 |
The ticket containing the coupon for this leg for an itinerary with more than four trip legs. Example: 12345678911 |
leg_coupon_number Alphanumeric Max:1 |
The coupon number on the ticket for the trip leg. Example: 1 |
leg_departure_airport Alpha Max:3 |
The 3 character IATA airport code of the departure airport for the trip leg. Example: DXB |
leg_departure_date Alphanumeric Max:10 |
Date of departure for the trip leg. Example: “2023-03-18" |
leg_departure_tax Alphanumeric Max:14 |
Tax payable on departure for the trip leg. Example: 10000 |
leg_departure_time Alphanumeric Max:9 |
Departure time in local time for the departure airport for this trip leg. Example: 01:00:00Z |
leg_destination_airport Alpha Max:3 CAI |
The 3 character IATA airport code for the destination airport for the trip leg. Example: CAI |
leg_destination_arrival_date Alphanumeric Max:10 |
Arrival date in local time for the destination airport for this trip leg. Example: “2023-03-18" |
leg_destination_arrival_time Alphanumeric Max:9 |
Arrival time in local time for the destination airport for this trip leg. Example: 01:00:00Z |
leg_endorsements_restrictions Alphanumeric Max:20 |
Restrictions (e.g. non-refundable) or endorsements applicable to the trip leg. Example: 4242342 |
leg_exchange_ticket_number Alphanumeric Max:16 |
New ticket number issued when a ticket is exchanged for the trip leg. Example: 12345678922 |
leg_fare Integer Max:14 |
Total fare payable for the trip leg. Example: 42342342 |
leg_fare_basis Alphanumeric Max:24 |
Code defining the rules forming the basis of the fare (type of fare, class entitlement, etc.) Example: 42342342 |
leg_fees Alphanumeric Max:14 |
Total fees payable for the trip leg. Example: 11.22 |
leg_flight_number Alphanumeric Max:6 |
The flight number for the trip leg. Example: 123455 |
leg_stopover_permitted Alpha Max:5 false |
Indicates if a stopover is permitted for the trip leg. Example: true |
leg_taxes Alphanumeric Max:14 |
Total taxes payable for the trip leg. Example: 11.22 |
leg_travel_class Alphanumeric max:3 |
The industry code indicating the class of service (e.g. Business, Coach) for the leg. Example: A |
Parameters for airline_passengers_list
Attributes | Description |
---|---|
passenger_first_name Alphanumeric max: 50 |
First name of the passenger to whom the ticket is being issued. Example: XXXXX |
passenger_frequent_flyer_number Alphanumeric max:20 |
Frequent Flyer or Loyalty Program number for this passenger. Example: 131231 |
passenger_last_name Alphanumeric max: 20 |
Last name of the passenger to whom the ticket is being issued. Example: XXXX |
passenger_middle_name Alphanumeric max:50 |
Middle name of the passenger to whom the ticket is being issued. Example: XXXXXX |
passenger_specific_information Alphanumeric max: 59 |
Passenger specific information recorded on the ticket. Example: VVVV |
passenger_title Alphanumeric max: 20 |
Title of the passenger to whom the ticket is being issued. Example: MR |
Parameters for the airline_ticket
Attributes | Description |
---|---|
ticket_issue List |
Ticket issue information. |
ticket_ticket_number Alphanumeric max:16 | The airline ticket number associated with the transaction. Example: 123323487673 |
ticket_conjunction_ticket_indicator Alpha Max:5 |
Indicates whether a conjunction ticket with additional coupons was issued. Example: false |
ticket_eTicket Alpha max: 5 |
Indicates if an electronic ticket was issued. Example: true |
ticket_exchanged_ticket_number Alphanumeric max:16 |
The original ticket number when this is a transaction for an exchanged ticket. Example: 123444444444 |
ticket_total_fare Alphanumeric max:14 |
Total fare for all trip legs on the ticket. Example: 11 |
ticket_total_fees Alphanumeric max:14 |
Total fare for all trip legs on the ticket. Exmple: 12 |
ticket_total_taxes Alphanumeric max:14 |
Total taxes for all trip legs on the ticket. Example: 121 |
ticket_restricted Alpha max:5 |
Indicates if the issued ticket is refundable. Example: true |
ticket_tax_or_fee Array |
Breakdown of the ticket taxes, airport taxes, charges and fees for an airline ticket purchase.The total of the amounts in this group should equal the sum of the airline.ticket.totalFees and airline.ticket.totalTaxes fields. |
Parameters for the ticket_tax_or_fee
Attributes | Description |
---|---|
tax_or_fee_amount Alphanumeric max:14 |
The tax, charge or fee amount payable. Part of the ticket_tax_or_fee list. Example: 123 |
tax_or_fee_type Alphanumeric max:3 |
The tax, charge or fee type code as assigned by IATA.Part of the ticket_tax_or_fee list. Example: TT1 |
Parameters for the ticket_issue
Attributes | Description |
---|---|
issue_address Alphanumeric max:16 |
The address where the ticket was issued. Example: 32342 |
issue_carrier_code Alphanumeric max:6 |
The 2-character IATA airline code or 3 digit accounting code or both of the airline carrier issuing the ticket. Example: ZZ/999 |
issue_carrier_name Alphanumeric max:25 |
Name of airline carrier issuing the ticket. Example: CCCC |
issue_city Alphanumeric max:100 |
The city/town where the ticket was issued. Example: dubai |
issue_country Alphanumeric max:3 |
The 3 character ISO 3166-1 alpha-3 country code of the country where the ticket was issued. Example: UAE |
issue_date Alphanumeric max:10 |
The date the ticket was issued. Example: “2023-03-10" |
issue_travel_agent_code Alphanumeric max:9 |
Industry code of the travel agent issuing the ticket. Example: 12312312 |
issue_travel_agent_name Alphanumeric max: 30 |
Name of the travel agent issuing the ticket. Example: test |
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'command' => 'PURCHASE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
'customer_email' => 'test@payfort.com',
'signature' => 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b',
'token_name' => '7288fc8155014c57ad809d8e9574575e'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'command':'PURCHASE',
'access_code':'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier':'CycHZxVj',
'merchant_reference':'XYZ9239-yu898',
'language':'en',
'signature':'7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description':'iPhone 6-S',
'customer_email':'test@payfort.com',
'signature' : 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b',
'token_name' : '7288fc8155014c57ad809d8e9574575e'
};
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' => 'PURCHASE',
'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
'merchant_identifier' => 'CycHZxVj',
'merchant_reference' => 'XYZ9239-yu898',
'language' => 'en',
'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
'order_description' => 'iPhone 6-S',
'customer_email => 'test@payfort.com',
'signature' => 'fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b',
'token_name' => '7288fc8155014c57ad809d8e9574575e'
};
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)
String jsonRequestString = "{\n \"command\": \"PURCHASE\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"Abhitest-10052\",\n \"amount\": \"20000\",\n \"currency\": \"AED\",\n \"language\": \"en\",\n \"customer_email\": \"test@payfort.com\",\n \"signature\": \"fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b\",\n \"token_name\": \"7288fc8155014c57ad809d8e9574575e\"\n}";
// 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());
{
"command": "PURCHASE",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "Abhitest-10052",
"amount": "20000",
"currency": "AED",
"language": "en",
"customer_email": "test@payfort.com",
"signature": "fb466699104651adb8c3eace5a3d8ea8e2dbd4739330b7379a6ece4956bed14b",
"token_name": "7288fc8155014c57ad809d8e9574575e"
}
Operations - Response
The following parameters will be returned in Amazon Payment Services’s response:
ATTRIBUTES | Description |
---|---|
command Alpha max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
access_code Alphanumeric Max: 20 |
The ID of the Merchant. Example: zx0IPmPy5jp1vAz |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
amount Numeric Max: 10 |
The transaction’s amount. Example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Max: 254 |
The customer’s email. Example: customer1@domain.com |
customer_ip Alphanumeric max: 45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf |
token_name Alphanumeric max: 100 |
The Token received from the Tokenization process. Example: COp9Vmp |
signature Alphanumeric Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
fort_id Numeric Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
payment_option Alpha Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) |
eci Alpha Max: 16 |
Ecommerce indicator. Possible/ expected values: - ECOMMERCE - MOTO - RECCURING |
order_description Alphanumeric Max: 150 |
A description of the order. Example: iPhone 6-S |
authorization_code Alphanumeric Max: 100 |
The authorization code returned from the 3rd party. Example: P1000000000000372136 |
response_message Alphanumeric Max: 150 |
Message description of the response code. It returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
customer_name Alpha Max: 40 |
The customer’s name. Example: John Smith |
merchant_extra Alphanumeric Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra1 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra2 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra3 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra4 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra5 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
expiry_date Numeric Max: 4 |
The card’s expiry date. Example: 2105 |
card_number Numeric Max: 19 |
The masked credit card’s number. Only the MEEZA payment option takes 19 digits card number. *AMEX payment option takes 15 digits card number. *Otherwise, they take 16 digits card number. Example: 400555*****0001 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
card_holder_name Alpha Max: 50 |
The card holder name. Example: John Smith |
3ds_url Alphanumeric Max: 300 |
The URL where the Merchant redirects a customer whose card is 3D Secure for authentication. Example: https://www.3dsecure.com |
remember_me Alpha Max: 3 |
This parameter provides you with an indication to whether to save this token for the user based on the user selection. Possible/ expected values: -YES -NO |
phone_number Alphanumeric max: 19 |
The customer’s phone number. Example: 00962797219966 |
settlement_reference Alphanumeric max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 |
billing_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. Reference: ISO_3166-2 Example1: AMMAN Example2: TALFILAH |
billing_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. Reference: ISO_3166-2 Example1: AM Example2: AT |
billing_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
billing_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
billing_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
billing_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
billing_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
billing_city Alphanumeric Optional max: 100 |
The city portion of the address. |
shipping_stateProvince Alphanumeric Optional max: 20 |
The state or province of the address. |
shipping_provinceCode Alphanumeric Optional max: 3 |
The three character ISO 3166-2 country subdivision code for the state or province of the address. Providing this field might improve your payer experience for 3-D Secure payer authentication. |
shipping_street Alphanumeric Optional max: 100 |
The first line of the address. For example, this may be the street name and number, or the Post Office Box details. |
shipping_street2 Alphanumeric Optional max: 100 |
The second line of the address (if provided). |
shipping_source Alphanumeric Optional |
How you obtained the shipping address. Possible/ expected values: NEW_ADDRESS, ADDRESS_ON_FILE |
shipping_sameAsBilling Alphanumeric Optional |
Indicates whether the shipping address provided is the same as the payer’s billing address. Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different. Possible/ expected values: DIFFERENT, SAME, UNKNOWN |
shipping_postcode Alphanumeric Optional max: 10 |
The post code or zip code of the address. |
shipping_country Alphanumeric Optional min:3, max: 3 |
The 3 letter ISO standard Alphanumeric country code of the address. |
shipping_company Alphanumeric Optional max: 100 |
The name of the company associated with this address. |
shipping_city Alphanumeric Optional max: 100 |
The city portion of the address. |
agreement_id Alphanumeric max: 100 |
identifier for the agreement with the payer to process payments to be used in recurring payments |
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. We only support “Trusted and merchant page” channels for Purchase operations.
How To Capture An Authorized Amount
1. Using API:
Using Capture Api Request.
Capture Operation URLs
Test Environment URL:
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production Environment URL:
https://paymentservices.payfort.com/FortAPI/paymentApi
Parameters Submission Type
REST POST request using JSON.
Capture Operation - Request
(Please take a look at the ** Request Example** on the right side of the page.)
Capture Request Example
{
"command": "CAPTURE",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "{{$randomPassword}}",
"amount": "200",
"currency": "SAR",
"language": "en",
"signature": "{{signature}}",
"airline_data": {
"airline_booking_reference": "12345666",
"airline_document_type": "KENNEL_CHARGE",
"airline_itinerary": {
"itinerary_leg": [
{
"leg_carrier_code": "EK/999",
"leg_conjunction_ticket_number": "12345678911",
"leg_coupon_number": "1",
"leg_departure_airport": "DXB",
"leg_departure_date": "2023-03-18",
"leg_departure_tax": "1000.0",
"leg_departure_time": "01:00:00Z",
"leg_destination_airport": "CAI",
"leg_destination_arrival_date": "2023-03-11",
"leg_destination_arrival_time": "01:00:00Z",
"leg_endorsements_restrictions": "4242342",
"leg_exchange_ticket_number": "12345678922",
"leg_fare": "42342342",
"leg_fare_basis": "4234234",
"leg_fees": "34234234",
"leg_flight_number": "123455",
"leg_stopover_permitted": "true",
"leg_taxes": "100",
"leg_travel_class": "A"
}
],
"itinerary_number_in_party": "2",
"itinerary_origin_country": "UAE"
},
"airline_passengers_list": [
{
"passenger_first_name": "xxxxx",
"passenger_frequent_flyer_number": "131231",
"passenger_last_name": "xxxxxx",
"passenger_middle_name": "xxxxx",
"passenger_specific_information": "hello",
"passenger_title": "SA"
},
{
"passenger_first_name": "xxxxx",
"passenger_frequent_flyer_number": "xxxxx",
"passenger_last_name": "xxxxxx",
"passenger_middle_name": "xxxxx",
"passenger_specific_information": "hi",
"passenger_title": "MNGR"
}
],
"airline_plan_number": "12",
"airline_ticket": {
"ticket_conjunction_ticket_indicator": "false",
"ticket_eTicket": "true",
"ticket_exchanged_ticket_number": "123444444444",
"ticket_issue": {
"issue_address": "32342",
"issue_carrier_code": "ZZ/999",
"issue_carrier_name": "XXXXXX",
"issue_city": "dubai",
"issue_country": "UAE",
"issue_date": "2023-03-10",
"issue_travel_agent_code": "12312312",
"issue_travel_agent_name": "test"
},
"ticket_restricted": "true",
"ticket_tax_or_fee": [
{
"tax_or_fee_amount": "123",
"tax_or_fee_type": "TT1"
}
],
"ticket_ticket_number": "123323487673",
"ticket_total_fare": "11",
"ticket_total_fees": "12",
"ticket_total_taxes": "121"
},
"airline_transaction_type": "EXCHANGE_TICKET"
},
"customer_ip": "10.0.0.1"
}
String jsonRequestString = "{\n \"command\": \"CAPTURE\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"M7bl0CMDio9kuJH\",\n \"amount\": \"200\",\n \"currency\": \"SAR\",\n \"language\": \"en\",\n \"signature\": \"\",\n \"airline_data\": {\n \"airline_booking_reference\": \"12345666\",\n \"airline_document_type\": \"KENNEL_CHARGE\",\n \"airline_itinerary\": {\n \"itinerary_leg\": [\n {\n \"leg_carrier_code\": \"EK/999\",\n \"leg_conjunction_ticket_number\": \"12345678911\",\n \"leg_coupon_number\": \"1\",\n \"leg_departure_airport\": \"DXB\",\n \"leg_departure_date\": \"2023-03-18\",\n \"leg_departure_tax\": \"1000.0\",\n \"leg_departure_time\": \"01:00:00Z\",\n \"leg_destination_airport\": \"CAI\",\n \"leg_destination_arrival_date\": \"2023-03-11\",\n \"leg_destination_arrival_time\": \"01:00:00Z\",\n \"leg_endorsements_restrictions\": \"4242342\",\n \"leg_exchange_ticket_number\": \"12345678922\",\n \"leg_fare\": \"42342342\",\n \"leg_fare_basis\": \"4234234\",\n \"leg_fees\": \"34234234\",\n \"leg_flight_number\": \"123455\",\n \"leg_stopover_permitted\": \"true\",\n \"leg_taxes\": \"100\",\n \"leg_travel_class\": \"A\"\n }\n ],\n \"itinerary_number_in_party\": \"2\",\n \"itinerary_origin_country\": \"UAE\"\n },\n \"airline_passengers_list\": [\n {\n \"passenger_first_name\": \"xxxx\",\n \"passenger_frequent_flyer_number\": \"131231\",\n \"passenger_last_name\": \"xxxxx\",\n \"passenger_middle_name\": \"xxxxx\",\n \"passenger_specific_information\": \"hello\",\n \"passenger_title\": \"SA\"\n },\n {\n \"passenger_first_name\": \"xxxxx\",\n \"passenger_frequent_flyer_number\": \"999\",\n \"passenger_last_name\": \"xxxxx\",\n \"passenger_middle_name\": \"xxxxxx\",\n \"passenger_specific_information\": \"hi\",\n \"passenger_title\": \"MNGR\"\n }\n ],\n \"airline_plan_number\": \"12\",\n \"airline_ticket\": {\n \"ticket_conjunction_ticket_indicator\": \"false\",\n \"ticket_eTicket\": \"true\",\n \"ticket_exchanged_ticket_number\": \"123444444444\",\n \"ticket_issue\": {\n \"issue_address\": \"32342\",\n \"issue_carrier_code\": \"ZZ/999\",\n \"issue_carrier_name\": \"XXXXXX\",\n \"issue_city\": \"dubai\",\n \"issue_country\": \"UAE\",\n \"issue_date\": \"2023-03-10\",\n \"issue_travel_agent_code\": \"12312312\",\n \"issue_travel_agent_name\": \"test\"\n },\n \"ticket_restricted\": \"true\",\n \"ticket_tax_or_fee\": [\n {\n \"tax_or_fee_amount\": \"123\",\n \"tax_or_fee_type\": \"TT1\"\n }\n ],\n \"ticket_ticket_number\": \"123323487673\",\n \"ticket_total_fare\": \"11\",\n \"ticket_total_fees\": \"12\",\n \"ticket_total_taxes\": \"121\"\n },\n \"airline_transaction_type\": \"EXCHANGE_TICKET\"\n },\n \"customer_ip\": \"10.0.0.1\"\n}"
// 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());
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
{
'command'=> 'CAPTURE',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> '{{$randomPassword}}',
'amount'=> '200',
'currency'=> 'SAR',
'language'=> 'en',
'signature'=> '{{signature}}',
'airline_data'=> {
'airline_booking_reference'=> '12345666',
'airline_document_type'=> 'KENNEL_CHARGE',
'airline_itinerary'=> {
'itinerary_leg'=> [
{
'leg_carrier_code'=> 'EK/999',
'leg_conjunction_ticket_number'=> '12345678911',
'leg_coupon_number'=> '1',
'leg_departure_airport'=> 'DXB',
'leg_departure_date'=> '2023-03-18',
'leg_departure_tax'=> '1000.0',
'leg_departure_time'=> '01:00:00Z',
'leg_destination_airport'=> 'CAI',
'leg_destination_arrival_date'=> '2023-03-11',
'leg_destination_arrival_time'=> '01:00:00Z',
'leg_endorsements_restrictions'=> '4242342',
'leg_exchange_ticket_number'=> '12345678922',
'leg_fare'=> '42342342',
'leg_fare_basis'=> '4234234',
'leg_fees'=> '34234234',
'leg_flight_number'=> '123455',
'leg_stopover_permitted'=> 'true',
'leg_taxes'=> '100',
'leg_travel_class'=> 'A'
}
],
'itinerary_number_in_party'=> '2',
'itinerary_origin_country'=> 'UAE'
},
'airline_passengers_list'=> [
{
'passenger_first_name'=> 'XXXX',
'passenger_frequent_flyer_number'=> '131231',
'passenger_last_name'=> 'XXXXX',
'passenger_middle_name'=> 'XXXXXX',
'passenger_specific_information'=> 'hello',
'passenger_title'=> 'SA'
},
{
'passenger_first_name'=> 'XXXX',
'passenger_frequent_flyer_number'=> '999',
'passenger_last_name'=> 'XXXX',
'passenger_middle_name'=> 'XXXXX',
'passenger_specific_information'=> 'hi',
'passenger_title'=> 'MNGR'
}
],
'airline_plan_number'=> '12',
'airline_ticket'=> {
'ticket_conjunction_ticket_indicator'=> 'false',
'ticket_eTicket'=> 'true',
'ticket_exchanged_ticket_number'=> '123444444444',
'ticket_issue'=> {
'issue_address'=> '32342',
'issue_carrier_code'=> 'ZZ/999',
'issue_carrier_name'=> 'XXXXXX',
'issue_city'=> 'dubai',
'issue_country'=> 'UAE',
'issue_date'=> '2023-03-10',
'issue_travel_agent_code'=> '12312312',
'issue_travel_agent_name'=> 'test'
},
'ticket_restricted'=> 'true',
'ticket_tax_or_fee'=> [
{
'tax_or_fee_amount'=> '123',
'tax_or_fee_type'=> 'TT1'
}
],
'ticket_ticket_number'=> '123323487673',
'ticket_total_fare'=> '11',
'ticket_total_fees'=> '12',
'ticket_total_taxes'=> '121'
},
'airline_transaction_type'=> 'EXCHANGE_TICKET'
},
'customer_ip'=> '10.0.0.1'
}
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData =
{
'command': 'CAPTURE',
'access_code': '{{access_code}}',
'merchant_identifier': '{{merchant_identifier}}',
'merchant_reference': '{{$randomPassword}}',
'amount': '200',
'currency': 'SAR',
'language': 'en',
'signature': '{{signature}}',
'airline_data': {
'airline_booking_reference': '12345666',
'airline_document_type': 'KENNEL_CHARGE',
'airline_itinerary': {
'itinerary_leg': [
{
'leg_carrier_code': 'EK/999',
'leg_conjunction_ticket_number': '12345678911',
'leg_coupon_number': '1',
'leg_departure_airport': 'DXB',
'leg_departure_date': '2023-03-18',
'leg_departure_tax': '1000.0',
'leg_departure_time': '01:00:00Z',
'leg_destination_airport': 'CAI',
'leg_destination_arrival_date': '2023-03-11',
'leg_destination_arrival_time': '01:00:00Z',
'leg_endorsements_restrictions': '4242342',
'leg_exchange_ticket_number': '12345678922',
'leg_fare': '42342342',
'leg_fare_basis': '4234234',
'leg_fees': '34234234',
'leg_flight_number': '123455',
'leg_stopover_permitted': 'true',
'leg_taxes': '100',
'leg_travel_class': 'A'
}
],
'itinerary_number_in_party': '2',
'itinerary_origin_country': 'UAE'
},
'airline_passengers_list': [
{
'passenger_first_name': 'XXXX',
'passenger_frequent_flyer_number': '131231',
'passenger_last_name': 'xxxxx',
'passenger_middle_name': 'xxxxxx',
'passenger_specific_information': 'hello',
'passenger_title': 'SA'
},
{
'passenger_first_name': 'XXXX',
'passenger_frequent_flyer_number': '999',
'passenger_last_name': 'XXXX',
'passenger_middle_name': 'XXXm',
'passenger_specific_information': 'hi',
'passenger_title': 'MNGR'
}
],
'airline_plan_number': '12',
'airline_ticket': {
'ticket_conjunction_ticket_indicator': 'false',
'ticket_eTicket': 'true',
'ticket_exchanged_ticket_number': '123444444444',
'ticket_issue': {
'issue_address': '32342',
'issue_carrier_code': 'ZZ/999',
'issue_carrier_name': 'XXXXXX',
'issue_city': 'dubai',
'issue_country': 'UAE',
'issue_date': '2023-03-10',
'issue_travel_agent_code': '12312312',
'issue_travel_agent_name': 'test'
},
'ticket_restricted': 'true',
'ticket_tax_or_fee': [
{
'tax_or_fee_amount': '123',
'tax_or_fee_type': 'TT1'
}
],
'ticket_ticket_number': '123323487673',
'ticket_total_fare': '11',
'ticket_total_fees': '12',
'ticket_total_taxes': '121'
},
'airline_transaction_type': 'EXCHANGE_TICKET'
},
'customer_ip': '10.0.0.1'
};
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'=> 'CAPTURE',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> '{{$randomPassword}}',
'amount'=> '200',
'currency'=> 'SAR',
'language'=> 'en',
'signature'=> '{{signature}}',
'airline_data'=> {
'airline_booking_reference'=> '12345666',
'airline_document_type'=> 'KENNEL_CHARGE',
'airline_itinerary'=> {
'itinerary_leg'=> [
{
'leg_carrier_code'=> 'EK/999',
'leg_conjunction_ticket_number'=> '12345678911',
'leg_coupon_number'=> '1',
'leg_departure_airport'=> 'DXB',
'leg_departure_date'=> '2023-03-18',
'leg_departure_tax'=> '1000.0',
'leg_departure_time'=> '01:00:00Z',
'leg_destination_airport'=> 'CAI',
'leg_destination_arrival_date'=> '2023-03-11',
'leg_destination_arrival_time'=> '01:00:00Z',
'leg_endorsements_restrictions'=> '4242342',
'leg_exchange_ticket_number'=> '12345678922',
'leg_fare'=> '42342342',
'leg_fare_basis'=> '4234234',
'leg_fees'=> '34234234',
'leg_flight_number'=> '123455',
'leg_stopover_permitted'=> 'true',
'leg_taxes'=> '100',
'leg_travel_class'=> 'A'
}
],
'itinerary_number_in_party'=> '2',
'itinerary_origin_country'=> 'UAE'
},
'airline_passengers_list'=> [
{
'passenger_first_name'=> 'XXXXX',
'passenger_frequent_flyer_number'=> '131231',
'passenger_last_name'=> 'XXXXX',
'passenger_middle_name'=> 'XXXXX',
'passenger_specific_information'=> 'hello',
'passenger_title'=> 'SA'
},
{
'passenger_first_name'=> 'XXXXX',
'passenger_frequent_flyer_number'=> '999',
'passenger_last_name'=> 'XXXXX',
'passenger_middle_name'=> 'XXXXX',
'passenger_specific_information'=> 'hi',
'passenger_title'=> 'MNGR'
}
],
'airline_plan_number'=> '12',
'airline_ticket'=> {
'ticket_conjunction_ticket_indicator'=> 'false',
'ticket_eTicket'=> 'true',
'ticket_exchanged_ticket_number'=> '123444444444',
'ticket_issue'=> {
'issue_address'=> '32342',
'issue_carrier_code'=> 'ZZ/999',
'issue_carrier_name'=> 'XXXXX',
'issue_city'=> 'dubai',
'issue_country'=> 'UAE',
'issue_date'=> '2023-03-10',
'issue_travel_agent_code'=> '12312312',
'issue_travel_agent_name'=> 'test'
},
'ticket_restricted'=> 'true',
'ticket_tax_or_fee'=> [
{
'tax_or_fee_amount'=> '123',
'tax_or_fee_type'=> 'TT1'
}
],
'ticket_ticket_number'=> '123323487673',
'ticket_total_fare'=> '11',
'ticket_total_fees'=> '12',
'ticket_total_taxes'=> '121'
},
'airline_transaction_type'=> 'EXCHANGE_TICKET'
},
'customer_ip'=> '10.0.0.1'
};
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: xxxxxxxxx |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: xxxxxxxxx |
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 |
airline_data List Optional |
List of parameters you can pass for the airline to process a transaction |
Parameters for the airline_data parameters:
ATTRIBUTES | Description |
---|---|
airline_booking_reference Alphanumeric Max: 15 |
The record locator used to access a specific Passenger Name Record (PNR) Example: 12345666 |
airline_document_type Alpha Optional |
The type of charge associated with the transaction. Example: ADDITIONAL_COLLECTION: Additional Collection AGENCY_EXCHANGE_ORDER: Agency Exchange Order AGENCY_GROUP_TICKET: Agency Group Ticket AGENCY_MISCELLANEOUS_CHARGE_ORDER: Agency Misc. Charge Order (MCO) AGENCY_PASSENGER_TICKET: Agency Passenger Ticket AGENCY_TOUR_ORDER_OR_VOUCHER: Agency Tour Order/Voucher AIR_FREIGHT SPD: Air Freight ANIMAL_TRANSPORTATION_CHARGE: Animal Transportation Charge CATALOGUE_MERCHANDISE_ORDERED: Catalogue Merchandise Ordered CLUB_MEMBERSHIP_FEE: Club Membership Fee COUPON_BOOK: Coupon Book CREDIT_CLASS_SERVICE_ADJUSTMENT: Credit Class of Service Adjustment CREDIT_DENIED_BOARDING: Credit Denied Boarding CREDIT_EXCHANGE_REFUND: Credit Exchange Refund CREDIT_LOST_TICKET_REFUND: Credit Lost Ticket Refund CREDIT_MISCELLANEOUS_REFUND: Credit Misc. Refund CREDIT_MULTIPLE_UNUSED_TICKETS: Credit Multiple Unused Tickets CREDIT_OVERCHARGE_ADJUSTMENT: Credit Overcharge Adjustment CREDIT_UNUSED_TRANSPORTATION: Credit Unused Transportation DEBT_ADJUSTMENT_DUPLICATE_REFUND_OR_USE: Debt Adjustment Duplicate Refund/Use DUTY_FREE_SALE: Duty Free Sale EXCESS_BAGGAGE: Excess Baggage EXCHANGE_ADJUSTMENT: Exchange Adjustment EXCHANGE_ORDER: Exchange Order FIREARMS_CASE Firearms: Case FREQUENT_FLYER_FEE_OR_PURCHASE: Frequent Flyer Fee/Purchase FREQUENT_FLYER_FULFILLMENT: Frequent Flyer Fulfillment FREQUENT_FLYER_OVERNIGHT_DELIVERY_CHARGE: Frequent Flyer Overnight Delivery Charge GROUP_TICKET: Group Ticket IN_FLIGHT_ADJUSTMENT: In-flight Adjustment IN_FLIGHT_CHARGES: In-flight Charges IN_FLIGHT_DUTY_FREE_PURCHASE: In-flight Duty Free Purchase IN_FLIGHT_MERCHANDISE_ORDERED: In-flight Merchandise Ordered IN_FLIGHT_PHONE_CHARGES: In-flight Phone Charges KENNEL_CHARGE: Kennel Charge LOST_TICKET_APPLICATION: Lost Ticket Application MISCELLANEOUS_CHARGE_ORDER_OR_PREPAID_TICKET_ADVICE: Misc. Charge Order (MCO) / Prepaid Ticket Auth. MISCELLANEOUS_TAXES_FEES: Miscellaneous Tax(es) Fee(s) PASSENGER_TICKET: Passenger Ticket SELF_SERVICE_TICKETS: Self-Service Ticket(s) SENIOR_CITIZEN_DISCOUNT_BOOKLETS: Senior Citizen Discount Booklets SMALL_PACKAGE_DELIVERY: Small Package Delivery SPECIAL_SERVICE_TICKET: Special Service Ticket SUPPORTED_REFUND: Supported Refund TICKET_BY_MAIL: Ticket by Mail TOUR_DEPOSIT: Tour Deposit TOUR_ORDER_VOUCHER: Tour Order Voucher UNDERCHARGE_ADJUSTMENT: Undercharge Adjustment UNSUPPORTED_REFUND: Unsupported Refund UPGRADE_CHARGE: Upgrade Charge VENDOR_REFUND_CREDIT: Vendor Refund Credit VENDOR_SALE: Vendor Sale |
airline_itinerary List Optional |
Itinerary details |
airline_passengers_list Array |
Passenger details. |
airline_plan_number Alphanumeric max: 2 |
Plan number supplied by the airline for this booking. Example: 12 |
airline_ticket List |
Ticket details. |
airline_transaction_type Alphanumeric |
The type of transaction performed against this airline booking. EXCHANGE_TICKET MISCELLANEOUS_CHARGE TICKET_PURCHASE TOUR_ORDER |
Parameters for the airline_itinerary:
ATTRIBUTES | Description |
---|---|
itinerary_number_in_party Integer max:3 |
Number of passengers associated with this booking. This parameter is to be passed within airline_itinerary. Example: 1 |
itinerary_origin_country Alpha max:3 |
The 3 character ISO 3166-1 alpha-3 country code of the country of origin for the itinerary. This parameter is to be passed within airline_itinerary. Example: UAE |
itinerary_leg Array Optional |
Travel leg details. This parameter is to be passed within airline_itinerary. |
Parameters for the itinerary_leg:
ATTRIBUTES | Description |
---|---|
leg_carrier_code Alphanumeric Max: 6 |
The 2-character IATA airline code or 3 digit accounting code or both of the airline carrier for the trip leg. Example: EK/999 |
leg_conjunction_ticket_number Alphanumeric Max:16 |
The ticket containing the coupon for this leg for an itinerary with more than four trip legs. Example: 12345678911 |
leg_coupon_number Alphanumeric Max:1 |
The coupon number on the ticket for the trip leg. Example: 1 |
leg_departure_airport Alpha Max:3 |
The 3 character IATA airport code of the departure airport for the trip leg. Example: DXB |
leg_departure_date Alphanumeric Max:10 |
Date of departure for the trip leg. Example: “2023-03-18" |
leg_departure_tax Alphanumeric Max:14 |
Tax payable on departure for the trip leg. Example: 10000 |
leg_departure_time Alphanumeric Max:9 |
Departure time in local time for the departure airport for this trip leg. Example: 01:00:00Z |
leg_destination_airport Alpha Max:3 CAI |
The 3 character IATA airport code for the destination airport for the trip leg. Example: CAI |
leg_destination_arrival_date Alphanumeric Max:10 |
Arrival date in local time for the destination airport for this trip leg. Example: “2023-03-18" |
leg_destination_arrival_time Alphanumeric Max:9 |
Arrival time in local time for the destination airport for this trip leg. Example: 01:00:00Z |
leg_endorsements_restrictions Alphanumeric Max:20 |
Restrictions (e.g. non-refundable) or endorsements applicable to the trip leg. Example: 4242342 |
leg_exchange_ticket_number Alphanumeric Max:16 |
New ticket number issued when a ticket is exchanged for the trip leg. Example: 12345678922 |
leg_fare Integer Max:14 |
Total fare payable for the trip leg. Example: 42342342 |
leg_fare_basis Alphanumeric Max:24 |
Code defining the rules forming the basis of the fare (type of fare, class entitlement, etc.) Example: 42342342 |
leg_fees Alphanumeric Max:14 |
Total fees payable for the trip leg. Example: 11.22 |
leg_flight_number Alphanumeric Max:6 |
The flight number for the trip leg. Example: 123455 |
leg_stopover_permitted Alpha Max:5 false |
Indicates if a stopover is permitted for the trip leg. Example: true |
leg_taxes Alphanumeric Max:14 |
Total taxes payable for the trip leg. Example: 11.22 |
leg_travel_class Alphanumeric max:3 |
The industry code indicating the class of service (e.g. Business, Coach) for the leg. Example: A |
Parameters for airline_passengers_list
Attributes | Description |
---|---|
passenger_first_name Alphanumeric max: 50 |
First name of the passenger to whom the ticket is being issued. Example: XXXXX |
passenger_frequent_flyer_number Alphanumeric max:20 |
Frequent Flyer or Loyalty Program number for this passenger. Example: 131231 |
passenger_last_name Alphanumeric max: 20 |
Last name of the passenger to whom the ticket is being issued. Example: XXXX |
passenger_middle_name Alphanumeric max:50 |
Middle name of the passenger to whom the ticket is being issued. Example: XXXXXX |
passenger_specific_information Alphanumeric max: 59 |
Passenger specific information recorded on the ticket. Example: VVVV |
passenger_title Alphanumeric max: 20 |
Title of the passenger to whom the ticket is being issued. Example: MR |
Parameters for the airline_ticket
Attributes | Description |
---|---|
ticket_issue List |
Ticket issue information. |
ticket_ticket_number Alphanumeric max:16 | The airline ticket number associated with the transaction. Example: 123323487673 |
ticket_conjunction_ticket_indicator Alpha Max:5 |
Indicates whether a conjunction ticket with additional coupons was issued. Example: false |
ticket_eTicket Alpha max: 5 |
Indicates if an electronic ticket was issued. Example: true |
ticket_exchanged_ticket_number Alphanumeric max:16 |
The original ticket number when this is a transaction for an exchanged ticket. Example: 123444444444 |
ticket_total_fare Alphanumeric max:14 |
Total fare for all trip legs on the ticket. Example: 11 |
ticket_total_fees Alphanumeric max:14 |
Total fare for all trip legs on the ticket. Exmple: 12 |
ticket_total_taxes Alphanumeric max:14 |
Total taxes for all trip legs on the ticket. Example: 121 |
ticket_restricted Alpha max:5 |
Indicates if the issued ticket is refundable. Example: true |
ticket_tax_or_fee Array |
Breakdown of the ticket taxes, airport taxes, charges and fees for an airline ticket purchase.The total of the amounts in this group should equal the sum of the airline.ticket.totalFees and airline.ticket.totalTaxes fields. |
Parameters for the ticket_tax_or_fee
Attributes | Description |
---|---|
tax_or_fee_amount Alphanumeric max:14 |
The tax, charge or fee amount payable. Part of the ticket_tax_or_fee list. Example: 123 |
tax_or_fee_type Alphanumeric max:3 |
The tax, charge or fee type code as assigned by IATA.Part of the ticket_tax_or_fee list. Example: TT1 |
Parameters for the ticket_issue
Attributes | Description |
---|---|
issue_address Alphanumeric max:16 |
The address where the ticket was issued. Example: 32342 |
issue_carrier_code Alphanumeric max:6 |
The 2-character IATA airline code or 3 digit accounting code or both of the airline carrier issuing the ticket. Example: ZZ/999 |
issue_carrier_name Alphanumeric max:25 |
Name of airline carrier issuing the ticket. Example: CCCC |
issue_city Alphanumeric max:100 |
The city/town where the ticket was issued. Example: dubai |
issue_country Alphanumeric max:3 |
The 3 character ISO 3166-1 alpha-3 country code of the country where the ticket was issued. Example: UAE |
issue_date Alphanumeric max:10 |
The date the ticket was issued. Example: “2023-03-10" |
issue_travel_agent_code Alphanumeric max:9 |
Industry code of the travel agent issuing the ticket. Example: 12312312 |
issue_travel_agent_name Alphanumeric max: 30 |
Name of the travel agent issuing the ticket. Example: test |
Capture Operation - Response
Capture Response Example
{"command":"CAPTURE","access_code":"xxxxxxxxx","merchant_identifier":"xxxxxxxxx","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":"xxxxxxxxx","merchant_identifier":"xxxxxxxxx","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":"xxxxxxxxx","merchant_identifier":"xxxxxxxxx","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":"xxxxxxxxx","merchant_identifier":"xxxxxxxxx","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":"xxxxxxxxx","merchant_identifier":"xxxxxxxxx","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: xxxxxxxxx |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: xxxxxxxxx |
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 |
Refund operation
An operation that returns the entire amount of a transaction, or returns part of it, after you have captured an amount.
How To Refund Captured Amount
How To Refund Captured Amount
1 . Using API: Using Refund Api Request.
Refund operation URLs
Test Environment URL:
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production Environment URL:
https://paymentservices.payfort.com/FortAPI/paymentApi
Parameters Submission Type
REST POST request using JSON.
Refund operation - request
(Please take a look at the Refund request example on the right side of the page.)
Refund request example
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
{
'command'=> 'REFUND',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'amount'=> '200',
'currency'=> 'SAR',
'language'=> 'en',
'signature'=> '{{signature}}',
'fort_id'=> '169996200000373656',
'airline_data'=> {
'airline_document_type'=> 'KENNEL_CHARGE',
'airline_transaction_type'=> 'REFUND',
'airline_ticket'=> {
'ticket_issue'=> {
'issue_carrier_code'=> 'ZZ/999',
'issue_carrier_name'=> 'XXXXXX',
'issue_city'=> 'dubai',
'issue_date'=> '2023-03-10'
}
}
}
}
);
$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": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"amount": "200",
"currency": "SAR",
"language": "en",
"signature": "{{signature}}",
"fort_id": "169996200000373656",
"airline_data": {
"airline_document_type": "KENNEL_CHARGE",
"airline_transaction_type": "REFUND",
"airline_ticket": {
"ticket_issue": {
"issue_carrier_code": "ZZ/999",
"issue_carrier_name": "XXXXXX",
"issue_city": "dubai",
"issue_date": "2023-03-10"
}
}
}
}
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData =
{
'command': 'REFUND',
'access_code': '{{access_code}}',
'merchant_identifier': '{{merchant_identifier}}',
'amount': '200',
'currency': 'SAR',
'language': 'en',
'signature': '{{signature}}',
'fort_id': '169996200000373656',
'airline_data': {
'airline_document_type': 'KENNEL_CHARGE',
'airline_transaction_type': 'REFUND',
'airline_ticket': {
'ticket_issue': {
'issue_carrier_code': 'ZZ/999',
'issue_carrier_name': 'XXXXXX',
'issue_city': 'dubai',
'issue_date': '2023-03-10'
}
}
}
};
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 = "{\n \"command\": \"REFUND\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"amount\": \"200\",\n \"currency\": \"SAR\",\n \"language\": \"en\",\n \"signature\": \"\",\n \"fort_id\": \"169996200000373656\",\n \"airline_data\": {\n \"airline_document_type\": \"KENNEL_CHARGE\",\n \"airline_transaction_type\": \"REFUND\",\n \"airline_ticket\": {\n \"ticket_issue\": {\n \"issue_carrier_code\": \"ZZ/999\",\n \"issue_carrier_name\": \"XXXXXX\",\n \"issue_city\": \"dubai\",\n \"issue_date\": \"2023-03-10\"\n }";
// 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'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'amount'=> '200',
'currency'=> 'SAR',
'language'=> 'en',
'signature'=> '{{signature}}',
'fort_id'=> '169996200000373656',
'airline_data'=> {
'airline_document_type'=> 'KENNEL_CHARGE',
'airline_transaction_type'=> 'REFUND',
'airline_ticket'=> {
'ticket_issue'=> {
'issue_carrier_code'=> 'ZZ/999',
'issue_carrier_name'=> 'XXXXXX',
'issue_city'=> 'dubai',
'issue_date'=> '2023-03-10'
}
}
}
}
};
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: xxxxxxxxx |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: xxxxxxxxx |
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 |
airline_data List Optional |
List of parameters you can pass for the airline to process a transaction |
Parameters for the airline_data list:
ATTRIBUTES | Description |
---|---|
airline_document_type Alpha Optional |
The type of charge associated with the transaction. Example: ADDITIONAL_COLLECTION: Additional Collection AGENCY_EXCHANGE_ORDER: Agency Exchange Order AGENCY_GROUP_TICKET: Agency Group Ticket AGENCY_MISCELLANEOUS_CHARGE_ORDER: Agency Misc. Charge Order (MCO) AGENCY_PASSENGER_TICKET: Agency Passenger Ticket AGENCY_TOUR_ORDER_OR_VOUCHER: Agency Tour Order/Voucher AIR_FREIGHT SPD: Air Freight ANIMAL_TRANSPORTATION_CHARGE: Animal Transportation Charge CATALOGUE_MERCHANDISE_ORDERED: Catalogue Merchandise Ordered CLUB_MEMBERSHIP_FEE: Club Membership Fee COUPON_BOOK: Coupon Book CREDIT_CLASS_SERVICE_ADJUSTMENT: Credit Class of Service Adjustment CREDIT_DENIED_BOARDING: Credit Denied Boarding CREDIT_EXCHANGE_REFUND: Credit Exchange Refund CREDIT_LOST_TICKET_REFUND: Credit Lost Ticket Refund CREDIT_MISCELLANEOUS_REFUND: Credit Misc. Refund CREDIT_MULTIPLE_UNUSED_TICKETS: Credit Multiple Unused Tickets CREDIT_OVERCHARGE_ADJUSTMENT: Credit Overcharge Adjustment CREDIT_UNUSED_TRANSPORTATION: Credit Unused Transportation DEBT_ADJUSTMENT_DUPLICATE_REFUND_OR_USE: Debt Adjustment Duplicate Refund/Use DUTY_FREE_SALE: Duty Free Sale EXCESS_BAGGAGE: Excess Baggage EXCHANGE_ADJUSTMENT: Exchange Adjustment EXCHANGE_ORDER: Exchange Order FIREARMS_CASE Firearms: Case FREQUENT_FLYER_FEE_OR_PURCHASE: Frequent Flyer Fee/Purchase FREQUENT_FLYER_FULFILLMENT: Frequent Flyer Fulfillment FREQUENT_FLYER_OVERNIGHT_DELIVERY_CHARGE: Frequent Flyer Overnight Delivery Charge GROUP_TICKET: Group Ticket IN_FLIGHT_ADJUSTMENT: In-flight Adjustment IN_FLIGHT_CHARGES: In-flight Charges IN_FLIGHT_DUTY_FREE_PURCHASE: In-flight Duty Free Purchase IN_FLIGHT_MERCHANDISE_ORDERED: In-flight Merchandise Ordered IN_FLIGHT_PHONE_CHARGES: In-flight Phone Charges KENNEL_CHARGE: Kennel Charge LOST_TICKET_APPLICATION: Lost Ticket Application MISCELLANEOUS_CHARGE_ORDER_OR_PREPAID_TICKET_ADVICE: Misc. Charge Order (MCO) / Prepaid Ticket Auth. MISCELLANEOUS_TAXES_FEES: Miscellaneous Tax(es) Fee(s) PASSENGER_TICKET: Passenger Ticket SELF_SERVICE_TICKETS: Self-Service Ticket(s) SENIOR_CITIZEN_DISCOUNT_BOOKLETS: Senior Citizen Discount Booklets SMALL_PACKAGE_DELIVERY: Small Package Delivery SPECIAL_SERVICE_TICKET: Special Service Ticket SUPPORTED_REFUND: Supported Refund TICKET_BY_MAIL: Ticket by Mail TOUR_DEPOSIT: Tour Deposit TOUR_ORDER_VOUCHER: Tour Order Voucher UNDERCHARGE_ADJUSTMENT: Undercharge Adjustment UNSUPPORTED_REFUND: Unsupported Refund UPGRADE_CHARGE: Upgrade Charge VENDOR_REFUND_CREDIT: Vendor Refund Credit VENDOR_SALE: Vendor Sale |
airline_ticket List |
Ticket details. |
ticket_issue List | Ticket issue information. This is a child of airline_ticket. |
Parameters for the ticket_issue
Attributes | Description |
---|---|
issue_carrier_code Alphanumeric max:6 |
The 2-character IATA airline code or 3 digit accounting code or both of the airline carrier issuing the ticket. Example: ZZ/999 |
issue_carrier_name Alphanumeric max:25 |
Name of airline carrier issuing the ticket. Example: CCCC |
issue_city Alphanumeric max:100 |
The city/town where the ticket was issued. Example: dubai |
issue_date Alphanumeric max:10 |
The date the ticket was issued. Example: “2023-03-10" |
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":"xxxxxxxxx","merchant_identifier":"xxxxxxxxx","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":"xxxxxxxxx","merchant_identifier":"xxxxxxxxx","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":"xxxxxxxxx","merchant_identifier":"xxxxxxxxx","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":"xxxxxxxxx","merchant_identifier":"xxxxxxxxx","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":"xxxxxxxxx","merchant_identifier":"xxxxxxxxx","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: xxxxxxxxx |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: xxxxxxxxx |
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 |
Tabby APIs
You will be able to integrate Tabby into Amazon Payment Services merchant facility. It describes the protocols, parameters, and technical environment provided by Amazon Payment Services for merchants integrating the Tabby BNPL Payment method. Tabby is a buy-now pay-later payment method. Tabby users can pay for a purchase in installments where the first installment will be charged during the purchase and the rest will be charged on the scheduled date based on the installment plan chosen by the user in the Tabby payment page.
Pre-requisites
Merchants need to set up a merchant account with Tabby in order to receive funds when the customers pay. Share the tabby created merchant_code and authorization key with APS to process the transaction from APS side.
Customer Integration
Merchants can integrate Tabby by redirecting their customers to Amazon Payment Services which in turn route the customer to the Tabby Payment page for onboarding (if the customer doesn’t have an account) or the payment is initiated from the merchant’s checkout page. When a customer is ready to pay, the merchant’s website redirects the customer to the Tabby payment page. In which customer selects the instalment plans completes their payment details on the Tabby’s payment screen. Customers can use their Tabby authorized phone number and OTP to complete a payment or they can use card (Visa, master), apple pay and all GCC approved cards for payment.
URLs
Test Environment URL:
https://sbcheckout.payfort.com/FortAPI/paymentPage
Production Environment URL:
https://checkout.payfort.com/FortAPI/paymentPage
Authorization/ Purchase - Request
Authorization/ Purchase Request Example
{
"command": "PURCHASE",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "merchantTest-10073",
"amount": "1000",
"currency": "AED",
"language": "en",
"customer_email": "test@merchantdomain.com",
"signature": "",
"payment_option":"TABBY",
}
$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',
'payment_option' => 'TABBY'
);
$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',
'payment_option' : 'TABBY'
};
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',
'payment_option' => 'TABBY'
};
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>";
ATTRIBUTES | Description |
---|---|
command Alpha Mandatory max: 20 |
Command. Possible/ expected values: PURCHASE. Please refer to this section to know more about the differences. |
access_code Alphanumeric Mandatory max: 20 |
Merchant account Access Code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Mandatory max: 20 |
Amazon Payment Services Merchant Account identifier. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory max: 40 |
The Merchant’s unique reference for a specific request. Example: XYZ9239-yu898 Special characters: _ - . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Mandatory Max: 254 |
The customer’s email. Example: customer@domain.com Special characters: _ - . @ + |
token_name Alphanumeric Optional Max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp Special characters: . @ - _ |
payment_option Alpha Mandatory Max: 10 |
Payment option. Possible/ expected values:TABBY |
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: $ ! = ? # & - _ / : . |
Sample TABBY Request
Redirection request should be submitted as HTTPs POST Form request from the browser. Then you will get redirected to our payment gateway to fill payment details
The following parameters will be returned in Amazon Payment Services’ response:
ATTRIBUTES | Description |
---|---|
command Alpha Mandatory max: 20 |
Command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
access_code Alphanumeric Mandatory max: 20 |
Merchant account Access Code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Mandatory max: 20 |
FORT Merchant Account identifier. Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory max: 40 |
The Merchant’s unique reference for a specific request. Example: XYZ9239-yu898 Special characters: _ - . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Mandatory Max: 254 |
The customer’s email. Example: customer@domain.com Special characters: _ - . @ + |
signature Alphanumeric Mandatory 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 Optional Max: 10 |
Payment option. Possible/ expected values:TABBY |
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. *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 |
Tabby Direct link feature
APS offers the one button click for transaction look up (direct link) for customer service representatives when checking a customer payment inquiry for Tabby transactions.
How it works?
- Merchant needs to use the code that needs to be integrated in his backoffice.
- The above code uses a POST method wherein a Merchant has to specify the FORT ID.
- Once the button is added, the Merchant team users will then be able to click it and get redirected to the APS Transaction Reports page.
- Once this is completed in your sandbox account, we can move it to production.
Here is the below code for sandbox and production:
For Sandbox:
<form target="_blank" action="https://testfort.payfort.com/transactions-report" method="POST">
<input type="hidden" name="fort_id" value="{insert-fort-id-here}">
<button type="submit">Open In APS</button>
</form>
For Production:
<form target="_blank" action="https://fort.payfort.com/transactions-report" method="POST">
<input type="hidden" name="fort_id" value="{insert-fort-id-here}">
<button type="submit">Open In APS</button>
</form>
Once this is completed in your sandbox account, we can move it to production.
Issuing Refunds
The refund API has been implemented to follow the same standards for all the other payment option refund flow. Please use the following document to understand the flow: https://docs.payfort.com/docs/api/build/index.html#refund-operation.
Messages and Statuses
Please use the following document to understand the messages and statuses: https://docs.payfort.com/docs/api/build/index.html#transactions-response-codes
Payment Link 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 Payment Link. When your customer clicks on the payment link they can conveniently pay for the invoiced amount using the currency and payment method that they prefer.
The payment link included in the invoice is directly connected to your merchant account so that your customer’s payment is simply and efficiently processed by Amazon Payment Services.
You have two options for Payment Link service:
1. Using the backoffice.
2. Using our APIs.
Read more about generating invoices using Payment Link
Payment Link Service - Backoffice
If you need to integrate Payment Link ( Invoicing service) manually from the back-office, you need follow the below steps to start testing the payments and generating invoices and simulate the process:
- Login to Sandbox account and Go to the Account Profile tab
- Add the Terms and Conditions URLs in the fields “English terms and conditions” & “Arabic terms and conditions” in the back-office account under General Information Tab
- Save the settings
- Go to invoices Management Tab and click on Generate New Invoice
- Generate invoices by filling the mandatory fields which are Merchant Reference, Customer Email , Amount, Expiry date, and Currency
Please check below the explanations for the fields. - Go to the tab “technical settings” and click the Redirection hyper link , and fill your domain URL / Terms & conditions URL for all the fields listed in this tab.
The invoice will be sent to the customer as Email,SMS based on your notification type selection.
The invoice can be tested on sandbox environment using our Testing Cards
ATTRIBUTES | Description |
---|---|
Invoice Number Alphanumeric Optional max: 40 |
The invoice number. Example: InvoiceAPS-0123 |
Merchant Reference Alphanumeric Mandatory max: 40 |
A unique order number. Example: APSInvoiceTransaction01 |
Customer Email Alphanumeric Mandatory max: 254 |
The customer’s email. Example: customer@domain.com Special characters: _ - . @ + |
Amount Numeric Mandatory max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 100 USD=1.00 USD |
Notification Type Optional |
The notification type the customer recieves Example: SMS/Email |
Expiry Date Calendar Mandatory max: 25 |
The invoice link expiry date. Example: 2017-12-20T15:36:55+03:00 Special characters: + : - |
Payment Option Drop down Optional |
The payment option Possible/ expected values: VISA/MasterCard/MADA/AMEX |
Order Description Alphanumeric Optional max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
Customer Name Alpha Optional max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' Space |
Language Drop down Optional |
The invoice and the received messages language. Possible/ expected values: English / Arabic |
Mobile Number Numeric Optional max: 19 |
The Customer mobile number. It’s mandatory when selecting SMS as notification type. Example: 00962797219966 |
Tabby Payment Link - Backoffice
If you need to integrate Payment Link ( Invoicing service) manually from the back-office, you need follow the below steps to start testing the payments and generating invoices and simulate the process:
- Login to Sandbox account and Go to the Account Profile tab
- Add the Terms and Conditions URLs in the fields “English terms and conditions” & “Arabic terms and conditions” in the back-office account under General Information Tab
- Save the settings
- Go to invoices Management Tab and click on Generate New Invoice
- Generate invoices by filling the mandatory fields which are Merchant Reference, Customer Email , Amount, Expiry date, Currency, Customer Name, Order Description and Phone Number.
- Go to the tab “technical settings” and click the Redirection hyper link , and fill your domain URL / Terms & conditions URL for all the fields listed in this tab.
The invoice will be sent to the customer as Email,SMS based on your notification type selection.
The invoice can be tested on sandbox environment using our Testing Cards
ATTRIBUTES | Description |
---|---|
Invoice Number Alphanumeric Optional max: 40 |
The invoice number. Example: InvoiceAPS-0123 |
Merchant Reference Alphanumeric Mandatory max: 40 |
A unique order number. Example: APSInvoiceTransaction01 |
Customer Email Alphanumeric Mandatory max: 254 |
The customer’s email. Example: customer@domain.com Special characters: _ - . @ + |
Amount Numeric Mandatory max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 100 USD=1.00 USD |
Notification Type Optional |
The notification type the customer recieves Example: SMS/Email |
Expiry Date Calendar Mandatory max: 25 |
The invoice link expiry date. Example: 2017-12-20T15:36:55+03:00 Special characters: + : - |
Payment Option Drop down Optional |
The payment option Possible/ expected values: VISA/MasterCard/MADA/AMEX |
Order Description Alphanumeric Optional max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
Customer Name Alpha Optional max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' Space |
Language Drop down Optional |
The invoice and the received messages language. Possible/ expected values: English / Arabic |
Phone Number Numeric Optional max: 19 |
The Customer mobile number. It’s mandatory when selecting SMS as notification type. Example: 00962797219966 |
> Request Sample
{
"merchant_reference":"TABBYPaymentLink",
"notification_type":"EMAIL",
"customer_phone":"966500000001",
"access_code":"s4lwuuoY5upZlZY5D6dr",
"request_expiry_date":"2023-08-20T15:36:55+03:00",
"merchant_identifier":"WeVJHPYm",
"currency":"AED",
"customer_name":"APS",
"order_description":"TABBY API Invoice",
"service_command":"PAYMENT_LINK",
"language":"en",
"customer_email":"otp.success@tabby.ai",
"link_command":"PURCHASE",
"payment_option":"TABBY",
"amount":"300",
"signature":"870786f1d740e6fb9f53f8db9e65b6e8f9170685e101de2273419577891eb6be"
}
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'merchant_reference'=>'TABBYPaymentLink',
'notification_type'=>'EMAIL',
'customer_phone'=>'966500000001',
'access_code'=>'s4lwuuoY5upZlZY5D6dr',
'request_expiry_date'=>'2023-08-20T15:36:55+03:00',
'merchant_identifier'=>'WeVJHPYm',
'currency'=>'AED',
'customer_name'=>'APS',
'order_description'=>'TABBY API Invoice',
'service_command'=>'PAYMENT_LINK',
'language'=>'en',
'customer_email'=>'otp.success@tabby.ai',
'link_command'=>'PURCHASE',
'payment_option'=>'TABBY',
'amount'=>'300',
'signature'=>'870786f1d740e6fb9f53f8db9e65b6e8f9170685e101de2273419577891eb6be'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'merchant_reference':'TABBYPaymentLink',
'notification_type':'EMAIL',
'customer_phone':'966500000001',
'access_code':'s4lwuuoY5upZlZY5D6dr',
'request_expiry_date':'2023-08-20T15:36:55+03:00',
'merchant_identifier':'WeVJHPYm',
'currency':'AED',
'customer_name':'APS',
'order_description':'TABBY API Invoice',
'service_command':'PAYMENT_LINK',
'language':'en',
'customer_email':'otp.success@tabby.ai',
'link_command':'PURCHASE',
'payment_option':'TABBY',
'amount':'300',
'signature':'870786f1d740e6fb9f53f8db9e65b6e8f9170685e101de2273419577891eb6be'
};
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 =
{
'merchant_reference'=>'TABBYPaymentLink',
'notification_type'=>'EMAIL',
'customer_phone'=>'966500000001',
'access_code'=>'s4lwuuoY5upZlZY5D6dr',
'request_expiry_date'=>'2023-08-20T15:36:55+03:00',
'merchant_identifier'=>'WeVJHPYm',
'currency'=>'AED',
'customer_name'=>'APS',
'order_description'=>'TABBY API Invoice',
'service_command'=>'PAYMENT_LINK',
'language'=>'en',
'customer_email'=>'otp.success@tabby.ai',
'link_command'=>'PURCHASE',
'payment_option'=>'TABBY',
'amount'=>'300',
'signature'=>'870786f1d740e6fb9f53f8db9e65b6e8f9170685e101de2273419577891eb6be'
};
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)
String jsonRequestString = "{\"merchant_reference\":\"TABBYPaymentLink\",\n\"notification_type\":\"EMAIL\",\n\"customer_phone\":\"966500000001\",\n\"access_code\":\"s4lwuuoY5upZlZY5D6dr\",\n\"request_expiry_date\":\"2023-08-20T15:36:55+03:00\",\n\"merchant_identifier\":\"WeVJHPYm\",\n\"currency\":\"AED\",\n\"customer_name\":\"APS\",\n\"order_description\":\"TABBY API Invoice\",\n\"service_command\":\"PAYMENT_LINK\",\n\"language\":\"en\",\n\"customer_email\":\"otp.success@tabby.ai\",\n\"link_command\":\"PURCHASE\",\n\"payment_option\":\"TABBY\",\n\"amount\":\"300\",\n\"signature\":\"870786f1d740e6fb9f53f8db9e65b6e8f9170685e101de2273419577891eb6be\""}";
// 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());
Payment Link Service API
Payment Link 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.
Payment Link Service - Request
Include the following parameters in the Request you will send to Amazon Payment Services:
{
"service_command": "PAYMENT_LINK",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "Test-10080",
"amount": "125000",
"currency": "AED",
"language": "en",
"customer_email": "vit@amazon.com",
"request_expiry_date":"2022-07-22T15:36:55+03:00",
"notification_type":"EMAIL",
"signature": "{{signature}}"
}
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'service_command'=> 'PAYMENT_LINK',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> 'Test-10080',
'amount'=> '125000',
'currency'=> 'AED',
'language'=> 'en',
'customer_email'=> 'vit@amazon.com',
'request_expiry_date'=>'2022-07-22T15:36:55+03:00',
'notification_type'=>'EMAIL',
'signature'=> '{{signature}}'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'service_command': 'PAYMENT_LINK',
'access_code': '{{access_code}}',
'merchant_identifier': '{{merchant_identifier}}',
'merchant_reference': 'Test-10080',
'amount': '125000',
'currency': 'AED',
'language': 'en',
'customer_email': 'vit@amazon.com',
'request_expiry_date':'2022-07-22T15:36:55+03:00',
'notification_type':'EMAIL',
'signature': '{{signature}}'
};
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 =
{
'service_command'=> 'PAYMENT_LINK',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> 'Test-10080',
'amount'=> '125000',
'currency'=> 'AED',
'language'=> 'en',
'customer_email'=> 'vit@amazon.com',
'request_expiry_date'=>'2022-07-22T15:36:55+03:00',
'notification_type'=>'EMAIL',
'signature'=> '{{signature}}'
};
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)
String jsonRequestString = "{\n \"service_command\": \"PAYMENT_LINK\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"merchantTest-10080\",\n \"amount\": \"125000\",\n \"currency\": \"AED\",\n \"language\": \"en\",\n \"customer_email\": \"merchantvit@amazon.com\",\n \"request_expiry_date\":\"2022-07-22T15:36:55+03:00\",\n \"notification_type\":\"EMAIL\",\n \"signature\": \"\"\n}";
// 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());
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. Please refer to this section to know more about the differences. |
payment_link_id Alphanumeric Optional max: 20 |
The ID of the generated Invoice payment link. Example: 148708392700020346 Special characters: - _ . |
payment_option Alpha Optional max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - SADAD (for Purchase operations only) - NAPS (for Purchase operations only) - KNET(for Purchase operations only) - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) |
order_description Alphanumeric Optional max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
customer_name Alpha Optional max: 40 |
The customer’s name. Example: John Smith Special characters: _ \ / - . ' Space |
customer_phone Numeric Optional max: 19 |
The Customer mobile number. It’s mandatory when selecting SMS as notification type. Example: 00962797219966 |
Payment Link 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. 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. Please refer to this section to know more about the differences. |
payment_link_id Alphanumeric max: 20 |
The ID of the generated Invoice payment link. Example: 148708392700020346 |
payment_link Alphanumeric max: 150 |
The generated invoice link notified to the Customer by one of the notification types, used to complete the payment process. Example: https://checkout.payfort.com/dfc3d762 |
payment_option Alpha max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - SADAD (for Purchase operations only) - NAPS (for Purchase operations only) - KNET(for Purchase operations only) - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) |
order_description Alphanumeric max: 150 |
It holds the description of the order. Example: iPhone 6-S |
customer_name Alpha max: 40 |
The customer’s name. Example: John Smith |
response_message Alphanumeric max: 150 |
Message description of the response code. It returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code is made up of five digits, the first 2 digits refer to the request status, and the last 3 digits refer to the request messages. Example: 20064 |
status Numeric max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: statuses |
customer_phone Numeric max: 19 |
The Customer mobile number. Example: 00962797219966 |
return_url Alphanumeric max: 400 |
The URL of the Merchant’s page to be redirected to when the order is processed. Example: https://www.merchant.com |
- After completing the checkout process through the payment link; the following list of parameters will be returned under the “Direct Transaction Feedback”:
ATTRIBUTES | Description |
---|---|
command Alpha Max: 20 |
A command. Possible/ expected values: AUTHORIZATION, PURCHASE. Please refer to this section to know more about the differences. |
access_code Alphanumeric Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
merchant_reference Alphanumeric Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
amount Numeric Max: 10 |
The transaction’s amount. Example: 10000 |
currency Alpha Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Max: 254 |
The customer’s email. Example: customer1@domain.com |
signature Alphanumeric Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
payment_link_id Alphanumeric max: 20 |
The ID of the generated Invoice payment link. Example: 148708392700020346 |
token_name Alphanumeric max: 100 |
The Token received from the Tokenization process. Example: Op9Vmp |
fort_id Numeric Max: 20 |
The order’s unique reference returned by our system. Example: 149295435400084008 |
payment_option Alpha Max: 10 |
Payment option. Possible/ expected values: - MASTERCARD - VISA - AMEX - SADAD (for Purchase operations only) - NAPS (for Purchase operations only) - KNET(for Purchase operations only) - MADA (for Purchase operations and eci Ecommerce only) Click here to download MADA Branding Document - MEEZA (for Purchase operations and ECOMMERCE eci only) |
sadad_olp Alphanumeric Max: 12 |
SADAD Online Payment ID Alias. The merchant sends this value if the OLP ID is collected on the merchant checkout. Example: SABBP2P_UAT2 |
eci Alpha Max: 16 |
The E-commerce indicator. Possible/ expected values: - ECOMMERCE - MOTO |
order_description Alphanumeric Max: 150 |
It holds the description of the order. Example: iPhone 6-S |
customer_ip Alphanumeric max: 45 |
It holds the customer’s IP address. *We support IPv4 and IPv6 as shown in the example below. Example: IPv4 → 192.178.1.10 IPv6 → 2001:0db8:3042:0002:5a55:caff:fef6:bdbf |
customer_name Alpha Max: 40 |
The customer’s name. Example: John Smith |
merchant_extra Alphanumeric Max: 999 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra1 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra2 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra3 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra4 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
merchant_extra5 Alphanumeric Max: 250 |
Extra data sent by merchant. Will be received and sent back as received. Will not be displayed in any report. Example: JohnSmith |
authorization_code Alphanumeric Max: 100 |
The authorization code returned from the 3rd party. Example: P1000000000000372136 |
response_message Alphanumeric Max: 150 |
The message description of the response code; it returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 20064 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
card_holder_name Alpha Max: 50 |
The card holder name. Example: John Smith |
expiry_date Numeric Max: 4 |
The card’s expiry date. Example: 2105 |
card_number Numeric Max: 19 |
The masked credit card’s number. Only the MEEZA payment option takes 19 digits card number. *AMEX payment option takes 15 digits card number. *Otherwise, they take 16 digits card number. Example: 400555*****0001 |
remember_me Alpha Max: 2 |
This parameter provides you with an indication to whether to save this token for the user based on the user selection. Possible/ expected values: NO |
phone_number Alphanumeric max: 19 |
The customer’s phone number. Example: 00962797219966 |
settlement_reference Alphanumeric max: 34 |
The Merchant submits unique value to Amazon Payment Services. The value is then passed to the Acquiring bank and displayed to the merchant in the Acquirer settlement file. Example: XYZ9239-yu898 |
Payment Link Update Service
This service enables you to change details for a payment link such as status, amount, currency or expiry date.
Merchants can now use the Update feature for Payment Links to handle the following scenarios:
• Merchant creates and shares a Payment Link to a customer with a defined amount value to be collected from the customer. If the invoice amount changes from the original amount for pending Payment Links, then Merchant can use the Update feature to change the amount value of the Payment Link without having to recreate or resend new links to the customers.
• Merchant creates and shares a Payment Link to a customer to collect payments. If the merchant receives the payment from a customer from another channel, then the Merchant can use the Update feature to close the Payment Link so that the customer does not pay twice for the same invoice.
• Merchant creates and shares a Payment Link to customers to collect payments by a due date. Subsequently if the link expires without the customer making the payment, then the Merchant can reopen the Payment Link using the Update Feature and set a new Expiry date and update Payment Link Status. The customer will then be able to complete the payment for the invoice using the same link.
• Merchant creates and shares a Payment Link to a customer but the invoice has incorrect details (e.g. customer name or order description). Merchant can use the Update Feature to update the invoice details with correct or updated values.
If the payment link has not been paid, you can change the status as follows:
• From: Open > Closed. • From: Closed > Opened • From: Expired > Open. A new Expiry Date must be provided
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.
Update Payment Link Service - Request
Include the following parameters in the Request you will send to Amazon Payment Services:
{
"service_command": "UPDATE_PAYMENT_LINK",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "Test-10080",
"payment_link_status": "Closed",
"amount": "125000",
"currency": "AED",
"language": "en",
"request_expiry_date":"2022-07-22T15:36:55+03:00",
"signature": "{{signature}}"
}
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'service_command'=> 'UPDATE_PAYMENT_LINK',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> 'Test-10080',
'payment_link_status'=> 'Closed',
'amount'=> '125000',
'currency'=> 'AED',
'language'=> 'en',
'request_expiry_date'=>'2022-07-22T15:36:55+03:00',
'signature'=> '{{signature}}'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'service_command': 'UPDATE_PAYMENT_LINK',
'access_code': '{{access_code}}',
'merchant_identifier': '{{merchant_identifier}}',
'merchant_reference': 'Test-10080',
'payment_link_status': 'Closed',
'amount': '125000',
'currency': 'AED',
'language': 'en',
'request_expiry_date':'2022-07-22T15:36:55+03:00',
'signature': '{{signature}}'
};
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 =
{
'service_command'=> 'UPDATE_PAYMENT_LINK',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> 'Test-10080',
'payment_link_status'=> 'Closed',
'amount'=> '125000',
'currency'=> 'AED',
'language'=> 'en',
'request_expiry_date'=>'2022-07-22T15:36:55+03:00',
'signature'=> '{{signature}}'
};
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)
String jsonRequestString = "{\n \"service_command\": \"UPDATE_PAYMENT_LINK\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"merchantTest-10080\",\n \"amount\": \"125000\",\n \"currency\": \"AED\",\n \"language\": \"en\",\n \"request_expiry_date\":\"2022-07-22T15:36:55+03:00\",\n \"signature\": \"\"\n, \n \"payment_link_status\":\"Closed\",}";
// 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());
ATTRIBUTES | Description |
---|---|
service_command Alpha Mandatory max: 20 |
Command. Possible/ expected values: UPDATE_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. Optional if payment_link_id is passed Example: CycHZxVj |
merchant_reference Alphanumeric Mandatory max: 40 |
The Merchant’s unique order number. You can use merchant reference or payment_link_id. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Optional max: 10 |
The transaction’s amount to be updated. *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 Optional max: 3 |
Currency to set the payment link amount. The currency of the transaction’s amount in ISO code 3. Example: USD |
language Alpha Mandatory max: 2 |
The received messages language. Possible/ expected values: en / ar |
request_expiry_date Alphanumeric Optional max: 25 |
The invoice link expiry date to be updated. Example: 2017-12-20T15:36:55+03:00 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_link_id Alphanumeric Optional if merchant_reference is passed max: 20 |
The ID of the generated Invoice payment link. Example: 148708392700020346 Special characters: - _ . |
payment_link_status Alpha Optional max: 20 |
The status of the generated Invoice Payment link Possible/Expected values: Open, Closed |
payment_option Alpha Optional Max: 10 |
Payment option to be updated. 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 to be updated. Example: iPhone 6-S |
customer_name Alpha Optional Max: 40 |
The customer’s name to be updated. Example: John Smith |
Update Payment Link 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: UPDATE_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 received messages language. Possible/ expected values: en / ar |
request_expiry_date Alphanumeric max: 25 |
The invoice link expiry date. Example: 2017-12-20T15: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 |
payment_link_id Alphanumeric max: 20 |
The ID of the generated Invoice payment link. Example: 148708392700020346 |
payment_link_status Alpha max: 20 |
The status of the generated Invoice Payment link Possible/Expected values: Open, Closed. |
response_message Alphanumeric Max: 150 |
Message description of the response code. It returns according to the request language. When you do not pass any parameter to update in the request, you get the message “Missing parameter : payment_link_status”. . All the update parameters for update payment link are optional. 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: statuses |
payment_option Alpha Max: 10 |
Payment option to be updated. 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 to be updated. Example: iPhone 6-S |
customer_name Alpha Max: 40 |
The customer’s name to be updated. Example: John Smith |
Get Payment Link Service
This service enables you to check the status of specific payment link.
Test Environment URL:
https://sbpaymentservices.PayFort.com/FortAPI/paymentApi
Production Environment URL:
https://paymentservices.PayFort.com/FortAPI/paymentApi
Parameters Submission Type
REST POST request using JSON.
Get Payment Link Status Service - Request
This service enables you to check the status of a specific payment link. A Merchant creates and shares Payment Links with customers. The merchant can then enquire the status of the specific Payment link by using the Check Payment Link status feature. A Merchant invokes the service by providing a payment Link ID or Merchant Reference. This service returns a response containing details about the link status (Open, Paid, Expired, Closed) and how many times the customer has opened the link.
Include the following parameters in the Request you will send to Amazon Payment Services:
{
"query_command": "CHECK_PAYMENT_LINK_STATUS",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "Test-10080",
"signature": "{{signature}}"
}
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'query_command'=> 'CHECK_PAYMENT_LINK_STATUS',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> 'Test-10080',
'signature'=> '{{signature}}'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'query_command': 'CHECK_PAYMENT_LINK_STATUS',
'access_code': '{{access_code}}',
'merchant_identifier': '{{merchant_identifier}}',
'merchant_reference': 'Test-10080',
'signature': '{{signature}}'
};
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_PAYMENT_LINK_STATUS',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> 'Test-10080',
'signature'=> '{{signature}}'
};
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)
String jsonRequestString = "{\n \"query_command\": \"CHECK_PAYMENT_LINK_STATUS\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"merchantTest-10080\", \n \"signature\": \"\"\n,}";
// 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());
ATTRIBUTES | Description |
---|---|
query_command Alpha Mandatory max: 20 |
Command. Possible/ expected values: CHECK_PAYMENT_LINK_STATUS 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. This parameter is optional if you pass payment_link_id |
merchant_reference Alphanumeric Mandatory max: 40 |
The Merchant’s unique order number. You can use either merchant_reference or payment_link_id to fetch details of the status Example: XYZ9239-yu898 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_link_id Alphanumeric Optional if merchant_reference is passed max: 20 |
The ID of the generated Invoice payment link. Example: 148708392700020346 Special characters: - _ . |
Get Payment Link Service - Response
The following parameters will be returned in Amazon Payment Services’s response:
ATTRIBUTES | Description |
---|---|
query_command Alpha max: 20 |
Command. Possible/ expected values: CHECK_PAYMENT_LINK_STATUS |
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 received messages language. Possible/ expected values: en / ar |
request_expiry_date Alphanumeric max: 25 |
The invoice link expiry date. Example: 2017-12-20T15: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 |
payment_link_id Alphanumeric max: 20 |
The ID of the generated Invoice payment link. Example: 148708392700020346 |
payment_link_status Alpha Optional max: 20 |
The status of the generated Invoice Payment link Possible/Expected values: Open, Closed, Paid, or Expired |
user_attempts_count Numeric |
The number of times a user opened the payment link. |
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 |
status Numeric max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: statuses |
Payment Link Service - Customization
Amazon Payment link for credit card is fully customizable to match your website’s look and feel.
How it works
From your back-office go to the tab Payment Link Template, Click on Add Payment Link Template , You will find two options for customizing the payment page:
1. Using our back-office live editor.
2. Uploading your own css and html files.
Customization using our back-office live editor
We have added a full online editor on the back-office to simplify the CSS customization and change the look and feel without any coding , also your changes could be checked on the same tab Customize .
This option allows you to change the following :
- Primary color ( in Hexa )
- Secondary color ( In Hexa )
- Background Color ( In Hexa )
Using HTML and CSS files
If you want to have more control on the payment link design and add more edits , you have two file options to upload:
HTML Template:
You can implement and create your own html file that you want to load in the payment link and change the look and feel for the payment link as you wish.
Your edits and customization must be added between the following tag in a separated <div> as below :
<div>$$PZ$$</div> to inject your changes in our payment zone pages
The scripts aren’t allowed in the templates.
CSS Theme :
Develop your CSS file that edit our colors and theme in the payment link here you have to edit our existing CSS classes by inspecting the elements of the payment link , then include your changes on a CSS file.
Batch Service
Amazon Payment Services offers batch processing as an alternative where it is not practical or desirable for you to write code to automate a process on your server. Instead, you can upload a batch file to our server that contains the instructions that you want to execute.
Read more about batch processing here
Batch Service API
We support Batch service using our API for the following options below:
1. You’re only allowed to send one of the following transactions in your batch file or a mixture of them:
2. You must activate the batch processing service before attempting to upload a batch file.
* Recurring: PURCHASE command.
Please refer to the following sample
* Maintenance operations (capture, refund, and void authorization): after completing a successful Authorization or Purchase transactions through one of Amazon Payment Services’ channels.
Please refer to the following sample
* Invoicing: PURCHASE command.
Please refer to the following sample
.
How it works - Steps
1. Upload the batch file:
This request enables you to upload the batch file to Amazon Payment Services.
2. Get Batch Results::
With this request you validate the format of the batch file you uploaded and check that the merchant reference for each and every transaction is unique. After validation the “Account Administrator” will receive an email notification including a count of the invoices successfully sent.
3. Process Batch File:
When you send this request you initiate the processing of transactions. To start the processing you must ensure that the batch file was validated and passed the validation process. After processing the “Account Administrator” will receive an email notification with a count of the invoices sent successfully.
Upload Batch file
This request enables you to upload your batch file to Amazon Payment Services. You specify the order of the fields in the batch file. You will receive a success message (response code: 50000) indicating that the batch file was received successfully by Amazon Payment Services. Amazon Payment Services will then start the validation process on the uploaded file
Upload Batch File URLs
Test Environment URL:
https://sbpaymentservices.payfort.com/FortAPI/upload/
Production Environment URL:
https://paymentservices.payfort.com/FortAPI/upload/
Parameters Submission Type
Host to Host Form Post Request (From the backend)
Upload Batch File - Request
<!DOCTYPE html>
<body>
<form method="post" action="" enctype="multipart/form-data">
<input type="text" name="service_command" value="UPLOAD_BATCH_FILE">
<input type="text" name="access_code" value="ACCESS CODE">
<input type="text" name="merchant_identifier" value="MERCHANT IDENTIFIER" >
<input type="text" name="batch_reference" value="BATCH REFERENCE">
<input type="text" name="language" value="en">
<input type="file" name="file">
<input name="submitButton" type="submit" value="Process request">
</form>
</body>
</html>
<?php
// Display errors
ini_set('display_errors', 1);
ini_set('display_startup_errors', 1);
error_reporting(E_ALL);
// Production Environment URL
$productionUrl = "https://paymentservices.payfort.com/FortAPI/upload/";
// Test Environment URL
$testUrl = "https://sbpaymentservices.payfort.com/FortAPI/upload/";
if(isset($_POST['submitButton'])){
// Array data
$arrayData = array(
'service_command' => $_POST['service_command'],
'access_code' => $_POST['access_code'],
'merchant_identifier' => $_POST['merchant_identifier'],
'batch_reference' => $_POST['batch_reference'],
'language' => $_POST['language'],
'file' => $_FILES['file']['name']
);
// Generate signature and add it to the arrayData
$signature = calculateSignature($arrayData);
$arrayData['signature'] = $signature;
// file data
$cfile = new CURLFile($_FILES['file']['tmp_name'], $_FILES['file']['type'], $_FILES['file']['name']);
$arrayData['file'] = $cfile;
$ch = curl_init( $testUrl );
curl_setopt($ch, CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type:multipart/form-data"));
curl_setopt( $ch, CURLOPT_POSTFIELDS, $arrayData );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
$result = curl_exec($ch);
curl_close($ch);
// Display the resualt
echo "<pre>$result</pre>";
}
// this function is for signature calculation
function calculateSignature($arrayData) {
$shaString = '';
// sort an array by key
ksort($arrayData);
foreach ($arrayData as $key => $value) {
$shaString .= "$key=$value";
}
// make sure to fill your sha request pass phrase
$shaString = "YOUR_SHA_REQUEST_PASSPHRASE" . $shaString . "YOUR_SHA_REQUEST_PASSPHRASE";
$signature = hash("sha256", $shaString);
// your request signature
return $signature;
}
?>
Include the following parameters in the Request you will send to Amazon Payment Services:
ATTRIBUTES | Description |
---|---|
service_command Alpha Mandatory Max: 20 |
Command. Possible/ expected values: UPLOAD_BATCH_FILE Special characters: _ |
access_code Alphanumeric Mandatory Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Mandatory Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
batch_reference Alphanumeric Mandatory Max: 20 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . / |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
file Alphanumeric Mandatory Max: 50 |
The file that contain a batch of transactions. The file should be of type CSV. Example: test.csv Special characters: . - ! @ # $ % ^ & ( ) _ + , Space |
signature Alphanumeric Mandatory Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
Upload Batch File - Response
The following parameters will be returned in Amazon Payment Services’ response:
ATTRIBUTES | Description |
---|---|
service_command Alpha Max: 20 |
Command. Possible/ expected values: UPLOAD_BATCH_FILE |
access_code Alphanumeric Max: 20 |
Access code. Example: zx0IPmPy5jp1vAz8Kpg7 |
merchant_identifier Alphanumeric Max: 20 |
The ID of the Merchant. Example: CycHZxVj |
batch_reference Alphanumeric Max: 20 |
The Merchant’s unique order number. Example: XYZ9239-yu898 |
language Alpha Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
batch_id Numeric Max: 20 |
The Merchant’s unique batch ID. Example: 150754364000030895 |
signature Alphanumeric Mandatory Max: 200 |
A string hashed using the Secure Hash Algorithm. Please refer to section Signature Example: 7cad05f0212ed933c9a5d5dffa31661acf2c827a |
response_message Alphanumeric Max: 150 |
The message description of the response code; it returns according to the request language. Possible/ expected values: Please refer to section messages |
response_code Numeric Max: 5 |
Response Code carries the value of our system’s response. *The code consists of five digits, the first 2 digits represent the response status, and the last 3 digits represent the response messages. Example: 50000 |
status Numeric Max: 2 |
A two-digit numeric value that indicates the status of the transaction. Possible/ expected values: Please refer to section statuses |
Get Batch Results
This request enables you to validate the format of your batch file and to check that the merchant reference for each and every transaction is unique. In the response of this request you receive the batch file validation results, which could be any one of: batch validation success, validation done with errors, batch file is still under validation.
Note: Your batch file cannot be processed if the validation status is “the batch file still under validation”.
Get Batch Results URLs
Test Environment URL:
https://sbpaymentservices.payfort.com/FortAPI/batchApi/
Production Environment URL:
https://paymentservices.payfort.com/FortAPI/batchApi/
Parameters Submission Type
REST POST request using JSON.
Get Batch Results - Request
Include the following parameters in the Request you will send to Amazon Payment Services:
{
“merchant_identifier”:“bxgOIxIz”,
“access_code”:“1DFxVvhXWV6wumenTTg9”,
“signature”:“17e62207b17ea9f550b41811039cb4a05f86087c5cdec40aad1dcc250909b054”,
“service_command”:“GET_BATCH_RESULTS”,
“batch_reference”:“batch180”,
“language”:“en”,
“batch_id” : “151791753100095172”
}
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
{
'merchant_identifier'=>'bxgOIxIz',
'access_code'=>'1DFxVvhXWV6wumenTTg9',
'signature'=>'17e62207b17ea9f550b41811039cb4a05f86087c5cdec40aad1dcc250909b054',
'service_command'=>'GET_BATCH_RESULTS',
'batch_reference'=>'batch180',
'language'=>'en',
'batch_id' => '151791753100095172'
}
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'merchant_identifier':'bxgOIxIz',
'access_code':'1DFxVvhXWV6wumenTTg9',
'signature':'17e62207b17ea9f550b41811039cb4a05f86087c5cdec40aad1dcc250909b054',
'service_command':'GET_BATCH_RESULTS',
'batch_reference':'batch180',
'language':'en',
'batch_id' : '151791753100095172'
};
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 =
{
'merchant_identifier'=>'bxgOIxIz',
'access_code'=>'1DFxVvhXWV6wumenTTg9',
'signature'=>'17e62207b17ea9f550b41811039cb4a05f86087c5cdec40aad1dcc250909b054',
'service_command'=>'GET_BATCH_RESULTS',
'batch_reference'=>'batch180',
'language'=>'en',
'batch_id' => '151791753100095172'
}
;
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)
String jsonRequestString = "{\n“merchant_identifier”:“bxgOIxIz”,\n“access_code”:“1DFxVvhXWV6wumenTTg9”,\n“signature”:“17e62207b17ea9f550b41811039cb4a05f86087c5cdec40aad1dcc250909b054”,\n“service_command”:“GET_BATCH_RESULTS”,\n“batch_reference”:“batch180”,\n“language”:“en”,\n“batch_id” : “151791753100095172”\n}";
// 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());
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:
{
“merchant_identifier”:“bxgOIxIz”,
“access_code”:“1DFxVvhXWV6wumenTTg9”,
“signature”:“17e62207b17ea9f550b41811039cb4a05f86087c5cdec40aad1dcc250909b054”,
“service_command”:"PROCESS_BATCH",
“batch_reference”:“batch180”,
“language”:“en”,
“batch_id” : “151791753100095172”
}
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
{
'merchant_identifier'=>'bxgOIxIz',
'access_code'=>'1DFxVvhXWV6wumenTTg9',
'signature'=>'17e62207b17ea9f550b41811039cb4a05f86087c5cdec40aad1dcc250909b054',
'service_command'=>'PROCESS_BATCH',
'batch_reference'=>'batch180',
'language'=>'en',
'batch_id' => '151791753100095172'
}
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'merchant_identifier':'bxgOIxIz',
'access_code':'1DFxVvhXWV6wumenTTg9',
'signature':'17e62207b17ea9f550b41811039cb4a05f86087c5cdec40aad1dcc250909b054',
'service_command':'PROCESS_BATCH',
'batch_reference':'batch180',
'language':'en',
'batch_id' : '151791753100095172'
};
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 =
{
'merchant_identifier'=>'bxgOIxIz',
'access_code'=>'1DFxVvhXWV6wumenTTg9',
'signature'=>'17e62207b17ea9f550b41811039cb4a05f86087c5cdec40aad1dcc250909b054',
'service_command'=>'PROCESS_BATCH',
'batch_reference'=>'batch180',
'language'=>'en',
'batch_id' => '151791753100095172'
}
;
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)
String jsonRequestString = "{\n“merchant_identifier”:“bxgOIxIz”,\n“access_code”:“1DFxVvhXWV6wumenTTg9”,\n“signature”:“17e62207b17ea9f550b41811039cb4a05f86087c5cdec40aad1dcc250909b054”,\n“service_command”:"PROCESS_BATCH",\n“batch_reference”:“batch180”,\n“language”:“en”,\n“batch_id” : “151791753100095172”\n}";
// 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());
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 Payment Link 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.
Read more about Payment Link here
Batch Invoicing Backoffice
Before starting you have to know the following:
1. You’re only allowed to send the PAYMENT_LINK service command in the invoice batch file.
2. You must activate batch processing and invoicing services in the back office.
3. You can download the invoice batch file template from the back office by clicking on the “Batch invoicing” tab. Note that this tab will appear only if you activated the batch invoicing service.
You can start batch invoicing integration by choosing one of the below options:
1. Manually from the back-office by going through simple manual steps.
- Login to your Sandbox account and Go to the Batch Invoicing tab.
- Click Download batch template file. “This template will be downloaded as CSV format in your computer”.
- Fill the template fields with the correct values according to below table .
- Save the file with “.csv” extension and click browse and upload the file to your back-office.
- Process the batch file validated by clicking on process button.
- The invoices will be created as a bulk and sent to customer either by EMAIL or SMS.
- On sandbox environment, the invoices created through Batch service can be tested on sandbox environment using our testing cards mentioned in our API Documentation: https://paymentservices.amazon.com/docs/EN/12.html
{
"service_command": "PAYMENT_LINK",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "AbhiTest-10080",
"amount": "125000",
"currency": "AED",
"language": "en",
"customer_email": "abhivit@amazon.com",
"request_expiry_date":"2022-07-22T15:36:55+03:00",
"notification_type":"EMAIL",
"signature": "{{signature}}"
}
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'service_command'=> 'PAYMENT_LINK',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> 'AbhiTest-10080',
'amount'=> '125000',
'currency'=> 'AED',
'language'=> 'en',
'customer_email'=> 'abhivit@amazon.com',
'request_expiry_date'=>'2022-07-22T15:36:55+03:00',
'notification_type'=>'EMAIL',
'signature'=> '{{signature}}'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'service_command': 'PAYMENT_LINK',
'access_code': '{{access_code}}',
'merchant_identifier': '{{merchant_identifier}}',
'merchant_reference': 'AbhiTest-10080',
'amount': '125000',
'currency': 'AED',
'language': 'en',
'customer_email': 'abhivit@amazon.com',
'request_expiry_date':'2022-07-22T15:36:55+03:00',
'notification_type':'EMAIL',
'signature': '{{signature}}'
};
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 =
{
'service_command'=> 'PAYMENT_LINK',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> 'AbhiTest-10080',
'amount'=> '125000',
'currency'=> 'AED',
'language'=> 'en',
'customer_email'=> 'abhivit@amazon.com',
'request_expiry_date'=>'2022-07-22T15:36:55+03:00',
'notification_type'=>'EMAIL',
'signature'=> '{{signature}}'
};
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)
String jsonRequestString = "{\n \"service_command\": \"PAYMENT_LINK\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"merchantTest-10080\",\n \"amount\": \"125000\",\n \"currency\": \"AED\",\n \"language\": \"en\",\n \"customer_email\": \"merchantvit@amazon.com\",\n \"request_expiry_date\":\"2022-07-22T15:36:55+03:00\",\n \"notification_type\":\"EMAIL\",\n \"signature\": \"\"\n}";
// 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());
ATTRIBUTES | Description |
---|---|
service_command Alpha Mandatory max: 20 |
Command. Possible/ expected values: PAYMENT_LINK |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Mandatory Max: 254 |
The customer’s email. Example: customer@domain.com Special characters: _ - . @ + |
request_expiry_date Alphanumeric Mandatory max: 25 |
The expiry date of invoice, format must be of the following format Example: 20T15:36:55+03:00 |
link_command Alphanumeric Mandatory Max: 15 |
Depending on the merchant account and payment stack Possible/ expected values: PURCHASE / AUTHORIZATION |
notification_type Alphanumeric Mandatory Max: 20 |
How will the customer be notified about this invoice. Possible/ expected values:“EMAIL”, “SMS”, “EMAIL,SMS” |
customer_phone Alpha Optional Max: 19 |
The phone of the customer on which they will recieve the SMS format should be 9ccxxxxxxxxx Possible values: 966551234567 |
cusotmer_name Alpha Mandatory Max: 40 |
The customer name. Possible/ expected values: Jon Doe |
order_description Alphanumeric Optional Max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
return_url Alphanumeric Optional Max: 400 |
The URL of the Merchant’s page to be displayed to the customer when the order is processed. Example: https://www.merchant.com Special characters: $ ! = ? # & - _ / : . |
payment_link_id Alphanumeric Optional Max: 20 |
The unique ID of link generated by the merchant for search purpose Example: 123456432 |
payment_option Alpha Optional Max: 10 |
What are the payment options the customer can be pay in. Possible/ expected values: - MASTERCARD - VISA - AMEX - MADA - KNET - NAPS |
How it Works
1. Create the batch file:
Kindly refer the URLs that contains “Recurring, maintenance Operations , Collect“ parameters that should be included in the batch file and saved as CSV:
https://paymentservices-reference.payfort.com/docs/api/build/index.html#recurring-transactions
https://paymentservices-reference.payfort.com/docs/api/build/index.html#payment-maintenance-operations
https://paymentservices-reference.payfort.com/docs/api/build/index.html#payment-link-service-request
.
- Login to your Sandbox account and Go to the Batch Invoicing tab.
- Click Download batch template file. “This template will be downloaded as CSV format in your computer”.
- Fill the template fields with the correct values according to below table .
- Save the file with “.csv” extension and click browse and upload the file to your back-office.
- Process the batch file validated by clicking on process button.
- The invoices will be created as a bulk and sent to customer either by EMAIL or SMS.
- On sandbox environment, the invoices created through Batch service can be tested on sandbox environment using our testing cards mentioned in our API Documentation: https://paymentservices.amazon.com/docs/EN/12.html
Please refer to the following sample For any explanation about the headers/values included in this file , Please refer to the table listed below
ATTRIBUTES | Description |
---|---|
service_command Alpha Mandatory max: 20 |
Command. Possible/ expected values: PAYMENT_LINK |
merchant_reference Alphanumeric Mandatory Max: 40 |
The Merchant’s unique order number. Example: XYZ9239-yu898 Special characters: - _ . |
amount Numeric Mandatory Max: 10 |
The transaction’s amount. *Each currency has predefined allowed decimal points that should be taken into consideration when sending the amount. Example: 10000 |
currency Alpha Mandatory Max: 3 |
The currency of the transaction’s amount in ISO code 3. Example: AED |
language Alpha Mandatory Max: 2 |
The checkout page and messages language. Possible/ expected values: en/ ar |
customer_email Alphanumeric Mandatory Max: 254 |
The customer’s email. Example: customer@domain.com Special characters: _ - . @ + |
request_expiry_date Alphanumeric Mandatory max: 25 |
The expiry date of invoice, format must be of the following format Example: 20T15:36:55+03:00 |
link_command Alphanumeric Mandatory Max: 15 |
Depending on the merchant account and payment stack Possible/ expected values: PURCHASE / AUTHORIZATION |
notification_type Alphanumeric Mandatory Max: 20 |
How will the customer be notified about this invoice. Possible/ expected values:“EMAIL”, “SMS”, “EMAIL,SMS” |
customer_phone Alpha Optional Max: 19 |
The phone of the customer on which they will recieve the SMS format should be 9ccxxxxxxxxx Possible values: 966551234567 |
cusotmer_name Alpha Mandatory Max: 40 |
The customer name. Possible/ expected values: Jon Doe |
order_description Alphanumeric Optional Max: 150 |
It holds the description of the order. Example: iPhone 6-S Special characters: ' / . _ - # : $ Space |
return_url Alphanumeric Optional Max: 400 |
The URL of the Merchant’s page to be displayed to the customer when the order is processed. Example: https://www.merchant.com Special characters: $ ! = ? # & - _ / : . |
payment_link_id Alphanumeric Optional Max: 20 |
The unique ID of link generated by the merchant for search purpose Example: 123456432 |
payment_option Alpha Optional Max: 10 |
What are the payment options the customer can be pay in. Possible/ expected values: - MASTERCARD - VISA - AMEX - MADA - KNET - NAPS |
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:
{
"query_command": "GENERATE_REPORT",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "99999992011",
"from_date": "2022-07-13T00:00:00+03:00",
"to_date": "2022-07-13T03:01:16+03:00",
"columns": [
"3ds_indicator",
"acquirer_name",
"acquirer_response_code",
"amount",
"authorization_code",
"card_bin",
"currency",
"customer_ip",
"customer_name",
"fort_id",
"merchant_reference",
"operation",
"order_date",
"order_description",
"payment_option",
"response_code",
"response_message",
"status",
"transaction_date"
],
"language": "en",
"response_format": "JSON",
"signature": "{{signature}}",
"filters": [
{
"key": "payment_option",
"value": "VISA"
}
]
}
String jsonRequestString = "{\n \"query_command\": \"GENERATE_REPORT\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"99999992011\",\n \"from_date\": \"2022-07-13T00:00:00+03:00\",\n \"to_date\": \"2022-07-13T03:01:16+03:00\",\n \"columns\": [\n \"3ds_indicator\",\n \"acquirer_name\",\n \"acquirer_response_code\",\n \"amount\",\n \"authorization_code\",\n \"card_bin\",\n \"currency\",\n \"customer_ip\",\n \"customer_name\",\n \"fort_id\",\n \"merchant_reference\",\n \"operation\",\n \"order_date\",\n \"order_description\",\n\n \"payment_option\",\n \"response_code\",\n \"response_message\",\n \"status\",\n \"transaction_date\"\n ],\n \"language\": \"en\",\n \"response_format\": \"JSON\",\n \"signature\": \"\",\n \"filters\": [\n {\n \"key\": \"payment_option\",\n \"value\": \"VISA\"\n }\n ]\n}";
// 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());
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
{
'query_command'=> 'GENERATE_REPORT',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> '99999992011',
'from_date'=> '2022-07-13T00:00:00+03:00',
'to_date'=> '2022-07-13T03:0116+03:00'
'columns'=> [
'3ds_indicator',
'acquirer_name',
'acquirer_response_code',
'amount',
'authorization_code',
'card_bin',
'currency',
'customer_ip',
'customer_name',
'fort_id',
'merchant_reference',
'operation',
'order_date',
'order_description',
'payment_option',
'response_code',
'response_message',
'status',
'transaction_date'
],
'language'=> 'en',
'response_format'=> 'JSON',
'signature'=> '{{signature}}',
'filters'=> [
{
'key'=> 'payment_option',
'value'=> 'VISA'
}
]
}
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
{
'query_command': 'GENERATE_REPORT',
'access_code': '{{access_code}}',
'merchant_identifier': '{{merchant_identifier}}',
'merchant_reference': '99999992011',
'from_date': '2022-07-13T00:00:00+03:00',
'to_date': '2022-07-13T03:0116+03:00',
'columns': [
'3ds_indicator',
'acquirer_name',
'acquirer_response_code',
'amount',
'authorization_code',
'card_bin',
'currency',
'customer_ip',
'customer_name',
'fort_id',
'merchant_reference',
'operation',
'order_date',
'order_description',
'payment_option',
'response_code',
'response_message',
'status',
'transaction_date'
],
'language': 'en',
'response_format': 'JSON',
'signature': '{{signature}}',
'filters': [
{
'key': 'payment_option',
'value': 'VISA'
}
]
}
};
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'=> 'GENERATE_REPORT',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> '99999992011',
'from_date'=> '2022-07-13T00:00:00+03:00',
'to_date'=> '2022-07-13T03:0116+03:00',
'columns'=> [
'3ds_indicator',
'acquirer_name',
'acquirer_response_code',
'amount',
'authorization_code',
'card_bin',
'currency',
'customer_ip',
'customer_name',
'fort_id',
'merchant_reference',
'operation',
'order_date',
'order_description',
'payment_option',
'response_code',
'response_message',
'status',
'transaction_date'
],
'language'=> 'en',
'response_format'=> 'JSON',
'signature'=> '{{signature}}',
'filters'=> [
{
'key'=> 'payment_option',
'value'=> 'VISA'
}
]
}
;
arrData.each {|key, value|
puts key +value ;
}
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)
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 - 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:
{
"query_command": "DOWNLOAD_REPORT",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "99999992011",
"signature": "{{signature}}"
}
String jsonRequestString = "{\n \"query_command\": \"DOWNLOAD_REPORT\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"99999992011\",\n \"signature\": \"\"\n}";
// 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());
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
{
'query_command'=> 'DOWNLOAD_REPORT',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> '99999992011',
'signature'=> '{{signature}}'
}
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData =
{
'query_command': 'DOWNLOAD_REPORT',
'access_code': '{{access_code}}',
'merchant_identifier': '{{merchant_identifier}}',
'merchant_reference': '99999992011',
'signature': '{{signature}}'
};
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'=> 'DOWNLOAD_REPORT',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> '99999992011',
'signature'=> '{{signature}}'
}
;
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)
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 - 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:
{
"query_command": "GET_REPORT",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"from_date": "2022-07-13T00:00:00+03:00",
"to_date": "2022-07-21T23:59:59+03:00",
"columns": [
"3ds_indicator",
"acquirer_name",
"acquirer_response_code",
"amount",
"authorization_code",
"card_bin",
"currency",
"customer_ip",
"customer_name",
"fort_id",
"merchant_reference",
"operation",
"order_date",
"order_description",
"payment_option",
"response_code",
"response_message",
"status",
"transaction_date"
],
"page_size":"1",
"start_index":"1",
"signature": "{{signature}}"
}
String jsonRequestString = "{\n \"query_command\": \"GET_REPORT\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"from_date\": \"2022-07-13T00:00:00+03:00\",\n \"to_date\": \"2022-07-21T23:59:59+03:00\",\n \"columns\": [\n \"3ds_indicator\",\n \"acquirer_name\",\n \"acquirer_response_code\",\n \"amount\",\n \"authorization_code\",\n \"card_bin\",\n \"currency\",\n \"customer_ip\",\n \"customer_name\",\n \"fort_id\",\n \"merchant_reference\",\n \"operation\",\n \"order_date\",\n \"order_description\",\n \"payment_option\",\n \"response_code\",\n \"response_message\",\n \"status\",\n \"transaction_date\"\n ],\n \"page_size\":\"1\",\n \"start_index\":\"1\",\n \"signature\": \"\"\n}";
// 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());
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
{
'query_command'=> 'GET_REPORT',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'from_date'=> '2022-07-13T00:00:00+03:00',
'to_date'=> '2022-07-21T23:59:59+03:00',
'columns'=> [
'3ds_indicator',
'acquirer_name',
'acquirer_response_code',
'amount',
'authorization_code',
'card_bin',
'currency',
'customer_ip',
'customer_name',
'fort_id',
'merchant_reference',
'operation',
'order_date',
'order_description',
'payment_option',
'response_code',
'response_message',
'status',
'transaction_date'
],
'page_size'=>'1',
'start_index'=>'1',
'signature'=> '{{signature}}'
}
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
{
'query_command': 'GET_REPORT',
'access_code': '{{access_code}}',
'merchant_identifier': '{{merchant_identifier}}',
'from_date': '2022-07-13T00:00:00+03:00',
'to_date': '2022-07-21T23:59:59+03:00',
'columns': [
'3ds_indicator',
'acquirer_name',
'acquirer_response_code',
'amount',
'authorization_code',
'card_bin',
'currency',
'customer_ip',
'customer_name',
'fort_id',
'merchant_reference',
'operation',
'order_date',
'order_description',
'payment_option',
'response_code',
'response_message',
'status',
'transaction_date'
],
'page_size':'1',
'start_index':'1',
'signature': '{{signature}}'
};
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'=> 'GET_REPORT',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'from_date'=> '2022-07-13T00:00:00+03:00',
'to_date'=> '2022-07-21T23:59:59+03:00',
'columns'=> [
'3ds_indicator',
'acquirer_name',
'acquirer_response_code',
'amount',
'authorization_code',
'card_bin',
'currency',
'customer_ip',
'customer_name',
'fort_id',
'merchant_reference',
'operation',
'order_date',
'order_description',
'payment_option',
'response_code',
'response_message',
'status',
'transaction_date'
],
'page_size'=>'1',
'start_index'=>'1',
'signature'=> '{{signature}}'
}
;
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)
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:
{
“query_command”:“VERIFY_CARD”,
“merchant_reference”:“XYZ9239-yu898”,
“access_code”:“zx0IPmPy5jp1vAz”,
“merchant_identifier”:“CycHZxVj”,
“language”:“en”,
“signature”:“f93c586997906bac21e8d046407c3fbed6b6820affcb7345353487287cc7c03a”
}
String jsonRequestString = "{\n“query_command”:“VERIFY_CARD”,\n“merchant_reference”:“XYZ9239-yu898”,\n“access_code”:“zx0IPmPy5jp1vAz”,\n“merchant_identifier”:“CycHZxVj”,\n“language”:“en”,\n“signature”:“f93c586997906bac21e8d046407c3fbed6b6820affcb7345353487287cc7c03a”\n}\n";
// 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());
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'query_command'=>'VERIFY_CARD',
'merchant_reference'=>'XYZ9239-yu898',
'access_code'=>'zx0IPmPy5jp1vAz',
'merchant_identifier'=>'CycHZxVj',
'language'=>'en',
'signature'=>'f93c586997906bac21e8d046407c3fbed6b6820affcb7345353487287cc7c03a'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'query_command':'VERIFY_CARD',
'merchant_reference':'XYZ9239-yu898',
'access_code':'zx0IPmPy5jp1vAz',
'merchant_identifier':'CycHZxVj',
'language':'en',
'signature':'f93c586997906bac21e8d046407c3fbed6b6820affcb7345353487287cc7c03a'
};
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'=>'VERIFY_CARD',
'merchant_reference'=>'XYZ9239-yu898',
'access_code'=>'zx0IPmPy5jp1vAz',
'merchant_identifier'=>'CycHZxVj',
'language'=>'en',
'signature'=>'f93c586997906bac21e8d046407c3fbed6b6820affcb7345353487287cc7c03a'
};
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)
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:
{
“query_command”:“CHECK_VERIFY_CARD_STATUS”,
“merchant_reference”:“XYZ9239-yu898”,
“access_code”:“zx0IPmPy5jp1vAz”,
“merchant_identifier”:“CycHZxVj”,
“language”:“en”,
“signature”:“f93c586997906bac21e8d046407c3fbed6b6820affcb7345353487287cc7c03a”
}
String jsonRequestString = "{\n“query_command”:“CHECK_VERIFY_CARD_STATUS”,\n“merchant_reference”:“XYZ9239-yu898”,\n“access_code”:“zx0IPmPy5jp1vAz”,\n“merchant_identifier”:“CycHZxVj”,\n“language”:“en”,\n“signature”:“f93c586997906bac21e8d046407c3fbed6b6820affcb7345353487287cc7c03a”\n}\n";
// 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());
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'query_command'=>'CHECK_VERIFY_CARD_STATUS',
'merchant_reference'=>'XYZ9239-yu898',
'access_code'=>'zx0IPmPy5jp1vAz',
'merchant_identifier'=>'CycHZxVj',
'language'=>'en',
'signature'=>'f93c586997906bac21e8d046407c3fbed6b6820affcb7345353487287cc7c03a'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'query_command':'CHECK_VERIFY_CARD_STATUS',
'merchant_reference':'XYZ9239-yu898',
'access_code':'zx0IPmPy5jp1vAz',
'merchant_identifier':'CycHZxVj',
'language':'en',
'signature':'f93c586997906bac21e8d046407c3fbed6b6820affcb7345353487287cc7c03a'
};
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_VERIFY_CARD_STATUS',
'merchant_reference'=>'XYZ9239-yu898',
'access_code'=>'zx0IPmPy5jp1vAz',
'merchant_identifier'=>'CycHZxVj',
'language'=>'en',
'signature'=>'f93c586997906bac21e8d046407c3fbed6b6820affcb7345353487287cc7c03a'
};
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)
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 |
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: “`shell {
"service_command”: “CREATE_TOKEN”, “access_code”: “{{access_code}}”, “merchant_identifier”: “{{merchant_identifier}}”, “merchant_reference”: “merchantTest-10084”, “amount”: “2000”, “currency”: “AED”, “language”: “en”, “expiry_date”:“5000”, “card_number”:“1111112345678902”, “return_url”:“http://localhost:8081/Merchant_Return_URL.html”, “signature”: “”
} “`
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'service_command'=> 'CREATE_TOKEN',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> 'merchantTest-10084',
'amount'=> '2000',
'currency'=> 'AED',
'language'=> 'en',
'expiry_date'=>'5000',
'card_number'=>'1111112345678902',
'return_url':'http://localhost:8081/Merchant_Return_URL.html',
'signature'=> ''
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'service_command': 'CREATE_TOKEN',
'access_code': '{{access_code}}',
'merchant_identifier': '{{merchant_identifier}}',
'merchant_reference': 'merchantTest-10084',
'amount': '2000',
'currency': 'AED',
'language': 'en',
'expiry_date':'5000',
'card_number':'1111112345678902',
'return_url':'http://localhost:8081/Merchant_Return_URL.html',
'signature': ''
};
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 = {
'service_command'=> 'CREATE_TOKEN',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> 'merchantTest-10084',
'amount'=> '2000',
'currency'=> 'AED',
'language'=> 'en',
'expiry_date'=>'5000',
'card_number'=>'1111112345678902',
'return_url':'http://localhost:8081/Merchant_Return_URL.html',
'signature'=> ''
};
arrData.each {|key, value|
puts key +value ;
}
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)
String jsonRequestString = " {\n\n \n \"service_command\": \"CREATE_TOKEN\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"merchantTest-10084\",\n \"amount\": \"2000\",\n \"currency\": \"AED\",\n \"language\": \"en\",\n \"expiry_date\":\"5000\",\n \"card_number\":\"1111112345678902\",\n \"return_url\":\"http://localhost:8081/Merchant_Return_URL.html\",\n \"signature\": \"\"\n\n\n}";
// 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());
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:
{
"service_command": "UPDATE_TOKEN",
"access_code": "{{access_code}}",
"merchant_identifier": "{{merchant_identifier}}",
"merchant_reference": "merchantTest-10084",
"amount": "2000",
"currency": "AED",
"language": "en",
"card_number":"1111112345678902",
"signature": ""
}
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'service_command'=> 'UPDATE_TOKEN',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> 'merchantTest-10084',
'amount'=> '2000',
'currency'=> 'AED',
'language'=> 'en',
'card_number'=>'1111112345678902',
'signature'=> ''
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'service_command': 'UPDATE_TOKEN',
'access_code': '{{access_code}}',
'merchant_identifier': '{{merchant_identifier}}',
'merchant_reference': 'merchantTest-10084',
'amount': '2000',
'currency': 'AED',
'language': 'en',
'card_number':'1111112345678902',
'signature': '
};
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 =
{
'service_command'=> 'UPDATE_TOKEN',
'access_code'=> '{{access_code}}',
'merchant_identifier'=> '{{merchant_identifier}}',
'merchant_reference'=> 'merchantTest-10084',
'amount'=> '2000',
'currency'=> 'AED',
'language'=> 'en',
'card_number'=>'1111112345678902',
'signature'=> '
};
arrData.each {|key, value|
puts key +value ;
}
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)
String jsonRequestString = "{\n \"query_command\": \"DOWNLOAD_REPORT\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"merchant_reference\": \"99999992011\",\n \"signature\": \"\"\n}";
// 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());
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 |
Difference between Token_name (Temporary & Permanent)
Temporary Token | Permanent Token | |
---|---|---|
How to receive | Will be recieved in the repsonse of Tokenization API | Will be recieved in the repsonse of Operation / Create token API |
Life Time | 30 minutes | Permanent |
Purpose | To process the Operation API request (Payment Request) | To Process MOTO/Recurring For the save card option you could use this permanent token for submitting Operation request directly, So the customers don’t have to re-enter their complete card details for every transaction |
Difference between create_token and Tokenization
create_token | Tokenization | |
---|---|---|
Purpose | Generate a permanent token name directly for you without charging the customer |
Generate the permanent token name,once the customer process a complete success payment |
Card Authenticated | Card will NOT be authenticated by aquirer bank |
Card will be authenticated by aquirer bank |
Payment impact | We will not verify the validity of your customer’s payment card details We will only verify the validity of the payment card details associated with a newly created token once you attempt to charge the customer’s payment card. According to that the recurring/Moto/Next payments may failed because the card declined , … so this is will increase the number of failure transactions in your account) |
We will verify the validity of your customer’s payment card details |
Tokenization service (Remember Me Option) Mobile SDK/Redirection
Pre-Requisites
Tokenization service should be active in your account.
Work Flow
1- The customer will locate (remember me) option in our payment page. 2- If the customer enables the remember_me option in the payment page , and the first payment processed successfully , you will receive a token_name parameter in the response , this token_name can be considered as a permanent token_name and can be used in the next checkouts for the customer if he wishes to pay in his saved card again , you should send the token_name parameter in the next request with the value received from the first payment , the card details will be published in the payment page ( card number as masked value and the expiry date ) , the customer needs to fill the cvc/cvv only and proceed with the payment process .
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:
{
"service_command": "CURRENCY_CONVERSION",
"access_code": "DyGkTj68aMuexd2geu2j",
"merchant_identifier": "bYqNmale",
"amount": "10000",
"currency": "USD",
"language": "en",
"converted_currency":"AED",
"signature": "{{signature}}"
}
String jsonRequestString = "{\n \"service_command\": \"CURRENCY_CONVERSION\",\n \"access_code\": \"{{access_code}}\",\n \"merchant_identifier\": \"{{merchant_identifier}}\",\n \"amount\": \"10000\",\n \"currency\": \"USD\",\n \"language\": \"en\",\n \"converted_currency\":\"AED\",\n \"signature\": \"\"\n}";
// 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());
error_reporting(E_ALL);
ini_set('display_errors', '1');
$url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
$arrData = array(
'service_command'=> 'CURRENCY_CONVERSION',
'access_code'=> 'DyGkTj68aMuexd2geu2j',
'merchant_identifier'=> 'bYqNmale',
'amount'=> '10000',
'currency'=> 'USD',
'language'=> 'en',
'converted_currency'=>'AED',
'signature'=> '{{signature}}'
);
$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>";
import urllib
import urllib2
import json
url = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
arrData = {
'service_command': 'CURRENCY_CONVERSION',
'access_code': 'DyGkTj68aMuexd2geu2j',
'merchant_identifier': 'bYqNmale',
'amount': '10000',
'currency': 'USD',
'language': 'en',
'converted_currency':'AED',
'signature': '{{signature}}'
};
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 =
{
'service_command'=> 'CURRENCY_CONVERSION',
'access_code'=> 'DyGkTj68aMuexd2geu2j',
'merchant_identifier'=> 'bYqNmale',
'amount'=> '10000',
'currency'=> 'USD',
'language'=> 'en',
'converted_currency'=>'AED',
'signature'=> '{{signature}}'
};
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)
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
Mada Branding
In case the merchant has integrated mada there is a mandatory mada branding that has to be added in the merchant checkout to be compliant with mada branding guidelines .
To add mada branding in Merchant checkout pages, Merchant need to follow the below guidelines:
1- “Standalone format” for each payment option:
Display mada logo on both English and Arabic website pages next to the name “mada bank card” in lower case / البنكية مدى بطاقة. Merchant needs to add an alert for customers to choose the Credit card option in case they fill a non-mada BIN in the mada bank card option.
2- Credit card & mada in a single payment option:
Display mada logo as the first logo in the list on both English and Arabic website pages next to the name (name is optional) as shown:
- In English: mada bank card / Credit card
بطاقة مدى البنكية /بطاقة ائتمان : Arabic In- Notes
In case the merchant is using trusted channel or custom merchant page, the merchant needs to check the card BIN “first 6th digits of the card number” once the customer starts filling the card in the card number field, if it matches one of mada BINs merchant needs to display mada logo inside the field. Merchant can do so by building a condition from their end before submitting any request to Amazon Payment Services. This should happen in the client-side browser/app itself; Merchant should not process/store/handle/log/save clear card details.
• On the test environment merchant can use this mada BIN to do your checks “529741". • On production: mada bins list is mentioned in Mada guidelines.
- The mada logo needs to be the same size or larger than other logos
- The mada logo must NOT be placed in a white box in case of colored backgrounds.
- If the Merchant has payment options on the website’s footer, please ensure to add the mada logo there as well - and ensure it is the first logo at all times. Find all the details (Branding guidelines and logo of mada provided from mada and need to be implemented on the checkout page) in the following link :Mada guidelines Important
- Note : Merchant should not to do any changes on mada branding after we’ve confirmed the move to production.
Amex Branding
In case the merchant has integrated Amex and has an entity in KSA , there is a mandatory Amex branding that has to be added in the merchant checkout to be compliant with Amex branding guidelines .
To add Amex branding in your checkout pages, you need to follow these guidelines:
• CVC field accepts 4 digits .
• Display Amex blue box logo or logo type from your end in your checkout page .
•You need to be compliant with Amex branding guidelines for both languages if you have an Arabic and English website.
• The Blue Box Logos and Logotype should never be recreated or modified.
• The Alternate Logo can only be used when the standard Blue Box Logo would not be legible, both should be only Bright Blue, never any other color, never be reversed out or white.
• The selected background color or image area should always allow for optimal Blue Box Logo legibility.
• The Logo type may only be Bright Blue, Deep Blue, White or Cool Gray.
Find all the details (Branding guidelines and logo of Amex provided from Amex and need to be implemented on the checkout page) in the following link : Amex Logo and Guidelines.
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;
?>
#Python version 3.x.x
import hashlib
def calculate(unsorted_dict, sha_phrase, sha_method=hashlib.sha256):
# sorting the keys of the data
sorted_keys = sorted(unsorted_dict, key=lambda x: x.lower())
#sorting the data and concatenating "=" between the key and the value
sorted_dict = {k: unsorted_dict[k] for k in sorted_keys}
result = "".join(f"{k}={v}" for k, v in sorted_dict.items())
#Adding the SHA Request Phrase and preparing the string to the encryption
result_string = f"{sha_phrase}{result}{sha_phrase}"
#Encrypting the result of the out sting with given algorithm from sha_method
signature = sha_method(result_string.encode()).hexdigest()
return signature
#Data Sample
dataDict = {'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'}
print(calculate(dataDict,"YOUR_SHA_PHRASE","sha256"))
require 'digest'
def calculate(unsorted_arr,sha_phrase)
#Sorting the keys of the data alphabetically with by the key
unsorted_arr = unsorted_arr.sort.to_h
result = ""
#Concatenating "=" between the key and the value
unsorted_arr.each do |key, value|
result+= key+"="+value
end
#Encrypting the result of the out sting with SHA256 method
signature = Digest::SHA256.hexdigest(sha_phrase+result+sha_phrase);
#Return the signautre
return signature
end
#Data Sample
data_arr = {'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'
}
#calculate(data, YOUR_SHA_PHRASE,)
#Calling the function and print the value
print calculate(data_arr,"YOUR_SHA_PHRASE")
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
<FORT_PARAMETER_NAME_1>VALUE</FORT_PARAMETER_NAME_1>
<FORT_PARAMETER_NAME_2_list>
<FORT_PARAMETER_NAME_2>
<FORT_PARAMETER_NAME_3>VALUE</FORT_PARAMETER_NAME_3>
<FORT_PARAMETER_NAME_4>VALUE</FORT_PARAMETER_NAME_4>
<FORT_PARAMETER_NAME_5>VALUE</FORT_PARAMETER_NAME_5>
</FORT_PARAMETER_NAME_2>
<FORT_PARAMETER_NAME_2>
<FORT_PARAMETER_NAME_3>VALUE</FORT_PARAMETER_NAME_3>
<FORT_PARAMETER_NAME_4>VALUE</FORT_PARAMETER_NAME_4>
<FORT_PARAMETER_NAME_5>VALUE</FORT_PARAMETER_NAME_5>
</FORT_PARAMETER_NAME_2>
</FORT_PARAMETER_NAME_2_list>
</FORT_PARAMETER_NAME_1>VALUE</FORT_PARAMETER_NAME_1>
</response>
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
<response_code>54000</response_code>
<from_date>2017-01-19T12:20:00+02:00</from_date>
<data_list>
<data>
<card_number>455701******8902</card_number>
<expiry_date>2105</expiry_date>
<token_name>466E93413AB648DEE053320A10AC5986</token_name>
<card_brand>VISA</card_brand>
<card_bin>455701</card_bin>
<token_status>ACTIVE</token_status>
<creation_date>2017-01-20T08:25:37+13:00</creation_date>
</data>
<data>
<card_number>400555******0001</card_number>
<expiry_date>1705</expiry_date>
<token_name>tkn001</token_name>
<card_brand>VISA</card_brand>
<card_bin>455701</card_bin>
<token_status>ACTIVE</token_status>
<creation_date>2016-05-13T14:34:09+13:00</creation_date>
</data>
</data_list>
<signature>4b6b1f0219169b0dc77f7ceac83b930cf71995ab7a4fcc435a</signature>
<merchant_identifier>uZOJfKqb</merchant_identifier>
<access_code>AwvucffCjzibl0eZYTB3</access_code>
<language>en</language>
<response_format>XML</response_format>
<response_message>Success</response_message>
<to_date>2017-01-19T12:30:00+02:00</to_date>
<query_command>GET_TOKENS</query_command>
<data_count>1</data_count>
<status>54</status>
</response>
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. |
181 | You didn’t reach the minimum amount for this service. |
221 | You exceeded the maximum amount for this service. |
225 | This operation is not permitted for merchant to use. |
662 | Operation not allowed. The specified order is not confirmed yet. |
666 | Transaction declined. |
746 | Purchase amount is more than the customer limit |
747 | Insufficient Wallet Balance |
748 | PARAMETER_MISMATCH — Send OTP and purchase request parameters do not match. |
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”.
Difference between Authorization and Purchase
Authorization | Purchase |
---|---|
Its a command submitted in the request in order to hold an amount from the Customer’s credit card account for a period of time (Specified from the bank side). | The Purchase command means to authorize and capture the transaction amount automatically in one single request, accordingly the amount will be deducted from the customer’s card. |
If no capture or void was processed during this period, the transaction will be voided automatically from the bank side | Cant be voided. |
The authorized amount can’t be refunded until it’s captured from the customer credit card, the Authrorizer has the ability to void it only if it’s not captured. | It can be refunded after a successful transaction. |
Redirection URL (return_url)
The return_url is your implemented endpoint with controller to handle the response received from our end after the processed payment to consider the page where you need to redirect the customer after processing the transaction and display a proper message for the customers indicates the payment status in your checkout page ( failed or accepted ).
Return_URL is a parameter that you send in your request , while Redirection_URL is configured in your account under Integration settings , Technical settings tab. if you send the return_url in your request it will override the Redirection URL configured in your account in that transaction processed .
Redirection_URL which you need to configure should be reachable and accepting of POST method so we can post the response after each payment on this URL. Also this url should not contain an ip address or port number, as is it should consist of your domain name.
If you are using one of our plugins, Please copy the “host to host url” which you can find in the plugin configuration page, then go to your account >> Technical Settings >> click on the needed channel (Redirection, Merchant page) >> paste the url in the three url fields displayed then save changes.
Secure Connect
Secure Sockets Layer (SSL) and Transport Layer Security (TLS) certificates allow systems to verify the identity and establish an encrypted network connection using specific protocols. SSL and TLS certificates function as digital identity cards to secure network communication, and to check the identity of websites and resources on private networks.
You can securely connect to the Amazon Payment Services servers using TLS certificates to utilize the plugins, cURL, and other HTTP clients to access Amazon Payment Services APIs. TLS certificates ensure that the API calls remain secure, and are safeguarded against unauthorized access. The SSL and TLS certificates are constantly validated, each time you connect to the Amazon Payment Services server.
Certificate Pinning
Certificate pinning is a security measure that is implemented in applications in order to authenticate remote hosts. Certificate pinning directly associates the host with its certificate or public key, instead of relying on a certificate hierarchy. This enables the application to bypass the standard SSL/TLS certificate chain validation process. In a typical scenario, SSL validation involves verifying the signature along the certificate chain, beginning from the root certificate authority (CA) through any subordinate CA certificates, and ultimately checking the certificate for the remote host at the lowest level of the hierarchy.
Certificate pinning enables the application to trust the certificate of the remote host. It does not trust the root certificate or any other certificates that are available in the chain. This certificate or the public key can be integrated into the application at the development stage. The application can also incorporate the certificate while establishing the first connection with the host.
How will you be affected?
Amazon Payment Services recommends against pinning certificates to avoid intricate merchant integration setup, especially when the domain certificates are being rotated. For more information on certificate pinning, see Certificate pinning problems.
However, if your internal policies demand that certificate pinning be enabled, Amazon Payment Services recommends you to maintain an internal standard operating procedure (SOP) for your team to keep track of certificate updates. Amazon Payment Services sends regular email updates to the account admin appraising about the upcoming schedules for certificate rotation for the associated domains.
NOTE: Certificate pinning might introduce new challenges when you update certificates on the server side. Ensure that you build a strategy to handle certificate updates and revocations. If you have explicitly specified a list of acceptable CAs for domains, your services might be impacted when a new TLS certificate is released.
Certificate Update
Amazon Payment Services does not track merchant accounts, while enabling certificate pinning and adding domain certificates. However, Amazon Payment Services sends regular updates to the merchant account email ID, to inform about the schedules for domain certificate updates. Amazon Payment Services issues new certificates to replace expired certificates as per the schedule.
NOTE: When a certificate update is notified, ensure that you add the new TLC certificate to the trust and whitelist group. Your business transactions will be affected if your system continues to pin the expired certificates.
Certificates for Amazon Payment Services Endpoints
Amazon Payment Services provides certificates for the following endpoints to a merchant to authenticate when merchants establish secure connections to our API endpoints. Ensure that you whitelist or trust certificates before you connect to the endpoints.
Endpoint | URL |
---|---|
checkout.payfort.com | https://checkout.payfort.com/ |
paymentservices.payfort.com | https://paymentservices.amazon.com/ |
*.payfort.com | https://paymentservices.amazon.com/ |
NOTE * indicate the sub-domains that can be used with PayFort.
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.
To configure these URLs, please go to your Technical Settings Tab in your Amazon Payment services account and click on the activated channel you have, then configure the URL under Direct Feedback and Notification Feedback URLs. - Kindly avoid configuring any invalid URLs such as (apple.com, google.com, example.com …etc) in your accounts (test/production).If you are planning to use our accounts only for Invoicing/Subscription/E-terminal solutions, and you don’t have any active connection and integration between your website and Amazon Payment Services account, please use your domain URL / Terms & conditions URL for all the fields listed in your technical settings tab.)
Difference between Direct Transaction Feedback and Notification URL.
Direct Transaction Feedback URL | Notification URL | |
---|---|---|
Purpose | 1-In order to Update the order status using the request call that will be submitted from our server to your server after each processed transaction in the website/app. | 1- In order to push the recovery response of the transaction in-case of any outages on the processor level 2- In order to send the notification for Maintenance operations (capture, refund, and void authorization) accordingly update the transaction status. |
Configuration | Go to your account >> Technical Settings >> Choose the channel ( Merchant Page, Redirection, Mobile SDK,… ) >> Direct Transaction Feedback URL | Go to your account >> Technical Settings >> Choose the channel ( Merchant Page, Redirection, Mobile SDK,… ) >> Notification URL |
Data type | https reachable accepting a POST method should not contain an IP address or port number, as is it should consist of your domain name. | https reachable accepting a POST method should not contain an IP address or port number, as is it should consist of your domain name. |
Transaction feedback log
Transaction Feedback Log indicates if we are able to push the response parameters for the transaction successfully after each payment to your server as Post method.
The final status column will indicate whether we have pushed the response parameters successfully or not.
- If the “final status” is successful that means we have sent the parameters successfully to your server.Final Status Success
- If the final status is failed we can check the details to know the exact error APS has received from your server while posting the parameters.
- On details you can see the notification URL that we have sent the payment response parameters to as post https method and the response code and response status which your server has returned to APS when we tried to post the response parameters
- If the status is failed, it means that there is an issue with the server connection and we have tried to send the response parameters after processing the transaction but we have failed do so due to an issue in your server connection.
For example in the image below the server responded with Response Code :500 and a Response Status : Internal server error.
To solve this issue you need to configure a direct transaction feedback url and the notification url in your account which are reachable ( returns 200 or any successful http respons) and accepts POST method so we can post the response after each payment on the configured URL in your account under the Technical settings tab.
You can check the Direct and Notification Feedback logs in your Amazon Payment Services back-office Account to check the details related to the submission like the Transaction Feedback URL which was triggered, The response which our Amazon Payment Services system pushed , The response Code and Status retuned from your Transaction Feedback URL.
The specifics of the data will differ based upon the financial operation that has been processed. Please refer to the Amazon Payment Services integration guide for more details.
If you want to change the submission type to JSON or XML, you can contact us on **integration-ps@amazon.com**.
If you want to change the grace period or the time interval between the retries please contact us on **integration-ps@amazon.com**.
Go Live Checklist
In order to confirm your sign-off and create a production account for you,
Email us on : integration-ps@amazon.com
The following information should be included in your email.
1-Email Subject : Integration Sign-off - The website name
2-Please share with us the requested details applicable to your integration which listed under section Test The Integration section .
3-Please consider the listed items applicable to your integration under section Verify The Integration.
You will receive the listed verification points as checklist FORM that you need to submit for confirming your integration.
4-If you integrated with local payment options ex: mada , STCPAY ,You need to take in consideration the verification points listed under your integration ex: Redirection, in addition to payment option related points.
Note: If you’re integrated using supported plug-in, only Go to Test The Integration section and please share with us the requested details.
Test The Integration
In order to start the Integration certification process for your website/Application:
1. You need to provide us with the below screenshots as a ZIP file/pdf size 20MB (URLs should be visible in your screenshots):
Screenshots Requested | Reason |
---|---|
The Page before the checkout page | This is required only for MADA users as we’ll check If you have implemented MADA branding |
The checkout page | We’ll check the custom merchant page integration and redirection payement page |
3-D Secure Page | We’ll check whether you’re displaying 3DS URL in the main window |
The page after the checkout page when the customer returns to your website |
We’ll check the success or failed messages after transaction |
Code snipped for TOKENIZATION Request | This is only if you are using “Custom Merchant Page” integration in mobile application We will check if You are submitting Tokenization service_command as “POST FORM”,“FRONT-END” since this is the only allowed option |
2. You need to cover the below test scenarios using our testing cards:
- Success test transaction using one of the Non 3-D Secure Credit Cards
- Success test transaction using one of the 3-D Secure Credit Cards
- Declined test transaction using the Declined Credit Card
- Success test transaction using one of the Credit Cards for Installments
- Success test transaction using Mada test card (If you have SAR currency in your website)
3. Share the merchant references for the simulated test cases in order to validate your account logs
Apple pay
In order to start the Integration certification process for your website/Application:
1. Simulate a Success test transaction using apple pay testing cards, then share with us the merchant references for the simulated test cases in order to validate your account logs.
2. Provide us with the below screenshots:
- Code snippet for the Supported payment network, to validate you have chosen mada and Amex as one of the supported payment network
- Code snippet for the merchant capability
KNET
In order to begin KNET certification process:
1. Provide us with the below screenshots of the payment flow on your website or application and share the merchant references for both simulated test cases using our KNET testing card in order to validate your account logs:
- The Page before the checkout page(buy/product page)
- The checkout page
- Knet payment page
- Knet confirmation page
- The receipt page (the page after the checkout page when the customer is returned to your website)
2. Make sure you include two sets of screenshots (one for a success transaction and another for a declined transaction) and include each set in a separate .zip file.
NAPS
In order to begin NAPS certification process:
1. Provide us with the below screenshots of the payment flow on your website or application and share the merchant reference for both simulated test cases in both languages(Arabic and English) using our NAPS testing card in order to validate your account logs:
- The Page before the checkout page
- The checkout page
- NAPS payment page
- NAPS confirmation page
- The receipt page (the page after the checkout page when the customer is returned to your website)
2. Make sure you include two sets of screenshots (one for a success transaction and another for a declined transaction) and include each set in a separate .zip file.
BENEFIT
In order to begin BENEFIT certification process:
1.Provide us with the below screenshots of the payment flow on your website or application and share the merchant references for both simulated test cases using our BENEFIT testing cards in order to validate your account logs:
- The Page before the checkout page
- The checkout page that contains Benefit payment option
- Benefit payment page
- Order confirmation page
- The page after the checkout page when the customer is returned to your website
2. Make sure you include two sets of screenshots (one for a success transaction and another for a declined transaction) and include each set in a separate .zip file.
OmanNet
In order to begin OmanNet certification process:
1.Provide us with the below screenshots of the payment flow on your website or application and share the merchant reference for both simulated test cases in order to validate your account logs:
- The Page before the checkout page
- The checkout page contains OmanNet payment option
- OmanNet payment page
- OmanNet OTP page
- Order confirmation page
- The page after the checkout page when the customer is returned to your website
2. Send the screenshots in a .zip file.
STCPAY
In order to begin STCPAY certification process:
1.Provide us with the below screenshots of the payment flow on your website or application and share the merchant references for both simulated test cases using our STCPAY testing number in order to validate your account logs:
- The Page before the checkout page
- The checkout page which contains STCPAT payment option
- STCPAY payment pages [phone number and OTP]
- The page after the checkout page when the customer is returned to your website
2. Make sure you include two sets of screenshots (one for a success transaction and another for a declined transaction) and include each set in a separate .zip file.
Verify The Integration
Go through the below verification criteria and make sure you have implemented them.
We will send to you the below points as checklist form you need to submit, to confirm your sign-off.
Verify Redirection Integration
check point | Integration and Definition |
---|---|
Detect Customer Email Address | Detect the customer Actual email address and pass it to customer_email parameter Sending static value to customer_email parameter will cause the transaction to be blocked by our fraud detection tool in production environment |
Accept responses returned as POST FORMs | The return_url submitted in the API Request accepts the response returned as POST FORM since in the production environment you will have only POST Method option to receive the responses. In addition, the value passed to return_url parameter in the API Request should be https |
Request and Response Signature Calculations and validations | 1- While calculating the request signature, make sure to exclude the empty parameters (without values) from the signature calculations to avoid mismatch, this is applicable for all API requests submitted to APS 2-For the response signature, You need to validate the signature you receive from Amazon Payment Services by calculating the signature for the response parameters you receive on the return_url once the transaction is processed using the SHA response phrase listed in your test account under: Integration settings >> Security settings, the value of the calculated signature should match the value of the signature returned from Amazon Payment Services 3- Please make sure that you are handling the response as it is returned from APS without trimming any trailing spaces so you can be able to validate response signature correctly 4- Identify your request and response SHA phrases and make sure to do the signature calculations from your back-end only |
Transaction Feedback Implementation | Your code handles the response parameters received on Check Status API or Direct Transaction Feedback for payment instant responses and Notification Feedback URL for the recovery responses under Technical Settings, In this step, you need to create an endpoint to receive response parameters as a POST Method. To configure these URLs, please go to your Technical Settings Tab in your Amazon Payment services account and click on the activated channel you have, then configure the URL under Direct Feedback and Notification Feedback URLs. - Kindly avoid configuring any invalid URLs such as (apple.com, google.com, example.com …etc) in your accounts (test/production).If you are planning to use our accounts only for Invoicing/Subscription/E-terminal solutions, and you don’t have any active connection and integration between your website and Amazon Payment Services account, please use your domain URL / Terms & conditions URL for all the fields listed in your technical settings tab.) |
Amount Validation | Remember to validate the actual amount deducted from the customer, as it should matches the same amount you submit in the API requests to Amazon Payment services This is required to protect your website from any fraud |
The command parameter value PURCHASE or AUTHORIZATION | PURCHASE command means that the amount will be fully deducted from the customer’s card to your bank account (The amount is Automatically captured) AUTHORIZATION command means that the amount will be held from the customer’s card without capturing , the capture for the authorized amount should be done from your side manually through the back-office under Order Transaction Management tab or automatically through our APIs. You can find more details in the API documentation section Payment maintenance operations |
Different Inbound Server IP in Sandbox and Production | Remember to not use the same Inbound server IP you are currently using in Sandbox environment to submit the API Requests in the Production environment while submitting API requests for real payments to avoid impacting both environments |
MADA | You need to follow MADA Branding Document to add MADA branding in the checkout page |
NAPS | This document covers the guidelines that you need to follow to conclude the certification successfully with QPAY PG QPAY Certification Guidelines and UI Best Practices |
BENEFIT | You need to follow BENEFIT Branding Document to add BENEFIT payment button |
Knet | As a mandatory Knet requirement, you must display two Knet related ID’s (knet_ref_number ,third_party_transaction_number) , payment amount and transaction date in the receipt page which is the page theat the customer will be redirected to it after processing the payment |
Amex | You need to follow AMEX branding guidelines to add amex branding |
Your website was tested on Google Chrome web browser.
We encourage you to test it on other browsers and from different Operating systems and confirm normal operations. .
Verify Standard Merchant Page Integration
check point | Integration and Definition |
---|---|
Detect Customer Email Address and IP | Detect the customer Actual email address and pass it to customer_email parameter Detect the public IP address for the customer who’s browsing your website/application and pass it to customer_ip parameter in the Payment Operation request Sending static value to customer_email or customer ip parameter will cause the transaction to be blocked by our fraud detection tool in production environment |
Accept responses returned as POST FORMs | The return_url submitted in the API Request accepts the response returned as POST FORM since in the production environment you will have only POST Method option to receive the responses. In addition, the value passed to return_url parameter in the API Request should be https |
Request and Response Signature Calculations and validations | 1- While calculating the request signature, make sure to exclude the empty parameters (without values) from the signature calculations to avoid mismatch, this is applicable for all API requests submitted to APS 2-For the response signature, You need to validate the signature you receive from Amazon Payment Services by calculating the signature for the response parameters you receive on the return_url once the transaction is processed using the SHA response phrase listed in your test account under: Integration settings >> Security settings, the value of the calculated signature should match the value of the signature returned from Amazon Payment Services 3- Please make sure that you are handling the response as it is returned from APS without trimming any trailing spaces so you can be able to validate response signature correctly 4- Identify your request and response SHA phrases and make sure to do the signature calculations from your back-end only |
Amount Validation | Remember to validate the actual amount deducted from the customer, as it should matches the same amount you submit in the API requests to Amazon Payment services This is required to protect your website from any fraud |
Transaction Feedback Implementation | Your code handles the response parameters received on Check Status API or Direct Transaction Feedback for payment instant responses and Notification Feedback URL for the recovery responses under Technical Settings, In this step, you need to create an endpoint to receive response parameters as a POST Method. To configure these URLs, please go to your Technical Settings Tab in your Amazon Payment services account and click on the activated channel you have, then configure the URL under Direct Feedback and Notification Feedback URLs. - Kindly avoid configuring any invalid URLs such as (apple.com, google.com, example.com …etc) in your accounts (test/production).If you are planning to use our accounts only for Invoicing/Subscription/E-terminal solutions, and you don’t have any active connection and integration between your website and Amazon Payment Services account, please use your domain URL / Terms & conditions URL for all the fields listed in your technical settings tab.) |
Tokenization Service command | Submit Tokenization service_command as POST FORM, from client side (browser/mobile app) only It is a PCI mandate to submit this request from client side & you should not process/store/handle/log/save clear card details |
Dynamic Controller for 3DS | Remember to implement a dynamic controller from your end to handle the 3DS service , if you receive the 3ds_url you can redirect the customers to it , otherwise “if it’s “NULL” you need to consider the final response returned to you in JSON body and update the customer in his checkout page about the final payment status. |
Merchant Page Customization | Change the look and feel for our current Merchant Page by following the below: 1- check our CSS classes and update them 2-insert your changes in a CSS file so we can upload it in your account under Payment Page Template tab to inject your changes It’s highly recommend to do that to fit your checkout page look and feel. |
The command parameter value PURCHASE or AUTHORIZATION | PURCHASE command means that the amount will be fully deducted from the customer’s card to your bank account ( Automatically captured for the amount ) AUTHORIZATION command means that the amount will be held from the customer’s card without capturing , the capture for the authorized amount will happen from your side manually through the back-office under Order Transaction Management tab or automatically through our APIs. You can find more details in the API documentation section Payment maintenance operations |
Different Inbound Server IP in Sandbox and Production | Remember to not use the same Inbound server IP you are currently using in Sandbox environment to submit the API Requests in the Production environment while submitting API requests for real payments to avoid impacting both environments |
Advanced Fraud Tool( ReD ) | If you agreed with your account manager to have our Advanced Fraud Tool ( ReD ) active in your production account To protect your transactions you need to add the device_fingerprint parameter in the purchase/authorization request using our script to generate the value, check our device fingerprint script |
MADA | You need to follow MADA Branding Document to add MADA branding in the checkout page |
Amex | You need to follow AMEX branding guidelines to add amex branding |
Your website was tested on Google Chrome web browser. We encourage you to test it on other browsers and from different Operating systems and confirm normal operations. .
Verify Custom Merchant Page Integration
check point | Integration and Definition |
---|---|
Detect Customer Email Address and IP | Detect the customer Actual email address and pass it to customer_email parameter Detect the public IP address for the customer who’s browsing your website/application and pass it to customer_ip parameter in the Payment Operation request Sending static value to customer_email or customer ip parameter will cause the transaction to be blocked by our fraud detection tool in production environment |
Accept responses returned as POST FORMs | The return_url submitted in the API Request accepts the response returned as POST FORM since in the production environment you will have only POST Method option to receive the responses. In addition, the value passed to return_url parameter in the API Request should be https |
Request and Response Signature Calculations and validations | 1- While calculating the request signature, make sure to exclude the empty parameters (without values) from the signature calculations to avoid mismatch, this is applicable for all API requests submitted to APS 2-For the response signature, You need to validate the signature you receive from Amazon Payment Services by calculating the signature for the response parameters you receive on the return_url once the transaction is processed using the SHA response phrase listed in your test account under: Integration settings >> Security settings, the value of the calculated signature should match the value of the signature returned from Amazon Payment Services 3- Please make sure that you are handling the response as it is returned from APS without trimming any trailing spaces so you can be able to validate response signature correctly 4- Identify your request and response SHA phrases and make sure to do the signature calculations from your back-end only |
Transaction Feedback Implementation | Your code handles the response parameters received on Check Status API or Direct Transaction Feedback for payment instant responses and Notification Feedback URL for the recovery responses under Technical Settings, In this step, you need to create an endpoint to receive response parameters as a POST Method. To configure these URLs, please go to your Technical Settings Tab in your Amazon Payment services account and click on the activated channel you have, then configure the URL under Direct Feedback and Notification Feedback URLs. - Kindly avoid configuring any invalid URLs such as (apple.com, google.com, example.com …etc) in your accounts (test/production).If you are planning to use our accounts only for Invoicing/Subscription/E-terminal solutions, and you don’t have any active connection and integration between your website and Amazon Payment Services account, please use your domain URL / Terms & conditions URL for all the fields listed in your technical settings tab.) |
Tokenization Service command | Submit Tokenization service_command as POST FORM, from client side (browser/mobile app) only It is a PCI mandate to submit this request from client side & you should not process/store/handle/log/save clear card details |
Dynamic Controller for 3DS | Remember to implement a dynamic controller from your end to handle the 3DS service , if you receive the 3ds_url you can redirect the customers to it , otherwise “if it’s “NULL” you need to consider the final response returned to you in JSON body and update the customer in his checkout page about the final payment status. |
Amount Validation | Remember to validate the actual amount deducted from the customer, as it should matches the same amount you submit in the API requests to Amazon Payment services This is required to protect your website from any fraud |
Different Inbound Server IP in Sandbox and Production | Remember to not use the same Inbound server IP you are currently using in Sandbox environment to submit the API Requests in the Production environment while submitting API requests for real payments to avoid impacting both environments |
Advanced Fraud Tool( ReD ) | If you agreed with your account manager to have our Advanced Fraud Tool ( ReD ) active in your production account To protect your transactions you need to add the device_fingerprint parameter in the purchase/authorization request using our script to generate the value, check our device fingerprint script |
MADA | You need to follow MADA Branding Document to add MADA branding in the checkout page |
Amex | You need to follow AMEX branding guidelines to add amex branding |
STCPAY | Detect the actual phone_number and OTP filled by the customer in your checkout page without having them static in the API Requests |
Your website was tested on Google Chrome web browser. We encourage you to test it on other browsers and from different Operating systems and confirm normal operations. .
Verify Trusted Integration
check point | Integration and Definition |
---|---|
Detect Customer Email Address and IP | Detect the customer Actual email address and pass it to customer_email parameter Detect the public IP address for the customer who’s browsing your website/application and pass it to customer_ip parameter in the Payment Operation request Sending static value to customer_email or customer ip parameter will cause the transaction to be blocked by our fraud detection tool in production environment |
Accept responses returned as POST FORMs | The return_url submitted in the API Request accepts the response returned as POST FORM since in the production environment you will have only POST Method option to receive the responses. In addition, the value passed to return_url parameter in the API Request should be https |
Request and Response Signature Calculations and validations | 1- While calculating the request signature, make sure to exclude the empty parameters (without values) from the signature calculations to avoid mismatch, this is applicable for all API requests submitted to APS 2-For the response signature, You need to validate the signature you receive from Amazon Payment Services by calculating the signature for the response parameters you receive on the return_url once the transaction is processed using the SHA response phrase listed in your test account under: Integration settings >> Security settings, the value of the calculated signature should match the value of the signature returned from Amazon Payment Services 3- Please make sure that you are handling the response as it is returned from APS without trimming any trailing spaces so you can be able to validate response signature correctly 4- Identify your request and response SHA phrases and make sure to do the signature calculations from your back-end only |
Transaction Feedback Implementation | Your code handles the response parameters received on Check Status API or Direct Transaction Feedback for payment instant responses and Notification Feedback URL for the recovery responses under Technical Settings, In this step, you need to create an endpoint to receive response parameters as a POST Method. To configure these URLs, please go to your Technical Settings Tab in your Amazon Payment services account and click on the activated channel you have, then configure the URL under Direct Feedback and Notification Feedback URLs. - Kindly avoid configuring any invalid URLs such as (apple.com, google.com, example.com …etc) in your accounts (test/production).If you are planning to use our accounts only for Invoicing/Subscription/E-terminal solutions, and you don’t have any active connection and integration between your website and Amazon Payment Services account, please use your domain URL / Terms & conditions URL for all the fields listed in your technical settings tab.) |
Dynamic Controller for 3DS | Remember to implement a dynamic controller from your end to handle the 3DS service , if you receive the 3ds_url you can redirect the customers to it , otherwise “if it’s “NULL” you need to consider the final response returned to you in JSON body and update the customer in his checkout page about the final payment status. |
Amount Validation | Remember to validate the actual amount deducted from the customer, as it should matches the same amount you submit in the API requests to Amazon Payment services This is required to protect your website from any fraud |
Different Inbound Server IP in Sandbox and Production | Remember to not use the same Inbound server IP you are currently using in Sandbox environment to submit the API Requests in the Production environment while submitting API requests for real payments to avoid impacting both environments |
Advanced Fraud Tool( ReD ) | If you agreed with your account manager to have our Advanced Fraud Tool ( ReD ) active in your production account To protect your transactions you need to add the device_fingerprint parameter in the purchase/authorization request using our script to generate the value, check our device fingerprint script |
MADA | You need to follow MADA Branding Document to add MADA branding in the checkout page |
Amex | You need to follow AMEX branding guidelines to add amex branding |
Your website was tested on Google Chrome web browser. We encourage you to test it on other browsers and from different Operating systems and confirm normal operations. .
Verify Mobile SDK Integration
check point | Integration and Definition |
---|---|
Detect Customer Email Address and IP | Detect the customer Actual email address and pass it to customer_email parameter Detect the public IP address for the customer who’s browsing your website/application and pass it to customer_ip parameter in the Payment Operation request Sending static value to customer_email or customer ip parameter will cause the transaction to be blocked by our fraud detection tool in production environment |
Request and Response Signature Calculations and validations | 1- While calculating the request signature, make sure to exclude the empty parameters (without values) from the signature calculations to avoid mismatch, this is applicable for all API requests submitted to APS 2-For the response signature, You need to validate the signature you receive from Amazon Payment Services by calculating the signature for the response parameters you receive on the return_url once the transaction is processed using the SHA response phrase listed in your test account under: Integration settings >> Security settings, the value of the calculated signature should match the value of the signature returned from Amazon Payment Services 3- Please make sure that you are handling the response as it is returned from APS without trimming any trailing spaces so you can be able to validate response signature correctly 4- Identify your request and response SHA phrases and make sure to do the signature calculations from your back-end only |
Transaction Feedback Implementation | Your code handles the response parameters received on Check Status API or Direct Transaction Feedback for payment instant responses and Notification Feedback URL for the recovery responses under Technical Settings, In this step, you need to create an endpoint to receive response parameters as a POST Method. To configure these URLs, please go to your Technical Settings Tab in your Amazon Payment services account and click on the activated channel you have, then configure the URL under Direct Feedback and Notification Feedback URLs. - Kindly avoid configuring any invalid URLs such as (apple.com, google.com, example.com …etc) in your accounts (test/production).If you are planning to use our accounts only for Invoicing/Subscription/E-terminal solutions, and you don’t have any active connection and integration between your website and Amazon Payment Services account, please use your domain URL / Terms & conditions URL for all the fields listed in your technical settings tab.) |
Amount Validation | Remember to validate the actual amount deducted from the customer, as it should matches the same amount you submit in the API requests to Amazon Payment services This is required to protect your website from any fraud |
The SDK_TOKEN generation | You need to handle the SDK_TOKEN generation from your server side not from the application, since this API request contains your security settings values which shouldn’t pass your application, that’s why we shift the signature calculations to the back-end not to be in the mobile application for any reverse engineering may occur |
You are using the latest SDK version | Check Amazon Payment Services repositories on github to get the latest Mobile SDK version Amazon Payment Services |
Different Inbound Server IP in Sandbox and Production | Remember to not use the same Inbound server IP you are currently using in Sandbox environment to submit the API Requests in the Production environment while submitting API requests for real payments to avoid impacting both environments |
MADA | You need to follow MADA Branding Document to add MADA branding in the checkout page |
Amex | You need to follow AMEX branding guidelines to add amex branding |
Verify Apple pay Integration
Apple pay Merchant page
check point | Integration and Definition |
---|---|
Detect Customer Email Address and IP | Detect the customer Actual email address and pass it to customer_email parameter Detect the public IP address for the customer who’s browsing your website/application and pass it to customer_ip parameter in the Payment Operation request Sending static value to customer_email or customer ip parameter will cause the transaction to be blocked by our fraud detection tool in production environment |
Accept responses returned as POST FORMs | The return_url submitted in the API Request accepts the response returned as POST FORM since in the production environment you will have only POST Method option to receive the responses. In addition, the value passed to return_url parameter in the API Request should be https |
Request and Response Signature Calculations and validations | 1- While calculating the request signature, make sure to exclude the empty parameters (without values) from the signature calculations to avoid mismatch, this is applicable for all API requests submitted to APS 2-For the response signature, You need to validate the signature you receive from Amazon Payment Services by calculating the signature for the response parameters you receive on the return_url once the transaction is processed using the SHA response phrase listed in your test account under: Integration settings >> Security settings, the value of the calculated signature should match the value of the signature returned from Amazon Payment Services 3- Please make sure that you are handling the response as it is returned from APS without trimming any trailing spaces so you can be able to validate response signature correctly 4- Identify your request and response SHA phrases and make sure to do the signature calculations from your back-end only |
Transaction Feedback Implementation | Your code handles the response parameters received on Check Status API or Direct Transaction Feedback for payment instant responses and Notification Feedback URL for the recovery responses under Technical Settings, In this step, you need to create an endpoint to receive response parameters as a POST Method. To configure these URLs, please go to your Technical Settings Tab in your Amazon Payment services account and click on the activated channel you have, then configure the URL under Direct Feedback and Notification Feedback URLs |
Amount Validation | Remember to validate the actual amount deducted from the customer, as it should matches the same amount you submit in the API requests to Amazon Payment services This is required to protect your website from any fraud |
Supported Payment methods | Make sure that you have chosen mada and Amex as one of the supported payment network in your Apple Pay integration For more details about the supported Payment Networks you can add in your current Integration, please refer to the reference from Apple Supported Networks |
MADA considerations | Set country code as SA for mada payments on Apple pay, here is the URL for your reference: Country Codes |
Different Inbound Server IP in Sandbox and Production | Remember to not use the same Inbound server IP you are currently using in Sandbox environment to submit the API Requests in the Production environment while submitting API requests for real payments to avoid impacting both environments |
Applepay capability | Set the merchant capability in your apple pay wesbite integration as: supports3DS For more details about merchant capability, please refer to this reference from Apple merchantCapabilities |
Apple pay Mobile SDK
check point | Integration and Definition |
---|---|
Detect Customer Email Address and IP | Detect the customer Actual email address and pass it to customer_email parameter Detect the public IP address for the customer who’s browsing your website/application and pass it to customer_ip parameter in the Payment Operation request Sending static value to customer_email or customer ip parameter will cause the transaction to be blocked by our fraud detection tool in production environment |
Accept responses returned as POST FORMs | The return_url submitted in the API Request accepts the response returned as POST FORM since in the production environment you will have only POST Method option to receive the responses. In addition, the value passed to return_url parameter in the API Request should be https |
Request and Response Signature Calculations and validations | 1- While calculating the request signature, make sure to exclude the empty parameters (without values) from the signature calculations to avoid mismatch, this is applicable for all API requests submitted to APS 2-For the response signature, You need to validate the signature you receive from Amazon Payment Services by calculating the signature for the response parameters you receive on the return_url once the transaction is processed using the SHA response phrase listed in your test account under: Integration settings >> Security settings, the value of the calculated signature should match the value of the signature returned from Amazon Payment Services 3- Please make sure that you are handling the response as it is returned from APS without trimming any trailing spaces so you can be able to validate response signature correctly 4- Identify your request and response SHA phrases and make sure to do the signature calculations from your back-end only |
Transaction Feedback Implementation | Your code handles the response parameters received on Check Status API or Direct Transaction Feedback for payment instant responses and Notification Feedback URL for the recovery responses under Technical Settings, In this step, you need to create an endpoint to receive response parameters as a POST Method. To configure these URLs, please go to your Technical Settings Tab in your Amazon Payment services account and click on the activated channel you have, then configure the URL under Direct Feedback and Notification Feedback URLs. - Kindly avoid configuring any invalid URLs such as (apple.com, google.com, and example.com) in your accounts (test/production).If you are planning to use our accounts only for Invoicing/Subscription/E-terminal solutions, and you don’t have any active connection and integration between your website and Amazon Payment Services account, please use your domain URL / Terms & conditions URL for all the fields listed in your technical settings tab.) |
Amount Validation | Remember to validate the actual amount deducted from the customer, as it should matches the same amount you submit in the API requests to Amazon Payment services This is required to protect your website from any fraud |
Supported Payment methods | Make sure that you have chosen mada and Amex as one of the supported payment network in your Apple Pay integration For more details about the supported Payment Networks you can add in your current Integration, please refer to the reference from Apple Supported Networks |
MADA considerations | Set country code as SA for mada payments on Apple pay, here is the URL for your reference: Country Codes |
Different Inbound Server IP in Sandbox and Production | Remember to not use the same Inbound server IP you are currently using in Sandbox environment to submit the API Requests in the Production environment while submitting API requests for real payments to avoid impacting both environments |
Applepay capability | Set the merchant capability in your apple pay SDK integration as: capability3DS For more details about merchant capability, please refer to this reference from Apple merchantCapabilities |
The SDK_TOKEN generation | You need to handle the SDK_TOKEN generation from your server side not from the application, since this API request contains your security settings values which shouldn’t pass your application, that’s why we shift the signature calculations to the back-end not to be in the mobile application for any reverse engineering may occur. |
You are using the latest SDK version | Check Amazon Payment Services repositories on github to get the latest Mobile SDK version Amazon Payment Services |
Verify MOTO And Recurring Integration
check point | Integration and Definition |
---|---|
Detect Customer Email Address and IP | Detect the customer Actual email address and pass it to customer_email parameter Detect the public IP address for the customer who’s browsing your website/application and pass it to customer_ip parameter in the Payment Operation request Sending static value to customer_email or customer ip parameter will cause the transaction to be blocked by our fraud detection tool in production environment |
Amount Validation | Remember to validate the actual amount deducted from the customer, as it should matches the same amount you submit in the API requests to Amazon Payment services This is required to protect your website from any fraud |
Request and Response Signature Calculations and validations | 1- While calculating the request signature, make sure to exclude the empty parameters (without values) from the signature calculations to avoid mismatch, this is applicable for all API requests submitted to APS 2-For the response signature, You need to validate the signature you receive from Amazon Payment Services by calculating the signature for the response parameters you receive on the return_url once the transaction is processed using the SHA response phrase listed in your test account under: Integration settings >> Security settings, the value of the calculated signature should match the value of the signature returned from Amazon Payment Services 3- Please make sure that you are handling the response as it is returned from APS without trimming any trailing spaces so you can be able to validate response signature correctly 4- Identify your request and response SHA phrases and make sure to do the signature calculations from your back-end only |
Transaction Feedback Implementation | Your code handles the response parameters received on Check Status API or Direct Transaction Feedback for payment instant responses and Notification Feedback URL for the recovery responses under Technical Settings, In this step, you need to create an endpoint to receive response parameters as a POST Method. To configure these URLs, please go to your Technical Settings Tab in your Amazon Payment services account and click on the activated channel you have, then configure the URL under Direct Feedback and Notification Feedback URLs. - Kindly avoid configuring any invalid URLs such as (apple.com, google.com, example.com …etc) in your accounts (test/production).If you are planning to use our accounts only for Invoicing/Subscription/E-terminal solutions, and you don’t have any active connection and integration between your website and Amazon Payment Services account, please use your domain URL / Terms & conditions URL for all the fields listed in your technical settings tab.) |
Different Inbound Server IP in Sandbox and Production | Remember to not use the same Inbound server IP you are currently using in Sandbox environment to submit the API Requests in the Production environment while submitting API requests for real payments to avoid impacting both environments |
Frequently Asked Questions (FAQs)
Read the frequently asked questions about your integration.
- The Merchant identifier value which you submitted in the API Requests or configured in your plugin is not the same as that in your “Security Settings” on the FORT account.
- The transaction request for a live transaction is sent to the test environment or vice versa. You need to ensure you are using the correct endpoints for each environment as follows:
- The certificate not uploaded in your Amazon Payment Services account under Apple Pay Settings Tab.
- You are encrypting Apple data using a different Payment Processing certificate) that is already uploaded in your Amazon Payment Services account.
- Check if SDK_TOKEN you generated using the correct account you are processing the payment from.
- Check if you are generating a new SDK_TOKEN for each payment. This is mandatory.
- Check if you are using your proper security settings values in your account.
- Check if the environment endpoint is correct as mentioned in our guide.
- Check if you are submitting proper device_id, you can generate this parameter using the method mentioned in our SDK guide.
- Make sure that your merchant identifier certificate is correctly created.
- Verify that the openssl command used to generate the certificate is executed accurately and exclusively on a Mac device.
The error “Invalid Merchant Identifier” occurs in the following cases:
Sandbox URLs:
1.Tokenization Request:
https://sbcheckout.payfort.com/FortAPI/paymentPage
2.Payment Request:
https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Production URLs:1.Tokenization Request:
https://checkout.PayFort.com/FortAPI/paymentPage
2.Payment Request:
https://paymentservices.payfort.com/FortAPI/paymentApi
You need to ensure that the access code value configured in your account under Security Settings is the same value you submit in the API request or configure in your plugin settings.
Your source IP or URL that your requests come from doesn’t match the Origin IP or/and URL which is configured in your account under Securtiy Settings. To solve this error, you should configure same origin IPs and URLs for your requests under the Security Settings tab, or keep these configurations empty under the same tab.
You need to make sure that the channel you are integrating is added and configured in your account under Technical Settings Tab. Know more about Technical Settings configurations here .
The response will be received as POST Method.
Our calculated signature doesn’t match your signature value received in the request , you need to check the calculations rules in this link . We have simulators in the same reference where you can get the signature calcualtions in steps.
The Tokenization service is supported through all channels. If the customer processes the first payment successfully, you will receive a token_name in the response to be used in the next checkouts. For more details, you can refer to safe service section in this guide .
You can integrate this option easily in any integrated channel by adding few extra parameters related to the installments in the payload, for more details you can refer to this guide for all supported channels.
The Invoicing Service is supported through the Redirection channel. You can generate the invoices “manually from your account under the “Invoicing Management” tab or automatically through the APIs”. For more details about the Invoicing Service implementation you can refer to this guide.
APS Payment page for Credit Card is fully customizable, you can upload the template (CSS/ HTML)to change the look and feel or add your own content, then upload the templates in your account under Payment Page template tab. To inject your changes on our page, please make sure to add $$PZ$$ in the template body. For more details you can refer to this guide.
Standard merchant page allows the merchant to use APS payment form and add it in an iframe as light-box or embedded form in your checkout page, this form is fully customizable through the CSS to match the look and feel of your checkout page. The Custom merchant page allows to develop your own payment form, where you have full control on form development, and then the card details should be submitted directly to APS.
Yes it’s mandatory for fraud rules checks.
The TLS version should be 1.2 and above.
Yes it’s required. Try it yourself here.
The Merchant Page form is fully customizable through the CSS , your can extract our CSS classes, then uplaod your changes in a CSS file in your account under Payment Page Template tab. To get our classes you can refer to this link.
The device_fingerprint is a unique deviceID generated in the merchant checkout page by running a script that contains the customer’s computing device information for the purpose of identification. It’s required to run the Advanced Fraud Rules. To get the script you should run, you can refer to this guide.
You should redirect the customers to the 3ds_url received to get the final response of the payment. You need to display the 3ds_url as it’s received from our end in a main window without escaping any character.
The token_name which you sent in the Merchant Page Operations is expired, for some cases, the token might not be saved permanently to perform payments such as: MOTO/Recurring or saved card functionlity.
In the hosted installments, you have full control to display the installments details, you can check out this guide to get the details and submit the API requests.
The Purchase command means to authorize and capture the transaction amount automatically in one single request; accordingly, the amount will be deducted from the customer’s card and can’t be voided while it can be refunded. The Authorization command means to hold an amount from the customer’s credit card account for a period of time will be specified from the bank side until the Merchants capture or void the transaction. For more details you can refer to this link.
No, it’s not allowed, the Merchant is able to VOID the full amount only.
In this case you are trying to capture a transaction already captured, you should make sure that the captured operation are not applied on the amount that captured previously. Or you are trying to capture an amount value which is greater than the authorized amount submitted in the Authorization request.
In this case, you are trying to refund an amount that is greater than the captured amount. The amount parameter which is submitted in the Refund amount should be equal or less than the captured amount.
Yes , it’s allowed under Order Transaction Management Tab ,for more details you can refer to this link..
You can receive the response on the Direct Feedback endpoint which can be configured in your Account under Technical Settings Tab, the response will be received as a POST method to the configured endpoint. For more details you can refer to this link. Or you can use the check status API to pull the final response, you can refer to check status guide here.
It should be submitted as a REST POST using the JSON format from the back-end . For more details about SDK API request, you can refer to this guide. Its the same process for IOS/Android.
We have a feature called “Direct Pay” that allows you to securely process e-commerce transactions using tokenized payment card details. To implement this feature you can refer to this guide.
You need to make sure that the environment which you are using to submit the SDK_TOKEN generation request matches the environment set in the SDK . The SDK_TOKEN parameter value submitted in the SDK Operations should be a newly generated one if no one generated a token from the same device.
API request contains your security settings values which you shouldn’t pass on to your application. We have shifted the signature calculations to the back-end and to not be in the mobile application for reverse engineering issues.
You can check this guide to know the response codes and messages that Amazon Payment Services returns after the payments.
The issue is related to your (Payment Processing certificate),it can occur in the following scenarios:
you can use the testing card details mentioned in this link.
The correct value for the parameter paymentDataType depends on your integration with apple pay if its for non China requests the value should be 3DSecure.
In web it should be “Support3ds” and in app “Capability3DS”.
You should check the amount which is sent in the PURCHASE Operations request, it should match at the least the minimum amount for the plan selected by the customer.
Installments support the PURCHASE command only.
No, Installments is supported only through the Credit Cards.
You can contact merchantsupport-ps@amazon.com, in order to activate the Hosted Installments option in your Account.
No, it’s not customizable , you can only add a logo to be displayed in the installments page from your account under general information tab.
You will receive the response code as “20064” and the response_message is “3-D Secure check requested”.
The payment will be updated to “Dropped” and the response will be pushed to you in the Notification Feedback URL which can be configured in your Account under Technical Settings Tab, or you can use check status to get the final status.
The Token name will be generated from the first Ecommerce payment through one of Amazon Payment Services channels ( Redirection, Merchant Page,Trusted and Mobile SDK), you can save the permanent token returned and use the same in the MOTO / Recurring payments.
You should submit in the command parameter “PURCHASE” only ,while in MOTO option you can submit AUTHORIZATION and PURCHASE commands.
Recurring service allows you to charge customer’s card a specific amount on regular basis using tokens. For example, the Merchant will be charging a customer’s card a subscription fee on monthly basis, or weekly basis,etc. While in MOTO you need to charge the customers offline but not on a regular basis or in a specific time.
The Trusted integration type is allowed only for the merchants who are PCI certified , since it’s required to submit the clear card details in this API to the merchant’s back-end.
Yes, they are supported. You can send the eci parameter directly in the Trusted API request as MOTO or Recurring along with the card details.
Yes it’s required.
You can use this service if you wish to create a permanent token through the customer’s card without charging them any amount.
UPDATE TOKEN service allows you to update the customer’s card associated with a token and the status of a token via API calls. You can update the card information for the customer, activate or deactivate his card token.
In case you need to delete the customer’s card , you can use the UPDATE TOKEN API by sending the token_status parameter with INACTIVE value.
You can use the unique Token service. This Service allows you to receive a unique and one token for the same card filled by the customer, this service gives you a control to know if the customer is using/saving the same card or not.
You need to validate the card bin you received from Tokenization API response or detect customer’s bin in the payment page with the list of BINs you would like to apply discounts for then compare both values, if they match you can apply discount formula on the final amount and send the amount after discount in the payment request.
Direct Transaction Feedback will send Merchants HTTPs notifications that inform them of the transaction’s final status whenever a transaction is processed. While Notification Transaction Feedback, will send Merchants HTTPs notifications that inform them of the transaction’s final status whenever a transaction status is updated. For more details you can refer to this link.
You can refer to this link for mada branding guidelines.
You can refer to this link for AMEX branding guidelines.
The Trusted integration type is allowed only for merchants who are PCI certified. For Pre-requisite to use this channel, you can refer to this link.
You can customize both English and Arabic layouts as needed and add any static elements or redesign the view if needed, in that case, you must keep the elements used in the standard layout particularly if the element has an ID. The customized XML file should be added to the layout file in the target project (your Application) to override the default SDK file. You can refer to this link for customizing the standard payment UI, and this link for customizing the payment UI.
You can customize the payment UI presented by our React Native SDK in a number of ways to better reflect your business. For more details you can refer to this link.
For flutter SDK we support only “Standard checkout” option, the customization is not allowed.
You can follow the steps in this link.
You can use the testing cards for all card types listed in this link.
OTP expires in 15 minutes and the customer has 5 number of retries.
Yes, amount_per_month includes the interest rate.
You can submit only “OTP_GENERATE”API, its for: verifying customer,get installment plans and OTP generation.
We will accept any value you send in the request.
COF stands to “CardOnFile”. This option enables you to collect additional payment details related to your customer’s subscription and store them through APS to process subsequent payments. For more details you can refer to this link.
Scheduled recurring means that the customer pays fixed or variable amount through specific subscription period already pre-defined by the merchant. While the Unscheduled means that the merchant deducts amounts for recurring payment whenever required. This mode does not require a fixed time range or a fixed amount for payments. For more examples and details you can refer to this link.
You can refer to this link for required parameters and usage for each.
You can use the testing card details provided in this link, and have to create a Sandbox tester account on your Apple Developer portal and sign in with it as Apple ID
This error usually relates to your Payment Processing certificate. It can occur if the certificate isn’t uploaded in your Amazon Payment Services account under Apple Pay Settings or if you’re encrypting Apple data with a different certificate that’s already uploaded.
The appropriate value for paymentDataType depends on your Apple Pay integration. For non-China requests, the value should be 3DSecure.
For web, it should be “Support3ds,” and for app, it’s “Capability3DS.”
This might be due to an unsupported browser or device. Apple Pay primarily works on Apple devices, and using an outdated version of Safari or non-Apple devices could lead to this issue. Make sure you’re using a compatible device and an up-to-date Safari browser.
Also, Apple Pay availability varies by country. If it’s not supported in your region, the button might not appear.
This error indicates that the Apple Pay session expired before the transaction completes. Sessions have time limits, and if users take too long, the session may expire.
This is due to testing environment limitations. Not all cards or issuers are supported in the Apple Pay sandbox environment. Make sure that you’re using a supported test card.
If you implemented APS API call inside the paymentauthorized callback event of Apple Pay javascript, and if API fails, they might see the Payment Not Complete message after the customer authorizes the transaction with TouchID, FaceID or PassCode
To fix this error: