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

# Go SDK

> Install and configure the official UQPAY Go SDK to integrate banking and card issuance APIs.

The UQPAY Go SDK provides typed access to the UQPAY API, including automatic OAuth2 authentication, automatic idempotency keys, and thread-safe credential management.

<Card title="GitHub" icon="golang" href="https://github.com/uqpay/uqpay-sdk-go">
  github.com/uqpay/uqpay-sdk-go
</Card>

<Info>
  The SDK requires **Go 1.19** or higher. Current version: **1.0.3**.
</Info>

## Installation

```bash theme={null}
go get github.com/uqpay/uqpay-sdk-go@latest
```

## Quick start

```go theme={null}
package main

import (
    "context"
    "log"

    "github.com/uqpay/uqpay-sdk-go"
    "github.com/uqpay/uqpay-sdk-go/configuration"
    "github.com/uqpay/uqpay-sdk-go/issuing"
)

func main() {
    client, err := uqpay.NewClient(
        "your-client-id",
        "your-api-key",
        configuration.Sandbox(),
    )
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // Create a cardholder
    cardholder, err := client.Issuing.Cardholders.Create(ctx, &issuing.CreateCardholderRequest{
        Email:       "user@example.com",
        PhoneNumber: "1234567890",
        FirstName:   "John",
        LastName:    "Doe",
        CountryCode: "US",
    })
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Cardholder ID: %s\n", cardholder.CardholderID)
}
```

## Configuration

<Tabs>
  <Tab title="Direct parameters">
    ```go theme={null}
    // Sandbox (for testing)
    client, err := uqpay.NewClient(clientID, apiKey, configuration.Sandbox())

    // Production
    client, err := uqpay.NewClient(clientID, apiKey, configuration.Production())
    ```
  </Tab>

  <Tab title="Environment variables">
    ```bash theme={null}
    export UQPAY_CLIENT_ID="your-client-id"
    export UQPAY_API_KEY="your-api-key"
    ```

    Or create a `.env` file from the provided template:

    ```bash theme={null}
    cp .env.example .env
    ```
  </Tab>

  <Tab title="Custom endpoint">
    ```go theme={null}
    client, err := uqpay.NewClient(clientID, apiKey, &configuration.Config{
        BaseURL: "https://custom-api.example.com/api",
    })
    ```
  </Tab>
</Tabs>

## Authentication

The SDK handles OAuth2 authentication automatically:

* Fetches access tokens using client credentials
* Caches tokens until expiration
* Automatically refreshes expired tokens
* Thread-safe token management

## Idempotency

Every API request automatically includes a unique idempotency key to ensure safe retries and prevent duplicate operations. You do not need to set this manually.

## Error handling

The SDK returns detailed error information including HTTP status codes and API error details:

```go theme={null}
card, err := client.Issuing.Cards.Get(ctx, cardID)
if err != nil {
    log.Printf("Error: %v\n", err)
    return
}
```

Example error format:

```
failed to get card: 404: card_not_found: Card not found (HTTP 404)
```

## API coverage

### Banking API

| Resource             | Operations                                                   |
| -------------------- | ------------------------------------------------------------ |
| **Balances**         | Get, List, ListTransactions                                  |
| **Transfers**        | Create, List, Get                                            |
| **Deposits**         | List, Get                                                    |
| **Beneficiaries**    | Create, List, Get, Update, Delete, ListPaymentMethods, Check |
| **Payouts**          | Create, List, Get                                            |
| **Virtual Accounts** | Create, List                                                 |
| **Conversions**      | CreateQuote, Create, List, Get, ListConversionDates          |
| **Exchange Rates**   | List                                                         |

### Issuing API

| Resource         | Operations                                                     |
| ---------------- | -------------------------------------------------------------- |
| **Cardholders**  | Create, Get, List                                              |
| **Cards**        | Create, Get, GetSecure, List, Recharge, Withdraw, UpdateStatus |
| **Transactions** | Get, List                                                      |
| **Products**     | List                                                           |