ルールリファレンス

ルールを作成する前に、ルールが処理される方法と、評価基準の設定に使用できる支払い属性を把握しておくことが重要です。Stripe の機械学習を活用した不正使用対策システムは、多くの不正使用の支払いをブロックできますが、サポートされる属性を使用してビジネス固有のルールを作成することもできます。

ルールの処理と順序付け

Radar は、以下の優先順位を使用して、アクションタイプに応じて作成したルールに照らして各支払いを評価します。

1. 3DS のリクエスト: Payment Intents API または Checkout とともに使用された際、3D セキュア認証がサポートされる場合にそれをカード発行会社に「リクエスト」するルール。Radar はこのルールを、ブロックルール、審査ルール、または許可ルールの前に評価します。
2. 許可: 支払いの処理を「許可」するルール。許可ルールに該当する支払いは、ブロックルールまたは審査ルールに照らした評価は行われません。
3. ブロック: 支払いを「ブロック」して拒否するルール。ブロックされた支払いは、審査ルールに照らした評価は行われません。
4. 審査: 支払いの処理は許可するが、「審査対象」にするルール。

同じアクションタイプのルールは順序付けられません。

支払いがルールの基準に一致する場合、Radar は適切なアクションをとり、評価を中止します。たとえば、支払いが許可ルールに一致する場合は、支払いが基準も満たしている場合でも、後続のブロックルールや審査ルールを評価せずに通常どおり処理されます。ルールセットの一例を紹介します。

• $10 未満の支払いを 許可する
• アメリカ国内で行われた支払いで、リスクレベルが normal のものを 許可する
• リスクレベルが high の支払いを ブロックする
• greater than $1,000 の支払いを ブロックする
• outside the US で発行されたカードでの支払いを 審査する

上記のルールの使用:

• リスクレベルやカード発行会社に関係なく、10 USD 未満のすべての支払いが処理されます。最初のルールで支払いが許可されるため、それ以降のルールは評価されません。
• アメリカ国内で通常のリスクレベルで行われた 1,500 米ドルの支払いは、2 番目のルールの基準を満たしているため、通常どおり処理され、1,000 米ドルを超える支払いをブロックするルールに対して評価されません。
• 1,000 USD を超える高リスクの支払いは、どちらの許可ルールの基準も満たさないためブロックされ、評価の順序に関係なく両方のブロックルールがトリガーされます。

ルールの構造

ルールは、実行すべき アクション と、評価するための 条件 の 2 つの要素で構成されています。

{action} if {condition}

これらは、合わせて 述語 と呼ばれます。実際に、1,000 USD を超えるすべての支払いをブロックするルールは次のようになります。

Block if :amount_in_usd: > 1000.00

• 「アクション」は Block です。
• 「条件」は :amount_in_usd: > 1000.00 です。

アクション

支払いが基準を満たすと、ルールはこのセクションで説明されている 4 つのアクションのいずれかを実行します。以下のアクションタイプの順序は、Radar が各ルールを評価する際に従う優先順位を表します。

3D セキュアをリクエストする

Payment Intents API とともに使用した場合、このルールにより、Stripe がカード発行会社に 3D セキュア認証を試みるよう要求するかどうかが決まります。3DS のみをリクエストしても、考えられる 3D セキュアの結果がすべてブロックされるわけではありません。このルールに一致するかどうかに関係なく、その後、許可ルール、ブロックルール、審査ルールが評価されます。

許可

このルールによって、一致する他のルールに関係なく、特定の基準を満たす支払いを許可するケースが決定されます。支払いが許可ルールの基準に一致すると、その支払いはそれ以降は Radar ルール評価の対象とはなりません。Stripe は支払いを通常どおりに処理しますが、カード発行会社によって拒否されることがあります。

ブロック

ブロックルールは、支払いが常に Stripe によってブロックされるケースを勧告します。支払いがブロックルールの基準に一致すると、Stripe によってその支払いは拒否され、それ以降のルール評価は行われません。

審査

特定の支払いタイプを許可すると同時に、その支払いを詳しく検証できるようにしたい場合があります。審査ルールを使用することで、支払いを審査対象にできます。これは、通常より高額の支払いや、あまり配送したことがない国からの支払いなど、特に一般的なパターンに該当しない支払いに役に立ちます。Stripe はこれらの支払いを引き続き処理し、顧客に請求しますが、お客様は、注文を審査して不正利用の兆候がないか確認するための機会が得られます。

特定のルールがトリガーされると、Radar は規定のアクションを実行し、それ以降のルール評価を中止します。

条件

支払いがルールの条件に一致する場合、そのルールのアクションが実行されます。基本的な条件自体は、次の 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 attribute name]:: [operator] [metadata_value]

たとえば、メタデータフィールドに格納されている以下のキーと値のデータを含む支払いがあるとします。

以下の基準に一致する支払いを審査対象にするルールを作成できます。

Review if ::Customer Age:: < 30

