ルールリファレンス
ルールを作成する前に、ルールが処理される方法と、評価基準の設定に使用できる支払い属性を把握しておくことが重要です。Stripe の機械学習を活用した不正使用対策システムは、多くの不正使用の支払いをブロックできますが、サポートされる属性を使用してビジネス固有のルールを作成することもできます。
ルールの処理と順序付け
ルールが実行するアクションによって処理される順序が決まります。Radar は各支払いを、作成されたルールに照らして評価します。ルールには以下の優先順位があります。
- 3DS のリクエスト: Payment Intents API または Checkout と一緒に使用された際、3D セキュア認証がサポートされる場合にそれを「リクエスト」するルール。Radar はこのルールを、ブロックルール、レビュールール、または許可ルールの前に評価します。
- 許可: 支払いの処理を「許可」するルール。許可ルールに該当する支払いは、ブロックルールまたはレビュールールに照らした評価は行われません。
- ブロック: 支払いを「ブロック」して拒否するルール。ブロックされた支払いは、レビュールールに照らした評価は行われません。
- レビュー: 支払いの処理は許可するが、「レビュー対象」にするルール。
支払いがルールの基準に一致する場合、Radar は適切なアクションをとり、その支払いの評価はそれ以上行われません。支払いが許可ルールに一致する場合は、通常どおり処理されます。その支払いがブロックルールやレビュールールの基準も満たす場合でも、それ以後にそれらのルールで評価されることはありません。ルールセットの一例を紹介します。
$10
未満の支払いを 許可する- アメリカ国内で行われた支払いで、リスクレベルが
normal
のものを 許可する - リスクレベルが
high
の支払いを ブロックする greater than $1,000
の支払いを ブロックするoutside the US
で発行されたカードでの支払いを レビューする
上記のルールを使用すると、リスクレベルや使用したカードの発行場所に関係なく、10 USD 未満の支払いはすべて処理されます。これは、最初のルールで支払いが許可されているため、それ以降のルールは評価されないことが理由です。同様に、1,000 USD を超える支払いをブロックするルールが存在しますが、アメリカ国内で行われた通常のリスクレベルの 1,500 USD の支払いも許可されます。これは、リストの 2 番目のルールにより、アメリカ国内で行われた通常のリスクレベルの支払いが許可されるためです。特定のルールがトリガーされると、それ以降のルールは評価されません。
ルールの構造
ルールは、実行する必要のある「アクション」と、評価するための「条件」の 2 つの要素で構成されています。
{action} if {condition}
これらは、合わせて「述語」と呼ばれます。実際に、1,000 USD を超えるすべての支払いをブロックするルールは次のようになります。
Block if :amount_in_usd: > 1000.00
- 「アクション」は
Block
です。 - 「条件」は
:amount_in_usd: > 1000.00
です。
アクション
ルールは、基準を満たす支払いに 4 つのアクションのうちのいずれかを実行することができ、特定の順序で処理されます。
3D セキュアをリクエストする
Payment Intents API とともに使用した場合、このルールにより、Stripe がカード発行会社に 3D セキュア認証を試みるよう要求するかどうかが決まります。3DS のみをリクエストしても、考えられる 3D セキュアの結果がすべてブロックされるわけではありません。このルールに一致するかどうかに関係なく、その後、許可ルール、ブロックルール、レビュールールが評価されます。
許可
このルールによって、Stripe の評価や一致する他のルールに関係なく、特定の基準を満たす支払いを常に許可するケースが決定されます。支払いが許可ルールの基準に一致すると、その支払いは Stripe によって通常どおり処理され、それ以降のルール評価の対象とはなりません。ただし、Stripe が支払いを続行する場合でも、カード発行会社によって拒否されることがあります。
ブロック
ブロックルールは、支払いが常に Stripe によってブロックされるケースを指定します。支払いがブロックルールの基準に一致すると、Stripe によってその支払いは拒否され、それ以降のルール評価は行われません。
レビュー
特定の支払いタイプを許可すると同時に、その支払いを詳しく検証できるようにしたい場合があります。レビュールールを使用することで、支払いをレビュー対象にできます。これは、通常より高額の支払いや、あまり配送したことがない国からの支払いなど、特に一般的なパターンに該当しない支払いに役に立ちます。Stripe はこれらの支払いを引き続き処理し、顧客に請求しますが、お客様は、注文をレビューして不正使用の兆候がないか確認するための機会が得られます。
条件
支払いがルールの条件に一致する場合、そのルールのアクションが実行されます。基本的な条件自体は、次の 3 つの部分で構成されています。
[attribute] [operator] [value]
- attribute : 支払い属性 (「金額」、「カードタイプ」など)
- operator : 属性を値と比較する演算子 (「より大きい」、「等しくない」など)
- value : 使用する基準 (
100.00
、debit
など)
アクションと条件の両方を組み合わせると、ルールの構造は次のようになります。
{action} if {[attribute] [operator] [value]}
属性タイプに応じて、4 つのタイプの条件があります。
[string_attribute] [operator] [string_value]
[country_attribute] [operator] [country_value]
[numeric_attribute] [operator] [numeric_value]
[boolean_attribute]
特定の属性を、条件内の対応する値として使用することもできます。たとえば、次の属性と値を使用して、カードが発行された国と支払いが行われた国が一致しない場合に支払いをブロックするルールを作成できます。
Block if :card_country: != :ip_country:
可能性のあるすべての条件の一覧については、サポートされる属性をご覧ください。
文字列属性
文字列属性には、文字の任意の組み合わせが含まれます。文字列属性と値は通常、カードブランド (例: visa
、amex
) やリスクレベル (例: elevated
) などのテキストを表します。これらをルールに使用して、特定の国からの支払いのみを許可したり、プリペイドカードでの支払いをブロックしたりできます。
メタデータ属性
メタデータ属性は、支払いに関連付けられたメタデータから派生します。メタデータ属性は、文字列または数字として機能します。文字列として使用する場合、メタデータ属性では 「大文字と小文字が区別されます」。
Stripe Radar ルールを作成する際にメタデータ属性を使用することにより、支払いに関連付けられたメタデータフィールドで Stripe に渡したカスタムのビジネス属性に照らし合わせるルールを作成できます。
メタデータ属性は、次の構造で記述されます。
::[metadata_value]
:: [operator]
たとえば、メタデータフィールドに格納されている以下のキーと値のデータを含む支払いがあるとします。
メタデータ名 | メタデータ値 |
---|---|
Customer Age | 22 |
Item ID | 5A381D |
Category ID | groceries |
以下の基準に一致する支払いをレビュー対象にするルールを作成できます。
Review if < 30
メタデータ属性と、このドキュメントに記載されている他のサポートされる属性の両方を使用して、ルールを作成することもできます。たとえば、Item ID
が 5A381D
と一致し、支払い額が 1,000 USD を超える場合にのみ支払いをレビュー対象にするルールを作成できます。
Review if =
'5A381D'
and :amount_in_usd: > 1000
メタデータ属性は、複数の値と照合するための IN
演算子もサポートしています。たとえば、Category ID
が「groceries」、「electronics」、「clothing」のいずれかである場合に支払いをレビュー対象にするルールを作成できます。
Review if IN (
'groceries'
, 'electronics'
, 'clothing'
)
INCLUDES
演算子は、サブストリングに一致するメタデータ属性およびその他の文字列属性のルールで使用できます。たとえば、Item ID
に文字列 A381
が含まれている場合に支払いをレビュー対象にするルールを作成できます。この場合、A381、5A381D、A381D、5A381 などが一致します。
Review if INCLUDES
'A381'
注意
文字列として使用する場合、メタデータ属性では大文字と小文字が区別されます。ルールで指定するメタデータ値が、支払いに関連付けられているものと完全に同じであることを必ず確認してください。
Customer オブジェクトと Destination オブジェクトのメタデータ
メタデータには、Customer オブジェクトと Destination オブジェクトからもアクセスできます (これらのオブジェクトが特定の支払いに使用されている場合)。これらの属性は、次の構造を使用します。
::[customer|destination]:[metadata_value]
:: [operator]
たとえば、以下のメタデータを含む顧客がいるとします。
メタデータ名 | メタデータ値 |
---|---|
Trusted | true |
顧客の Trusted
メタデータフィールドが true
の場合は常に支払いを許可するというルールを作成できます。
Allow if =
'true'
または、以下のメタデータを含むデスティネーションがあるとします。
メタデータ名 | メタデータ値 |
---|---|
Category | new |
デスティネーションの Category
メタデータフィールドが new
の場合は支払いをレビューする、というルールを作成できます。
Review if =
'new'
国属性
国の属性には、国を表す 2 文字の国コードが使用されます。たとえば、アメリカは US
、イギリスは GB
、アルゼンチンは AR
として表されます。国の属性は文字列属性と同じように機能しますが、唯一の違いは、値が国コードでなければならないということです。
州の属性
州の属性には、州または国の区画を表す ISO コードが使用されます。たとえば、アメリカのカリフォルニア州は CA
、イギリスのイングランドは ENG
、アルゼンチンのラ・パンパ州は L
として表されます。州の ISO コードからは 2 文字の国コードが省略されるため、カリフォルニア州からの取引をブロックする場合、ルールは州の属性を CA
と比較します。
Block if :ip_state: =
'CA'
州の属性は文字列属性と同じように機能しますが、唯一の違いは、値が ISO コードでなければならないということです。
数値属性
数値属性には数値のみが含まれているため、文字列属性や値よりも多くの演算子に対応しています。支払い「額」は、数値属性の一例です。金額が指定した金額より高い、低い、等しい、または等しくない場合にアクションを実行するというルールを作成できます。
時間枠でカウントされる数値属性の場合、カウントには現在処理中の支払いは含まれません。たとえば、total_charges_per_customer_hourly
は、過去 1 時間に特定の顧客から行われたこれまでの支払い試行回数を表します。したがって、特定の 1 時間の中で最初に行われた顧客の支払い試行では、total_charges_per_customer_hourly
の値が 0
になります。同じ時間内に行われた 2 回目の支払い試行で値は 1
になり、以降同様に続きます。
Time-since-first-seen の各属性でも、現在処理中の支払いは考慮されません。たとえば、メールアドレスがない支払いには、seconds_since_email_first_seen
の値がありません。メールアドレスがある支払いでも、それまでアカウントで処理されたことがなかった場合にはやはりこの値がありません (現在処理中の支払いは含まれないため、最初の例と実質的に同じ動作になります)。欠落値の詳細については、以下をご覧ください。seconds_since_email_first_seen
フィールドは、メールアドレスが指定された新しい支払いが処理された後に初めて null ではなくなります。
制限付き数値属性
制限付き数値属性は、前述の数値属性と似ています。たとえば、現在処理中の支払いは除外されます。異なるのは、制限付き数値属性で使用できる値が、特定の値を上限とする (または「制限付き」) 点です。
たとえば、authorized_charges_per_email_hourly
を例に挙げます。これは、過去 1 時間に自身のアカウントで、あるメールアドレスに対してオーソリされたこれまでの支払い件数を表します。ここでは、5
の制限があるとします。メールアドレス jenny.rosen@example.com
で過去 1 時間に試行された支払いが初回の場合、カウンター値は 0
です。同じ時間内に支払いが試行されるたびに、数値は上がります。同じ時間内に jenny.rosen@example.com
が 6 回目の試行を行うと、カウンターは増加しなくなり、実際には過去 1 時間に 6
回の支払い試行が行われたにもかかわらず、5
のままとなります。
上限を超えてカウンターを増加させる試みが行われた場合、古い値は考慮からはずされ、新しい値に置き換えられます。たとえば、3
の上限が設定され、すでに 3 回の支払いが行われたカウンターを考えてみましょう。カウンターを可視化する 1 つの方法は、支払いの入金回数を表すタイムスタンプのリストを管理することです。たとえば、[10, 20, 30]
の場合、支払いが 50
回に到達すると、カウンターは [20, 30, 50]
のようになります。
ブール値属性
ブール値属性は、特定の属性が true であるかどうかを表します。文字列や数値の属性とは異なり、使用する演算子や値はありません。ブール値属性を使用して、使い捨てのメールアドレスで行われた支払いをブロックしたり、匿名の IP アドレスで行われた支払いをレビュー対象にしたりすることができます。
オーソリ後属性
オーソリ後属性 (:cvc_check:
、:address_zip_check:
、:address_line1_check:
など) では、オーソリプロセスの一環として、Stripe がカード発行会社とデータを交換する必要があります。カード発行会社は、このデータをカード保有者の登録情報と照合し、一致することを確認します。オーソリ後属性を使用するルールは、オーソリ後属性を使用しないルールの後に実行されます。(これにより支払いがブロックされるかどうかに影響はしませんが、支払いをブロックするルールに影響を与える可能性があります。)
ルールでオーソリ後属性を使用すると、支払いが最終的にブロックされた場合でも、顧客の明細書に一時的にオーソリが表示されることがありますが、通常は数日後に消えます。
住所 (AVS) 属性とセキュリティコード属性には次の 5 つの値があります。
属性値 | 説明 |
---|---|
pass | 提供されたデータは正しいです。 |
fail | 提供されたデータは正しくありません。 |
unavailable | 顧客のカード発行会社は提供されたデータを確認しません。すべてのカード発行会社や国が住所確認に対応しているわけではありません。 |
unchecked | データは提供されましたが、まだ確認されていません。顧客のカード発行会社が最終的に提供されたデータを確認します。 |
not_provided | データが Stripe に提供されませんでした。 |
いくつかのルール例を以下に示します。
Block if :address_line1_check: =
'fail'
Block if :cvc_check: !=
'pass'
Block if :address_zip_check: in (
'fail'
,'not_provided'
)
ルールで厳格な pass
を要求すると、過度に制限的になってしまう可能性があります。たとえば、ウォレットはトークン化されたカード情報を保管しているため、通常は CVC を提供しません。そのため、3D セキュアの確認などによるセキュリティコードの確認は、Apple Pay などの決済手段で利用できません。このようなエッジケースに考慮した Radar の構築済みのルールを使用することをお勧めします。
サポートされる属性
カスタムのルール定義に適用できる属性の一覧については、サポートされる属性の一覧をご覧ください。
換算後の金額
amount_in_xyz
を使用する場合、お客様が選択した基準に金額が一致するかどうかを確認するときに、Stripe は支払いの換算後の金額を自動的に判定します。たとえば、amount_in_usd
を使用して 1,000 USD を超えるすべての支払いをブロックするルールを作成すると、別の通貨での額面価格がそれよりも低い (例: 900 GBP) 場合でも、換算後の値が 1,000 USD を超える支払いがブロックされます。
「2020 年以降の支払いが対象となります」の実務への影響について
一部のルール属性の説明には、「2020 年以降の支払いが対象となります」という語句が含まれています。これは、あるカードでのビジネスとの最後の取引が 2019 年であった場合、そのカードが新規取引のカードと同様に扱われることになることを表します。理解しづらい状況が発生するおそれがあるため、この語句については、ビジネスでの業務の処理方法とルールを慎重に検討する必要があります。たとえば、新しいカードでの高額の支払いをブロックするルールを作成した場合、2019 年以降に購入取引を行っていなかった優良顧客がブロックされる可能性があります。
「この属性は、過去 <week, year> にアカウントとやり取りのあった本番環境の Customer オブジェクトのみが対象となります。このルールは最大でも 72 時間に 1 回更新されます」の実務における意味について
一部のルール属性の説明には、「この属性は、過去 <week, year> にアカウントとやり取りのあった本番環境の Customer オブジェクトのみが対象となります。このルールは最大でも 72 時間に 1 回更新されます」という文章が含まれます。これは、過去 1 週間または 1 年間にアカウントで作成、請求、更新された本番環境の Customer オブジェクトが、カウントに含まれることを意味します。ただし、カウントは即時に更新されるのではなく、システム全体に反映されるには最大 72 時間かかる場合があります。とはいうものの、多くの場合、これらのカウンターは 72 時間よりも前に更新されます。
演算子
条件の演算子は、支払い属性と指定した値の比較を示します。使用されている属性のタイプに応じて、使用可能な演算子は異なります。
演算子 | 文字列 | メタデータ | 国 | 州 | 数値 | 説明 | 例 |
---|---|---|---|---|---|---|---|
= | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | 等しい | :card_country: = |
!= | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | 等しくない | :card_funding: != |
< | ✔︎ | より小さい | :amount_in_gbp: < 10.00 | ||||
> | ✔︎ | より大きい | :amount_in_usd: > 500.00 | ||||
<= | ︎ | ✔︎ | 以下 | :amount_in_eur: <= 100.00 | |||
>= | ✔︎ | 以上 | :amount_in_cad: >= 10.00 | ||||
IN | ✔ | ✔︎ | ✔ | ✔︎ | ✔︎ | グループに含まれる | :card_country: IN ( |
INCLUDES | ✔ | ✔︎ | ✔ | ✔ | 文字列を含む | :ip_address: INCLUDES | |
LIKE | ✔ | ✔︎ | ✔ | ✔ | 特定のパターンの一致を調べます。ゼロ、または任意の数の文字、数字、記号の一致を調べるには、ワイルドカード文字 % を使用します。 | :email: LIKE |
リスト
リストを使用して、ルール内の値のグループを参照できます。ルールで参照されるリストのエイリアスは、すべて @
で始まる必要があります。リストを参照するルールを作成するには、以下の構造を使用します。
{action} [attribute] in [list]
たとえば、ブロック対象にするカードの国リストがあるとします。以下のようにいくつかの OR
句を使用してルールを書くことができます。
Block if :card_country: =
'CA'
OR :card_country: = 'DE'
OR :card_country: = 'AE'
インラインリストを使用してルールを作成することもできます。
Block if :card_country: IN (
'CA'
, 'DE'
, 'AE'
)
ブロック対象にするカードの国リストを card_countries_to_block
という名前で作成することもできます。次に、選択した国をリストに追加し、ルールでそのリストを参照できます。
Block if :card_country: in @card_countries_to_block
ルールでリストを参照することにより、多くの個別ルールを維持するのではなく、一元的に多くのアイテムを編集できるようになります。
注意
EU の加盟店は、Geo-blocking Regulation によって EU 加盟国に在住の顧客からの支払いをブロックすることが禁じられていることに注意してください。この規制の詳細はこちらで確認できます。
属性の欠落
一般的なルール条件は、:card_country:
(すべてのカードベースの支払いに設定される) や、支払いリクエストで常に送信するメタデータ属性など、すべての支払いに設定される属性を参照します。一部のケースでは、以下の例のように、属性が欠落していることがあります。
サイトにさまざまな決済フローがあり、そのフローの一部が顧客のメールアドレスを収集しない
Stripe.js の使用を始めたばかりのため、
:ip_country:
は新規支払いでは利用できるが、 (ルールのプレビュー時に検索する) 過去の支払いでは利用できない一部の支払いについて、組み込みのバグにより所定のメタデータキーの設定に失敗する
ルール条件が欠落している属性を評価する方法
ルール Block if :email_domain: =
を検討します。顧客のメールアドレスを収集しなかった場合、'definitelyfraud.com'
:email_domain:
属性が欠落し、想定どおりルール条件が支払いと一致しません。
次に、Review if :email_domain: != ‘definitelysafe.com’
ルールについて考えてみましょう。:email_domain:
属性が欠落していると、このルールは支払いの照合 「も」 しません。値が欠落しているということは
であることと同じではないため、この結果に驚くかもしれません。このケースでは、'definitelysafe.com'
!= ‘definitelysafe.com’
が「属性が ‘definitelysafe.com’
以外の値を持つ」と言う意味に解釈され、属性が欠落しているとこれが満たされません。
一般に、欠落しているフィーチャーを別の静的な値またはフィーチャー (欠落していても存在していても) と比較 (=
、!=
、>
、<
など) すると、常に false が返されます。
is_missing
関数による明示的な処理
属性またはメタデータ属性の存在を明示的に確認する場合は、is_missing
関数を使用します。この関数を、欠落しているか可能性がある属性またはメタデータキーとともに使用します。
たとえば、顧客のメールアドレスにアクセスできないすべての支払いに一致するルールを作成できます。
Review if is_missing(:email_domain:)
あるいは、特定のメタデータ属性が設定されているすべての支払いに一致するルールを作成することもできます。
Review if !(is_missing( ))
is_missing
関数は、OR
または AND
結合でも使用できます。
Review if is_missing(:email_domain:) OR :email_domain: IN (
'yopmail.net'
,'yandex.ru'
)
複雑な条件
演算子 AND、OR、NOT を使用して基本条件を結合することにより、複雑な条件を作成できます。&&、||、! などの同等を意味する記号もそれぞれ使用できます。
C、Python、SQL などのプログラミング言語と同様に、Stripe は標準演算子の「優先順位」(演算の順序) に対応しています。たとえば、以下のような複雑な条件があります。
{condition_X} OR NOT {condition_Y} AND {condition_Z}
上記は、以下のように解釈されます。
{condition_X} OR ((NOT {condition_Y}) AND {condition_Z})
複雑な条件内でのサブ条件によるグループ化にも、括弧を使用することで対応しています。たとえば、前の例を修正して、サブ述語の評価順序を明示的に変更できます。
({condition_X} OR (NOT {condition_Y})) AND {condition_Z}
{condition_X} OR NOT ({condition_Y} AND {condition_Z})
さまざまな場所で括弧を使用することにより、上記の複雑な条件はそれぞれ異なる結果につながります。
有効な条件
次の条件は、属性およびサポートされる演算子の正しい使用例です。
:card_brand: =
'amex'
:card_country: !=
'US'
:amount_in_usd: >= 1000.00
:is_anonymous_ip:
無効な条件
ルールを作成する際に無効な条件を使用しようしているかどうかについて、Radar からフィードバックが提供されます。参考のために、無効な条件の例を以下に示します。この例では、使用されている属性または演算子の値がサポートされていません。
:risk_level: <
(文字列の値は = または != 演算子でのみ使用できます)'highest'
:ip_country: =
(国の値は 2 文字の短いコードで入力する必要があります)'Canada'
:amount_in_usd: >=
(数値は数字で入力する必要があります)'one thousand dollars'
:is_anonymous_ip: =
(ブール値属性は演算子または値と一緒に使用しません)'true'
速度ルール
多くのサポートされる属性には、さまざまな時間スケールに対応した不変量が含まれます (total_charges_per_email_daily
の daily
など)。これらは、速度ルールと呼ばれます。
属性は、カレンダーではなく固定の秒数に基づいて、経過期間として計算されます。たとえば、daily
は、rule 属性における 2 つの支払いの間隔が、最大 24 時間または 86400 秒離れている必要があることを意味します。
属性は以下のように定義されます。
hourly
は 3600 秒daily
は 86400 秒weekly
は 604800 秒yearly
は 31536000 秒
これらの属性の一般的なユースケースは、Radar の基本ガイドで説明されているように、カードテスティングまたは列挙攻撃のシナリオを減らすことです。