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

# 快速开始

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

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

<h2 id="prerequisites">前置条件</h2>

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

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

<h2 id="authenticate-and-call-the-api">认证并调用 API</h2>

<Steps>
  <Step title="获取 Access Token">
    使用你的 API 凭证调用 [Access Token](/zh/account-center/v1.6/api-reference/access-token) 接口，获取一个 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 title="响应示例">
      ```json theme={null}
      {
        "auth_token": "2YotnFZFEjr1zCsicMWpAA...",
        "expired_at": 1757449854
      }
      ```
    </Accordion>

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

    <Note>
      生产环境下，Access Token 的有效期为 **30 分钟**。在过期前，你可以在多次 API 调用中复用它。

      Token 并发策略因业务线而异 —— Account Center 和 Card Issuance 允许多个 Token 共存，而 Global Account、Global Acquiring 和 Stablecoin Account 在每次签发新 Token 时会使上一个 Token 失效。详见 [Access Token 参考](/zh/account-center/v1.6/api-reference/access-token)。
    </Note>
  </Step>

  <Step title="发起你的第一次 API 调用">
    用这个 Token 调用 [列出关联账户](/zh/account-center/v1.6/api-reference/list-connected-accounts)接口。该接口返回关联到你平台的账户。

    ```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`。
    </Warning>

    <Accordion title="响应示例">
      ```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"
            }
          }
        ]
      }
      ```
    </Accordion>

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

<h2 id="set-up-webhooks">配置 Webhooks</h2>

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

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

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

<h2 id="next-steps">下一步</h2>

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

<CardGroup cols={2}>
  <Card title="Global Acquiring" icon="cash-register" href="/zh/global-acquiring/v1.6/guide/overview">
    接收卡支付和电子钱包支付。
  </Card>

  <Card title="Global Account" icon="building-columns" href="/zh/global-account/v1.6/guide/overview">
    收款、出款和货币兑换。
  </Card>

  <Card title="Card Issuance" icon="credit-card" href="/zh/card-issuance/v1.6/guide/overview">
    签发并管理虚拟卡或实体卡。
  </Card>

  <Card title="Stablecoin Account" icon="arrow-right-arrow-left" href="/zh/stablecoin-account/v1.6/guide/stablecoin-account-api-publisher-disclaimer">
    在法币和稳定币之间出入金。
  </Card>
</CardGroup>