Checkout Pages

Individual checkout page endpoints. Each page represents a step in the checkout flow.

Get current checkout state

get

Returns the current checkout state and determines which page should be displayed. The response includes a list of completed pages and the current page context.

If the page query parameter is provided, it forces the display of that specific page. Otherwise, the system automatically determines the appropriate page based on checkout progress.

Query parameters

pagestring · enumOptional

Optional page name to force display a specific page

Possible values:

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Checkout state retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

302

Redirect to basket (empty basket) or login (guest purchase not allowed)

404

Basket not found

get

/orders/checkout/

HTTPcURLJavaScriptPython

Process checkout step

post

Processes form submission for the current checkout step. The page parameter determines which page's data is being submitted.

Processing Flow:

1. Validates preconditions for the specified page

2. Validates submitted data according to page-specific rules

3. Updates pre-order state if validation succeeds

4. Recalculates campaigns and discounts

5. Determines next page and returns updated checkout state

Error Handling:

• Validation errors are returned in the errors object

• User remains on the current page when errors occur

• Previously entered valid data is preserved

Query parameters

pagestring · enumRequired

Page name to process (e.g., "IndexPage", "AddressSelectionPage")

Possible values:

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

objectOptional

No input fields are required for this step. Submit an empty form body to trigger order number assignment and 3D Secure routing evaluation.

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

objectOptional

No input fields are required for this step. The request body must be empty. Any fields submitted in the body are not processed by this page and will not cause a validation error; however, the Garanti Pay gateway is not involved at this step, so gateway-specific parameters are irrelevant here.

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

or

Responses

200

Step processed successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

302

Redirect to basket (empty basket)

post

/orders/checkout/

HTTPcURLJavaScriptPython

Get Index Page context

get

Returns the context for the Index Page, which collects user email and optional phone number. This page is skipped for authenticated users.

Preconditions:

• Basket must not be empty

• If CAN_GUEST_PURCHASE is false, user must be authenticated

Skip Conditions:

• Page is skipped if user is already logged in

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Index page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=IndexPage

HTTPcURLJavaScriptPython

200

Index page context retrieved

Submit Index Page (email and phone)

post

Submits user email and optional phone number for guest checkout. After successful submission, the system routes to the next appropriate page.

Configuration:

• CAN_GUEST_PURCHASE: Controls whether guest checkout is allowed. If false, user must be authenticated.

• USER_PHONE_FORMAT: Phone number format used for display hints and validation guidance (default: "05999999999")

Next Pages (determined dynamically):

• If multiple delivery options exist: DeliveryOptionSelectionPage

• If scheduled delivery is active: SlotSelectionPage

• Otherwise: AddressSelectionPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

user_emailstring · emailRequired

User email address. Required for guest checkout.

phone_numberstringOptional

Optional phone number. Must match phone regex pattern if provided.

Responses

200

Email submitted successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=IndexPage

HTTPcURLJavaScriptPython

With phone numberWithout phone number

200

Email submitted successfully

Get Delivery Option Selection Page context

get

Returns available delivery options for selection. This page is automatically skipped if only one active delivery option exists.

Preconditions:

• User email must be set

• Basket must not be empty

Skip Conditions:

• Page is skipped if only one active delivery option exists

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Delivery options retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=DeliveryOptionSelectionPage

HTTPcURLJavaScriptPython

200

Delivery options retrieved

Set Delivery Option

post

Sets the selected delivery option to the current pre-order.

Configuration:

• CHECKOUT_DELIVERY_OPTION_SELECTION_PAGE: Determines which delivery option selection page is used. Can be set to DeliveryOptionSelectionPage or RemoteDeliveryOptionSelectionPage.

Next Pages (based on selected delivery option):

• If scheduled delivery is active: SlotSelectionPage

• If pickup location selected: PickupLocationSelectionPage

• If retail store selected: RetailStoreSelectionPage

• Otherwise: AddressSelectionPage

Cascading Invalidation:

• Changing delivery option with clear=true resets shipping and billing addresses

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

delivery_optionintegerRequired

Primary key of the selected delivery option

clearbooleanOptional

If true, clears shipping and billing addresses when changing delivery option

Default: false

Responses

200

Delivery option set successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=DeliveryOptionSelectionPage

HTTPcURLJavaScriptPython

Customer delivery optionRetail store with address clear

200

Delivery option set successfully

Get Remote Delivery Option Selection Page context

get

Returns available delivery options fetched from a remote service. Extends DeliveryOptionSelectionPage to use RemoteDeliveryOptionService.

Configuration:

• Requires REMOTE_DELIVERY_OPTION_PROVIDER dynamic setting to be configured

• The provider fetches delivery options from an external service based on the configuration

• Used when CHECKOUT_DELIVERY_OPTION_SELECTION_PAGE is set to RemoteDeliveryOptionSelectionPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Remote delivery options retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=RemoteDeliveryOptionSelectionPage

HTTPcURLJavaScriptPython

200

Remote delivery options retrieved

Set Remote Delivery Option

post

Sets the selected remote delivery option. Validates that the selected option is available from the remote service.

Configuration:

• Requires REMOTE_DELIVERY_OPTION_PROVIDER dynamic setting to be configured

• The provider fetches delivery options from an external service based on the configuration

• Used when CHECKOUT_DELIVERY_OPTION_SELECTION_PAGE is set to RemoteDeliveryOptionSelectionPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

delivery_optionintegerRequired

Primary key of the selected delivery option

clearbooleanOptional

If true, clears shipping and billing addresses when changing delivery option

Default: false

Responses

200

Remote delivery option set successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=RemoteDeliveryOptionSelectionPage

HTTPcURLJavaScriptPython

200

Remote delivery option set successfully

Get Address Selection Page context

get

Returns available addresses for selection (billing and shipping). Supports both authenticated users (shows saved addresses) and anonymous users (shows addresses stored in session).

Preconditions:

• User email must be set

• Delivery option must be selected and must be customer type (is_customer())

• Basket must not be empty

Address Sources:

• Authenticated users: Addresses from their account, ordered by primary status and modification date

• Anonymous users: Addresses stored in session via AnonymousUserAddressService

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Address selection page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=AddressSelectionPage

HTTPcURLJavaScriptPython

200

Address selection page context retrieved

Send User's Billing and Shipping Addresses

post

Sets the billing and shipping addresses for the order.

Configuration:

• REMOTE_PRICE_ATTRIBUTE_KEY: Product attribute key (default: "has_remote_price") that indicates a product requires remote price calculation. If any basket item has this attribute set to "true", the checkout flow routes to RemotePriceCalculationPage after address selection.

• IDENTITY_NUMBER_REQUIRED_AMOUNT: Order amount threshold that requires identity number validation. If set and order total (with interest) exceeds this amount, shipping address must have identity_number field populated, otherwise validation fails.

• DEFAULT_COUNTRY_CODE: Default country code used to populate country field in address contexts.

Remote Price Detection:

• Checks if any basket item has REMOTE_PRICE_ATTRIBUTE_KEY attribute set to "true"

• If detected, routes to RemotePriceCalculationPage next

Next Pages:

• If remote price calculation needed: RemotePriceCalculationPage

• Otherwise: Shipping option selection page

Validation:

• If IDENTITY_NUMBER_REQUIRED_AMOUNT is set and order total exceeds threshold, shipping address must have identity_number populated

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

billing_addressintegerRequired

Primary key of the billing address

shipping_addressintegerRequired

Primary key of the shipping address

Responses

200

Addresses set successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=AddressSelectionPage

HTTPcURLJavaScriptPython

Same billing and shipping addressDifferent billing and shipping addresses

200

Addresses set successfully

Get Retail Store Selection Page context

get

Returns available retail stores for click-and-collect orders. Only displayed when delivery option type is retail store.

Preconditions:

• Delivery option must be selected and must be retail store type (is_retail_store())

• Basket must not be empty

Retail Store Filtering:

• If CHECKOUT_LIST_RETAIL_STORES is False, no stores are listed

• If CHECKOUT_RETAIL_STORE_FILTERS.by_stock is True, only stores with available stock for basket items are shown

• Otherwise, all active retail stores with click_and_collect=True are displayed

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Retail store selection page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=RetailStoreSelectionPage

HTTPcURLJavaScriptPython

200

Retail store selection page context retrieved

Select Retail Store

post

Sets the selected retail store for click-and-collect order.

Configuration:

• CHECKOUT_LIST_RETAIL_STORES: Controls whether retail stores are listed (static setting, default: True). When False, no stores are fetched or displayed.

• CHECKOUT_RETAIL_STORE_FILTERS: Filtering options for retail stores (default: {"by_stock": false}). When by_stock is true, only retail stores with available stock for basket items are shown. When false, all active retail stores with click_and_collect=True are displayed.

• DEFAULT_COUNTRY_CODE: Default country code used to populate country field in address contexts.

Address Handling:

• Creates a RetailStoreAddress object from the selected retail store

• Uses billing address details (first name, last name) and user email

• Sets billing_and_shipping_same to false

Next Pages:

• Shipping option selection page

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

billing_addressintegerRequired

Primary key of the billing address

retail_storeintegerRequired

Primary key of the selected retail store

Responses

200

Retail store selected successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=RetailStoreSelectionPage

HTTPcURLJavaScriptPython

200

Retail store selected successfully

Get Pickup Location Selection Page context

get

Returns context for pickup location selection. Only displayed when delivery option type is pickup location.

Preconditions:

• Delivery option must be selected and must be pickup location type (is_pickup_location())

• Basket must not be empty

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Pickup location selection page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=PickupLocationSelectionPage

HTTPcURLJavaScriptPython

200

Pickup location selection page context retrieved

Select Pickup Location

post

Sets the selected pickup location for the order.

Configuration:

• DEFAULT_COUNTRY_CODE: Default country code used to populate country field in address contexts.

Pickup Location Handling:

• Uses PickupLocationService to fetch location by remote_id

• Creates a PickupLocationAddress object

• Validates that the remote location exists

Next Pages:

• Shipping option selection page

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

remote_idstringRequired

Remote identifier for the pickup location

billing_addressintegerRequired

Primary key of the billing address

Responses

200

Pickup location selected successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=PickupLocationSelectionPage

HTTPcURLJavaScriptPython

200

Pickup location selected successfully

Get Address Clear Page context

get

A utility page that clears all address-related data from the pre-order. Used internally to reset checkout state. Does not require user interaction.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Address clear page context

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=AddressClearPage

HTTPcURLJavaScriptPython

200

Address clear page context

Clear Address Data

post

Clears shipping address, billing address, billing_and_shipping_same, and retail_store from the pre-order. Routes to EmptyPage after completion.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Address data cleared successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=AddressClearPage

HTTPcURLJavaScriptPython

200

Address data cleared successfully

Get Shipping Option Selection Page context

get

Returns available shipping options for the selected shipping address. This is the default shipping option selection page when CHECKOUT_SHIPPING_OPTION_SELECTION_PAGE dynamic setting is set to ShippingOptionSelectionPage (default).

Preconditions:

• Shipping address must be selected (check_address_selected)

• Basket must not be empty

Shipping Option Rules: Shipping options are filtered based on configured rules that determine availability. Each shipping option can have multiple rules attached, and all rules must pass for the option to be available.

• Rules are evaluated against the current checkout context (basket, address, user, etc.)

• Common rule types include:

  • Geographic rules: Filter by country, city, township, or district

  • Basket rules: Filter by basket total amount, item count, or weight

  • Product rules: Filter by product attributes, categories, or data sources

  • User rules: Filter by user segment, membership status, or order history

  • Time-based rules: Filter by day of week, time windows, or date ranges

• If no rules pass for any shipping option, checkout cannot proceed

• Rule configurations are managed through the admin interface

Shipping Amount Calculators: Each shipping option has a configured calculator that determines the shipping cost dynamically.

• Calculator Types:

  • FreeShippingCalculator: Always returns zero shipping cost

  • FixedPriceCalculator: Returns a fixed shipping amount configured on the shipping option

  • WeightBasedCalculator: Calculates cost based on total basket weight and configured weight tiers

  • PriceBasedCalculator: Calculates cost based on basket total amount and configured price tiers

  • QuantityBasedCalculator: Calculates cost based on total item quantity in basket

  • RemoteCalculator: Fetches shipping cost from an external service/API

  • DataSourceCalculator: Calculates cost per data source (vendor/supplier)

• Calculators receive basket contents, shipping address, and currency as input

• Calculator results are cached per request for performance

• Custom calculators can be implemented by extending the base calculator class

Auto-selection:

• If AUTOSELECT_SHIPPING setting is True and only one shipping option is available, it is automatically selected and the page is skipped

Configuration:

• CHECKOUT_SHIPPING_OPTION_SELECTION_PAGE: Determines which shipping option selection page is used. Can be set to ShippingOptionSelectionPage (default), DataSourceShippingOptionSelectionPage, AttributeBasedShippingOptionSelectionPage, or RemoteShippingOptionSelectionPage.

• AUTOSELECT_SHIPPING: When True, automatically selects the shipping option if only one is available.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Shipping option selection page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=ShippingOptionSelectionPage

HTTPcURLJavaScriptPython

200

Shipping option selection page context retrieved

Select Shipping Option

post

Sets the selected shipping option for the order.

Validation:

• The selected shipping option must be in the list of available shipping options

• The shipping option's rules are re-evaluated to ensure it's still valid

• If the shipping option has required_fields in its kwargs, those fields must be provided

Rule Re-evaluation:

• Rules are checked again at submission time to prevent race conditions

• If basket contents changed since page load, rules may now fail

• If address changed since page load, geographic rules are re-evaluated

• Failed rule validation returns an error and the user must select a different option

Shipping Amount Calculation:

• Amount is calculated using the shipping option's configured calculator

• Calculator receives current basket contents, shipping address, and currency

• Available calculator types:

  • FreeShippingCalculator: Zero cost

  • FixedPriceCalculator: Fixed amount from shipping option configuration

  • WeightBasedCalculator: Cost based on basket weight tiers

  • PriceBasedCalculator: Cost based on basket amount tiers

  • QuantityBasedCalculator: Cost based on item quantity

  • RemoteCalculator: Cost from external service

  • DataSourceCalculator: Cost per vendor/supplier

• Calculated amount is stored in pre-order and added to order total

Next Pages:

• If sample product discounts are available: SampleProductPage

• If retail store reservation is needed: ReservationSelectionPage

• Otherwise: PaymentOptionSelectionPage

Cascading Invalidation:

• Changing shipping option resets any previously selected payment option

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

shipping_optionintegerRequired

Primary key of the selected shipping option

Other propertiesstringOptional

Additional required fields defined in the shipping option's kwargs.required_fields. These fields vary based on the shipping option configuration and may include fields like delivery_date, time_slot, etc.

Responses

200

Shipping option selected successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=ShippingOptionSelectionPage

HTTPcURLJavaScriptPython

Select standard shippingShipping option with required fields

200

Shipping option selected successfully

Get Data Source Shipping Option Selection Page context

get

Returns available shipping options grouped by data source (supplier/vendor). Used when products in the basket come from different data sources and each data source requires separate shipping option selection.

This page is used when CHECKOUT_SHIPPING_OPTION_SELECTION_PAGE dynamic setting is set to DataSourceShippingOptionSelectionPage.

Preconditions:

• Shipping address must be selected (check_address_selected)

• Basket must not be empty

Data Source Grouping:

• Products are grouped by their data source (supplier/vendor)

• Each data source has its own set of available shipping options

• User must select a shipping option for each data source

Configuration:

• CHECKOUT_SHIPPING_OPTION_SELECTION_PAGE: Must be set to DataSourceShippingOptionSelectionPage to enable this page.

Error Handling:

• Raises NoDataSourceShippingOptionAvailable exception if no shipping options are available for the basket and shipping address combination

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Data source shipping option selection page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=DataSourceShippingOptionSelectionPage

HTTPcURLJavaScriptPython

200

Data source shipping option selection page context retrieved

Select Shipping Options per Data Source

post

Sets the shipping options for each data source in the basket. Each data source in the basket must have exactly one shipping option selected.

Input Format:

• data_source_shipping_options: JSON-encoded array of DataSourceShippingOption primary keys

• Each ID in the array corresponds to a shipping option selected for a specific data source

• The array must contain exactly one shipping option ID per data source in the basket

Example: If a basket contains products from 2 data sources (Vendor A and Vendor B), and the available shipping options are:

• Data Source "Vendor A": Standard Shipping (ID: 10), Express Shipping (ID: 11)

• Data Source "Vendor B": Standard Shipping (ID: 20), Economy Shipping (ID: 21)

To select Standard Shipping for Vendor A and Economy Shipping for Vendor B:

data_source_shipping_options: "[10, 21]"

Validation:

• All data sources in the basket must have a shipping option selected

• Selected options must be available for the current basket and shipping address

• Shipping amounts are recalculated to ensure consistency

Shipping Amount:

• Total shipping amount is the sum of all selected data source shipping option amounts

Next Pages:

• If sample product discounts are available: SampleProductPage

• If retail store reservation is needed: ReservationSelectionPage

• Otherwise: PaymentOptionSelectionPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

data_source_shipping_optionsstringRequired

JSON-encoded array of data source shipping option IDs. Each ID is the primary key of a DataSourceShippingOption model. One shipping option must be selected for each data source in the basket.

Example: [10, 20, 30]

Responses

200

Data source shipping options selected successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=DataSourceShippingOptionSelectionPage

HTTPcURLJavaScriptPython

200

Data source shipping options selected successfully

Get Attribute-Based Shipping Option Selection Page context

get

Returns available shipping options grouped by product attribute values. Products are grouped based on configured attribute keys, and each group can have different shipping options available.

This page is used when CHECKOUT_SHIPPING_OPTION_SELECTION_PAGE dynamic setting is set to AttributeBasedShippingOptionSelectionPage.

Preconditions:

• Shipping address must be selected (check_address_selected)

• Basket must not be empty

Attribute-Based Grouping: Products are grouped by their attribute VALUES (not keys). The grouping mechanism works as follows:

1. Rule Evaluation: The system evaluates rules from ATTRIBUTE_KEYS_FOR_ATTRIBUTE_BASED_SHIPPING_OPTION setting in sort_order priority (lower values first). Each rule is evaluated against the shipping address using location-based conditions (country, city, township, district).

2. First Match Wins: The first rule that matches the shipping address determines which group_attribute_key is used for grouping. Remaining rules are ignored.

3. Grouping by Attribute Value: Products are then grouped by the value of the selected attribute key. For example, if group_attribute_key is "warehouse_location":

   • Product A with warehouse_location: "istanbul" → Group: "istanbul"

   • Product B with warehouse_location: "istanbul" → Group: "istanbul" (same group)

   • Product C with warehouse_location: "ankara" → Group: "ankara"

4. Missing Attributes: Products without the specified attribute are grouped under "None". A default shipping option (with is_default=True) typically handles these products.

5. Multiple Attribute Keys: If group_attribute_key is a list (e.g., ["brand", "category"]), products are grouped by composite keys with semicolon separator:

   • Product with brand: "Nike", category: "shoes" → Group: "Nike;shoes"

   • Product with only brand: "Nike" → Group: "Nike;None"

Available Rules for Rule Configuration:

Rule Slug	Description	Parameters
any-rule	Always matches (fallback rule)	none
country-rule	Matches addresses in specified countries	countries: list of country IDs, exclude: boolean
city-rule	Matches addresses in specified cities	cities: list of city IDs, exclude: boolean
township-rule	Matches addresses in specified townships	townships: list of township IDs, exclude: boolean
district-rule	Matches addresses in specified districts	districts: list of district IDs, exclude: boolean
postal-code-rule	Matches addresses with specified postal codes	postal_codes: list of postal code strings, exclude: boolean
not-rule	Negates a child rule	child: child rule object
and-rule	All children must match	children: list of child rule objects
or-rule	Any child must match	children: list of child rule objects

Configuration Example:

In this example:

• For addresses in countries 1 or 2: Products are grouped by warehouse_location

• For addresses in city 5 (if not in countries 1, 2): Products are grouped by brand;category

• For all other addresses: Products are grouped by supplier

Segment Support:

• Available shipping options can vary based on user segment

• Segment-specific pricing and availability rules are applied

Configuration:

• CHECKOUT_SHIPPING_OPTION_SELECTION_PAGE: Must be set to AttributeBasedShippingOptionSelectionPage

• ATTRIBUTE_KEYS_FOR_ATTRIBUTE_BASED_SHIPPING_OPTION: List of attribute key configurations that define how products are grouped

Error Handling:

• Raises NoAttributeBasedShippingOptionAvailable exception if no shipping options are available for the basket and shipping address combination

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Attribute-based shipping option selection page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=AttributeBasedShippingOptionSelectionPage

HTTPcURLJavaScriptPython

200

Attribute-based shipping option selection page context retrieved

Select Shipping Options per Attribute Value Group

post

Sets the shipping options for each attribute value group in the basket. Each attribute value group must have exactly one shipping option selected.

Input Format:

• attribute_based_shipping_options: JSON-encoded object mapping attribute values to shipping option IDs

• Keys are attribute values (the group keys from the GET response, e.g., "electronics", "clothing", "Nike;shoes")

• Values are AttributeBasedShippingOption primary keys (integers)

Example: If the GET response returns the following attribute-based shipping options:

{
  "electronics": {
    "attribute_based_shipping_options": [
      {"pk": 100, "shipping_option_name": "Standard Delivery", "shipping_amount": "5.99"},
      {"pk": 101, "shipping_option_name": "Express Delivery", "shipping_amount": "15.99"}
    ],
    "product_ids": [1001, 1002, 1003],
    "attribute_key": ["category"]
  },
  "clothing": {
    "attribute_based_shipping_options": [
      {"pk": 200, "shipping_option_name": "Economy Delivery", "shipping_amount": "3.99"},
      {"pk": 201, "shipping_option_name": "Standard Delivery", "shipping_amount": "8.99"}
    ],
    "product_ids": [2001, 2002],
    "attribute_key": ["category"]
  }
}

To select Standard Delivery (ID: 100) for electronics and Economy Delivery (ID: 200) for clothing:

Composite Group Keys: If products are grouped by multiple attributes (e.g., ["brand", "category"]), the group keys will be composite values separated by semicolons:

Validation:

• All attribute value groups must have a shipping option selected

• Selected options must be available for the current basket, shipping address, and segment

• Product IDs must match the expected grouping

• Shipping amounts are recalculated to ensure consistency

Shipping Amount:

• Total shipping amount is the sum of all selected attribute-based shipping option amounts

Address Validation:

• Validates that the shipping address hasn't changed since options were loaded

• If address changed, options are recalculated

Next Pages:

• If sample product discounts are available: SampleProductPage

• If retail store reservation is needed: ReservationSelectionPage

• Otherwise: PaymentOptionSelectionPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

attribute_based_shipping_optionsstringRequired

JSON-encoded object mapping attribute values to shipping option IDs. Keys are attribute values (e.g., "electronics", "clothing", "warehouse_a"). Values are primary keys of AttributeBasedShippingOption models. One shipping option must be selected for each attribute value group.

Example: {"electronics": 100, "clothing": 200}

Responses

200

Attribute-based shipping options selected successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=AttributeBasedShippingOptionSelectionPage

HTTPcURLJavaScriptPython

200

Attribute-based shipping options selected successfully

Get Payment Option Selection Page context

get

Returns available payment options for the order. Payment options are filtered based on configured rules and user context.

Preconditions:

• Shipping option must be selected (check_shipping_option_selected)

• Basket must not be empty

Payment Option Availability:

• Each payment option has associated rules that determine availability

• Rules can check basket contents, user status, order amount, and more

• Unavailable options are returned separately with error codes and messages

Checkout URLs:

• checkout_url: URL for checkout with token (used for external payment flows)

• status_url: URL to check checkout status (used for polling payment status)

• Generated by CheckoutWithTokenService

Payment Types: Payment options can have different types that determine the next page flow:

• credit_card: Routes to BinNumberPage

• funds_transfer: Routes to FundsTransferChoicePage

• bkm_express: Routes to BexSelectionPage

• loyalty_money: Routes to LoyaltyMoneyPage

• cash_register: Routes to CashRegisterPage

• gpay: Routes to GPaySelectionPage

