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

# 快速开始

> 了解如何接入 SpeedPay 开放 API

本指南帮助你在数分钟内完成 SpeedPay 开放平台 API 的首次调用。

## 前置条件

接入 SpeedPay API 之前，请确保你已具备：

* 已在 SpeedPay 商户平台创建应用，获取到 **`app_id`** 与 **`签名密钥`**
* 用于调用接口的服务器环境（可访问公网 HTTPS）
* 用于接收回调的公网回调地址（用于异步通知）

## 通用约定

<CardGroup cols={2}>
  <Card title="请求方式" icon="globe">
    所有接口均为 `POST`，`Content-Type: application/json`。
  </Card>

  <Card title="鉴权" icon="key">
    通过请求头 `Authorization` 传入签名 token。
  </Card>

  <Card title="时间戳" icon="clock">
    所有请求需带 `timestamp`（Unix 秒），与服务端时差不能超过 5 分钟。
  </Card>

  <Card title="返回结构" icon="code">
    统一返回 `{ code, data, msg }`，`code = 0` 表示成功。
  </Card>
</CardGroup>

## 公共请求参数

| 参数              | 位置     | 类型      | 必选 | 说明            |
| --------------- | ------ | ------- | -- | ------------- |
| `Authorization` | header | string  | 是  | 鉴权 token      |
| `app_id`        | body   | string  | 是  | 商户平台分配的应用 ID  |
| `timestamp`     | body   | integer | 是  | 请求时间戳（Unix 秒） |

## 公共返回字段

| 字段     | 类型            | 说明                           |
| ------ | ------------- | ---------------------------- |
| `code` | integer       | `0` 表示成功，非 0 表示失败；`401` 鉴权失败 |
| `data` | object / null | 业务数据                         |
| `msg`  | string        | 描述信息或错误说明                    |

## 首次调用示例

以下示例调用「VISA 支持的国家」接口，验证鉴权与基础联通性。

<Steps>
  <Step title="准备请求">
    填入你的 `app_id` 与当前时间戳。
  </Step>

  <Step title="发起请求">
    ```bash theme={null}
    curl -X POST https://api.speedpay.hk/mc-platformapi/v1/open/et/vs/card/support/country \
      -H "Authorization: <YOUR_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "app_id": "mc-kjgyfnbhk88dhu38f",
        "timestamp": 1755185001
      }'
    ```
  </Step>

  <Step title="校验返回">
    返回 `code = 0` 即接入成功，可在 [API 参考](/api/visa/card-apply) 中查阅完整接口。
  </Step>
</Steps>

## 接口分类速览

<CardGroup cols={2}>
  <Card title="VISA 卡片" icon="credit-card" href="/api/visa/card-apply">
    申请、激活、卡信息、限额、充值、消费记录。
  </Card>

  <Card title="JCB 卡片" icon="credit-card" href="/api/jcb/card-apply">
    申请、激活、锁卡、转账、费率设置。
  </Card>

  <Card title="JCB 钱包" icon="wallet" href="/api/jcb/wallet-address">
    钱包地址与链上交易记录查询。
  </Card>

  <Card title="支撑数据" icon="database" href="/api/visa/support-country">
    国家、行业、职位、财富来源、费用类型等枚举。
  </Card>
</CardGroup>

<Tip>
  接入过程中遇到问题，可联系 [support@speedpay.com.hk](mailto:support@speedpay.com.hk)。
</Tip>