minFraud 退款网络服务 API

向 MaxMind 报告交易退款,可以帮助我们为您的公司多侦测出 10 – 50% 的欺诈件数。我们提供两种递交退款数据的方式:通过在线表格或通过本页面所记录的一个 API。

HTTP API

HTTP API 要求您通过一个 HTTP POST 用 JSON 格式传送一组参数。

该服务的 URI 是 https://minfraud.maxmind.com/minfraud/chargeback

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

  • minfraud-us-east.maxmind.com
  • minfraud-us-west.maxmind.com
  • minfraud-eu-west.maxmind.com

授权

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

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

请求体

minFraud API 接受 HTTP POST 的主体中 JSON 格式的输入。JSON 文件应该由一个单独对象组成。该对象可以包含下列键(键名需要区分大小写):

名称 类型 描述

必填字段

下列字段必须填写。

ip_address 字符串

下单客户的 IP 地址。这应该用“44.55.66.77”或“2001:db8::2:1”之类的字符串传送。

选填字段

下列字段为选填项。

chargeback_code 字符串

一个由您的支付处理商提供的字符串,用来说明退款原因

tag 字符串

用来说明交易可能属于欺诈的概率的字符串。可能的值:not_fraudsuspected_fraudspam_or_abusechargeback

该字段原来被称为 fraud_score,但这个名称现已弃用。简言之,API 将 fraud_scoretag 均作为有效键接受。另外,在这段过渡期间,fraud_score 以前被接受的值 known_fraud 仍将得到接受,但会自动映射至 chargeback

maxmind_id 字符串(8)

一个含有八位字符的独特字符串,用来标识 minFraud Standard 或 Premium 请求。对于成功的 minFraud 请求,将在 maxmindID 字段中返回这些 ID。该字段不是必填项,但我们鼓励您在可能的情况下提供该信息。

minfraud_id 字符串(36)

一个标识 minFraud Score、minFraud Insights 或 minFraud Factors 请求的 UUID。在请求的 /id 中返回这一 ID 。该字段不是必填项,但是,如果是针对上述某项服务提供的请求,我们鼓励您提供该信息。

transaction_id 字符串

您最初传送给 minFraud 的交易 ID。该字段不是必填项,但我们鼓励您提供该信息或是交易的 maxmind_idminfraud_id

请求头

Content-Type 头总是 application/json

请求

使用 HTTP 状态码来传递成功与错误讯息。一个成功的 POST 将返回一个 204(无内容)状态码。

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

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

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

代码 HTTP 状态 描述

错误代码

FRAUD_SCORE_INVALID 400 请求无效

Fraud_score 的可能值包括 ‘not_fraud’、‘suspected_fraud’ 以及 ‘known_fraud’。为 fraud_score 提供任何其他值均将触发这一错误。

JSON_INVALID 400 请求无效

无法解析您的 JSON。试着用 jsonlint.com 之类的工具检查您的 JSON 是否有误。

MAXMIND_ID_INVALID 400 请求无效

您提供了一个无效的 maxmind_id。该字段区分大小写。检查您的 maxmind_id,确保其长度为8位字符且仅由数字和大写字母组成。这个值必须来自对此前某次 minFraud 请求的成功响应。

MINFRAUD_ID_INVALID 400 请求无效

您提供了一个无效的 minfraud_id。检查您的 minfraud_id,确保它是一个由 minFraud Score、minFraud Insights 或 minFraud Factors 响应返回的有效 UUID。

PARAMETER_UNKNOWN 400 请求无效

您提供了一个未知参数。检查您 JSON 数据中的键,确保您没有拼错任何字段名或传送任何未列入可用输入字段的字段名。

IP_ADDRESS_INVALID 400 请求无效

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

IP_ADDRESS_REQUIRED 400 请求无效

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

IP_ADDRESS_RESERVED 400 请求无效

您所提供的 IP 地址属于保留或私有的范围。

AUTHORIZATION_INVALID 401 未授权

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

LICENSE_KEY_REQUIRED 401 未授权

您在授权页头中提供的 MaxMind 许可证密钥无效。

USER_ID_REQUIRED 401 未授权

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

(none) 415 不支持媒体类型

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

(none) 503 服务不可用

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

客户端代码示例

Perl

curl