wallee-go-sdk

README

wallee-go-sdk

A Go client for the Wallee Web Service API.

The Live badge reports the weekly run against Wallee's shared test space. It is the stronger of the two: green means the generated models still decode real responses, not merely that the package compiles. See Testing.

Wallee publishes official SDKs for PHP, Java, Python, Ruby, C#, and TypeScript, but not Go. This module fills that gap the same way the others are built: the client is generated from Wallee's own OpenAPI (Swagger 2.0) definition, so it tracks the upstream API. The one hand-written piece is authentication (Wallee's spec declares no security scheme), added as an http.RoundTripper that signs every request.

• Module: github.com/zweiundeins/wallee-go-sdk
• Import path / package: github.com/zweiundeins/wallee-go-sdk/wallee (package wallee)
• Generated with openapi-generator 7.23.0 (pinned in openapitools.json) from swagger.json (pinned in-repo). The generated client + hand-written auth live in the wallee/ subpackage; the module root holds only project files (go.mod, README, gen.sh, CI, the spec).
• No third-party dependencies — pure standard library.

Install

go get github.com/zweiundeins/wallee-go-sdk/wallee

Quick start

import (
    "context"
    "os"

    "github.com/zweiundeins/wallee-go-sdk/wallee"
)

client, err := wallee.NewClient(wallee.Config{
    UserID:    140519,                        // Application User id
    SecretKey: os.Getenv("WALLEE_API_KEY"),   // its authentication key (base64, from the portal)
})
if err != nil {
    return err
}

// Almost every entity is scoped to a space; pass spaceId explicitly.
tx, _, err := client.TransactionServiceAPI.
    TransactionServiceRead(context.Background()).
    SpaceId(12345).Id(42).
    Execute()

Every operation is a fluent request builder terminated by Execute(), which returns (*Model, *http.Response, error). API errors come back as *wallee.GenericOpenAPIError; use .Body() for the raw response and .Model() for the parsed error entity. See wallee/example_test.go for a full checkout flow.

Authentication

Credentials belong to a Wallee Application User (portal: Space or Account → Users → Application Users). You need its numeric User Id and its authentication key (a base64 string). Keep the key server-side only.

Two signing schemes are live on app-wallee.com, both selectable via Config.Auth:

Scheme	Config.Auth	How	Notes
JWT (default)	AuthJWT	Authorization: Bearer <HS256 JWT>	Matches the current official SDKs. Recommended.
MAC (legacy)	AuthMAC	x-mac-* headers, HMAC-SHA512	Still accepted; use only if you have a reason to.

Both decode the base64 key and sign per request. The JWT binds each token to the exact request path (without the query string) and HTTP method; the MAC binds to the full request URI (with query). Signing is a transparent http.RoundTripper, so it covers every generated call. To layer your own transport (proxy, tracing, retries) beneath the signature, pass an *http.Client with a Transport set:

wallee.NewClient(wallee.Config{
    UserID:     140519,
    SecretKey:  key,
    HTTPClient: &http.Client{Transport: myTracingTransport},
})

Webhooks

Wallee webhooks deliver an entity reference (type + id + spaceId), not a trusted payload. Treat the notification only as a signal to re-read the entity via the API (e.g. TransactionServiceAPI.TransactionServiceRead) and act on that authoritative state. This also makes duplicate/out-of-order deliveries safe.

Which services

The full surface is generated (111 services, 445 models — see wallee/docs/). The services most integrations use:

• TransactionServiceAPI — create/read/confirm/search transactions
• TransactionPaymentPageServiceAPI — hosted Payment Page URL
• TransactionLightboxServiceAPI / TransactionIframeServiceAPI — embedded flows
• SubscriptionServiceAPI, SubscriptionProductServiceAPI, SubscriptionChargeServiceAPI — recurring billing
• RefundServiceAPI — refunds
• WebhookListenerServiceAPI, WebhookUrlServiceAPI — webhook configuration

Regenerating from upstream

The generator version and the spec are both pinned, so regeneration is reproducible. On a Wallee API bump:

./gen.sh --refresh-spec   # pull the latest spec, then regenerate
./gen.sh                  # regenerate from the committed spec
git diff                  # review added/changed fields before committing

gen.sh regenerates into wallee/, then gofmts and builds+vets. Hand-written files (wallee/auth.go, wallee/*_test.go) are protected by wallee/.openapi-generator-ignore and are never overwritten.

Testing

go test ./...

The auth layer is covered by known-answer vectors (JWT and MAC), independent signature verification, and end-to-end checks through the generated client via httptest. No network or credentials are needed.

License

MIT.

openapi-generator places no licensing condition on the code it emits, so the generated client is covered by the same terms as the hand-written auth.go. The vendored swagger.json is Wallee's published API definition and remains theirs. This is an independent client, not an official Wallee product.