Skip to main content

Protect Plus API

Protect Plus is Amazon Payment Services' advanced fraud protection service that provides comprehensive real-time fraud detection and prevention capabilities using sophisticated machine learning algorithms and behavioral analysis.

API Endpoints

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

Request Format

  • Method: POST
  • Content-Type: application/json or application/x-www-form-urlencoded
  • Submission: Server-to-server HTTPS POST or HTML Form POST

The "fraud_extra" fields are custom fields as their values depend on the sector. Each sector has specific requirements for these fields.

Fraud-Specific Request Parameters

The following parameters are fraud-specific parameters that can be added alongside your standard Custom Integration parameters

Parameter
device_fingerprint   String Max: 4000 Required

Unique device ID generated by Script. Please refer to Fraud Native Mobile SDK Guide to generate device fingerprint.
Example. 04003hQUMXGB0po…
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ % + ! Space
customer_type   String Max: 1 Optional

This parameter is required if any customer detail is present.
Example. B
customer_id   String Max: 16 Optional

The Customer's ID/account number.
Example. Au8vJ9HxLo
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
customer_first_name   String Max: 30 Optional

The Customer's first name.
Example. Osama
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
customer_middle_initial   String Max: 1 Optional

The Customer's middle name's initial.
Example. M
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
customer_last_name   String Max: 30 Optional

The Customer's last name.
Example. Kamal
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
customer_date_birth   String Max: 10 Optional

The Customer's date of birth.
Format: YYYY-MM-DD
Example. 1977-10-03
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
customer_phone   String Max: 19 Optional

The Customer's home phone number.
Example. 00962797219966
customer_alt_phone   String Max: 19 Optional

The Customer's alternative phone. For the Telecommunications sector, send: MSISDN.
Example. 00962797256645
customer_address1   String Max: 30 Optional

The Customer/Billing address line 1.
Example. Amman - Khalda
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
customer_address2   String Max: 30 Optional

The Customer/Billing address line 2 (for extra details).
Example. Al Sati St.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
customer_apartment_no   String Max: 30 Optional

The Customer/Billing apartment number.
Example. 12
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
customer_city   String Max: 20 Optional

The Customer/Billing city.
Example. Amman
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
customer_state   String Max: 10 Optional

The Customer/Billing state code.
Example. Jordan
customer_zip_code   String Max: 9 Optional

The Customer/Billing post/zip code.
Example. 11183
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
customer_country_code   String Max: 3 Optional

The Customer's country code; ISO 3-digit country code.
Example. JOR
ship_type   String Max: 1 Optional

Shipping details present flag. This parameter is not applicable for the Gaming sector.
Example. S
ship_first_name   String Max: 30 Optional

Ship to first name. This parameter is not applicable for the Gaming sector.
Example. Rana
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
ship_middle_name   String Max: 1 Optional

Ship to middle initial. This parameter is not applicable for the Gaming sector.
Example. A
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
ship_last_name   String Max: 30 Optional

Ship to last name. This parameter is not applicable for the Gaming sector.
Example. Rashdan
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
ship_address1   String Max: 30 Optional

Ship to address line 1. This parameter is not applicable for the Gaming sector.
Example. Cairo - Egypt
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ , Space
ship_address2   String Max: 30 Optional

Ship to address line 2. This parameter is not applicable for the Gaming sector.
Example. Garden City
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ , Space
ship_apartment_no   String Max: 30 Optional

Ship to apartment number. This parameter is not applicable for the Gaming sector.
Example. 22
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
ship_address_city   String Max: 20 Optional

Ship to address city. This parameter is not applicable for the Gaming sector.
Example. Dubai
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
ship_address_state   String Max: 3 Optional

Ship to address state. This parameter is not applicable for the Gaming sector.
Example. UAE
ship_zip_code   String Max: 9 Optional

Ship to post/zip code. This parameter is not applicable for the Gaming sector.
Example. 11183
ship_country_code   String Max: 3 Optional

Ship to country code; ISO 3-Digit country code. This parameter is not applicable for the Gaming sector.
Example. JOR
ship_phone   String Max: 19 Optional

Ship to home phone number. This parameter is not applicable for the Gaming sector.
Example. 0096265534256
ship_alt_phone   String Max: 12 Optional

Ship To alternative phone. This parameter is not applicable for the Gaming sector.
Example. 0797334465
ship_email   String Max: 254 Optional

Ship to email address. For the Gaming sector, send: Player Email Address.
Example. ship@gmail.com
Special characters: @ - . _ Space
ship_comments   String Max: 160 Optional

Any shipping comments. For the Gaming sector, send: Player Email Address.
Example. (Any shipping comments can be entered)
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
ship_method   String Max: 1 Optional

The shipping method. This parameter is not applicable for the Gaming sector.
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   String Max: 256 Optional

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   String Max: 256 Optional

If the sector is Retail, Travel, or Telecommunications, the value of the field must be the "Concatenated Shipping Address". This parameter is not applicable for the Gaming sector.
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra3   String Max: 256 Optional

If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the "Address Verification (PayPal)".
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra4   String Max: 256 Optional

If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the "Account Status (PayPal)".
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra5   String Max: 256 Optional

If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the "Eligibility Status (PayPal)".
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra6   String Max: 256 Optional

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   String Max: 256 Optional

If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the "Credit Score (PayPal)".
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra8   String Max: 256 Optional

If the sector is Telecommunications, the value must be the "Account Number" (if multiple MSISDN per account).
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra9   String Max: 265 Optional

If the sector is Telecommunications, the value must be the "MSISDN Age in days".
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra10   String Max: 256 Optional

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   String Max: 30 Optional

