跳到正文

风控与反欺诈

欺诈评分、制裁(OFAC)筛查、设备 / IP 指纹与实名认证(KYC),统一在一个风控 API 后面。

1. 概览

基础路径: https://api.infrai.cc/v1/risk
鉴权头: Authorization: Bearer $INFRAI_API_KEY
bash
# Call any /v1/risk capability over raw HTTP — no SDK to install.
# curl:
curl https://api.infrai.cc/v1/risk/... \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json"

2. 方法 (3)

2.1risk.score

POST /v1/risk/score

对用户 / 账户事件(登录、支付、注册)进行欺诈与滥用风险评分,返回 0..1 归一化分数及 接受 / 复核 / 拒绝 处置。计费工作动作,ML 高毛利(service_markup)。

参数

名称类型必填说明
subject_idstring可选被评估的用户 / 账户 id。
event_typestring可选被评分 / 上报的事件。
default: "login"e.g. login
ipstring可选来源 IP 地址。
format: ipv4
emailstring可选与主体关联的邮箱地址。
format: email
device_fingerprintstring可选设备指纹 / 访客 id。
amountnumber可选交易金额。
≥ 0
currencystring可选金额的 ISO 货币代码。
3–3 chars
propertiesRecord<string, unknown>可选任意信号属性。
vendor"maxmind" | "sift" | "shumei" | "tongdun"可选显式 vendor 锁定。
idempotency_keystring可选客户端提供的幂等键。

返回

RiskScore { score, decision, reasons: string[] }
名称类型说明
vendorstring处理此请求的供应商
scorenumber归一化风险评分,越高越危险
0–1
disposition"accept" | "review" | "reject"风险评估处置(allow、challenge、deny)
score_idstringrisk score的唯一标识符
reasonsstring[]reasons contributing to the risk score列表

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/risk/score \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

2.2risk.device.fingerprint

POST /v1/risk/device/fingerprint

由客户端采集令牌加 IP、user-agent 信号解析出稳定的设备指纹 / 访客 id,用于机器人与隐身检测。由 vendor(sift / castle)提供。

参数

名称类型必填说明
request_tokenstring可选客户端采集的令牌 / 访客 id。
ipstring可选来源 IP 地址。
user_agentstring可选客户端 user-agent 字符串。
propertiesRecord<string, unknown>可选任意信号属性。

返回

Device { device_id, signals: object }
名称类型说明
okboolean指纹是否已处理
fingerprint_hashstring | null设备指纹哈希
risk_scorenumber | null此设备的风险评分(0-1)

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/risk/device/fingerprint \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

2.3risk.event.report

POST /v1/risk/event/report

将风险相关事件或标签(拒付、欺诈、滥用)作为反馈回报给 vendor,以改进后续评分。

参数

名称类型必填说明
subject_idstring可选被评估的用户 / 账户 id。
event_typestring
必填
被评分 / 上报的事件。
e.g. chargeback
label"fraud" | "not_fraud"可选结果标签——fraud、legit 或 chargeback。
reasonstring可选上报的自由文本原因。
propertiesRecord<string, unknown>可选任意信号属性。

返回

{ ok: boolean }
名称类型说明
okboolean事件是否已记录
event_idstring | null已记录事件的唯一标识符

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/risk/event/report \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type": "sample"}'
高级:指定 vendor

默认情况下 infrai 会把每次调用智能路由到最佳可用供应商——无需自己挑选 vendor。作为高级逃生口,本能力支持可选的 vendor 入参以锁定某个供应商。本能力当前所有可用 vendor 可通过该能力 id 对应的 discovery 端点实时获取——参见 discovery API

GET /v1/discovery/{capability}

risk.score

3. 全部能力

本模块全部已路由能力——完整的对外 REST 契约。上方方法是带讲解的入门示例,此表是完整参考。

risk.device.fingerprintPOST /v1/risk/device/fingerprint

Resolve a stable device fingerprint / visitor id from a client-collected token plus IP and user-agent signals, for bot and incognito detection. Served by a vendor (sift).

参数 (4)
名称类型必填说明
request_tokenstring可选client-collected token / visitor id
ipstring可选IP address from which the session was created
user_agentstring可选User-Agent string of the client
propertiesobject可选Additional properties for risk assessment
risk.event.reportPOST /v1/risk/event/report

Report a risk-relevant event or label (chargeback, fraud, abuse) back to the vendor as feedback to improve future scoring.

参数 (5)
名称类型必填说明
subject_idstring可选Identifier of the subject being risk-scored
event_typestring必填Type of risk event (e.g. login, payment, registration)
e.g. chargeback
label"fraud" | "not_fraud"可选Risk label (e.g. low, medium, high)
reasonstring可选Reason for the current state or action
propertiesobject可选Additional properties for risk assessment
risk.scorePOST /v1/risk/score

Score a user/account event (login, payment, signup) for fraud and abuse risk, returning a normalized 0..1 score plus an accept / review / reject disposition. Billable work-action, ML high-margin (service_markup).

参数 (10)
名称类型必填说明
subject_idstring可选user/account id under evaluation
event_typestring可选Type of risk event (e.g. login, payment, registration)
default: "login"e.g. login
ipstring可选IP address from which the session was created
format: ipv4
emailstring可选Email address
format: email
device_fingerprintstring可选Device fingerprint hash for identity tracking
amountnumber可选Monetary amount in the specified currency
≥ 0
currencystring可选ISO 4217 currency code (e.g. USD, CNY)
3–3 chars
propertiesobject可选Additional properties for risk assessment
vendor"maxmind" | "sift" | "shumei" | "tongdun"可选Vendor that handled or will handle this request
idempotency_keystring可选Client-provided idempotency key; prevents duplicate execution on retry

4. 完整示例

本模块的生产级端到端范例:先一次性配置,再运行业务流程,尽量覆盖本模块的多数 API。

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
# 1) Auth: every call is a raw HTTPS request to the Infrai gateway carrying
#    only your project key. No SDK, no install.
#    Get your key: sign in with Google/GitHub at https://infrai.cc/login for a
#    project key + $2 free credit (email sign-in starts at $0). On 402
#    INSUFFICIENT_CREDIT, add funds at https://infrai.cc/billing (or POST
#    /v1/account/topup and open the returned checkout_url).
export INFRAI_API_KEY="ifr_..."   # from https://infrai.cc/login

5. 开发者指南(英文)

从端点细节继续进入完整工作流、生产模式和基于实时 API 验证的故障排查指南。

风控与反欺诈 开发者指南