• redirection: Routes to RedirectionPaymentSelectedPage

• stored_card: Routes to MobilExpressSelectionPage

• masterpass: Routes to MasterpassBinNumberPage

• masterpass_rest: Routes to MasterpassRestBinNumberPage

• credit_payment: Routes to CreditPaymentSelectionPage

• pay_later: Routes to PayLaterCompletePage

• saved_card: Routes to SavedCardSelectionPage

• confirmation: Routes to ConfirmationPaymentAgreementCheckPage

• b2b: Routes to B2BPage

• wallet: Routes to WalletSelectionPage

• pay_on_delivery: Routes to PayOnDeliveryPaymentChoicePage or PayOnDeliveryPage

• gift_card: Routes to GiftCardPaymentPage

Gift Card Payment Option: The gift_card payment option appears in the available options list only when all of the following are true:

• At least one gift card reservation exists on the order

• The remaining unpaid amount is exactly zero (gift cards fully cover the order)

When gift cards only partially cover the order total, the gift_card payment option is not shown. In this case the user selects a regular payment option (e.g. credit card). During order placement the applied gift card amounts are charged first; the remaining balance is then charged to the selected payment method.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Payment option selection page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=PaymentOptionSelectionPage

HTTPcURLJavaScriptPython

200

Payment option selection page context retrieved

Select Payment Option

post

Sets the selected payment option for the order.

Validation:

• The selected payment option must be active

• The selected payment option must pass its availability rules

Payment Option Processing:

• If payment option is pay-on-delivery type, installment and card_info are cleared

• Previous MobilExpress data (keys starting with me_) is cleared

• Payment choice is reset

Next Pages: Based on the selected payment option type, the user is routed to the appropriate page:

• credit_card: BinNumberPage (enter card bin number)

• funds_transfer: FundsTransferChoicePage (select bank account)

• bkm_express: BexSelectionPage (BKM Express flow)

• loyalty_money: LoyaltyMoneyPage (use loyalty points)

• cash_register: CashRegisterPage (cash register payment)

• gpay: GPaySelectionPage (Google Pay flow)

• redirection: RedirectionPaymentSelectedPage (redirect to payment provider)

• stored_card: MobilExpressSelectionPage (use stored card)

• masterpass: MasterpassBinNumberPage (Masterpass flow)

• masterpass_rest: MasterpassRestBinNumberPage (Masterpass REST API flow)

• credit_payment: CreditPaymentSelectionPage (credit/installment payment)

• pay_later: PayLaterCompletePage (buy now pay later)

• saved_card: SavedCardSelectionPage (use saved card)

• confirmation: ConfirmationPaymentAgreementCheckPage (confirmation required)

• b2b: B2BPage (B2B payment)

• wallet: WalletSelectionPage (digital wallet)

• pay_on_delivery: If multiple payment choices available: PayOnDeliveryPaymentChoicePage, otherwise: PayOnDeliveryPage

• gift_card: GiftCardPaymentPage (complete order fully covered by gift cards)

Partial gift card payment: When gift cards are applied but do not fully cover the order, the user selects a regular payment option here. Selecting a non-gift-card payment type does not remove the applied gift card reservations. During order placement, the gift card amounts are charged first; the remaining balance is charged to the selected payment method.

Cascading Invalidation:

• Selecting a new payment option clears previous payment-related data

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

payment_optionintegerRequired

Primary key of the selected payment option. Must be an active payment option that passes availability rules.

Responses

200

Payment option selected successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=PaymentOptionSelectionPage

HTTPcURLJavaScriptPython

Select credit card paymentSelect pay on deliverySelect gift card payment (full coverage)

200

Payment option selected successfully

Get BIN Number Page context

get

Returns the context for entering the card BIN (Bank Identification Number). This page captures the first 6-8 digits of the credit card to determine card type, bank, and available installment options.

Preconditions:

• Payment option must be selected and must be credit card type (is_credit_card())

• Basket must not be empty

BIN Number Validation:

• BIN number must be 6 or 8 digits

• System looks up the BIN in the BinNumber database to determine card type

• If BIN not found, falls back to default card configuration

Card Information Extraction:

• Card type (Visa, Mastercard, Amex, etc.)

• Issuing bank

• Available installment options

• Card category (credit, debit, prepaid)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

BIN Number page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=BinNumberPage

HTTPcURLJavaScriptPython

200

BIN Number page context retrieved

Submit Card BIN Number

post

Submits the card BIN number to determine card type and available installments.

BIN Number Processing:

1. Validates that BIN is 6 or 8 digits

2. Looks up BIN in database to find matching card

3. If found: Uses card configuration (bank, type, installments)

4. If not found: Uses default card configuration

Card Info Object:

• bin_number: The submitted BIN (first 6-8 digits)

• card: Card model with bank, type, and installment relationships

Next Pages:

• InstallmentSelectionPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

bin_numberstringRequired

First 6 or 8 digits of the credit card (BIN - Bank Identification Number). Used to determine card type, bank, and available installment options. Must contain only digits.

Example: 542119Pattern: ^\d{6,8}$

Responses

200

BIN number submitted successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=BinNumberPage

HTTPcURLJavaScriptPython

6-digit BIN number8-digit BIN number

200

BIN number submitted successfully

Get Installment Selection Page context

get

Returns available installment options for the card. Displays installment options with interest rates and monthly payments.

Preconditions:

• Card info must be entered (check_card_info_entered)

• Basket must not be empty

Installment Calculation:

• Installment options are retrieved from the card's installment configuration

• Each installment includes:

  • Installment count (1, 3, 6, 9, 12, etc.)

  • Interest rate percentage

  • Total amount with interest

  • Monthly payment amount

• Installment count of 1 means no installment (single payment)

Installment Filtering:

• Installments are filtered through INSTALLMENT_FILTERS dynamic setting

• Filters can restrict options based on:

  • Basket amount thresholds

  • User segmentation

  • Campaign eligibility

  • Currency requirements

• Filter messages are returned to inform users of restrictions

Installment Messages:

• Gateway-specific promotional messages

• Installment availability notices

• Special campaign information from payment gateway

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Installment selection page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=InstallmentSelectionPage

HTTPcURLJavaScriptPython

200

Installment selection page context retrieved

Select Installment Option

post

Sets the selected installment option for the credit card payment.

Validation:

• Selected installment must belong to the card's available installments

• Installment must be active

Interest Calculation:

• Total amount is recalculated with selected installment's interest rate

• Monthly payment amount is calculated (total / installment_count)

• Interest-free installments may be available based on campaigns

Selected Campaign/Rewards Reset:

• Selecting an installment clears previously selected campaigns

• Clears previously selected rewards

• Campaigns and rewards are re-evaluated based on new total with interest

Next Pages:

• CreditCardConfirmationPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

installmentintegerRequired

Primary key of the selected installment option. Must be one of the installments available for the card. Installment count of 1 represents single payment (no installment).

Responses

200

Installment selected successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=InstallmentSelectionPage

HTTPcURLJavaScriptPython

Single payment (no installment)3 installments6 installments

200

Installment selected successfully

Get Credit Card Confirmation Page context

get

Returns the context for entering full credit card details and completing payment. This is the final step before payment processing or 3D Secure verification.

Preconditions:

• Installment must be selected (check_installment_selected)

• Basket must not be empty

Credit Card Fields Required:

• Card number (full 16-digit number)

• Card holder name

• Expiration month and year

• CVV/CVC security code

• Card nickname (optional, for saving card)

Campaign and Rewards Integration:

• Gateway may support bank-specific campaigns

• Gateway may support loyalty rewards (points/miles)

• Context indicates if these features are available

3D Secure Support:

• Page checks if 3D Secure is required for the transaction

• Browser information is collected for 3D Secure verification

• If 3D Secure required, routes to CreditCardThreeDSecurePage

Save Card Feature:

• Authenticated users can save card for future purchases

• Guest users cannot save cards

• Card details are tokenized and stored securely

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Credit card confirmation page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=CreditCardConfirmationPage

HTTPcURLJavaScriptPython

200

Credit card confirmation page context retrieved

Submit Credit Card Details and Process Payment

post

Submits full credit card details and processes the payment. May route to 3D Secure verification or complete order directly.

Required Fields:

• card_number: Full 16-digit card number

• card_holder: Cardholder name as printed on card

• card_month: Expiration month (MM format, e.g., "01", "12")

• card_year: Expiration year (YYYY format, e.g., "2026")

• card_cvv: CVV/CVC security code (3-4 digits)

• agreement: User must accept terms and conditions (boolean, must be true)

Optional Fields:

• card_name: Nickname for saved card (required if save is true)

• save: Whether to save card for future use (boolean, default false)

• use_three_d: User preference for 3D Secure (may be overridden by rules)

• client_time: Client-side timestamp for fraud detection

• Browser information fields for 3D Secure:

  • browser_java_enabled: Boolean

  • browser_language: Language code (e.g., "en-US")

  • browser_color_depth: Screen color depth (e.g., "24")

  • browser_screen_height: Screen height in pixels

  • browser_screen_width: Screen width in pixels

  • browser_time_zone: Timezone offset in minutes

  • browser_header: Accept header (auto-captured)

  • browser_user_agent: User agent string (auto-captured)

Card Validation:

• Card number validated using Luhn algorithm

• Expiration date must be in the future

• CVV must be 3-4 digits

• Cardholder name validated against format rules

3D Secure Decision: System determines if 3D Secure is required based on:

• Payment gateway configuration

• Card type and BIN rules

• Transaction amount thresholds

• User risk profile

• Bank requirements

Save Card Processing:

• If save is true and user is authenticated: Card is tokenized and saved

• Card details are encrypted and stored securely

• Only token and last 4 digits are retained

• Saved cards can be used in future checkouts

Identity Number Validation:

• If IDENTITY_NUMBER_REQUIRED_AMOUNT setting is configured:

  • Validates shipping address has identity_number field

  • Required when order total exceeds configured threshold

3D Secure Decision Logic:

• Master switch: THREE_D_SECURE_ENABLED must be true

• If enabled, evaluates THREE_D_SECURE_RULES conditions:

  • Amount limits

  • Guest user checks

  • First order checks

  • POS terminal restrictions

  • Failed attempt limits per user/IP

  • Currency restrictions

• If ANY rule returns true, 3D Secure is required

Next Pages:

• If 3D Secure required: CreditCardThreeDSecurePage

• If 3D Secure not required: ThankYouPage (order completed)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

card_numberstringRequired

Full credit card number (16 digits). Validated using Luhn algorithm. Spaces are automatically removed.

Example: 5421190000000004Pattern: ^\d{16}$

card_holderstringRequired

Cardholder name as printed on the card. Must contain only letters and spaces. Validated against format rules.

Example: JOHN DOE

card_monthstringRequired

Card expiration month in MM format. Must be between 01 and 12.

Example: 12Pattern: ^(0[1-9]|1[0-2])$

card_yearstringRequired

Card expiration year in YYYY format. Must be current year or future.

Example: 2026Pattern: ^\d{4}$

card_cvvstringRequired

Card security code (CVV/CVC). Must be 3-4 digits depending on card type.

Example: 123Pattern: ^\d{3,4}$

card_namestringOptional

Nickname for the card if saving for future use. Required when save is true. Optional otherwise.

Example: My Visa Card

agreementboolean · enumRequired

User must accept terms and conditions to proceed. Must be true.

Possible values:

savebooleanOptional

Whether to save the card for future purchases. Only available for authenticated users. Guest users cannot save cards.

Default: false

use_three_dbooleanOptional

User preference for 3D Secure verification. May be overridden by system rules. Optional field.

client_timestring · date-timeOptional

Client-side timestamp for fraud detection

browser_java_enabledbooleanOptional

Whether Java is enabled in the browser

browser_languagestringOptional

Browser language code (e.g., "en-US", "tr-TR")

Example: en-US

browser_color_depthstringOptional

Screen color depth in bits (e.g., "24", "32")

Example: 24

browser_screen_heightstringOptional

Screen height in pixels

Example: 1080

browser_screen_widthstringOptional

Screen width in pixels

Example: 1920

browser_time_zonestringOptional

Timezone offset from UTC in minutes. Example: UTC-4 would be "240" (4 hours * 60 minutes)

Example: 240

Responses

200

Credit card details submitted successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=CreditCardConfirmationPage

HTTPcURLJavaScriptPython

Complete payment without saving cardComplete payment and save card

200

Credit card details submitted successfully

Get Credit Card 3D Secure Page context

get

Returns the context for 3D Secure verification redirect. This page handles the redirect to the bank's 3D Secure authentication page and processes the return response.

3D Secure Flow:

1. User is redirected to bank's 3D Secure page

2. User completes authentication (SMS OTP, biometric, etc.)

3. Bank redirects back with verification result

4. System validates the response and completes payment

Redirect URL:

• redirect_url: Internal endpoint that handles 3D Secure initiation

• This endpoint generates the bank redirect form with necessary parameters

Cached Card Data:

• Card details are temporarily cached during 3D Secure flow

• Cache key is based on pre-order hash

• Cached data is encrypted using Django's signing framework

Security Considerations:

• Sensitive card data (number, CVV) marked with @sensitive_variables

• Card data cleared from cache after successful verification

• Failed verifications also clear cached data

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

3D Secure page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=CreditCardThreeDSecurePage

HTTPcURLJavaScriptPython

200

3D Secure page context retrieved

Process 3D Secure Return Response

post

Processes the return response from 3D Secure verification and completes payment. This endpoint is called when the bank redirects back after authentication.

Return Parameters: Gateway-specific parameters are passed back from the 3D Secure provider. Common parameters include:

• three_d_secure: Verification status (boolean)

• success: Transaction success status (boolean)

• md: Merchant data passed through 3D Secure flow

• xid: Transaction identifier from 3D Secure

• eci: Electronic Commerce Indicator

• cavv: Cardholder Authentication Verification Value

• mdStatus: MD status code from provider

• Additional gateway-specific parameters

MD Status Validation:

• Gateway validates the mdStatus and other response parameters

• Each gateway has specific validation logic via is_md_status_valid()

• Failed validation returns user to payment page with error

Transaction Creation:

• Successful 3D Secure verification creates order and transaction

• Transaction ID format: 3D_RETURN_{order_number}_{suffix}

• Sensitive parameters are filtered from transaction log

Cached Card Retrieval:

• Card details are retrieved from cache using pre-order hash

• If cache expired, payment fails and user must restart

• Successful payment clears cached card data

Save Card After 3D Secure:

• If user chose to save card, it's tokenized after successful payment

• Save operation happens asynchronously via Celery task

Next Pages:

• Success: ThankYouPage (order completed)

• Failure: Redirects back to CreditCardConfirmationPage with error

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

three_d_secureboolean · enumRequired

3D Secure verification status. Must be true for successful verification.

Possible values:

successboolean · enumRequired

Transaction success status. Must be true for successful transaction.

Possible values:

mdstringOptional

Merchant data passed through 3D Secure flow

xidstringOptional

Transaction identifier from 3D Secure provider

ecistringOptional

Electronic Commerce Indicator from 3D Secure

cavvstringOptional

Cardholder Authentication Verification Value

liqpay_tokenstringOptional

LiqPay-specific token (gateway-specific)

statusstringOptional

Status from payment gateway

paymentIdstringOptional

Payment identifier from gateway

conversationDatastringOptional

Conversation data from gateway

conversationIdstringOptional

Conversation identifier from gateway

mdStatusstringOptional

MD status code from 3D Secure provider. Different values indicate authentication success/failure. Gateway-specific validation logic.

bodyobjectOptional

Additional gateway-specific response data

Responses

200

3D Secure verification processed

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=CreditCardThreeDSecurePage

HTTPcURLJavaScriptPython

200

3D Secure verification processed

Get GPay Redirect Page context

get

Returns the context for the GPay Redirect Page, which is the second step in the Garanti Pay checkout flow. At this point the system is ready to initiate the external redirect to the Garanti Pay hosted payment page.

Preconditions:

• Basket must not be empty

• The selected payment option must be of gpay type

• No redirect transaction has been recorded for this checkout session yet (the session must not already contain a Garanti Pay transaction identifier)

• An order number must have been assigned by the preceding GPay Selection step

• Card information associated with the GPay virtual BIN number must be present in the current checkout session

Page Context:

• Returns an empty object {}. All relevant order and payment summary data is available in the pre_order field of the response.

Already Completed:

• This step is considered already completed when a redirect transaction identifier is already stored in the checkout session. When this condition is met, the checkout flow automatically advances to GPayCompletePage without requiring a POST request.

Post-Order Flow:

• Available in the post-order re-payment flow. When is_post_order is true, this page participates in the GPay re-payment sequence for existing orders that require an additional payment attempt.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

GPay Redirect Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=GPayRedirectPage

HTTPcURLJavaScriptPython

200

GPay Redirect Page context retrieved

Initiate GPay Redirect Transaction

post

Initiates the Garanti Pay redirect flow by creating a redirect-type transaction record and storing the resulting transaction identifier in the checkout session. After successful submission, the flow advances to GPayCompletePage, which supplies the external redirect URL to the Garanti Pay hosted payment page.

Request Body:

• No input fields are required. The request body must be empty. Submit the POST with no body, or pass an empty form-encoded payload {}.

Processing Flow:

1. The client IP address is captured from the incoming request and stored in the checkout session for transaction logging and fraud prevention.

2. A redirect-type transaction record is persisted with the following attributes:

   • Transaction identifier: REDIRECT_GPAY_{order_number}

   • Transaction type: redirect

   • Succeeded flag: true

   • 3D Secure flag: false

   • Amount: the order total inclusive of any applicable installment interest

   • Currency: taken from the checkout session currency

3. The persisted transaction identifier is written into the checkout session state, marking this step as complete and enabling the is_already_done check on subsequent GET requests.

Backward Navigation:

• When the user navigates back from this step, the stored redirect transaction identifier and any redirect-state marker are removed from the checkout session, reverting the flow to the GPay Selection step.

Next Page:

• GPayCompletePage — Provides the redirect URL and processes the Garanti Pay callback once the user returns from the external hosted payment page.

Error Handling:

• If the POS configuration is missing or invalid, transaction creation fails and an error is returned. The checkout session is not modified on failure.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

objectOptional

No input fields are required for this step. The request body must be empty. Any fields submitted in the body are not processed by this page and will not cause a validation error; however, the Garanti Pay gateway is not involved at this step, so gateway-specific parameters are irrelevant here.

Responses

200

Redirect transaction initiated — flow advancing to GPayCompletePage

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=GPayRedirectPage

HTTPcURLJavaScriptPython

200

Redirect transaction initiated — flow advancing to GPayCompletePage

Get Funds Transfer Choice Page context

get

Returns available bank accounts for funds transfer (wire transfer/EFT) payment. User selects which bank account to transfer money to.

Preconditions:

• Payment option must be selected and must be funds transfer type (is_funds_transfer())

• Basket must not be empty

Bank Account Selection:

• Lists all active bank accounts configured in the system

• Each bank account includes: bank name, account holder, IBAN, currency

• User selects one bank account for payment instructions

Auto-selection:

• If only one bank account is available and no POS slug configured:

  • Bank account is automatically selected

  • Page is skipped

  • Routes directly to FundsTransferPage

Reference Code Generation:

• Some payment gateways support reference codes for tracking

• If gateway has has_reference_code capability:

  • Reference code is generated when bank account is selected

  • Reference code is stored in pre_order.data['funds_transfer']

  • Used to match customer payment with order

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Funds transfer choice page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=FundsTransferChoicePage

HTTPcURLJavaScriptPython

200

Funds transfer choice page context retrieved

Select Bank Account for Funds Transfer

post

Sets the selected bank account for funds transfer payment.

Validation:

• Selected bank account must be active

• Basket amount must be greater than or equal to zero

Reference Code Generation:

• If payment gateway supports reference codes (has_reference_code):

  • Generates unique reference code for the order

  • Uses order number, amount, currency as input

  • Includes user email, addresses, and site domain

  • Stores reference code in pre_order.data['funds_transfer']['reference_code']

• Reference code is displayed to user on next page for payment matching

Order Number Assignment:

• Pre-order number is assigned at this step (if not already assigned)

• Order number used in reference code generation

Bank Account Change Handling:

• If user changes bank account selection:

  • Reference code is regenerated

  • Previous reference code is invalidated

Next Pages:

• FundsTransferPage (display payment instructions)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

bank_accountintegerRequired

Primary key of the selected bank account. Must be an active bank account configured in the system.

Responses

200

Bank account selected successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=FundsTransferChoicePage

HTTPcURLJavaScriptPython

200

Bank account selected successfully

Get Funds Transfer Page context

get

Returns payment instructions for funds transfer. Displays bank account details and reference code for customer to complete payment.

Preconditions:

• Payment option must be funds transfer type

• Bank account must be selected (funds_transfer_bank)

• Basket must not be empty

Payment Instructions:

• Bank account details (IBAN, account holder, bank name)

• Order number for reference

• Reference code (if gateway supports it)

• Total amount to transfer

• Currency information

Reference Code Context:

• Retrieved from pre_order.data['funds_transfer']

• Displayed prominently for customer to include in transfer

• Used by payment reconciliation system to match transfers

Order Status:

• Order is created in "pending" status

• Waiting for payment confirmation

• Payment team manually confirms transfer receipt

• Order status updated to "confirmed" after verification

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Funds transfer page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=FundsTransferPage

HTTPcURLJavaScriptPython

200

Funds transfer page context retrieved

Complete Funds Transfer Order

post

Completes the order creation for funds transfer payment. Order is created in pending status, awaiting payment confirmation.

Required Fields:

• agreement: User must accept terms and conditions (boolean, must be true)

Validation:

• Basket amount must be greater than or equal to zero

• Bank account must be selected

• Payment option must be funds transfer type

Order Creation:

• Order is created with status "pending_payment" or "awaiting_funds_transfer"

• Order details include:

  • Selected bank account information

  • Reference code (if applicable)

  • Payment instructions

• User receives confirmation email with payment details

• Stock is reserved (depending on configuration)

Order Number:

• Order number is NOT regenerated at this step

• Uses existing pre-order number assigned in previous step

Payment Confirmation Flow:

1. User completes bank transfer using provided details

2. Payment team receives transfer notification

3. Payment team matches transfer using reference code/order number

4. Order status updated to "confirmed"

5. Fulfillment process begins

Next Pages:

• ThankYouPage (order completed, awaiting payment)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

agreementboolean · enumRequired

User must accept terms and conditions to proceed. Must be true.

Possible values:

Responses

200

Funds transfer order completed successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=FundsTransferPage

HTTPcURLJavaScriptPython

200

Funds transfer order completed successfully

Get Pay on Delivery Payment Choice Page context

get

Returns the available payment choices for a pay-on-delivery payment option. This page allows the user to select how they will pay at the point of delivery (e.g., cash, credit card terminal, etc.).

Preconditions:

• Basket must not be empty

• Payment option must be selected and must be of pay-on-delivery type

Skip Conditions:

• Page is skipped when is_post_order is true (post-order flow)

• Page is skipped entirely when the selected payment option's payment_choices list is empty (no choices to present). In this case the flow proceeds directly to PayOnDeliveryPage.

Routing from PaymentOptionSelectionPage:

• Routes here when skip_pod_choices is false and there is at least one choice, or when there is more than one choice regardless of skip_pod_choices.

• When skip_pod_choices is true and exactly one choice exists, the choice is auto-selected and this page is skipped.

Payment Choice Object: Each item in payment_choices contains:

• value: internal identifier string used as the form value

• label: human-readable display name

• price: additional fee charged for this payment method (as decimal string)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Pay on delivery payment choice page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=PayOnDeliveryPaymentChoicePage

HTTPcURLJavaScriptPython

200

Pay on delivery payment choice page context retrieved

Select Pay on Delivery Payment Choice

post

Saves the user's selected payment choice for pay-on-delivery.

Required Fields:

• payment_choice: The value string of one of the items returned in payment_choices from the GET context. Submitting a value not present in that list causes a validation error.

Validation:

• Basket amount must be greater than zero

• payment_choice must match one of the valid values returned by the payment option's choices

State Update:

• pre_order.payment_choice is set to the selected PaymentChoice object

Next Pages:

• SendSmsPage — when the payment option's sms_verification configuration is true

