minFraud Score、minFraud Insights 以及 minFraud Factors API

如果您是 minFraud Legacy 客户,请参阅我们的文件 《 minFraud Score、minFraud Insights 与 minFraud Factors 的新特点》,了解变动概要。

发布说明

我们的发布说明记录了 minFraud 网络服务中的有关修改。

客户端 API

MaxMind API

如果您使用下表中列出的语言,我们强烈建议您使用官方支持库。无需与 REST API 界面直接互动。

语言或框架 包存储库 文档 版本控制
.NET (C#) NuGet GitHub Pages GitHub
Java Maven Central GitHub Pages GitHub
Perl metacpan metacpan GitHub
PHP Packagist GitHub Pages GitHub
Python PyPI Read the Docs GitHub

第三方 API

警告!MaxMind 为这些 API 提供支持,也并未审核其代码。 使用者请自行承担风险。
语言或框架 API 名称 包存储库 文档 版本控制
Ruby minfraud RubyGems.org RubyDoc.info GitHub

退单报告

如果您在使用我们的 minFraud 交易欺诈检测服务,我们建议您也同时使用 退单报告服务。通过对交易进行标记,您可以帮助我们显著提高为您检测到的欺诈数量。我们根据所标记的交易,为每位客户量身定制机器学习模型。我们还对许多标记交易进行人工审核,从而为每位提供反馈的客户进行识别定制和算法改善。

设备跟踪附加功能

您可以选择在自己的网站上加入部分 JavaScript,帮助我们识别您的客户所使用的设备,从而判断该设备是否曾用于以前的欺诈交易。 设备信息会作为考虑因素,计入 minFraud 服务所生成的分数。

每项服务的 URI

每项服务所使用的 URI 如下所示。所有 API 呼叫均应通过 HTTP POST 进行,并使用如下规定的请求格式。

请注意,minFraud 服务的免费试用版只能使用 minFraud Score 和 minFraud Insights 服务。

如需了解使用 minFraud Factors 服务的更多信息,请点击此处

服务 URI 内容 – 类型
Score https://minfraud.maxmind.com/minfraud/v2.0/score application/vnd.maxmind.com-minfraud-score+json; charset=UTF-8; version=2.0
Insights https://minfraud.maxmind.com/minfraud/v2.0/insights application/vnd.maxmind.com-minfraud-insights+json; charset=UTF-8; version=2.0
Factors https://minfraud.maxmind.com/minfraud/v2.0/factors application/vnd.maxmind.com-minfraud-factors+json; charset=UTF-8; version=2.0

minfraud.maxmind.com 主机名自动挑选地理位置离您最近的数据中心。有些情况下,该数据中心未必能向您提供最佳服务。您可以直接试用以下主机名,查看哪个对您来说性能最佳:

  • minfraud-us-east.maxmind.com(美国弗吉尼亚州)
  • minfraud-us-west.maxmind.com(美国加州圣何塞)
  • minfraud-eu-west.maxmind.com(英国伦敦)

请求头

Accept 请求头完全属于选填项。如果您确实要加入这个请求头,则必须接受以下规定中的一种:

  • application/json
  • application/vnd.maxmind.com-minfraud-score+json
  • application/vnd.maxmind.com-minfraud-score+json; charset=UTF-8; version=2.0

用适当的服务类型替代“score”。任何其他 MIME 类型的请求均将导致 415 Unsupported Media Type 错误。

如果您在自己的客户端代码中设定 Accept-Charset 请求头,则必须接受 UTF-8 字符集。如果不接受,您将得到 406 Not Acceptable 的响应,因为该数据只能通过 UTF-8 提供。

授权

必须使用 HTTP 授权头进行授权。用户名是您的 MaxMind 用户 ID。密码是您的 MaxMind 许可证密钥。您必须就我们的某项网络服务申请试用样本或进行订购,才能获得用户 ID 和许可证密钥。

我们使用 HTTP 基本验证。要求验证的 API 只能通过 HTTPS 获取。绝对不会以未加密方式传输凭证信息。如果您试图通过 HTTP 使用该服务,您将得到 403 Forbidden HTTP 响应。

请求体

目前,minFraud Score、minFraud Insights 和 minFraud Factors 使用同样的请求文件格式。请求由一个带有如下所示的一个或多个字段的 JSON 对象构成。顶层对象中的每个键均映射以下描述的某个对象或数组。以后可以再加入适用于对象及/或数组的字段。

必须输入的字段只有 device 对象中的 ip_address 字段。日后也可能免除这条规定。

除非另行限定更短长度,字符串字段不得多于 255 个有效 Unicode 字符;不得使用空字符和换行符。当然,很多字段还有限定长度的其他限制。例如,ip_address 字段不得长于 IPv6 地址最长的有效表示。除非必须与某个特定格式匹配,否则字符串可以为空。

必须用 JSON truefalse 的形式提供布尔字段。

除非另有具体规定,只要是符合字段要求的值,便不会被修改。除了各字段具体标明的例外情况外,如果所提供的值与我们所要求的类型不同,则也属于本条规定的例外情况。在这种情况下,如果可能,我们会将其转化为要求的类型。例如,如果您用数字格式提供了字符串,数字会被转为字符串;反之亦然。这一转化仅适用于数字与字符串之间。

整个请求体的长度限于 20000 个字节。超出这一限制的请求体会被拒绝。

请求示例

顶层请求字段(/

设备(/device

这一对象包含交易所用设备的信息。(必填

值类型 描述
ip_address 字符串 顾客在交易中所用设备的相关 IP 地址。IP 地址必须采用 IPv4 或 IPv6 表达形式,亦即点分四段表示法或 IPv6 十六进制 – 冒号表示法。(必填
user_agent 字符串(255) 交易中所用浏览器的 HTTP “User-Agent”页头。
accept_language 字符串(255) 交易中所用设备的 HTTP “Accept-Language”页头。
session_age 十进制 用户会话的创建与交易时间之间的秒数。注意:session_age 并不是当前访问的停留时间,而是从首次访问开始算起的时间。数值必须至少为 0,最多 253-1。
session_id 字符串(255) 一个对网站上的访问者会话进行独特识别的 ID。

事件(/event

这一对象包含与评分事件相关的概况信息。

值类型 描述
transaction_id 字符串(255) 您给该交易的内部 ID。我们可以利用该信息在记录中找到一笔具体交易,它也会显示在我们发给您的电邮警报和通知中。不要求特定格式。
shop_id 字符串(255) 您给该订单所来自的商店、联盟机构或商家的内部 ID。如果 minFraud 用户系转售方、支付提供方、网关及联盟网络,则必须使用。不要求特定格式。
time 字符串 事件发生的日期和时间。字符串必须采用 RFC 3339 日期 – 时间格式,例如“2012-04-12T23:20:50.52Z”。时间必须为过去 10 年之内。如果请求中未包含该字段,则将使用当前时间。
type 枚举

评分事件的类型。有效类型包括:

  • account_creation
  • account_login
  • email_change
  • password_reset
  • purchase
  • recurring_purchase
  • referral
  • survey

账户(/account

这一对象包含终端用户在发生事件的网站上的账户信息。

值类型 描述
user_id 字符串(255) 您系统中的终端用户所独有的用户 ID。如果您的系统允许账户更改登录名,则这一 ID 不应做为账户的登录名,而应该是一个无法更改的内部 ID。这 不是您的 MaxMind 用户 ID。不要求特定格式。
username_md5 字符串(32) MD5 哈希值是账户相关用户名或登录名的十六进制字符串。

电子邮件(/email

值类型 描述
address 字符串(255) 该字段必须是一个有效电邮地址或是交易中所用电邮的 MD5 函数。
domain 字符串(255) 交易中所用电邮地址的域名。

账单(/billing

值类型 描述
first_name 字符串(255) 账单信息中所提供的终端用户之名。
last_name 字符串(255) 账单信息中所提供的终端用户之姓。
company 字符串(255) 账单信息中所提供的终端用户公司。
address 字符串(255) 用户账单地址的第一行。
address_2 字符串(255) 用户账单地址的第二行。
city 字符串(255) 用户账单地址的城市。
region 字符串(4) 用户账单地址的 ISO 3166-2 分区代码
country 字符串(2) 用户账单地址的两位字符 ISO 3166-1 alpha-2 国家代码
postal 字符串(255) 用户账单地址的邮政编码。
phone_number 字符串(255) 用户账单地址的电话号码(不含国家区号)。标点符号将被去除。去除标点符号后,号码必须仅含数字。
phone_country_code 字符串(4) 用户账单地址相关电话号码的国家区号。如果您提供这一信息,则必须提供至少一位数字。

寄送(/shipping

值类型 描述
first_name 字符串(255) 寄送信息中所提供的终端用户之名。
last_name 字符串(255) 寄送信息中所提供的终端用户之姓。
company 字符串(255) 寄送信息中所提供的终端用户公司。
address 字符串(255) 用户寄送地址的第一行。
address_2 字符串(255) 用户寄送地址的第二行。
city 字符串(255) 用户寄送地址的城市。
region 字符串(4) 用户寄送地址的 ISO 3166-2 分区代码
country 字符串(2) 用户寄送地址的两位字符 ISO 3166-1 alpha-2 国家代码
postal 字符串(255) 用户寄送地址的邮政编码。
phone_number 字符串(255) 用户寄送地址的电话号码(不含国家区号)。标点符号将被去除。去除标点符号后,号码必须仅含数字。
phone_country_code 字符串(4) 用户寄送地址相关电话号码的国家区号。如果您提供这一信息,则必须提供至少一位数字。
delivery_speed 枚举

订单的交付速度。有效值包括:

  • same_day
  • overnight
  • expedited
  • standard

支付(/payment

值类型 描述
processor 枚举

交易所使用的支付处理商。有效值包括:

  • adyen
  • altapay
  • amazon_payments
  • american_express_payment_gateway
  • authorizenet
  • balanced
  • beanstream
  • bluepay
  • bluesnap
  • bpoint
  • braintree
  • ccnow
  • chase_paymentech
  • checkout_com
  • cielo
  • collector
  • commdoo
  • compropago
  • concept_payments
  • conekta
  • cuentadigital
  • curopayments
  • cybersource
  • dalpay
  • dibs
  • digital_river
  • ebs
  • ecomm365
  • elavon
  • emerchantpay
  • epay
  • eprocessing_network
  • eway
  • exact
  • first_data
  • global_payments
  • heartland
  • hipay
  • ingenico
  • internetsecure
  • intuit_quickbooks_payments
  • iugu
  • lemon_way
  • mastercard_payment_gateway
  • mercadopago
  • merchant_esolutions
  • mirjeh
  • mollie
  • moneris_solutions
  • nmi
  • oceanpayment
  • openpaymx
  • optimal_payments
  • orangepay
  • other
  • pacnet_services
  • payfast
  • paygate
  • paymentwall
  • payone
  • paypal
  • payplus
  • paystation
  • paytrace
  • paytrail
  • payture
  • payu
  • payulatam
  • payway
  • payza
  • pinpayments
  • princeton_payment_solutions
  • psigate
  • qiwi
  • quickpay
  • raberil
  • rede
  • redpagos
  • rewardspay
  • sagepay
  • securetrading
  • simplify_commerce
  • skrill
  • smartcoin
  • solidtrust_pay
  • sps_decidir
  • stripe
  • telerecargas
  • towah
  • transact_pro
  • usa_epay
  • vantiv
  • verepay
  • vericheck
  • vindicia
  • virtual_card_services
  • vme
  • vpos
  • wirecard
  • worldpay
如果本列表中没有您的支付处理商,请联系 support@maxmind.com
was_authorized 布尔 来自支付处理商的授权结果。如果交易尚未得到批准或拒绝,请勿包括这一字段。
decline_code 字符串(255) 由您的支付处理商提供的拒绝代码。如果交易未被拒绝,请勿包括这一字段。

信用卡(/credit_card

值类型 描述
issuer_id_number 字符串(6) 信用卡发放者的 ID 号码。这是信用卡卡号的前 6 位数字。用它来识别发卡银行。
last_4_digits 字符串(4) 信用卡卡号最后 4 位数字。
token 字符串(255) 对信用卡进行独特标识的令牌。令牌应该由非空格可打印 ASCII 字符组成。如果令牌全部为数字,则长度必须超过 19 个字符。令牌 不得 为主要账户号码(PAN)或其简单转换。如果你有一个看似但其实并非 PAN 的有效令牌,你可以用一个固定字符串给它做前缀,例如 token-
bank_name 字符串(255) 终端用户所提供的发卡银行名称。
bank_phone_country_code 字符串(4) 终端用户所提供的发卡银行电话号码的国家区号。如果您提供这一信息,则必须提供至少一位数字。
bank_phone_number 字符串(255) 终端用户所提供的发卡银行电话号码(不含国家区号)。标点符号将被去除。去除标点符号后,号码必须仅含数字。
avs_result 字符(1) 由您的信用卡处理商返回的地址验证系统(AVS)检查结果。minFraud 服务支持标准 AVS 代码。
cvv_result 字符(1) 支付处理商提供的信用卡验证值(CVV)代码

订单(/order

值类型 描述
amount 十进制 未计税款与折扣前的交易订单总额。数值必须至少为 0,最多 1e17 – 1。
currency 字符串(3) 交易所用货币的 ISO 4217 货币代码。
discount_code 字符串(255) 用于交易的折扣码。如果使用了多个折扣码,请用逗号分隔。
affiliate_id 字符串(255) 订单所来自的联盟机构的 ID。 不要求特定格式。
subaffiliate_id 字符串(255) 订单所来自的子联盟机构的 ID。不要求特定格式。
referrer_uri 字符串(1024) 该订单转介网站的 URI。需为绝对 URI,并具有 https:// 之类的 URI 结构。
is_gift 布尔 购买者是否将订单标为“礼品”。
has_gift_message 布尔 购买者是否包括礼品留言。

购物车(/shopping_cart

这是购物车货品对象的 数组。购物车应该由一个或多个货品对象的数组构成。

购物车货品
值类型 描述
category 字符串(255) 货品的类型。
item_id 字符串(255) 您给该货品的内部 ID。不要求特定格式。
quantity 整数 购物车中货品的数量。数值必须至少为 0,最多 253-1,而且没有小数部分。
price 十进制 购物车中货品的单价。该项使用的货币应该与订单货币相同。数值必须至少为 0,最多 1e17 – 1。

自定义输入(/custom_inputs

自定义输入是 minFraud 服务的选填输入项,必须先针对您的账户进行设置。要进行设置,请在账户门户选择“自定义输入”。如果需要更多信息,请参阅我们的自定义输入文档

值类型
您的自定义布尔输入键 布尔
您的自定义数字输入键 在 -253 和 253 之间的浮点数
您的自定义电话号码输入键 电话号码,限于 255 个字符。数字、空格与标点均可输入,不过空格和标点将被去除。可接受标点包括下列 ASCII 字符:` ~ ! @ # $ % ^ & * ( ) – _ = + ' " ; : , < . > / ? | [ ] { 以及 }。
您的自定义字符串输入键 字符串,限于 255 个字符。不允许空字符。

响应头

针对上文所列各项服务的成功响应有不同的Content-Type 头。

也可能随 Content-Type 返回错误信息,设定为 application/vnd.maxmind.com-error+json; charset=UTF-8; version=2.0。如果是这种情况,响应体中将包含带有 codeerror 两个键的 JSON 文档。如需更多信息,请参阅 错误部分

响应中也总会含有一个 Content-Length 头。

响应体

所有服务均以 JSON 文档返回数据。所返回的文档均由一个对象(亦即映像或哈希)构成。

返回文档中不会包括带有未定义值或空值的键。

文档中返回的数据将采用 UTF-8 编码。

请注意,如果无法包括与某个特定键及值相关的任何信息,响应体可能会将其略。例如,如果你没有在请求中传送关于信用卡的任何信息,则响应中不会包括 credit_card 键或值。

顶层字段(/

包括在……
值类型 描述 Score? Insights? Factors?
id 字符串(UUID) 这是 minFraud ID,亦即用来识别 minFraud 响应的 UUID。 用该 ID 来 搜索您的 minFraud 记录 或向 MaxMind 提出支持请求。
risk_score 十进制 该字段包括风险分数,数值从 0.01 到 99。较高的分数意味着较高的欺诈风险。例如,分数为 20 意味着交易属于欺诈的概率为 20%。我们从不返回“0”值的风险分数,因为所有交易都有属于欺诈的可能性。同样道理,我们从不返回“100”的风险分数。
funds_remaining 十进制 您的 MaxMind 账户中剩余资金的大约美元值。
queries_remaining 整数 您的账户资金用尽前仍可用于服务查询的大概次数。
warnings 数组 该数组包括警告对象,详细列出这些无效或未知输入数据所提交的请求的相关问题。当您集成网络服务时,强烈建议您检查这一数组,查找问题。

IP 地址(/ip_address

对于 minFraud Score,该对象只包括 IP 地址的 risk。对于 minFraud Insights 和 Factors,该对象是 GeoIP2 Insights 响应体,带有四个修改项:(1)risk 被直接加在 ip_address 对象上;(2)is_high_risk 被加在 country 子对象上;(3)local_time 被加在 location 子对象上;以及(4)maxmind 对象不存在。描述如下:

包括在……
值类型 描述 Score? Insights? Factors?
risk 十进制 字段包括与该 IP 地址相关的风险。值的范围在 0.01 到 99 之间。较高的分数意味着较高风险。

国家(/ip_address/country

包括在……
值类型 描述 Score? Insights? Factors?
is_high_risk 布尔 如果 IP 国家为高风险,则该值为真。

地点(/ip_address/location

值类型 描述 Score? Insights? Factors?
local_time 字符串(255) 交易在 IP 地址相关时区中的日期和时间。值的格式遵循 RFC 3339。例如,波士顿当地时间可能会用 2015-04-27T19:17:24-04:00 的格式返回。

信用卡(/credit_card

这一对象包含与信用卡相关的 minFraud 信息。如果请求中没有提供发放者的 ID 号码(IIN),则该对象不会在响应中出现。

包括在……
值类型 描述 Score? Insights? Factors?
issuer 对象 该字段包括一个带有信用卡发放者相关信息的 JSON 对象。
brand 字符串(255) 卡的品牌,例如“Visa”、“Discover”、“American Express”等。
country 字符串(2) 根据账单地址,使用该信用卡的多数顾客所在地点的两位字符 ISO 3166-1 alpha-2 国家代码。如果顾客地点高度混杂,则默认为该卡发放银行的国家。
is_issued_in_billing_address_country 布尔 如果账单地址所在国家与使用该 IIN 的多数顾客所在国家匹配,则该字段为真。如果顾客地点高度混杂,则匹配项为该卡发放银行的国家。
is_prepaid 布尔 如果该卡为预付卡,则该字段为真。
type 枚举

信用卡的类型。有效值包括:

  • 签账卡 —— 参阅维基百科,了解签账卡与信用卡之间的差别。
  • 信用卡
  • 借记卡

信用卡发放者(/credit_card/issuer

这是 credit_card 的一个子对象,包括信用卡发放者的相关信息。

包括在……
值类型 描述 Score? Insights? Factors?
name 字符串(255) 信用卡发卡银行的名称
matches_provided_name 布尔 如果名称与对信用卡发放者的请求中所提供的名称匹配,则该字段为真。如果名称不匹配,则为假。如果请求中没有提供名称或发放者 ID 号码(IIN),或是 MaxMind 没有该 IIN 的相关名称,则不包括该字段。
phone_number 字符串(255) 信用卡发卡银行的电话号码。有些情况下,我们返回的电话号码可能已经过期。
matches_provided_phone_number 布尔 如果电话号码与对信用卡发放者的请求中所提供的电话号码匹配,则该字段为真。如果号码不匹配,则为假。如果请求中没有提供电话号码或发放者 ID 号码(IIN),或是 MaxMind 没有该 IIN 的相关电话号码,则不包括该字段。

设备(/device

该对象包括 MaxMind 认为与请求中所传送的 IP 地址相关的设备的信息。

包括在……
值类型 描述 Score? Insights? Factors?
confidence 十进制 一个从 0.01 到 99 的数字,代表该 /device/id 指称一个独特设备而不是一群相似设备的置信度。 一个 0.01 的置信度意味着对于设备系属独特只有非常低的信心,99 分则意味着很高的信心。
id UUID MaxMind 用来标识该 IP 地址相关设备的 UUID。注意,许多设备由于太过普遍,而无法被独特识别(例如,某一型号及 OS 发布的所有 iPhones)。 在这种情况下,minFraud 服务不会为该设备返回 UUID。 这仅适用于设备跟踪附加功能的用户。
last_seen 字符串(255) 设备最后一次出现的日期和时间。值的格式遵循 RFC 3339

电子邮件(/email

这一对象包含请求中所传送的电邮地址的信息。

包括在……
值类型 描述 Score? Insights? Factors?
first_seen 字符串(10) 用来识别 MaxMind 首次见到该电邮地址的日期的字符串(例如 2017-04-24)。使用 ISO 8601 日期格式 YYYY-MM-DD 表达。
is_free 布尔 如果 MaxMind 认为该邮件系由 Gmail 或雅虎邮件等免费电邮提供商托管, 则该字段为真。
is_high_risk 布尔 如果 MaxMind 认为该邮件有可能被用于欺诈,则该字段为真。 注意,响应中的整体 risk_score 也会考虑这一因素。

寄送地址(/shipping_address

这一对象含有与寄送地址相关的 minFraud 响应数据。如果未在请求中提供寄送地址或寄送地址无法解析,则该对象不会在响应中出现。

包括在……
值类型 描述 Score? Insights? Factors?
is_high_risk 布尔 如果寄送地址是一个与欺诈交易相关的地址,则该字段为真。如果地址与增加风险无关,则该字段为假。
is_postal_in_city 布尔 如果与地址一起提供的邮政编码处于该地址所在城市中,则该字段为真。如果邮政编码不在相应城市中,则该字段为假。
latitude* 十进制 地址的大致纬度。
longitude* 十进制 地址的大致经度。
distance_to_ip_location 整数 从地址到 IP 地点的公里距离。
distance_to_billing_address 整数 从寄送地址到账单地址的公里距离。
is_in_ip_country 布尔 如果寄送地址处于 IP 国家中,则该字段为真。如果寄送地址不在 IP 国家中,则该字段为假。如果无法对 IP 地址进行地理定位,响应中不会包括这一字段。
* 纬度和经度不够准确,不应用来确认某个具体的街道地址或住户。

账单地址(/billing_address

这一对象含有与账单地址相关的 minFraud 响应数据。如果账单地址未在请求中提供或无法得到解析,则该对象不会在响应中出现。

包括在……
值类型 描述 Score? Insights? Factors?
is_postal_in_city 布尔 如果与地址一起提供的邮政编码处于该地址所在城市中,则该字段为真。如果邮政编码不在相应城市中,则该字段为假。
latitude* 十进制 地址的大致纬度。
longitude* 十进制 地址的大致经度。
distance_to_ip_location 整数 从地址到 IP 地点的公里距离。
is_in_ip_country 布尔 如果地址处于 IP 国家中,则该字段为真。如果地址不在 IP 国家中,则该字段为假。如果无法对 IP 地址进行地理定位,响应中不会包括这一字段。
* 纬度和经度不够准确,不应用来确认某个具体的街道地址或住户。

处置(/disposition

这一对象包括如何根据你所设置的自定义规则处理请求的信息。 如果您的账户没有任何自定义规则,该对象不会在响应中出现。

包括在……
值类型 描述 Score? Insights? Factors?
action 枚举

用来描述如何处理请求。有效值包括:

  • Accept(接受)—— 如果没有与请求匹配的自定义规则,则使用这一默认值。
  • reject(拒绝)
  • manual_review(人工审核)
reason 枚举

用来描述为什么将 action 设为某个特定值。有效值包括:

  • default(默认) —— 没有与请求匹配的自定义规则
  • Custom_rule(自定义规则)—— 适用某条自定义规则并用来设置 action

子分数(/subscores

这一对象包含 risk_score 计算中所使用的许多单个组件的子分数。

只有 minFraud Factors 包括这一对象。
包括在……
值类型 描述 Score? Insights? Factors?
avs_result 十进制 与 AVS 结果相关的风险。如果有,则数值在 0.01 到 99 的范围之间。
billing_address 十进制 与账单地址相关的风险。如果有,则数值在 0.01 到 99 的范围之间。
billing_address_distance_to_ip_location 十进制 账单地址与给定 IP 地址地点之间距离的相关风险。 如果有,则数值在 0.01 到 99 的范围之间。
browser 十进制 浏览器属性(例如用户-代理、接受语言)的相关风险。 如果有,则数值在 0.01 到 99 的范围之间。
chargeback 十进制 您的账户和商店 ID 的给定 IP 地址的个体化退款风险。该项仅供向 MaxMind 递交退款数据的用户使用。 如果有,则数值在 0.01 到 99 的范围之间。
country 十进制 与交易起源国家相关的风险。 如果有,则数值在 0.01 到 99 的范围之间。
country_mismatch 十进制 与 IP 国家、信用卡发放国、账单国家以及寄送国家的组合相关的风险。 如果有,则数值在 0.01 到 99 的范围之间。
cvv_result 十进制 与 CVV 结果相关的风险。如果有,则数值在 0.01 到 99 的范围之间。
email_address 十进制 与具体电子邮件地址相关的风险。如果有,则数值在 0.01 到 99 的范围之间。
email_domain 十进制 与电邮域名相关的一般风险。如果有,则数值在 0.01 到 99 的范围之间。
email_tenure 十进制 与电邮域名的发放者 ID 号码相关的风险。 如果有,则数值在 0.01 到 99 的范围之间。
ip_tenure 十进制 与 IP 地址的发放者 ID 号码相关的风险。 如果有,则数值在 0.01 到 99 的范围之间。
issuer_id_number 十进制 根据账单地点以及某个具体的发放者 ID 号码(IIN)在您的账号和商店 ID 中的使用历史,得出该 IIN 的相关风险。 如果有,则数值在 0.01 到 99 的范围之间。
order_amount 十进制 您的账号及商店 ID 的具体订单数额的相关风险。 如果有,则数值在 0.01 到 99 的范围之间。
phone_number 十进制 与具体电话号码相关的风险。如果有,则数值在 0.01 到 99 的范围之间。
shipping_address_distance_to_ip_location 十进制 寄送地址与给定 IP 地址地点之间距离的相关风险。 如果有,则数值在 0.01 到 99 的范围之间。
time_of_day 十进制 交易在 IP 地址位置所在地的当日时间的相关风险。 如果有,则数值在 0.01 到 99 的范围之间。

警告

包括在……
值类型 描述 Score? Insights? Factors?
code 字符串(255)

该值是一个用来识别警告的机读代码。虽然今后可以加入更多代码,目前的代码包括:

  • BILLING_CITY_NOT_FOUND – 我们的数据库中找不到账单城市。
  • BILLING_COUNTRY_MISSING – 提供账单地址信息时没有提供账单国家。
  • BILLING_COUNTRY_NOT_FOUND – 我们的数据库中找不到账单国家。
  • BILLING_POSTAL_NOT_FOUND – 我们的数据库中找不到账单邮编。
  • INPUT_INVALID – 键的相关值不符合规定的限制条件,例如,在一个规定填入两个字母国家代码的字段中填入“United States”。
  • INPUT_UNKNOWN – 请求体中遇到了未知键。
  • IP_ADDRESS_NOT_FOUND – IP地址无法进行地理定位。
  • SHIPPING_CITY_NOT_FOUND – 我们的数据库中找不到寄送城市。
  • SHIPPING_COUNTRY_MISSING – 提供寄送地址信息时没有提供寄送国家。
  • SHIPPING_COUNTRY_NOT_FOUND – 我们的数据库中找不到寄送国家。
  • SHIPPING_POSTAL_NOT_FOUND – 我们的数据库中找不到寄送邮编。
warning 字符串(255) 该字段提供一个人类可读的警告解释。这一描述可以随时改变,不应与之进行匹配。
input_pointer JSON 指针字符串 与警告相关的输入字段的 JSON 指针。例如,如果是关于账单城市的警告,它将是 /billing/city。如果是关于购物车第二项货品价格的警告,则将是 /shopping_cart/1/price

响应体示例

错误

当服务器返回错误信息(4xx 或 5xx)时,响应体中可能包括一个 JSON 文档。该文件是带有 codeerror 键的单个对象。code 字段是一个机用的静态错误代码。任何给定代码的价值永远都不会变化,虽然代码可以添加或移除。error 字段是人类可读的错误描述,随时可以修改。

并非所有错误都包括一个 JSON 体。内容协商中的错误不会包括主体,很多 5xx 错误也不会,通常这些错误都发生在我们网络服务请求处理代码之外。在试图将主体作为 JSON 解码之前,您应该先检查错误响应的 Content-Type 类型。

除了下文记录的错误外,客户端代码也应该做好处理任何有效的 HTTP 4xx 或 5xx 状态码的准备。

代码 HTTP 状态 描述
IP_ADDRESS_INVALID 400 请求无效

您没有提供一个有效的 IPv4 或 IPv6 地址。

IP_ADDRESS_REQUIRED 400 请求无效

您没有提供 IP 地址,而这是必填字段。

IP_ADDRESS_RESERVED 400 请求无效

您提供的 IP 地址已被保留。

JSON_INVALID 400 请求无效

我们无法将主体作为 JSON 对象解码。

AUTHORIZATION_INVALID 401 未授权

您在授权页头中提供的 MaxMind 用户 ID 及/或许可证密钥无效。

LICENSE_KEY_REQUIRED 401 未授权

您没有在授权页头中提供 MaxMind 许可证密钥

USER_ID_REQUIRED 401 未授权

您没有在授权页头中提供 MaxMind 用户 ID

INSUFFICIENT_FUNDS 402 需要付款

您提供的许可证密钥没有足够资金,无法使用这项服务。请 购买更多服务信用额

PERMISSION_REQUIRED 403 禁止访问

您无权使用该服务。请联系 support@maxmind.com 获取更多信息。

(none) 403 禁止访问

当请求体超过 20000 个字节时,会返回这一状态。

(none) 415 不支持媒体类型

您的请求包括一个不受支持的 Content-Type 页头。对于 GET 请求,这意味着网络服务无法返回该类型的内容。对于 PUTPOST 查询,这意味着网络服务无法解析该类型的请求体。

(none) 503 服务不可用

网络服务服务器出现问题。您可以稍后再次尝试这一请求。

发布说明

我们的发布说明中记录了 minFraud 网络服务中的修改。

版本

minFraud Score 和 minFraud Insights 网络服务使用由两部分组成的版本号。我们目前的发布是版本 2.0。在可见的将来,主版本号将保持为 2。

只会在网络服务出现重大修改时,才会修改次版本号。重大修改是破坏遵循本页文档规定的客户端代码的修改。重大修改包括修改现有字段的类型、完全删除一个字段或修改 URI。

对网络服务的所有修改均将在 minFraud 发布说明中记录,无论版本号码是否修改。

下列修改 被视为重大修改,也不会随之修改版本号码。

  • 因输入验证加强而导致返回警告信息,同样的情况以前不会返回警告。
  • 在结构的顶层或在某个具体对象(例如 billing 或 credit_card)中增加一个新的请求或响应字段。写客户端代码时应该允许新字段的出现。
  • processor 这类的枚举字段添加新的值。
  • 添加或去除警告或错误代码,及/或修改错误的主体类型。客户端代码应该随时检查 Content-Type 页头,查找任何错误响应。客户端代码还应该做好处理任何有效的 HTTP 4xx 或 5xx 状态码的准备。
  • 用新路径添加一个新服务。

许可证

这些服务包含根据知识共享署名 3.0 许可协议获取的 Geonames 地理数据。