Method: projects.assessments.annotate

Annotates a previously created Assessment to provide additional information on whether the event turned out to be authentic or fraudulent.

HTTP request

POST https://recaptchaenterprise.googleapis.com/v1/{name=projects/*/assessments/*}:annotate

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
name

string

Required. The resource name of the Assessment, in the format projects/{project}/assessments/{assessment}.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "annotation": enum (Annotation),
  "reasons": [
    enum (Reason)
  ],
  "accountId": string,
  "hashedAccountId": string,
  "transactionEvent": {
    object (TransactionEvent)
  }
}
Fields
annotation

enum (Annotation)

Optional. The annotation that is assigned to the Event. This field can be left empty to provide reasons that apply to an event without concluding whether the event is legitimate or fraudulent.
reasons[]

enum (Reason)

Optional. Reasons for the annotation that are assigned to the event.
accountId

string

Optional. A stable account identifier to apply to the assessment. This is an alternative to setting accountId in assessments.create, for example when a stable account identifier is not yet known in the initial request.
hashedAccountId

string (bytes format)

Optional. A stable hashed account identifier to apply to the assessment. This is an alternative to setting hashedAccountId in assessments.create, for example when a stable account identifier is not yet known in the initial request.

A base64-encoded string.
transactionEvent

object (TransactionEvent)

Optional. If the assessment is part of a payment transaction, provide details on payment lifecycle events that occur in the transaction.

Response body

If successful, the response body is empty.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the name resource:

  • recaptchaenterprise.assessments.annotate

For more information, see the IAM documentation.

Annotation

Enum that represents the types of annotations.

Enums
ANNOTATION_UNSPECIFIED Default unspecified type.
LEGITIMATE Provides information that the event turned out to be legitimate.
FRAUDULENT Provides information that the event turned out to be fraudulent.
PASSWORD_CORRECT

Provides information that the event was related to a login event in which the user typed the correct password. Deprecated, prefer indicating CORRECT_PASSWORD through the reasons field instead.
PASSWORD_INCORRECT

Provides information that the event was related to a login event in which the user typed the incorrect password. Deprecated, prefer indicating INCORRECT_PASSWORD through the reasons field instead.

Reason

Enum that represents potential reasons for annotating an assessment.

Enums
REASON_UNSPECIFIED Default unspecified reason.
CHARGEBACK Indicates that the transaction had a chargeback issued with no other details. When possible, specify the type by using CHARGEBACK_FRAUD or CHARGEBACK_DISPUTE instead.
CHARGEBACK_FRAUD Indicates that the transaction had a chargeback issued related to an alleged unauthorized transaction from the cardholder's perspective (for example, the card number was stolen).
CHARGEBACK_DISPUTE Indicates that the transaction had a chargeback issued related to the cardholder having provided their card details but allegedly not being satisfied with the purchase (for example, misrepresentation, attempted cancellation).
REFUND Indicates that the completed payment transaction was refunded by the seller.
REFUND_FRAUD Indicates that the completed payment transaction was determined to be fraudulent by the seller, and was cancelled and refunded as a result.
TRANSACTION_ACCEPTED Indicates that the payment transaction was accepted, and the user was charged.
TRANSACTION_DECLINED Indicates that the payment transaction was declined, for example due to invalid card details.
PAYMENT_HEURISTICS Indicates the transaction associated with the assessment is suspected of being fraudulent based on the payment method, billing details, shipping address or other transaction information.
INITIATED_TWO_FACTOR Indicates that the user was served a 2FA challenge. An old assessment with ENUM_VALUES.INITIATED_TWO_FACTOR reason that has not been overwritten with PASSED_TWO_FACTOR is treated as an abandoned 2FA flow. This is equivalent to FAILED_TWO_FACTOR.
PASSED_TWO_FACTOR Indicates that the user passed a 2FA challenge.
FAILED_TWO_FACTOR Indicates that the user failed a 2FA challenge.
CORRECT_PASSWORD Indicates the user provided the correct password.
INCORRECT_PASSWORD Indicates the user provided an incorrect password.
SOCIAL_SPAM Indicates that the user sent unwanted and abusive messages to other users of the platform, such as spam, scams, phishing, or social engineering.

TransactionEvent

Describes an event in the lifecycle of a payment transaction.

JSON representation 
{
  "eventType": enum (TransactionEventType),
  "reason": string,
  "value": number,
  "eventTime": string
}
Fields
eventType

enum (TransactionEventType)

Optional. The type of this transaction event.
reason

string

Optional. The reason or standardized code that corresponds with this transaction event, if one exists. For example, a CHARGEBACK event with code 6005.
value

number

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.
eventTime

string (Timestamp format)

Optional. Timestamp when this transaction event occurred; otherwise assumed to be the time of the API call.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

TransactionEventType

Enum that represents an event in the payment transaction lifecycle.

Enums
TRANSACTION_EVENT_TYPE_UNSPECIFIED Default, unspecified event type.
MERCHANT_APPROVE Indicates that the transaction is approved by the merchant. The accompanying reasons can include terms such as 'INHOUSE', 'ACCERTIFY', 'CYBERSOURCE', or 'MANUAL_REVIEW'.
MERCHANT_DENY 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'.
MANUAL_REVIEW Indicates that the transaction is being evaluated by a human, due to suspicion or risk.
AUTHORIZATION Indicates that the authorization attempt with the card issuer succeeded.
AUTHORIZATION_DECLINE 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.
PAYMENT_CAPTURE Indicates that the transaction is completed because the funds were settled.
PAYMENT_CAPTURE_DECLINE Indicates that the transaction could not be completed because the funds were not settled.
CANCEL Indicates that the transaction has been canceled. Specify the reason for the cancellation. For example, 'INSUFFICIENT_INVENTORY'.
CHARGEBACK_INQUIRY 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_ALERT 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.
FRAUD_NOTIFICATION 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.
CHARGEBACK 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_REPRESENTMENT 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_REVERSE 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.
REFUND_REQUEST 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_DECLINE 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 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_REVERSE 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.