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/json
orapplication/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:
- 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