Validate a supplied reCAPTCHA token

Ask Wallkit to verify a client token for the selected resource. The result describes this validation call; it does not create identity, grant content access or certify every anti-abuse condition.

Task	Operation	Access
Verify a supplied client token	Validate	Guest action with required resource context.

Example clients and synthetic values follow response conventions.

Verify the resource’s supplied token

POST /api/v1/integrations/google-recaptcha/validate

Send an existing client token for provider verification. Google receives the token and configured secret; Wallkit logs the provider answer and exception details.

Before you call

Guest ACL permits this action, but a valid resource header is required. No member token is required. The selected resource must have google_recaptcha.active enabled. Resource-specific public/secret keys fall back to server configuration when empty; this operation neither supplies a secret nor acquires a client token. Use the token from your already configured client integration.

Wallkit accepts Google’s success value when it evaluates to true in a boolean check. It has no active score threshold, expected action, hostname or independent expiry check. Do not interpret status:true as proof of those conditions. Provider compatibility and malformed provider-response behavior are unspecified.

Request

JSON body in examples. Nonempty posted form fields take precedence over JSON; choose one representation. The body is cast to an object, so an empty/malformed body is not a reliable separate empty-body error: with active configuration, missing recaptcha_token reaches the missing-token branch.

Name	Location	Type / requirement	Meaning
resource	header	required existing public key	Selects resource and its reCAPTCHA configuration; see transport.
recaptcha_token	JSON / form	required supplied string; missing or null rejected	Sanitized as string before forwarding. Empty string is not locally rejected as missing; it reaches provider verification. No local token length/format guarantee.

Result

HTTP 200 JSON when the provider success value evaluates to true in a boolean check. The provider object is not forwarded.

Field	Type / presence	Meaning
status	boolean true; successful result	Wallkit accepted this provider verification answer under its success check.
error	string; handled failure	error_validate_recaptcha for caught action exceptions; shared resource errors differ.
error_description	string; handled failure	Exception message; provider-false result says Recaptcha is not valid.
req_guid	string; error	Request correlation value; common optional metadata follows response conventions.

Example: Interpret an accepted provider answer

The synthetic token marks an already supplied client value; it is not a usable token. In this scenario Google’s success value evaluates to true and Wallkit accepts it.

curl -X POST "${WALLKIT_API_BASE}/api/v1/integrations/google-recaptcha/validate" \
  -H "Content-Type: application/json" \
  -H "resource: ${RESOURCE_KEY}" \
  --data-raw '{"recaptcha_token": "SYNTHETIC_RECAPTCHA_TOKEN"}'

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/integrations/google-recaptcha/validate`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "resource": process.env.RESOURCE_KEY },
  body: JSON.stringify({"recaptcha_token": "SYNTHETIC_RECAPTCHA_TOKEN"})
});
console.log(response.status, await response.json());

import os, json
from urllib.request import Request, urlopen
from urllib.error import HTTPError

body = {'recaptcha_token': 'SYNTHETIC_RECAPTCHA_TOKEN'}
request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/integrations/google-recaptcha/validate",
    data=json.dumps(body).encode("utf-8"),
    headers={"Content-Type": "application/json", "resource": os.environ["RESOURCE_KEY"]}, method="POST")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

Synthetic HTTP 200 excerpt:

{
  "status": true
}

Continue only the task whose requirements your application has actually checked; this response carries no user or entitlement.

Consequential alternate

When the provider answer is an array with success false/missing, HTTP 409 excerpt (other response metadata omitted):

{
  "error": "error_validate_recaptcha",
  "error_description": "Recaptcha is not valid"
}

The call did not pass Wallkit validation. Malformed/null provider JSON can fail outside the caught Exception path; no stable JSON/status is promised for that case.

Recovery

HTTP status	API code / shape	Cause	Next action
404	resource_not_exists	Missing/unresolved resource key.	Check the supplied resource public key with integration owner.
422	error_validate_recaptcha; Google Recaptcha is not enabled on current resource	Resource configuration inactive.	Ask integration owner to inspect the selected resource’s configuration.
422	error_validate_recaptcha; Empty google recaptcha token	Token field missing or null with active configuration.	Supply the existing client token in one selected body representation.
409	error_validate_recaptcha; Recaptcha is not valid	Provider answer has false/missing success.	Handle rejection and let the configured client flow obtain a fresh token if appropriate; do not treat rejection as identity.
Unspecified	No universal JSON/status contract	Other provider/transport or malformed-answer failure.	Handle unavailable validation separately from a pass; inspect server/provider configuration through integration owner.

Next task

Return to the In-depth integration tasks. reCAPTCHA validation alone does not require an account request or payment.