recaptcha-node

A Node.js library to verify reCAPTCHA v2/v3 response tokens received from a client.

GitHub | NPM

Install

npm install recaptcha-node

Usage

Importing

If you are using reCAPTCHA v2, import the RecaptchaV2 class.

const {RecaptchaV2} = require('recaptcha-node');

If you are using reCAPTCHA v3, import the RecaptchaV3 class.

const {RecaptchaV3} = require('recaptcha-node');

Verifying a Response Token

To verify a response token using either RecaptchaV2 or RecaptchaV3, call the verify method.

The verify method's signature on RecaptchaV2 and RecaptchaV3 is nearly identical, differing only in the return value. RecaptchaV2's verify method returns an instance of RecaptchaV2Result, and RecaptchaV3's verify method returns an instance of RecaptchaV3Result.

const {RecaptchaV2} = require('recaptcha-node');

const recaptchaV2 = new RecaptchaV2('secretKey');

recaptchaV2.verify('responseToken')
.then(result => {
  if (result.success) {
    // reCAPTCHA response was valid.
  }
  else {
    // reCAPTCHA response was invalid.
  }
})
.catch(error =>  {
  // Request failed.
});

Configuration

The RecaptchaV2 and RecaptchaV3 classes can be initialized with an options object as the second argument.

const {RecaptchaV3} = require('recaptcha-node');

const recaptchaV3 = new RecaptchaV3('secretKey', {
  hostname: 'google.com',
  port: 443,
  protocol: 'https',
  timeout: 30 * 1000,
});

Name	Default	Description
agent	undefined
hostname	google.com	Hostname that requests are made to
port	80 if protocol is 'http', 443 if protocol is 'https'	Port that requests are made to
protocol	'https'	'https' or 'http'
timeout	30000	Milliseconds before a request times out. Setting to 0 will prevent the request from ever timing out

Objects

RecaptchaV2Result

Property	Type	Optional	Description
success	boolean	false	Whether this request was a valid reCAPTCHA token for your site
challengeTimestamp	Date	false	Timestamp of the challenge load
apkPackageName	string	true	The package name of the app where the reCAPTCHA was solved
hostname	string	true	The hostname of the site where the reCAPTCHA was solved
errorCodes	string[]	true

RecaptchaV3Result

Property	Type	Optional	Description
success	boolean	false	Whether this request was a valid reCAPTCHA token for your site
score	number	false	The score for this request (0.0 - 1.0)
action	string	false	The action name for this request
challengeTimestamp	Date	false	Timestamp of the challenge load
hostname	string	false	The hostname of the site where the reCAPTCHA was solved
errorCodes	string[]	true