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

# 快速开始

> 获取 Access Token 并在几分钟内完成你的第一次 UQPAY API 调用。

本指南将引导你完成 UQPAY API 的认证，并从命令行发起你的第一次请求。

## 前置条件

开始之前，请确保你已具备：

* 一个[沙盒账户](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/guide/create-a-sandbox-account.md)
* 你的 [API 密钥](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/guide/create-api-keys.md)（`x-client-id` 和 `x-api-key`）

## 认证并调用 API

**1. 获取 Access Token**

使用你的 API 凭证调用 [Access Token](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/api-reference/access-token.md) 接口，获取一个 bearer token。

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/connect/token \
  -H "x-client-id: YOUR_CLIENT_ID" \
  -H "x-api-key: YOUR_API_KEY"
```

> [accordion] 响应示例
>
> ```json theme={null}
> {
>   "auth_token": "2YotnFZFEjr1zCsicMWpAA...",
>   "expired_at": 1757449854
> }
> ```

复制 `auth_token` 的值 —— 下一步需要用到。

> [!NOTE]
>
> 生产环境下，Access Token 的有效期为 **30 分钟**。在过期前，你可以在多次 API 调用中复用它。
>
> Token 并发策略因业务线而异 —— Account Center 和 Card Issuance 允许多个 Token 共存，而 Global Account、Global Acquiring 和 Stablecoin Account 在每次签发新 Token 时会使上一个 Token 失效。详见 [Access Token 参考](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/api-reference/access-token.md)。

**2. 发起你的第一次 API 调用**

用这个 Token 调用 [列出关联账户](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/api-reference/list-connected-accounts.md)接口。该接口返回关联到你平台的账户。

```bash theme={null}
curl -X GET "https://api-sandbox.uqpaytech.com/api/v1/accounts?page_size=10&page_number=1" \
  -H "x-auth-token: Bearer YOUR_AUTH_TOKEN"
```

> [!WARNING]
>
> `x-auth-token` header 的值必须是 `Bearer ` 紧接 Token，且 `Bearer` 与 JWT 之间**只能有一个空格**。最常见的 401 错误来自下面三种情况之一：
>
> * 直接发送裸 JWT，没有加 `Bearer ` 前缀；
> * 发送了 `Bearer<token>`，中间没有空格；
> * 把 Token 放进了 `Authorization` 而不是 `x-auth-token`。
>
> header 名是 `x-auth-token`，不是 `Authorization`。

> [accordion] 响应示例
>
> ```json theme={null}
> {
>   "total_pages": 1,
>   "total_items": 1,
>   "data": [
>     {
>       "account_id": "f5bb6498-552e-40a5-b14b-616aa04ac1c1",
>       "short_reference_id": "P220406-LLCVLRM",
>       "business_code": ["BANKING"],
>       "account_name": "UQPAY PTE LTD.",
>       "entity_type": "COMPANY",
>       "status": "ACTIVE",
>       "verification_status": "APPROVED",
>       "country": "SG",
>       "contact_details": {
>         "email": "example@company.com"
>       }
>     }
>   ]
> }
> ```

如果返回结果里包含 `data`，说明你的集成已经跑通。

## 配置 Webhooks

UQPAY 使用 Webhook 在异步事件发生时通知你的应用 —— 例如支付成功或出款完成。配置 Webhook 端点后，你无需轮询 API 获取状态更新。

1. 在控制台[配置通知 URL](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/guide/webhooks-setting.md)，并订阅与你的集成相关的事件类型。
2. 查阅 [Webhooks 概览](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/guide/webhooks-overview.md)，了解 payload 结构、重试逻辑和签名验证。

> [!TIP]
>
> 你可以随时配置 Webhook，但尽早配置能确保你在开发阶段不会遗漏任何事件。

## 下一步

你已经完成认证，可以调用任意 UQPAY API。根据你的使用场景选择对应的产品继续探索：

> [card] [Global Acquiring](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/guide/overview.md)
>
> 接收卡支付和电子钱包支付。

> [card] [Global Account](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/guide/overview.md)
>
> 收款、出款和货币兑换。

> [card] [Card Issuance](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/overview.md)
>
> 签发并管理虚拟卡或实体卡。

> [card] [Stablecoin Account](https://developers-sandbox.uqpaytech.com/docs/zh/stablecoin-account/v1.6/guide/stablecoin-account-api-publisher-disclaimer.md)
>
> 在法币和稳定币之间出入金。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.