---
title: "收银台（Checkout）"
description: "集成 Fystack 的 Checkout API，为你的用户打造流畅的支付体验。"
url: https://docs.fystack.io/zh/checkout
last_updated: 2026-11-13
---

> ## Documentation index
> Fetch the complete documentation index at: https://docs.fystack.io/llms.txt
> Use it to discover all available pages before exploring further.

# 收银台（Checkout）

Checkout API 提供了一种强大的方式，可通过 Fystack 的安全基础设施创建支付会话、管理支付流程并处理交易。

---

## 创建收银台会话

**Endpoint:** `POST /checkouts`

要创建新的收银台会话，请携带所需参数向 `/checkouts` endpoint 发送 POST 请求。

### 参数

- `price` (string, required): 以字符串表示的支付金额（例如 "66"）。
- `currency` (string, required): 三个字母的 ISO 货币代码（例如 USD、EUR）。目前仅支持 USD。
- `expiry_duration_seconds` (number, required): 收银台会话过期前的秒数。必须介于 0 到 31536000 之间。
- `destination_wallet_id` (string, required): 接收付款的钱包 ID。

  _Image: 复制钱包 ID_

### 资产参数

请提供 `supported_assets` 或 `accepted_assets` 其中之一。

- `supported_assets` (array): 支持的加密资产列表。每一项可以是资产 UUID，也可以是 "SYMBOL:CHAIN_ID" 格式的别名（例如 "SOL:1399811149"）。

  | 链 | 链 ID | 格式示例 |
  | --- | --- | --- |
  | Solana | 1399811149 | `SOL:1399811149` |
  | Ethereum | 1 | `ETH:1`, `USDC:1` |
  | BNB Chain | 56 | `BNB:56` |
  | Base | 8453 | `ETH:8453` |
  | Polygon | 137 | `POL:137` |
- `accepted_assets` (array): 以可读形式表示的支持加密资产列表。每一项包含 `asset` 和 `network`，例如网络 `ETHEREUM_MAINNET` 上的资产 `USDC`。
- `success_url` (string): 付款成功后将客户重定向到的 URL。
- `cancel_url` (string): 客户取消结账流程时将其重定向到的 URL。
- `description` (string): 客户所购买内容的描述。
- `product_id` (string): 所购买产品的唯一标识符。
- `customer_id` (string): 将此收银台会话关联到你系统中的现有客户。
- `order_id` (string): 订单的唯一标识符。
- `enable_localization` (boolean): 是否为收银台页面启用本地化。默认为 false。
- `from_address` (string): 可选的付款方地址。如果提供，Fystack 将使用单钱包支付流程。
- `underpaid_cover_percent` (number): 允许的少付容差百分比。必须介于 0 到 100 之间。

### 响应

- `id` (string): 收银台会话的唯一标识符。
- `checkout_url` (string): 托管收银台页面的 URL。请将客户重定向到此 URL。
- `status` (string): 收银台会话的状态。可以是 `Pending`、`Confirming`、`Success`、`Expired`、`Unresolved`、`Resolved` 或 `Cancelled`。
- `created_at` (timestamp): 收银台会话的创建时间。
- `updated_at` (timestamp): 收银台会话的最后更新时间。
- `currency` (string): 三个字母的 ISO 货币代码。
- `price` (string): 以字符串表示的支付金额。
- `product_id` (string): 所购买产品的唯一标识符。
- `order_id` (string): 订单的唯一标识符。
- `workspace_id` (string): 此收银台会话所属工作区的标识符。
- `description` (string): 客户所购买内容的描述。
- `supported_assets` (array): 此收银台会话支持的加密资产列表。
- `customer_id` (string): 与此收银台会话关联的客户标识符。
- `expiry_duration_seconds` (number): 收银台会话过期前的秒数。
- `enable_localization` (boolean): 收银台页面是否已启用本地化。
- `success_url` (string): 付款成功后将客户重定向到的 URL。
- `cancel_url` (string): 客户取消结账流程时将其重定向到的 URL。
- `outcome` (object|null): 付款结果信息（如有）。
- `from_address` (string|null): 付款来源地址（如有）。

