Plugipay
ForjioHuudisIdentityPlugipayPaymentsStorlaunchE-commerceFulkrumaFulfilmentRiplloMarketingLinkSnapShort URLsPawpadoGPU streaming
Plugipay Docs
⌘K

Installing the Go SDK

The Plugipay Go SDK is a single Go module with zero runtime dependencies — just standard library. go get is all you need; no codegen, no native bindings, no build tags.

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

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

If both worked, skip to the Quickstart. The rest of this page covers Go version support, go.sum verification, vendoring, and version pinning — useful if you're being deliberate about your build pipeline.

Requirements

Requirement Version Notes
Go 1.22+ Generics are used for Page[T] and DoList[T]. 1.21 lacks the loop-scoping behavior we rely on.
OS any Pure Go, no cgo.
Runtime deps none Stdlib only — see go.mod.
Build deps none No codegen, no go generate step.

The module declares go 1.22 in its go.mod. The Go toolchain enforces this on go build. If you're on 1.21 or older, upgrade before adding the SDK.

No external dependencies. The SDK is intentionally stdlib-only — net/http, crypto/hmac, crypto/sha256, encoding/json. This keeps your go.sum minimal and removes a whole class of supply-chain risk. We will not add transitive deps without a major version bump.

Install

The canonical module path is:

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

The package name is plugipay. Most callers alias it explicitly so goimports doesn't drift:

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

From scratch

mkdir my-checkout-service && cd my-checkout-service
go mod init github.com/yourorg/my-checkout-service
go get github.com/hachimi-cat/saas-plugipay/sdk/go

Your go.mod after install:

module github.com/yourorg/my-checkout-service

go 1.22

require github.com/hachimi-cat/saas-plugipay/sdk/go v0.1.0

And the SDK's transitive line in go.sum:

github.com/hachimi-cat/saas-plugipay/sdk/go v0.1.0 h1:...
github.com/hachimi-cat/saas-plugipay/sdk/go v0.1.0/go.mod h1:...

Two lines, no transitive entries — that's the whole footprint.

Pinning a specific version

go get resolves to the latest tagged release by default. To pin:

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

To upgrade later:

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

Or to a specific newer release:

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

We follow semver. Pre-1.0, minor bumps may include small breaks — check the changelog before crossing a minor.

go.sum verification

After go get, run:

go mod verify

This re-hashes the downloaded module and compares against go.sum. A mismatch means either a corrupted cache (go clean -modcache and reinstall) or, in the rare case, a tampered proxy — report it.

For supply-chain-paranoid teams, set the public Go checksum database (the default):

export GOSUMDB=sum.golang.org

The proxy at proxy.golang.org mirrors the module and sum.golang.org provides the trusted hashes. Both are public infrastructure run by the Go team. If your enterprise environment runs an internal Go proxy, point GOPROXY at it — the SDK is hosted on GitHub and any standard Go proxy mirrors it transparently.

Vendoring

If your team uses go mod vendor (common in regulated environments where third-party code must be reviewed in-tree):

go mod vendor

This copies the SDK source into ./vendor/github.com/hachimi-cat/saas-plugipay/sdk/go/. The whole SDK is ~70KB of source across ~25 .go files — small to review.

go build automatically uses the vendored copy when a vendor/ directory is present. To force module mode (skip vendor):

go build -mod=mod ./...

To force vendor mode (fail if vendor is incomplete):

go build -mod=vendor ./...

CI typically uses -mod=vendor to guarantee builds are hermetic.

Workspaces (Go 1.18+)

If you're hacking on the SDK alongside your service in a go.work workspace:

mkdir my-workspace && cd my-workspace
git clone https://github.com/hachimi-cat/saas-plugipay
git clone https://github.com/yourorg/my-checkout-service

go work init ./my-checkout-service
go work use ./saas-plugipay/sdk/go

Now edits inside saas-plugipay/sdk/go/ are picked up by my-checkout-service without go get. Helpful for reproducing SDK bugs against your own code.

Verifying the install

A more thorough check than import plugipay:

package main

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

func main() {
    // Construct with explicit creds so we don't depend on env state.
    c, err := plugipay.NewClient(plugipay.ClientOptions{
        KeyID:  "pk_test_dummy",
        Secret: "sk_test_dummy",
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(c.BaseURL())   // https://plugipay.com
    fmt.Println(c.KeyID())     // pk_test_dummy

    // Resource fields are non-nil after construction.
    fmt.Printf("%T\n", c.Customers)        // *plugipay.CustomersResource
    fmt.Printf("%T\n", c.CheckoutSessions) // *plugipay.CheckoutSessionsResource
}

If any line panics or fails to compile, you have a stale module cache. Clean and retry:

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

Upgrading

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

Then run your tests. The SDK ships a typed surface — if a method signature changes between minor versions, the compiler tells you immediately. We don't rely on runtime reflection for the public API, so upgrades are caught at build time, not in production.

Troubleshooting

go: module ... not found

You're on Go 1.21 or older, or GOPROXY is blocked from reaching proxy.golang.org. Check:

go version
go env GOPROXY

If GOPROXY=off, the toolchain only uses local cache — set it back to https://proxy.golang.org,direct or your enterprise proxy.

verifying ...: checksum mismatch

A go.sum line doesn't match what was downloaded. Almost always a stale local cache after a force-push to a branch you'd already imported. Fix:

go clean -modcache
go mod tidy

If the mismatch persists with a tagged release (it shouldn't), open an issue.

package github.com/...: ambiguous import

You have both go get-ed and replace-ed (or vendored and module-mode) copies of the SDK. Remove the replace line in go.mod, or run -mod=mod to skip vendor.

undefined: plugipay.Page[Customer] on Go 1.21

You're on a Go version older than 1.22. Upgrade:

# Linux: download from https://go.dev/dl/ or use your package manager.
# macOS: brew install go (gives latest).
# Windows: installer from go.dev/dl/.

Next

  • Quickstart — first customer + checkout session.
  • Authentication — ClientOptions, env vars, on-behalf-of.
  • API keys — if you don't have a pk_test_* / sk_test_* pair yet.
Plugipay — Payments that don't tax your success