Attribute hCaptcha requests with a developer tag

Send a developer tag per task request, preserve customer authentication, and report eligible paid usage separately from referrals and free-plan work.

Activate the developer program first

An account can activate the developer program in the dashboard’s Affiliates screen. It then receives a tag for attributing paid task requests through its software. The program credits 5% of eligible paid task credit spent to the developer’s service balance daily.

This is request attribution, not an account key setting. Your integration must attach the tag to the creation requests you intend to attribute. A tag does not authenticate the customer or authorize spending by itself.

Choose a header or body field

Authorization: Bearer CUSTOMER_API_KEY
X-Developer-Tag: YOUR_DEVELOPER_TAG
Content-Type: application/json

Alternatively, include developer_tag in the JSON task body. When both are supplied, they must match. Unknown tags fail before task admission. Use the exact activated tag rather than inventing an identifier with a similar prefix.

The SDK clients also support a default developer tag in their construction options. That convenience still results in request-level attribution; it does not permanently attach a tag to an API key. If your software builds requests directly, keep the attribution rule at the same boundary as task creation.

Keep customer and developer responsibilities separate

For a custom browser extension package, set developer_tag inside easycaptcha_settings in the root manifest.json:

{
  "easycaptcha_settings": {
    "developer_tag": "YOUR_DEVELOPER_TAG"
  }
}

The extension includes this tag in each recognition task creation request. This setting is manifest only; the popup, settings RPC, and saved sync settings cannot override it. Reload the extension after changing the manifest, and apply the setting again when replacing the package. See extension manifest configuration for the other supported fields.

The customer’s key authorizes the task. The developer tag determines revenue attribution for eligible work. Never ask a customer to send their account password as a substitute for an API key, and do not place a shared customer key in a public application bundle.

Free-plan tasks, refunded work, and the developer’s own requests do not generate revenue. A local submission count therefore cannot be multiplied by an assumed task price to establish earnings. Grouping, modes, actual paid spend, and reversals can all affect the result.

Verify attribution with a small integration trial

Inspect a constructed request with credentials redacted, then check the program totals after eligible work and settlement. Test an invalid tag and conflicting header/body values so errors do not silently disappear into a generic retry.

The affiliate documentation covers exclusions, daily credits, and payout approval. Revenue attribution analysis explains why pending earnings differ from a withdrawal, and referral versus developer programs separates their calculation bases.