**请求** `POST /checkouts`

```typescript
import { PaymentService, Environment } from '@fystack/sdk'

const paymentService = new PaymentService({
  apiKey: apiCredentials.APIKey,
  environment: Environment.Production
})

await paymentService.createCheckout({
  price: '66',
  currency: 'USD',
  supported_assets: ['SOL:1399811149', 'USDC:1399811149', 'ETH:8453', 'ETH:1', 'USDC:1'],
  description: 'Access to premium features and exclusive content.',
  success_url: 'https://example.com/payment/success',
  cancel_url: 'https://example.com/payment/cancel',
  product_id: '4c57fae9-1a54-4a1b-9d94-00d5b4a3e1d2',
  customer_id: 'bc5bd50d-265e-4ea9-b312-bd8de5118683',
  order_id: 'bc5bd50d-265e-4ea9-b312-bd8de5118683',
  enable_localization: false,
  destination_wallet_id: 'ca6b5c4d-753f-4c2d-af18-520f66a42bd4',
  expiry_duration_seconds: 3600
})
```

```bash
curl -X POST https://api.fystack.io/api/v1/checkouts \
  -H "ACCESS-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "price": "66",
    "currency": "USD",
    "supported_assets": ["SOL:1399811149", "USDC:1399811149", "ETH:8453"],
    "description": "Access to premium features and exclusive content.",
    "success_url": "https://example.com/payment/success",
    "cancel_url": "https://example.com/payment/cancel",
    "product_id": "4c57fae9-1a54-4a1b-9d94-00d5b4a3e1d2",
    "customer_id": "bc5bd50d-265e-4ea9-b312-bd8de5118683",
    "order_id": "order_123",
    "enable_localization": false,
    "destination_wallet_id": "ca6b5c4d-753f-4c2d-af18-520f66a42bd4",
    "expiry_duration_seconds": 3600
  }'
```

```json
{
  "success": true,
  "message": "success",
  "code": 0,
  "data": {
    "id": "17976d0a-e4ff-44a6-a47e-c7e2bbab3db2",
    "created_at": "2025-05-17T12:39:27.308105515+07:00",
    "updated_at": "2025-05-17T12:39:27.308105515+07:00",
    "currency": "USD",
    "product_id": "4c57fae9-1a54-4a1b-9d94-00d5b4a3e1d2",
    "order_id": "bc5bd50d-265e-4ea9-b312-bd8de5118683",
    "workspace_id": "ffb8c9d1-0bd2-4c30-bf4f-2a8fe7710d51",
    "underpaid_cover_percent": 0,
    "description": "Access to premium features and exclusive content.",
    "price": "66",
    "supported_assets": [
      {
        "id": "6f4b5818-967f-4132-a475-20fe766c6c0e",
        "created_at": "0001-01-01T00:00:00Z",
        "updated_at": "0001-01-01T00:00:00Z",
        "is_native": false,
        "is_whitelisted": false
      },
      {
        "id": "c0b89aea-08b1-4a10-a754-17f3b133be24",
        "created_at": "0001-01-01T00:00:00Z",
        "updated_at": "0001-01-01T00:00:00Z",
        "is_native": false,
        "is_whitelisted": false
      }
    ],
    "customer_id": "bc5bd50d-265e-4ea9-b312-bd8de5118683",
    "expiry_duration_seconds": 3600,
    "enable_localization": false,
    "success_url": "https://example.com/payment/success",
    "cancel_url": "https://example.com/payment/cancel",
    "status": "Pending",
    "outcome": null,
    "from_address": null,
    "checkout_url": "https://app.fystack.io/checkout/17976d0a-e4ff-44a6-a47e-c7e2bbab3db2"
  }
}
```

---

## 获取收银台会话

**Endpoint:** `GET /checkouts/:id`

根据 ID 获取收银台会话的详细信息。

### 响应

