API documentation

Enrollment, payment, and control contracts.

Distort owns canonical products, orders, entitlements, and admin control. This site owns learning presentation, provider checkout, webhook verification, legal display, and payment-control infrastructure.

Step 01

Signed enrollment redirect

Distort redirects members to /checkout?intent=<signed-token>. The token contains an intent ID and expiry metadata only. Price, package, account, and duration resolve server-to-server.

GET https://learn.example/checkout?intent=<signed-token>

Step 02

Resolve canonical intent

The learning site calls Distort with a timestamped HMAC. Distort returns canonical package, amount, user, duration, gift target, and expiry.

POST /api/internal/payment-shell/resolve-intent
Headers:
  content-type: application/json
  x-distort-shell-timestamp: 1777000000
  x-distort-shell-signature: hmac_sha256(timestamp + "." + rawBody)

Body:
{
  "checkoutIntentId": "ci_abc123"
}

Step 03

Create provider checkout

The learning site creates a Creem checkout with product_id, request_id, success_url, customer email, and metadata.

POST https://api.creem.io/v1/checkouts
{
  "product_id": "prod_...",
  "request_id": "ci_abc123",
  "success_url": "https://learn.example/checkout/success?intent=ci_abc123",
  "metadata": { "distortIntentId": "ci_abc123" }
}

Step 04

Finalize after verified webhook

Creem webhooks are verified from the raw body, recorded idempotently, then finalized through Distort exactly once for completed checkout events.

POST /api/webhooks/creem
Header:
  creem-signature: hmac_sha256(rawBody, CREEM_WEBHOOK_SECRET)

Handled event:
  checkout.completed

POST /api/internal/payment-shell/finalize
{
  "intentId": "ci_abc123",
  "provider": "creem",
  "providerCheckoutId": "ch_abc123",
  "providerOrderId": "ord_abc123",
  "amount": 49,
  "currency": "USD",
  "rawEventId": "evt_abc123"
}

Step 05

Internal control from Distort

Distort controls legal settings, provider mappings, event listing, and retry workflows through signed POST-only shell-control endpoints. Query-token admin access is not accepted.

POST /api/internal/shell-control/mappings/upsert
Headers:
  x-distort-shell-timestamp: 1777000000
  x-distort-shell-signature: hmac_sha256(timestamp + "." + rawBody)

Body:
{
  "mapping": {
    "distortProductId": "academy_3_month",
    "distortProductName": "3-Month Study Plan",
    "creemProductId": "prod_...",
    "active": true
  }
}

Error model

400Missing or invalid checkout intent, product mapping, control payload, or provider payload.

401Timestamped HMAC or webhook signature verification failed.

404Checkout intent or provider event not found.

500Provider or Distort finalization failed; event remains retryable from Distort admin tooling.