Go SDK

The Plugipay Go SDK is a stdlib-only HMAC-signed REST client with full resource coverage. Same surface as the Node and Python SDKs, packaged the Go way: resources are fields on the Client struct, every method takes context.Context first and returns (value, error), and option structs replace keyword arguments.

import plugipay "github.com/hachimi-cat/saas-plugipay/sdk/go"

c, err := plugipay.NewClient(plugipay.ClientOptions{
    KeyID:  "pk_test_xxxxxxxxxxxxxxxx",
    Secret: "sk_test_xxxxxxxxxxxxxxxxxxxxxxxx",
})
if err != nil {
    log.Fatal(err)
}

cust, err := c.Customers.Create(ctx, plugipay.CustomerCreateInput{
    Email: ptr("ada@example.com"),
    Name:  ptr("Ada Lovelace"),
})

If this looks right to you, jump to Quickstart. The rest of this page is the lay of the land.

What's in the box

NewClient(ClientOptions{...}) — one constructor. KeyID and Secret default from PLUGIPAY_KEY_ID / PLUGIPAY_SECRET env vars, so a zero-value ClientOptions{} works in production.
Resource fields on Client — c.Customers, c.CheckoutSessions, c.Invoices, c.Subscriptions, c.Refunds, c.Payouts, c.Ledger, c.Reports, c.Webhooks, and the rest. Same shape as the Node and Python SDKs, just PascalCase.
Page[T] generic — list endpoints return Page[Customer], Page[Invoice], etc., with Data, Cursor, HasMore.
One error type, *plugipay.Error — extract with errors.As, branch on .Code / .Status / .RequestID. Network and timeout failures land in the same type with Status == 0 and a stable Code.
VerifyWebhook + VerifyWebhookSignature — verify inbound webhook deliveries. Pass the raw body bytes; no framework integration required.
Stdlib only. The go.mod has no require block beyond the Go version. No transitive supply-chain surface.

Conventions

The SDK is idiomatic Go and avoids surprises:

context.Context is the first argument to every API method. Pass a context.Background() for one-offs, a request-scoped context inside an HTTP handler, or a context.WithTimeout if you want a per-call deadline tighter than ClientOptions.Timeout.
Optional fields are pointers (*string, *int, *bool). The SDK exposes a ptr helper pattern but doesn't ship one — most teams define their own one-liner: func ptr[T any](v T) *T { return &v }.
JSON tags follow the wire — customerId, successUrl, accountId. The Go struct fields are PascalCase (CustomerID, SuccessURL, AccountID); the json: tag does the translation. You never touch the wire form unless you want to.
No globals. The Client carries the key, secret, base URL, and *http.Client. Safe for concurrent use by multiple goroutines. Construct one at startup, share it everywhere.
Idempotency keys are automatic for Create / mutation calls. The SDK generates a fresh key per call. Drop down to c.Do(...) with a RequestOptions{IdempotencyKey: ...} if you want to control it.

Requirements

Requirement	Version
Go	`1.22+`
OS	any (pure Go)
Network	outbound HTTPS to `plugipay.com`

We pin Go 1.22 because the SDK uses generics (Page[T], DoList[T]) and the for k, v := range semantics that landed in 1.22. Older Go versions are unsupported.

Install

go get github.com/hachimi-cat/saas-plugipay/sdk/go

See Installation for module paths, version pinning, go.sum verification, and vendoring.

When to use the SDK vs. the raw API

Use the SDK if your code is Go and you want signing handled for you. Use the raw API if:

You're embedding Plugipay calls into a CGo-restricted binary where pulling another module is friction.
You're proxying calls through a non-Go gateway and want the wire format to be the source of truth.
You're cross-implementing the SDK in a language we don't ship (Rust, Elixir, etc.).

HMAC signing is straightforward — the recipe is in API authentication. The SDK is a productivity shortcut, not a hidden requirement.

Source

The Go SDK lives in the saas-plugipay repo under sdk/go/. Issues and PRs welcome at github.com/hachimi-cat/saas-plugipay/issues.

The module path is canonical and stable:

github.com/hachimi-cat/saas-plugipay/sdk/go

The package name is plugipay, so callers typically import as:

import plugipay "github.com/hachimi-cat/saas-plugipay/sdk/go"

The leading plugipay alias is optional — Go infers the name from the package directive — but explicit aliasing keeps goimports from drifting back to the long form on save.

Pre-1.0

The SDK is at v0.x. Minor versions may include small breaking changes; we document every break in the changelog on GitHub. After 1.0 (target mid-2026), the major/minor/patch contract becomes strict and we'll publish a versioned module path (/sdk/go/v1) per Go convention.

Vendoring is fine. If your team uses go mod vendor, the SDK vendors cleanly — it's pure-Go, no cgo, no generated code. See Installation for the workflow.

Installation — go get, go.sum, vendoring, version pinning.
Quickstart — customer + checkout session in 40 lines.
Authentication — ClientOptions, env vars, OnBehalfOf, custom *http.Client.
Errors — the *plugipay.Error type and retry patterns.
Pagination — Page[T] and cursor iteration.
Webhooks — VerifyWebhook with net/http.
Reference — every method on every resource.