Customizing Websites to use Fraud Management Filters

You can detect and manage Fraud Management Filter results using IPN and the PayPal API. All merchants using IPN or the PayPal API must ensure that their systems can handle transactions pended by Fraud Management Filters.

Using Fraud Management Filters With IPN

Fraud Management Filter actions are reported in IPN payment messages only when a filter causes the payment to be pended awaiting your review or a when you accept or deny a filter-pended payment. Filter actions are not reported when filters flag payments for review, allow payments to be accepted, or cause them to be denied.
When a payment occurs, an IPN message shows the transaction's payment status as Completed, regardless of whether a Fraud Management Filter was activated or not. There is no special notification for transactions that are flagged by a Fraud Management Filter. If a Fraud Management Filter is set to Deny, PayPal does not send an IPN message when the filter actually causes the payment to be denied.

When a transaction is pended, however, PayPal sends an IPN message containing one or more fraud_management_pending_filters_n variables, which identify the filters that caused the payment to be pended, where n=1 specifies the first filter, and so on. In addition, the payment_status variable is set to Pending. The following example shows an IPN message in which two filters cause the transaction to be pended:

txn_type = virtual_terminal
payment_date = 17:11:42 Jul 15, 2008 PDT
last_name =
receipt_id = 3075-7371-4622-1677
residence_country = US
pending_reason = address
item_name =
payment_gross = 3.33
mc_currency = USD
business = acqrte_1215804264_biz@gmail.com
payment_type = instant
verify_sign = APYUGJhXGkUmvFnZf4I5co6CedKKAowZjfT4T7GXWJMDnZ0uFLkcq.oH
payer_status = unverified
test_ipn = 1
fraud_management_pending_filters_1 = Maximum Transaction Amount
tax = 0.00
txn_id = 5XN64179EB804362B
fraud_management_pending_filters_2 = Unconfirmed Address
quantity = 1
first_name =
receiver_email = acqrte_1215804264_biz@gmail.com
payer_id = PUWAJRBB8NM74
receiver_id = 2RXLTRMGT3M2G
item_number =
payment_status = Pending
shipping = 0.00
mc_gross = 3.33
custom =
charset = windows-1252
notify_version = 2.4
Note: If the transaction is for an authorization or an order, the auth_status variable may also be set to Pending.

If a transaction has been pended, PayPal sends an IPN message when the payment has been accepted or denied. The following example shows an IPN message indicating that a pended transaction has been accepted:

txn_type = virtual_terminal
payment_date = 17:11:42 Jul 15, 2008 PDT
last_name =
receipt_id = 3075-7371-4622-1677
residence_country = US
item_name =
payment_gross = 3.33
mc_currency = USD
business = acqrte_1215804264_biz@gmail.com
payment_type = instant
verify_sign = AFcWxV21C7fd0v3bYYYRCpSSRl31AjcbYkD.VCCBmpD4lZq.yYTxBKkr
payer_status = unverified
test_ipn = 1
fraud_management_pending_filters_1 = Maximum Transaction Amount
tax = 0.00
txn_id = 5XN64179EB804362B
fraud_management_pending_filters_2 = Unconfirmed Address
quantity = 1
receiver_email = acqrte_1215804264_biz@gmail.com
first_name =
payer_id = PUWAJRBB8NM74
receiver_id = 2RXLTRMGT3M2G
item_number =
payment_status = Completed
payment_fee = 0.45
mc_fee = 0.45
shipping = 0.00
mc_gross = 3.33
custom =
charset = windows-1252
notify_version = 2.4

The following example shows an IPN message indicating that a pended transaction has been denied:

txn_type = virtual_terminal
payment_date = 17:09:40 Jul 15, 2008 PDT
last_name =
receipt_id = 0739-3836-3393-2098
residence_country = US
item_name =
payment_gross = 2.11
mc_currency = USD
business = acqrte_1215804264_biz@gmail.com
payment_type = instant
verify_sign = AFcWxV21C7fd0v3bYYYRCpSSRl31ASrKFBPwac7aQm47p8CMLrdParSt
payer_status = unverified
test_ipn = 1
fraud_management_pending_filters_1 = Maximum Transaction Amount
tax = 0.00
txn_id = 53R82724RM1848354
fraud_management_pending_filters_2 = Unconfirmed Address
quantity = 1
first_name =
receiver_email = acqrte_1215804264_biz@gmail.com
payer_id = PUWAJRBB8NM74
receiver_id = 2RXLTRMGT3M2G
item_number =
payment_status = Denied
shipping = 0.00
mc_gross = 2.11
custom =
charset = windows-1252
notify_version = 2.4