• PayOnDeliveryPage — in all other cases

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

payment_choicestringRequired

The value string of one of the payment choices returned in the payment_choices list from the GET context of PayOnDeliveryPaymentChoicePage. Submitting a value not present in that list causes a validation error.

Example: cash

Responses

200

Payment choice selected successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=PayOnDeliveryPaymentChoicePage

HTTPcURLJavaScriptPython

Select cash paymentSelect credit card terminal

200

Payment choice selected successfully

Get Pay on Delivery Page context

get

Returns the confirmation page for a pay-on-delivery order. The user reviews the order and accepts the terms and conditions before the order is created.

Preconditions:

• Basket must not be empty

• Payment option must be pay-on-delivery type

• If the payment option has payment_choices configured, a choice must already have been selected (via PayOnDeliveryPaymentChoicePage)

• If the payment option has sms_verification: true in its configuration, the user must have completed SMS verification (phone number entered, code sent and entered correctly)

Page Context:

• Returns an empty object {}. All order summary information is available in the pre_order field of the response.

Skip Conditions:

• Page is skipped when is_post_order is true (post-order flow)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Pay on delivery page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=PayOnDeliveryPage

HTTPcURLJavaScriptPython

200

Pay on delivery page context retrieved

Complete Pay on Delivery Order

post

Creates the order for pay-on-delivery after the user accepts the terms and conditions.

Required Fields:

• agreement: Must be true. Submitting false or omitting this field causes a validation error.

Validation:

• Basket amount must be greater than zero

Order Creation:

• Order is created via PaymentPageMixin.process_order

• After creation: basket is submitted, contracts are saved, confirmation email is sent, order completion SMS is sent

• pre_order.card_info is reset to null

• pre_order.installment is reset to null

Order Number:

• The order number is regenerated at this step unless it was already set

Next Pages:

• ThankYouPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

agreementboolean · enumRequired

User must accept terms and conditions to proceed. Must be true.

Possible values:

Responses

200

Pay on delivery order created successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=PayOnDeliveryPage

HTTPcURLJavaScriptPython

200

Pay on delivery order created successfully

Get BKM Express Selection Page context

get

Returns the context for the BKM Express (BEX) payment initiation page. This page triggers the BKM Express API to obtain a one-time ticket that is required before the user can enter card details via the BKM Express JS widget.

Preconditions:

• Basket must not be empty

• Payment option must be selected and must be of BKM Express type (is_bkm_express())

Page Context:

• Returns an empty object {} (no context fields are exposed to the client at GET time). The BKM Express JS widget credentials (path, token, transaction_id) are provided on the next page (BexBinNumberPage).

Skip Conditions:

• No skip conditions beyond the standard post-order check. available_for_post_order is true, so the page is accessible in post-order flows.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

BKM Express selection page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=BexSelectionPage

HTTPcURLJavaScriptPython

200

BKM Express selection page context retrieved

Initiate BKM Express Session

post

Accepts the terms and conditions and initiates a BKM Express session by calling the BKM Express API to obtain a one-time ticket.

Required Fields:

• agreement: Must be true. Submitting false or omitting this field causes a validation error.

Validation:

• Basket amount must be greater than zero

Processing:

1. An order number is assigned to the pre-order (pre_order.set_number())

2. BexService.one_time_ticket() is called with the order number, total amount (with interest), user information, and remote address

3. On success: path, token, and transaction_id from the BKM response are stored in pre_order.data and the transaction_id is mapped to the pre-order hash in cache

4. On failure: order number is reset and a non_field_errors error is returned

Next Pages:

• BexBinNumberPage — on success

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

agreementboolean · enumRequired

User must accept terms and conditions to proceed. Must be true.

Possible values:

Responses

200

BKM Express session initiated successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=BexSelectionPage

HTTPcURLJavaScriptPython

200

BKM Express session initiated successfully

Get BKM Express BIN Number Page context

get

Returns the BKM Express widget credentials needed to render the BKM Express JS widget in the browser. The widget handles card number entry on behalf of BKM.

Preconditions:

• Basket must not be empty

• A valid BKM Express ticket must be present, meaning path, token, and transaction_id must all exist in the pre-order session data (set by BexSelectionPage)

Page Context:

• path: BKM Express API path used to initialise the JS widget

• token: Session token issued by BKM Express

• transaction_id: Unique transaction identifier assigned by BKM Express

These three values are passed directly to the BKM Express JS SDK to render the card entry widget. The widget then sends the card BIN to the server via a separate callback endpoint (/orders/bex-installments/), which eventually results in a POST to this page with the resolved BIN number.

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

BKM Express BIN number page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=BexBinNumberPage

HTTPcURLJavaScriptPython

200

BKM Express BIN number page context retrieved

Submit Card BIN Number for BKM Express

post

Submits the card BIN number (first 6-8 digits) resolved through the BKM Express widget. The BIN is used to identify the card type and retrieve the available installment options.

Required Fields:

• bin_number: First 6 or 8 digits of the card. Must contain only digits.

BIN Resolution:

• System looks up the BIN in the BinNumber table. If found, the matching card record (bank, card type, installments) is used.

• If no match is found, the system falls back to the default card configuration defined by DEFAULT_CARD_SLUG.

State Update:

• pre_order.card_info is set to a CardInfo object containing bin_number and the resolved card record.

Next Pages:

• BexInstallmentSelectionPage

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

bin_numberstringRequired

First 6 or 8 digits of the card (BIN - Bank Identification Number). Used to identify the card type and available installment options for BKM Express. Must contain only digits.

Example: 542119Pattern: ^\d{6,8}$

Responses

200

BIN number submitted successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=BexBinNumberPage

HTTPcURLJavaScriptPython

6-digit BIN number8-digit BIN number

200

BIN number submitted successfully

Get BKM Express Installment Selection Page context

get

Returns the available installment options for the BKM Express payment. Installment options are determined by the card identified in the previous step (BexBinNumberPage).

Preconditions:

• Basket must not be empty

• Card info must have been entered (pre_order.card_info must be set, i.e., BexBinNumberPage must have been completed)

Page Context:

• installments: List of available installment options for the resolved card. Each entry contains pk, installment_count, label, price_with_accrued_interest, and monthly_price_with_accrued_interest calculated against the current unpaid basket amount.

• card_type: Card type details (name, slug, logo), derived from pre_order.card_info.card.card_type.

• installment_messages: List of informational strings returned by InstallmentService (e.g., filter messages or promotion notices).

Installment Filtering:

• InstallmentService.get_pre_order_installments() is called, which applies the INSTALLMENT_FILTERS dynamic setting rules before returning the list.

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

BKM Express installment selection page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=BexInstallmentSelectionPage

HTTPcURLJavaScriptPython

200

BKM Express installment selection page context retrieved

Select Installment Option for BKM Express

post

Sets the selected installment option for the BKM Express payment.

Required Fields:

• installment: The installment_count integer (e.g., 1 for single payment, 3 for three installments). This is not a primary key — it is the installment count value. The system looks up the matching active Installment record for the resolved card by installment_count.

Validation:

• installment must match an active Installment record linked to the card resolved in BexBinNumberPage. If no matching record is found, pre_order.installment is set to null (no explicit error message is returned for this case; the flow simply does not advance past this page).

• If pre_order.card_info is not set at validation time, a validation error is returned with the message "You need to enter your card number".

State Update:

• pre_order.installment is set to the resolved Installment object.

Next Pages:

• BexNoncePage

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

installmentintegerRequired

The installment count to select (e.g., 1 for single payment, 3 for three installments). This is not a primary key. The system resolves the matching active Installment record for the card by installment_count.

Example: 3

Responses

200

Installment selected successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=BexInstallmentSelectionPage

HTTPcURLJavaScriptPython

Select single payment (no installments)Select 3 installments

200

Installment selected successfully

Get BKM Express Nonce Page context

get

Returns the context for the BKM Express nonce waiting page. At this stage the BKM Express JS widget completes the payment on the BKM side and sends the result (nonce) back to the server via an asynchronous callback. The client waits for this callback to complete.

Preconditions:

• Basket must not be empty

• A valid BKM Express ticket must be present (path, token, and transaction_id must exist in the pre-order session data)

Page Context:

• Returns an empty object {}.

Step Completion: This page is considered already completed (is_already_done) when either:

• The payment option is BKM Express and cached nonce data is present (i.e., the BKM widget callback has already been received), or

• The order has already been finalised (order_finalized() is true)

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

BKM Express nonce page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=BexNoncePage

HTTPcURLJavaScriptPython

200

BKM Express nonce page context retrieved

Submit BKM Express Nonce (BKM Widget Callback)

post

Receives and stores the payment result (nonce) returned by the BKM Express JS widget after the user completes the payment on the BKM side.

This endpoint is called by the BKM Express JS widget callback, not directly by the end user.

Required Fields:

• order_id: Order identifier as returned by BKM Express

• transaction_id: Transaction identifier matching the one stored in the pre-order session data

• data: JSON object containing the BKM Express payment result. Required sub-fields:

  • status: Must be "ok" for a successful payment

  • paymentPurchased: Must be truthy (indicates payment was charged)

  • totalAmount: Decimal string with comma as decimal separator (e.g., "159,99"). Validated against the current pre-order total with interest.

Validation:

• data.status must equal "ok"

• data.paymentPurchased must be truthy

• data.totalAmount (after replacing , with .) must match pre_order.get_total_amount_with_interest()

State Update:

• The validated nonce data is stored in cache under a key derived from pre_order.basket.get_hash(). This cached value is later consumed by BexCompletePage.

Backward Navigation:

• When navigating backward from this page, the nonce key is removed from pre_order.data.

Next Pages:

• BexCompletePage

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

order_idstringRequired

Order identifier as returned by the BKM Express callback. Corresponds to the order number assigned in BexSelectionPage.

Example: ORD-2026-0001

transaction_idstringRequired

Transaction identifier issued by BKM Express. Must match the transaction_id stored in the pre-order session data from BexSelectionPage.

Example: TXN-20260401-001

Responses

200

Nonce received and stored successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=BexNoncePage

HTTPcURLJavaScriptPython

200

Nonce received and stored successfully

Get BKM Express Complete Page context

get

Returns the context for the BKM Express order completion page. At this stage the nonce data has been received and cached; the page is ready to finalise the order.

Preconditions:

• Basket must not be empty

• Payment option must be BKM Express type

• Cached nonce data must be present (stored by BexNoncePage)

Page Context:

• Returns an empty object {}.

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

BKM Express complete page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=BexCompletePage

HTTPcURLJavaScriptPython

200

BKM Express complete page context retrieved

Finalise BKM Express Order

post

Finalises the BKM Express order by retrieving the cached nonce data and processing the payment through the BKM Express gateway.

No direct user input is required. The input is retrieved automatically from the cache using the pre-order hash. The cached nonce data (stored by BexNoncePage) is validated with the same rules as BexNoncePage before the order is processed.

Processing:

1. Cached nonce data is retrieved via get_cached_nonce_data(pre_order)

2. The nonce data is re-validated with BexNonceInputSerializer

3. Payment is processed via PaymentPageMixin.process_order

4. After creation: basket is submitted, contracts are saved, confirmation email is sent, order completion SMS and notification are sent

Order Number:

• The order number is not regenerated at this step (set_number=False). The number was already assigned during BexSelectionPage.

Next Pages:

• ThankYouPage

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

objectOptional

No user-supplied fields. Submit an empty body or omit the body entirely. Input is read automatically from the server-side nonce cache.

Responses

200

BKM Express order finalised successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=BexCompletePage

HTTPcURLJavaScriptPython

200

BKM Express order finalised successfully

Get Masterpass REST BIN Number Page context

get

Returns the context for the Masterpass REST BIN number page. The card details are collected on the client side via the Masterpass JS SDK; only the BIN (and a flag indicating whether the card is a stored Masterpass card) is sent back to the server so it can identify the card type and determine the available installment options.

Preconditions:

• Basket must not be empty

• Payment option must be of Masterpass REST type (is_masterpass_rest())

Page Context:

• Returns an empty object {}. No additional data is exposed at GET time — the card data flow runs through the Masterpass JS SDK.

Step Completion: This page is considered already completed (is_already_done) when both of the following are true:

• pre_order.card_info is populated, and

• The selected payment option is Masterpass REST.

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Masterpass REST BIN number page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=MasterpassRestBinNumberPage

HTTPcURLJavaScriptPython

200

Masterpass REST BIN number page context retrieved

Submit Card BIN Number for Masterpass REST

post

Submits the card BIN number captured by the Masterpass JS SDK. The BIN is used to identify the card type (bank, card type, available installment records). If the BIN cannot be matched in the BinNumber table, the system falls back to the default card configuration (DEFAULT_CARD_SLUG).

Required Fields:

• bin_number: First 6 or 8 digits of the card. Must contain only digits.

Optional Fields:

• is_masterpass_stored_card: Boolean flag indicating whether the card is being used from the user's Masterpass stored cards. Defaults to false.

Validation:

• bin_number must be a 6 or 8 digit numeric string. A non-matching value returns the error "Please enter a valid bin number.".

• If the active payment option has provision_enabled = true and the resolved card is a debit card, a validation error is raised: "You can only use credit cards.".

State Update:

• pre_order.card_info is set to a CardInfo object containing the bin_number and the resolved card.

• pre_order.data["is_masterpass_stored_card"] is set to the submitted flag.

• pre_order.data["is_mastercard"] is set based on the card type detected from the BIN (true when the card brand is master).

Backward Navigation:

• On backward navigation, both is_masterpass_stored_card and is_mastercard keys are removed from pre_order.data.

Next Pages:

• MasterpassRemoteInstallmentPage — when the active payment option's config has an installment_slug set (i.e., a remote installment service is configured for this Masterpass POS).

• MasterpassRestInstallmentPage — otherwise (default flow).

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

bin_numberstringRequired

First 6 or 8 digits of the card (BIN - Bank Identification Number). Captured by the Masterpass JS SDK on the client side. Must contain only digits and have a length of 6 or 8.

Example: 542119Pattern: ^\d{6,8}$

is_masterpass_stored_cardbooleanOptional

Flag indicating whether the card BIN comes from the user's stored Masterpass cards. Stored on the pre-order as pre_order.data["is_masterpass_stored_card"].

Default: falseExample: false

Responses

200

BIN submitted successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=MasterpassRestBinNumberPage

HTTPcURLJavaScriptPython

6-digit BIN, fresh card entry8-digit BIN, stored Masterpass card

200

BIN submitted successfully

Get Masterpass REST Installment Selection Page context

get

Returns the available installment options for the Masterpass REST flow. Installments are derived from the card identified in the previous step (MasterpassRestBinNumberPage) and filtered by the INSTALLMENT_FILTERS rules through InstallmentService.

Preconditions:

• Basket must not be empty

• Card information must have been entered (pre_order.card_info must be set, i.e., MasterpassRestBinNumberPage must have been completed)

Page Context:

• installments: List of available installment options for the resolved card. Each entry contains pk, installment_count, label, price_with_accrued_interest, and monthly_price_with_accrued_interest calculated against the current unpaid basket amount.

• card_type: Card type details (name, slug, logo), derived from pre_order.card_info.card.card_type.

• installment_messages: List of informational strings returned by InstallmentService (e.g., filter messages or promotion notices).

Skip Conditions:

• This page is considered already completed (is_already_done) when pre_order.installment is set and the active payment option is Masterpass REST.

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Masterpass REST installment selection page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=MasterpassRestInstallmentPage

HTTPcURLJavaScriptPython

200

Masterpass REST installment selection page context retrieved

Select Installment Option for Masterpass REST

post

Sets the selected installment option for the Masterpass REST flow.

Required Fields:

• installment: Primary key (pk) of the Installment record to apply. The PK must reference an active installment linked to the card resolved in MasterpassRestBinNumberPage.

Validation:

• installment must be the PK of an active Installment belonging to the card in pre_order.card_info. Submitting a PK outside of that set returns a validation error.

State Update:

• pre_order.installment is set to the resolved Installment.

• pre_order.selected_campaign and pre_order.selected_rewards are reset to null (inherited from InstallmentSelectionPage).

• pre_order.payment_choice is reset to null.

Backward Navigation:

• On backward navigation, pre_order.installment is reset to null.

Next Pages:

• MasterpassRestOrderNoPage

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

installmentintegerRequired

Primary key (pk) of the Installment record to select. The PK must reference an active installment linked to the card resolved in MasterpassRestBinNumberPage.

Example: 2

Responses

200

Installment selected successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=MasterpassRestInstallmentPage

HTTPcURLJavaScriptPython

Select single paymentSelect 3 installments

200

Installment selected successfully

Get Masterpass REST Order Number Page context

get

Returns the context for the Masterpass REST order number assignment page. This page assigns the order number that will be used for the subsequent Masterpass payment request and decides whether the transaction must be completed via 3D Secure.

Preconditions:

• Basket must not be empty

• Payment option must be Masterpass REST (check_masterpass_selected)

• Card information must be present (check_card_info_not_empty)

• An installment must be selected, either through pre_order.installment (default flow) or pre_order.data["installment_alt"] (remote installment flow)

Page Context:

• Returns an empty object {}.

Skip Conditions: This page is considered already completed (is_already_done) when both:

• The order number has been assigned (pre_order.order_number_empty() is false), and

• pre_order.redirect_to_three_d is set (either true or false).

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Masterpass REST order number page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=MasterpassRestOrderNoPage

HTTPcURLJavaScriptPython

200

Masterpass REST order number page context retrieved

Assign Order Number and Decide 3D Secure Routing

post

Assigns the order number that will be sent to Masterpass and evaluates whether the transaction must be processed under 3D Secure.

Optional Fields:

• use_three_d: Boolean flag forwarded to the 3D Secure decision rule (check_three_d_secure). When the rule resolves to true, the user will be required to complete a 3D Secure challenge before the subsequent MasterpassRestCompletePage step. Defaults to false.

Processing:

1. The client IP is captured from the request and stored as pre_order.remote_addr.

2. The order number is generated via pre_order.set_number().

3. The 3D Secure decision is computed by check_three_d_secure(...) using the gateway's POS configuration, the user, the basket total, the resolved card, the BIN number, and the submitted use_three_d flag. If the gateway's merchant_type is "custom", the regular pre-order POS is used as the underlying POS and the Masterpass POS is supplied as proxy_pos; otherwise the Masterpass POS is used directly.

4. pre_order.redirect_to_three_d is set to either true or false accordingly.

Backward Navigation:

• On backward navigation: pre_order.remote_addr is cleared, pre_order.reset_number() is called, and redirect_to_three_d is reset to null.

Next Pages:

• MasterpassRestCompletePage

Previous Page (computed dynamically):

• MasterpassRemoteInstallmentPage — when the payment option's config has an installment_slug set

• MasterpassRestInstallmentPage — otherwise

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

use_three_dbooleanOptional

Hint forwarded to check_three_d_secure(...). When the rule resolves to true, the user must complete a 3D Secure challenge before the subsequent MasterpassRestCompletePage step.

Default: falseExample: false

Responses

200

Order number assigned successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=MasterpassRestOrderNoPage

HTTPcURLJavaScriptPython

Default - rule decides 3D routingHint that 3D Secure should be used

200

Order number assigned successfully

Get Masterpass REST Complete Page context

get

Returns the context required to drive the final Masterpass REST payment request from the client. The context contains the MSISDN, the order number, the 3D Secure routing flag, and a set of gateway-specific extras that are passed through to the Masterpass JS SDK.

Preconditions:

• Basket must not be empty

• Payment option must be Masterpass REST (check_masterpass_selected)

• Card information must be present (check_card_info_not_empty)

• An installment must be selected (check_installment_selected)

• Order number must have been generated (check_order_no_generated)

• pre_order.redirect_to_three_d must be set (check_redirect_to_three_d_not_none)

Page Context:

• msisdn: The user's phone number formatted with the country code, obtained from payment_gateway._get_msisdn(...).

• order_no: The previously assigned pre_order.number.

• three_d: pre_order.redirect_to_three_d — true if a 3D Secure challenge is required, otherwise false.

• extras:

  • user_id: The user's PK as a string. null for guest checkouts.

  • bank_ica: ACQ ICA value when the gateway's merchant_type is "custom" (resolved via payment_gateway.get_pos_config(vpos)). null for non-custom gateways.

  • additional_fields: Free-form dict returned by payment_gateway.get_additional_fields(...). Includes user, billing/shipping addresses, remote address, the total with interest, and reward state.

Step Completion:

• is_already_done returns true when the order is finalised (pre_order.order_finalized() is true).

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Masterpass REST complete page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=MasterpassRestCompletePage

HTTPcURLJavaScriptPython

200

Masterpass REST complete page context retrieved

Finalise Masterpass REST Order

post

Finalises the Masterpass REST order. The body of this request reflects the Masterpass / 3D Secure callback payload. Note that all query string parameters from the request URL are merged into the submitted form data, while the amount form key (if any) is removed before validation. This is the mechanism used to consume 3D Secure return parameters that are appended as query string by the gateway.

Required Fields:

• three_d_secure: Must match pre_order.redirect_to_three_d (set during MasterpassRestOrderNoPage). Submitting a mismatching value returns the error "Transaction failed. Please try again.".

Optional / 3D Secure Callback Fields:

• token: Masterpass payment token.

• oid, md, xid, eci, cavv, rnd, hash, hashParams, hashParamsVal, mdStatus, bankIca, paymentReceived, clientId, sign: 3D Secure callback parameters returned by the bank.

• amount: Decimal value (12 digits, 2 decimal places). When provided, it is divided by 100 and validated against pre_order.get_total_amount_with_interest(). A mismatch returns "Transaction failed. Please try again.". Note that the amount form key in the body is stripped before merging the query string, so the value used is the one provided via the bank callback if any.

• transactionType: One of PURCHASE, PURCHASE_3D, DIRECT_PURCHASE, DIRECT_PURCHASE_3D, REGISTER_AND_PURCHASE, REGISTER_AND_PURCHASE_3D.

• status, completeStatus, paymentId, conversationData, conversationId, callbackStatus: Additional Masterpass status fields.

3D Secure Validation:

• When three_d_secure is true:

  • If the gateway has hash_validation_enabled and the request comes from a non-mobile client (client_type is neither ios nor android), the hash is validated via gateway.is_hash_valid(...). A failure returns "Hash values don't match.".

  • The MD status is validated via gateway.is_md_status_valid(...). A failure returns "Transaction failed. Please try again.".

Processing:

1. The base process() is called with the merged data (form body + request query string, with the form amount removed).

2. The set_defaults step runs with set_number=False because the order number was already assigned in MasterpassRestOrderNoPage.

3. When pre_order.redirect_to_three_d is false, skip_create_transaction returns true and no separate transaction record is created at this step. Otherwise a transaction with id "MASTERPASS_<order_number>_<suffix>" is created.

4. The Masterpass payment is processed via the PaymentPageMixin.process_order flow, which submits the basket, saves contracts, and triggers post-completion notifications.

Next Pages:

• ThankYouPage

Backward Navigation:

• This page does not perform any backward state changes (backward() is a no-op).

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

Final Masterpass REST submission payload. The endpoint also merges any request query string parameters into the form data (with the form amount key removed before merging) so that 3D Secure callback parameters appended by the bank are captured automatically.

three_d_securebooleanRequired

Must match pre_order.redirect_to_three_d set in MasterpassRestOrderNoPage. A mismatch returns "Transaction failed. Please try again.".

Example: true

tokenstringOptional

Masterpass payment token issued by the SDK.

Example: mp-token-abc123

oidstringOptional

Order id echoed back by the bank on 3D callback.

Example: ORD-2026-0042

mdstringOptional

3D Secure md parameter from the bank callback.

xidstringOptional

3D Secure xid parameter from the bank callback.

ecistringOptional

3D Secure ECI value from the bank callback.

Example: 05

cavvstringOptional

3D Secure CAVV value from the bank callback.

rndstringOptional

3D Secure random nonce from the bank callback.

hashstringOptional

Bank-issued response hash. Validated via gateway.is_hash_valid when three_d_secure is true and the gateway has hash_validation_enabled (skipped for iOS/Android client types).

hashParamsstringOptional

3D Secure hash params list from the bank callback.

hashParamsValstringOptional

