Annotate assessments with transaction events

This page describes how to annotate assessments with transaction events to refine your site-specific model.

For best performance, reCAPTCHA Fraud Prevention needs visibility into payment lifecycle events for transactions. Therefore, we recommend that you send annotations for the assessments that you created with transaction data. For example, you can provide the transaction information to reCAPTCHA Fraud Prevention as a transaction event in the following scenarios:

  • The payment provider accepts or declines the transaction.

  • The merchant issues a refund.

  • The payment issuer files a refund.

To learn more about how to send annotations, see Annotate assessments.

We recommend that you make these requests automatically as part of the corresponding logic in your system when the data is available, such as when the status of a transaction changes.

After you create an assessment with included transaction data, reCAPTCHA Fraud Prevention returns a verdict and an assessment name. Annotate the assessment with transaction events at the following important stages in the payment lifecycle when they occur:

Event type Description Reason example Value example
MERCHANT_APPROVE | MERCHANT_DENY When you decide whether the transaction should be allowed to proceed. IN_HOUSE N/A
AUTHORIZATION | AUTHORIZATION_DECLINE When you submit the transaction to be processed, and the card issuer decides whether to allow the transaction to proceed. 82 (a reason code meaning that the CVV was incorrect) N/A
CHARGEBACK When the transaction is charged back. Card Reported Stolen 20 (representing a partial chargeback of 20 units of currency)

Along with the CHARGEBACK event type, include the chargeback reason code that was provided by the card issuer by using the reason field. Also, include the monetary amount charged back in the value field if the transaction was partially charged back.

In the transaction event reason field, either include clarifying terms to provide more context on the reason for the event, or provide reason codes that are obtained directly from the payment network or card issuer. These terms and codes differ depending on the event type.

The following table specifies the complete list of transaction event types:

Annotation reason Description
MERCHANT_APPROVE Indicates that the transaction is approved by the merchant. The accompanying reasons can include terms such as IN_HOUSE, 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 IN_HOUSE, 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 couldn't be completed because the funds were not settled.
CANCEL Indicates that the transaction is 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: FRAUD.
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: FRAUD.
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: PROACTIVE_FRAUD.
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.

The following example shows a sample annotation payload containing a transaction event. For more details, see Annotate assessments.

POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate
{
  "transaction_event": {
    "event_type": "CHARGEBACK",
    "reason": "Card Reported Stolen",
    "value": 20
  }
}

What's next