NAME

WebService::MinFraud::Client - Perl API for MaxMind's minFraud Score and Insights web services

VERSION

version 1.009000

SYNOPSIS

  use 5.010;

  use WebService::MinFraud::Client;

  # The Client object can be re-used across several requests.
  # Your MaxMind account_id and license_key are available at
  # https://www.maxmind.com/en/my_license_key
  my $client = WebService::MinFraud::Client->new(
      account_id  => 42,
      license_key => 'abcdef123456',
  );

  # Request HashRef must contain a 'device' key, with a value that is a
  # HashRef containing an 'ip_address' key with a valid IPv4 or IPv6 address.
  # All other keys/values are optional; see other modules in minFraud Perl API
  # distribution for details.

  my $request = { device => { ip_address => '24.24.24.24' } };

  # Use the 'score', 'insights', or 'factors' client methods, depending on
  # the minFraud web service you are using.

  my $score = $client->score( $request );
  say $score->risk_score;

  my $insights = $client->insights( $request );
  say $insights->shipping_address->is_high_risk;

  my $factors = $client->factors( $request );
  say $factors->subscores->ip_tenure;


  # Request HashRef must contain an 'ip_address' key containing  a valid
  # IPv4 or IPv6 address. All other keys/values are optional; see other modules
  # in minFraud Perl API distribution for details.

  $request = { ip_address => '24.24.24.24' };

  # Use the chargeback client method to submit an IP address back to Maxmind.
  # The chargeback api does not return any content from the server.

  my $chargeback = $client->chargeback( $request );
  if ($chargeback->isa('WebService::MinFraud::Model::Chargeback')) {
    say 'Successfully submitted chargeback';
  }

DESCRIPTION

This class provides a client API for the MaxMind minFraud Score, Insights Factors web services, and the Chargeback web service. The Insights service returns more data about a transaction than the Score service. See the API documentation for more details.

Each web service is represented by a different model class, and these model classes in turn contain multiple Record classes. The Record classes have attributes which contain data about the transaction or IP address.

If the web service does not return a particular piece of data for a transaction or IP address, the associated attribute is not populated.

The web service may not return any information for an entire record, in which case all of the attributes for that record class will be empty.

TRANSPORT SECURITY

Requests to the minFraud web service are made over an HTTPS connection.

USAGE

The basic API for this class is the same for all of the web services. First you create a web service object with your MaxMind account_id and license_key, then you call the method corresponding to the specific web service, passing it the transaction you want analyzed.

If the request succeeds, the method call will return a model class for the web service you called. This model in turn contains multiple record classes, each of which represents part of the data returned by the web service.

If the request fails, the client class throws an exception.

CONSTRUCTOR

This class has a single constructor method:

WebService::MinFraud::Client->new

This method creates a new client object. It accepts the following arguments:

• account_id

  Your MaxMind User ID. Go to https://www.maxmind.com/en/my_license_key to see your MaxMind User ID and license key.

  This argument is required.

• license_key

  Your MaxMind license key.

  This argument is required.

• locales

  This is an array reference where each value is a string indicating a locale. This argument will be passed on to record classes to use when their name methods are called.

  The order of the locales is significant. When a record class has multiple names (country, city, etc.), its name method will look at each element of this array reference and return the first locale for which it has a name.

  Note that the only locale which is always present in the minFraud data is en. If you do not include this locale, the name method may return undef even when the record in question has an English name.

  Currently, the valid list of locale codes is:

  • de - German

  • en - English

    English names may still include accented characters if that is the accepted spelling in English. In other words, English does not mean ASCII.

  • es - Spanish

  • fr - French

  • ja - Japanese

  • pt-BR - Brazilian Portuguese

  • ru - Russian

  • zh-CN - Simplified Chinese

  Passing any other locale code will result in an error.

  The default value for this argument is ['en'].

• host

  The hostname of the minFraud web service used when making requests. This defaults to minfraud.maxmind.com. In most cases, you do not need to set this explicitly.

• ua

  This argument allows you to set your own LWP::UserAgent object. This is useful if you have to override the default object (LWP::UserAgent->new()) to set http proxy parameters, for example.

  This attribute can be any object which supports agent and request methods:

  • request

    The request method will be called with an HTTP::Request object as its only argument. This method must return an HTTP::Response object.

  • agent

    The agent method will be called with a User-Agent string, constructed as described below.

REQUEST

The request methods are passed a HashRef as the only argument. See the "SYNOPSIS" and WebService::MinFraud::Example for detailed usage examples. Some important notes regarding values passed to the minFraud web service via the Perl API are described below.

device => ip_address or ip_address

This must be a valid IPv4 or IPv6 address in presentation format, i.e., dotted-quad notation or the IPv6 hexadecimal-colon notation.

REQUEST METHODS

All of the fraud service request methods require a device ip_address. See the API documentation for fraud services for details on all the values that can be part of the request. Portions of the request hash with undefined and empty string values are automatically removed from the request.

The chargeback request method requires an ip_address. See the API documentation for chargeback for details on all the values that can be part of the request.

score

This method calls the minFraud Score web service. It returns a WebService::MinFraud::Model::Score object.

insights

This method calls the minFraud Insights web service. It returns a WebService::MinFraud::Model::Insights object.

factors

This method calls the minFraud Factors web service. It returns a WebService::MinFraud::Model::Factors object.

chargeback

This method calls the minFraud Chargeback web service. It returns a WebService::MinFraud::Model::Chargeback object.

User-Agent HEADER

Requests by the minFraud Perl API will have a User-Agent header containing the package name and version of this module (or a subclass if you use one), the package name and version of the user agent object, and the version of Perl.

This header is set in order to help us support individual users, as well to determine support policies for dependencies and Perl itself.

EXCEPTIONS

For details on the possible errors returned by the web service itself, please refer to the API documentation.

Prior to making the request to the web service, the request HashRef is passed to WebService::MinFraud::Validator for checks. If the request fails validation an exception is thrown, containing a string describing all of the validation errors.

If the web service returns an explicit error document, this is thrown as a WebService::MinFraud::Error::WebService exception object. If some other sort of error occurs, this is thrown as a WebService::MinFraud::Error::HTTP object. The difference is that the web service error includes an error message and error code delivered by the web service. The latter is thrown when an unanticipated error occurs, such as the web service returning a 500 status or an invalid error document.

If the web service returns any status code besides 200, 4xx, or 5xx, this also becomes a WebService::MinFraud::Error::HTTP object.

Finally, if the web service returns a 200 but the body is invalid, the client throws a WebService::MinFraud::Error::Generic object.

All of these error classes have a message method and overload stringification to show that message. This means that if you don't explicitly catch errors they will ultimately be sent to STDERR with some sort of (hopefully) useful error message.

WHAT DATA IS RETURNED?

Please see the API documentation for details on what data each web service may return.

Every record class attribute has a corresponding predicate method so that you can check to see if the attribute is set.

  my $insights = $client->insights( $request );
  my $issuer   = $insights->issuer;
  # phone_number attribute, with has_phone_number predicate method
  if ( $issuer->has_phone_number ) {
      say "issuer phone number: " . $issuer->phone_number;
  }
  else {
      say "no phone number found for issuer";
  }

SUPPORT

Bugs may be submitted through https://github.com/maxmind/minfraud-api-perl/issues.

AUTHOR

Mateu Hunter <mhunter@maxmind.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 - 2018 by MaxMind, Inc.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm WebService::MinFraud

perl -MCPAN -e shell
install WebService::MinFraud