recaptcha3

README

go-playground-recaptcha3-validator

go-playground-recaptcha3-validator is a custom validator for playground implementing Google reCAPTCHA v3 validation.

Installation

go get github.com/rgglez/go-playground-recaptcha3-validator

Usage

First import the module:

import (
   recaptcha3 "github.com/rgglez/go-playground-recaptcha3-validator"
)

This is a sample structure to validate:

// Struct to bind and validate
type ContactForm struct {
	Name           string `json:"name" validate:"required"`
	Email          string `json:"email" validate:"required,email"`
	RecaptchaToken string `json:"recaptcha_token" validate:"required,recaptcha"`
}

Set it up:

// Load reCAPTCHA secret
secret := os.Getenv("RECAPTCHA3_SECRET_KEY") // this is just a sample name
if secret == "" {
    fmt.Println("Missing RECAPTCHA3_SECRET_KEY env variable")
    os.Exit(1)
}

// Create Google verifier
verifier, err := recaptcha3.NewGoogleVerifier(recaptcha3.Config{
    Secret:         secret,
    ExpectedAction: "contact",
    MinScore:       0.5,
})
if err != nil {
    panic(err)
}

// Set up validator
validate := validator.New()
err = recaptcha3.RegisterRecaptchaValidator(validate, "recaptcha", verifier)
if err != nil {
    panic(err)
}

Call it in your handler:

if err := validate.Struct(form); err != nil {
    return c.Status(fiber.StatusUnprocessableEntity).JSON(fiber.Map{
        "error": err.Error(),
    })
}

See the real example.

Configuration

• Secret the secret key for reCAPTCHA v3. Required.
• ExpectedAction a string specifying the expected action. For example: "login" or "contact".
• MinScore a float value specifying the lowest acceptable score for the reCAPTCHA validation.
• HTTPClient a pointer to an optional http.Client object

Examples

Two examples are provided:

• mock for testing (it does not contact Google's servers).
• real to try the validator, using the sample web page. You need to copy that webpage (or create a similar) to your web server, and use your own site key.

Dependencies

• go get github.com/go-playground/validator/v10

Security

• Remember that reCAPTCHA v3 does not stops bots directly, but just gives a risk score. It is responsability of the application to accept the request or deny it.
• Another captcha (such as reCAPTCHA v2) could be shown with a classic challenge as a "plan B", if the score is lower than expected.

License

Copyright (c) 2026 Rodolfo González González

Licensed under the Apache 2.0 license. Read the LICENSE file.

Documentation

Index

• func RegisterRecaptchaValidator(v *validator.Validate, fieldTag string, verifier Verifier) error
• type Config
• type GoogleVerifier
  • func NewGoogleVerifier(cfg Config) (*GoogleVerifier, error)
  • func (g *GoogleVerifier) Verify(token string) (bool, error)
• type MockVerifier
  • func (m *MockVerifier) Verify(token string) (bool, error)
• type RecaptchaResponse
• type RestyConfig
• type Verifier

Functions

func RegisterRecaptchaValidator

func RegisterRecaptchaValidator(v *validator.Validate, fieldTag string, verifier Verifier) error

Types

type Config

type Config struct {
	// The secret key for reCAPTCHA v3. Required.
	Secret string

	// A string indicating the expected action. For example: "login" or "contact".
	ExpectedAction string

	// The lowest acceptable score for the reCAPTCHA validation.
	MinScore float64

	// Optional Resty client
	Client *resty.Client
}

Config holds the parameters to build a real verifier

type GoogleVerifier

type GoogleVerifier struct {
	Secret         string
	ExpectedAction string
	MinScore       float64
	Client         *resty.Client
}

func NewGoogleVerifier

func NewGoogleVerifier(cfg Config) (*GoogleVerifier, error)

func (*GoogleVerifier) Verify

func (g *GoogleVerifier) Verify(token string) (bool, error)

type MockVerifier

type MockVerifier struct {
	ShouldPass bool
	Err        error
}

func (*MockVerifier) Verify

func (m *MockVerifier) Verify(token string) (bool, error)

type RecaptchaResponse

type RecaptchaResponse struct {
	Success     bool     `json:"success"`
	ChallengeTS string   `json:"challenge_ts"`
	Hostname    string   `json:"hostname"`
	Score       float64  `json:"score"`
	Action      string   `json:"action"`
	ErrorCodes  []string `json:"error-codes"`
}

reCAPTCHA response

type RestyConfig

type RestyConfig struct {
	RetryCount       int
	RetryWaitTime    int
	RetryMaxWaitTime int
}

type Verifier

type Verifier interface {
	Verify(token string) (bool, error)
}

Verifier defines how to verify a token.