- HTTP request
- Path parameters
- Request body
- Response body
- Authorization scopes
- Annotation
- Reason
- TransactionEvent
- TransactionEventType
Annotates a previously created Assessment to provide additional information on whether the event turned out to be authentic or fradulent.
HTTP request
POST https://recaptchaenterprise.googleapis.com/v1beta1/{name=projects/*/assessments/*}:annotate
The URL uses gRPC Transcoding syntax.
Path parameters
Parameters | |
---|---|
name |
Required. The resource name of the Assessment, in the format |
Request body
The request body contains data with the following structure:
JSON representation |
---|
{ "annotation": enum ( |
Fields | |
---|---|
annotation |
Optional. The annotation that will be 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[] |
Optional. Reasons for the annotation that are assigned to the event. |
hashedAccountId |
Optional. Unique stable hashed user identifier to apply to the assessment. This is an alternative to setting the A base64-encoded string. |
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.
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 ( |
Fields | |
---|---|
eventType |
Optional. The type of this transaction event. |
reason |
Optional. The reason or standardized code that corresponds with this transaction event, if one exists. For example, a CHARGEBACK event with code 6005. |
value |
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 |
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: |
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. |