# Token Checkout

Token-based checkout flow endpoints

## Initiate Token-Based Checkout

> Initiates a checkout session using a pre-generated token.\
> \
> \## Token Generation\
> \
> Tokens are generated during the standard checkout flow on the \`PaymentOptionSelectionPage\`.\
> The token URLs (\`checkout\_url\` and \`status\_url\`) are included in that page's response.\
> \
> \*\*Token generation requirements:\*\*\
> 1\. The request must be from an in-store (kiosk) device (\`client\_type: instore\`)\
> 2\. User must be authenticated, OR the \`CHECKOUT\_WITH\_TOKEN\_ALLOW\_ANONYMOUS\` setting must be enabled\
> 3\. A valid session must exist\
> \
> If these conditions are not met, no token URLs are generated.\
> \
> \## How It Works\
> \
> 1\. Validates the token and retrieves the associated basket/user.\
> 2\. If user is anonymous, validates the \`one\_time\_token\` query parameter.\
> 3\. Logs in the user (if authenticated) and redirects to the checkout page.\
> 4\. Sets the client type to \`instore\` for analytics tracking.\
> \
> \*\*Configuration:\*\*\
> \| Setting | Type | Default | Description |\
> \|---------|------|---------|-------------|\
> \| \`CHECKOUT\_WITH\_TOKEN\_ALLOW\_ANONYMOUS\` | boolean | \`false\` | Allows anonymous users to use token-based checkout. Can be changed via Admin Panel (Dynamic Setting). |\
> \
> \*\*Use Cases:\*\*\
> \- In-store kiosk checkout (customer scans QR code to complete purchase on their phone)\
> \- QR code-based checkout\
> \- Email/SMS checkout links

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"tags":[{"name":"Token Checkout","description":"Token-based checkout flow endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[],"paths":{"/orders/checkout-with-token/{token}/":{"get":{"tags":["Token Checkout"],"summary":"Initiate Token-Based Checkout","description":"Initiates a checkout session using a pre-generated token.\n\n## Token Generation\n\nTokens are generated during the standard checkout flow on the `PaymentOptionSelectionPage`.\nThe token URLs (`checkout_url` and `status_url`) are included in that page's response.\n\n**Token generation requirements:**\n1. The request must be from an in-store (kiosk) device (`client_type: instore`)\n2. User must be authenticated, OR the `CHECKOUT_WITH_TOKEN_ALLOW_ANONYMOUS` setting must be enabled\n3. A valid session must exist\n\nIf these conditions are not met, no token URLs are generated.\n\n## How It Works\n\n1. Validates the token and retrieves the associated basket/user.\n2. If user is anonymous, validates the `one_time_token` query parameter.\n3. Logs in the user (if authenticated) and redirects to the checkout page.\n4. Sets the client type to `instore` for analytics tracking.\n\n**Configuration:**\n| Setting | Type | Default | Description |\n|---------|------|---------|-------------|\n| `CHECKOUT_WITH_TOKEN_ALLOW_ANONYMOUS` | boolean | `false` | Allows anonymous users to use token-based checkout. Can be changed via Admin Panel (Dynamic Setting). |\n\n**Use Cases:**\n- In-store kiosk checkout (customer scans QR code to complete purchase on their phone)\n- QR code-based checkout\n- Email/SMS checkout links","operationId":"initiateTokenCheckout","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"},"description":"The checkout token (UUID format)."}],"responses":{"302":{"description":"Redirects to the checkout page","headers":{"Location":{"schema":{"type":"string"},"description":"Redirect URL to checkout flow."}}},"401":{"description":"User mismatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"404":{"description":"Invalid token or user not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}}}}}},"components":{"schemas":{"ValidationErrorResponse":{"type":"object","description":"Standard DRF validation error response","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}
```

## Check Token Checkout Order Status

> Checks whether an order has been created for the basket associated with the token.\
> \
> \*\*Business Logic:\*\*\
> \- Retrieves the basket associated with the token.\
> \- Checks if the basket status is \`submitted\` (order created).\
> \- Returns the order number if the order exists.\
> \
> \*\*Use Cases:\*\*\
> \- Polling from external systems to check order completion.\
> \- In-store kiosk status display.\
> \- Real-time order tracking from POS systems.

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"tags":[{"name":"Token Checkout","description":"Token-based checkout flow endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[],"paths":{"/orders/checkout-with-token/{token}/status/":{"get":{"tags":["Token Checkout"],"summary":"Check Token Checkout Order Status","description":"Checks whether an order has been created for the basket associated with the token.\n\n**Business Logic:**\n- Retrieves the basket associated with the token.\n- Checks if the basket status is `submitted` (order created).\n- Returns the order number if the order exists.\n\n**Use Cases:**\n- Polling from external systems to check order completion.\n- In-store kiosk status display.\n- Real-time order tracking from POS systems.","operationId":"getTokenCheckoutStatus","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"},"description":"The checkout token (UUID format)."}],"responses":{"200":{"description":"Order status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenCheckoutStatusResponse"}}}},"404":{"description":"Token not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}}}}}},"components":{"schemas":{"TokenCheckoutStatusResponse":{"type":"object","properties":{"order_created":{"type":"boolean","description":"Whether an order has been created for the token's basket."},"order_number":{"type":"string","description":"The order number (only present if order_created is true)."}}},"ValidationErrorResponse":{"type":"object","description":"Standard DRF validation error response","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}
```