3D Secure hash params values from the bank callback.

mdStatusstringOptional

3D Secure MD status. Validated via gateway.is_md_status_valid when three_d_secure is true. A failure returns "Transaction failed. Please try again.".

Example: 1

bankIcastringOptional

Bank ACQ ICA value passed back by the gateway.

paymentReceivedstringOptional

Payment received indicator returned by the gateway.

amountstring · decimalOptional

Total amount in minor units returned by the bank. Divided by 100 during validation and compared against pre_order.get_total_amount_with_interest(). A mismatch returns "Transaction failed. Please try again.". Note: any amount form field is dropped before request query parameters are merged into the body, so the value used is the one supplied by the bank callback when present.

Example: 16559

clientIdstringOptional

Merchant client id echoed back by the gateway.

signstringOptional

Signature value from the bank callback.

transactionTypestring · enumOptional

Masterpass transaction type.

Example: PURCHASE_3DPossible values:

statusstringOptional

Masterpass status string.

completeStatusstringOptional

Masterpass complete status string.

paymentIdstringOptional

Masterpass payment id.

conversationDatastringOptional

Masterpass conversation data.

conversationIdstringOptional

Masterpass conversation id.

callbackStatusstringOptional

Masterpass callback status string.

Responses

200

Masterpass REST order finalised successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=MasterpassRestCompletePage

HTTPcURLJavaScriptPython

Non-3D flow - token only3D Secure callback parameters

200

Masterpass REST order finalised successfully

Get Masterpass REST Reward List Page context

get

Returns the context for the Masterpass REST reward list page. Unlike the regular RewardListPage, this page does not collect raw card details — the card has already been registered with Masterpass — so only a card alias is required to query the gateway for available rewards.

This is an independent page — submitting it does not advance the main checkout flow.

Preconditions:

• Basket must not be empty

• Payment option must be Masterpass REST (check_masterpass_selected)

• The Masterpass POS gateway must have enable_rewards = true and has_rewards() returning true (check_gateway_has_rewards)

Page Context:

• Returns an empty object {}.

Skip Conditions:

• This page is considered already completed when pre_order.rewards is not None (rewards have already been queried).

Next Pages:

• MasterpassRestRewardSelectionPage

available_for_post_order: inherited from RewardListPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Masterpass REST reward list page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=MasterpassRestRewardListPage

HTTPcURLJavaScriptPython

200

Masterpass REST reward list page context retrieved

Query available rewards for the Masterpass REST card

post

Submits the Masterpass card alias to the gateway and retrieves the list of available rewards. The returned reward list is stored in pre_order.rewards and used by the subsequent MasterpassRestRewardSelectionPage.

This is an independent page — submitting it does not advance the main checkout flow.

Required Fields:

• card_alias: Alias of the Masterpass card the user wants to query rewards for. The alias is the value the Masterpass JS SDK uses to identify a stored card.

Processing:

1. pre_order.rewards and pre_order.selected_rewards are reset to null.

2. The Masterpass POS gateway is resolved through pre_order.get_pos_using_slug(). If no POS is found, the page is a no-op and rewards remains null.

3. When enable_rewards is true and the gateway reports has_rewards(), gateway.query_rewards(...) is called with the current pre-order currency, the user, and the validated input data.

4. The returned reward list is stored in pre_order.rewards.

Next Pages:

• MasterpassRestRewardSelectionPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

card_aliasstringRequired

Alias of the Masterpass stored card to query rewards for. The alias is the value the Masterpass JS SDK uses to identify a card. The value is forwarded to gateway.query_rewards(...).

Example: MP-CARD-ALIAS-001

Responses

200

Rewards retrieved or empty list returned

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=MasterpassRestRewardListPage

HTTPcURLJavaScriptPython

200

Rewards retrieved or empty list returned

Get Masterpass REST Reward Selection Page context

get

Returns the list of rewards fetched in the preceding MasterpassRestRewardListPage step. The user picks how much of each reward type to apply to the order. Behaviour and request format are identical to RewardSelectionPage — only the entry pre-conditions differ (Masterpass REST must be the active payment option).

This is an independent page — submitting it does not advance the main checkout flow.

Preconditions:

• Basket must not be empty

• Payment option must be Masterpass REST (check_masterpass_selected)

• Reward data must have been fetched (check_reward_available, i.e., pre_order.rewards is not None)

Page Context:

• rewards: The reward list obtained in MasterpassRestRewardListPage, where each entry contains an amount and a type (RewardType enum value).

Skip Conditions:

• This page is considered already completed when pre_order.selected_rewards is not None.

Next Pages:

• No further checkout page (EmptyPage — independent terminal step)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Masterpass REST reward selection page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=MasterpassRestRewardSelectionPage

HTTPcURLJavaScriptPython

200

Masterpass REST reward selection page context retrieved

Apply selected reward amounts to the Masterpass REST order

post

Accepts the user's reward amount selections and stores them in pre_order.selected_rewards. The request body is dynamic — each field name corresponds to a RewardType value present in the rewards list returned by MasterpassRestRewardListPage. Each value is a decimal amount the user chooses to apply, between 0 and the maximum available for that type.

This is an independent page — submitting it does not advance the main checkout flow.

Dynamic Fields:

• One field per reward type (e.g., general, special).

• Field type: decimal with up to 12 digits and 2 decimal places.

• Minimum value: 0

• Maximum value: the amount value for that reward type from the pre-order state.

Validation:

• The sum of all selected reward amounts must not exceed the order total (pre_order.get_total_amount_with_interest()). If it does, a validation error is returned: "Selected reward amount cannot be higher than total amount.".

State Update:

• On success, pre_order.selected_rewards is populated with the chosen amounts keyed by RewardType enum values.

Backward Navigation:

• When navigating backward, pre_order.selected_rewards is reset to null.

Next Pages:

• No further checkout page (EmptyPage)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

Dynamic input schema — the fields are determined at runtime based on the reward types returned by the payment gateway in the preceding RewardListPage step. Each field name is a RewardType enum value (general or special) and each value is a decimal amount between 0 and the maximum available for that type. The sum of all submitted amounts must not exceed the order total.

Other propertiesstring · decimalOptional

Amount of this reward type to apply. Between 0 and the maximum available for this type (12 digits, 2 decimal places).

Example: 25.00

Responses

200

Rewards applied or validation error

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=MasterpassRestRewardSelectionPage

HTTPcURLJavaScriptPython

200

Rewards applied or validation error

Get Campaign List Page context

get

Returns the context for the Campaign List Page, which queries the payment gateway for available campaigns associated with the selected credit card. This page is only reachable when a credit card payment option is selected, card details are present in the pre-order, and the active payment gateway supports campaign querying.

Preconditions:

• Basket must not be empty

• A credit card payment option must be selected

• Card information must be present in the current pre-order

• The active payment gateway must support campaign listing

Skip Conditions:

• Page is skipped if campaign data has already been fetched (i.e., campaigns is not null in the current pre-order state)

available_for_post_order: true

Next Pages (determined dynamically):

• CampaignSelectionPage — always, after campaign data is fetched

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Campaign List Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=CampaignListPage

HTTPcURLJavaScriptPython

200

Campaign List Page context retrieved

Query available campaigns for the selected credit card

post

Submits the full card number to the payment gateway and retrieves the list of available campaigns. The returned campaign list is stored in the pre-order state and used by the subsequent CampaignSelectionPage to allow the user to choose a campaign.

Required Fields:

• card_number: The full credit card number. Spaces are stripped before validation. Must pass card number format validation.

Validation:

• card_number must be a valid card number; all spaces are removed before the check is applied

• If the card number is invalid, an error is returned and the user remains on CampaignListPage

State Update:

• On success, campaigns in the pre-order is populated with the list of campaign objects returned by the payment gateway. If the gateway returns no campaigns, campaigns is set to [] (empty array).

Backward Navigation:

• When navigating backward from this page, campaigns is reset to null, requiring the user to re-submit the card number.

Next Pages:

• CampaignSelectionPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

card_numberstringRequired

The full credit card number. Leading, trailing, and internal spaces are stripped before validation is applied. Must be a valid card number.

Example: 5400010000000004

Responses

200

Campaign list retrieved successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=CampaignListPage

HTTPcURLJavaScriptPython

200

Campaign list retrieved successfully

Get Campaign Selection Page context

get

Returns the context for the Campaign Selection Page, which presents the list of campaigns fetched from the payment gateway in the preceding CampaignListPage step. The user selects one campaign from this list to apply to the order.

Preconditions:

• Campaign data must have been fetched (i.e., campaigns must not be null in the current pre-order state; an empty list [] is accepted)

Skip Conditions:

• Page is skipped if a campaign has already been selected (i.e., selected_campaign is not null in the current pre-order state)

available_for_post_order: true

Next Pages (determined dynamically):

• Proceeds to the next applicable checkout step once a campaign is selected

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Campaign Selection Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=CampaignSelectionPage

HTTPcURLJavaScriptPython

200

Campaign Selection Page context retrieved

Select a campaign to apply to the order

post

Submits the user's chosen campaign code. The submitted code is validated against the list of campaigns previously fetched from the payment gateway. On success, the selected campaign is stored in the pre-order state.

Required Fields:

• campaign: The code of the campaign to apply. Must be one of the codes present in the campaigns list of the current pre-order state.

Validation:

• campaign must match a code from the available campaigns list. If the submitted code is not found in the list, a validation error is returned and the user remains on CampaignSelectionPage.

State Update:

• On success, selected_campaign in the pre-order is set to the submitted campaign code.

Backward Navigation:

• When navigating backward from this page, selected_campaign is reset to null, requiring the user to re-select a campaign.

Next Pages:

• The checkout flow advances to the next applicable step as determined by the overall checkout state.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

campaignstringRequired

The code of the campaign to apply to the order. Must match one of the campaign codes present in the campaigns list of the current pre-order state. Submitting a code not present in that list causes a validation error.

Example: CAMP001

Responses

200

Campaign selected successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=CampaignSelectionPage

HTTPcURLJavaScriptPython

200

Campaign selected successfully

Get Loyalty Money Page context

get

Returns the context for the Loyalty Money Page, which presents a terms and conditions agreement to the user before finalizing a loyalty money payment. This page is reached when the loyalty money payment option has been selected and the loyalty balance fully covers the order total (no unpaid amount remains).

Preconditions:

• The selected payment option must be of loyalty money type

• The LOYALTY_MONEY_ENABLED dynamic setting must be true

• The loyalty money balance must cover the full order amount (unpaid amount must be zero)

Skip Conditions:

• Page is skipped if the loyalty money payment option is selected and the order has already been finalized

Configuration:

• LOYALTY_MONEY_ENABLED: Controls whether the loyalty money payment method is available during checkout. Defaults to false.

available_for_post_order: true

Next Pages (determined dynamically):

• ThankYouPage — after the order is placed

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Loyalty Money Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=LoyaltyMoneyPage

HTTPcURLJavaScriptPython

200

Loyalty Money Page context retrieved

Confirm loyalty money payment and place the order

post

Submits the user's agreement to terms and conditions, confirming the loyalty money payment. On success, the order is placed using the available loyalty money balance, which must fully cover the order total.

Required Fields:

• agreement: Must be true. The user must explicitly accept the terms and conditions to proceed.

Validation:

• agreement must be true; any other value returns a validation error

• The basket total must be greater than zero

State Update:

• On success, the order is finalized using the loyalty money balance. The card and installment information in the pre-order are cleared as they are not applicable to loyalty money payments.

Backward Navigation:

• Navigating backward from this page does not alter the pre-order state.

Next Pages:

• The order is placed upon successful submission; the checkout flow advances to the order confirmation step.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

agreementboolean · enumRequired

User must accept the terms and conditions to proceed with the loyalty money payment. Must be true.

Possible values:

Responses

200

Loyalty money payment confirmed and order placed

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=LoyaltyMoneyPage

HTTPcURLJavaScriptPython

200

Loyalty money payment confirmed and order placed

Get Loyalty Money Usage Page context

get

Returns the user's available loyalty money balance and a breakdown of account groups by label, enabling the user to specify how much loyalty money to apply toward the current order. This page runs as an independent step, meaning it does not reset or block other checkout steps and can be submitted at any point once the precondition is satisfied.

Preconditions:

• The LOYALTY_MONEY_ENABLED dynamic setting must be true

Skip Conditions:

• None

Configuration:

• LOYALTY_MONEY_ENABLED: Controls whether the loyalty money feature is active during checkout. Defaults to false. When false, this page is excluded from the checkout flow entirely.

Next Pages:

• This is an independent step and does not determine the next checkout page. The checkout flow proceeds based on the current checkout state.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Loyalty Money Usage Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=LoyaltyMoneyUsagePage

HTTPcURLJavaScriptPython

200

Loyalty Money Usage Page context retrieved

Set loyalty money amount to apply to the order

post

Specifies the amount of loyalty money the user wishes to apply to the current order. The submitted amount is stored in the checkout session and used when the payment is finalized.

Two input modes are supported:

1. Legacy mode — submit loyalty_amount_to_use as a flat decimal amount. The system automatically distributes the debit across the user's accounts in label-priority order.

2. Label-based mode — submit account_usages as a JSON-encoded array specifying the exact amount to debit from each account label.

When both fields are provided, loyalty_amount_to_use takes precedence and account_usages is discarded.

Required Fields:

• At least one of loyalty_amount_to_use or account_usages must be present. Submitting null for loyalty_amount_to_use sets the applied amount to zero.

Validation:

• Each entry in account_usages must reference a label the user owns.

• The requested amount per label must not exceed the available balance for that label.

• account_usages must be a valid JSON array; a malformed value returns a validation error.

State Update:

• The selected payment option, card details, and installment selection are cleared from the checkout session, as loyalty money usage is evaluated independently of credit card payment flows.

• loyalty_amount_to_use and loyalty_account_usages are updated with the submitted values.

Backward Navigation:

• Navigating backward from this page does not alter the checkout state.

Next Pages:

• This is an independent step; the checkout flow continues to the page determined by the current checkout state.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

loyalty_amount_to_usenumber · nullableOptional

The flat loyalty money amount to apply to the order, as a decimal value with up to 12 digits and 2 decimal places (e.g., "50.00"). When provided alongside account_usages, this field takes precedence and account_usages is ignored. Submit 0 or null to remove any previously applied loyalty money amount.

Example: 50.00

account_usagesstring · nullableOptional

A JSON-encoded array specifying the loyalty money amount to debit from each account label. Each array item must contain:

• label_id: integer primary key of the account label, or null for unlabeled accounts
• amount: decimal string representing the amount to debit from that label group

The requested amount per label must not exceed the user's available balance for that label. Unlabeled accounts are referenced with "label_id": null. Malformed JSON returns a validation error.

Ignored when loyalty_amount_to_use is also provided.

Example: [{"label_id": 1, "amount": "25.00"}, {"label_id": null, "amount": "10.00"}]

Responses

200

Loyalty money usage amount set successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=LoyaltyMoneyUsagePage

HTTPcURLJavaScriptPython

Apply a flat loyalty money amount (legacy mode)Apply loyalty money per account labelRemove previously applied loyalty money

200

Loyalty money usage amount set successfully

Get Loyalty Card Page context

get

Returns the user's loyalty card balance and redeemable points information, enabling the user to select how many loyalty card points to apply toward the current order. This page runs as an independent step and is also available after order placement (available_for_post_order: true).

The redeemable amount displayed to the user is automatically capped so that the remaining order total does not fall below the MINIMUM_ORDER_AMOUNT threshold. The total available points on the card (loyalty_total_amount) and the effective redeemable amount after cap (loyalty_amount) may therefore differ.

If the user has no active loyalty card, all amount fields return 0 or null and card_number is null.

Preconditions:

• User must be authenticated and have an active loyalty card associated with their account

Skip Conditions:

• None

Configuration:

• CUSTOMER_LOYALTY_CARD_SERVICE: Object — configures the custom service implementation that retrieves available loyalty card points and the optional minimum_basket_amount_for_redeem threshold.

• MINIMUM_ORDER_AMOUNT: Decimal — the minimum order amount that must remain after loyalty card redemption. The redeemable points are capped at basket_total - MINIMUM_ORDER_AMOUNT.

Next Pages:

• This is an independent step and does not determine the next checkout page.

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Loyalty Card Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=LoyaltyCardPage

HTTPcURLJavaScriptPython

200

Loyalty Card Page context retrieved

Apply loyalty card points to the order

post

Submits the number of loyalty card points the user wishes to redeem for the current order. The selected amount is validated against the user's available balance and the basket constraints, then stored in the checkout session.

Required Fields:

• selected_loyalty_amount: The points amount to apply. Must be a positive decimal value up to 12 digits with 2 decimal places.

Validation:

• The selected amount must not exceed the user's available loyalty card points balance.

• The selected amount is capped at basket_total - MINIMUM_ORDER_AMOUNT plus any previously applied amount. Submitting a value above this cap returns a validation error.

• If minimum_basket_amount_for_redeem is configured via CUSTOMER_LOYALTY_CARD_SERVICE, the basket total must meet or exceed this threshold before any redemption is allowed.

State Update:

• The selected points amount and its type are stored in the checkout session.

Backward Navigation:

• Navigating backward from this page clears the selected loyalty amount from the checkout session.

Next Pages:

• This is an independent step; the checkout flow continues based on the current checkout state.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

selected_loyalty_amountnumber · decimalRequired

The loyalty card points amount to apply to the order, as a decimal value with up to 12 digits and 2 decimal places (e.g., "5.00"). Must not exceed the user's available points balance. The effective maximum is basket_total - MINIMUM_ORDER_AMOUNT plus any previously applied amount. Submitting a value above this cap or above the available balance returns a validation error.

Example: 5.00

Responses

200

Loyalty card points applied successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=LoyaltyCardPage

HTTPcURLJavaScriptPython

Apply a loyalty card points amountApply the full redeemable points amount

200

Loyalty card points applied successfully

Get Gift Box Page context

get

Presents the gift box selection form. The user may add an optional personal note, request a gift video, and confirm whether a gift video notification has been sent.

The page_context exposes the price of the gift box product so the storefront can display it to the user before confirmation.

Preconditions:

• GIFT_BOX_CONFIGURATIONS.is_active must be true

• pre_order.user_email must be set

Skip Conditions:

• Page is auto-processed when a gift box selection already exists on the pre-order (i.e., pre_order.gift_box is not null)

Configuration:

• GIFT_BOX_CONFIGURATIONS: Must have is_active: true. The sku field identifies the gift box product used to resolve the displayed price. When sku is null, the price is 0.00.

Next Pages (determined dynamically):

• Proceeds to the next applicable checkout step once gift box selection is complete

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Gift box page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=GiftBoxPage

HTTPcURLJavaScriptPython

200

Gift box page context retrieved

Submit Gift Box Page

post

Saves the gift box selection to the pre-order with the provided note and video preferences, then proceeds to the next checkout step.

All fields are optional. Submitting without any fields creates a gift box with no note and no video.

Required Fields:

• None — all fields are optional

Validation:

• note: maximum 160 characters; null and empty string are accepted

State Update:

• pre_order.gift_box is populated with the submitted note, gift_video, and gift_video_notification_sent values. The gift box product is resolved from GIFT_BOX_CONFIGURATIONS.sku.

Backward Navigation:

• Navigating back to GiftBoxIndexPage clears pre_order.gift_box, resetting the selection

Next Pages:

• Proceeds to the next applicable checkout step

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

notestring · max: 160 · nullableOptional

An optional personal message to include with the gift box. Maximum 160 characters. Accepts null and empty string.

Example: Happy Birthday! Wishing you all the best.

gift_videobooleanOptional

When true, a gift video is requested for this order.

Example: true

gift_video_notification_sentbooleanOptional

Indicates whether the gift video notification has already been sent. Passed through from the client after the notification is dispatched.

Example: false

Responses

200

Gift box saved, proceeding to next checkout step

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=GiftBoxPage

HTTPcURLJavaScriptPython

Gift box with personal noteGift box without note or video

200

Gift box saved, proceeding to next checkout step

Get Gift Box Index Page context

get

Entry point for the gift box selection flow. Clears any previously selected gift box from the pre-order and routes immediately to GiftBoxPage.

This page is automatically processed (skipped) whenever its preconditions are met — it is never rendered directly. Upon access, the gift box selection is cleared and the response context reflects GiftBoxPage.

Preconditions:

• GIFT_BOX_CONFIGURATIONS.is_active must be true

• pre_order.user_email must be set

Skip Conditions:

• Always auto-processed when preconditions are met (is_already_done returns true whenever GIFT_BOX_CONFIGURATIONS.is_active is true)

Configuration:

• GIFT_BOX_CONFIGURATIONS: Controls whether the gift box flow is enabled. When is_active is false, this page and GiftBoxPage are both inaccessible.

Next Pages (determined dynamically):

• GiftBoxPage — always, when preconditions are met

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Gift box index page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=GiftBoxIndexPage

HTTPcURLJavaScriptPython

200

Gift box index page context retrieved

Submit Gift Box Index Page

post

Clears the current gift box selection from the pre-order and proceeds to GiftBoxPage. This endpoint accepts no input fields.

Typically called during backward navigation to allow the user to re-select a gift box option.

State Update:

• pre_order.gift_box is set to null, removing any previously selected gift box

Backward Navigation:

• Submitting this page resets the gift box selection, allowing a fresh choice on GiftBoxPage

Next Pages:

• GiftBoxPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Gift box cleared, routed to GiftBoxPage

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=GiftBoxIndexPage

HTTPcURLJavaScriptPython

200

Gift box cleared, routed to GiftBoxPage

Get Cash Register Page context

get

Returns the context for the cash register payment confirmation step. This page is displayed when the selected payment option is of type cash_register.

Preconditions:

• A payment option of type cash_register must be selected (check_cr_selected)

• Basket must not be empty

Purpose: Cash register payment is an in-store payment method where the customer agrees to pay at a physical cash register terminal. The store staff initiates the transaction on behalf of the customer.

Page Context: This page returns an empty page context. The primary action is the submission of the agreement along with store staff identification headers.

Page Completion State:

• This page is considered complete when the payment option is cash_register and a pre-order number has been generated.

• If already complete, the system automatically advances to the next step.

Navigation:

• Previous page: PaymentOptionSelectionPage

• Next page: CashRegisterInstallmentSelectionPage (if installment is active) or CashRegisterCompletePage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Cash register page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

302

Redirect to basket (empty basket) or login (guest purchase not allowed)

get

/orders/checkout/?page=CashRegisterPage

HTTPcURLJavaScriptPython

Submit Cash Register Payment Agreement

post

Submits the cash register payment agreement and records store staff identification. Generates a pre-order number that will be used to track the cash register transaction.

Required Fields:

• agreement: User must accept terms and conditions (must be true)

Required Headers: In addition to the standard AJAX header, the following store identification headers are required for all cash register submissions:

• X-STORE-STAFF-ID: Local store staff identifier

• X-STORE-STAFF-EMAIL: Store staff email address

• X-STORE-ID: Local store identifier

• X-STORE-STAFF-REMOTE-ID: Remote store staff identifier

• X-STORE-REMOTE-ID: Remote store identifier

All five headers must be present. If any header is missing, a 400 validation error is returned indicating which header is required.

Processing:

• Generates a unique pre-order number for the transaction

• Records store staff information (staff_id, staff_email, store_id, local_staff_id, local_store_id) in the pre-order data

• Associates the transaction with the initiating store staff member

• Default fallback values for staff_id, staff_email, and store_id may be configured via the CASH_REGISTER_DEFAULTS Django setting. Header values always take precedence and override any defaults.

Basket Amount Validation:

• Basket amount must be greater than zero before submitting

Navigation After Success:

• If payment option has is_installment_active: true in its configuration: routes to CashRegisterInstallmentSelectionPage

• Otherwise: routes to CashRegisterCompletePage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

X-STORE-STAFF-IDstringRequired

Local store staff identifier assigned by the store management system

X-STORE-STAFF-EMAILstring · emailRequired

Email address of the store staff member initiating the transaction

X-STORE-IDstringRequired

Local store identifier assigned by the store management system

X-STORE-STAFF-REMOTE-IDstringRequired

Remote system identifier for the store staff member

X-STORE-REMOTE-IDstringRequired

Remote system identifier for the store

