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

# Go SDK

> Official Fyatu Go SDK — type-safe card issuing and payment API client for Go applications.

<Warning>
  This SDK is coming soon. Subscribe to our [changelog](/v3/changelog/overview) to be notified when it's released.
</Warning>

The official Go SDK for FYATU API v3, with idiomatic Go design and error handling.

## Requirements

* Go 1.21 or higher

## Installation

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

## Quick Start

```go theme={null}
package main

import (
    "context"
    "fmt"
    "log"

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

func main() {
    client := fyatu.NewClient(
        fyatu.WithCredentials("your_app_id", "your_secret_key"),
    )

    // Create a collection
    collection, err := client.Collections.Create(context.Background(), &fyatu.CreateCollectionParams{
        Amount:      10.00,
        Currency:    "USD",
        Reference:   "order_123",
        Description: "Payment for Order #123",
        Customer: &fyatu.Customer{
            Email: "customer@example.com",
            Name:  "Alice Example",
        },
        RedirectURL: "https://yoursite.com/payment/success",
        WebhookURL:  "https://yoursite.com/webhooks/fyatu",
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(collection.CheckoutURL)
}
```

## Features

* **Idiomatic Go** - Follows Go conventions and best practices
* **Context Support** - Full context.Context support for cancellation
* **Structured Errors** - Type-safe error handling with error codes
* **Automatic Token Management** - Handles JWT refresh automatically
* **Thread-Safe** - Safe for concurrent use

## Configuration Options

```go theme={null}
client := fyatu.NewClient(
    fyatu.WithCredentials("your_app_id", "your_secret_key"),

    // Optional configuration
    fyatu.WithBaseURL("https://api.fyatu.com/api/v3"),
    fyatu.WithTimeout(30 * time.Second),
    fyatu.WithRetries(3),
    fyatu.WithHTTPClient(customHTTPClient),
)
```

## Available Services

| Service              | Description                    |
| -------------------- | ------------------------------ |
| `client.Collections` | Accept payments via checkout   |
| `client.Refunds`     | Manage refunds                 |
| `client.Payouts`     | Send money to recipients       |
| `client.Cardholders` | Manage cardholders             |
| `client.Cards`       | Issue and manage virtual cards |

\| `client.Account` | Access account information |

## Error Handling

```go theme={null}
import (
    "errors"
    "github.com/fyatu/fyatu-go"
)

payout, err := client.Payouts.Create(ctx, &fyatu.CreatePayoutParams{
    Amount:      100,
    Currency:    "USD",
    RecipientID: "invalid_id",
})
if err != nil {
    var apiErr *fyatu.Error
    if errors.As(err, &apiErr) {
        switch apiErr.Code {
        case fyatu.ErrValidation:
            fmt.Printf("Validation failed: %v\n", apiErr.Details)
        case fyatu.ErrAuthentication:
            fmt.Printf("Authentication failed: %s\n", apiErr.Message)
        case fyatu.ErrInsufficientBalance:
            fmt.Printf("Insufficient balance: %s\n", apiErr.Message)
        default:
            fmt.Printf("API error [%s]: %s\n", apiErr.Code, apiErr.Message)
        }
    } else {
        fmt.Printf("Unexpected error: %v\n", err)
    }
    return
}
```

## Webhook Verification

```go theme={null}
import (
    "net/http"
    "github.com/fyatu/fyatu-go/webhook"
)

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    signature := r.Header.Get("X-Fyatu-Signature")

    payload, err := io.ReadAll(r.Body)
    if err != nil {
        http.Error(w, "Failed to read body", http.StatusBadRequest)
        return
    }

    valid, err := webhook.VerifySignature(payload, signature, "your_webhook_secret")
    if err != nil || !valid {
        http.Error(w, "Invalid signature", http.StatusUnauthorized)
        return
    }

    var event webhook.Event
    if err := json.Unmarshal(payload, &event); err != nil {
        http.Error(w, "Invalid payload", http.StatusBadRequest)
        return
    }

    fmt.Printf("Received event: %s\n", event.Type)
    w.WriteHeader(http.StatusOK)
}
```

## Pagination

```go theme={null}
// List all collections with pagination
iter := client.Collections.List(ctx, &fyatu.ListCollectionsParams{
    Limit: 10,
})

for iter.Next() {
    collection := iter.Current()
    fmt.Printf("Collection: %s - %s\n", collection.ID, collection.Status)
}

if err := iter.Err(); err != nil {
    log.Fatal(err)
}
```

## Resources

* [API Reference](/v3/api-reference/introduction)
* [Webhooks Guide](/v3/concepts/webhooks)
* [GitHub Repository](https://github.com/fyatu/fyatu-go) *(Coming soon)*