- `id` (string): 收银台会话的唯一标识符。
- `status` (string): 收银台会话的状态。可以是 `Pending`、`Confirming`、`Success`、`Expired`、`Unresolved`、`Resolved` 或 `Cancelled`。
- `price` (string): 以字符串表示的支付金额。
- `currency` (string): 三个字母的 ISO 货币代码。
- `created_at` (timestamp): 收银台会话的创建时间。
- `updated_at` (timestamp): 收银台会话的最后更新时间。
- `product_id` (string): 所购买产品的唯一标识符。
- `order_id` (string): 订单的唯一标识符。
- `workspace_id` (string): 此收银台会话所属工作区的标识符。
- `description` (string): 客户所购买内容的描述。
- `supported_assets` (array): 此收银台会话支持的加密资产列表。
- `customer_id` (string): 与此收银台会话关联的客户标识符。
- `expiry_duration_seconds` (number): 收银台会话过期前的秒数。
- `success_url` (string): 付款成功后将客户重定向到的 URL。
- `cancel_url` (string): 客户取消结账流程时将其重定向到的 URL。
- `checkout_url` (string): 托管收银台页面的 URL。
- `outcome` (object|null): 付款结果信息（如有）。
- `from_address` (string|null): 付款来源地址（如有）。

**请求** `GET /checkouts/:id`

```typescript
import { PaymentService, Environment } from '@fystack/sdk'

const paymentService = new PaymentService({
  apiKey: apiCredentials.APIKey,
  environment: Environment.Production
})

const checkout = await paymentService.getCheckout('17976d0a-e4ff-44a6-a47e-c7e2bbab3db2')
```

```bash
curl -X GET https://api.fystack.io/api/v1/checkouts/17976d0a-e4ff-44a6-a47e-c7e2bbab3db2
```

```json
{
  "success": true,
  "message": "success",
  "code": 0,
  "data": {
    "id": "2912168a-6bb6-4b5c-88bb-723706718e4a",
    "created_at": "2025-05-17T12:50:57.807741+07:00",
    "updated_at": "2025-05-17T12:50:57.807741+07:00",
    "currency": "USD",
    "product_id": "4c57fae9-1a54-4a1b-9d94-00d5b4a3e1d2",
    "order_id": "bc5bd50d-265e-4ea9-b312-bd8de5118683",
    "workspace_id": "ffb8c9d1-0bd2-4c30-bf4f-2a8fe7710d51",
    "underpaid_cover_percent": 0,
    "description": "Access to premium features and exclusive content.",
    "price": "66",
    "supported_assets": [
      {
        "id": "e9337429-a741-4e92-afbb-c1b1fc1ad8a4",
        "created_at": "2024-09-21T17:48:12.718886+07:00",
        "updated_at": "2024-09-21T17:48:12.718886+07:00",
        "name": "USD Coin",
        "symbol": "USDC",
        "decimals": 6,
        "logo_url": "https://assets-cdn.trustwallet.com/blockchains/ethereum/assets/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48/logo.png",
        "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "asset_type": "erc20",
        "is_native": false,
        "address_type": "evm",
        "is_whitelisted": true,
        "network_id": "dd21bfb5-f809-4070-a789-18ec8abbee1b"
      },
      {
        "id": "6f4b5818-967f-4132-a475-20fe766c6c0e",
        "created_at": "2024-12-05T20:32:42.14387+07:00",
        "updated_at": "2024-12-05T20:32:42.14387+07:00",
        "name": "Solana token",
        "symbol": "SOL",
        "decimals": 9,
        "logo_url": "https://upload.wikimedia.org/wikipedia/en/b/b9/Solana_logo.png",
        "is_native": true,
        "address_type": "sol",
        "is_whitelisted": true,
        "network_id": "8ae1f43f-d428-484d-8ad4-ee9ccc65a9ac"
      }
    ],
    "customer_id": "bc5bd50d-265e-4ea9-b312-bd8de5118683",
    "expiry_duration_seconds": 3600,
    "enable_localization": false,
    "success_url": "https://example.com/payment/success",
    "cancel_url": "https://example.com/payment/cancel",
    "status": "Pending",
    "outcome": null,
    "from_address": null,
    "checkout_url": "https://app.fystack.io/checkout/2912168a-6bb6-4b5c-88bb-723706718e4a"
  }
}
```

