NOWPayments 使用账户会话管理充值订单；仅 IPN 由供应商携带 x-nowpayments-sig 调用。先检查当前充值能力，USD 美分与 credit_micro 为不同单位。保留原订单和 Idempotency-Key，unknown 不重建 invoice；只有官方查询核实足额 finished 才唯一入账。签名为递归排序 JSON 的 HMAC SHA512，不能由浏览器伪造付款。
身份要求
账户会话. 会话/管理写操作不在公共 Playground 执行。
接口
curl --request POST 'https://api.oneaster.ai/core/v1/billing/nowpayments/orders' \
--header 'Authorization: Bearer '"$ONEASTER_SESSION_TOKEN" \
--header 'Idempotency-Key: '"$ONEASTER_INTENT" \
--header 'Content-Type: application/json' \
--data '{
"amount_usd_cents": "1500",
"pay_currency": "usdttrc20"
}'
参数
- Idempotency-Key (header, 必填): {"type":"string","minLength":1,"maxLength":100}
请求 JSON Schema
{
"type": "object",
"additionalProperties": false,
"properties": {
"amount_usd_cents": {
"type": "string",
"pattern": "^(?:[1-9][0-9]{2,5}|1000000)$",
"maxLength": 7,
"description": "新订单1500–1000000美元美分；旧订单以原金额和原意图重放保持报价。"
},
"pay_currency": {
"anyOf": [
{
"enum": [
"usdttrc20",
"usdtbsc",
"usdterc20",
"usdtmatic",
"usdcsol",
"usdcbsc",
"usdc",
"usdcmatic"
],
"description": "币种/网络代码；省略默认USDT TRON；不能为空或使用其他链，提交后不能改变。"
},
{
"type": "null"
}
]
}
},
"required": [
"amount_usd_cents"
]
}
响应
200
创建一次托管充值订单；同意图不重复创建 invoice
{
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"additionalProperties": false,
"properties": {
"order": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"pattern": "^[0-9]+$"
},
"currency": {
"const": "usd"
},
"amount_usd_cents": {
"type": "string",
"pattern": "^(?:[1-9][0-9]{2,5}|1000000)$",
"maxLength": 7,
"description": "NOWPayments USD整数美分，100–1000000（$1–$10000）；1美分=10000 OneAster整数账务单位。"
},
"credit_micro": {
"type": "string",
"pattern": "^[0-9]+$",
"description": "整数账务单位；1 积分 = 10000 单位，1 USD = 100 积分。前端用 BigInt。"
},
"state": {
"enum": [
"creating",
"unknown",
"open",
"paid",
"expired",
"failed"
]
},
"invoice_id": {
"anyOf": [
{
"type": "string",
"pattern": "^[0-9]+$"
},
{
"type": "null"
}
]
},
"checkout_url": {
"anyOf": [
{
"type": "string",
"format": "uri",
"description": "仅本人未归档且付款窗口未超时的 open 订单返回托管付款链接；旧订单没有本地截止时间。"
},
{
"type": "null"
}
]
},
"latest_payment_status": {
"anyOf": [
{
"enum": [
"waiting",
"confirming",
"confirmed",
"sending",
"partially_paid",
"finished",
"failed",
"refunded",
"expired"
]
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"paid_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"pay_currency": {
"anyOf": [
{
"enum": [
"usdttrc20",
"usdtbsc",
"usdterc20",
"usdtmatic",
"usdcsol",
"usdcbsc",
"usdc",
"usdcmatic"
]
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"payment_window_expired": {
"type": "boolean"
}
},
"required": [
"id",
"user_id",
"currency",
"amount_usd_cents",
"credit_micro",
"state",
"invoice_id",
"checkout_url",
"latest_payment_status",
"created_at",
"updated_at",
"paid_at",
"archived",
"archived_at",
"pay_currency",
"expires_at",
"payment_window_expired"
]
},
"reused": {
"type": "boolean"
}
},
"required": [
"order",
"reused"
]
}
},
"required": [
"success",
"data"
]
}
}
}
201
创建一次托管充值订单；同意图不重复创建 invoice
{
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"success": {
"const": true
},
"data": {
"type": "object",
"additionalProperties": false,
"properties": {
"order": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"pattern": "^[0-9]+$"
},
"currency": {
"const": "usd"
},
"amount_usd_cents": {
"type": "string",
"pattern": "^(?:[1-9][0-9]{2,5}|1000000)$",
"maxLength": 7,
"description": "NOWPayments USD整数美分，100–1000000（$1–$10000）；1美分=10000 OneAster整数账务单位。"
},
"credit_micro": {
"type": "string",
"pattern": "^[0-9]+$",
"description": "整数账务单位；1 积分 = 10000 单位，1 USD = 100 积分。前端用 BigInt。"
},
"state": {
"enum": [
"creating",
"unknown",
"open",
"paid",
"expired",
"failed"
]
},
"invoice_id": {
"anyOf": [
{
"type": "string",
"pattern": "^[0-9]+$"
},
{
"type": "null"
}
]
},
"checkout_url": {
"anyOf": [
{
"type": "string",
"format": "uri",
"description": "仅本人未归档且付款窗口未超时的 open 订单返回托管付款链接；旧订单没有本地截止时间。"
},
{
"type": "null"
}
]
},
"latest_payment_status": {
"anyOf": [
{
"enum": [
"waiting",
"confirming",
"confirmed",
"sending",
"partially_paid",
"finished",
"failed",
"refunded",
"expired"
]
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"paid_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"pay_currency": {
"anyOf": [
{
"enum": [
"usdttrc20",
"usdtbsc",
"usdterc20",
"usdtmatic",
"usdcsol",
"usdcbsc",
"usdc",
"usdcmatic"
]
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"payment_window_expired": {
"type": "boolean"
}
},
"required": [
"id",
"user_id",
"currency",
"amount_usd_cents",
"credit_micro",
"state",
"invoice_id",
"checkout_url",
"latest_payment_status",
"created_at",
"updated_at",
"paid_at",
"archived",
"archived_at",
"pay_currency",
"expires_at",
"payment_window_expired"
]
},
"reused": {
"type": "boolean"
}
},
"required": [
"order",
"reused"
]
}
},
"required": [
"success",
"data"
]
}
}
}
default
错误代码见 core-api.md；供应商/数据库错误已隐藏。
{
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"success": {
"const": false
},
"error": {
"type": "object",
"additionalProperties": false,
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"type": {
"const": "oneaster_error"
}
},
"required": [
"code",
"message",
"type"
]
},
"data": {
"type": "null"
}
},
"required": [
"success",
"error",
"data"
]
}
}
}