Body

application/x-www-form-urlencoded

agreementboolean · enumRequired

User must accept terms and conditions to proceed. Must be true. Basket amount must be greater than zero.

Possible values:

Responses

200

Cash register payment agreement submitted successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

302

Redirect to basket (empty basket)

post

/orders/checkout/?page=CashRegisterPage

HTTPcURLJavaScriptPython

Get Cash Register Installment Selection Page context

get

Returns the available installment options for the cash register payment. This page is only reachable when the selected payment option has is_installment_active: true in its configuration.

Preconditions:

• A payment option of type cash_register must be selected (check_cr_selected)

• A pre-order number must have been generated (check_has_pre_order_number)

• Basket must not be empty

Page Context: Returns a list of cards with their available installment plans. Installments are filtered based on the current basket total amount, ensuring only applicable plans are presented to the customer.

Page Completion State:

• This page is considered complete when an installment is selected or no_installment has been explicitly confirmed.

Navigation:

• Previous page: CashRegisterPage

• Next page: CashRegisterCompletePage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Cash register installment selection page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

302

Redirect to basket (empty basket)

get

/orders/checkout/?page=CashRegisterInstallmentSelectionPage

HTTPcURLJavaScriptPython

Submit Cash Register Installment Selection

post

Submits the installment selection for the cash register payment. Exactly one of installment or no_installment must be provided.

Required Fields (mutually exclusive — exactly one must be submitted):

• installment: Primary key of the selected installment option

• no_installment: Explicit confirmation to proceed without installment (true)

Validation Rules:

• Providing both installment and no_installment is invalid

• Providing neither installment nor no_installment is invalid

• The installment pk must reference an active installment record

Navigation After Success:

• Routes to CashRegisterCompletePage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

installmentintegerOptional

Primary key of the selected installment option. Must reference an active installment record. Mutually exclusive with no_installment — exactly one must be provided.

no_installmentboolean · enumOptional

Explicit confirmation to proceed without installment. Must be true when provided. Mutually exclusive with installment — exactly one must be provided.

Possible values:

Responses

200

Installment selection submitted successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

302

Redirect to basket (empty basket)

post

/orders/checkout/?page=CashRegisterInstallmentSelectionPage

HTTPcURLJavaScriptPython

Select an installment planProceed without installment

Get Cash Register Complete Page context

get

Returns the barcode and order number for the cash register transaction. This page is displayed after the pre-order number has been generated and, if applicable, after the installment selection has been completed.

Preconditions:

• A payment option of type cash_register must be selected (check_cr_selected)

• A pre-order number must have been generated (check_has_pre_order_number)

• If is_installment_active is true: installment or no-installment must be confirmed (check_installment_selected)

• Basket must not be empty

Page Context:

• barcode: Base64-encoded PNG image of the Code128 barcode

• number: The pre-order number to be scanned at the cash register

• seconds: Countdown duration in seconds before the session expires (1800 = 30 minutes)

Barcode Format: The barcode is generated in Code128 format and encoded as a Base64 PNG string. Clients should render it as <img src="data:image/png;base64,{barcode}" />.

Page Completion State:

• This page is considered complete when the cash register transaction has been finalized and the order has been created.

Navigation:

• Previous page: CashRegisterInstallmentSelectionPage (if installment active) or PaymentOptionSelectionPage

• Next page: ThankYouPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Cash register complete page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

302

Redirect to basket (empty basket)

get

/orders/checkout/?page=CashRegisterCompletePage

HTTPcURLJavaScriptPython

Complete Cash Register Payment

post

Finalizes the cash register payment by confirming the completed transaction. This endpoint has no required request body fields. It validates internally that a successful cash register transaction record exists for the current pre-order before creating the order.

No Request Body Required: This submission does not require any body fields. The system validates the transaction state automatically.

Transaction Validation: The system verifies that a CashRegisterTransaction record exists for the current pre-order with is_succeeded: true. This record is created by the cash register terminal when the customer completes payment at the physical register. If no such record exists yet, the response returns a validation error asking the client to wait.

Installment Handling:

• If is_installment_active is false: the installment and no_installment fields are cleared from the pre-order before order creation.

• Card info is always cleared after this step.

Navigation After Success:

• Routes to ThankYouPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

objectOptional

No request body fields are required for this submission. The system validates internally that a successful cash register transaction exists for the current pre-order.

Responses

200

Cash register payment completed and order created successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

302

Redirect to basket (empty basket)

post

/orders/checkout/?page=CashRegisterCompletePage

HTTPcURLJavaScriptPython

Get Send Barcode SMS Page context

get

Returns the context for the barcode SMS sending step. This is an independent page — submitting it does not advance the checkout flow state.

Preconditions:

• SMS must not have been sent within the cooldown period (check_is_sent_sms_before)

• Request must originate from an in-store client (check_client_type_is_instore)

• A payment option of type cash_register must be selected (check_payment_option_is_cash_register)

• A pre-order number must have been generated (check_has_pre_order_number)

SMS Cooldown: Once an SMS is sent, the same SMS cannot be resent until the cooldown period has elapsed. The cooldown duration is configured via the ORDER_BARCODE_SENT_SMS_EXPIRATION_IN_SECONDS setting (default: 1800 seconds).

Page Context: Returns an empty page context. The only required input is the recipient phone number.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Send barcode SMS page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=SendBarcodeSmsPage

HTTPcURLJavaScriptPython

200

Send barcode SMS page context retrieved

Send Barcode SMS to Customer

post

Sends the order barcode URL to the specified phone number via SMS. This is an independent page — it does not advance the checkout flow.

Required Fields:

• phone_number: The recipient's phone number, validated against the configured phone number format.

SMS Content: The SMS contains a signed URL pointing to the order barcode page. The URL allows the customer to display the barcode on their own device.

Cooldown Enforcement: After a successful send, the SMS cannot be resent until the cooldown period configured by ORDER_BARCODE_SENT_SMS_EXPIRATION_IN_SECONDS has elapsed. Submitting before the cooldown expires will result in a precondition failure.

Client Type Restriction: Only in-store clients (ClientType.instore) are permitted to submit this page.

Navigation After Success: Returns to an empty (no further action) state. The checkout flow position is not changed.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

phone_numberstringRequired

Recipient phone number for the barcode SMS. Validated against the configured phone number format.

Example: [phone]

Responses

200

Barcode SMS sent successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=SendBarcodeSmsPage

HTTPcURLJavaScriptPython

200

Barcode SMS sent successfully

Get Send Checkout URL SMS Page context

get

Returns the context for sending the checkout URL via SMS. This page is used when the customer does not have a QR code reader and cannot scan the barcode directly. An SMS with the checkout URL is sent instead. This is an independent page — submitting it does not advance the checkout flow.

Preconditions:

• SMS must not have been sent within the cooldown period (check_is_sent_sms_before)

• Request must originate from an in-store client (check_client_type_is_instore)

Difference from SendBarcodeSmsPage:

• SendBarcodeSmsPage sends a direct link to the barcode image

• SendCheckoutUrlSmsPage sends the checkout URL with an authentication token, allowing the customer to continue the checkout on their own device

Page Context: Returns an empty page context.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Send checkout URL SMS page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=SendCheckoutUrlSmsPage

HTTPcURLJavaScriptPython

200

Send checkout URL SMS page context retrieved

Send Checkout URL SMS to Customer

post

Sends the checkout continuation URL to the specified phone number via SMS. This allows customers without a QR reader to open the checkout flow on their own device by tapping the link in the SMS. This is an independent page — it does not advance the checkout flow.

Required Fields:

• phone_number: The recipient's phone number, validated against the configured phone number format.

SMS Content: The SMS contains a tokenized checkout URL. The token allows the customer to authenticate and resume the checkout session from their own device.

Cooldown Enforcement: Shares the same SMS cooldown mechanism as SendBarcodeSmsPage. The ORDER_BARCODE_SENT_SMS_EXPIRATION_IN_SECONDS setting controls the minimum interval between sends.

Client Type Restriction: Only in-store clients (ClientType.instore) are permitted to submit this page.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

phone_numberstringRequired

Recipient phone number for the checkout URL SMS. Validated against the configured phone number format.

Example: [phone]

Responses

200

Checkout URL SMS sent successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=SendCheckoutUrlSmsPage

HTTPcURLJavaScriptPython

200

Checkout URL SMS sent successfully

Get Remote Shipping Option Selection Page context

get

Returns available shipping options fetched from an external remote service. This page is used as an alternative to ShippingOptionSelectionPage when shipping option data must be sourced from a third-party API rather than the local database.

This page is used when CHECKOUT_SHIPPING_OPTION_SELECTION_PAGE dynamic setting is set to RemoteShippingOptionSelectionPage.

Preconditions:

• Shipping address must be selected (check_address_selected)

• Basket must not be empty

Remote Shipping Options:

• Shipping options are fetched via RemoteShippingOptionService using the REMOTE_SHIPPING_OPTION_PROVIDER setting

• The remote service is called with the current pre-order context (basket, address, etc.)

• Options returned from the remote service are matched against local ShippingOption records

Configuration:

• CHECKOUT_SHIPPING_OPTION_SELECTION_PAGE: Must be set to RemoteShippingOptionSelectionPage

• REMOTE_SHIPPING_OPTION_PROVIDER: The remote shipping option provider configuration

Auto-selection:

• If AUTOSELECT_SHIPPING setting is True and only one shipping option is available, it is automatically selected and the page is skipped

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Remote shipping option selection page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=RemoteShippingOptionSelectionPage

HTTPcURLJavaScriptPython

200

Remote shipping option selection page context retrieved

Select Remote Shipping Option

post

Sets the selected shipping option from the remote shipping option list.

Validation:

• The selected shipping option must be in the list returned by the remote service

• The remote service is queried again at submission time to ensure the option is still valid

Next Pages:

• If sample product discounts are available: SampleProductPage

• If retail store reservation is needed: ReservationSelectionPage

• Otherwise: PaymentOptionSelectionPage

Cascading Invalidation:

• Changing shipping option resets any previously selected payment option

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

shipping_optionintegerRequired

Primary key of the selected shipping option. Must be one of the options returned by the remote shipping service for the current checkout context.

Example: 1

Responses

200

Remote shipping option selected successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=RemoteShippingOptionSelectionPage

HTTPcURLJavaScriptPython

200

Remote shipping option selected successfully

Get Send SMS Page context (Pay on Delivery phone verification)

get

Returns the context for the phone number collection step in the pay-on-delivery flow. This page is part of the pay-on-delivery verification sequence and appears between PayOnDeliveryPaymentChoicePage and VerifySmsPage, before the user reaches PayOnDeliveryPage. The user is asked to enter their phone number to receive a one-time verification code.

Preconditions:

• Pay-on-delivery payment option must be selected (check_pay_on_delivery_selected)

• If the payment option has any payment_choices, one must already be selected

Skip Conditions:

• Page is skipped when sms_verification is false in the payment option's configuration. In that case the flow proceeds directly to PayOnDeliveryPage.

Page Context:

• verification: Whether SMS verification is enabled for this payment option. This will always be true when this page is reached (skipped otherwise).

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Send SMS page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=SendSmsPage

HTTPcURLJavaScriptPython

200

Send SMS page context retrieved

Send Pay on Delivery Verification SMS

post

Sends a one-time verification code (OTP) to the given phone number via SMS.

Required Fields:

• phone_number: Recipient's phone number, validated against the configured phone number format (User.phone_regex).

SMS Content:

• A 6-digit random verification code is generated and sent to the phone number.

• If a message format is configured in the payment option's sms_config, the code is embedded in the formatted message. Otherwise the code is sent as-is.

State Changes:

• pre_order.phone_number is set to the submitted phone number

• pre_order.verification_code is set to the generated 6-digit code

• pre_order.verification_sent_datetime is set to the current timestamp

Next Page: VerifySmsPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

phone_numberstringRequired

Recipient phone number for the Pay on Delivery verification SMS. Validated against the configured phone number format.

Example: [phone]

Responses

200

Verification SMS sent successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=SendSmsPage

HTTPcURLJavaScriptPython

200

Verification SMS sent successfully

Get Verify SMS Page context

get

Returns the context for the SMS verification step. The user enters the 6-digit code that was sent to their phone number on the SendSmsPage.

Preconditions:

• An SMS must have been sent — pre_order.phone_number and pre_order.verification_code must both be set (check_sms_sent)

Skip Conditions:

• Page is skipped when sms_verification is false in the payment option's configuration.

Page Context:

• verification_sent_datetime: ISO 8601 timestamp of when the SMS was sent

• seconds_left: Remaining seconds before the code expires (based on verify_timeout, default 180 seconds)

• retry: Whether a verification code has been issued (always true when page is reached)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Verify SMS page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=VerifySmsPage

HTTPcURLJavaScriptPython

200

Verify SMS page context retrieved

Submit SMS Verification Code

post

Verifies the code entered by the user against the code that was sent via SMS.

Required Fields:

• verify_code: The 6-digit numeric code the user received via SMS. Must consist of exactly 6 digits.

Validation:

• The entered code must match pre_order.verification_code

• The code must be submitted before the timeout expires. Timeout is configured via verify_timeout in the payment option's config (default: 180 seconds).

• If the timeout has elapsed, a validation error is returned and the user must go back to SendSmsPage to request a new code.

State Changes:

• pre_order.entered_code is set to the submitted code

Next Page: PayOnDeliveryPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

verify_codestringRequired

The 6-digit numeric verification code sent via SMS for Pay on Delivery verification. Must consist of exactly 6 digits. The code is validated against the stored pre_order.verification_code and must be submitted before the verify_timeout (default: 180 seconds) elapses.

Example: 483921Pattern: ^\d{6}$

Responses

200

SMS verification result

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=VerifySmsPage

HTTPcURLJavaScriptPython

200

SMS verification result

Get Coupon Selection Page context

get

Returns the available coupons for the current user. This page runs as an independent step, meaning it does not reset or block other checkout steps and can be submitted at any point once the precondition is satisfied.

Coupon Types:

• Coupon (offer_type = coupon): Standard single-use coupon assigned to the user

• Bulk Coupon (offer_type = bulk_coupon): A coupon from a bulk voucher batch, assigned to the user's BulkVoucherCode with an ACTIVE status

Applied Coupons:

• Offer applications are evaluated live via OfferApplicator on each GET request

• Coupons currently applied to the basket have is_applied: true

Preconditions:

• No strict preconditions — available to both authenticated and anonymous users

• Anonymous users see an empty coupon list (coupons are user-specific)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Coupon selection page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=CouponSelectionPage

HTTPcURLJavaScriptPython

200

Coupon selection page context retrieved

Add or Remove a Coupon

post

Adds or removes a coupon from the current checkout session. This is an independent step and does not determine the next checkout page. The checkout flow proceeds based on the current checkout state.

Required Fields:

• coupon: The primary key of the BasketOffer record as a string

• action: Either "add" to apply the coupon or "remove" to unapply it

State Changes:

• The coupon PK is added to or removed from pre_order.data["coupons"]

• Offer applications are recalculated on the next GET request

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

couponstringRequired

Primary key of the BasketOffer record to add or remove, as a string.

Example: 101

actionstring · enumRequired

Action to perform: "add" to apply the coupon or "remove" to unapply it.

Example: addPossible values:

Responses

200

Coupon action processed

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=CouponSelectionPage

HTTPcURLJavaScriptPython

Add a coupon to the checkoutRemove a coupon from the checkout

200

Coupon action processed

Get Voucher Code Page context

get

Returns the current voucher code set on the checkout session, if any. This page runs as an independent step, meaning it does not reset or block other checkout steps and can be submitted at any point once the precondition is satisfied.

Voucher vs Coupon:

• CouponSelectionPage manages user-specific BasketOffer coupons

• VoucherCodePage manages a free-text voucher code stored on pre_order.voucher_code

• The voucher code is applied to the basket at order creation time via OfferApplicator

Validation:

• The submitted voucher code is validated by running the offer applicator in a dry-run mode (without modifying the basket)

• If the code is not recognized or has already been used, a validation error is returned

Page Context:

• voucher_code: The voucher code currently set, or null if none

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Voucher code page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=VoucherCodePage

HTTPcURLJavaScriptPython

200

Voucher code page context retrieved

Apply or Clear Voucher Code

post

Sets or clears the voucher code on the checkout session. This is an independent step and does not determine the next checkout page. The checkout flow proceeds based on the current checkout state.

Required Fields:

• voucher_code: The voucher code string to apply (optional, max 128 characters). Whitespace is trimmed automatically. Submit an empty value or omit the field to clear the voucher code.

Validation:

• If a non-empty voucher code is provided, it is validated using OfferApplicator in a dry-run mode (on a copy of the pre-order and basket)

• The code is considered valid only if it results in an applied and non-failed voucher

• An invalid code returns a validation error in the errors field

State Changes:

• pre_order.voucher_code is set to the validated code

• Submitting an empty value clears pre_order.voucher_code (sets it to null)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

voucher_codestring · max: 128Optional

Voucher code to apply to the checkout session. Leading and trailing whitespace is trimmed automatically. Submit an empty string or omit this field to clear the currently set voucher code. Maximum 128 characters.

Example: WELCOME2024

Responses

200

Voucher code processed

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=VoucherCodePage

HTTPcURLJavaScriptPython

Apply a voucher codeClear the current voucher code

200

Voucher code processed

Get Reward List Page context

get

Returns the context for the Reward List Page, which collects the user's full credit card details and queries the payment gateway for available rewards. This page is only reachable when a credit card payment option is selected, card info is present in the pre-order, and the active gateway has rewards enabled. This is an independent page — submitting it does not advance the checkout flow.

Preconditions:

• Basket must not be empty

• A credit card payment option must be selected (check_credit_card_selected)

• Card information must be present in the pre-order (card_info is populated)

• The active payment gateway must have enable_rewards = true and has_rewards() returning true

Skip Conditions:

• Page is skipped if reward data has already been fetched (i.e., rewards is not null in pre-order)

Next Pages:

• RewardSelectionPage — always, after reward data is fetched

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Reward List Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=RewardListPage

HTTPcURLJavaScriptPython

200

Reward List Page context retrieved

Query available rewards for the selected credit card

post

Submits the full credit card details to the payment gateway and retrieves the list of available rewards. The returned reward list is stored in pre_order.rewards and used by the subsequent RewardSelectionPage. This is an independent page — submitting it does not advance the checkout flow.

Required Fields:

• card_number: Full credit card number. Spaces are stripped before validation.

• card_month: Card expiry month.

• card_year: Card expiry year (4 digits).

• card_cvv: Card security code.

Optional Fields:

• card_holder: Cardholder name.

• card_name: Alias or label for the card.

Validation:

• card_number must be a valid card number (spaces stripped before check)

• card_month must be a valid month value

• card_year must be a 4-digit valid year

• card_cvv must be a valid CVV format

• Card must not be expired

State Update:

• On success, rewards in the pre-order is populated with the list of reward objects returned by the gateway. If the gateway returns no rewards, rewards may be set to an empty list.

Backward Navigation:

• When navigating backward from this page, rewards is reset to null.

Next Pages:

• RewardSelectionPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

card_numberstringRequired

Full credit card number. Leading, trailing, and internal spaces are stripped before validation. Must pass card number format validation.

Example: 5400010000000004

card_monthstringRequired

Card expiry month. Must be a valid month value.

Example: 12

card_yearstring · min: 4 · max: 4Required

Card expiry year (4 digits). Must be a valid future year.

Example: 2027

card_cvvstringRequired

Card security code (CVV/CVC). Must pass CVV format validation.

Example: 123

card_holderstringOptional

Cardholder full name. Optional.

Example: John Doe

card_namestring · nullableOptional

Optional alias or label for the card.

Example: My Main Card

Responses

200

Rewards retrieved or validation error

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=RewardListPage

HTTPcURLJavaScriptPython

200

Rewards retrieved or validation error

Get Reward Selection Page context

get

Returns the list of available rewards fetched in the preceding RewardListPage step. The user selects how much of each reward type to apply to the order. This is an independent page — submitting it does not advance the checkout flow.

Preconditions:

• Basket must not be empty

• Reward data must have been fetched (i.e., rewards must not be null in pre-order)

Skip Conditions:

• Page is skipped if rewards have already been selected (i.e., selected_rewards is not null)

Next Pages:

• No further checkout page — this is a terminal reward step (EmptyPage)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Reward Selection Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=RewardSelectionPage

HTTPcURLJavaScriptPython

200

Reward Selection Page context retrieved

Apply selected reward amounts to the order

post

Accepts the user's reward amount selections and stores them in pre_order.selected_rewards. The request body is dynamic: each field name corresponds to a RewardType enum value present in the rewards list returned by RewardListPage. Each value is a decimal amount the user chooses to apply, between 0 and the maximum available for that type. This is an independent page — submitting it does not advance the checkout flow.

Dynamic Fields:

• One field per reward type (e.g., general, special).

• Field type: decimal with up to 12 digits and 2 decimal places.

• Minimum value: 0

• Maximum value: the amount value for that reward type from the pre-order state.

Validation:

• The sum of all selected reward amounts must not exceed the order total (pre_order.get_total_amount_with_interest()). If it does, a validation error is returned.

State Update:

• On success, selected_rewards is populated with the chosen amounts keyed by RewardType enum values.

Backward Navigation:

• When navigating backward, selected_rewards is reset to null.

Next Pages:

• No further checkout page (EmptyPage)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

Dynamic input schema — the fields are determined at runtime based on the reward types returned by the payment gateway in the preceding RewardListPage step. Each field name is a RewardType enum value (general or special) and each value is a decimal amount between 0 and the maximum available for that type. The sum of all submitted amounts must not exceed the order total.

Other propertiesstring · decimalOptional

Amount of this reward type to apply. Between 0 and the maximum available for this type (12 digits, 2 decimal places).

Example: 25.00

Responses

200

Rewards applied or validation error

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=RewardSelectionPage

HTTPcURLJavaScriptPython

200

Rewards applied or validation error

Get Sample Product Page context

get

Returns the list of sample products available for selection, based on the offer/discount applications on the current basket. This page is shown when active campaigns include sample product discounts.

Preconditions:

• Basket must not be empty

• A shipping option must already be selected (check_shipping_option_selected)

Skip Conditions:

• Page is skipped if sample products have already been selected or declined (i.e., sample_products or unwanted_sample_products is set in pre_order.data)

Previous Page: ShippingOptionSelectionPage (or configured variant)

Next Page: PaymentOptionSelectionPage

Note: This page appears only when at least one active offer discount includes sample_product_discounts. If no such discounts are applied to the basket, this page will not appear in the flow.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Sample Product Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=SampleProductPage

HTTPcURLJavaScriptPython

200

Sample Product Page context retrieved

Select or decline sample products

post

Accepts the user's sample product selection. The user can either select one or more products (up to allowed_quantity) or submit an empty list to explicitly decline all sample products.

Fields:

• sample_products: List of product PKs to add as samples. Must be from the available sample product IDs for the current basket discounts. Duplicates are deduplicated automatically. Can be an empty list to decline all samples.

Validation:

• The number of selected products must not exceed allowed_quantity. If it does, a validation error is returned.

• Each submitted PK must belong to the set of available sample products for the current offer discount applications.

State Update:

• If products are selected: pre_order.data['sample_products'] is set to the selected product list.

• If the list is empty (decline): pre_order.data['unwanted_sample_products'] is set to true and sample_products is removed.

Backward Navigation:

• When navigating backward, both sample_products and unwanted_sample_products are removed from pre_order.data.

Next Pages:

• PaymentOptionSelectionPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

sample_productsinteger[]Required

List of product PKs to add as sample products. Must be from the set of available sample products for the current basket's offer discount applications. Duplicates are deduplicated automatically. Submit an empty array to explicitly decline all sample products (sets unwanted_sample_products = true). The count must not exceed the allowed_quantity returned in the page context.

Example: [101]

Responses

200

Sample product selection applied or validation error

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=SampleProductPage

HTTPcURLJavaScriptPython

User selects one sample productUser declines all sample products

200

Sample product selection applied or validation error

Get Order Note Page context

get

Returns the current order note stored in the pre-order. This page allows the user to add or update a free-text note attached to their order. This is an independent page — submitting it does not advance the checkout flow.

