Call the hCaptcha task API from Go

Use net/http with a request deadline, JSON encoding, Bearer authentication, and explicit task-state handling before reading a token.

Build the request with net/http

You can call the easycaptcha API from Go without a language-specific SDK. Use JSON encoding rather than constructing a body with concatenated strings. Set a transport deadline that allows the server’s requested hold interval plus network overhead.

package integration

import (
    "bytes"
    "context"
    "encoding/json"
    "net/http"
    "time"
)

func Submit(ctx context.Context, key, sitekey, pageURL string) (*http.Response, error) {
    body, err := json.Marshal(map[string]any{
        "type": "hcaptcha_token", "sitekey": sitekey,
        "url": pageURL, "hold": 30,
    })
    if err != nil { return nil, err }
    req, err := http.NewRequestWithContext(ctx, http.MethodPost,
        "https://api.easycaptcha.to/v1/task", bytes.NewReader(body))
    if err != nil { return nil, err }
    req.Header.Set("Authorization", "Bearer " + key)
    req.Header.Set("Content-Type", "application/json")
    client := &http.Client{Timeout: 45 * time.Second}
    return client.Do(req)
}

This helper returns the HTTP response rather than pretending every response is a token. Its caller must close the body, check the actual status, and decode the appropriate response schema. A production service should normally reuse a configured HTTP client across calls.

Model the lifecycle separately

After successful creation, retain the task ID and initial status. Look up queued or running work with GET /v1/task/{task_id}. Decode result.token only after confirming a completed token task. A failed task snapshot is distinct from an HTTP Problem Details response.

Your context can stop local waiting, but it does not cancel accepted server work. Avoid automatically retrying a POST after an ambiguous network failure. Persist the ID as soon as it is available so another worker can retrieve the same task after a restart.

Keep amounts and credentials precise

Balance microcents are integer strings, not floating-point dollars. Use integer parsing for accounting and format decimal dollars only for display. Never attach browser session cookies or an account password to customer-key calls.

The OpenAPI document is the source for complete models and fields. Use curl to isolate serialization issues, and the recovery guide to design process restart behavior before scaling concurrent workers.