This package provides an API for the MaxMind minFraud web services. This includes minFraud Score, Insights, and Factors. It also includes our minFraud Report Transaction API.
The legacy minFraud Standard and Premium services are not supported by this API.
This library works with .NET Framework version 4.6.1 and above and .NET Standard 2.0 or above.
This library depends on GeoIP2 and its dependencies.
We recommend installing this library with NuGet. To do this, type the following into the Visual Studio Package Manager Console:
install-package MaxMind.MinFraud
This API uses the async/await feature introduced in .NET 4.5 to provide non-blocking calls to the minFraud web services.
To use this API, first create a new WebServiceClient object. The constructor
takes your MaxMind account ID and license key:
var client = new WebServiceClient(10, "LICENSEKEY");To use the Sandbox web service instead of the production web service, you can provide the host argument:
var client = new WebServiceClient(
accountId: 10,
licenseKey: "LICENSEKEY",
host: "sandbox.maxmind.com"
);You may also specify the fall-back locales, the host, or the timeout as optional parameters. See the API docs for more information.
This object is safe to share across threads. If you are making multiple requests, the object should be reused to so that new connections are not created for each request. Once you have finished making requests, you should dispose of the object to ensure the connections are closed and any resources are promptly returned to the system.
Create a new Transaction object. This represents the transaction that you
are sending to minFraud:
var transaction = new Transaction(
device: new Device(
ipAddress: System.Net.IPAddress.Parse("152.216.7.110"),
userAgent: "Mozilla/5.0 (X11; Linux x86_64)",
acceptLanguage: "en-US,en;q=0.8"
),
account:
new Account(
userId: "3132",
username: "fred"
)
);After creating the request object, send a non-blocking minFraud Score request
by calling the ScoreAsync method using the await keyword from a method
marked as async:
var score = await client.ScoreAsync(transaction);A minFraud Insights request by calling the InsightsAsync method:
var insights = await client.InsightsAsync(transaction);Or a minFraud Factors request by calling the FactorsAsync method:
var factors = await client.FactorsAsync(transaction);If the request succeeds, a model object will be returned for the endpoint. If the request fails, an exception will be thrown.
See the API documentation for more details.
To use the web service API with HttpClient factory pattern as a Typed client you need to do the following:
- Add the following lines to
Startup.csConfigureServicesmethod:
// Configure to read configuration options from MinFraud section
services.Configure<WebServiceClientOptions>(Configuration.GetSection("MinFraud"));
// Configure dependency injection for WebServiceClient
services.AddHttpClient<WebServiceClient>();- Add configuration in your
appsettings.jsonwith your account ID and license key.
...
"MinFraud": {
"AccountId": 10,
"LicenseKey": "LICENSEKEY",
"Timeout": TimeSpan.FromSeconds(5), // optional
"Host": "minfraud.maxmind.com" // optional
},
...- Inject the
WebServiceClientwhere you need to make the call and use it.
[ApiController]
[Route("[controller]")]
public class MinFraudController : ControllerBase
{
private readonly WebServiceClient _minfraudClient;
public MaxMindController(WebServiceClient minfraudClient)
{
_minfraudClient = minfraudClient;
}
[HttpGet]
public async Task<double?> RiskScore(Transaction transaction)
{
var score = await _minfraudClient.ScoreAsync(transaction);
return score.RiskScore;
}
}If a transaction was scored incorrectly or you received a chargeback, you may
report it to MaxMind. To do this, create a new TransactionReport object:
var report = new TransactionReport(
ipAddress: IPAddress.Parse("104.16.148.244"),
tag: TransactionReportTag.Chargeback,
chargebackCode: "BL",
maxmindId: "abcd1234",
minfraudId: new Guid("01c25cb0-f067-4e02-8ed0-a094c580f5e4"),
notes: "Suspicious account behavior",
transactionId: "txn123");A valid tag and at least one of the following are required parameters:
ipAddress, maxmindId, minfraudId, transactionId.
Send the report by calling the ReportAsync method using the await keyword:
await client.ReportAsync(report);The endpoint does not return any data and the method does not return a value. If there is an error, an exception will be thrown.
Thrown by the request models:
ArgumentException- Thrown when invalid data is passed to the model constructor.
Thrown by WebServiceClient method calls:
AuthenticationException- Thrown when the server is unable to authenticate the request, e.g., if the license key or account ID is invalid.InsufficientFundsException- Thrown when your account is out of funds.PermissionRequireException- Thrown when your account does not have permission to access the service.InvalidRequestException- Thrown when the server rejects the request for another reason such as invalid JSON in the POST.MinFraudException- Thrown when the server returns an unexpected response. This also serves as the base class for the above exceptions.HttpException- Thrown when an unexpected HTTP error occurs such as an internal server error or other unexpected status code.
using MaxMind.MinFraud;
using MaxMind.MinFraud.Request;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
public class MinFraudExample
{
static void Main()
{
MinFraudAsync().Wait();
}
static public async Task MinFraudAsync()
{
var transaction = new Transaction
{
Device = new Device
{
IPAddress = IPAddress.Parse("152.216.7.110"),
UserAgent = "Mozilla/5.0 (X11; Linux x86_64)",
AcceptLanguage = "en-US,en;q=0.8",
SessionAge = 3600.5,
SessionId = "a333a4e127f880d8820e56a66f40717c"
},
Event = new Event
{
TransactionId = "txn3134133",
ShopId = "s2123",
Time = new DateTimeOffset(2014, 4, 12, 23, 20, 50, 52, new TimeSpan(0)),
Type = EventType.Purchase
},
Account = new Account
{
UserId = "3132",
Username = "fred"
},
Email = new Email
{
Address = "[email protected]",
Domain = "maxmind.com",
HashAddress = false
},
Billing = new Billing
{
FirstName = "First",
LastName = "Last",
Company = "Company",
Address = "101 Address Rd.",
Address2 = "Unit 5",
City = "City of Thorns",
Region = "CT",
Country = "US",
Postal = "06510",
PhoneNumber = "123-456-7890",
PhoneCountryCode = "1"
},
Shipping = new Shipping
{
FirstName = "ShipFirst",
LastName = "ShipLast",
Company = "ShipCo",
Address = "322 Ship Addr. Ln.",
Address2 = "St. 43",
City = "Nowhere",
Region = "OK",
Country = "US",
Postal = "73003",
PhoneNumber = "123-456-0000",
PhoneCountryCode = "1",
DeliverySpeed = ShippingDeliverySpeed.SameDay
},
Payment = new Payment
{
Processor = PaymentProcessor.Stripe,
WasAuthorized = false,
DeclineCode = "invalid number"
},
CreditCard = new CreditCard
{
IssuerIdNumber = "411111",
BankName = "Bank of No Hope",
BankPhoneCountryCode = "1",
BankPhoneNumber = "123-456-1234",
AvsResult = 'Y',
CvvResult = 'N',
Last4Digits = "7643",
Token = "123456abc1234",
Was3DSecureSuccessful = true
},
CustomInputs = new CustomInputs.Builder
{
{ "float_input", 12.1d},
{ "integer_input", 3123},
{ "string_input", "This is a string input."},
{ "boolean_input", true},
}.Build(),
Order = new Order
{
Amount = 323.21m,
Currency = "USD",
DiscountCode = "FIRST",
AffiliateId = "af12",
SubaffiliateId = "saf42",
ReferrerUri = new Uri("http://www.amazon.com/"),
IsGift = true,
HasGiftMessage = false
},
ShoppingCart = new List<ShoppingCartItem>
{
new ShoppingCartItem
{
Category = "pets",
ItemId = "ad23232",
Quantity = 2,
Price = 20.43m
},
new ShoppingCartItem
{
Category = "beauty",
ItemId = "bst112",
Quantity = 1,
Price = 100.00m
}
}
};
// If you are making multiple requests, a single WebServiceClient
// should be shared across requests to allow connection reuse. The
// class is thread safe.
//
// Replace "6" with your account ID and "ABCD567890" with your license
// key.
using (var client = new WebServiceClient(6, "ABCD567890"))
{
// Use `InsightsAsync` if querying Insights
var score = await client.ScoreAsync(transaction);
Console.WriteLine(score);
}
}
}Please report all issues with this code using the GitHub issue tracker.
If you are having an issue with the minFraud service that is not specific to the client API, please see our support page.
Patches and pull requests are encouraged. Please include unit tests whenever possible.
This API uses Semantic Versioning.
This software is Copyright (c) 2015-2024 by MaxMind, Inc.
This is free software, licensed under the Apache License, Version 2.0.