# Áskell

> Áskell is an Icelandic subscription and recurring-payments platform by Overcast. It exposes a REST API at `https://askell.is/api/` for managing customers, payment methods, subscriptions, one-off payments, checkouts and webhooks, plus hosted payment pages and an embeddable checkout widget (`askell.js`).

Important notes for integrators:

- Authenticate with an `Authorization: Api-Key <key>` header. Public keys may be used in browser JavaScript for a small set of endpoints (mainly creating unconfirmed payment methods); secret keys are server-side only and must never appear in HTML or JavaScript.
- There are two subscription models: the legacy `PlanVariant`/`Subscription` flow, and Subscription Contracts V2 (`/api/v2/`) built around a product catalog, prices, bundles, quotes, checkouts, contracts and billing runs. New integrations should use V2.
- A typical V2 flow: fetch catalog products/prices/bundles → create a quote (`POST /api/v2/subscription-offer-quotes/`) → fetch payment-processor options (`POST /api/v2/payment-processor-options/`) → create a checkout (`POST /api/v2/checkouts/`) → finalize it (`POST /api/v2/checkouts/{token}/finalize/`) → poll checkout and billing-run status.
- Another typical flow is the embedded checkout: set up the V2 catalog and a sales channel → create a short-lived, scoped checkout session from your backend using the secret API key → pass only the session token to the browser → render the checkout on your own site with `askell.js`. The browser can only perform the checkout actions the session allows.
- Card capture with 3D Secure processors uses `TemporaryPaymentMethod` tokens (`POST /api/temporarypaymentmethod/`) and a card-verification iframe.
- Webhooks notify your server of subscription, subscription-contract, billing-run, customer and payment events.
- The Áskell Test Gateway payment processor can be used for testing without an acquirer agreement.
- Documentation is available in English (`/en/`) and Icelandic (`/is/`).

## Docs

- [Getting started](https://docs.askell.is/en/getting_started/index.html): Account setup, payment processors (including the Áskell Test Gateway), subscription plans and API keys
- [Authentication](https://docs.askell.is/en/api/authentication.html): API-key header format, public vs. secret keys, request examples in Python and JavaScript
- [Subscription Contracts V2](https://docs.askell.is/en/api/subscription_contracts_v2.html): The new subscription model — catalog, prices, bundles, quotes, payment-processor options, checkouts, contracts and billing runs
- [Subscriptions (legacy)](https://docs.askell.is/en/api/subscriptions.html): The older `PlanVariant`/`Subscription` flow and its endpoints
- [Payments](https://docs.askell.is/en/api/payments.html): One-off charges against a stored payment method, and payment statuses (`pending`, `settled`, `failed`, `retrying`)
- [3D Secure](https://docs.askell.is/en/api/3dsecure.html): Card verification flow using `TemporaryPaymentMethod` tokens and a verification iframe
- [Embedded checkout](https://docs.askell.is/en/api/embedded_checkout.html): Short-lived, scoped checkout sessions rendered on your own site with `askell.js` (`https://cdn.askell.is/js/dist/askell.js`)
- [Payment pages](https://docs.askell.is/en/api/payment_pages.html): Hosted payment pages at `https://askell.is/public/payments/<id>/` with query-string parameters for prefilling form data
- [Webhooks](https://docs.askell.is/en/api/webhooks.html): Event types (`subscription.*`, `subscription_contract.*`, `billing_run.*`, `customer.*`, …) and payload details
- [Wallet pass barcodes](https://docs.askell.is/en/api/wallet_pass_barcodes.html): Verifying HMAC-SHA256-signed barcode values in wallet passes

## API reference

- [Swagger UI](https://askell.is/api/swagger/): Interactive documentation where every API call can be tried out
- [OpenAPI spec (JSON)](https://askell.is/api/swagger/swagger.json): Machine-readable schema of all API endpoints, parameters and models

## Optional

- [Release notes](https://docs.askell.is/en/release_notes/index.html): Changes to the platform and API
- [Icelandic documentation](https://docs.askell.is/is/): The same documentation in Icelandic