Protect Plus API
Copy page
Copy page as Markdown for LLMs
Open in ChatGPT
Ask questions about this page
Open in Claude
Ask questions about this page
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/jsonorapplication/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 StringMax: 4000RequiredUnique device ID generated by Script. Please refer to Fraud Native Mobile SDK Guide to generate device fingerprint. Example. 04003hQUMXGB0po… Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ % + ! Space | 
| customer_type StringMax: 1OptionalThis parameter is required if any customer detail is present. Example. B | 
| customer_id StringMax: 16OptionalThe Customer's ID/account number. Example. Au8vJ9HxLo Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| customer_first_name StringMax: 30OptionalThe Customer's first name. Example. Osama Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| customer_middle_initial StringMax: 1OptionalThe Customer's middle name's initial. Example. M Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| customer_last_name StringMax: 30OptionalThe Customer's last name. Example. Kamal Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| customer_date_birth StringMax: 10OptionalThe Customer's date of birth. Format: YYYY-MM-DDExample. 1977-10-03 Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| customer_phone StringMax: 19OptionalThe Customer's home phone number. Example. 00962797219966 | 
| customer_alt_phone StringMax: 19OptionalThe Customer's alternative phone. For the Telecommunications sector, send: MSISDN. Example. 00962797256645 | 
| customer_address1 StringMax: 30OptionalThe Customer/Billing address line 1. Example. Amman - Khalda Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| customer_address2 StringMax: 30OptionalThe Customer/Billing address line 2 (for extra details). Example. Al Sati St. Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| customer_apartment_no StringMax: 30OptionalThe Customer/Billing apartment number. Example. 12 Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| customer_city StringMax: 20OptionalThe Customer/Billing city. Example. Amman Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| customer_state StringMax: 10OptionalThe Customer/Billing state code. Example. Jordan | 
| customer_zip_code StringMax: 9OptionalThe Customer/Billing post/zip code. Example. 11183 Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| customer_country_code StringMax: 3OptionalThe Customer's country code; ISO 3-digit country code. Example. JOR | 
| ship_type StringMax: 1OptionalShipping details present flag. This parameter is not applicable for the Gaming sector. Example. S | 
| ship_first_name StringMax: 30OptionalShip to first name. This parameter is not applicable for the Gaming sector. Example. Rana Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| ship_middle_name StringMax: 1OptionalShip to middle initial. This parameter is not applicable for the Gaming sector. Example. A Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| ship_last_name StringMax: 30OptionalShip to last name. This parameter is not applicable for the Gaming sector. Example. Rashdan Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| ship_address1 StringMax: 30OptionalShip to address line 1. This parameter is not applicable for the Gaming sector. Example. Cairo - Egypt Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ , Space | 
| ship_address2 StringMax: 30OptionalShip to address line 2. This parameter is not applicable for the Gaming sector. Example. Garden City Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ , Space | 
| ship_apartment_no StringMax: 30OptionalShip to apartment number. This parameter is not applicable for the Gaming sector. Example. 22 Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| ship_address_city StringMax: 20OptionalShip to address city. This parameter is not applicable for the Gaming sector. Example. Dubai Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| ship_address_state StringMax: 3OptionalShip to address state. This parameter is not applicable for the Gaming sector. Example. UAE | 
| ship_zip_code StringMax: 9OptionalShip to post/zip code. This parameter is not applicable for the Gaming sector. Example. 11183 | 
| ship_country_code StringMax: 3OptionalShip to country code; ISO 3-Digit country code. This parameter is not applicable for the Gaming sector. Example. JOR | 
| ship_phone StringMax: 19OptionalShip to home phone number. This parameter is not applicable for the Gaming sector. Example. 0096265534256 | 
| ship_alt_phone StringMax: 12OptionalShip To alternative phone. This parameter is not applicable for the Gaming sector. Example. 0797334465 | 
| ship_email StringMax: 254OptionalShip to email address. For the Gaming sector, send: Player Email Address. Example. ship@gmail.com Special characters: @ - . _ Space | 
| ship_comments StringMax: 160OptionalAny shipping comments. For the Gaming sector, send: Player Email Address. Example. (Any shipping comments can be entered) Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| ship_method StringMax: 1OptionalThe 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 StringMax: 256OptionalIf 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 StringMax: 256OptionalIf 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 StringMax: 256OptionalIf the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the "Address Verification (PayPal)". Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| fraud_extra4 StringMax: 256OptionalIf the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the "Account Status (PayPal)". Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| fraud_extra5 StringMax: 256OptionalIf the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the "Eligibility Status (PayPal)". Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| fraud_extra6 StringMax: 256OptionalIf the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the "Outstanding Balance on the Account (PayPal)". Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| fraud_extra7 StringMax: 256OptionalIf the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the "Credit Score (PayPal)". Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| fraud_extra8 StringMax: 256OptionalIf the sector is Telecommunications, the value must be the "Account Number" (if multiple MSISDN per account). Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| fraud_extra9 StringMax: 265OptionalIf the sector is Telecommunications, the value must be the "MSISDN Age in days". Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| fraud_extra10 StringMax: 256OptionalIf 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 StringMax: 30OptionalIf the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the "Account Age". Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| fraud_extra12 StringMax: 30OptionalIf 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 StringMax: 30OptionalIf 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 StringMax: 30OptionalIf 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 StringMax: 30OptionalIf 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 StringMax: 30OptionalIf the sector is Retail, Gaming, Travel, or Telecommunications, the value must be the "Event/Promotion Flag". Special characters: @ - . _ ' / # \ : = ? & ; ( ) $ Space | 
| fraud_extra18 StringMax: 30OptionalIf 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 StringMax: 30OptionalIf 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 StringMax: 30OptionalIf 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 StringMax: 30OptionalIf 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 StringMax: 30OptionalIf 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 StringMax: 30OptionalIf 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 StringMax: 30OptionalIf 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 StringMax: 30OptionalIf 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 StringMax: 999OptionalThis 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:
- Retail Cart Example
- Gaming Cart Example
- Travel Cart Example
- Telecommunications Cart Example
"{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'}]}"
"{cart_items:[{item_quantity:1000,item_description:'2023-01-15', item_price:25000,item_sku:'GOLD_BALANCE',item_prod_code:'SILVER_BALANCE',item_part_no:'EXP_BALANCE'}]}"
"{cart_items:[{item_quantity:1,item_description:'Email Delivery', item_price:75000,item_sku:'FLIGHT_TICKET',item_prod_code:'ECONOMY',item_part_no:'EK521',item_shipping_no:'2023-12-25T14:30:00',item_shipping_comments:'DXB-LHR-JFK'}]}"
"{cart_items:[{item_quantity:1,item_description:'Monthly Plan', item_price:10000,item_sku:'MOBILE_PLAN',item_prod_code:'UNLIMITED',item_part_no:'PLAN001',item_gift_msg:'HIGH_RISK_FLAG'}]}"
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"
}
{
  "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