---

## 创建收银台付款

**Endpoint:** `POST /checkouts/:id/payment`

通过指定用于支付的受支持资产，为现有收银台会话创建付款。

### 参数

- `pay_asset_id` (string, required): 用于支付的资产 ID。必须是该收银台会话中受支持的资产之一。
- `customer_email` (string): 付款客户的电子邮箱地址。

### 响应

- `id` (string): 付款的唯一标识符。
- `checkout_id` (string): 关联的收银台会话 ID。
- `customer_email` (string|null): 客户的电子邮箱（如已提供）。
- `pay_asset_id` (string): 用于支付的资产 ID。
- `network_id` (string): 交易所在区块链网络的 ID。
- `expired_at` (timestamp): 付款的过期时间。
- `payer_address` (string|null): 发送付款的地址（如有）。
- `tx_hash` (string|null): 交易哈希（如有）。
- `converted_crypto_price` (string): 换算为所选加密货币后的支付金额。
- `deposit_address` (string): 付款应发送到的地址。
- `deposit_qr` (string): 包含充值地址的二维码 URL。
- `created_at` (timestamp): 付款的创建时间。
- `updated_at` (timestamp): 付款的最后更新时间。

**请求** `POST /checkouts/:id/payment`

```typescript
import { PaymentService, Environment } from '@fystack/sdk'

const paymentService = new PaymentService({
  apiKey: apiCredentials.APIKey,
  environment: Environment.Production
})

// First get the checkout to see available assets
const checkout = await paymentService.getCheckout('2912168a-6bb6-4b5c-88bb-723706718e4a')

// Then create a payment using one of the supported assets
const payment = await paymentService.createCheckoutPayment(checkout.id, {
  pay_asset_id: checkout.supported_assets[0].id
})
```

```bash
curl -X POST https://api.fystack.io/api/v1/checkouts/2912168a-6bb6-4b5c-88bb-723706718e4a/payment \
  -H "Content-Type: application/json" \
  -d '{
    "pay_asset_id": "e9337429-a741-4e92-afbb-c1b1fc1ad8a4"
  }'
```

```json
{
  "success": true,
  "message": "success",
  "code": 0,
  "data": {
    "id": "06d92c50-e6f1-4637-8c20-72cf7e7d7b8a",
    "created_at": "2025-05-17T12:50:57.925269212+07:00",
    "updated_at": "2025-05-17T12:50:57.925269212+07:00",
    "checkout_id": "2912168a-6bb6-4b5c-88bb-723706718e4a",
    "checkout": null,
    "customer_email": null,
    "pay_asset_id": "e9337429-a741-4e92-afbb-c1b1fc1ad8a4",
    "network_id": "dd21bfb5-f809-4070-a789-18ec8abbee1b",
    "network": null,
    "expired_at": "2025-05-17T13:50:57.853990519+07:00",
    "payer_address": null,
    "tx_hash": null,
    "converted_crypto_price": "66",
    "deposit_address": "0xAbE72E79729e7463cd0822700255eD03bc6BD37C",
    "deposit_qr": "https://quickchart.io/qr?size=300&margin=2&text=0xAbE72E79729e7463cd0822700255eD03bc6BD37C"
  }
}
```

---

## 获取收银台付款

**Endpoint:** `GET /checkouts/payment/:id`

根据 ID 获取收银台付款的详细信息。

### 响应