Preconditions:

• Basket must not be empty

Skip Conditions:

• Page is skipped if a note has already been entered (i.e., notes is set in pre_order.data)

Next Pages:

• No further checkout page from this step (EmptyPage)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Order Note Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=OrderNotePage

HTTPcURLJavaScriptPython

200

Order Note Page context retrieved

Save or clear the order note

post

Accepts an optional note for the order and stores it in pre_order.data['notes']. Submitting a blank or null value removes any previously stored note. This is an independent page — submitting it does not advance the checkout flow.

Fields:

• notes: Free-text note for the order. Maximum 320 characters. null or empty string clears the note.

State Update:

• If notes is a non-empty string: stored in pre_order.data['notes'].

• If notes is null or empty: notes key is removed from pre_order.data.

Backward Navigation:

• When navigating backward, notes is removed from pre_order.data.

Next Pages:

• No further checkout page (EmptyPage)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

notesstring · max: 320 · nullableRequired

Free-text note to attach to the order. Maximum 320 characters. Submitting null or an empty string clears any previously stored note.

Example: Please leave at the door.

Responses

200

Note saved or cleared

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=OrderNotePage

HTTPcURLJavaScriptPython

Save a noteClear existing note

200

Note saved or cleared

Get Delivery Bags Page context

get

Returns the delivery bags fee calculated for the current basket. This page allows users to confirm (and optionally choose the quantity of) delivery bags to include with their order. This is an independent page — submitting it does not advance the checkout flow.

Preconditions:

• Basket must not be empty

• DELIVERY_BAGS_CONF.is_active must be true (is_delivery_bags_active check)

Skip Conditions:

• Page is always considered done when DELIVERY_BAGS_CONF.is_active is true (i.e., is_already_done() mirrors the is_valid() check)

Configuration: Requires DELIVERY_BAGS_CONF dynamic setting to be active. See the DELIVERY_BAGS_CONF section in Dynamic Settings above for full details.

Next Pages:

• No further checkout page from this step (EmptyPage)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Delivery Bags Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=DeliveryBagsPage

HTTPcURLJavaScriptPython

200

Delivery Bags Page context retrieved

Confirm delivery bag selection

post

Accepts the delivery bag product SKU and (optionally) a quantity. Calculates the final number of bags based on the DELIVERY_BAGS_CONF settings and stores the result in pre_order.data. This is an independent page — submitting it does not advance the checkout flow.

Fields:

• product: SKU of the bag product. Must match DELIVERY_BAGS_CONF.sku. Must be an active product with product_type = miscellaneous.

• quantity: Number of bags requested by the user. Only applicable when DELIVERY_BAGS_CONF.is_quantity_changeable is true. Must be >= DELIVERY_BAGS_CONF.min_quantity. Defaults to 0 if omitted (falls back to min_quantity).

Quantity Calculation:

• When is_quantity_changeable is false: quantity is auto-calculated as ceil(total_amount / per_amount), floored at min_quantity. Items with the exclude_bag_attribute_name attribute are excluded from the total amount.

• When is_quantity_changeable is true: the submitted quantity value is used directly.

State Update:

• pre_order.data['bags']: list of the bag product repeated bags_count times.

• pre_order.data['bags_fee']: calculated delivery bags fee.

Backward Navigation:

• When navigating backward, bags and bags_fee are removed from pre_order.data.

Next Pages:

• No further checkout page (EmptyPage)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

productstringRequired

SKU of the delivery bag product. Must match the SKU configured in DELIVERY_BAGS_CONF.sku. The product must be active and have product_type = miscellaneous.

Example: DELIVERY-BAG-001

quantityintegerOptional

Number of bags requested by the user. Only used when DELIVERY_BAGS_CONF.is_quantity_changeable is true. Must be greater than or equal to DELIVERY_BAGS_CONF.min_quantity. Defaults to 0 if omitted, which falls back to min_quantity. Raises a validation error if is_quantity_changeable is false and a non-zero value is submitted.

Example: 3

Responses

200

Delivery bag selection confirmed or validation error

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=DeliveryBagsPage

HTTPcURLJavaScriptPython

Submit bag product (quantity auto-calculated)Submit with user-specified quantity (is_quantity_changeable = true)

200

Delivery bag selection confirmed or validation error

Get Order Selection Page context

get

If additional information needs to be collected from the user during checkout, a custom schema can be defined on the Order model via the admin interface. This page returns that schema so the frontend can render the appropriate form. The submitted value is stored in pre_order.data['extra_field'] and written to the order upon completion. This is an independent page — submitting it does not advance the checkout flow.

Preconditions:

• None — this page is always reachable regardless of checkout state.

Skip Conditions:

• Page is skipped if extra_field has already been set in pre_order.data.

Next Pages:

• No further checkout page from this step (EmptyPage)

Note: This page is only used by projects that have a custom order schema configured in the admin interface.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Order Selection Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=OrderSelectionPage

HTTPcURLJavaScriptPython

200

Order Selection Page context retrieved

Submit custom extra field value for the order

post

Accepts a JSON value for the extra_field on the order, validates it against the Order model's attribute configuration, and stores it in pre_order.data. This is an independent page — submitting it does not advance the checkout flow.

Fields:

• extra_field: A JSON value that must conform to the schema defined for the Order model's extra_field attribute. Validated via Order.get_attribute_config('extra_field'). If no attribute config exists, the value is stored as-is.

Validation:

• If an attribute config for extra_field exists and attribute.validate_value() raises AttributeConfigNotFoundException or AttributeInputTypeNotValidException, a validation error is returned.

State Update:

• On success, pre_order.data['extra_field'] is set to the validated value.

Backward Navigation:

• When navigating backward, extra_field is removed from pre_order.data.

Next Pages:

• No further checkout page (EmptyPage)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

extra_fieldanyRequired

A JSON value for the Order model's extra_field attribute. Must conform to the schema defined by the Order model's attribute configuration (accessible via the schema key in the GET page context). Validated via Order.get_attribute_config('extra_field'). If no attribute config is registered, the value is stored as-is without additional validation.

Example: {"preference":"gift"}

Responses

200

Extra field saved or validation error

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=OrderSelectionPage

HTTPcURLJavaScriptPython

200

Extra field saved or validation error

Get Slot Selection Page context

get

Returns the available delivery time slots for the user to choose from. Slots are generated by SlotService.generate_slots() based on configured slot day counts and the selected delivery option.

Preconditions:

• Basket must not be empty

• User email must be set (user_email_not_empty)

• A shipping address must be selected (check_address_selected)

Skip Conditions:

• Page is skipped if a delivery range has already been selected (i.e., delivery_range is set in the pre-order)

Next Pages:

• PaymentOptionSelectionPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Slot Selection Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=SlotSelectionPage

HTTPcURLJavaScriptPython

200

Slot Selection Page context retrieved

Select a delivery time slot

post

Submits the chosen delivery time window (lower and upper datetime bounds). The slot is validated to ensure it is still available. On success, the shipping option and shipping amount are calculated and stored in the pre-order, and the delivery range is recorded.

Required Fields:

• lower: Start of the delivery time window (ISO 8601 datetime with timezone).

• upper: End of the delivery time window (ISO 8601 datetime with timezone).

Validation:

• The submitted range must still be available according to SlotService.is_delivery_range_available().

State Update:

• pre_order.shipping_option is set to the first available shipping option.

• pre_order.shipping_amount is calculated.

• pre_order.data['delivery_range'] is set to the selected range.

• If DELIVERY_BAGS_CONF.auto_run is enabled, DeliveryBagsPage is auto-processed.

• For retail store delivery options, the shipping address is replaced with the retail store address.

Backward Navigation:

• When navigating backward, delivery_range is reset, shipping_option is cleared, and shipping_amount is set to 0.00.

Next Pages:

• PaymentOptionSelectionPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

lowerstring · date-timeRequired

Start of the selected delivery time window. Must be an ISO 8601 datetime with timezone. Must be a currently available slot according to SlotService.is_delivery_range_available().

Example: 2026-05-01T10:00:00+03:00

upperstring · date-timeRequired

End of the selected delivery time window. Must be an ISO 8601 datetime with timezone.

Example: 2026-05-01T14:00:00+03:00

Responses

200

Slot selected or validation error

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=SlotSelectionPage

HTTPcURLJavaScriptPython

200

Slot selected or validation error

Get Reservation Selection Page context

get

Returns available delivery time slots for retail store reservation. This is a specialised variant of SlotSelectionPage used when the selected delivery option is a retail store. The user may optionally skip the reservation by submitting skip_reservation = true.

Preconditions:

• Basket must not be empty

• User email must be set (user_email_not_empty)

• A shipping address must be selected (check_address_selected)

• A retail store must be available for reservation (check_retail_store_available)

Skip Conditions:

• Page is skipped if a reservation has already been made (delivery_range set) or explicitly skipped (skip_reservation = true in pre-order data)

Next Pages:

• PaymentOptionSelectionPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Reservation Selection Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=ReservationSelectionPage

HTTPcURLJavaScriptPython

200

Reservation Selection Page context retrieved

Select a reservation slot or skip reservation

post

Submits a chosen retail store delivery time window, or explicitly skips reservation scheduling. If skip_reservation is true, lower and upper are not required and no delivery range is set.

Required Fields:

• skip_reservation: Whether to skip selecting a time slot. Defaults to false.

Conditionally Required Fields (required when skip_reservation is false):

• lower: Start of the delivery time window (ISO 8601 datetime with timezone).

• upper: End of the delivery time window (ISO 8601 datetime with timezone).

Validation:

• When skip_reservation is false, lower and upper are both required.

• The submitted range must be available according to SlotService.is_delivery_range_available().

State Update:

• pre_order.data['skip_reservation'] is set to the submitted boolean.

• pre_order.data['delivery_range'] is set to the selected range, or null if reservation is skipped.

Backward Navigation:

• When navigating backward, delivery_range is reset to null and skip_reservation is set to false.

Next Pages:

• PaymentOptionSelectionPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

skip_reservationbooleanRequired

Set to true to skip reservation scheduling. When true, lower and upper are not required and no delivery range is stored. When false, both lower and upper are required.

Default: falseExample: false

lowerstring · date-timeOptional

Start of the selected reservation time window. Required when skip_reservation is false.

Example: 2026-05-01T10:00:00+03:00

upperstring · date-timeOptional

End of the selected reservation time window. Required when skip_reservation is false.

Example: 2026-05-01T12:00:00+03:00

Responses

200

Reservation selected or skipped

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=ReservationSelectionPage

HTTPcURLJavaScriptPython

Select a reservation time slotSkip reservation scheduling

200

Reservation selected or skipped

Get Credit Payment Selection Page context

get

Returns the list of available POS (point-of-sale) options for credit payment. This page is reached when the user selects a payment option whose type is credit_payment.

Preconditions:

• Basket must not be empty

• A credit payment option must be selected (check_credit_payment_selected)

Skip Conditions:

• Page is skipped if a POS option has already been selected (i.e., credit_payment_option is set in pre_order.data)

Next Pages:

• CreditPaymentConfirmationPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Credit Payment Selection Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=CreditPaymentSelectionPage

HTTPcURLJavaScriptPython

200

Credit Payment Selection Page context retrieved

Select a credit POS option

post

Stores the selected POS option in pre_order.data['credit_payment_option']. The submitted PK must belong to one of the available POS options returned in the GET context (payment_option.get_available_poses()).

Required Fields:

• credit_payment_option: Primary key of the selected Pos object.

Validation:

• The POS must be present in the available POS options for the current payment option.

State Update:

• pre_order.data['credit_payment_option'] is set to the selected Pos instance.

Backward Navigation:

• When navigating backward, credit_payment_option is reset to null.

Next Pages:

• CreditPaymentConfirmationPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

credit_payment_optionintegerRequired

Primary key of the selected Pos object. Must be one of the available POS options returned by payment_option.get_available_poses() for the current credit payment option.

Example: 10

Responses

200

POS option selected or validation error

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=CreditPaymentSelectionPage

HTTPcURLJavaScriptPython

200

POS option selected or validation error

Get Credit Payment Confirmation Page context

get

Returns the empty confirmation page context. At this step the user reviews the order and accepts the terms and conditions before being redirected to the payment gateway.

Preconditions:

• Basket must not be empty

• A credit payment option must be selected (check_payment_option)

• A POS option must have been selected (check_credit_payment_option_selected)

Skip Conditions:

• Page is skipped if the redirect URL is already set in the pre-order and the user has not yet been redirected (redirect_url set and is_redirected is false)

Note — is_redirected flag:

• is_redirected is set to true when the user visits /orders/redirection/ (RedirectionView), which acts as a bridge before forwarding to the payment gateway. Once is_redirected is true, this page is no longer considered done and will be shown again if the user navigates back (e.g. payment failed at the gateway).

Page Context: (empty)

Next Pages:

• CreditPaymentCompletePage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Credit Payment Confirmation Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=CreditPaymentConfirmationPage

HTTPcURLJavaScriptPython

200

Credit Payment Confirmation Page context retrieved

Confirm credit payment and initiate gateway redirect

post

Accepts the user's agreement and initiates the payment redirect via payment_strategy.start_redirect(). On success, a redirect_url is stored in the pre-order for the frontend to redirect the user to the payment gateway.

Required Fields:

• agreement: User must accept the terms and conditions. Must be true.

Validation:

• agreement must be true.

• Basket amount must be greater than zero.

State Update:

• pre_order.data['redirection_started'] is set to true.

• pre_order.data['is_redirected'] is set to false.

• pre_order.data['redirect_url'] is set to the gateway redirect URL.

• pre_order.data['remote_redirect_url'] and pre_order.data['token'] may also be set.

Backward Navigation:

• When navigating backward, redirection_started, is_redirected, redirect_url, and token are removed from pre_order.data.

Next Pages:

• CreditPaymentCompletePage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

agreementboolean · enumRequired

User must accept the terms and conditions to initiate the payment redirect. Must be true.

Possible values:

Responses

200

Redirect initiated or error

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=CreditPaymentConfirmationPage

HTTPcURLJavaScriptPython

200

Redirect initiated or error

Get Credit Payment Complete Page context

get

Returns the gateway redirect URL so the frontend can redirect the user to the payment gateway. This page is shown after the confirmation step has initiated the payment redirect.

Preconditions:

• Basket must not be empty

• A credit payment option must be selected (check_payment_option)

• A POS option must have been selected (credit_payment_option_selected)

• Payment redirect must have been initiated (is_redirection_started)

Skip Conditions:

• Page is skipped if the order has been finalized (order_finalized())

Page Context:

• redirect_url: The URL to redirect the user to on the payment gateway.

• is_iframe: Whether the redirect should be rendered in an iframe (optional).

Next Pages:

• ThankYouPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Credit Payment Complete Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=CreditPaymentCompletePage

HTTPcURLJavaScriptPython

200

Credit Payment Complete Page context retrieved

Complete credit payment after gateway redirect

post

Processes the payment gateway's callback after the user returns from the payment redirect. The required input fields depend on the specific payment gateway configured for the selected POS option.

Gateway-Specific Input Serializers:

• compay_credit → Response, acqResponseCode, AuthCode (optional), orderId, amount, productType (optional) — hash-validated

• garanti_credit → success (must be true), TransactionId, Key, CardToken

• fiba_credit → success (must be true)

• zip_credit → checkout_id

• Default (other gateways) → success (must be true)

Validation:

• Gateway-specific hash or status validation is performed.

State Update:

• On success, a transaction is created and the order is finalized.

• pre_order.data['is_redirected'] is set to false after processing.

Backward Navigation:

• On error, redirection_started, is_redirected, redirect_url, and token are removed from pre_order.data.

Next Pages:

• ThankYouPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

The active schema depends on the gateway of the selected POS option (pre_order.data['credit_payment_option'].gateway).

or

or

or

or

Responses

200

Payment completed or error

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=CreditPaymentCompletePage

HTTPcURLJavaScriptPython

Default gateway callback (success)Garanti credit gateway callbackComPay credit gateway callback

200

Payment completed or error

Get MobilExpress Selection Page context

get

Returns the context for the MobilExpress stored-card flow entry point. This page is reached when the user selects a payment option whose type is stored_card (a MobilExpress-backed option). The page has no page context of its own; its role is to trigger a card-list lookup on the MobilExpress gateway.

Preconditions:

• Basket must not be empty

• Payment option must be selected and must be MobilExpress type (check_mobilexpress_payment_selected)

Skip Conditions:

• Page is skipped when MobilExpressSelectionPage has already been completed and the order number is assigned (is_already_done).

Page Context: (empty)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

MobilExpress selection page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=MobilExpressSelectionPage

HTTPcURLJavaScriptPython

200

MobilExpress selection page context retrieved

Confirm MobilExpress card-list lookup

post

Triggers a card-list lookup on the MobilExpress gateway for the current user. Based on the gateway response, the flow proceeds to the OTP phone entry page (if OTP is required) or directly to the card list page.

Required Fields:

• clear: Set to true to cancel the MobilExpress flow and clear all stored MobilExpress data from the pre-order. Set to false (default) to proceed.

State Changes (when clear is false):

• pre_order.number is assigned

• pre_order.data['me_user_checked'] is set to true

• pre_order.data['me_needs_otp'] is set based on the gateway's otp_required flag

• Forward MobilExpress data (me_otp_sent, me_phone_number, etc.) is cleared

State Changes (when clear is true):

• All me_* keys are removed from pre_order.data

Next Page:

• MobilExpressCardFoundOtpRequiredPhonePage — when me_needs_otp is true

• MobilExpressCardListPage — otherwise

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

clearbooleanOptional

Set to true to cancel the MobilExpress flow and clear all stored MobilExpress data from the pre-order. Set to false (default) to proceed with the card-list lookup.

Default: false

Responses

200

MobilExpress selection processed

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=MobilExpressSelectionPage

HTTPcURLJavaScriptPython

Proceed with MobilExpress card lookupCancel MobilExpress flow

200

MobilExpress selection processed

Get MobilExpress OTP Phone Entry Page context

get

Returns the context for the phone number entry step when the MobilExpress gateway requires OTP verification before returning the card list.

Preconditions:

• Basket must not be empty

• Payment option must be selected and must be MobilExpress type (check_mobilexpress_payment_selected)

• MobilExpressSelectionPage must have been completed and the MobilExpress gateway must have indicated that OTP verification is required to retrieve the card list (check_need_otp)

Page Context:

• phone_number: The user's phone number pre-filled from pre_order.user.phone

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

OTP phone entry page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=MobilExpressCardFoundOtpRequiredPhonePage

HTTPcURLJavaScriptPython

200

OTP phone entry page context retrieved

Submit phone number to receive MobilExpress OTP

post

Sends an OTP to the provided phone number via the MobilExpress gateway (send_otp_for_card_list). On success, the flow advances to the OTP entry page.

Required Fields:

• phone_number: Recipient phone number. Must be exactly 10 characters.

State Changes:

• pre_order.data['me_otp_sent'] is set to true

• pre_order.data['me_phone_number'] is set to the submitted phone number

• Forward MobilExpress data (me_otp_valid, me_card_token, etc.) is cleared

Next Page: MobilExpressCardFoundOtpRequiredOtpPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

phone_numberstring · min: 10 · max: 10Required

Recipient phone number for the OTP SMS. Must be exactly 10 characters.

Example: 5551234567

Responses

200

OTP phone submission result

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=MobilExpressCardFoundOtpRequiredPhonePage

HTTPcURLJavaScriptPython

200

OTP phone submission result

Get MobilExpress OTP Entry Page context

get

Returns the context for the OTP entry step. The user enters the code that was sent to their phone on MobilExpressCardFoundOtpRequiredPhonePage.

Preconditions:

• Basket must not be empty

• Payment option must be selected and must be MobilExpress type (check_mobilexpress_payment_selected)

• MobilExpressSelectionPage must have been completed and the MobilExpress gateway must have indicated that OTP verification is required to retrieve the card list (check_need_otp)

• OTP SMS must have been sent and phone number must have been recorded (check_otp_sent)

Page Context: (empty)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

OTP entry page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=MobilExpressCardFoundOtpRequiredOtpPage

HTTPcURLJavaScriptPython

200

OTP entry page context retrieved

Verify MobilExpress OTP and retrieve card list

post

Submits the OTP code to the MobilExpress gateway (verify_and_get_card_list). On success, the flow advances to the card selection page.

Required Fields:

• otp: The OTP code received by the user. Between 4 and 8 characters.

State Changes:

• pre_order.data['me_otp_valid'] is set to true

• me_otp_sent, me_phone_number, and me_needs_otp are removed from pre_order.data

• Forward MobilExpress data (me_card_token, etc.) is cleared

Next Page: MobilExpressCardListPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

otpstring · min: 4 · max: 8Required

One-time password received by the user via SMS. Between 4 and 8 characters.

Example: 123456

Responses

200

OTP verification result

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=MobilExpressCardFoundOtpRequiredOtpPage

HTTPcURLJavaScriptPython

200

OTP verification result

Get MobilExpress Card List Page context

get

Returns the list of stored cards available for the current user from the MobilExpress gateway. The user selects one of these cards to proceed with payment.

Preconditions:

• Basket must not be empty

• Payment option must be selected and must be MobilExpress type (check_mobilexpress_payment_selected)

• MobilExpressSelectionPage must have been completed and, if OTP was required, OTP verification must also have been completed (check_user_source)

Skip Conditions:

• Page is skipped when a card has already been selected (me_card_token, me_masked_card_number, and card_info are all set).

Page Context:

• cards: List of stored cards returned by the gateway. Each card contains:

  • masked_card_number: Partially masked PAN (e.g., "450803******1234")

  • card_token: Opaque token identifying the card

  • is_expired: Whether the card is expired (may be null)

  • last_year: Card expiry year (may be null)

  • last_month: Card expiry month (may be null)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Card list page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=MobilExpressCardListPage

HTTPcURLJavaScriptPython

200

Card list page context retrieved

Select a MobilExpress stored card

post

Records the card chosen by the user. The card token and masked card number are stored on the pre-order and the corresponding CardInfo (BIN-based card type lookup) is set.

Required Fields:

• card_token: Opaque token identifying the selected card.

• masked_card_number: Partially masked PAN of the selected card. Used to derive the BIN number for installment/card-type lookup.

State Changes:

• pre_order.data['me_card_token'] is set to card_token

• pre_order.data['me_masked_card_number'] is set to masked_card_number

• pre_order.card_info is set based on BIN lookup

• Forward MobilExpress data (me_payment_tried, etc.) is cleared

Next Page: MobilExpressInstallmentSelectionPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

card_tokenstringRequired

Opaque token identifying the selected stored card.

Example: token-abc

masked_card_numberstringRequired

Partially masked PAN of the selected card (e.g., "450803******1234"). Used for BIN-based card type and installment lookup.

Example: 450803******1234

Responses

200

Card selection result

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=MobilExpressCardListPage

HTTPcURLJavaScriptPython

200

Card selection result

Get MobilExpress Installment Selection Page context

get

Returns the list of available installment options for the selected MobilExpress card. Installment options are determined by the card type obtained from the BIN lookup.

Preconditions:

• Basket must not be empty

• Payment option must be selected and must be MobilExpress type (check_mobilexpress_payment_selected)

• A card must have been selected from the card list and BIN lookup must have been completed (check_card_selected)

Skip Conditions:

• Page is skipped when pre_order.installment is already set (is_already_done).

Page Context:

• installments: List of available installment plans for the selected card

• installment_messages: List of informational messages from the installment service

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Installment selection page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=MobilExpressInstallmentSelectionPage

HTTPcURLJavaScriptPython

200

Installment selection page context retrieved

Select a MobilExpress installment plan

post

Records the chosen installment plan on the pre-order.

Required Fields:

• installment: Primary key of the Installment record to use. Must be an active installment option linked to the selected card.

State Changes:

• pre_order.installment is set to the selected Installment instance

• pre_order.selected_campaign, pre_order.selected_rewards, and pre_order.payment_choice are reset to null

• Forward payment data (me_payment_tried, etc.) is cleared

Next Page: MobilExpressTryPaymentPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

installmentintegerRequired

Primary key of the Installment record to use. Must be an active installment option linked to the selected card type.

Example: 1

Responses

200

Installment selection result

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=MobilExpressInstallmentSelectionPage

