Skip to main content

​
Scope

Commerce APIs cover checkout initiation/verification, catalog reads, marketplace listings, KYC session helpers, and balance-aware purchase flows.

​
Endpoint map

  • Checkout: /api/checkout/crypto, /api/checkout/crypto/verify, /api/checkout/dsports-cash. POST /api/checkout/crypto/verify confirms pack purchases. PUT /api/packs/{id}/purchase is 410 GONE.
  • Cash balance: /api/dsports-cash, /api/dsports-cash/ledger
  • Public reads: /api/commerce, /api/packs/{id}/odds, /api/v1/product_entitlement_mapping
  • Authenticated rate: GET /api/v1/exchange-rate — CHF ↔ D-Sports Cash for the mobile buy sheet. Requires a Clerk session (401 without one).
  • Catalog: /api/products (retired Frontline Pack / Frontline Pass rows are hidden even if they remain in the database)
  • Revenue webhooks (platform integration): /api/webhooks/revenuecat
  • Card provenance: GET /api/v1/cards/{id}/provenance (public; in OpenAPI)
  • Marketplace: /api/v1/marketplace/* — published in OpenAPI (Marketplace tag). Use the Endpoints playground for request/response shapes.
  • Listing PIN: POST /api/v1/user/set-pin, POST /api/v1/user/verify-pin (returns a short-lived X-Listing-Pin-Token; 404 PIN_NOT_SET until set)
  • KYC: POST /api/v1/kyc/link-token, POST /api/v1/kyc/session/complete, GET /api/v1/user/kyc-status (KYC tag)

​
Marketplace notes

  • Prefer GET /api/v1/marketplace/me/listings. GET /api/v1/marketplace/listings/mine is a native alias for the same handler.
  • POST /api/v1/marketplace/listings requires x-listing-pin-token. Invalid or missing proof returns 401 PIN_TOKEN_INVALID.
  • Listing a pack that is still processing returns 409 with code PACK_NOT_LISTABLE.
  • An already-opened pack returns 409 with code PACK_ALREADY_OPENED.
  • Pack-instance status on GET /api/user/packs is authoritative. Do not use template isOpenable as a substitute.
  • Auction listings accept optional reservePrice (positive integer, at least the starting bid). Ended auctions that miss reserve surface as ended-reserve-not-met.
  • Featured listings (GET /api/v1/marketplace/featured) are cacheable and public. Team promos are GET /api/v1/marketplace/promos. There is no combined shop featured feed.
  • List and detail GETs (/marketplace, /listings, listing by id, collectible listings, listing bids, top-bids) accept an optional Bearer token and personalize when a session is present. featured and price-suggestion stay public-only.
  • Staff-only POST /featured and POST /promos are not in generated OpenAPI.

​
KYC notes

  • These are authenticated session helpers only. They do not expose vendor dashboard URLs or webhook secrets.
  • POST /api/v1/kyc/link-token accepts optional { retry }. A retry with no prior session returns 404.
  • POST /api/v1/kyc/session/complete requires { identityVerificationId } and optional linkSessionId.
  • GET /api/v1/user/kyc-status returns { status, verifiedAt, identityVerificationId }.

​
Integration notes

  • Payment verification flows should be treated as asynchronous and failure-prone.
  • Use explicit item identifiers and quantity validation before checkout submission.

​
Deep-dive documentation