---
title: 账单
description: 在 Coinetic 加密货币支付网关中通过 API 创建账单：字段、可支付资产（USDT、USDC、比特币等）、幂等性、账单状态、金额与汇率，以及逾期付款的处理。
url: https://coinetic.money/zh/docs/invoices/
lang: zh-Hans
---

# 账单

一张账单对应一次购买：以法币或稳定币计价的价格、有效期，以及顾客选择后确定的支付币种和收款地址。

## 创建

`POST /v1/invoices`

请求头：`Authorization`（[CP-HMAC](https://coinetic.money/zh/docs/authentication/)）、`Idempotency-Key`、`Content-Type: application/json`。

`请求体`

```json
{
  "order_id": "ORDER-1001",
  "price_amount": "49.99",
  "price_currency": "USD",
  "allowed_assets": ["USDT-TRON", "USDC-BASE", "BTC"],
  "return_url": "https://shop.example/orders/ORDER-1001",
  "expires_in_seconds": 1800,
  "metadata": { "user_id": "42", "plan": "pro" }
}
```

| 字段 | 必填 | 规则 |
| --- | --- | --- |
| `order_id` | 是 | 1–128 个字符，在商户范围内唯一（重复将返回 `409 duplicate_order`） |
| `price_amount` | 是 | 大于 0 的十进制**字符串**，小数点后最多 18 位 |
| `price_currency` | 是 | `USD`、`EUR`、`USDT` 或 `USDC` |
| `allowed_assets` | 否 | 最多 30 个资产 id（`GET /v1/assets`）。留空表示所有可用资产。账单实际采用与可用资产的**交集**；交集为空则返回 `422 invalid_allowed_assets` |
| `return_url` | 否 | `https://…`，用于「返回商店」按钮 |
| `expires_in_seconds` | 否 | 300–86 400，默认 1800（30 分钟） |
| `metadata` | 否 | 最多 20 个键，键名格式 `[A-Za-z0-9_.-]{1,64}`，值最长 500 个字符；会在账单中原样返回 |

响应 `201`：

```json
{
  "id": "inv_x7k2…",
  "order_id": "ORDER-1001",
  "status": "created",
  "price_amount": "49.99",
  "price_currency": "USD",
  "allowed_assets": ["USDT-TRON", "BTC"],
  "checkout_url": "https://pay.coinetic.money/pay/inv_x7k2…#t=…",
  "return_url": "https://shop.example/orders/ORDER-1001",
  "expires_at": "2026-10-12T15:30:00Z",
  "created_at": "2026-10-12T15:00:00Z",
  "quote": null,
  "paid_amount": "0", "outstanding_amount": "0", "overpaid_amount": "0",
  "refunded_amount": "0", "refundable_amount": "0",
  "payments": [],
  "metadata": { "user_id": "42", "plan": "pro" },
  "livemode": true
}
```

- `price_amount` 以规范形式返回，去掉末尾的零：传入 `"3.00"` 会返回 `"3"`。请按十进制数比较金额，不要用 float，也不要逐字节比较。
- `checkout_url` 在 `#` 之后包含支付页面的令牌。请勿将其写入日志或公开。
- `livemode: false` 表示沙盒账单。生产环境的商店应拒绝此类账单。

### 哪些资产会出现在账单中

资产可用的条件是：Coinetic 已启用该资产，您在该网络上有有效的收款钱包，并且您没有在后台（「设置」→「可支付资产」）中将其排除。每种资产都有最低金额（`GET /v1/assets` 中的 `min_amount`）：如果账单金额折算成该资产后低于最低金额，该资产就不会出现在账单中。例如：BTC = 60 000 USD 时，一张 3 USD 的账单折合 5 000 聪，而最低金额为 10 000 聪，因此这张账单只会提供稳定币。

`selectable_assets` 字段列出 `allowed_assets` 中当前可以选择的资产；支付页面只展示这些资产。

## 幂等性

- `Idempotency-Key`：8–128 个可打印 ASCII 字符，不含空格，且不能以 `d:` 开头。建议基于订单号生成，例如 `order-ORDER-1001`。
- 相同的键和相同的请求体，返回**相同的响应**（同一张账单）。
- 相同的键但请求体不同，返回 `409 idempotency_conflict`。
- 首次请求仍在处理中，返回 `409 idempotency_in_progress`，请一秒后重试。
- 因业务规则被拒绝的结果（例如 `422`）同样会被记住。

## 查询

`GET /v1/invoices/{id}`

顾客选择币种后，账单中会出现 `quote`：

`quote`

```json
{
  "asset_id": "USDT-TRON", "network": "tron", "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "address": "TX…", "amount_due": "49990000", "decimals": 6, "display_amount": "49.99",
  "payment_uri": "tron:…", "rate": "1", "rate_valid_until": null,
  "network_warning": "请仅通过 TRON 网络（TRC-20）发送 USDT…"
}
```

`payments` 为付款列表：`tx_hash`、`amount`（以最小单位计）、`confirmations`、`required_confirmations`、`state`（`mempool`、`included`、`confirmed`、`reorged`、`replaced`、`failed`、`dropped`）。

`unmatched_payments` 为转入账单地址但**未计入**的转账：来自其他 EVM 网络（`wrong_network`），或使用了不在白名单中的代币（`token_not_whitelisted`）。它们不会改变账单状态和 `paid_amount`。

## 列表

`GET /v1/invoices?status=paid&from=…&to=…&limit=50&cursor=…`

响应：`{ "items": [...], "next_cursor": "…" | null }`，按从新到旧排序，`limit` 取值 1–200。

## 状态

| 状态 | 含义 | 商店应如何处理 |
| --- | --- | --- |
| `created` | 账单已创建，尚未选择币种 | 等待 |
| `awaiting_payment` | 已选择币种并分配地址 | 等待 |
| `detected` | 链上已看到付款（内存池） | 显示「已检测到付款」，**不要发货** |
| `confirming` | 已打包进区块，确认数尚未达到要求 | 显示进度，**不要发货** |
| `paid` | 已足额支付并确认 | **完成订单** |
| `overpaid` | 支付金额超出应付金额 | 完成订单；多付部分可按需退款 |
| `underpaid` | 已确认金额少于应付金额（扣除容差后） | 请顾客向同一地址补付 |
| `expired` | 已过期，未收到付款 | 提供新账单（见下文） |
| `late_payment` | 付款在过期后才到账 | 由您决定：完成订单或退款 |
| `manual_review` | 付款正在接受 AML 审查 | 等待审查结果；不要发货 |
| `refunded`、`cancelled` | 已关闭 | 不要发货 |

> **核心规则.** 仅当通过 `GET /v1/invoices/{id}` 获取到 `paid` 或 `overpaid` 状态时才完成订单。

### 过期后使用稳定币付款

以 USD 计价的账单用 USDT 或 USDC 支付不存在汇率风险，因此过期后（30 天内）的付款会被自动计入：已收到 `invoice.expired` 的账单会变为 `paid`，并发送带有 `data.late: true` 的 `invoice.paid`。因此，**请不要因为 `invoice.expired` 就不可逆地关闭订单**。对于波动性资产，此类付款会进入 `late_payment` 状态。

## 金额与汇率

- 价格以账单币种设定。顾客选择支付币种时，Coinetic 会锁定对应的加密货币金额。
- **与计价币种对应的稳定币**（USD 账单使用 USDT）：按 1:1 计算，金额在账单有效期内固定不变。
- **波动性资产**（BTC、ETH 等）：取 Kraken、Coinbase 和 Bitstamp 汇率的中位数，锁定 20 分钟。
- `amount_due` 以资产的最小单位表示（TRON 上的 USDT 为 6 位小数：`"49990000"` = 49.99）。`display_amount` 是同一金额的常规写法。
- 少付容差（默认 0.5%）用于覆盖钱包的舍入误差。

参考汇率：`GET /v1/rates?base=BTC&quote=USD`。请不要据此向顾客展示“精确”的加密货币金额：只有账单给出的金额才具有约束力。