HTTPcURLJavaScriptPython

200

Installment selection result

Get MobilExpress Try Payment Page context

get

Returns the context for the payment attempt step. This page triggers the actual payment request to the MobilExpress gateway.

Preconditions:

• Basket must not be empty

• Payment option must be selected and must be MobilExpress type (check_mobilexpress_payment_selected)

• A card must have been selected from the card list and BIN lookup must have been completed (check_card_selected)

• An installment plan must have been selected (check_installment_selected)

• Basket items must still be available at time of payment (check_available_basketitems)

Skip Conditions:

• Page is skipped when the order is already finalized or me_payment_tried is set.

Page Context: (empty)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Try payment page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=MobilExpressTryPaymentPage

HTTPcURLJavaScriptPython

200

Try payment page context retrieved

Attempt MobilExpress payment

post

Submits the payment attempt to the MobilExpress gateway (process_payment). Depending on the gateway's ResultCode, the flow routes to different completion pages.

Required Fields:

• agreement: User must accept the terms and conditions. Must be true.

Payment Flow:

• The gateway is called with the stored card token, order number, installment count, and total amount. 3D Secure may be requested automatically based on system rules.

• If ResultCode is Success and no further action is needed, the order is created and the user is routed to ThankYouPage.

• If ResultCode is ThreeDSecureURLCreated, a 3D redirect URL is stored and the user is routed to MobilExpressPaymentThreeDPage.

• Other result codes route to the appropriate completion page.

State Changes (on non-success outcome):

• pre_order.data['me_payment_tried'] is set to true

• pre_order.data['me_payment_succeeded'] is set based on the result

• pre_order.data['me_further_action'] is set to the ResultCode

• pre_order.data['me_transaction_id'] is set to the MobilExpress transaction ID

• pre_order.data['me_three_d_redirect_url'] is set if 3D redirect is needed

Next Page:

• ThankYouPage — payment succeeded

• MobilExpressPaymentThreeDPage — 3D Secure redirect required

• MobilExpressPaymentCompleteOtpPage — ResultCode is OTPRequired

• MobilExpressPaymentCompleteCvvPage — ResultCode is CVVRequired

• MobilExpressPaymentCompleteCvvAndOtpPage — ResultCode is CVVAndOTPRequired

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

agreementboolean · enumRequired

User must accept the terms and conditions to proceed. Must be true.

Possible values:

Responses

200

Payment attempt result

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=MobilExpressTryPaymentPage

HTTPcURLJavaScriptPython

200

Payment attempt result

Get MobilExpress Payment Complete OTP Page context

get

Returns the context for the OTP completion step after the initial payment attempt returned ResultCode: OTPRequired.

Preconditions:

• Basket must not be empty

• Payment option must be selected and must be MobilExpress type (check_mobilexpress_payment_selected)

• Initial payment attempt must have returned OTPRequired as the result code (check_needs_otp)

Page Context: (empty)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

OTP completion page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=MobilExpressPaymentCompleteOtpPage

HTTPcURLJavaScriptPython

200

OTP completion page context retrieved

Complete MobilExpress payment with OTP

post

Finalises the payment by submitting the OTP to the MobilExpress gateway (finish_payment_process with otp set and cvv empty). On success, the order is created.

Required Fields:

• otp: The OTP code received by the user. Between 4 and 8 characters.

Next Page: ThankYouPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

otpstring · min: 4 · max: 8Required

OTP code for payment completion. Between 4 and 8 characters.

Example: 483921

Responses

200

OTP payment completion result

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=MobilExpressPaymentCompleteOtpPage

HTTPcURLJavaScriptPython

200

OTP payment completion result

Get MobilExpress Payment Complete CVV Page context

get

Returns the context for the CVV completion step after the initial payment attempt returned ResultCode: CVVRequired.

Preconditions:

• Basket must not be empty

• Payment option must be selected and must be MobilExpress type (check_mobilexpress_payment_selected)

• Initial payment attempt must have returned CVVRequired as the result code (check_needs_cvv)

Page Context: (empty)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

CVV completion page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=MobilExpressPaymentCompleteCvvPage

HTTPcURLJavaScriptPython

200

CVV completion page context retrieved

Complete MobilExpress payment with CVV

post

Finalises the payment by submitting the CVV to the MobilExpress gateway (finish_payment_process with cvv set and otp empty). On success, the order is created.

Required Fields:

• cvv: The 3-digit card security code.

Next Page: ThankYouPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

cvvstring · min: 3 · max: 3Required

3-digit card security code (CVV/CVC) printed on the back of the card.

Example: 123

Responses

200

CVV payment completion result

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=MobilExpressPaymentCompleteCvvPage

HTTPcURLJavaScriptPython

200

CVV payment completion result

Get MobilExpress Payment Complete CVV and OTP Page context

get

Returns the context for the combined CVV and OTP completion step after the initial payment attempt returned ResultCode: CVVAndOTPRequired.

Preconditions:

• Basket must not be empty

• Payment option must be selected and must be MobilExpress type (check_mobilexpress_payment_selected)

• Initial payment attempt must have returned CVVAndOTPRequired as the result code (check_needs_cvv_and_otp)

Page Context: (empty)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

CVV and OTP completion page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=MobilExpressPaymentCompleteCvvAndOtpPage

HTTPcURLJavaScriptPython

200

CVV and OTP completion page context retrieved

Complete MobilExpress payment with CVV and OTP

post

Finalises the payment by submitting both the CVV and OTP to the MobilExpress gateway (finish_payment_process with both otp and cvv set). On success, the order is created.

Required Fields:

• otp: The OTP code received by the user. Between 4 and 8 characters.

• cvv: The 3-digit card security code.

Next Page: ThankYouPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

cvvstring · min: 3 · max: 3Required

3-digit card security code (CVV/CVC).

Example: 123

otpstring · min: 4 · max: 8Required

OTP code for payment completion. Between 4 and 8 characters.

Example: 483921

Responses

200

CVV and OTP payment completion result

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=MobilExpressPaymentCompleteCvvAndOtpPage

HTTPcURLJavaScriptPython

200

CVV and OTP payment completion result

Get MobilExpress Payment 3D Secure Page context

get

Returns the 3D Secure redirect URL for the current MobilExpress payment attempt. The client should redirect the user to this URL to complete 3D Secure verification. After the bank redirects back, the POST endpoint finalises the order.

Preconditions:

• Basket must not be empty

• Payment option must be selected and must be MobilExpress type (check_mobilexpress_payment_selected)

• A 3D Secure redirect URL must have been generated by the MobilExpress gateway (check_redirect_url)

Skip Conditions:

• Page is skipped when the order is already finalized (is_already_done).

Page Context:

• me_redirect_url: The 3D Secure redirect URL provided by the MobilExpress gateway

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

3D Secure page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=MobilExpressPaymentThreeDPage

HTTPcURLJavaScriptPython

200

3D Secure page context retrieved

Complete MobilExpress 3D Secure payment

post

Finalises the order after the user completes 3D Secure verification at the bank. This endpoint is called by the browser after the bank redirects back to the checkout URL with page=MobilExpressPaymentThreeDPage&pos_redirect=true as query parameters.

The gateway's hash is validated and finish_payment_process is called with three_d_secure=True.

