From f3c3f3868ae923b6e194185909adf14a56d9754e Mon Sep 17 00:00:00 2001 From: Google APIs Date: Fri, 17 Mar 2023 14:23:45 -0700 Subject: [PATCH] feat: add reCAPTCHA Enterprise Fraud Prevention API This cl adds API features for Fraud Prevention including the FraudPreventionAssessment. PiperOrigin-RevId: 517508635 --- .../v1/recaptchaenterprise.proto | 332 +++++++++++++++++- .../v1/recaptchaenterprise_v1.yaml | 7 + 2 files changed, 330 insertions(+), 9 deletions(-) diff --git a/google/cloud/recaptchaenterprise/v1/recaptchaenterprise.proto b/google/cloud/recaptchaenterprise/v1/recaptchaenterprise.proto index 5c90c5493ddcb..c77eef437b264 100644 --- a/google/cloud/recaptchaenterprise/v1/recaptchaenterprise.proto +++ b/google/cloud/recaptchaenterprise/v1/recaptchaenterprise.proto @@ -1,4 +1,4 @@ -// Copyright 2022 Google LLC +// Copyright 2023 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -65,6 +65,7 @@ service RecaptchaEnterpriseService { post: "/v1/{parent=projects/*}/keys" body: "key" }; + option (google.api.method_signature) = "parent,key"; } // Returns the list of all keys that belong to a project. @@ -72,6 +73,7 @@ service RecaptchaEnterpriseService { option (google.api.http) = { get: "/v1/{parent=projects/*}/keys" }; + option (google.api.method_signature) = "parent"; } // Returns the secret key related to the specified public key. @@ -90,6 +92,7 @@ service RecaptchaEnterpriseService { option (google.api.http) = { get: "/v1/{name=projects/*/keys/*}" }; + option (google.api.method_signature) = "name"; } // Updates the specified key. @@ -98,6 +101,7 @@ service RecaptchaEnterpriseService { patch: "/v1/{key.name=projects/*/keys/*}" body: "key" }; + option (google.api.method_signature) = "key,update_mask"; } // Deletes the specified key. @@ -105,6 +109,7 @@ service RecaptchaEnterpriseService { option (google.api.http) = { delete: "/v1/{name=projects/*/keys/*}" }; + option (google.api.method_signature) = "name"; } // Migrates an existing key from reCAPTCHA to reCAPTCHA Enterprise. @@ -175,6 +180,125 @@ message CreateAssessmentRequest { Assessment assessment = 2 [(google.api.field_behavior) = REQUIRED]; } +// Describes an event in the lifecycle of a payment transaction. +message TransactionEvent { + // Enum that represents an event in the payment transaction lifecycle. + enum TransactionEventType { + // Default, unspecified event type. + TRANSACTION_EVENT_TYPE_UNSPECIFIED = 0; + + // Indicates that the transaction is approved by the merchant. The + // accompanying reasons can include terms such as 'INHOUSE', 'ACCERTIFY', + // 'CYBERSOURCE', or 'MANUAL_REVIEW'. + MERCHANT_APPROVE = 1; + + // Indicates that the transaction is denied and concluded due to risks + // detected by the merchant. The accompanying reasons can include terms such + // as 'INHOUSE', 'ACCERTIFY', 'CYBERSOURCE', or 'MANUAL_REVIEW'. + MERCHANT_DENY = 2; + + // Indicates that the transaction is being evaluated by a human, due to + // suspicion or risk. + MANUAL_REVIEW = 3; + + // Indicates that the authorization attempt with the card issuer succeeded. + AUTHORIZATION = 4; + + // Indicates that the authorization attempt with the card issuer failed. + // The accompanying reasons can include Visa's '54' indicating that the card + // is expired, or '82' indicating that the CVV is incorrect. + AUTHORIZATION_DECLINE = 5; + + // Indicates that the transaction is completed because the funds were + // settled. + PAYMENT_CAPTURE = 6; + + // Indicates that the transaction could not be completed because the funds + // were not settled. + PAYMENT_CAPTURE_DECLINE = 7; + + // Indicates that the transaction has been canceled. Specify the reason + // for the cancellation. For example, 'INSUFFICIENT_INVENTORY'. + CANCEL = 8; + + // Indicates that the merchant has received a chargeback inquiry due to + // fraud for the transaction, requesting additional information before a + // fraud chargeback is officially issued and a formal chargeback + // notification is sent. + CHARGEBACK_INQUIRY = 9; + + // Indicates that the merchant has received a chargeback alert due to fraud + // for the transaction. The process of resolving the dispute without + // involving the payment network is started. + CHARGEBACK_ALERT = 10; + + // Indicates that a fraud notification is issued for the transaction, sent + // by the payment instrument's issuing bank because the transaction appears + // to be fraudulent. We recommend including TC40 or SAFE data in the + // `reason` field for this event type. For partial chargebacks, we recommend + // that you include an amount in the `value` field. + FRAUD_NOTIFICATION = 11; + + // Indicates that the merchant is informed by the payment network that the + // transaction has entered the chargeback process due to fraud. Reason code + // examples include Discover's '6005' and '6041'. For partial chargebacks, + // we recommend that you include an amount in the `value` field. + CHARGEBACK = 12; + + // Indicates that the transaction has entered the chargeback process due to + // fraud, and that the merchant has chosen to enter representment. Reason + // examples include Discover's '6005' and '6041'. For partial chargebacks, + // we recommend that you include an amount in the `value` field. + CHARGEBACK_REPRESENTMENT = 13; + + // Indicates that the transaction has had a fraud chargeback which was + // illegitimate and was reversed as a result. For partial chargebacks, we + // recommend that you include an amount in the `value` field. + CHARGEBACK_REVERSE = 14; + + // Indicates that the merchant has received a refund for a completed + // transaction. For partial refunds, we recommend that you include an amount + // in the `value` field. Reason example: 'TAX_EXEMPT' (partial refund of + // exempt tax) + REFUND_REQUEST = 15; + + // Indicates that the merchant has received a refund request for this + // transaction, but that they have declined it. For partial refunds, we + // recommend that you include an amount in the `value` field. Reason + // example: 'TAX_EXEMPT' (partial refund of exempt tax) + REFUND_DECLINE = 16; + + // Indicates that the completed transaction was refunded by the merchant. + // For partial refunds, we recommend that you include an amount in the + // `value` field. Reason example: 'TAX_EXEMPT' (partial refund of exempt + // tax) + REFUND = 17; + + // Indicates that the completed transaction was refunded by the merchant, + // and that this refund was reversed. For partial refunds, we recommend that + // you include an amount in the `value` field. + REFUND_REVERSE = 18; + } + + // Optional. The type of this transaction event. + TransactionEventType event_type = 1 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. The reason or standardized code that corresponds with this + // transaction event, if one exists. For example, a CHARGEBACK event with code + // 6005. + string reason = 2 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. The value that corresponds with this transaction event, if one + // exists. For example, a refund event where $5.00 was refunded. Currency is + // obtained from the original transaction data. + double value = 3 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. Timestamp when this transaction event occurred; otherwise assumed + // to be the time of the API call. + google.protobuf.Timestamp event_time = 4 + [(google.api.field_behavior) = OPTIONAL]; +} + // The request message to annotate an Assessment. message AnnotateAssessmentRequest { // Enum that represents the types of annotations. @@ -288,6 +412,11 @@ message AnnotateAssessmentRequest { // in the initial request. It is recommended that the identifier is hashed // using hmac-sha256 with stable secret. bytes hashed_account_id = 4 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. If the assessment is part of a payment transaction, provide + // details on payment lifecycle events that occur in the transaction. + TransactionEvent transaction_event = 5 + [(google.api.field_behavior) = OPTIONAL]; } // Empty response for AnnotateAssessment. @@ -401,7 +530,7 @@ message PrivatePasswordLeakVerification { [(google.api.field_behavior) = OUTPUT_ONLY]; } -// A recaptcha assessment resource. +// A reCAPTCHA Enterprise assessment resource. message Assessment { option (google.api.resource) = { type: "recaptchaenterprise.googleapis.com/Assessment" @@ -433,15 +562,19 @@ message Assessment { // The private password leak verification field contains the parameters that // are used to to check for leaks privately without sharing user credentials. PrivatePasswordLeakVerification private_password_leak_verification = 8; + + // Assessment returned by Fraud Prevention when TransactionData is provided. + FraudPreventionAssessment fraud_prevention_assessment = 11; } +// The event being assessed. message Event { - // Optional. The user response token provided by the reCAPTCHA client-side - // integration on your site. + // Optional. The user response token provided by the reCAPTCHA Enterprise + // client-side integration on your site. string token = 1 [(google.api.field_behavior) = OPTIONAL]; - // Optional. The site key that was used to invoke reCAPTCHA on your site and - // generate the token. + // Optional. The site key that was used to invoke reCAPTCHA Enterprise on your + // site and generate the token. string site_key = 2 [(google.api.field_behavior) = OPTIONAL]; // Optional. The user agent present in the request from the user's device @@ -460,6 +593,149 @@ message Event { // Optional. Unique stable hashed user identifier for the request. The // identifier must be hashed using hmac-sha256 with stable secret. bytes hashed_account_id = 6 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. Data describing a payment transaction to be assessed. Sending + // this data enables reCAPTCHA Enterprise Fraud Prevention and the + // FraudPreventionAssessment component in the response. + TransactionData transaction_data = 13 + [(google.api.field_behavior) = OPTIONAL]; +} + +// Transaction data associated with a payment protected by reCAPTCHA Enterprise. +// All fields are optional. +message TransactionData { + // Structured address format for billing and shipping addresses. + message Address { + // The recipient name, potentially including information such as "care of". + string recipient = 1; + + // The first lines of the address. The first line generally contains the + // street name and number, and further lines may include information such as + // an apartment number. + repeated string address = 2; + + // The town/city of the address. + string locality = 3; + + // The state, province, or otherwise administrative area of the address. + string administrative_area = 4; + + // The CLDR country/region of the address. + string region_code = 5; + + // The postal or ZIP code of the address. + string postal_code = 6; + } + + // Details about a user's account involved in the transaction. + message User { + // Unique account identifier for this user. If using account defender, + // this should match the hashed_account_id field. Otherwise, a unique and + // persistent identifier for this account. + string account_id = 6; + + // The epoch milliseconds of the user's account creation. + int64 creation_ms = 1; + + // The email address of the user. + string email = 2; + + // Whether the email has been verified to be accessible by the user (OTP or + // similar). + bool email_verified = 3; + + // The phone number of the user, with country code. + string phone_number = 4; + + // Whether the phone number has been verified to be accessible by the user + // (OTP or similar). + bool phone_verified = 5; + } + + // Line items being purchased in this transaction. + message Item { + // The full name of the item. + string name = 1; + + // The value per item that the user is paying, in the transaction currency, + // after discounts. + double value = 2; + + // The quantity of this item that is being purchased. + int64 quantity = 3; + + // When a merchant is specified, its corresponding account_id. Necessary to + // populate marketplace-style transactions. + string merchant_account_id = 4; + } + + // Details about the transaction from the gateway. + message GatewayInfo { + // Name of the gateway service (for example, stripe, square, paypal). + string name = 1; + + // Gateway response code describing the state of the transaction. + string gateway_response_code = 2; + + // AVS response code from the gateway + // (available only when reCAPTCHA Enterprise is called after authorization). + string avs_response_code = 3; + + // CVV response code from the gateway + // (available only when reCAPTCHA Enterprise is called after authorization). + string cvv_response_code = 4; + } + + // Unique identifier for the transaction. This custom identifier can be used + // to reference this transaction in the future, for example, labeling a refund + // or chargeback event. Two attempts at the same transaction should use the + // same transaction id. + optional string transaction_id = 11; + + // The payment method for the transaction. The allowed values are: + // + // * credit-card + // * debit-card + // * gift-card + // * processor-{name} (If a third-party is used, for example, + // processor-paypal) + // * custom-{name} (If an alternative method is used, for example, + // custom-crypto) + string payment_method = 1; + + // The Bank Identification Number - generally the first 6 or 8 digits of the + // card. + string card_bin = 2; + + // The last four digits of the card. + string card_last_four = 3; + + // The currency code in ISO-4217 format. + string currency_code = 4; + + // The decimal value of the transaction in the specified currency. + double value = 5; + + // The value of shipping in the specified currency. 0 for free or no shipping. + double shipping_value = 12; + + // Destination address if this transaction involves shipping a physical item. + Address shipping_address = 6; + + // Address associated with the payment method when applicable. + Address billing_address = 7; + + // Information about the user paying/initiating the transaction. + User user = 8; + + // Information about the user or users fulfilling the transaction. + repeated User merchants = 13; + + // Items purchased in this transaction. + repeated Item items = 14; + + // Information about the payment gateway's response to the transaction. + GatewayInfo gateway_info = 10; } // Risk analysis result for an event. @@ -485,6 +761,12 @@ message RiskAnalysis { // Too little traffic has been received from this site thus far to generate // quality risk analysis. LOW_CONFIDENCE_SCORE = 5; + + // The request matches behavioral characteristics of a carding attack. + SUSPECTED_CARDING = 6; + + // The request matches behavioral characteristics of chargebacks for fraud. + SUSPECTED_CHARGEBACK = 7; } // Legitimate event score from 0.0 to 1.0. @@ -496,6 +778,7 @@ message RiskAnalysis { repeated ClassificationReason reasons = 2; } +// Properties of the provided event token. message TokenProperties { // Enum that represents the types of invalid token reasons. enum InvalidReason { @@ -550,6 +833,36 @@ message TokenProperties { string action = 5; } +// Assessment for Fraud Prevention. +message FraudPreventionAssessment { + // Information about stolen instrument fraud, where the user is not the + // legitimate owner of the instrument being used for the purchase. + message StolenInstrumentVerdict { + // Probability (0-1) of this transaction being executed with a stolen + // instrument. + float risk = 1; + } + + // Information about card testing fraud, where an adversary is testing + // fraudulently obtained cards or brute forcing their details. + message CardTestingVerdict { + // Probability (0-1) of this transaction attempt being part of a card + // testing attack. + float risk = 1; + } + + // Probability (0-1) of this transaction being fraudulent. Summarizes the + // combined risk of attack vectors below. + float transaction_risk = 1; + + // Assessment of this transaction for risk of a stolen instrument. + StolenInstrumentVerdict stolen_instrument_verdict = 2; + + // Assessment of this transaction for risk of being part of a card testing + // attack. + CardTestingVerdict card_testing_verdict = 3; +} + // Account defender risk assessment. message AccountDefenderAssessment { // Labels returned by account defender for this request. @@ -770,8 +1083,9 @@ message Key { // Creating and managing labels. map labels = 6; - // The timestamp corresponding to the creation of this Key. - google.protobuf.Timestamp create_time = 7; + // Output only. The timestamp corresponding to the creation of this Key. + google.protobuf.Timestamp create_time = 7 + [(google.api.field_behavior) = OUTPUT_ONLY]; // Options for user acceptance testing. TestingOptions testing_options = 9; @@ -1110,4 +1424,4 @@ message WafSettings { // Required. The WAF feature for which this key is enabled. WafFeature waf_feature = 2 [(google.api.field_behavior) = REQUIRED]; -} \ No newline at end of file +} diff --git a/google/cloud/recaptchaenterprise/v1/recaptchaenterprise_v1.yaml b/google/cloud/recaptchaenterprise/v1/recaptchaenterprise_v1.yaml index ed7fab727c67a..8cebd57a92c2e 100644 --- a/google/cloud/recaptchaenterprise/v1/recaptchaenterprise_v1.yaml +++ b/google/cloud/recaptchaenterprise/v1/recaptchaenterprise_v1.yaml @@ -21,3 +21,10 @@ authentication: publishing: organization: CLIENT_LIBRARY_ORGANIZATION_UNSPECIFIED + new_issue_uri: '' + documentation_uri: '' + api_short_name: '' + github_label: '' + doc_tag_prefix: '' + codeowner_github_teams: + library_settings: