收银台（Checkout）

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

创建收银台会话

POST

/checkouts

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

参数

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

资产参数

请提供 supported_assets 或 accepted_assets 其中之一。

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

链	链 ID	格式示例
Solana	1399811149	`SOL:1399811149`
Ethereum	1	`ETH:1`, `USDC:1`
BNB Chain	56	`BNB:56`
Base	8453	`ETH:8453`
Polygon	137	`POL:137`

响应

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

请求

POST

/checkouts

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
})

Response

200

{
  "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"
  }
}

获取收银台会话

GET

/checkouts/{id}

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

响应

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

请求

GET

/checkouts/:id

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')

Response

200

{
  "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"
  }
}

创建收银台付款

POST

/checkouts/{id}/payment

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

参数

Name
pay_asset_id
Type
string
Required
required
Description
用于支付的资产 ID。必须是该收银台会话中受支持的资产之一。
Name
customer_email
Type
string
Description
付款客户的电子邮箱地址。

响应

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

请求

POST

/checkouts/:id/payment

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
})

Response

200

{
  "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"
  }
}

获取收银台付款

GET

/checkouts/payment/{id}

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

响应

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

请求

GET

/checkouts/payment/:id

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)

Response

200

{
  "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 事件，你需要：

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

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

事件载荷结构

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

验证 webhook 事件

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');
  }
});

收银台（Checkout）

创建收银台会话

参数

资产参数

响应

请求

Response

获取收银台会话

响应

请求

Response

创建收银台付款

参数

响应

请求

Response

获取收银台付款

响应

请求

Response

收银台 Webhook

常见 webhook 事件

验证 webhook 事件

事件载荷结构

验证 webhook 事件

Webhook 载荷示例