Fraud Management Filters API Prerequisites

If your website uses PayPal APIs and you want to use FMF, you must detect transactions that have been pended by Fraud Management Filters.

Important: To use Fraud Management Filters with the PayPal API, you must use version 52.0 or higher of the PayPal API.

To detect transactions that have been pended by Fraud Management Filters, you must ensure that your website meets the following criteria:

  • You must handle Pending in the pending status of a response as representing a successful payment.
  • You must handle the SuccessWithWarning acknowledgement status in the response to any of the following API operations that you use: BillUser DoDirectPayment DoExpressCheckoutPayment DoReferenceTransaction Any of these APIs could return a SuccessWithWarning status indicating that the transaction was pended.
    Important: You may lose payment transactions if you do not handle SuccessWithWarning acknowledgements.
  • You must capture and evaluate the return code associated with a SuccessWithWarning acknowledgement.
  • If you process authorizations or orders, you must be able to analyze the short message associated with a capture failure
    Because a payment cannot be captured until it is taken out of the pending state, a capture failure may occur because the transaction was pended or it may occur for some valid reason. You must be able to distinguish between different kinds of failures.
  • Your shipping process must not allow shipping before the payment has been accepted.
    If the payment status is Pending, you must ensure that you do not ship merchandise until you review the transaction. You can use the PayPal website or the ManagePendingTransactionStatus PayPal API operation to either accept or deny pending transactions.
    Note: Pending payments are held 30 days unless explicitly denied or accepted. After 30 days, a pending payment is automatically reversed.
  • If you use Direct Payment Recurring Billing (for PayPal Payments Pro merchants), your subscription creation process must handle a SuccessWithWarning acknowledgement and associated return codes. Specifically, it must handle the situation in which only the first payment is pended; payments thereafter will not be placed in pending.

If you cannot accept these prerequisites; for example, if your shipping process would require substantial rework, you can still use Fraud Management Filters to flag or deny riskier payments, which provides you with additional risk review options, without changing your site. In this case, do not set any Fraud Management Filters to Review.

NVP Example

For a pended transaction, the NVP response would contain PAYMENTSTATUS set to Pending and the response would also contain the following fields:

ACK=SuccessWithWarning
L_ERRORCODE0=11610
L_SHORTMESSAGE0=Payment%20Pending%20your%20review%20in%20Fraud
%20Management%20Filters
L_LONGMESSAGE0=
L_SEVERITYCODE0=Warning

SOAP Example

The SOAP response would contain PaymentStatus set to Pending and the response would also contain the following fields:

...
<ack>
<__value__>
<m__value>SuccessWithWarning</m__value>
</__value__>
</ack>
...
<errors>
<com.paypal.soap.api.ErrorType>
<shortMessage>Payment Pending your review in Fraud Management
Filters</shortMessage>
<longMessage></longMessage>
<errorCode>
<m__value>11610</m__value>
</errorCode>
<severityCode>
<__value__>
<m__value>Warning</m__value>
</__value__>
</severityCode>
<____hashCodeCalc>false</____hashCodeCalc>
</com.paypal.soap.api.ErrorType>
</errors>
...

Detecting Pending Transactions Using the PayPal API

You must detect an acknowledgment status of SuccessWithWarning and an error code of 11610 to identify a pending transaction. The payment status should be Pending.
The following simple example modifies the DoExpressCheckoutPayment.jsp sample in the NVP SDK to support Fraud Management Filters. It does not handle the possibility that more than one error code can be returned. The changes to the sample are noted:

