Go SDK — getting started

The Go SDK is a single module split into three packages:

Package	Purpose
`github.com/paylera/paylera-go`	Typed client for `api.paylera.dev` (every operation in the OpenAPI spec)
`github.com/paylera/paylera-go/relay`	`net/http` relay handler — the ten-route SDK protocol the React SDK calls into
`github.com/paylera/paylera-go/webhook`	Webhook signature verifier + dispatcher

Each is independently importable; you only pull in what you use.

Install

go get github.com/paylera/paylera-go

Requires Go 1.25 or newer.

Build a client

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    paylera "github.com/paylera/paylera-go"
)

func main() {
    c, err := paylera.NewClient(
        paylera.WithAPIToken(os.Getenv("PAYLERA_API_TOKEN")),
    )
    if err != nil {
        log.Fatal(err)
    }

    check, err := c.CheckEntitlement(context.Background(), nil, paylera.CheckRequest{
        FeatureCode: "api_calls",
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("allowed=%v balance=%v\n", check.Allowed, check.Balance)
}

The token prefix picks the base URL automatically:

Prefix	Base URL
`pl_live_*`	`https://api.paylera.dev`
`pl_test_*`	`https://api.test.paylera.dev`
anything else	call `WithBaseURL(...)`

Construction options

paylera.WithAPIToken(token)        // required (or WithBaseURL on self-hosted)
paylera.WithBaseURL(url)           // override the auto-selected host
paylera.WithAPIVersion("2026-04-01")
paylera.WithHTTPClient(httpClient) // inject your transport / proxy
paylera.WithTracer(tracer)         // custom OpenTelemetry tracer
paylera.WithRetry(paylera.RetryConfig{
    MaxAttempts:    3,
    InitialBackoff: 500 * time.Millisecond,
    MaxBackoff:     5 * time.Second,
    Multiplier:     2.0,
    JitterFraction: 0.1,
})

The client is safe for concurrent use — build one at process start and share it.

Typed methods at a glance

Method	Endpoint	Idempotency
`CheckEntitlement`	`POST /v1/check`	optional
`TrackUsage`	`POST /v1/track`	auto-stamped
`Attach`	`POST /v1/attach`	auto-stamped
`CreateCustomer`	`POST /v1/customers`	auto-stamped
`GetCustomer`	`GET /v1/customers/{id}`	n/a
`ListPlans`	`GET /v1/plans`	n/a
`ResolveSubscriptionEntitlements`	`GET /v1/subscriptions/{id}/entitlements`	n/a

Anything not in the typed surface is reachable via c.Raw().* — the generated client, with the same auth + retry + idempotency middleware applied.

Run a working example

The repo ships two reference apps:

examples/go/stdlib-server/ — net/http, single file
examples/go/gin-server/ — Gin web framework

Both mount the relay at /api/paylera/, the webhook at /webhooks/paylera, and ship a mock JWT-claim auth middleware so relay.Identify has something to resolve.

git clone https://github.com/paylera/paylera
cd paylera/examples/go/stdlib-server
cp .env.example .env
# edit .env: PAYLERA_API_TOKEN, PAYLERA_WEBHOOK_SECRET
go run .

Where to next

Relay handler — mount in chi, gorilla/mux, gin, echo, fiber
Webhooks — verify, dispatch, rotate secrets
Idempotency — Idempotency-Key, UUIDv7 auto-stamping
Errors — errors.As against typed subtypes

Source

github.com/paylera/paylera-go — issues and PRs welcome.