Required Fields (posted by the bank's redirect):

• TransactionId: The internal order transaction ID

• MobilexpressTransId: The MobilExpress transaction ID

• Result: 3D Secure result. Must be '3DSuccess' to proceed with order creation

• TotalAmount: Total payment amount (must match pre_order amount)

• InstallmentCount: Number of installments used

• Hash: HMAC hash from the MobilExpress gateway for response integrity verification

Validation:

• Result must be '3DSuccess'; otherwise a validation error is returned

• Hash must be valid (verified by gateway.is_hash_valid)

• TotalAmount must match pre_order.get_total_amount_with_interest()

Next Page: ThankYouPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

TransactionIdstringRequired

Internal order transaction ID posted by the bank redirect.

Example: ORDER-20240115-001

MobilexpressTransIdstringRequired

MobilExpress transaction ID posted by the bank redirect.

Example: ME-TXN-987654

Resultstring · enumRequired

3D Secure result code. Must be '3DSuccess' to proceed.

Example: 3DSuccessPossible values:

TotalAmountstring · decimalRequired

Total payment amount posted by the bank redirect (12 digits, 2 decimal places). Must match pre_order.get_total_amount_with_interest().

Example: 350.00

InstallmentCountintegerRequired

Number of installments used in the transaction.

Example: 1

HashstringRequired

HMAC hash from the MobilExpress gateway for response integrity verification. Validated via gateway.is_hash_valid.

Example: a3f5c2d1e8b94f7a...

Responses

200

3D Secure payment completion result

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=MobilExpressPaymentThreeDPage

HTTPcURLJavaScriptPython

200

3D Secure payment completion result

Get Redirection Payment Selected Page context

get

Returns the context for the Redirection Payment Selected Page.

This page acts as a transition step in the redirection-based payment flow. It is reached after a payment option with payment_type: redirection has been selected on the pre-order. The page itself carries no additional context data; its purpose is to confirm that the preconditions for initiating the redirect are met before the customer proceeds to submit the form.

Preconditions:

• The basket must not be empty

• A payment option with payment_type: redirection must be selected on the pre-order

• No active transaction must exist for the current payment attempt (the transaction slot must be clear so that a fresh transaction can be created on form submission)

Auto-advance:

• If all three preconditions are met and the redirect has already been initiated (an order number is assigned and the redirection flow has started), the system considers this step complete and automatically advances to RedirectionPageCompletePage without requiring the customer to resubmit.

Navigation:

• Previous page: PaymentOptionSelectionPage

• Next page: RedirectionPageCompletePage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Redirection Payment Selected Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

302

Redirect to basket (empty basket) or login (guest purchase not allowed)

get

/orders/checkout/?page=RedirectionPaymentSelectedPage

HTTPcURLJavaScriptPython

Initiate Redirection Payment

post

Initiates the external payment gateway redirect for the selected redirection-based payment option. After successful submission, the system advances to RedirectionPageCompletePage, where the customer is sent to the payment provider's hosted page.

The customer must accept the terms and conditions (agreement: true) before the redirect can be initiated. Optionally, browser metadata fields may be submitted to support gateway-level installment selection or device fingerprinting.

Preconditions:

• The basket must not be empty

• A payment option with payment_type: redirection must be selected on the pre-order

• No active transaction must exist for the current payment attempt

Processing Flow:

1. Stores submitted browser metadata (browser_installments, browser_client_type) on the pre-order for use by the payment gateway strategy

2. Captures the customer's IP address and attaches it to the pre-order

3. Assigns an order number to the pre-order

4. Queries available installment options from the payment provider

5. Constructs success and failure callback URLs pointing to RedirectionPageCompletePage

6. Appends a single-use session token to both callback URLs to prevent session replay on return (controlled by USE_ONE_TIME_TOKEN)

7. Optionally embeds an encoded order number in the callback URLs to support isolated session recovery on return from the provider (controlled by ORDERS_USE_ISOLATED_PRE_ORDER_ON_RETURN)

8. Calls the gateway strategy to start the redirect; the strategy contacts the external payment provider and retrieves the redirect URL

9. On success: stores the redirect URL, remote redirect URL, inline HTML content (if applicable), transaction identifier, and marks the redirection as started on the pre-order

10. On failure: rolls back the assigned order number and returns a validation error so the customer may retry

Configuration:

• USE_ONE_TIME_TOKEN (dynamic setting, default: true): When enabled, a single-use token is appended to both the success and failure callback URLs. The token is validated on return to prevent session replay attacks.

• ORDERS_USE_ISOLATED_PRE_ORDER_ON_RETURN (static setting, default: false): When enabled, an encoded order number is embedded in the callback URLs (n query parameter) to allow the system to recover the correct pre-order session when the customer returns from the payment provider.

Post-order support:

• This page is available for post-order flows (available_for_post_order: true), allowing the payment step to be re-initiated on an existing order.

Forward page invalidation:

• Submitting this page invalidates all subsequent checkout pages (invalidate_forward_pages: true), ensuring that downstream steps (such as RedirectionPageCompletePage) reflect the freshly initiated payment state.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

Submission payload for initiating a redirection-based payment. Accepting the terms and conditions is mandatory. Browser metadata fields are optional and are forwarded to the payment gateway strategy to support installment pre-selection and device fingerprinting at the provider level.

agreementboolean · enumRequired

Customer's acceptance of the terms and conditions. Must be true; any other value prevents the redirect from being initiated.

Possible values:

browser_installmentsstring · max: 64 · nullableOptional

Colon-separated list of installment counts supported by the customer's browser environment (e.g., "1:3:6:9:12"). Each value must be an integer between 0 and 120 inclusive. Forwarded to the payment gateway to pre-select compatible installment options on the provider's hosted page.

browser_client_typestring · max: 64 · nullableOptional

Identifier for the type of client or browser environment initiating the payment (e.g., "web", "mobile"). Forwarded to the payment gateway strategy for device-aware routing or display decisions.

Responses

200

Redirect initiated. On success the system advances to RedirectionPageCompletePage. On failure the order number is rolled back and a validation error is returned so the customer may retry.

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

302

Redirect to basket (empty basket) or login (guest purchase not allowed)

post

/orders/checkout/?page=RedirectionPaymentSelectedPage

HTTPcURLJavaScriptPython

Minimal submission — agreement onlySubmission with browser installment and client type hints

Get Redirection Payment Completion Page context

get

Returns the payment gateway redirect URL and iframe display settings for completing a redirection-based payment flow.

This page is reached after the payment provider has accepted the transaction initiation (RedirectionPaymentSelectedPage). It provides the URL of the provider's hosted payment page where the customer authorises the transaction, along with a flag that controls whether that page is rendered inline or as a full redirect.

Preconditions:

• A redirection-based payment option (payment_type: redirection) must be selected on the pre-order

• The redirect flow must have been started (the payment provider accepted the transaction start and issued a redirect URL)

• The pre-order must have an assigned order number

Page Context:

• redirect_url — The full URL of the payment provider's hosted payment page

• is_iframe — Whether the provider's page should be embedded in an inline frame rather than navigating away from the checkout

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Redirection payment completion page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

302

Redirect to basket (empty basket) or login (guest purchase not allowed)

get

/orders/checkout/?page=RedirectionPageCompletePage

HTTPcURLJavaScriptPython

Process Redirection Payment Callback

post

Processes the callback returned by the external payment gateway after the customer completes or abandons the payment on the provider's hosted page.

The gateway posts its result to this endpoint (or the browser is redirected back to it). Query parameters present on the incoming URL are automatically merged with the POST body before validation, so gateway implementations that return data as redirect query strings are handled transparently.

The specific fields required vary by the active payment gateway. Most gateways include a success indicator; additional fields carry transaction identifiers, hash values, and status codes for server-side verification.

Preconditions:

• A redirection-based payment option must be selected

• The redirect flow must have been started

• The pre-order must have an assigned order number

Processing Flow:

1. Merges GET query parameters from the callback redirect URL into the submitted data

2. Selects the gateway-specific input schema based on the active payment provider. TeqPay note: the gateway submits fields as Token and Result (capitalised); these are normalised to token and result before validation

3. Validates callback fields (transaction ID, hash, status codes). Extension gateway note: installment_count and interest_fee values from the callback are stored on the pre-order under installment_alt (installment_count + installment_interest_amount) for downstream order and interest calculation

4. Records a return transaction entry with the payment outcome

5. On success: finalises the order, submits the basket, sends order confirmation email and SMS notifications

6. On failure: rolls back the redirection state and resets the order number so the customer may retry from the payment selection step

Configuration:

• USE_ONE_TIME_TOKEN (dynamic setting, default: true): When enabled, a single-use token is appended to both the success and failure callback URLs at transaction start. The token is validated on return to prevent session replay.

• ORDERS_USE_ISOLATED_PRE_ORDER_ON_RETURN (static setting, default: false): When enabled, an encoded order number is embedded in the callback URLs (n query parameter) to support isolated pre-order session recovery on return from the payment provider.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

Gateway callback payload posted to this endpoint after the customer completes or abandons the payment on the provider's hosted page.

The exact fields required depend on the active payment gateway. The gateway is determined by the POS record associated with the selected payment option. Most providers include a success indicator; additional fields carry transaction identifiers, hash values, and status codes for server-side verification.

or

or

or

or

or

or

or

or

or

or

or

or

or

Responses

200

Payment callback processed. On success the order is finalised and the response advances to ThankYouPage. On failure the redirection state is reset and an error is returned so the customer may retry.

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

302

Redirect to basket (empty basket) or login (guest purchase not allowed)

post

/orders/checkout/?page=RedirectionPageCompletePage

HTTPcURLJavaScriptPython

Generic gateway — success flag only (yandex_money, alpha, multisafepay, etc.)TeqPay gateway — capitalised fields (normalised to token/result server-side)

Get GPay Selection Page context

get

Returns the current checkout state for the Garanti Pay (GPay) selection step.

This page is reached after the customer selects a payment option whose type is gpay. It serves as a confirmation step before the system resolves the card type associated with the GPay BIN number and assigns an order number to the pre-order. The page itself carries no additional context data; all relevant order and payment information is available through the pre_order field of the response.

Preconditions:

• A payment option with payment_type: gpay must be selected on the pre-order

• No transaction must be in progress (no transaction identifier present, order number must be unset, and no card information must be resolved yet)

Auto-advance: This page is considered already complete when the GPay payment option is selected, the pre-order holds an assigned order number, and a card record has been resolved from the GPay BIN number. In that case the flow advances directly to GPayRedirectPage without requiring resubmission.

Navigation:

• Previous page: PaymentOptionSelectionPage

• Next page: GPayRedirectPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

GPay Selection Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

302

Redirect to basket (empty basket) or login (guest purchase not allowed)

get

/orders/checkout/?page=GPaySelectionPage

HTTPcURLJavaScriptPython

Confirm GPay Selection

post

Confirms the GPay payment selection and resolves the card type for the pre-order by looking up the card record associated with the configured GPay BIN number.

The request body must be submitted empty. Any fields present in the POST body will cause the request to be rejected with a validation error. This endpoint acts as a confirmation-only step that requires no additional customer input.

On success the system resolves the card type from the GPay BIN number record, attaches the card information to the pre-order, assigns a new order number, and advances to GPayRedirectPage to create the payment transaction.

Preconditions:

• A payment option with payment_type: gpay must be selected on the pre-order

• No transaction must be in progress

• The basket amount must be greater than zero

Processing Flow:

1. Validates that the basket amount is positive

2. Validates that the request body is empty

3. Looks up the card type using the configured GPay BIN number (GPAY_BIN_NUMBER)

4. On BIN number found: attaches the resolved card information to the pre-order and assigns a new order number

5. On BIN number not found: clears any existing card information and resets the order number silently — no error is returned. The flow does not advance because the next step requires card information to be present. Clients should check card_info: null on the pre_order to detect this condition

6. On success: advances to GPayRedirectPage

Configuration:

• GPAY_BIN_NUMBER (static setting, default: "GPAY00"): The BIN number used to look up the Garanti Pay card record. The resolved card determines which installment options are available for the GPay transaction.

Post-order support:

• This page is available for post-order flows (available_for_post_order: true), allowing a GPay payment to be re-initiated on an existing order.

Forward page invalidation:

• Submitting this page invalidates all subsequent checkout pages (invalidate_forward_pages: true), ensuring that GPayRedirectPage and GPayCompletePage reflect the freshly resolved card and order state.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

objectOptional

Confirmation payload for the GPay selection step. The request body must be submitted empty — any fields present will cause the request to be rejected with a validation error.

This design reflects the nature of the step: the customer simply confirms their GPay selection, and no additional data entry is required. The system resolves the card type and order number automatically upon submission.

Responses

200

GPay card resolved. On success the pre-order is updated with the resolved card information and order number, and the flow advances to GPayRedirectPage. On BIN number lookup failure the pre-order state is cleared but no error is raised — check card_info: null on the pre_order to detect this condition.

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

302

Redirect to basket (empty basket) or login (guest purchase not allowed)

post

/orders/checkout/?page=GPaySelectionPage

HTTPcURLJavaScriptPython

Get GPay Complete Page context

get

Returns the context for the Garanti Pay (GPay) payment completion step.

This page is reached after GPayRedirectPage has created the payment transaction and the customer is ready to be directed to the Garanti Pay hosted payment form. The page context provides the redirect URL for the GPay payment endpoint, where the customer authorises and selects their instalment option on the provider's interface.

Preconditions:

• A payment option with payment_type: gpay must be selected on the pre-order

• A transaction identifier must be present on the pre-order (set by GPayRedirectPage)

Page Context:

• redirect_url — The path of the Garanti Pay redirect endpoint (/orders/gpay-redirect/). The customer must be navigated to this URL to complete the payment on the provider's hosted form.

Auto-advance: This page is considered already complete when the order has been finalised and a transaction identifier is present. In that case the flow advances directly to ThankYouPage without requiring resubmission.

Navigation:

• Previous page: GPayRedirectPage

• Next page: ThankYouPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

GPay Complete Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

302

Redirect to basket (empty basket) or login (guest purchase not allowed)

get

/orders/checkout/?page=GPayCompletePage

HTTPcURLJavaScriptPython

Process GPay Payment Callback

post

Processes the callback returned by the Garanti Pay gateway after the customer completes the payment on the provider's hosted form.

The gateway posts its result to this endpoint. Query parameters present on the incoming callback URL are automatically merged with the POST body before validation, so fields returned via redirect query string are handled transparently alongside form-encoded fields.

The submitted payload is verified server-side using a gateway-specific HMAC hash. The gpinstallment value is resolved against the card's active instalment records and stored on the pre-order before order finalisation.

Preconditions:

• A payment option with payment_type: gpay must be selected on the pre-order

• A transaction identifier must be present on the pre-order

Processing Flow:

1. Merges GET query parameters from the callback URL into the submitted data

2. Validates gpay: true and success: true flags from the gateway

3. Resolves gpinstallment against the active instalment options for the pre-order's card and stores the resolved instalment on the pre-order

4. Verifies the full payload against the gateway's HMAC hash to confirm authenticity

5. Creates a return transaction record (transaction_type: return_back) with the payment outcome; the transaction identifier follows the format GPAY_{order_number}_{suffix}

6. On success: finalises the order, submits the basket, sends order confirmation email and SMS notifications, then advances to ThankYouPage

7. On failure: performs a full rollback — clears transaction_id and the redirect state, resets the order number, and sets card_info to null, returning the pre-order to the state it held at GPaySelectionPage

No dynamic settings apply to this page. All behaviour is determined by the static configuration of the Garanti Pay gateway.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

Callback payload posted by the Garanti Pay gateway after the customer completes the payment on the provider's hosted form.

All three fields are required. gpay and success must both be true for the payment to be accepted. gpinstallment carries the instalment count selected by the customer on the Garanti Pay form and is resolved against the active instalment options for the pre-order's card.

The full payload (including any additional fields returned by the gateway) is also verified against a gateway-specific HMAC hash. Payloads that fail hash verification are rejected regardless of the gpay and success values.

gpayboolean · enumRequired

Garanti Pay authorisation flag returned by the gateway. Must be true; any other value is treated as a failed transaction.

Possible values:

successboolean · enumRequired

Payment success flag returned by the gateway. Must be true; any other value is treated as a failed transaction.

Possible values:

gpinstallmentstringRequired

Instalment count selected by the customer on the Garanti Pay hosted form (e.g. "1" for a single payment, "3" for three instalments). The value is resolved against the active instalment records for the pre-order's card. If no matching active instalment is found the resolved instalment on the pre-order is set to null.

Example: 3

Responses

200

GPay callback processed. On success the order is finalised and the flow advances to ThankYouPage. On failure a full rollback is performed and a validation error is returned so the customer may retry from the payment selection step.

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

302

Redirect to basket (empty basket) or login (guest purchase not allowed)

post

/orders/checkout/?page=GPayCompletePage

HTTPcURLJavaScriptPython

Successful GPay callback with instalment selectionSuccessful GPay callback — single payment (no instalment)

Get Confirmation Payment Agreement Check Page context

get

Determines whether the selected confirmation payment method requires a pre-payment agreement. This page is part of the confirmation payment (e.g., mobile payment, QR payment) flow and is reached immediately after a confirmation payment option is selected.

Preconditions:

• Basket must not be empty

• A confirmation payment option must be selected (check_confirmation_payment_selected)

• Payment must be enabled (is_payment_enabled)

Skip Conditions:

• Page is skipped if agreement_required is already set (either true or false) in the pre-order data

Page Context: (empty)

Next Pages:

• ConfirmationPaymentAgreementConfirmPage — if the gateway requires an agreement

• ConfirmationPaymentSelectedPage — if no agreement is required

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Agreement check page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=ConfirmationPaymentAgreementCheckPage

HTTPcURLJavaScriptPython

200

Agreement check page context retrieved

Check whether a pre-payment agreement is required

post

Calls the payment gateway's agreement check. Based on the response, the pre-order is updated with agreement_required, payment_enabled, and optionally agreement_id and is_agreement_expired.

Required Fields: (none — submitting with an empty body is sufficient)

State Updates:

• If no agreement required: agreement_required = false, payment_enabled = true

• If agreement required:

  • agreement_required = true

  • payment_enabled: set from gateway response

  • agreement_id: set from gateway response (if present)

  • is_agreement_expired: set from gateway response (if present)

Backward Navigation:

• When navigating backward, agreement_required, agreement_id, is_agreement_expired, and payment_enabled are removed from pre_order.data.

Next Pages:

• ConfirmationPaymentAgreementConfirmPage — if agreement is required

• ConfirmationPaymentSelectedPage — if no agreement is required

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

objectOptional

Responses

200

Agreement check completed

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=ConfirmationPaymentAgreementCheckPage

HTTPcURLJavaScriptPython

200

Agreement check completed

Get Confirmation Payment Agreement Confirm Page context

get

Returns the terms and conditions data that the user must accept before the payment gateway can be enabled. This page is only shown when the preceding ConfirmationPaymentAgreementCheckPage determined that an agreement is required.

The terms_and_conditions field in the page context is a free-form dict (DictField) — its structure is entirely determined by the payment gateway and varies per integration. For example, the Paycell gateway returns termsOfServiceHtmlContentTR and termsOfServiceHtmlContentEN keys containing the full HTML content of the agreement alongside a responseHeader and eulaId.

Preconditions:

• Basket must not be empty

• A confirmation payment option must be selected (check_confirmation_payment_selected)

• Payment must be enabled (is_payment_enabled)

• Agreement must be required (is_agreement_required)

Skip Conditions:

• Page is skipped if agreement_signed = true is already set in the pre-order data

Next Pages:

• ConfirmationPaymentSelectedPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Agreement Confirm Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=ConfirmationPaymentAgreementConfirmPage

HTTPcURLJavaScriptPython

200

Agreement Confirm Page context retrieved

Accept the pre-payment agreement and enable the payment gateway

post

Submits the user's agreement acceptance and calls the payment gateway's enable_payment method. On success, the payment gateway is enabled and the flow advances to ConfirmationPaymentSelectedPage.

Required Fields:

• agreement: Must be true. Submitting false returns a validation error.

State Updates:

• On success: agreement_signed = true, agreement_required = false, agreement_id and is_agreement_expired are cleared from pre_order.data.

• On gateway failure: agreement_signed = false

Backward Navigation:

• When navigating backward, agreement_signed is removed from pre_order.data.

Next Pages:

• ConfirmationPaymentSelectedPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

agreementbooleanRequired

Must be true to accept the pre-payment terms and conditions and trigger the gateway's enable_payment call. Submitting false returns a validation error.

Example: true

Responses

200

Agreement accepted or error

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=ConfirmationPaymentAgreementConfirmPage

HTTPcURLJavaScriptPython

200

Agreement accepted or error

Get Confirmation Payment Selected Page context

get

Entry point for the confirmation payment initiation step. On this page, the user accepts the payment agreement and submits to trigger the payment gateway's start_payment call. The gateway returns a token that is used in the subsequent polling step.

Preconditions:

• Basket must not be empty

• A confirmation payment option must be selected (check_confirmation_payment_selected)

• No agreement must be required (is_agreement_not_required)

Skip Conditions:

• Page is skipped if all of the following are true:

  • A confirmation payment option is selected

  • Order number is assigned

  • user_confirmation_waiting = true in pre-order data

  • token is set in pre-order data

Page Context: (empty)

Previous Pages:

• ConfirmationPaymentAgreementCheckPage — if no agreement was required

• ConfirmationPaymentAgreementConfirmPage — if agreement was required and accepted

Next Pages:

• ConfirmationPaymentQueryPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Confirmation Payment Selected Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=ConfirmationPaymentSelectedPage

HTTPcURLJavaScriptPython

200

Confirmation Payment Selected Page context retrieved

Initiate confirmation payment and obtain a gateway token

post

Submits the standard checkout order agreement and calls the payment gateway's start_payment method. On success, the gateway returns a token which is stored in pre_order.data['token'] and the flow advances to the query (polling) step.

Required Fields:

• agreement: Must be true. This is the standard checkout order agreement (same field used across all payment methods via OrderAgreementInputSerializer), not the gateway-specific pre-payment agreement accepted in the preceding ConfirmationPaymentAgreementConfirmPage. Submitting false returns a validation error. The user must also be a registered (non-anonymous) user with a valid phone number.

Gateway Variants:

• For Apple Pay (checkout_apple_pay gateway): additional Apple Pay payment data fields may be submitted.

• For all other gateways: only agreement is required.

State Updates:

• token: set from gateway response

• user_confirmation_waiting = true

• context_data: set if gateway response includes a context field

• Previous token, user_confirmation_waiting, user_confirmed values are cleared before the new payment is initiated

Backward Navigation:

• When navigating backward, user_confirmation_waiting and token are cleared, and the order number is reset.

Next Pages:

• ConfirmationPaymentQueryPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

agreementbooleanRequired

Must be true to accept the standard checkout order agreement (OrderAgreementInputSerializer) and initiate the confirmation payment via the gateway's start_payment call. This is distinct from the gateway-specific pre-payment agreement accepted in ConfirmationPaymentAgreementConfirmPage. The user must also be a registered (non-anonymous) user with a valid phone number. Submitting false returns a validation error.

Example: true

Responses

200

Payment initiated or error

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=ConfirmationPaymentSelectedPage

HTTPcURLJavaScriptPython

200

Payment initiated or error

Get Confirmation Payment Query Page context

get

Returns the context for the confirmation payment query step. Depending on the gateway, the frontend either polls this page repeatedly (TomPay — waiting for in-app approval) or renders a form for user input (Paycell — OTP entry, PosAs Gift Card — card number and PIN). The page context may include gateway-specific data (e.g., Apple Pay context).

Preconditions:

• Basket must not be empty

• A confirmation payment option must be selected (check_confirmation_payment_selected)

• Payment must be in a user-confirmation-waiting state (is_user_confirmation_waiting): user_confirmation_waiting = true and token are both set in pre-order data

• Order number must be assigned (has_order_number)

Skip Conditions:

• Page is skipped if user_confirmed = true and token are both set in pre-order data

Page Context:

• For most gateways: empty

• For Apple Pay: includes context_data (JSON object from gateway)

Next Pages:

• ConfirmationPaymentCompletePage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Confirmation Payment Query Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=ConfirmationPaymentQueryPage

HTTPcURLJavaScriptPython

200

Confirmation Payment Query Page context retrieved

Submit payment confirmation

post

Calls the payment gateway's query_payment method. The behavior and required input differ significantly by gateway:

• TomPay: No input required. start_payment sent a push notification to the user's TomPay mobile app. The frontend submits this endpoint repeatedly (with an empty body) until the user approves in the app. While waiting, the gateway returns result.code = 3039 which maps to error_code: not_confirmed_yet.

• Paycell: Requires otp. start_payment sent an OTP SMS to the user's phone. The user enters the OTP and submits once — this is a single submission, not repeated polling.

• PosAs Gift Card: Requires customer_card_no and password. The user enters their gift card number and PIN and submits once.

• Apple Pay / default: No input required.

Response error codes:

• not_confirmed_yet: Gateway is still waiting for the user to confirm (applicable to TomPay). Frontend should retry.

• generic_error: An unrecoverable error occurred. Token and order number are cleared; the user must restart from ConfirmationPaymentSelectedPage.

State Updates (on success):

• user_confirmed = true

• For PosAs Gift Card: customer_card_no, customer_id, and code are also stored.

• token may be updated if the gateway returns a new token.

Backward Navigation:

• When navigating backward, user_confirmed, customer_card_no, customer_id, and code are removed from pre_order.data.

Next Pages:

• ConfirmationPaymentCompletePage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

Gateway-dependent input for the confirmation payment polling step. Most gateways (TomPay, Apple Pay, default) require no fields — submit an empty body for those. Gateway-specific fields are listed below.

otpstring · min: 4 · max: 4Optional

Paycell only. 4-digit one-time password sent to the user's registered phone number. Required when the active gateway is paycell.

Example: 1234

customer_card_nostring · max: 16Optional

PosAs Gift Card only. The gift card number. Required when the active gateway is posas_giftcard.

Example: 1234567890123456

passwordstringOptional

PosAs Gift Card only. 4-digit PIN for the gift card. Required when the active gateway is posas_giftcard. Must consist of exactly 4 digits.

Example: 1234Pattern: ^\d{4}$

Responses

200

Payment query result

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=ConfirmationPaymentQueryPage

HTTPcURLJavaScriptPython

Default / TomPay / Apple Pay (no input required)Paycell — submit OTP received by SMSPosAs Gift Card — submit card number and PIN

200

Payment query result

Get Confirmation Payment Complete Page context

get

Finalizes the confirmation payment and completes the order. This page is reached after the user has confirmed the payment on their device. The page processes the finalization logic inherited from PaymentPageMixin and advances to ThankYouPage on success.

Preconditions:

• Basket must not be empty

• A confirmation payment option must be selected (check_confirmation_payment_selected)

• Order number must be assigned (has_order_number)

• User must have confirmed the payment (is_payment_confirmed_by_user): user_confirmed = true and token are both set in pre-order data

Skip Conditions:

• Page is skipped if the order is already finalized

Page Context: (empty)

Next Pages:

• ThankYouPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Confirmation Payment Complete Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=ConfirmationPaymentCompletePage

HTTPcURLJavaScriptPython

200

Confirmation Payment Complete Page context retrieved

Finalize the confirmation payment and complete the order

post

Submits the finalization of the confirmation payment. No input data is required. The page processes the order finalization via PaymentPageMixin and advances to the ThankYouPage.

Required Fields: (none — submitting with an empty body is sufficient)

State Updates:

• Order is finalized; the pre-order is converted to a completed order.

• Note: set_defaults is overridden with set_number=False to preserve the already-assigned order number.

Next Pages:

• ThankYouPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

objectOptional

Responses

200

Order finalized

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=ConfirmationPaymentCompletePage

HTTPcURLJavaScriptPython

200

Order finalized

Get Remote Price Calculation Page context

get

This page appears in the checkout flow when basket items have prices that must be fetched from a remote service. It sits between the address selection step and the shipping option selection step. The page has no visible context of its own; its purpose is to trigger the remote price lookup on POST.

Preconditions:

• Basket must not be empty

• A shipping address must be selected (check_address_selected)

has_remote_price flag:

• Set by AddressSelectionPage during its process_pre_order step, after the shipping address is saved.

• Checks whether any basket item has a product attribute matching REMOTE_PRICE_ATTRIBUTE_KEY (default: "has_remote_price") with value "true".

• If true, AddressSelectionPage.next_page() routes directly to this page instead of ShippingOptionSelectionPage.

Valid Condition (is_valid):

• Returns true only if has_remote_price = true is set in pre_order.data.

Skip Conditions:

• Page is skipped if are_remote_prices_set = true is already set in pre_order.data.

Page Context: (empty)

Previous Page: AddressSelectionPage

Next Pages:

• ShippingOptionSelectionPage (or the configured shipping option selection variant)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Remote Price Calculation Page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=RemotePriceCalculationPage

HTTPcURLJavaScriptPython

200

Remote Price Calculation Page context retrieved

Trigger remote price calculation for basket items

post

Calls BasketItemRemotePriceService.set_remote_prices() to fetch and apply remote prices for basket items that require external price resolution. No input data is required.

Required Fields: (none — submitting with an empty body is sufficient)

State Updates:

• pre_order.data['are_remote_prices_set'] = true

Backward Navigation:

• When navigating backward, both has_remote_price and are_remote_prices_set are removed from pre_order.data.

Next Pages:

• ShippingOptionSelectionPage (or the configured shipping option selection variant)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

objectOptional

Responses

200

Remote prices set

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=RemotePriceCalculationPage

HTTPcURLJavaScriptPython

200

Remote prices set

Get Masterpass BIN Number Page context

get

Returns the context for the Masterpass BIN number entry step. Card details are collected on the client side via the Masterpass JS SDK; only the BIN and a flag indicating whether the card is a stored Masterpass card are submitted so the server can identify the card type and determine the available installment options.

Preconditions:

• Basket must not be empty

• Payment option must be of Masterpass type

Page Context:

• Returns an empty object {}. No additional data is exposed at GET time — the card data flow runs through the Masterpass JS SDK.

Step Completion: This page is considered already completed when both of the following are true:

• Card information has been recorded, and

• The selected payment option is of Masterpass type.

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Masterpass BIN number page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=MasterpassBinNumberPage

HTTPcURLJavaScriptPython

200

Masterpass BIN number page context retrieved

Submit Card BIN Number for Masterpass

post

Submits the card BIN number captured by the Masterpass JS SDK. The BIN is used to identify the card type (bank, card type, available installment records). If the BIN cannot be matched in the database, the system falls back to the default card configuration.

Required Fields:

• bin_number: First 6 or 8 digits of the card. Must contain only digits.

Optional Fields:

• is_masterpass_stored_card: Indicates whether the card is from the user's stored Masterpass cards. Defaults to false.

Validation:

• bin_number must be a 6 or 8 digit numeric string. A non-matching value returns "Please enter a valid bin number.".

• When the active payment option has provisioning enabled and the resolved card is a debit card, the submission is rejected with "You can only use credit cards.".

State Update:

• Card information is stored, containing the submitted BIN and the resolved card record.

• The stored card flag and the detected card brand (Mastercard or not) are saved to the session.

Backward Navigation:

• On backward navigation, the stored card flag and the card brand indicator are removed from the session.

Next Page:

• MasterpassInstallmentPage

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

bin_numberstringRequired

First 6 or 8 digits of the card (BIN — Bank Identification Number). Captured by the Masterpass JS SDK on the client side. Must contain only digits and have a length of 6 or 8.

Example: 542119Pattern: ^\d{6,8}$

is_masterpass_stored_cardbooleanOptional

Indicates whether the card BIN comes from the user's stored Masterpass cards. Saved to the session so later steps can distinguish stored-card and fresh-card flows.

Default: falseExample: false

Responses

200

BIN submitted successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=MasterpassBinNumberPage

HTTPcURLJavaScriptPython

6-digit BIN, fresh card entry8-digit BIN, stored Masterpass card

200

BIN submitted successfully

Get Masterpass Complete Page context

get

Returns the context required to drive the final Masterpass payment request from the client. The context contains the MSISDN, the order number, the 3D Secure routing flag, signed request tokens for the Masterpass JS SDK, and a set of gateway-specific extras.

Preconditions:

• Basket must not be empty

• Payment option must be of Masterpass type

• Card information must be present

• An installment must be selected

• Order number must have been generated

• The 3D Secure routing decision must have been made

Page Context:

• msisdn: The user's phone number in E.164 format (e.g. "905551234567"). null for guest checkouts or when the user has no phone number on file.

• order_no: The previously assigned order number. For payment gateways with a custom merchant type this value may differ from the raw pre_order.number.

• three_d: true when a 3D Secure challenge is required for this transaction, false otherwise.

• token: A signed request token for the Masterpass JS SDK, generated with the user's identity (user ID and MSISDN) when the customer is logged in. When provisioning is enabled for the payment option, the provision flag is included.

• direct_token: A variant of the above token where the MSISDN is set to null, used for direct and guest purchase flows.

• extras: Gateway-specific data (installment, amounts, addresses, user information) forwarded to the Masterpass JS SDK.

Step Completion:

• This page is considered already completed when the order has been finalised.

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Masterpass complete page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=MasterpassCompletePage

HTTPcURLJavaScriptPython

200

Masterpass complete page context retrieved

Finalise Masterpass Order

post

Finalises the Masterpass order. All query string parameters from the request URL are merged into the submitted form data, and the amount form key is removed before validation. This is the mechanism used to consume 3D Secure return parameters appended as query string by the gateway.

Required Fields:

• token: The Masterpass payment token received from the gateway.

• three_d_secure: Boolean indicating whether the transaction went through 3D Secure. Defaults to false.

Optional / 3D Secure Callback Fields:

• oid, md, xid, eci, cavv, rnd, hash, hashParams, hashParamsVal, mdStatus, bankIca, paymentReceived, clientId, sign: 3D Secure callback parameters returned by the bank.

• amount: Decimal value from the bank callback. When present, it is validated against the order total. A mismatch returns "Transaction failed. Please try again.". Note: any amount form field is removed before query string parameters are merged.

3D Secure Validation:

• When three_d_secure is true:

  • The hash is validated against the gateway. A failure returns "Hash values doesn't match.".

  • The MD status is validated. A failure returns "Transaction failed. Please try again.".

Processing:

1. Query string parameters from the bank callback are merged into the request body (form amount is removed first).

2. Order defaults are applied without regenerating the order number, as it was already assigned in MasterpassOrderNoPage.

3. When pre_order.redirect_to_three_d is false, no separate transaction record is created at this step. Otherwise a transaction is created with id "MASTERPASS_<order_number>_<suffix>".

4. The payment is processed and the order is finalised.

Backward Navigation:

• This page does not perform any backward state changes.

Next Page:

• ThankYouPage

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

Final Masterpass submission payload. The endpoint also merges any request query string parameters into the form data (with the form amount key removed before merging) so that 3D Secure callback parameters appended by the bank are captured automatically.

tokenstringRequired

Masterpass payment token received from the gateway.

Example: mp-token-abc123

three_d_securebooleanRequired

Indicates whether the transaction went through 3D Secure. When true, the hash and MD status are validated. Defaults to false.

Default: falseExample: false

oidstringOptional

Order ID echoed back by the bank on 3D callback.

Example: ORD-2026-0042

mdstringOptional

3D Secure md parameter from the bank callback.

xidstringOptional

3D Secure xid parameter from the bank callback.

ecistringOptional

3D Secure ECI value from the bank callback.

Example: 05

cavvstringOptional

3D Secure CAVV value from the bank callback.

rndstringOptional

3D Secure random nonce from the bank callback.

hashstringOptional

Bank-issued response hash. Validated via the gateway when three_d_secure is true.

hashParamsstringOptional

3D Secure hash params list from the bank callback.

hashParamsValstringOptional

3D Secure hash params values from the bank callback.

mdStatusstringOptional

3D Secure MD status. Validated via the gateway when three_d_secure is true. A failure returns "Transaction failed. Please try again.".

Example: 1

bankIcastringOptional

Bank ACQ ICA value passed back by the gateway.

paymentReceivedstringOptional

Payment received indicator returned by the gateway.

amountstring · decimalOptional

Total amount from the bank callback. When present, it is validated against the order total. A mismatch returns "Transaction failed. Please try again.". Note: any amount form field is removed before query string parameters are merged into the body, so the value used is the one supplied by the bank callback when present.

Example: 16559

clientIdstringOptional

Merchant client ID echoed back by the gateway.

signstringOptional

Signature value from the bank callback.

Responses

200

Masterpass order finalised successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=MasterpassCompletePage

HTTPcURLJavaScriptPython

Non-3D flow3D Secure callback parameters

200

Masterpass order finalised successfully

Get Masterpass Installment Selection Page context

get

Returns the available installment options for the Masterpass flow. Installments are derived from the card identified in the previous step and filtered by the active installment filter rules.

Preconditions:

• Basket must not be empty

• Card information must have been entered (MasterpassBinNumberPage must have been completed)

• Payment option must be of Masterpass type

Page Context:

• installments: List of available installment options for the resolved card. Each entry contains pk, installment_count, label, price_with_accrued_interest, and monthly_price_with_accrued_interest calculated against the current unpaid basket amount.

• card_type: Card type details (name, slug, logo), derived from the resolved card's card type.

• installment_messages: List of informational strings returned by the installment filter service (e.g. filter messages or promotion notices).

Step Completion: This page is considered already completed when both of the following are true:

• An installment has been selected, and

• The selected payment option is of Masterpass type.

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Masterpass installment selection page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=MasterpassInstallmentPage

HTTPcURLJavaScriptPython

200

Masterpass installment selection page context retrieved

Select Installment Option for Masterpass

post

Sets the selected installment option for the Masterpass flow.

Required Fields:

• installment: Primary key of the installment record to apply. The value must reference an active installment linked to the card resolved in MasterpassBinNumberPage.

Validation:

• The submitted installment PK must belong to an active installment for the resolved card. A PK outside this set returns a validation error.

State Update:

• The selected installment is stored on the pre-order.

• Any previously selected campaign and reward selections are cleared.

Backward Navigation:

• On backward navigation, the selected installment is cleared.

Next Page:

• MasterpassOrderNoPage

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

installmentintegerRequired

Primary key (pk) of the Installment record to select. The PK must reference an active installment linked to the card resolved in MasterpassBinNumberPage.

Example: 2

Responses

200

Installment selected successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=MasterpassInstallmentPage

HTTPcURLJavaScriptPython

Select single paymentSelect 3 installments

200

Installment selected successfully

Get Masterpass Order Number Page context

get

Returns the context for the Masterpass order number assignment page. This page assigns the order number that will be used for the subsequent Masterpass payment request and evaluates whether the transaction must be completed via 3D Secure.

Preconditions:

• Basket must not be empty

• Payment option must be of Masterpass type

• Card information must be present

• An installment must be selected

Page Context:

• Returns an empty object {}.

Step Completion: This page is considered already completed when both of the following are true:

• The order number has been assigned, and

• The 3D Secure routing decision has been made (either true or false).

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Masterpass order number page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=MasterpassOrderNoPage

HTTPcURLJavaScriptPython

200

Masterpass order number page context retrieved

Assign Order Number and Decide 3D Secure Routing

post

Assigns the order number that will be sent to Masterpass and evaluates whether the transaction must be processed under 3D Secure.

Fields:

• No fields are required. Submit an empty form body to trigger order number assignment.

Processing:

1. The client IP is captured and stored for the order.

2. The order number is generated.

3. The 3D Secure decision is evaluated using the gateway's POS configuration, the user, the basket total, the resolved card, and the BIN number. The result is stored so that MasterpassCompletePage can route the transaction correctly.

Backward Navigation:

• On backward navigation: the client IP is cleared, the order number is reset, and the 3D Secure routing flag is cleared.

Next Page:

• MasterpassCompletePage

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

objectOptional

No input fields are required for this step. Submit an empty form body to trigger order number assignment and 3D Secure routing evaluation.

Responses

200

Order number assigned successfully

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

post

/orders/checkout/?page=MasterpassOrderNoPage

HTTPcURLJavaScriptPython

200

Order number assigned successfully

Get Masterpass Remote Installment Selection Page context

get

Returns the available installment options for the Masterpass REST flow when a remote installment service is configured for the active POS. Installments are fetched from the external installment service using the card BIN and the current basket amount, then filtered by the active installment filter rules.

Preconditions:

• Basket must not be empty

• Payment option must be of Masterpass REST type

Page Context:

• installments: List of installment options returned by the remote installment service. Each entry contains id, label, bin_number, installment_count, interest_rate, interest_amount, final_price_with_interest, monthly_price_with_interest, and is_active.

• installment_messages: List of informational strings returned by the installment filter service.

Step Completion: This page is considered already completed when both of the following are true:

• The remote installment selection has been saved, and

• The selected payment option is of Masterpass REST type.

available_for_post_order: true

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Masterpass remote installment selection page context retrieved

application/json

errorsone ofOptional

or

nullOptional

or

string[]Optional

template_namestringOptional

get

/orders/checkout/?page=MasterpassRemoteInstallmentPage

HTTP