This page describes how to effectively protect payment transactions against attacks, such as carding, stolen instrument fraud, and account takeover payment fraud by using reCAPTCHA Enterprise Fraud Prevention.
reCAPTCHA Enterprise Fraud Prevention helps you protect payment transactions by identifying targeted manual attacks and scaled fraud attempts. It automatically trains behavior and transaction models to identify events that are likely fraudulent and can result in a dispute or chargeback if accepted.
As part of these models, reCAPTCHA Enterprise Fraud Prevention examines transaction signals to enable detection of fraud. For example, a series of purchase attempts with low prices might indicate a carding attack. In the response, you receive risk scores for different types of fraud, which you can use to send the transaction to a manual review, or directly block sufficiently suspicious transactions.
To set up reCAPTCHA Enterprise Fraud Prevention, complete the following steps:
Install reCAPTCHA Enterprise on your payment frontend.
Create assessments with transaction data.
Annotate assessments with transaction events.
Interpret responses to take action on potential fraud.
Before you begin
Review the pricing information for reCAPTCHA Enterprise Fraud Prevention.
Confirm that your integration supports tokens larger than 8 KB. reCAPTCHA Enterprise Fraud Prevention might use larger tokens, so confirm that they are sent in POST requests rather than GET, and in the body, not in a header.
Install reCAPTCHA Enterprise on your payment frontend
To start detecting attacks, install a score-based key on each page in your
payment user flow. This includes the interface where a user reviews their cart,
selects their payment method, and completes the purchase. After the user has
made their selection at each step, call grecaptcha.enterprise.execute()
to
generate a token. To learn how to install score-based keys and call
execute()
, see Install score-based keys.
The following example shows how to integrate a score-based key on a credit card transaction event.
function submitForm() { grecaptcha.enterprise.ready(function() { grecaptcha.enterprise.execute( 'reCAPTCHA_site_key', {action: 'purchase'}).then(function(token) { document.getElementById("token").value = token; document.getElementByID("paymentForm").submit(); }); }); }
<form id="paymentForm" action="?" method="POST"> Total: $1.99 Credit Card Number: <input name="cc-number" id="cc-number" autocomplete="cc-number"><br/> <input type="hidden" id="token" name="recaptcha_token"/> <button onclick="submitForm()">Purchase</button> </form>
<script src="https://www.google.com/recaptcha/enterprise.js" async defer></script>
You can experiment with this code in JSFiddle by clicking the <>
icon in the
top-right corner of the code window.
<html> <head> <title>Protected Payment</title> <script src="https://www.google.com/recaptcha/enterprise.js" async defer></script> <script> function submitForm() { grecaptcha.enterprise.ready(function() { grecaptcha.enterprise.execute( 'reCAPTCHA_site_key', {action: 'purchase'}).then(function(token) { document.getElementById("token").value = token; document.getElementByID("paymentForm").submit(); }); }); } </script> </head> <body> <form id="paymentForm" action="?" method="POST"> Total: $1.99 Credit Card Number: <input name="cc-number" id="cc-number" autocomplete="cc-number"><br/> <input type="hidden" id="token" name="recaptcha_token"/> <button onclick="submitForm()">Purchase</button> </form> </body> </html>
Create an assessment with transaction data
To enable payment fraud verdicts, create assessments with transaction data by using the additional fields in the projects.assessments.create method. For you to use this feature, Google must enable it for your organization. To request access to this feature, contact us.
The simplest integration includes the transaction ID, payment method, currency, and transaction value.
{ "event": { "token": "YOUR_TOKEN", "site_key": "KEY_ID", "expected_action": "YOUR_CHECKOUT_ACTION_NAME", "transaction_data": { "transaction_id": "txid-1234567890", "payment_method": "credit-card", "card_bin": "411111", "card_last_four": "1234", "currency_code": "USD", "value": 39.98, } } }
The following fields are optional, but we recommend providing these fields to improve the quality of fraud detection.
{ "event": { "token": "YOUR_TOKEN", "site_key": "KEY_ID", "expected_action": "YOUR_CHECKOUT_ACTION_NAME", "transaction_data": { "transaction_id": "txid-1234567890", "payment_method": "credit-card", "card_bin": "411111", "card_last_four": "1234", "currency_code": "USD", "value": 39.98, "shipping_value": 7.99, "shipping_address": { "recipient": "name1 name2", "address": "123 Street Name", "address": "Apt 1", "locality": "Sunnyvale", "administrative_area": "CA", "region_code": "USA", "postal_code": "123456" }, "billing_address": { "recipient": "name1 name2", "address": "123 Street Name", "address": "Apt 1", "locality": "Sunnyvale", "administrative_area": "CA", "region_code": "USA", "postal_code": "123456" }, "user": { "account_id": "abcde12345", "creation_ms": 1650000000000, "email": "user@example.com", "email_verified": true, "phone_number": "+16502530000", "phone_verified" false }, "merchant": { "account_id": "abcde12345", "creation_ms": 1650000000000, "email": "user@example.com", "email_verified": true, "phone_number": "+16502530000", "phone_verified": false }, "items": { "name": "first item", "value": 19.99, "quantity": 1, "merchant_account_id": "abcde12345", }, "items": { "name": "second item", "value": 19.99, "quantity": 1, "merchant_account_id": "abcde12345", }, "gateway_info": { "name": "google", "gateway_response_code": "SUCCESS", "avs_response_code": "Y", "cvv_response_code": "Y", } } } }
To learn about how to create assessments, see Create an assessment for your website.
Annotate assessments with transaction events
For best performance, reCAPTCHA Enterprise Fraud Prevention needs visibility into payment lifecycle events for transactions. Therefore, you must send annotations for the assessments that you created with transaction data. For example, you must provide the transaction information to reCAPTCHA Enterprise 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 Enterprise Fraud Prevention returns a verdict and an
assessment_id
. 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 could not 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 } }
Interpret assessments
After you start sending the transaction data, you see the
fraudPreventionAssessment
component in the riskAnalysis
response.
The fraudPreventionAssessment
component includes a transaction risk score, and
multiple fraud scores that identify different types of attacks.
The reCAPTCHA Enterprise Fraud Prevention transactionRisk
score ranges
from 0.0 to 1.0, summarizing the risk associated with this transaction from the
components below. The risk score 0.0 indicates that the risk is low and the
transaction is likely legitimate, and 1.0 indicates that the risk is high and
the interaction is likely fraudulent.
By installing reCAPTCHA Enterprise Fraud Prevention and adding
the TransactionData
component, you get access to the cardTestingVerdict
value, which detects adversaries using your website to test lists of stolen
instruments or brute force information. When they succeed, this results in
losses for your business.
You also get access to the behavioralTrustVerdict
value, which indicates
trust of a session based on behavioral signals on your site and across the
internet. This score is particularly helpful if you use an existing fraud engine
and you want to reduce false positives. Since this score includes unique and
orthogonal information to conventional detection based on transaction data, it
is effective at adding confidence in certain otherwise risky or neutral
transactions.
After you send lifecycle events including chargeback information, you get access
to the stolenInstrumentVerdict
value. This detects attacks even at very low
scale that are likely to be fraudulent based on the signals that
reCAPTCHA Enterprise analyzes on the transaction and on the user's behavior
across the network of millions of websites.
Access to the additional scores (stolen instrument risk, card testing risk) is enabled after a security review. Contact our sales team to initiate the security review.
The following block shows an example response with the transactionRisk
,
cardTestingVerdict
, stolenInstrumentVerdict
, and behavioralTrustVerdict
values.
"riskAnalysis": { "score": "BOT_SCORE" } "fraudPreventionAssessment": { "transactionRisk": 0.9, "stolenInstrumentVerdict": { "risk": 0.7 }, "cardTestingVerdict": { "risk": 1.0 } "behavioralTrustVerdict": { "trust": 0.0 } }
You are responsible for the actions you take based on the assessment.
For the simplest integration, you can set thresholds on the top level
transactionRisk
to contribute to your decision. For example, it can
contribute to sending to a manual review or directly rejecting likely fraudulent
transactions. You can also use these scores in your own fraud workflows, or as
part of rules with your existing system. Because reCAPTCHA Enterprise
examines different signals and has a different visibility of behavior, you can
expect incremental value even with an already mature detection engine.
What's next
- To learn about user accounts protection features, see User accounts protection features.