- `id` (string): 付款的唯一标识符。
- `checkout_id` (string): 关联的收银台会话 ID。
- `checkout` (object): 完整的收银台会话对象。
- `customer_email` (string|null): 客户的电子邮箱（如已提供）。
- `pay_asset_id` (string): 用于支付的资产 ID。
- `pay_asset` (object): 用于支付的资产详情。
- `network_id` (string): 交易所在区块链网络的 ID。
- `network` (object): 区块链网络详情。
- `expired_at` (timestamp): 付款的过期时间。
- `payer_address` (string|null): 发送付款的地址（如有）。
- `tx_hash` (string|null): 交易哈希（如有）。
- `converted_crypto_price` (string): 换算为所选加密货币后的支付金额。
- `deposit_address` (string): 付款应发送到的地址。
- `deposit_qr` (string): 包含充值地址的二维码 URL。
- `created_at` (timestamp): 付款的创建时间。
- `updated_at` (timestamp): 付款的最后更新时间。

**请求** `GET /checkouts/payment/:id`

```typescript
import { PaymentService, Environment } from '@fystack/sdk'

const paymentService = new PaymentService({
  apiKey: apiCredentials.APIKey,
  environment: Environment.Production
})

const checkoutPayment = await paymentService.getCheckoutPayment('06d92c50-e6f1-4637-8c20-72cf7e7d7b8a')
console.log('checkout payment', checkoutPayment)
```

```bash
curl -X GET https://api.fystack.io/api/v1/checkouts/payment/06d92c50-e6f1-4637-8c20-72cf7e7d7b8a
```

```json
{
  "success": true,
  "message": "success",
  "code": 0,
  "data": {
    "id": "06d92c50-e6f1-4637-8c20-72cf7e7d7b8a",
    "created_at": "2025-05-17T12:50:57.925269+07:00",
    "updated_at": "2025-05-17T12:50:57.925269+07:00",
    "checkout_id": "2912168a-6bb6-4b5c-88bb-723706718e4a",
    "checkout": {
      "id": "2912168a-6bb6-4b5c-88bb-723706718e4a",
      "created_at": "2025-05-17T12:50:57.807741+07:00",
      "updated_at": "2025-05-17T12:50:57.807741+07:00",
      "currency": "USD",
      "product_id": "4c57fae9-1a54-4a1b-9d94-00d5b4a3e1d2",
      "order_id": "bc5bd50d-265e-4ea9-b312-bd8de5118683",
      "workspace_id": "ffb8c9d1-0bd2-4c30-bf4f-2a8fe7710d51",
      "underpaid_cover_percent": 0,
      "description": "Access to premium features and exclusive content.",
      "price": "66",
      "supported_assets": [],
      "customer_id": "bc5bd50d-265e-4ea9-b312-bd8de5118683",
      "expiry_duration_seconds": 3600,
      "enable_localization": false,
      "success_url": "https://example.com/payment/success",
      "cancel_url": "https://example.com/payment/cancel",
      "status": "Pending",
      "outcome": null,
      "from_address": null
    },
    "customer_email": null,
    "pay_asset_id": "e9337429-a741-4e92-afbb-c1b1fc1ad8a4",
    "pay_asset": {
      "id": "e9337429-a741-4e92-afbb-c1b1fc1ad8a4",
      "symbol": "USDC",
      "name": "USD Coin",
      "logo_url": "https://assets-cdn.trustwallet.com/blockchains/ethereum/assets/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48/logo.png"
    },
    "network_id": "dd21bfb5-f809-4070-a789-18ec8abbee1b",
    "network": {
      "id": "dd21bfb5-f809-4070-a789-18ec8abbee1b",
      "name": "Ethereum",
      "logo_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRyVyCtMa_rKwrl1y0hyWcqPda3eG0vssJBAX5xQznEPw&s"
    },
    "expired_at": "2025-05-17T13:50:57.85399+07:00",
    "payer_address": null,
    "tx_hash": null,
    "converted_crypto_price": "66",
    "deposit_address": "0xAbE72E79729e7463cd0822700255eD03bc6BD37C",
    "deposit_qr": "https://quickchart.io/qr?size=300&margin=2&text=0xAbE72E79729e7463cd0822700255eD03bc6BD37C"
  }
}
```

## 收银台 Webhook

