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

# 账户概览

> 了解和管理支付账户

## 什么是账户？

账户代表 ramp 交易中资金的来源或目的地。用户可以拥有多个不同类型的账户，以支持各种支付方式和用例。

<Info>
  每个账户都链接到特定用户，在交易中使用前必须经过验证。
</Info>

## 账户类型

<CardGroup cols={2}>
  <Card title="银行账户" icon="building-columns" href="/zh/guides/accounts/bank-accounts">
    **PSE, SPEI, ACH, Wire**

    用于接收本地货币的传统法币银行账户。

    用于：Off-ramps（加密货币 → 法币）
  </Card>

  <Card title="加密货币钱包" icon="wallet" href="/zh/guides/accounts/crypto-wallets">
    **多个网络上的 USDC/USDT**

    用于接收加密货币的区块链钱包地址。

    用于：On-ramps（法币 → 加密货币）
  </Card>
</CardGroup>

## 快速开始

<Steps>
  <Step title="创建用户">
    在添加账户之前，用户必须存在

    ```bash theme={null}
    POST /api/v2/users
    ```
  </Step>

  <Step title="选择账户类型">
    Off-ramps 使用银行账户，on-ramps 使用钱包
  </Step>

  <Step title="创建账户">
    提交账户详情

    ```bash theme={null}
    POST /api/v2/accounts
    ```
  </Step>

  <Step title="等待验证">
    验证后，账户状态变为 ACTIVE
  </Step>

  <Step title="在 Ramps 中使用">
    创建 ramps 时引用账户 ID
  </Step>
</Steps>

## 创建账户

### 银行账户示例

```json theme={null}
{
  "type": "PSE",
  "userId": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
  "externalId": "bank-account-1",
  "data": {
    "firstName": "Juan",
    "lastName": "García",
    "email": "juan@example.com",
    "phone": "+573001234567",
    "accountNumber": "1234567890",
    "bankCode": "0001",
    "type": "savings",
    "countryCode": "CO",
    "document": {
      "type": "NUIP",
      "number": "1234567890",
      "issuedCountryCode": "CO"
    }
  }
}
```

### 钱包账户示例

```json theme={null}
{
  "type": "WALLET",
  "userId": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
  "externalId": "wallet-1",
  "data": {
    "firstName": "Juan",
    "lastName": "García",
    "email": "juan@example.com",
    "phone": "+573001234567",
    "currency": "USDC",
    "network": "POLYGON",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "countryCode": "CO",
    "document": {
      "type": "NUIP",
      "number": "1234567890",
      "issuedCountryCode": "CO"
    }
  }
}
```

## 查询账户

### 获取所有用户账户

```bash theme={null}
GET /api/v2/accounts/userId/{userId}
```

```javascript theme={null}
const getUserAccounts = async (userId) => {
  const response = await fetch(
    `https://sandbox.killb.app/api/v2/accounts/userId/${userId}`,
    {
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  
  return await response.json();
};
```

### 搜索账户

```bash theme={null}
GET /api/v2/accounts?userId=user-id&type=WALLET
```

**过滤器：**

* `ids` - 特定账户 ID（逗号分隔）
* `userId` - 按用户过滤
* `type` - 账户类型
* `accountNumber` - 银行账户号码
* `address` - 钱包地址
* `limit`, `page` - 分页

### 按 ID 获取账户

```bash theme={null}
GET /api/v2/accounts/{accountId}
```

## 更新账户

创建后只能更新有限字段：

```bash theme={null}
PATCH /api/v2/accounts/{accountId}
```

<CodeGroup>
  ```json 更新 PSE 账户 theme={null}
  {
    "type": "PSE",
    "data": {
      "accountNumber": "9876543210",
      "bankCode": "0002",
      "type": "checking"
    }
  }
  ```

  ```json 更新钱包 theme={null}
  {
    "type": "WALLET",
    "data": {
      "address": "0xNEW_ADDRESS_HERE",
      "network": "SOLANA"
    }
  }
  ```
</CodeGroup>

<Note>
  更新某些字段可能需要重新验证，并将账户状态设置回 PENDING。
</Note>

## 删除账户

```bash theme={null}
DELETE /api/v2/accounts/{accountId}
```

```javascript theme={null}
const deleteAccount = async (accountId) => {
  const response = await fetch(
    `https://sandbox.killb.app/api/v2/accounts/${accountId}`,
    {
      method: 'DELETE',
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  
  if (response.ok) {
    console.log('Account deleted');
  }
};
```

<Warning>
  在待处理或处理中的 ramps 中使用的账户无法删除。
</Warning>

## 账户验证

账户经过验证流程：

```mermaid theme={null}
graph LR
    A[已创建] -->|自动检查| B[验证中]
    B -->|有效| C[ACTIVE]
    B -->|无效| D[REJECTED]
    C -->|用户请求| E[已删除]
```

**状态：**

* `ACTIVE` - 可用于交易
* `PENDING` - 验证中
* `REJECTED` - 验证失败
* `INACTIVE` - 已禁用

## 多个账户

用户可以拥有多个账户：

```javascript theme={null}
const userAccounts = await getUserAccounts(userId);

// 按类型分组
const groupedAccounts = {
  banks: userAccounts.filter(a => ['PSE', 'SPEI', 'ACH'].includes(a.type)),
  wallets: userAccounts.filter(a => a.type === 'WALLET')
};

// 查找默认账户
const defaultWallet = userAccounts.find(a => 
  a.type === 'WALLET' && 
  a.data.network === 'POLYGON' &&
  a.data.currency === 'USDC'
);
```

## 最佳实践

<AccordionGroup>
  <Accordion title="创建前验证" icon="check-double">
    ```javascript theme={null}
    // 验证银行代码是否存在
    const banks = await getBanks('CO');
    const validBank = banks.find(b => b.code === bankCode);

    // 验证钱包地址格式
    const isValidAddress = /^0x[a-fA-F0-9]{40}$/.test(address);

    // 检查重复
    const existing = await findAccount({ userId, address });
    ```
  </Accordion>

  <Accordion title="使用外部 ID" icon="hashtag">
    ```javascript theme={null}
    {
      "externalId": `${yourUserId}-wallet-polygon-usdc`,
      // 使查找变得容易并防止重复
    }
    ```
  </Accordion>

  <Accordion title="处理验证延迟" icon="clock">
    ```javascript theme={null}
    if (account.status === 'PENDING') {
      showMessage('账户验证进行中');
      // 1 小时后检查或等待 webhook
    }
    ```
  </Accordion>

  <Accordion title="提供清晰的标签" icon="tag">
    ```javascript theme={null}
    // 帮助用户识别账户
    const accountLabel = account.type === 'WALLET'
      ? `${account.data.currency} on ${account.data.network}`
      : `${account.data.bankCode} - ${account.data.accountNumber.slice(-4)}`;
    ```
  </Accordion>
</AccordionGroup>

## 下一步

<CardGroup cols={2}>
  <Card title="银行账户" icon="building-columns" href="/zh/guides/accounts/bank-accounts">
    为不同国家设置银行账户
  </Card>

  <Card title="加密货币钱包" icon="wallet" href="/zh/guides/accounts/crypto-wallets">
    配置加密货币钱包账户
  </Card>

  <Card title="预充值账户" icon="bolt" href="/zh/guides/pre-fund/pre-fund-accounts">
    启用即时结算
  </Card>

  <Card title="API 参考" icon="code" href="/api-reference/endpoint/accounts-create">
    完整的账户 API 文档
  </Card>
</CardGroup>