Premium Fraud Management Tools

Server-Side Implementationanchor

availability

We always recommend using the latest versions of our SDKs. While older versions may support Premium Fraud Management Tools, in order to use all available features, you must use at least the version indicated below.

  • Java 3.10.0
  • .NET 5.4.0
  • Node 2.24.0
  • PHP 6.2.0
  • Python 4.3.0
  • Ruby 4.1.0

Using device dataanchor

Include the collected client device data via the top-level device_data parameter when creating a customer , payment method , or transaction.

Here's an example of passing device data with a transaction:

  1. Ruby
result = gateway.transaction.sale(
  :amount => "1000.00",
  :payment_method_nonce => nonce_from_the_client,
  :options => {
    :submit_for_settlement => true
  },
  :device_data => params[:device_data]
)

And here's an example of passing device data with a payment method creation (thus triggering a verification request):

  1. Ruby
result = gateway.payment_method.create(
  :customer_id => "131866",
  :payment_method_nonce => nonce_from_the_client,
  :options => {
    :verify_card => true
  },
  :device_data => params[:device_data]
)

When to pass device dataanchor

In general, we strongly recommend including device data on any event where:

  • a customer adds credit card data to your Vault
  • a customer initiates a transaction

We use both transactions and verification request data to ensure that you get the most comprehensive fraud protection possible. Our Premium Fraud Management Tools use device data to more accurately identify fraudulent requests.

This is especially important on verifications: verifying cards is the best way to stop fraudsters from getting into your Vault. Sending the verification with device data will ensure that preliminary fraud checks are being run in addition to normal AVS/CVV/risk threshold checks you may have enabled. This further augments the level of protection you have, helping to identify fraudulent patterns linked to a device sooner than if you only passed device data with transaction requests.

important

When you create PayPal transactions using our Vault flow, it's critical to include device data for a different reason - to reduce decline rates. See our PayPal guide for more details.

Skipping Premium Fraud Management Toolsanchor

If you do not want to perform Premium Fraud Management Tools checks on a specific transaction, pass Options.SkipAdvancedFraudChecking when creating the transaction via the API:

  1. Ruby
result = gateway.transaction.sale(
  :amount: "10.00",
  :payment_method_nonce => nonce_from_the_client,
  :options => {
    :skip_advanced_fraud_checking => true
  }
)

Additionally, you can choose to not perform Premium Fraud Management Tools checks on specific verifications by passing Options.SkipAdvancedFraudChecking in the following calls:

Payment Method: Create Payment Method: Update Customer: Create Customer: Update

Here is an example of how to use this option when creating a payment method:

  1. Ruby
result = gateway.payment_method.create(
  :customer_id => "12345",
  :payment_method_nonce => nonce_from_the_client,
  :options => {
    :skip_advanced_fraud_checking => true
  }
)

Custom fieldsanchor

Fraud Protection Advanced provides several fields that can be used to build conditional filters. However, you may have a specific set of fields pertaining to your business that you want to use in certain scenarios to mitigate fraud. Using Custom Fields, you can add such specific fields to the tool and then use them in building filter conditions.

Before you create any custom field in the tool, you must ensure the fields you want to use are passed as part of the payment transaction details. See our guide for steps to incorporate custom fields in your transaction API calls.

Response handlinganchor

We return the risk data on credit card verifications and on transactions with all compatible payment methods. The data includes the fraud service provider, the risk identifier, the device data captured flag, and the risk decision, which can provide further context on how a verification or transaction was scored by our Premium Fraud Management Tools. For users of Fraud Protection, the data will include the decision reasons. For users of Fraud Protection Advanced, the data will also include the risk score.

  1. Ruby
result.transaction.risk_data.fraud_service_provider
#=> "Kount"
result.transaction.risk_data.id
#=> "1SG23YHM4BT5"
result.transaction.risk_data.decision
#=> "Decline"
result.transaction.risk_data.device_data_captured
#=> true
result.transaction.risk_data.decision_reasons
#=> ["reason1", "reason2"]
result.transaction.risk_data.transaction_risk_score
#=> 42

The possible values of the risk decision are Not Evaluated, Approve, Review, and Decline.

See also


Next Page: Webhooks →