> ## 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 状态跟踪

> 监控和处理 ramp 交易状态

## 状态概览

Ramps 从创建到完成会经历多个状态。了解这些状态有助于您向用户提供准确的更新。

## 状态流程

```mermaid theme={null}
graph TD
    A[CREATED] --> B[CASH_IN_PROCESSING]
    B --> C[CASH_IN_COMPLETED]
    C --> D[CONVERSION_PROCESSING]
    D --> E[CONVERSION_COMPLETED]
    E --> F[CASH_OUT_PROCESSING]
    F --> G[COMPLETED]
    
    A -.-> H[CANCELED]
    B -.-> I[FAILED]
    D -.-> I
    F -.-> I
```

## 获取 Ramp 状态

```bash theme={null}
GET /api/v2/ramps/{rampId}
```

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

## 状态描述

| 状态                      | 描述        | 用户消息         |
| ----------------------- | --------- | ------------ |
| `CREATED`               | Ramp 已初始化 | "请完成支付"      |
| `CASH_IN_PROCESSING`    | 正在验证支付    | "正在处理您的支付"   |
| `CASH_IN_COMPLETED`     | 支付已确认     | "支付已收到，正在转换" |
| `CONVERSION_PROCESSING` | 正在转换货币    | "正在转换资金"     |
| `CASH_OUT_PROCESSING`   | 正在发送到目的地  | "正在交付资金"     |
| `COMPLETED`             | 交易完成      | "交易完成！"      |
| `FAILED`                | 交易失败      | "交易失败"       |
| `CANCELED`              | 用户/系统取消   | "交易已取消"      |

## 状态更新的 Webhooks

订阅 ramp 事件：

```javascript theme={null}
app.post('/webhooks/killb', (req, res) => {
  const { event, data } = req.body;
  
  switch(event) {
    case 'ramp.cash_in_completed':
      updateUI(data.id, '支付已确认');
      break;
    case 'ramp.completed':
      updateUI(data.id, '交易完成');
      notifyUser(data.userId, '资金已交付');
      break;
    case 'ramp.failed':
      updateUI(data.id, '交易失败');
      notifyUser(data.userId, data.details);
      break;
  }
  
  res.status(200).json({ received: true });
});
```

## 状态历史

获取完整的状态历史：

```bash theme={null}
GET /api/v2/ramps/{rampId}/status-history
```

```json 响应 theme={null}
[
  {
    "status": "CREATED",
    "timestamp": "2024-01-15T10:30:00.000Z"
  },
  {
    "status": "CASH_IN_PROCESSING",
    "timestamp": "2024-01-15T10:35:00.000Z"
  },
  {
    "status": "COMPLETED",
    "timestamp": "2024-01-15T10:45:00.000Z"
  }
]
```

## 最佳实践

<AccordionGroup>
  <Accordion title="主要使用 Webhooks" icon="bell">
    Webhooks 提供即时更新
  </Accordion>

  <Accordion title="轮询作为备用" icon="rotate">
    如果 webhook 失败，每 10-30 秒轮询一次
  </Accordion>

  <Accordion title="显示进度" icon="spinner">
    向用户显示当前状态和进度条
  </Accordion>

  <Accordion title="处理失败" icon="triangle-exclamation">
    检查 `details` 字段以了解失败原因
  </Accordion>
</AccordionGroup>

## 下一步

<CardGroup cols={2}>
  <Card title="Webhooks 设置" icon="bell" href="/zh/guides/webhooks/setup">
    配置 webhook 通知
  </Card>

  <Card title="错误处理" icon="shield" href="/zh/resources/error-handling">
    优雅地处理失败
  </Card>
</CardGroup>