API / v1
Partner API integration
Read the catalog, fund a wallet and purchase digital products from your server. These public docs never place orders or accept a real key.
Before you begin
Sign in, contact support for API approval, then create a key under Account → Partner API. Start read-only; enable write permissions only after checking your integration.
Public API base URL
https://cattshop.site/api/v1This address uses public API configuration, never an internal network URL. If only a relative path is shown, prepend the store’s public origin before running an example.
Authenticate and protect your key
Send Authorization: Bearer <API_KEY> over HTTPS from your server. API keys work only with /api/v1; they are not customer or admin JWTs. Never put a key in URLs, frontend code, logs, Git or localStorage. Read it only from CATT_API_KEY or a secret manager.
{
"PartnerApiKey": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "catt_<key-id>.<random-secret>",
"description": "Created once in /account/api after approval. Send from your backend only; never put it in a browser bundle, query string or chat message."
}
}Read the catalog
Set CATT_API_KEY outside source code. These examples only GET products; avoid verbose mode that might log authentication headers. Python uses the standard library; Node needs built-in fetch.
cURL / shell
curl --fail-with-body --silent --show-error \
--header "Authorization: Bearer $CATT_API_KEY" \
"https://cattshop.site/api/v1/products"Python / urllib
import json, os, urllib.request
base = "https://cattshop.site/api/v1"
request = urllib.request.Request(
base + "/products",
headers={"Authorization": "Bearer " + os.environ["CATT_API_KEY"]},
)
with urllib.request.urlopen(request, timeout=30) as response:
print(json.load(response))Node.js / fetch
const key = process.env.CATT_API_KEY;
if (!key) throw new Error("Set CATT_API_KEY in your environment");
const response = await fetch("https://cattshop.site/api/v1/products", {
headers: { Authorization: `Bearer ${key}` },
signal: AbortSignal.timeout(30_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());Fund your wallet, then purchase
- Read /wallet and /deposit-methods. Create /deposits with method and an integer VND vndAmount within current limits. Follow the exact payment instructions and check GET /deposits/{code} until credited. Creating a deposit request does not transfer money or credit your wallet.
- Read current prices and stock, then POST /orders with variantId, quantity and optional maxTotalUsdt. The server recomputes totals, reserves stock and pays from your wallet. If funds are insufficient, top up first; do not repeatedly create orders.
- Order creation POST returns metadata only, not product keys. Use GET /orders/{code} with orders:read to retrieve delivered items. PAID means payment succeeded but delivery may still be pending; do not create another order. Read the existing order again or contact support.
Retry safely with Idempotency-Key
Every order/deposit POST requires an Idempotency-Key for that operation. Save the idempotency key and payload before sending. After a timeout or uncertain outcome, retry with the same key and identical payload; do not generate a new key. Reusing a key with a different payload returns 409. Read a known resource’s status before retrying. This is not your secret API key.
Idempotency-Key: purchase-20260918-001
Content-Type: application/json
{"items":[{"variantId":"variant-example","quantity":1}],"maxTotalUsdt":"5.000000"}Money, expiry and limits
Response amounts are decimal strings (USDT; response vndAmount is also a string). Do not add money with floating-point arithmetic. Input vndAmount is a whole VND number; maxTotalUsdt is a string. Prices, balance and stock can change. Up to 5 active keys per account; default expiry 30 days, maximum 90. Read /deposit-methods for current minVnd, maxVnd and maxPending.
{
"readPerKeyPerMinute": 120,
"readPerOwnerPerMinute": 240,
"writePerKeyPerMinute": 30,
"writePerOwnerPerMinute": 30
}Handle errors
Errors return { error: { code, message }, requestId }. 400: correct input; 401: check expiry/revocation; 403: missing scope, access not enabled or account locked; 409: idempotency or state conflict; 429: slow down and honor Retry-After when present; 503: service or payment method unavailable. Never retry an uncertain POST with a new key.
{
"type": "object",
"required": [
"error",
"requestId"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"example": "IDEMPOTENCY_CONFLICT"
},
"message": {
"type": "string"
}
}
},
"requestId": {
"type": "string"
}
}
}Endpoint reference
Rendered directly from the shared OpenAPI contract. Expand an endpoint for parameters, body, permissions and responses. There is no request execution console.
GET/api/v1/products
List active products
Owner-scoped data only. Money is returned as decimal strings.
Security / permissions
{
"security": [
{
"PartnerApiKey": []
}
],
"scope": "catalog:read"
}Parameters
[]Responses
{
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Product"
}
}
}
}
},
"400": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
},
"description": "Seconds until the rate window resets"
}
}
},
"503": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}GET/api/v1/products/{slug}
Get an active product
Owner-scoped data only. Money is returned as decimal strings.
Security / permissions
{
"security": [
{
"PartnerApiKey": []
}
],
"scope": "catalog:read"
}Parameters
[
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
]Responses
{
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Product"
}
}
}
},
"400": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
},
"description": "Seconds until the rate window resets"
}
}
},
"503": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}GET/api/v1/wallet
Read own wallet balance
Owner-scoped data only. Money is returned as decimal strings.
Security / permissions
{
"security": [
{
"PartnerApiKey": []
}
],
"scope": "wallet:read"
}Responses
{
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Wallet"
}
}
}
},
"400": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
},
"description": "Seconds until the rate window resets"
}
}
},
"503": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}GET/api/v1/deposit-methods
Read enabled wallet top-up methods
Owner-scoped data only. Money is returned as decimal strings.
Security / permissions
{
"security": [
{
"PartnerApiKey": []
}
],
"scope": "deposits:read"
}Responses
{
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DepositMethods"
}
}
}
},
"400": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
},
"description": "Seconds until the rate window resets"
}
}
},
"503": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}GET/api/v1/deposits
List API-created deposits
Owner-scoped data only. Money is returned as decimal strings.
Security / permissions
{
"security": [
{
"PartnerApiKey": []
}
],
"scope": "deposits:read"
}Parameters
[
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
}
}
]Responses
{
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DepositPage"
}
}
}
},
"400": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
},
"description": "Seconds until the rate window resets"
}
}
},
"503": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}POST/api/v1/deposits
Create an idempotent wallet top-up
Requires Idempotency-Key. New resource: 201. Replayed request: 200 with Idempotency-Replayed: true. Timeout: retry the same key and body.
Security / permissions
{
"security": [
{
"PartnerApiKey": []
}
],
"scope": "deposits:write"
}Parameters
[
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"description": "8–128 ASCII letters, digits, dot, colon, underscore or dash. Reuse for retries; do not reuse with a different body.",
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
},
"example": "purchase-20260918-001"
}
]Request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateDeposit"
},
"example": {
"method": "sepay",
"vndAmount": 130000
}
}
}
}Responses
{
"200": {
"description": "Idempotent replay; current resource state",
"headers": {
"Idempotency-Replayed": {
"schema": {
"type": "string",
"enum": [
"true"
]
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Deposit"
}
}
}
},
"201": {
"description": "Resource created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Deposit"
}
}
}
},
"400": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
},
"description": "Seconds until the rate window resets"
}
}
},
"503": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}GET/api/v1/deposits/{code}
Read own API deposit and frozen payment instructions
Owner-scoped data only. Money is returned as decimal strings.
Security / permissions
{
"security": [
{
"PartnerApiKey": []
}
],
"scope": "deposits:read"
}Parameters
[
{
"name": "code",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
]Responses
{
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Deposit"
}
}
}
},
"400": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
},
"description": "Seconds until the rate window resets"
}
}
},
"503": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}GET/api/v1/orders
List API-created orders without delivered keys
Owner-scoped data only. Money is returned as decimal strings.
Security / permissions
{
"security": [
{
"PartnerApiKey": []
}
],
"scope": "orders:read"
}Parameters
[
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
}
}
]Responses
{
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrderPage"
}
}
}
},
"400": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
},
"description": "Seconds until the rate window resets"
}
}
},
"503": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}POST/api/v1/orders
Purchase with wallet balance atomically
At most 20 distinct variants and 100 items. Server recalculates prices and discounts. No external gateway session is created. No deliveredLines in this response, even on replay. Use GET order with orders:read to retrieve delivered goods. PAID can mean delivery is pending; never create another purchase to retry delivery.
Security / permissions
{
"security": [
{
"PartnerApiKey": []
}
],
"scope": "orders:write"
}Parameters
[
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"description": "8–128 ASCII letters, digits, dot, colon, underscore or dash. Reuse for retries; do not reuse with a different body.",
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
},
"example": "purchase-20260918-001"
}
]Request body
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateOrder"
},
"example": {
"items": [
{
"variantId": "variant-example",
"quantity": 1
}
],
"maxTotalUsdt": "5.000000"
}
}
}
}Responses
{
"200": {
"description": "Idempotent replay; current resource state",
"headers": {
"Idempotency-Replayed": {
"schema": {
"type": "string",
"enum": [
"true"
]
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Order"
}
}
}
},
"201": {
"description": "Resource created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Order"
}
}
}
},
"400": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
},
"description": "Seconds until the rate window resets"
}
}
},
"503": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}GET/api/v1/orders/{code}
Read own API order and delivered keys
Owner-scoped data only. Money is returned as decimal strings.
Security / permissions
{
"security": [
{
"PartnerApiKey": []
}
],
"scope": "orders:read"
}Parameters
[
{
"name": "code",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
]Responses
{
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrderDetail"
}
}
}
},
"400": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
},
"description": "Seconds until the rate window resets"
}
}
},
"503": {
"description": "Stable machine error code; message follows Accept-Language.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}GET/api/v1/openapi.json
Download the public API contract
Security / permissions
{
"security": []
}Responses
{
"200": {
"description": "This OpenAPI document"
}
}Data schemas
Error
{
"type": "object",
"required": [
"error",
"requestId"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"example": "IDEMPOTENCY_CONFLICT"
},
"message": {
"type": "string"
}
}
},
"requestId": {
"type": "string"
}
}
}Wallet
{
"type": "object",
"required": [
"balance",
"currency"
],
"properties": {
"balance": {
"type": "string",
"pattern": "^\\d+(\\.\\d{1,6})?$",
"example": "5.000001"
},
"currency": {
"type": "string",
"enum": [
"USDT"
]
}
}
}Product
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string",
"nullable": true
},
"category": {
"type": "string",
"nullable": true
},
"variants": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"price": {
"type": "string",
"pattern": "^\\d+(\\.\\d{1,6})?$",
"example": "5.000001"
},
"currency": {
"type": "string",
"enum": [
"USDT"
]
},
"availableStock": {
"type": "integer"
}
}
}
}
}
}CreateOrder
{
"type": "object",
"additionalProperties": false,
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"variantId",
"quantity"
],
"properties": {
"variantId": {
"type": "string"
},
"quantity": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
}
}
},
"couponCode": {
"type": "string",
"maxLength": 32
},
"maxTotalUsdt": {
"type": "string",
"pattern": "^\\d+(\\.\\d{1,6})?$",
"example": "5.000001"
}
}
}CreateDeposit
{
"type": "object",
"additionalProperties": false,
"required": [
"method",
"vndAmount"
],
"properties": {
"method": {
"type": "string",
"enum": [
"sepay",
"crypto_bep20",
"crypto_trc20",
"binance_id"
]
},
"vndAmount": {
"type": "integer",
"minimum": 10000,
"maximum": 100000000
}
}
}DepositMethods
{
"type": "object",
"properties": {
"methods": {
"type": "array",
"items": {
"type": "string"
}
},
"minVnd": {
"type": "integer"
},
"maxVnd": {
"type": "integer"
},
"maxPending": {
"type": "integer",
"example": 3
}
}
}Deposit
{
"type": "object",
"properties": {
"code": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"PENDING",
"SUCCESS",
"EXPIRED",
"CANCELLED"
]
},
"method": {
"type": "string"
},
"amountUsdt": {
"type": "string",
"pattern": "^\\d+(\\.\\d{1,6})?$",
"example": "5.000001"
},
"vndAmount": {
"type": "string",
"pattern": "^\\d+(\\.\\d{1,6})?$",
"example": "5.000001"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"paidAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"instructions": {
"type": "object",
"properties": {
"network": {
"type": "string",
"nullable": true
},
"address": {
"type": "string",
"nullable": true
},
"bank": {
"type": "string",
"nullable": true
},
"accountHolder": {
"type": "string",
"nullable": true
},
"memo": {
"type": "string",
"nullable": true
}
}
}
}
}Order
{
"type": "object",
"properties": {
"code": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"PENDING",
"PAID",
"DELIVERED",
"CANCELLED",
"EXPIRED"
]
},
"totalAmount": {
"type": "string",
"pattern": "^\\d+(\\.\\d{1,6})?$",
"example": "5.000001"
},
"currency": {
"type": "string",
"enum": [
"USDT"
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"paidAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"variantId": {
"type": "string",
"nullable": true
},
"productName": {
"type": "string"
},
"variantName": {
"type": "string"
},
"unitPrice": {
"type": "string",
"pattern": "^\\d+(\\.\\d{1,6})?$",
"example": "5.000001"
},
"quantity": {
"type": "integer"
}
}
}
}
}
}OrderDetail
{
"allOf": [
{
"$ref": "#/components/schemas/Order"
},
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"deliveredLines": {
"type": "array",
"items": {
"type": "string"
},
"description": "SOLD lines for this owner only, when PAID or DELIVERED."
}
}
}
}
}
}
]
}OrderPage
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Order"
}
},
"total": {
"type": "integer"
}
}
}DepositPage
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Deposit"
}
},
"total": {
"type": "integer"
}
}
}