If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the "Account Age".
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra12   String Max: 30 Optional

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   String Max: 30 Optional

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   String Max: 30 Optional

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   String Max: 30 Optional

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   String Max: 30 Optional

If the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the "Event/Promotion Flag".
Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space
fraud_extra18   String Max: 30 Optional

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   String Max: 30 Optional

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   String Max: 30 Optional

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   String Max: 30 Optional

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   String Max: 30 Optional

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   String Max: 30 Optional

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   String Max: 30 Optional

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   String Max: 30 Optional

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   String Max: 999 Optional

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: $

Multiply your transaction amount by the currency decimal code per ISO code 3 before sending the amount parameter. For currencies with three-decimal codes, round VISA transactions to zero in the final decimal place to avoid declined transactions. Example: For 500 AED (2 decimal places per ISO code 3), multiply by 100 to send 50000 in your request.

The device_fingerprint parameter is required for all Protect Plus transactions. Use the provided JavaScript library or mobile SDK to generate the device fingerprint.

Check signature calculation section to learn how to calculate the signature.

Response Parameters

When using Protect Plus, you will receive the standard Custom Integration response parameters. No additional fraud-specific parameters are returned in the response.

Cart Details Examples

The following are example values of the "cart_details" parameter for different sectors:

"{cart_items:[{item_quantity:1,item_description:'iPhone 14 Pro', item_price:50000,item_sku:'IPHONE14PRO',item_prod_code:'APPLE001',item_part_no:'A2894'},{item_quantity:2,item_description:'AirPods Pro', item_price:15000,item_sku:'AIRPODSPRO',item_prod_code:'APPLE002',item_part_no:'A2698'}]}"

Device Fingerprint Script

Device fingerprint 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.

Please don't edit the values in the script below.

You can download and use the enhanced device fingerprint script for better integration:

Download Link: device-fingerprint.js

Usage:

<!-- Include the downloadable script -->
<script type="text/javascript" src="/files/device-fingerprint.js"></script>

<!-- Ensure you have the input field -->
<input type="hidden" id="device_fingerprint" name="device_fingerprint" value="">

<script>
// Wait for device fingerprint to be ready
waitForDeviceFingerprint(function(fingerprint) {
if (fingerprint) {
console.log('Device fingerprint ready:', fingerprint);
// Proceed with payment processing
} else {
console.warn('Device fingerprint not available');
// Handle fallback scenario
}
}, 5000); // 5 second timeout
</script>

Response Codes

For a complete list of response codes and their descriptions, please refer to our Error Codes Documentation.

{
"command": "PURCHASE",
"access_code": "zx0IPmPy5jp1vAz8Kpg7",
"merchant_identifier": "CycHZxVj",
"merchant_reference": "PROTECT-PLUS-001",
"amount": 50000,
"currency": "AED",
"language": "en",
"customer_email": "customer@example.com",
"customer_ip": "192.168.1.100",
"card_number": "4005550000000001",
"expiry_date": "2505",
"card_security_code": "123",
"card_holder_name": "John Smith",
"eci": "ECOMMERCE",
"customer_type": "B",
"customer_id": "CUST123456",
"customer_first_name": "John",
"customer_last_name": "Smith",
"customer_phone": "00971501234567",
"customer_address1": "Dubai Marina",
"customer_city": "Dubai",
"customer_country_code": "ARE",
"customer_zip_code": "12345",
"ship_type": "S",
"ship_first_name": "John",
"ship_last_name": "Smith",
"ship_address1": "Dubai Marina",
"ship_address_city": "Dubai",
"ship_country_code": "ARE",
"ship_email": "customer@example.com",
"ship_method": "N",
"fraud_extra1": "Dubai Marina, Dubai, ARE, 12345",
"fraud_extra2": "Dubai Marina, Dubai, ARE, 12345",
"fraud_extra11": "365",
"fraud_extra12": "5",
"fraud_extra13": "30",
"fraud_extra14": "90",
"fraud_extra16": "3",
"fraud_extra17": "N",
"fraud_extra18": "WEB",
"fraud_extra19": "PRIVATE",
"fraud_extra20": "10",
"fraud_extra23": "WEB",
"cart_details": "{cart_items:[{item_quantity:1,item_description:'iPhone 14 Pro', item_price:50000,item_sku:'IPHONE14PRO'}]}",
"device_fingerprint": "04003hQUMXGB0po2NmM9AAABAAAAAAA...",
"signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
}
Sample Response
{
"command": "PURCHASE",
"access_code": "zx0IPmPy5jp1vAz8Kpg7",
"merchant_identifier": "CycHZxVj",
"merchant_reference": "PROTECT-PLUS-001",
"amount": "50000",
"currency": "AED",
"language": "en",
"customer_email": "customer@example.com",
"customer_ip": "192.168.1.100",
"eci": "ECOMMERCE",
"expiry_date": "2505",
"card_number": "400555******0001",
"card_holder_name": "John Smith",
"fort_id": "149295435400084008",
"payment_option": "VISA",
"authorization_code": "P1000000000000372136",
"response_message": "Success",
"response_code": "14000",
"status": "20",
"signature": "c63a266e5929c6c8b82c2d9f2c8ae5c2b1b6f8a9d7e4f3c2a1b0c9d8e7f6a5b4"
}

Testing The Integration

Sandbox Testing

Use the sandbox environment for development and testing:

  • Sandbox URL: https://sbpaymentservices.payfort.com/FortAPI/paymentApi
  • Test Cards: Use our comprehensive Testing Cards

Go-Live Process

When ready to move to production, follow our Go-Live checklist

Was this page helpful?

Thanks for your feedback!