> ## 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

> 安装并配置 UQPAY 官方 Go SDK，集成账户与发卡 API。

UQPAY Go SDK 以带类型的方式访问 UQPAY API，内置自动 OAuth2 鉴权、自动幂等键和线程安全的凭证管理。

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

<Info>
  SDK 需要 **Go 1.19** 或更高版本。当前版本：**1.0.3**。
</Info>

## 安装

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

## 快速上手

```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()

    // 创建持卡人
    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)
}
```

## 配置

<Tabs>
  <Tab title="直接传参">
    ```go theme={null}
    // 沙盒（测试用）
    client, err := uqpay.NewClient(clientID, apiKey, configuration.Sandbox())

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

  <Tab title="环境变量">
    ```bash theme={null}
    export UQPAY_CLIENT_ID="your-client-id"
    export UQPAY_API_KEY="your-api-key"
    ```

    或根据示例模板创建 `.env` 文件：

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

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

## 鉴权

SDK 自动处理 OAuth2 鉴权：

* 使用 client credentials 获取访问 token
* 缓存 token 直至过期
* 自动刷新过期 token
* 线程安全的 token 管理

## 幂等性

每次 API 请求都会自动带上唯一幂等键，确保安全重试、避免重复操作。你无需手动设置。

## 错误处理

SDK 返回详细的错误信息，包含 HTTP 状态码和 API 错误详情：

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

错误格式示例：

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

## API 覆盖范围

### Banking API

| 资源                   | 操作                                                     |
| -------------------- | ------------------------------------------------------ |
| **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

| 资源               | 操作                                                       |
| ---------------- | -------------------------------------------------------- |
| **Cardholders**  | Create、Get、List                                          |
| **Cards**        | Create、Get、GetSecure、List、Recharge、Withdraw、UpdateStatus |
| **Transactions** | Get、List                                                 |
| **Products**     | List                                                     |