> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Go SDK

> Waffo Go SDK installation, initialization, and usage guide.

## Requirements

* Go 1.20+
* No external dependencies (standard library only)

## Installation

```bash theme={null}
go get github.com/waffo-com/waffo-go/v2
```

## Initialization

```go theme={null}
package main

import (
    "log"
    waffo "github.com/waffo-com/waffo-go/v2"
    "github.com/waffo-com/waffo-go/v2/config"
)

func main() {
    cfg, err := config.NewConfigBuilder().
        APIKey("your-api-key").
        PrivateKey("your-base64-encoded-private-key").
        WaffoPublicKey("waffo-public-key").
        MerchantID("your-merchant-id").
        Environment(config.Sandbox).
        Build()
    if err != nil {
        log.Fatal(err)
    }

    client := waffo.New(cfg)
}
```

## Payments

```go theme={null}
import (
    "context"
    "strings"

    "github.com/google/uuid"
    "github.com/waffo-com/waffo-go/v2/types/order"
)

ctx := context.Background()
paymentRequestID := strings.ReplaceAll(uuid.New().String(), "-", "")

resp, err := client.Order().Create(ctx, &order.CreateOrderParams{
    PaymentRequestID:   paymentRequestID,
    MerchantOrderID:    "ORDER-" + uuid.New().String()[:8],
    OrderAmount:        "100.00",
    OrderCurrency:      "HKD",
    OrderDescription:   "Premium Plan",
    NotifyURL:          "https://your-site.com/webhook/waffo",
    SuccessRedirectURL: "https://your-site.com/payment/success",
    FailedRedirectURL:  "https://your-site.com/payment/failed",
    CancelRedirectURL:  "https://your-site.com/payment/cancel",
    UserInfo: &order.UserInfo{
        UserID:       "user_123",
        UserEmail:    "user@example.com",
        UserTerminal: "WEB",
    },
    GoodsInfo: &order.GoodsInfo{
        GoodsName: "Premium Plan",
        GoodsURL:  "https://your-site.com/product/001",
    },
    PaymentInfo: &order.PaymentInfo{
        ProductName: "ONE_TIME_PAYMENT",
    },
}, nil)

if err != nil {
    log.Fatal(err)
}

if resp.IsSuccess() {
    data := resp.GetData()
    fmt.Printf("Order ID: %s\n", data.AcquiringOrderID)
}
```

## Webhook handling

```go theme={null}
import "github.com/waffo-com/waffo-go/v2/core"

handler := client.Webhook().
    OnPayment(func(n *core.PaymentNotification) {
        fmt.Printf("Payment %s: %s\n", n.PaymentRequestID, n.OrderStatus)
    }).
    OnRefund(func(n *core.RefundNotification) {
        fmt.Printf("Refund %s: %s\n", n.RefundRequestID, n.RefundStatus)
    })

// HTTP handler
func webhookHandler(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    signature := r.Header.Get("X-SIGNATURE")

    result := handler.HandleWebhook(string(body), signature)

    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(200)
    w.Write([]byte(result.ResponseBody))
}
```

## Error handling

```go theme={null}
import "github.com/waffo-com/waffo-go/v2/core"

resp, err := client.Order().Create(ctx, params, nil)
if err != nil {
    var unknownErr *core.WaffoUnknownStatusError
    if errors.As(err, &unknownErr) {
        // Important note: The payment may have succeeded! Please confirm using the query API.
    }
    var waffoErr *core.WaffoError
    if errors.As(err, &waffoErr) {
        // Client-side error
    }
}
```

## Source code and documentation

* [GitHub](https://github.com/waffo-com/waffo-go)