メタデータ属性と、このドキュメントに記載されている他のサポートされる属性の両方を使用して、ルールを作成することもできます。たとえば、Item ID が 5A381D と一致し、支払い額が 1,000 USD を超える場合にのみ支払いを審査対象にするルールを作成できます。

Review if ::Item ID:: = '5A381D' and :amount_in_usd: > 1000

メタデータ属性は、複数の値と照合するための IN 演算子もサポートしています。たとえば、Category ID が「groceries」、「electronics」、「clothing」のいずれかである場合に支払いを審査対象にするルールを作成できます。

Review if ::Category ID:: IN ('groceries', 'electronics', 'clothing')

INCLUDES 演算子は、サブストリングに一致するメタデータ属性およびその他の文字列属性のルールで使用できます。たとえば、Item ID に文字列 A381 が含まれている場合に支払いを審査対象にするルールを作成できます。この場合、A381、5A381D、A381D、5A381 などが一致します。

Review if ::Item ID:: INCLUDES 'A381'

Customer オブジェクトと Destination オブジェクトのメタデータ

メタデータには、Customer オブジェクトと Destination オブジェクトからもアクセスできます (これらのオブジェクトが特定の支払いに使用されている場合)。これらの属性は、次の構造を使用します。

::[customer|destination]:[metadata attribute name]:: [operator] [metadata_value]

たとえば、以下のメタデータを含む顧客がいるとします。

顧客の Trusted メタデータフィールドが true の場合は常に支払いを許可するというルールを作成できます。

Allow if ::customer:Trusted:: = 'true'

または、以下のメタデータを含むデスティネーションがあるとします。

デスティネーションの Category メタデータフィールドが new の場合は支払いを審査する、というルールを作成できます。

Review if ::destination:Category:: = '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 つの値があります。

いくつかのルール例を以下に示します。

• Block if :address_line1_check: = 'fail'
• Block if :cvc_check: != 'fail'
• 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 時間よりも前に更新されます。

演算子

条件の演算子は、支払い属性と指定した値の比較を示します。使用されている属性のタイプに応じて、使用可能な演算子は異なります。

リスト

リストを使用して、ルール内の値のグループを参照できます。ルールで参照されるリストのエイリアスは、すべて @ で始まる必要があります。リストを参照するルールを作成するには、以下の構造を使用します。

{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

ルールでリストを参照することにより、多くの個別ルールを維持するのではなく、一元的に多くのアイテムを編集できるようになります。

属性の欠落

一般的なルール条件は、: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' 以外の値を持つ」と言う意味に解釈され、属性が欠落しているとこれが満たされません。NOT 演算子を使用すると、欠落している属性情報も先に繰り延べられます。そのため :email_domain: 属性が欠落している場合、ルール は NOT (:email_domain: = 'definitelysafe.com') が同様に支払いと一致ないかどうかを確認します。

一般に、欠落しているフィーチャーを別の静的な値またはフィーチャー (欠落していても存在していても) と比較 (=、!=、>、< など) すると、常に false が返されます。不足している機能が含まれる比較で NOT 演算子を使用すると、常に false が返されます。

is_missing 関数による明示的な処理

属性またはメタデータ属性の存在を明示的に確認する場合は、is_missing 関数を使用します。この関数を、欠落しているか可能性がある属性またはメタデータキーとともに使用します。

たとえば、顧客のメールアドレスにアクセスできないすべての支払いに一致するルールを作成できます。

• Review if is_missing(:email_domain:)

あるいは、特定のメタデータ属性が設定されているすべての支払いに一致するルールを作成することもできます。

• Review if !(is_missing(::foo::))

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: = 'Canada' (国の値は 2 文字の短いコードで入力する必要があります)
• :amount_in_usd: >= 'one thousand dollars' (数値は数字で入力する必要があります)
• :is_anonymous_ip: = 'true' (ブール値属性は演算子または値と一緒に使用しません)

速度ルール

多くのサポートされる属性には、さまざまな時間スケールに対応した不変量が含まれます (total_charges_per_email_daily の daily など)。これらは、速度ルールと呼ばれます。

Stripe はバケットの増分を使用して属性を計算します。増分の長さは属性の期間によって異なります。これにより、属性の速度には、この期間内に発生したデータと 1 バケットのデータが含まれる可能性があります。たとえば、1 時間ごとの属性間隔は、現在の取引の 3900 秒 (1 時間 5 分) になることがあります。これは、間隔に 5 分のバケットが使用されるためです。

属性は以下のように定義されます。

• hourly は最大 3900 秒 (5 分バケット)
• daily は最大 90000 秒 (1 時間バケット)
• weekly は最大 608400 秒 (1 時間バケット)
• yearly は最大 31622400 秒 (1 日バケット)
• all_time は最大 31622400 秒 (1 日バケット) の速度で 5 年間のデータを含む

これらの属性の一般的なユースケースは、Radar の基本ガイドで説明されているように、カードテスティングまたは列挙攻撃のシナリオを減らすことです。