# Go SDK

[`sumup-go`](https://github.com/sumup/sumup-go) is the official Go module. It exposes typed clients for every endpoint, handles authentication headers, and surfaces helpers for common request payloads.

## Installation

Install the module with `go get github.com/sumup/sumup-go` (or `go install` for reproducible builds).

## Configure Authentication

Create a secret API key or OAuth access token in the [developer dashboard](https://me.sumup.com/developers). The SDK reads `SUMUP_API_KEY` by default, so setting `SUMUP_API_KEY=sup_sk_MvxmLOl0...` before running your binary is enough. You can also pass the key explicitly:

```go
client := sumup.NewClient(client.WithAPIKey("sup_sk_MvxmLOl0..."))
```

## Examples

### Online Payment Checkout

```go
package main

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

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

func main() {
	ctx := context.Background()
	client := sumup.NewClient()

	merchantCode := os.Getenv("SUMUP_MERCHANT_CODE")
	desc := "Online payment via card widget"

	checkout, err := client.Checkouts.Create(ctx, sumup.CheckoutsCreateParams{
		Amount:            25.00,
		CheckoutReference: "ORDER-1001",
		Currency:          sumup.CurrencyEUR,
		Description:       &desc,
		MerchantCode:      merchantCode,
	})
	if err != nil {
		log.Fatalf("create checkout: %v", err)
	}

	fmt.Println(*checkout.ID)
	// Return checkout ID to your webpage so the SumUp card widget can complete the payment.
}
```

### Cloud API Checkout

```go
package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"strings"
	"time"

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

func main() {
	ctx := context.Background()
	client := sumup.NewClient()

	merchantCode := os.Getenv("SUMUP_MERCHANT_CODE")
	affiliateKey := os.Getenv("SUMUP_AFFILIATE_KEY")
	appID := os.Getenv("SUMUP_APP_ID")

	readerList, err := client.Readers.List(ctx, merchantCode)
	if err != nil {
		log.Fatalf("list readers: %v", err)
	}

	var solo sumup.Reader
	for _, rdr := range readerList.Items {
		if strings.EqualFold(string(rdr.Device.Model), "solo") {
			solo = rdr
			break
		}
	}
	if solo.ID == "" {
		log.Fatal("Pair a Solo reader before using the Cloud API.")
	}

	checkout, err := client.Readers.CreateCheckout(ctx, merchantCode, string(solo.ID), sumup.CreateCheckoutRequest{
		TotalAmount: sumup.CreateCheckoutRequestTotalAmount{
			Currency: "EUR",
			MinorUnit: 2,
			Value:    1500,
		},
	})
	if err != nil {
		log.Fatalf("create checkout: %v", err)
	}

	fmt.Println(checkout.Data.ClientTransactionId)
}
```