{"openapi":"3.0.3","info":{"title":"Catt Store Partner API","version":"1.0.0","description":"Approved accounts can create scoped API keys, top up their own wallet, buy digital goods and retrieve API orders. API keys never grant management access. No withdrawals, refunds or outbound partner webhooks."},"servers":[{"url":"/api/v1"}],"x-rate-limits":{"readPerKeyPerMinute":120,"readPerOwnerPerMinute":240,"writePerKeyPerMinute":30,"writePerOwnerPerMinute":30},"x-scopes":["catalog:read","wallet:read","deposits:read","deposits:write","orders:read","orders:write"],"paths":{"/products":{"get":{"summary":"List active products","security":[{"PartnerApiKey":[]}],"x-required-scope":"catalog:read","description":"Owner-scoped data only. Money is returned as decimal strings.","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"}}}}},"parameters":[]}},"/products/{slug}":{"get":{"summary":"Get an active product","security":[{"PartnerApiKey":[]}],"x-required-scope":"catalog:read","description":"Owner-scoped data only. Money is returned as decimal strings.","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"}}}}},"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}]}},"/wallet":{"get":{"summary":"Read own wallet balance","security":[{"PartnerApiKey":[]}],"x-required-scope":"wallet:read","description":"Owner-scoped data only. Money is returned as decimal strings.","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"}}}}}}},"/deposit-methods":{"get":{"summary":"Read enabled wallet top-up methods","security":[{"PartnerApiKey":[]}],"x-required-scope":"deposits:read","description":"Owner-scoped data only. Money is returned as decimal strings.","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"}}}}}}},"/deposits":{"get":{"summary":"List API-created deposits","security":[{"PartnerApiKey":[]}],"x-required-scope":"deposits:read","description":"Owner-scoped data only. Money is returned as decimal strings.","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"}}}}},"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}}]},"post":{"summary":"Create an idempotent wallet top-up","security":[{"PartnerApiKey":[]}],"x-required-scope":"deposits:write","description":"Requires Idempotency-Key. New resource: 201. Replayed request: 200 with Idempotency-Replayed: true. Timeout: retry the same key and body.","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"}}}}},"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"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDeposit"},"example":{"method":"sepay","vndAmount":130000}}}}}},"/deposits/{code}":{"get":{"summary":"Read own API deposit and frozen payment instructions","security":[{"PartnerApiKey":[]}],"x-required-scope":"deposits:read","description":"Owner-scoped data only. Money is returned as decimal strings.","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"}}}}},"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}]}},"/orders":{"get":{"summary":"List API-created orders without delivered keys","security":[{"PartnerApiKey":[]}],"x-required-scope":"orders:read","description":"Owner-scoped data only. Money is returned as decimal strings.","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"}}}}},"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}}]},"post":{"summary":"Purchase with wallet balance atomically","security":[{"PartnerApiKey":[]}],"x-required-scope":"orders:write","description":"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.","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"}}}}},"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"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrder"},"example":{"items":[{"variantId":"variant-example","quantity":1}],"maxTotalUsdt":"5.000000"}}}}}},"/orders/{code}":{"get":{"summary":"Read own API order and delivered keys","security":[{"PartnerApiKey":[]}],"x-required-scope":"orders:read","description":"Owner-scoped data only. Money is returned as decimal strings.","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"}}}}},"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}]}},"/openapi.json":{"get":{"summary":"Download the public API contract","security":[],"responses":{"200":{"description":"This OpenAPI document"}}}}},"components":{"securitySchemes":{"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."}},"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"}}}}}}