| name | recaptcha-transaction-defense-integrator |
| description | Integrates reCAPTCHA Enterprise Transaction Defense and automates ground truth via PSP chargeback webhooks (Stripe, Adyen). Use when a user wants to protect transactions from fraud and close the feedback loop with automated annotations. Don't use for generic reCAPTCHA v2 checkbox integrations or non-transactional bot protection. |
reCAPTCHA Transaction Defense Integrator
This skill helps you integrate reCAPTCHA Transaction Defense into your Node.js
application and automate the "ground truth" feedback loop by listening to
chargeback notifications from Payment Service Providers (PSPs) like Stripe and
Adyen.
Prerequisites
- Google Cloud Project: reCAPTCHA Enterprise must be enabled. The Fraud
Prevention feature must also be enabled in the reCAPTCHA settings for the
project.
- Authentication: Your server must be authenticated to Google Cloud. The
easiest way is to set the
GOOGLE_APPLICATION_CREDENTIALS environment
variable pointing to a downloaded Service Account JSON key.
- IAM Roles: The authenticated Service Account requires the
reCAPTCHA Enterprise Agent (roles/recaptchaenterprise.agent) role to create and
annotate assessments. During the execution of this agent skill,
roles/logging.viewer is required so that the skill can automatically
validate the success of implementation.
- Environment Separation: Create two reCAPTCHA keys: one for Test
(allowed domains:
localhost, 127.0.0.1) and one for Prod (your real
domain). Map these to environment variables (e.g., RECAPTCHA_SITE_KEY_TEST
and RECAPTCHA_SITE_KEY_PROD) to avoid "Invalid Domain" errors during
development.
- Node.js Dependencies: Run
npm install @google-cloud/recaptcha-enterprise to install the required client library.
Workflows
1. Integrate reCAPTCHA
First check if the user is using a V3 key. This skill so far only supports the
V3 integration.
Codebase Survey: Passively inspect the user's codebase and dependencies
(package.json, environment files, structure) to understand: 1. Frontend
Framework: React, Vue, Angular, or Vanilla JS? 2. State Management: How is
form state handled? 3. Entry Point: Where is the best place to inject the
<script> tag? 4. Secrets Management: Determine how the backend application
manages secrets (e.g., .env, Secret Manager). Adapt the secret loading when
injecting the integration logic to match this pattern.
Then use v3.md to understand common integration gotchas.
Action: Read the text in assets/frontend-snippets.html and
assets/frontend-snippets.js. Instruction: Inject those snippets directly
into the user's existing frontend code, adapting them on the fly to match the
discovered Framework and State Management patterns.
2. Integrate Transaction Protection (Best Practice: Multi-Stage)
Protecting a transaction is most effective when done in two stages:
- Stage 1: Initial Frontend Assessment: Collect the reCAPTCHA token on the
frontend (using
enterprise.js) and send it to your backend. Perform a
createAssessment with the token and user identifiers (email). Block bots
and high-risk requests immediately.
- Stage 2: Post-Authorization Enriched Assessment: Use a Payment Service
Provider (PSP) like Stripe with manual capture. After the user
authorizes the payment, use the webhook to retrieve real card data (last 4
digits, billing zip). Perform a second
createAssessment with this
enriched data to catch "stolen instrument" fraud before capturing funds.
Codebase Survey (Database & Architecture): You must store the
assessmentName or reCAPTCHA token to close the loop later. 1. Architecture
Check: Is the payment processing in the same service as the frontend serving?
If separated (Microservices), ensure you identify how to pass the
transactionId across the boundary. 2. Schema Check: Identify the
Database Schema and ORM (e.g., Prisma, Sequoia, TypeORM). *
CRITICAL: assessmentName can be long. Use VARCHAR(255) or TEXT.
Converting it to a standard UUID column (36 chars) will cause truncation and
failures. 3. Mapping Strategy: Determine where to store the transactionId
<-> assessmentName mapping.
CRITICAL WARNING: Token Storage Do NOT store the reCAPTCHA token in
Stripe's metadata field. The token is often larger than 2000 characters,
which exceeds Stripe's 500-character limit for metadata values, causing the
request to fail.
Solution: 1. Generate a unique transactionId on your server. 2. Store
the token in a server-side store (e.g., Redis, Database, or in-memory map)
using the transactionId as the key. 3. Pass only the transactionId in the
Stripe metadata. 4. In your webhook, retrieve the token using the
transactionId from the metadata.
Reference: See recaptcha-api.md for
request/response schemas and the expectedAction requirement.
Action: Read assets/recaptcha-integration.js and generate an equivalent
Node.js integration within the user's backend codebase.
Note: The template uses placeholders (e.g., 'YOUR_PROJECT_ID'). You must
manually wire these to the user's environment variables (e.g.,
process.env.CLOUD_PROJECT_ID).
Wiring: 1. Import the generated recaptcha-integration.js in your payment
processing route. 2. Call createAssessment before authorizing the charge
with your PSP.
Best Practice: Adopt a Fail Open strategy. If the reCAPTCHA API fails or
returns an error (other than a fraudulent verdict), allow the transaction to
proceed to avoid blocking legitimate users during outages. (The generated code
includes a try/catch block for this purpose).
3. Automate Ground Truth & Feedback Loop
The reCAPTCHA model improves when you provide feedback:
- Annotate: When a transaction is confirmed as legitimate or fraudulent
(e.g., via a chargeback), call
annotateAssessment.
- Webhooks: Map PSP events (like Stripe's
charge.dispute.created) to the
original reCAPTCHA assessment name.
Reference: See psp-webhooks.md for
PSP-specific webhook handling.
Action: Determine if the user is using stripe or adyen by reading
package.json. Read the corresponding template (assets/webhook-stripe.js or
assets/webhook-adyen.js) and inject the endpoint into their backend.
Note: If neither are detected directly in package.json (e.g., wrapped
via another library), look for imports or environment variables containing
"Stripe", "Adyen", or "Payment" to identify the integration point manually
before proceeding.
4. Verify Integration Health & End-to-End Test
Step 1: Metric Check To confirm that your keys are active and receiving
traffic, query the reCAPTCHA Enterprise API for metrics. Action: Read
assets/check-status.js. Create this script temporarily in their workspace and
execute it via node (ensuring environment variables are populated). Review the
outputs and delete the script.
Step 2: Logic Verification (Unit Test) Verify your integration logic handles
good, bad, and invalid tokens correctly without needing real traffic.
Action: Read assets/verify-logic.js. Create a temporary verification
script with the contents in the user's workspace, modifying the
require('./recaptcha-integration') line to match wherever you injected the
integration module in the previous step. Execute it via node, then delete it.
This checks the createAssessment function against various scenarios (high
score, low score, wrong action).
Step 3: End-to-End Transaction Test (Mandatory) Do not consider the task
complete until you have verified the full flow: 1. Frontend: Load the page,
check browser console for reCAPTCHA token generation. 2. Backend: Process a
test transaction (e.g., using Stripe Test Mode card numbers). 3. Logs: Check
server logs to confirm createAssessment was called and returned a verdict. 4.
Webhook (Optional): Trigger a test dispute in the PSP dashboard and verify
your webhook receives it.
Resources
- API Documentation: recaptcha-api.md
- PSP Webhooks Guide: psp-webhooks.md
- Integration Asset:
assets/recaptcha-integration.js
- Frontend Assets:
assets/frontend-snippets.html,
assets/frontend-snippets.js
- Verification Asset:
assets/verify-logic.js
- Webhook Assets:
assets/webhook-stripe.js, assets/webhook-adyen.js
- Status Check Asset:
assets/check-status.js
