SumUp Go SDK

IMPORTANT: This SDK is under development. We might still introduce minor breaking changes before reaching v1.

The Go SDK for the SumUp API.

To learn more, check out our API Reference and Documentation.

Installation

sumup-go is compatible with projects using Go Modules.

Import the SDK using:

import (
	"github.com/sumup/sumup-go"
)

And run any of go build/go install/go test which will resolve the package automatically.

Alternatively, you can install the SDK using:

go get github.com/sumup/sumup-go

Documentation

For complete documentation of SumUp APIs visit developer.sumup.com. Alternatively, refer to this simple example to get started:

package main

import (
	"context"
	"log"

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

func main() {
	client := sumup.NewClient()

	merchant, err := client.Merchants.Get(context.Background(), "MCNPLE22", sumup.MerchantsGetParams{})
	if err != nil {
		log.Printf("[ERROR] get merchant account: %v", err)
		return
	}

	log.Printf("[INFO] merchant code: %s", merchant.MerchantCode)
}

Authentication

The easiest form of authenticating with SumUp APIs is using API keys. You can create API keys in the API key section of the developer portal. Store them securely. The SDK by default loads the API key from SUMUP_API_KEY environment variable. Alternatively, provide API key on your own:

client := sumup.NewClient(client.WithAPIKey("sup_sk_LZFWoLyd..."))

Handling errors

Use errors.As from the standard errors package to read typed Problem details:

_, err := client.Checkouts.Get(context.Background(), "your-checkout-id")

var problem *sumup.Problem
if errors.As(err, &problem) {
    fmt.Println(problem.Type)
    if problem.Detail != nil {
        fmt.Println(*problem.Detail)
    }
}
var apiError *sumup.APIError
if errors.As(err, &apiError) {
    fmt.Println(apiError.StatusCode, string(apiError.Body))
}

APIError.Headers contains the response headers. Connection failures retain their original Go error, so errors.Is and errors.As continue to work.

Events

Receive signed event notifications with callbacks generated from the OpenAPI spec:

handler, err := client.EventsHandler(os.Getenv("SUMUP_EVENT_SECRET"), handleUnhandled)
if err != nil {
	return err
}
if err := handler.OnMemberUpdated(handleMemberUpdated); err != nil {
	return err
}
if err := handler.OnReaderCreated(handleReaderCreated); err != nil {
	return err
}

// Inside your HTTP handler, limit and read the raw body before dispatch.
r.Body = http.MaxBytesReader(w, r.Body, 1<<20)
body, err := io.ReadAll(r.Body)
if err != nil {
	http.Error(w, "invalid event body", http.StatusBadRequest)
	return
}
err = handler.Handle(r.Context(), body, r.Header.Get(sumup.EventSignatureHeader))
// Return a 2xx response only after success.

Callbacks accept a context and their specific event type:

func handleMemberUpdated(ctx context.Context, event *sumup.MemberUpdatedEvent) error {
	member, err := event.FetchObject(ctx)
	if err != nil {
		return err
	}
	log.Printf("member updated: %s", member.ID)
	return nil
}

The required fallback has signature func(context.Context, sumup.EventNotification) error. It receives known events without a registered callback and unknown event types. Registering a nil or duplicate callback returns an error; registration and handling are concurrency-safe. Callbacks execute synchronously and must synchronize any shared state themselves.

Signatures use X-SumUp-Webhook-Signature: t=<unix timestamp>,v1=<hex HMAC>. Verification happens before JSON parsing, uses the exact raw body, and accepts a fixed five minutes of clock skew. An empty signing secret is rejected. The SDK accepts already-read bytes and leaves body-size limits to your HTTP receiver. Use http.MaxBytesReader before reading the body, as in the example above.

For manual dispatch, use client.ParseEventNotification(secret, body, signature) and a type switch. Only use ParseEventNotificationWithoutVerification for fixtures or notifications already verified by trusted infrastructure.

FetchObject(ctx) returns the latest typed resource using the SDK's authentication and transport. Unknown events fetch raw JSON. Resource URLs must use the default API origin (https://api.sumup.com). URL credentials and fragments are ignored; the path and query use the client's configured base URL and authentication. Resource fetching does not follow redirects. API failures return *sumup.APIError, preserving the status, headers, and body. Structured Problem details remain accessible as *sumup.Problem with errors.As. Deleted resources may no longer be fetchable. Treat events as notifications, make processing idempotent using the event ID, and allow for retries and out-of-order delivery. Return a 5xx response for *sumup.EventCallbackError so failed processing can be retried.

See the events example for a complete HTTP receiver and error handling.

Examples

The repository includes several examples demonstrating different use cases:

simple - Basic merchant account information retrieval showing how to initialize the SDK and make a simple API call.

go run example/simple/main.go

checkout - Creating and processing a checkout programmatically using test card details.

go run example/checkout/main.go

full - Complete web application demonstrating the full checkout flow with the SumUp payment widget. Shows how to create checkouts and integrate the widget in a real application.

go run example/full/main.go

and visit http://localhost:8080

events - HTTP server showing signature verification, typed callbacks, and resource fetching.

SUMUP_EVENT_SECRET=whsec_test go run example/events/main.go

Then send POST requests to http://localhost:8080/events

Support

Our APIs and their public offering is limited and under heavy development. If you have any questions or inquiries reach out to our support team via the Contact Form.

For question specifically related to this Golang SDK please Open an Issue.

sumup-go SDK will always support latest 3 version of golang following the Golang Release Policy.