Fystack 的 Checkout API 使用 webhook 在重要事件发生时通知你的应用，例如收银台会话完成，或付款成功或失败时。

### 常见 webhook 事件

- `payment.received`：收到付款时触发。
- `payment.success`：付款成功时触发。

### 验证 webhook 事件

出于安全考虑，你应始终验证 webhook 事件，确保它们确实由 Fystack 发送。每个 webhook 请求都会在 `X-Webhook-Signature` 请求头中包含一个签名，你可以用它来验证 webhook 载荷的真实性。事件类型也包含在 `X-Webhook-Event` 请求头中。

要验证 webhook 事件，你需要：

1. webhook 事件载荷
2. 来自 `X-Webhook-Signature` 请求头的签名

使用 SDK 的 `verifyEvent` 方法，你可以在处理 webhook 之前轻松检查其是否有效。

### 事件载荷结构

- `webhook_id` (string): webhook 配置的唯一标识符。
- `resource_id` (string): 与该事件关联的资源标识符。
- `url` (string): webhook 发送到的 URL。
- `payload` (object): 实际的事件数据，包含收银台会话或付款的详细信息。
- `event` (string): 事件类型（例如 "payment.received"、"payment.success"）。

**验证 webhook 事件**

```typescript
import { APIService, Environment } from '@fystack/sdk'

// Express.js example
app.post('/webhook', express.raw({type: 'application/json'}), async (req, res) => {
  const signature = req.headers['x-webhook-signature'] as string;
  const eventType = req.headers['x-webhook-event'] as string;
  const event = req.body;

  const apiService = new APIService(apiCredentials, Environment.Production);

  try {
    const isValid = await apiService.Webhook.verifyEvent(event, signature);

    if (isValid) {
      // Process the webhook event
      if (eventType === 'payment.received') {
        const { checkout_id, tx_hash, status } = event.payload;
        console.log(`Payment received for checkout ${checkout_id}: ${tx_hash}`);
        // Update your database, notify your user, etc.
      }

      res.status(200).send('Webhook received and verified');
    } else {
      console.warn('Invalid webhook signature');
      res.status(400).send('Invalid signature');
    }
  } catch (error) {
    console.error('Webhook verification failed', error);
    res.status(400).send('Webhook verification failed');
  }
});
```

```javascript
import { APIService, Environment } from '@fystack/sdk'

// Example of manually verifying a webhook
const apiService = new APIService(apiCredentials, Environment.Production)
const event = {
  webhook_id: 'add3a1be-fc91-413c-9b4a-028f0011954a',
  resource_id: 'checkout:b065623b-dc9c-4399-964a-99850d78d289:Pending',
  url: 'https://webhook.site/3a782a92-0d1b-4848-8c57-cc0837cba513',
  payload: {
    amount: '10',
    chain_id: 11155111,
    checkout_id: '664f5839-2b5a-4b8b-8507-3b9b4815b9c1',
    checkout_payment_id: 'b2f7d8b6-4e90-43b4-be6d-a5910ef53fdd',
    deposit_address: '0x06A388F07F0EB0605D57947A7F1856a5e091940b',
    from_address: 'ACCLHbGJYGy1vSL6RjHvaraT3XZn1bXMxz5fPVRA112G',
    network_code: 'ETHER_SEPOLIA_TESTNET',
    network_id: '23d13c03-1f3c-4e2a-9aef-1771a244b7f6',
    status: 'Pending',
    timestamp: '2025-02-09T23:42:24.83521+07:00',
    tx_hash: '0x928af7fee293a501fbbe847025a19d2f42ceaf4cd000112fbba63e053c6d02ea'
  },
  event: 'payment.received'
}
const signature = '735d2bdca20d3414eb2dba1e2de54a262ca11e9fc80f6c0a05b5196fec18cce3'

const isValid = await apiService.Webhook.verifyEvent(event, signature)

if (isValid) {
  console.log('Webhook verified successfully')
  // Process the webhook
} else {
  console.warn('Invalid webhook signature')
}
```

### Webhook 载荷示例