## 卡 API 文档

> **推荐：** 您可以使用 [infini-skill](https://github.com/infini-money/infini-skill) 更快接入 Infini API。该 Skill 提供开箱即用的卡 API 接入能力，可帮助您先完成流程联调，再按需参考下方原始 API 文档。


卡相关接口用于为企业成员申请、查询、批量查询状态、获取交易、查看敏感信息、充值、赎回、冻结和解冻企业卡。

所有卡接口前缀：

`/v2/cards`

### 卡片标识

商户可用的卡片唯一标识为内部 **`id`**：

- **`POST /v2/cards/apply`** 成功响应中的 **`data.id`**
- **`GET /v2/cards/list`** 各项的 **`cards[].id`**
- 传给 **`GET /v2/cards/status`**、**`GET /v2/cards/transactions`**、**`POST /v2/cards/reveal`**、**`POST /v2/cards/top-up`**、**`POST /v2/cards/redeem`**、**`POST /v2/cards/freeze`**、**`POST /v2/cards/unfreeze`** 的 **`id`**
- 传给 **`POST /v2/cards/status/batch`** 的 **`card_ids`** 中的各个值


### 认证与权限

所有接口使用 **HMAC-SHA256** 认证：携带 **`Date`**、有请求体时携带 **`Digest`**，以及带 **`keyId`** 的 **`Authorization`** 请求头。计算方式见 [章节 4：授权与安全机制](/zh/docs/en/4-authorization)。

| 权限 | 适用接口 |
|  --- | --- |
| `card.create` | `POST /v2/cards/apply`、`GET /v2/cards/list`、`GET /v2/cards/status`、`POST /v2/cards/status/batch`、`GET /v2/cards/transactions`、`POST /v2/cards/top-up`、`POST /v2/cards/redeem`、`POST /v2/cards/freeze`、`POST /v2/cards/unfreeze` |
| `card.reveal` | `POST /v2/cards/reveal` |


> **IP 白名单：** 包含 `card.create` 或 `card.reveal` 权限的 API Key，必须在商户后台创建或更新时配置非空的 IP 白名单。


### 响应信封

所有接口统一使用 `code` / `message` / `data` 信封，`code === 0` 表示业务成功，非零 `code` 表示错误，详情见 `message`。

### 申请企业卡

**POST** /v2/cards/apply

为企业成员创建一张企业卡的申请及首次充值流程。

- **所需权限：** `card.create`


#### Request Body

| 字段 | 类型 | 必填 | 说明 |
|  --- | --- | --- | --- |
| product_id | integer | 是 | 卡产品 ID。`1` = Infini Lite，`2` = Infini Pro，`102` = Infini AI |
| top_up_amount | string | 是 | 首次充值金额，小数字符串 |
| token_type | string | 是 | 代币类型，例如 `USDT`、`USDC` |
| user_email | string | 是 | 商户组织下企业成员的业务账号邮箱 |
| holder_name | string | 是 | 持卡人姓名 |
| card_alias | string | 否 | 可选的卡片别名 |


#### 产品 ID

| product_id | 产品 |
|  --- | --- |
| `1` | Infini Lite |
| `2` | Infini Pro |
| `102` | Infini AI |


#### 请求示例

```json
{
  "product_id": 1,
  "top_up_amount": "100.00",
  "token_type": "USDT",
  "user_email": "jane@example.com",
  "holder_name": "Jane Doe",
  "card_alias": "Travel card"
}
```

#### 响应示例

```json
{
  "code": 0,
  "message": "",
  "data": {
    "id": "a441831c-a5c7-4bed-8f61-793738afd5bc",
    "status": "init",
    "total_top_up_amount": "100.00",
    "total_fee": "1.00",
    "total_pay_amount": "101.00",
    "message": ""
  }
}
```

### 查询企业卡列表

**GET** /v2/cards/list

按分页返回当前商户名下的企业卡列表。

- **所需权限：** `card.create`


#### 请求参数

| 字段 | 类型 | 必填 | 说明 |
|  --- | --- | --- | --- |
| status | string | 否 | 按卡片状态过滤；多个值以英文逗号分隔，例如 `active,pending` |
| card_alias | string | 否 | 按卡片别名过滤 |
| page | integer | 否 | 页码，从 `1` 开始；默认 `1` |
| page_size | integer | 否 | 每页数量，最大 `100`；默认 `20` |


#### 响应示例

```json
{
  "code": 0,
  "message": "",
  "data": {
    "cards": [
      {
        "id": "a441831c-a5c7-4bed-8f61-793738afd5bc",
        "mask": "411111******1111",
        "holder_name": "Jane Doe",
        "card_alias": "Travel card",
        "status": "active",
        "currency": "USD",
        "available_balance": "50.25",
        "user_id": "usr_01HXYZ",
        "created_at": 1714464000,
        "updated_at": 1714550400
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20,
    "total_pages": 1
  }
}
```

### 查询卡片状态

**GET** /v2/cards/status?id={id}

返回单张卡的生命周期状态及基础信息。申请提交后可用本接口轮询，直到 `status` 变为 `active`。

- **所需权限：** `card.create`


#### 请求参数

| 字段 | 类型 | 必填 | 说明 |
|  --- | --- | --- | --- |
| id | string | 是 | 申请或列表返回的卡片内部 `id` |


#### 响应示例

```json
{
  "code": 0,
  "message": "",
  "data": {
    "id": "a441831c-a5c7-4bed-8f61-793738afd5bc",
    "status": "pending",
    "card_alias": "Travel card",
    "mask": "",
    "holder_name": "Jane Doe",
    "currency": "USD",
    "available_balance": "0",
    "user_id": "usr_01HXYZ",
    "created_at": 1714464000,
    "updated_at": 1714464100
  }
}
```

### 批量查询卡片状态

**POST** /v2/cards/status/batch

批量返回最多 100 张卡的生命周期状态，结果顺序与请求顺序一致。

- **所需权限：** `card.create`


#### Request Body

| 字段 | 类型 | 必填 | 说明 |
|  --- | --- | --- | --- |
| card_ids | 字符串数组 | 是 | 申请或列表返回的卡片内部 ID；最少 `1` 个，最多 `100` 个 |


#### 请求示例

```json
{
  "card_ids": [
    "a441831c-a5c7-4bed-8f61-793738afd5bc",
    "b552942d-b6d8-5cef-9062-804849bfe6cd"
  ]
}
```

#### 响应示例

```json
{
  "code": 0,
  "message": "",
  "data": {
    "cards": [
      {
        "card_id": "a441831c-a5c7-4bed-8f61-793738afd5bc",
        "status": "active"
      },
      {
        "card_id": "b552942d-b6d8-5cef-9062-804849bfe6cd",
        "status": "pending"
      }
    ]
  }
}
```

### 查询卡片交易

**GET** /v2/cards/transactions?id={id}&page={page}&page_size={page_size}

分页返回单张企业卡的交易列表。响应使用商户可见的卡片内部 ID，不暴露供应商交易 ID。

- **所需权限：** `card.create`


#### 请求参数

| 字段 | 类型 | 必填 | 说明 |
|  --- | --- | --- | --- |
| id | string | 是 | 申请或列表返回的卡片内部 `id` |
| page | integer | 否 | 页码，从 `1` 开始；默认 `1` |
| page_size | integer | 否 | 每页数量，最大 `100`；默认 `20` |


#### 响应示例

```json
{
  "code": 0,
  "message": "",
  "data": {
    "transactions": [
      {
        "card_id": "a441831c-a5c7-4bed-8f61-793738afd5bc",
        "type": "Consume",
        "amount": "12.34",
        "fee": "0.12",
        "status": "Completed",
        "currency": "USD",
        "merchant": "Example Store",
        "transaction_time": 1710000000,
        "transaction_currency": "EUR",
        "transaction_amount": "11.20",
        "created_at": 1710000001,
        "updated_at": 1710000002,
        "settled_at": 1710000003
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20,
    "total_pages": 1
  }
}
```

### 查询卡敏感信息

**POST** /v2/cards/reveal

返回完整卡号、CVV 与有效期等敏感信息。请勿在客户端日志中输出或持久化保存这些数据。

- **所需权限：** `card.reveal`


#### Request Body

| 字段 | 类型 | 必填 | 说明 |
|  --- | --- | --- | --- |
| id | string | 是 | 申请或列表返回的卡片内部 `id` |


#### 请求示例

```json
{
  "id": "a441831c-a5c7-4bed-8f61-793738afd5bc"
}
```

#### 响应示例

```json
{
  "code": 0,
  "message": "",
  "data": {
    "card_number": "4111111111111111",
    "cvv": "123",
    "expiration_mmyy": "1228",
    "card_currency": "USD"
  }
}
```

### 卡片充值

**POST** /v2/cards/top-up

为企业卡充值。

- **所需权限：** `card.create`


#### Request Body

| 字段 | 类型 | 必填 | 说明 |
|  --- | --- | --- | --- |
| id | string | 是 | 申请或列表返回的卡片内部 `id` |
| amount | string | 是 | 充值金额 |
| token_type | string | 是 | 代币类型，例如 `USDT`、`USDC` |
| note | string | 否 | 可选的充值备注 |


#### 响应示例

```json
{
  "code": 0,
  "message": "",
  "data": {
    "tx_id": "tx_123",
    "card_balance": "150.25"
  }
}
```

### 卡片赎回

**POST** /v2/cards/redeem

从企业卡赎回资金。

- **所需权限：** `card.create`


#### Request Body

| 字段 | 类型 | 必填 | 说明 |
|  --- | --- | --- | --- |
| id | string | 是 | 申请或列表返回的卡片内部 `id` |
| amount | string | 是 | 赎回金额 |
| token_type | string | 是 | 代币类型，例如 `USDT`、`USDC` |
| note | string | 否 | 可选的赎回备注 |


#### 响应示例

```json
{
  "code": 0,
  "message": "",
  "data": {
    "tx_id": "tx_123",
    "card_balance": "80.25"
  }
}
```

### 冻结卡片

**POST** /v2/cards/freeze

冻结一张企业卡。

- **所需权限：** `card.create`


#### Request Body

| 字段 | 类型 | 必填 | 说明 |
|  --- | --- | --- | --- |
| id | string | 是 | 申请或列表返回的卡片内部 `id` |


#### 响应示例

```json
{
  "code": 0,
  "message": "",
  "data": {
    "success": true,
    "message": "Card frozen"
  }
}
```

### 解冻卡片

**POST** /v2/cards/unfreeze

解冻一张企业卡。

- **所需权限：** `card.create`


#### Request Body

| 字段 | 类型 | 必填 | 说明 |
|  --- | --- | --- | --- |
| id | string | 是 | 申请或列表返回的卡片内部 `id` |


#### 响应示例

```json
{
  "code": 0,
  "message": "",
  "data": {
    "success": true,
    "message": "Card unfrozen"
  }
}
```