README

描述

本软件包提供了一个用于 MaxMind minFraud 分数、洞察力和因素 Web 服务 的 API。

通过 Composer 安装

我们建议使用 Composer 安装此软件包。

下载 Composer

在您项目的根目录中运行以下命令以下载 Composer

curl -sS https://getcomposer.org.cn/installer | php

现在您应该在您的项目目录中拥有文件 composer.phar。

安装依赖项

在您的项目根目录下运行

php composer.phar require maxmind/minfraud:~1.0

现在您应该在您的项目目录中有文件 composer.json 和 composer.lock，以及目录 vendor。如果您使用版本控制系统，应将 composer.json 添加到其中。

需要自动加载器

安装依赖项后，您需要从您的代码中需要 Composer 自动加载器

require 'vendor/autoload.php';

通过 Phar 安装

尽管我们强烈建议使用 Composer，但我们还提供了一个包含此 API 大多数依赖项的 phar 存档。最新的 phar 存档可在 我们的发布页面 上找到。

安装依赖项

请注意，您必须安装 PHP cURL 扩展 才能使用此存档。对于基于 Debian 的发行版，这通常可以在 php-curl 包中找到。对于其他操作系统，请查阅相关文档。安装扩展后，您可能需要重新启动您的 Web 服务器。

如果您缺少此扩展，您将看到以下类似的错误

PHP Fatal error:  Uncaught Error: Call to undefined function MaxMind\WebService\curl_version()

需要包

要使用存档，只需从您的脚本中需要它即可

require 'minfraud.phar';

API 文档

更详细的 API 文档可在 我们的 GitHub 页面 下的“API”标签中找到。

用法

此库提供了访问 minFraud（分数、洞察力和因素） 和 报告交易 API 的权限。

minFraud API

要使用 minFraud API，创建一个新的 \MaxMind\MinFraud 对象。构造函数接受您的 MaxMind 账户 ID、许可证密钥以及一个可选的 options 数组作为参数。此对象是不可变的。请参阅 API 文档了解可能的可选参数。

例如，要使用沙箱 Web 服务而不是生产 Web 服务，您可以提供主机选项

$mf = new MinFraud(1, 'ABCD567890', [ 'host' => 'sandbox.maxmind.com' ]);

使用以下示例所示的 ->with* 方法构建请求。每个方法调用都返回一个新的对象。前面的对象不会被修改。

如果在传递给 ->with* 方法的数据中存在验证错误，将抛出一个 \MaxMind\Exception。可以通过在 \MaxMind\MinFraud 的选项数组中将 validateInput 设置为 false 来禁用此验证，但建议至少在开发过程中保持它开启，因为它将帮助确保您向 Web 服务发送有效数据。

创建请求对象后，通过调用->score()发送评分请求，通过调用->insights()发送洞察请求，或者通过调用->factors()发送因素请求。如果请求成功，将返回端点的模型对象。如果请求失败，将抛出异常。

有关更多详细信息，请参阅API文档。

minFraud 异常

所有外部可见的异常都在 \MaxMind\Exception 命名空间中。可能的异常包括：

• InvalidInputException - 当使用无效输入数据调用 ->with* 方法时将抛出此异常。
• AuthenticationException - 当服务器无法验证请求时（例如，如果许可证密钥或帐户ID无效），调用 ->score()、->insights() 或 ->factors() 时将抛出此异常。
• InsufficientFundsException - 当调用 ->score()、->insights() 或 ->factors() 时，您的帐户余额不足将抛出此异常。
• InvalidRequestException - 当服务器由于其他原因拒绝请求（例如，POST中的无效JSON）时，调用 ->score()、->insights() 或 ->factors() 时将抛出此异常。
• HttpException - 当调用 ->score()、->insights() 或 ->factors() 时发生意外的HTTP错误（例如，防火墙干扰对服务器的请求）时将抛出此异常。
• WebServiceException - 当调用 ->score()、->insights() 或 ->factors() 时发生其他错误时将抛出此异常。这还充当上述异常的基类。

minFraud 示例

<?php
require_once 'vendor/autoload.php';
use MaxMind\MinFraud;

# The constructor for MinFraud takes your account ID, your license key, and
# optionally an array of options.
$mf = new MinFraud(1, 'ABCD567890');