...
String strNVPResponse = (String) caller.call( strNVPString);
NVPDecoder decoder = new NVPDecoder();
decoder.decode(strNVPResponse);
String strAck = decoder.get("ACK");
// BEGIN CHANGES FOR FRAUD MANAGEMENT FILTERS
String strErrorCode = decode.get("L_ERRORCODE0");
String strPaymentStatus = decode.get("PAYMENTSTATUS");
if (strAck.equals("SuccessWithWarning") && strPaymentStatus.equals("Pending") && strErrorCode.equals("11610"))
{
// [insert code to record this transaction as pending "Review"]
}
else  // END CHANGES
if(strAck !=null && !(strAck.equals("Success") || strAck.equals("SuccessWithWarning")))
{
session.setAttribute("response",decoder);
response.sendRedirect("APIError.jsp");
return;
}
...

Handling FMF Errors in Payment API Operations

When you use Fraud Management Filters programatically, you must check for errors reported by a filter in the response to the DoDirectPayment, DoExpressCheckoutPayment, DoReferenceTransaction, and BillUser API operations. If you enabled reporting of FMF details in the request to these API operations, the response identifies the filters that caused a transaction to be pended or denied when these actions occur.
To enable reporting of FMF filter information, set the ReturnFMFDetails flag to 1 (true) in your request to DoDirectPayment, DoExpressCheckoutPayment, DoReferenceTransaction, and BillUser. You must explicitly request FMF detail information or the response will not contain it.

Note: Fraud Management Filters operate whether or not you request FMF detail information.

Regardless of whether you return FMF detail information, you must check for errors. Specifically, you must check for acknowledgements of Success and SuccessWithWarning in the response; however, PayPal recommends that you check for all possible acknowledgement status values. You must check for errors codes 11610 and 11611, depending on the acknowledgement status:

  • If the acknowledgement status is SuccessWithWarning, check for error code 11610, which indicates that one or more filters caused the transaction to be pended, awaiting your review
  • If the acknowledgement status is not Success or SuccessWithWarning, check for error code 11611, which indicates that one or more filters caused the transaction to be denied

The following SOAP example shows typical error handling for Fraud Management Filters:

...
if (DPRes.Ack == AckCodeType.Success) // No error
{
// Run success code
// Let buyer know, mark the order as complete in database, etc.
}
else if (DPRes.Ack == AckCodeType.SuccessWithWarning) // May be pended
{
// Test for pended transaction
bool isFMFPended = false;
for (int z = 0; z < DPRes.Errors.Length; z++)
{
if (DPRes.Errors[z].ErrorCode == "11610")
{
isFMFPended = true; // Transaction was pended
}
}
if (isFMFPended == true)
{
// Keep information about filters causing transaction to be pended
if (DPRes.FMFDetails.PendingFilters != null)
{
for (int x = 0; x < DPRes.FMFDetails.PendingFilters.Length; x++)
{
// Useful information to be kept:
// DPRes.FMFDetails.PendingFilters[x].Description;
// DPRes.FMFDetails.PendingFilters[x].Id;
// DPRes.FMFDetails.PendingFilters[x].Name;
}
}
}
}
else if (DPRes.Ack == AckCodeType.Failure ||
DPRes.Ack == AckCodeType.FailureWithWarning) // Definite failure
{
// Test for denied transaction
bool isFMFDenied = false;
for (int z = 0; z < DPRes.Errors.Length; z++)
{
if (DPRes.Errors[z].ErrorCode == "11611")
{
isFMFDenied = true; // Denied by FMF
}
}
if (isFMFDenied == true)
{
// Keep information about filters causing transaction to be denied
if (DPRes.FMFDetails.DenyFilters != null)
{
for (int x = 0; x < DPRes.FMFDetails.DenyFilters.Length; x++)
{
// Useful information to be kept:
// DPRes.FMFDetails.DenyFilters[x].Description;
// DPRes.FMFDetails.DenyFilters[x].Id;
// DPRes.FMFDetails.DenyFilters[x].Name;
}
}
}
}
else
{
// Unexpected ACK type. Log response and inform the buyer that the
// transaction must be manually investigated.
}

Migration From Risk Controls

Unlike Risk Controls, Fraud Management Filters do not return risk-related error codes for the DoAuthorization and DoCapture API operations. If you have previously programmed checks for risk controls after these operations, you may need to change your business logic.
You must handle error codes related to FMF in the response of the DoDirectPayment, DoExpressCheckoutPayment, DoReferenceTransaction, and BillUser API operations. These error codes are different than error codes associated with Risk Controls.