Akinon Release Notes 06/22/2026) are now live! Click here to learn what's new.
Ctrlk
Docs Portal
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Alternative Payment Methods

Checkout Alternative Payment Methods

Integrate Bex (BKM Express), Garanti Pay (GPay), Cash Register, and Confirmation Payment into your checkout. Each method follows a distinct step sequence—use the one that matches your storefront configuration.

Bex is a bank consortium payment method. The flow covers BIN lookup, nonce generation, installment selection, and payment completion.

Garanti Pay (GPay) redirects customers to an external page for QR-code or link-based payment and returns them upon completion.

Cash Register is a point-of-sale method for store staff. It supports installment selection and in-store payment completion.

Confirmation Payment lets the customer place an order first and confirm payment later through a separate channel. The flow includes agreement review and a confirmation step.

Authentication

These endpoints support both authenticated and anonymous sessions.

  • Authenticated users: Session cookie (sessionid) tracks checkout progress.

  • Anonymous users: Guest checkout is available when the CAN_GUEST_PURCHASE setting is enabled.

Request Format

Include the following header in all checkout requests:

  • x-requested-with: XMLHttpRequest

Dynamic Settings

The following settings are managed at runtime through the admin interface and do not require a server restart.

CASH_REGISTER_AUTH_CONF

Authentication credentials for the cash register payment service. Includes the service username and password.

INSTALLMENT_FILTERS

Filters applied during Bex and Cash Register installment selection to restrict the available options.

Static Settings

The following settings are configured in the server environment and require a restart to take effect.

DEFAULT_CARD_SLUG

Fallback card identifier used when a Bex BIN number lookup returns no match. Defaults to other.

GPAY_BIN_NUMBER

The identifier used to look up the virtual card for Garanti Pay transactions. Must match a record in the database. Defaults to GPAY00.

CASH_REGISTER_DEFAULTS

Fallback store staff information (staff ID, email address, and store ID) used when the corresponding request headers are absent.

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 of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=BexSelectionPage
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
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 of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=BexSelectionPage
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 of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=BexBinNumberPage
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
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 of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=BexBinNumberPage
200

BIN number submitted 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 of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=BexNoncePage
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
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 of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=BexNoncePage
200

Nonce received and stored 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 of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=BexInstallmentSelectionPage
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
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 of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=BexInstallmentSelectionPage
200

Installment selected 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 of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=BexCompletePage
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
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 of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=BexCompletePage
200

BKM Express order finalised successfully

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 of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=GPaySelectionPage

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
object · GPaySelectionPageInputOptional

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 of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=GPaySelectionPage

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 of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=GPayRedirectPage
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
object · GPayRedirectPageInputOptional

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 of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=GPayRedirectPage
200

Redirect transaction initiated — flow advancing to GPayCompletePage

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 of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=GPayCompletePage

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

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 of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=GPayCompletePage

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 of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=CashRegisterPage

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
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 of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=CashRegisterPage

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 of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=CashRegisterInstallmentSelectionPage

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
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 of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=CashRegisterInstallmentSelectionPage

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 of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=CashRegisterCompletePage

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
object · CashRegisterCompleteInputOptional

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 of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=CashRegisterCompletePage

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 of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=ConfirmationPaymentQueryPage
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

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 of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=ConfirmationPaymentQueryPage
200

Payment query result

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 of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=ConfirmationPaymentSelectedPage
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
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 of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=ConfirmationPaymentSelectedPage
200

Payment initiated or error

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 of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=ConfirmationPaymentAgreementCheckPage
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
objectOptional
Responses
200

Agreement check completed

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=ConfirmationPaymentAgreementCheckPage
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 of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=ConfirmationPaymentAgreementConfirmPage
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
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 of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=ConfirmationPaymentAgreementConfirmPage
200

Agreement accepted or error

PreviousCard PaymentNextMasterpass Payment

Last updated

Was this helpful?