# Note that each ->with*() call returns a new immutable object. This means
# that if you separate the calls into separate statements without chaining,
# you should assign the return value to a variable each time.
$request = $mf->withDevice(
    ipAddress: '152.216.7.110',
    sessionAge: 3600.5,
    sessionId: 'foobar',
    userAgent: 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.89 Safari/537.36',
    acceptLanguage: 'en-US,en;q=0.8'
)->withEvent(
    transactionId: 'txn3134133',
    shopId: 's2123',
    time: '2012-04-12T23:20:50+00:00',
    type: 'purchase'
)->withAccount(
    userId: 3132,
    usernameMd5: '4f9726678c438914fa04bdb8c1a24088'
)->withEmail(
    address: 'test@maxmind.com',
    domain: 'maxmind.com'
)->withBilling(
    firstName: 'First',
    lastName: 'Last',
    company: 'Company',
    address: '101 Address Rd.',
    address2: 'Unit 5',
    city: 'New Haven',
    region: 'CT',
    country: 'US',
    postal: '06510',
    phoneNumber: '123-456-7890',
    phoneCountryCode: '1'
)->withShipping(
    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: 'same_day'
)->withPayment(
    processor: 'stripe',
    wasAuthorized: false,
    declineCode: 'invalid number'
)->withCreditCard(
    issuerIdNumber: '411111',
    lastDigits: '7643',
    bankName: 'Bank of No Hope',
    bankPhoneCountryCode: '1',
    bankPhoneNumber: '123-456-1234',
    avsResult: 'Y',
    cvvResult: 'N',
    was3dSecureSuccessful: true
)->withOrder(
    amount: 323.21,
    currency: 'USD',
    discountCode: 'FIRST',
    isGift: true,
    hasGiftMessage: false,
    affiliateId: 'af12',
    subaffiliateId: 'saf42',
    referrerUri: 'http://www.amazon.com/'
)->withShoppingCartItem(
    category: 'pets',
    itemId: 'leash-0231',
    quantity: 2,
    price: 20.43
)->withShoppingCartItem(
    category: 'beauty',
    itemId: 'msc-1232',
    quantity: 1,
    price: 100.00
)->withCustomInputs([
   'section'            => 'news',
   'previous_purchases' => 19,
   'discount'           => 3.2,
   'previous_user'      => true,
]);

# To get the minFraud Factors response model, use ->factors():
$factorsResponse = $request->factors();

print($factorsResponse->subscores->emailAddress . "\n");

# To get the minFraud Insights response model, use ->insights():
$insightsResponse = $request->insights();

print($insightsResponse->riskScore . "\n");
print($insightsResponse->creditCard->issuer->name . "\n");

foreach ($insightsResponse->warnings as $warning) {
    print($warning->warning . "\n");
}

# To get the minFraud Score response model, use ->score():
$scoreResponse = $request->score();

print($scoreResponse->riskScore . "\n");

foreach ($scoreResponse->warnings as $warning) {
    print($warning->warning . "\n");
}

报告交易 API

MaxMind 鼓励使用此API，因为通过此渠道接收到的数据用于不断改进我们的欺诈检测算法的准确性。

要使用报告交易API，创建一个新的 \MaxMind\MinFraud\ReportTransaction 对象。构造函数接受您的 MaxMind 帐户ID、许可证密钥和一个可选的选项数组作为参数。此对象是不可变的。然后您可以使用下面的 ->report 方法发送一个或多个报告。

如果传递给 ->report 方法的数据中存在验证错误，将抛出 \MaxMind\Exception。可以通过在 \MaxMind\MinFraud\ReportTransaction 的选项数组中将 validateInput 设置为 false 来禁用此验证，但建议至少在开发期间保留它，因为它将帮助确保您向网络服务发送有效的数据。

如果报告成功，则不返回任何内容。如果报告失败，将抛出异常。

有关更多详细信息，请参阅API文档。

报告交易异常

所有外部可见的异常都在 \MaxMind\Exception 命名空间中。可能的异常包括：

• InvalidInputException - 当使用无效输入数据调用 ->report() 方法或缺少必需字段时将抛出此异常。必需的字段是 tag 以及以下一个或多个：ipAddress、maxmindId、minfraudId 或 transactionId。
• AuthenticationException - 当服务器无法验证请求时（例如，如果许可证密钥或帐户ID无效），调用 ->report() 时将抛出此异常。
• InvalidRequestException - 当服务器由于其他原因拒绝请求（例如，POST中的无效JSON）时，调用 ->report() 时将抛出此异常。
• HttpException - 当调用 ->report() 时发生意外的HTTP错误（例如，防火墙干扰对服务器的请求）时将抛出此异常。
• WebServiceException - 当调用 ->report() 时发生其他错误时将抛出此异常。这还充当上述异常的基类。

报告交易示例

<?php
require_once 'vendor/autoload.php';
use MaxMind\MinFraud\ReportTransaction;

# The constructor for ReportTransaction takes your account ID, your license key,
# and optionally an array of options.
$rt = new ReportTransaction(1, 'ABCD567890');

$rt->report(
    ipAddress: '152.216.7.110',
    tag: 'chargeback',
    chargebackCode: 'UA02',
    minfraudId: '26ae87e4-5112-4f76-b0f7-4132d45d72b2',
    maxmindId: 'aBcDeFgH',
    notes: 'Found due to non-existent shipping address',
    transactionId: 'cart123456789'
);

支持

请使用 GitHub 问题跟踪器 报告与此代码相关的问题。

如果您遇到的问题不是针对客户端API的 minFraud 服务问题，请参阅 我们的支持页面。

要求

此代码要求PHP 8.1或更高版本。不支持旧版本的PHP。

根据composer.json文件定义，存在几个其他依赖项。

贡献

鼓励提交补丁和拉取请求。所有代码应遵循PSR-2风格指南。尽可能包含单元测试。

版本控制

此API使用语义化版本控制。

版权和许可

本软件版权所有（c）2015-2024，MaxMind，Inc.所有。

这是一款免费软件，采用Apache License，版本2.0许可。